Documentation MCP Server

A Model Context Protocol (MCP) server that provides GitHub PR/issue data along with a documentation guide for LLM-based documentation generation.

Overview

This MCP server is a data provider that:

Fetches GitHub PR and issue data server-side
Loads a static documentation template
Returns formatted context to the client LLM
Lets the client LLM generate the actual documentation
Runs as an HTTP service - can be deployed locally or remotely

Architecture Flow:

User → Client LLM → HTTP → MCP Server
                              ↓
                       Fetches GitHub data
                              ↓
                       Returns guide + context
                              ↓
              Client LLM generates documentation
                              ↓
                      User receives documentation

The server does NOT contain its own LLM - it aggregates data for the client's LLM to process.

Features

HTTP Transport: Uses StreamableHTTP for MCP communication
Stateless: Supports multiple concurrent clients without session conflicts
Remote Deployment: Run on a different machine from your MCP client
Single Tool: writeDocumentation - aggregates GitHub data with documentation guide
Server-Side Fetching: Automatically retrieves PR details, linked issues, and diffs
Static Template: Uses a fixed documentation guide loaded at startup
No LLM Calls: Returns raw context for the client LLM to process
Health Check: Built-in /health endpoint for monitoring

Quick Start

1. Install and Build

npm install
npm run build

2. Set GitHub Token

export GITHUB_TOKEN="ghp_your_github_token_here"

Get your token at: https://github.com/settings/tokens

3. Start the Server

npm start

You should see:

Documentation MCP Server running on http://0.0.0.0:3000
MCP endpoint: http://0.0.0.0:3000/mcp
Health check: http://0.0.0.0:3000/health
Mode: HTTP (stateless, multiple clients supported)

Configuration

Environment Variables

Variable	Description	Default	Required
`GITHUB_TOKEN`	GitHub Personal Access Token	-	Yes
`PORT`	HTTP server port	`3000`	No
`HOST`	HTTP server host	`0.0.0.0`	No

Examples

# Custom port
PORT=8080 npm start

# Specific interface
HOST=127.0.0.1 npm start

# Both
PORT=8080 HOST=127.0.0.1 GITHUB_TOKEN=your_token npm start

Usage

Health Check

Test if the server is running:

curl http://localhost:3000/health
# Response: {"status":"ok","service":"documentation-mcp-server"}

MCP Client Configuration

Configure your MCP client to connect to the server:

{
  "mcpServers": {
    "documentation": {
      "url": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}

For remote servers:

{
  "mcpServers": {
    "documentation": {
      "url": "https://your-server.com/mcp",
      "transport": "http"
    }
  }
}

Tool: writeDocumentation

Input Parameters:

prUrl (string, optional): GitHub pull request URL
issueUrl (string, optional): GitHub issue URL
notes (string, optional): Additional context or notes

At least one of prUrl or issueUrl is required.

Example Usage:

User: "Write documentation for https://github.com/owner/repo/pull/123"

Client LLM: [Calls writeDocumentation tool via HTTP]

MCP Server: [Fetches GitHub data, returns guide + context]

Client LLM: [Generates documentation following the guide]

User: [Receives completed documentation]

Output:

Returns a formatted prompt containing:

The documentation guide (structure, rules, required sections)
GitHub PR/issue data (title, description, files, diffs)
Any additional notes provided
Instructions for the client LLM to generate documentation

Deployment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
ENV PORT=3000
ENV HOST=0.0.0.0
CMD ["npm", "start"]

Build and run:

docker build -t documentation-mcp-server .
docker run -d -p 3000:3000 \
  -e GITHUB_TOKEN=your_token \
  --name mcp-server \
  documentation-mcp-server

Docker Compose

version: '3.8'

services:
  mcp-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - PORT=3000
      - HOST=0.0.0.0
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Process Manager (PM2)

npm install -g pm2
pm2 start dist/index.js --name mcp-server
pm2 save
pm2 startup

Cloud Platforms

Deploy to Railway, Render, Fly.io, or any platform supporting Node.js:

Push your code to GitHub
Connect repository to platform
Set GITHUB_TOKEN environment variable
Platform will auto-deploy

Testing

Test with curl

# Initialize
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0.0"}
    }
  }'

# List tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Architecture

src/
├── index.ts           # MCP server with HTTP transport
└── github-client.ts   # GitHub API integration

documentation-guide.md # Static documentation template

How It Works

Server Starts: Loads documentation guide, starts HTTP server
Client Connects: MCP client connects to /mcp endpoint
Tool Invocation: Client calls writeDocumentation with GitHub URLs
Data Fetching: Server fetches PR/issue data from GitHub API
Context Building: Server combines guide + GitHub data into formatted prompt
Response: Server returns complete context via HTTP
Generation: Client LLM generates documentation following the guide

Transport Details

Protocol: StreamableHTTP (MCP specification)
MCP Endpoint: GET/POST /mcp - Main MCP communication
Health Endpoint: GET /health - Status check
CORS: Enabled for all origins (configure for production)
Session Mode: Stateless (supports multiple concurrent clients)

Security

For production deployment:

Configure CORS: Restrict allowed origins
Use HTTPS: Deploy behind reverse proxy (nginx, Caddy)
Rate Limiting: Add rate limiting middleware
Authentication: Add auth tokens if needed
GitHub Token: Keep secure, use environment variables
Network: Use firewall rules to restrict access

Troubleshooting

See TROUBLESHOOTING.md for detailed solutions.

Common issues:

"Server already initialized": Fixed in latest version (stateless mode)
Connection refused: Server not running or wrong port
CORS errors: Configure CORS for your client origin
GitHub rate limits: Use a GitHub token

Requirements

Node.js 18+
TypeScript 5+
GitHub token (optional, but recommended)

License

MIT

Documentation-mcp-server