# 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

```bash
npm install
npm run build
```

### 2. Set GitHub Token

```bash
export GITHUB_TOKEN="ghp_your_github_token_here"
```

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

### 3. Start the Server

```bash
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

```bash
# 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:

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

### MCP Client Configuration

Configure your MCP client to connect to the server:

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

**For remote servers:**

```json
{
  "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:

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

## Deployment

### Docker

```dockerfile
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:

```bash
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

```yaml
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)

```bash
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:

1. Push your code to GitHub
2. Connect repository to platform
3. Set `GITHUB_TOKEN` environment variable
4. Platform will auto-deploy

## Testing

### Test with curl

```bash
# 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

1. **Server Starts**: Loads documentation guide, starts HTTP server
2. **Client Connects**: MCP client connects to `/mcp` endpoint
3. **Tool Invocation**: Client calls `writeDocumentation` with GitHub URLs
4. **Data Fetching**: Server fetches PR/issue data from GitHub API
5. **Context Building**: Server combines guide + GitHub data into formatted prompt
6. **Response**: Server returns complete context via HTTP
7. **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:

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

## Troubleshooting

See [TROUBLESHOOTING.md](./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