feat: add Docker support with HTTP/SSE transport (#50)

* feat: add Docker support with HTTP/SSE transport

Add Docker container that exposes the MCP server over HTTP using mcp-proxy.
Supports both streamable HTTP (/mcp) and SSE (/sse) transports.
Publishes to GHCR on release.

* fix: run container as non-root user for security

Add mcpuser non-root user following security best practices.

Author: dwmkerr

.github/workflows/cicd.yaml

@@ -238,3 +238,45 @@ jobs:
         run: |
           npm set //npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}
           npm publish --registry https://npm.pkg.github.com
+
+  release-mcp-docker:
+    name: Release MCP Server Docker Image
+    needs: [release]
+    if: ${{ needs.release.outputs.released }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      packages: write
+    defaults:
+      run:
+        working-directory: ./mcp/ai-developer-guide-mcp
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${{ needs.release.outputs.tag }}
+          echo "version=${VERSION#v}" >> $GITHUB_OUTPUT
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./mcp/ai-developer-guide-mcp
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/ai-developer-guide-mcp:${{ steps.version.outputs.version }}
+            ghcr.io/${{ github.repository_owner }}/ai-developer-guide-mcp:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

mcp/ai-developer-guide-mcp/Dockerfile

@@ -0,0 +1,45 @@
+FROM node:24-slim AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install all dependencies (including dev for build)
+RUN npm ci
+
+# Copy source and build
+COPY . .
+RUN npm run build
+
+# Production image
+FROM node:24-slim
+
+# Create non-root user
+RUN groupadd -r mcpuser && useradd -r -g mcpuser mcpuser
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install only production dependencies
+RUN npm ci --omit=dev
+
+# Copy built application from builder
+COPY --from=builder /app/dist ./dist
+
+# Install mcp-proxy globally for HTTP/SSE transport
+RUN npm install -g mcp-proxy
+
+# Change ownership to non-root user
+RUN chown -R mcpuser:mcpuser /app
+
+# Switch to non-root user
+USER mcpuser
+
+# Expose HTTP port
+EXPOSE 8080
+
+# Use mcp-proxy to expose over HTTP (both /mcp streamable and /sse endpoints)
+ENTRYPOINT ["mcp-proxy", "--port", "8080", "--host", "0.0.0.0", "--shell", "node dist/cli.js"]

mcp/ai-developer-guide-mcp/README.md

@@ -28,6 +28,7 @@ A simple MCP server that connects your LLM to the developer guide:
 - [Example LLM Interactions](#example-llm-interactions)
 - [Configuration](#configuration)
 - [API Requirements](#api-requirements)
+- [Running in Docker](#running-in-docker)
 
 <!-- vim-markdown-toc -->
 
@@ -224,3 +225,28 @@ You can configure your MCP server using these parameters:
 ## API Requirements
 
 The API structure should match the [AI Developer Guide API format](https://dwmkerr.github.io/ai-developer-guide/api.json).
+
+## Running in Docker
+
+You can run the MCP server in Docker to expose it over HTTP:
+
+```bash
+# Pull and run from GitHub Container Registry.
+docker run -p 8080:8080 ghcr.io/dwmkerr/ai-developer-guide-mcp:latest
+
+# Or build locally.
+docker build -t ai-developer-guide-mcp ./ai-developer-guide-mcp
+docker run -p 8080:8080 ai-developer-guide-mcp
+
+# Test with MCP inspector (streamable HTTP or SSE endpoints).
+npx @modelcontextprotocol/inspector http://localhost:8080/mcp # recommended
+npx @modelcontextprotocol/inspector http://localhost:8080/sse # deprecated
+```
+
+Optionally configure a custom guide URL:
+
+```bash
+docker run -p 8080:8080 \
+  -e AI_DEVELOPER_GUIDE_URL=https://your-domain.com/your-guide \
+  ghcr.io/dwmkerr/ai-developer-guide-mcp:latest
+```