Which integrations are available for this server?

Deployed as a stateless MCP server on [Cloudflare Workers](/mcp/servers/integrations/cloudflare-workers) with zero-idle cost, distributed rate limiting using Cloudflare KV, and enterprise-grade security features. Provides secure, controlled access to [GitHub](/mcp/servers/integrations/github) operations including repository management, file operations, branch creation, and commit handling with multi-layer security validation and audit trails. Enables triggering [GitHub Actions](/mcp/servers/integrations/github-actions) workflows, checking workflow execution status, and fetching workflow logs, with delegation of heavy tasks to GitHub Actions for optimal performance.

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:

Add workflow file to your repository (.github/workflows/execution-handler.yml)
Set GITHUB_WEBHOOK_SECRET in 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/