grist-mcp-server/docs/plans/2025-12-29-docker-deployment.md

Docker Deployment Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Make grist-mcp deployable via Docker Compose with automated CI builds on version tag pushes.

Architecture: Replace stdio transport with SSE (HTTP-based) for remote operation. Multi-stage Dockerfile for small images. Single adaptive CI workflow that detects Gitea vs GitHub and pushes to the appropriate registry.

Tech Stack: Python 3.14, Starlette (ASGI), Uvicorn, Docker, GitHub Actions (compatible with Gitea Actions)

---

Task 1: Add SSE Transport Dependencies

Files:

• Modify: pyproject.toml

Step 1: Add dependencies to pyproject.toml

Edit pyproject.toml to add the SSE transport dependencies:

dependencies = [
    "mcp>=1.0.0",
    "httpx>=0.27.0",
    "pyyaml>=6.0",
    "starlette>=0.41.0",
    "uvicorn>=0.32.0",
    "sse-starlette>=2.1.0",
]

Step 2: Sync dependencies

Run: uv sync Expected: Dependencies install successfully

Step 3: Commit

git add pyproject.toml uv.lock
git commit -m "feat: add SSE transport dependencies"

---

Task 2: Implement SSE Transport in main.py

Files:

• Modify: src/grist_mcp/main.py

Step 1: Replace main.py with SSE implementation

Replace the entire contents of src/grist_mcp/main.py with:

"""Main entry point for the MCP server with SSE transport."""

import os
import sys

import uvicorn
from mcp.server.sse import SseServerTransport
from starlette.applications import Starlette
from starlette.routing import Route

from grist_mcp.server import create_server
from grist_mcp.auth import AuthError


def create_app() -> Starlette:
    """Create the Starlette ASGI application."""
    config_path = os.environ.get("CONFIG_PATH", "/app/config.yaml")

    if not os.path.exists(config_path):
        print(f"Error: Config file not found at {config_path}", file=sys.stderr)
        sys.exit(1)

    try:
        server = create_server(config_path)
    except AuthError as e:
        print(f"Authentication error: {e}", file=sys.stderr)
        sys.exit(1)

    sse = SseServerTransport("/messages")

    async def handle_sse(request):
        async with sse.connect_sse(
            request.scope, request.receive, request._send
        ) as streams:
            await server.run(
                streams[0], streams[1], server.create_initialization_options()
            )

    async def handle_messages(request):
        await sse.handle_post_message(request.scope, request.receive, request._send)

    return Starlette(
        routes=[
            Route("/sse", endpoint=handle_sse),
            Route("/messages", endpoint=handle_messages, methods=["POST"]),
        ]
    )


def main():
    """Run the SSE server."""
    port = int(os.environ.get("PORT", "3000"))
    app = create_app()
    print(f"Starting grist-mcp SSE server on port {port}")
    print(f"  SSE endpoint: http://0.0.0.0:{port}/sse")
    print(f"  Messages endpoint: http://0.0.0.0:{port}/messages")
    uvicorn.run(app, host="0.0.0.0", port=port)


if __name__ == "__main__":
    main()

Step 2: Test that the server starts

Run: CONFIG_PATH=./config.yaml.example GRIST_MCP_TOKEN=test uv run python -m grist_mcp.main & Expected: Server starts, prints port info (will fail auth but that's OK for this test) Kill: pkill -f "python -m grist_mcp.main"

Step 3: Commit

git add src/grist_mcp/main.py
git commit -m "feat: replace stdio with SSE transport"

---

Task 3: Create Dockerfile

Files:

• Create: Dockerfile

Step 1: Create multi-stage Dockerfile

Create Dockerfile with:

# Stage 1: Builder
FROM python:3.14-slim AS builder

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies
RUN uv sync --frozen --no-dev --no-install-project

# Copy source code
COPY src ./src

# Install the project
RUN uv sync --frozen --no-dev


# Stage 2: Runtime
FROM python:3.14-slim

# Create non-root user
RUN useradd --create-home --shell /bin/bash appuser

WORKDIR /app

# Copy virtual environment from builder
COPY --from=builder /app/.venv /app/.venv

# Copy source code
COPY --from=builder /app/src ./src

# Set environment
ENV PATH="/app/.venv/bin:$PATH"
ENV PORT=3000

# Switch to non-root user
USER appuser

EXPOSE 3000

CMD ["python", "-m", "grist_mcp.main"]

Step 2: Verify Dockerfile syntax

Run: docker build --check . (if available) or just proceed to next step

Step 3: Commit

git add Dockerfile
git commit -m "feat: add multi-stage Dockerfile"

---

Task 4: Create docker-compose.yaml

Files:

• Create: docker-compose.yaml

Step 1: Create docker-compose.yaml

Create docker-compose.yaml with:

services:
  grist-mcp:
    build: .
    ports:
      - "${PORT:-3000}:3000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file:
      - .env
    restart: unless-stopped

Step 2: Commit

git add docker-compose.yaml
git commit -m "feat: add docker-compose.yaml"

---

Task 5: Create .env.example

Files:

• Create: .env.example

Step 1: Create .env.example

Create .env.example with:

# grist-mcp environment configuration

# Server port (default: 3000)
PORT=3000

# Agent authentication token (required)
# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
GRIST_MCP_TOKEN=your-agent-token-here

# Grist API keys (referenced in config.yaml)
GRIST_WORK_API_KEY=your-work-api-key
GRIST_PERSONAL_API_KEY=your-personal-api-key

# Optional: Override config path (default: /app/config.yaml)
# CONFIG_PATH=/app/config.yaml

Step 2: Commit

git add .env.example
git commit -m "feat: add .env.example template"

---

Task 6: Create CI Workflow

Files:

• Create: .github/workflows/build.yaml

Step 1: Create workflow directory

Run: mkdir -p .github/workflows

Step 2: Create adaptive CI workflow

Create .github/workflows/build.yaml with:

name: Build and Push Docker Image

on:
  push:
    tags:
      - 'v*.*.*'

env:
  IMAGE_NAME: grist-mcp

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Determine registry
        id: registry
        run: |
          if [ "${{ vars.GITEA_ACTIONS }}" = "true" ]; then
            # Gitea: use server URL as registry
            REGISTRY="${{ github.server_url }}"
            REGISTRY="${REGISTRY#https://}"
            REGISTRY="${REGISTRY#http://}"
            echo "registry=${REGISTRY}" >> $GITHUB_OUTPUT
            echo "is_gitea=true" >> $GITHUB_OUTPUT
          else
            # GitHub: use GHCR
            echo "registry=ghcr.io" >> $GITHUB_OUTPUT
            echo "is_gitea=false" >> $GITHUB_OUTPUT
          fi

      - name: Log in to GitHub Container Registry
        if: steps.registry.outputs.is_gitea == 'false'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Log in to Gitea Container Registry
        if: steps.registry.outputs.is_gitea == 'true'
        uses: docker/login-action@v3
        with:
          registry: ${{ steps.registry.outputs.registry }}
          username: ${{ github.actor }}
          password: ${{ secrets.REGISTRY_TOKEN }}

      - name: Extract metadata (tags, labels)
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ steps.registry.outputs.registry }}/${{ github.repository }}
          tags: |
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=semver,pattern={{major}}
            type=raw,value=latest

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Step 3: Commit

git add .github/workflows/build.yaml
git commit -m "feat: add CI workflow for Docker builds"

---

Task 7: Update README with Docker Instructions

Files:

• Modify: README.md

Step 1: Read current README

Read README.md to understand current structure.

Step 2: Add Docker section after existing content

Add a "Docker Deployment" section with:

• Quick start with docker-compose
• Environment variable reference
• Configuration instructions

Step 3: Commit

git add README.md
git commit -m "docs: add Docker deployment instructions"

---

Task 8: Test Docker Build Locally

Files:

• None (verification only)

Step 1: Build the Docker image

Run: docker build -t grist-mcp:test . Expected: Build completes successfully

Step 2: Create test config and .env

Run:

cp config.yaml.example config.yaml
cp .env.example .env

Edit .env to set a test token matching one in config.yaml.

Step 3: Test with docker-compose

Run: docker compose up -d Expected: Container starts

Step 4: Verify server is running

Run: curl -I http://localhost:3000/sse Expected: HTTP response (connection may hang waiting for SSE, that's OK)

Step 5: Clean up

Run: docker compose down

Step 6: Final commit if any fixes needed

If any fixes were required, commit them.

---

Post-Implementation

After all tasks complete:

1. Tag a version: git tag v0.2.0 && git push --tags
2. Configure Gitea secret: Add REGISTRY_TOKEN in Gitea repo settings
3. Verify CI: Check that workflow runs and pushes images