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 repositoriesfetch_file- Fetch file contents from a repositorylist_files- List files in a directoryget_repository_info- Get repository metadata
Write-Controlled Tools
create_branch- Create a new branchcreate_commit- Create commits with file changesbatch_create_commits- Handle 100+ files in batch operations
Workflow Tools
trigger_workflow- Trigger GitHub Actions workflowsget_workflow_status- Check workflow execution statusget_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:
- Add workflow file to your repository (
.github/workflows/execution-handler.yml) - Set
GITHUB_WEBHOOK_SECRETin your repository settings - 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
- Never commit secrets - Use Wrangler secrets for all sensitive data
- Use principle of least privilege - GitHub tokens should have minimal required permissions
- Enable audit logging - Track all operations for compliance
- Regular secret rotation - Rotate JWT and encryption keys regularly
- 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:
- All tests pass
- Code follows existing patterns and style
- New features include tests
- Documentation is updated
License
MIT License - see LICENSE file for details
Support
For issues and questions:
- GitHub Issues: [repository-url]/issues
- Documentation: docs/