GitHub MCP Control Plane

A production-ready, enterprise-grade GitHub MCP (Model Context Protocol) server deployed on Cloudflare Workers with zero-idle cost, comprehensive security validation, and full audit trails.

Overview

This MCP server provides secure, controlled access to GitHub operations through the Model Context Protocol. It implements a stateless request/response model with enterprise-grade security features including:

• Multi-layer Security: Secret detection, vulnerability scanning, RBAC, and policy enforcement
• Full Audit Trail: Every action logged with correlation IDs for complete traceability
• Rate Limiting: Distributed rate limiting using Cloudflare KV
• Batch Operations: Handle 100+ files in a single commit
• Delegation: Heavy tasks delegated to GitHub Actions for optimal performance
• Idempotent Operations: Built-in retry logic with exponential backoff

Architecture

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ MCP Request
       ▼
┌─────────────────────────────────────┐
│  Cloudflare Worker (Stateless)     │
│  ┌───────────────────────────────┐  │
│  │  Entry Point & Routing       │  │
│  └──────────────┬────────────────┘  │
│                 ▼                    │
│  ┌───────────────────────────────┐  │
│  │  Authentication & Authorization│ │
│  └──────────────┬────────────────┘  │
│                 ▼                    │
│  ┌───────────────────────────────┐  │
│  │  Validation Pipeline           │  │
│  │  • Schema Validation           │  │
│  │  • Security Scanning           │  │
│  │  • Policy Enforcement          │  │
│  │  • Dependency Checking         │  │
│  └──────────────┬────────────────┘  │
│                 ▼                    │
│  ┌───────────────────────────────┐  │
│  │  Tool Execution               │  │
│  │  • Read-Only Tools            │  │
│  │  • Write-Controlled Tools     │  │
│  │  • Workflow Tools              │  │
│  └──────────────┬────────────────┘  │
│                 ▼                    │
│  ┌───────────────────────────────┐  │
│  │  Audit Logging & Response     │  │
│  └──────────────┬────────────────┘  │
└─────────────────┼────────────────────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
┌───────────────┐   ┌──────────────┐
│ GitHub API    │   │ GitHub       │
│               │   │ Actions      │
└───────────────┘   └──────────────┘

Quick Start

Prerequisites

• Node.js 18+
• Wrangler CLI
• GitHub Personal Access Token with appropriate permissions
• Cloudflare account with Workers and KV enabled

Installation

# Install dependencies
npm install

# Configure Wrangler
wrangler login

# Set required secrets
wrangler secret put GITHUB_TOKEN
wrangler secret put GITHUB_WEBHOOK_SECRET
wrangler secret put JWT_SECRET
wrangler secret put ENCRYPTION_KEY

# Validate configuration
npm run validate-config

# Deploy to production
npm run deploy

Local Development

# Start local development server
npm run dev

# The worker will be available at http://localhost:8787

Configuration

Environment Variables

See .env.example for all available configuration options.

Tool Manifest

Configure available tools in src/config/tools-manifest.json:

{
  "tools": [
    {
      "name": "list_repositories",
      "category": "read-only",
      "description": "List repositories accessible to the authenticated user",
      "requiredPermissions": ["read:org", "repo"]
    }
  ]
}

Policy Rules

Define authorization policies in src/config/policy-rules.json:

{
  "policies": [
    {
      "name": "write-restrictions",
      "tools": ["create_branch", "create_commit"],
      "conditions": {
        "repository": {
          "allowedPatterns": ["*"],
          "blockedPatterns": ["protected-*"]
        },
        "branch": {
          "blockedPatterns": ["main", "master", "production"]
        }
      }
    }
  ]
}

Security Features

1. Authentication

• JWT token validation
• GitHub permission verification
• Token expiration handling

2. Authorization

• RBAC with fine-grained permissions
• Repository-level access control
• Branch protection rules

3. Validation

• JSON schema validation for all requests
• Secret detection (regex + entropy analysis)
• Dependency vulnerability checking via OSV.dev
• Code policy enforcement

4. Rate Limiting

• Distributed rate limiting with Cloudflare KV
• Configurable windows and thresholds
• Per-client rate tracking

5. Audit Trail

• Every action logged with correlation ID
• Structured JSON logging
• Configurable retention period

Available Tools

Read-Only Tools

• list_repositories - List accessible repositories
• fetch_file - Fetch file contents from a repository
• list_files - List files in a directory
• get_repository_info - Get repository metadata

Write-Controlled Tools

• create_branch - Create a new branch
• create_commit - Create commits with file changes
• batch_create_commits - Handle 100+ files in batch operations

Workflow Tools

• trigger_workflow - Trigger GitHub Actions workflows
• get_workflow_status - Check workflow execution status
• get_workflow_logs - Fetch workflow execution logs

API Reference

See docs/API.md for detailed API documentation.

Deployment

Production Deployment

# Deploy to production
npm run deploy

# Deploy to staging
wrangler deploy --env staging

GitHub Actions Integration

For long-running tasks, the worker delegates to GitHub Actions. Configure:

1. Add workflow file to your repository (.github/workflows/execution-handler.yml)
2. Set GITHUB_WEBHOOK_SECRET in your repository settings
3. Configure the worker URL in workflow dispatch

See docs/DEPLOYMENT.md for complete deployment guide.

Monitoring

Health Check

curl https://your-worker-url.workers.dev/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0"
}

Logs

All logs are emitted in structured JSON format:

{
  "level": "info",
  "message": "Request received",
  "correlationId": "abc-123",
  "tool": "list_repositories",
  "userId": "user-123",
  "timestamp": "2024-01-01T00:00:00Z"
}

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test file
npx vitest tests/unit/auth.test.js

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": [
      {
        "field": "repository",
        "message": "Repository name is required"
      }
    ],
    "correlationId": "abc-123"
  }
}

Security Considerations

1. Never commit secrets - Use Wrangler secrets for all sensitive data
2. Use principle of least privilege - GitHub tokens should have minimal required permissions
3. Enable audit logging - Track all operations for compliance
4. Regular secret rotation - Rotate JWT and encryption keys regularly
5. Monitor rate limits - Set appropriate thresholds to prevent abuse

Troubleshooting

Common Issues

Worker returns 401 Unauthorized

• Check GITHUB_TOKEN is set correctly
• Verify token has required permissions
• Check token hasn't expired

Rate limit errors

• Review rate limiting configuration
• Check KV namespace is properly configured
• Monitor usage patterns

Validation failures

• Review validation logs for specific errors
• Check schema definitions in tools-manifest.json
• Verify secret patterns in secret-patterns.json

Contributing

Contributions are welcome! Please ensure:

1. All tests pass
2. Code follows existing patterns and style
3. New features include tests
4. Documentation is updated

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• GitHub Issues: [repository-url]/issues
• Documentation: docs/