# 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
```bash
# 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
```bash
# 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`:
```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`:
```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](docs/API.md) for detailed API documentation.
## Deployment
### Production Deployment
```bash
# 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](docs/DEPLOYMENT.md) for complete deployment guide.
## Monitoring
### Health Check
```bash
curl https://your-worker-url.workers.dev/health
```
Expected response:
```json
{
"status": "healthy",
"timestamp": "2024-01-01T00:00:00Z",
"version": "1.0.0"
}
```
### Logs
All logs are emitted in structured JSON format:
```json
{
"level": "info",
"message": "Request received",
"correlationId": "abc-123",
"tool": "list_repositories",
"userId": "user-123",
"timestamp": "2024-01-01T00:00:00Z"
}
```
## Testing
```bash
# 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:
```json
{
"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/](docs/)
