GitHub MCP Server Architecture

This document outlines the architecture for a Model Context Protocol (MCP) server that integrates with GitHub to provide comprehensive functionality for web-based projects in Cursor.

Overview

The GitHub MCP server follows a clean architecture approach with distinct layers:

1. Domain Layer: Core entities and business logic
2. Infrastructure Layer: GitHub API integration
3. Service Layer: Business logic coordination
4. MCP Layer: Tool definitions and request handling

The server supports both stdio and SSE transport options for flexibility.

System Components

github-mcp-server/
├── src/
│   ├── domain/                 # Domain entities and interfaces
│   │   ├── entities/           # Core domain entities
│   │   └── repositories/       # Repository interfaces
│   ├── infrastructure/         # External integrations
│   │   ├── github/             # GitHub API integration
│   │   └── transport/          # Transport implementations
│   ├── services/               # Business logic services
│   ├── mcp/                    # MCP protocol implementation
│   │   ├── tools/              # Tool definitions
│   │   └── handlers/           # Request handlers
│   ├── utils/                  # Utility functions
│   ├── env.ts                  # Environment configuration
│   └── index.ts                # Entry point
├── tests/                      # Test suite
├── .env.example                # Example environment variables
├── package.json                # Dependencies and scripts
└── tsconfig.json               # TypeScript configuration

Key Components

1. Domain Layer

The domain layer contains the core business entities and repository interfaces:

• Repository Entity: Represents a GitHub repository
• File Entity: Represents a file in a repository
• Project Entity: Represents a GitHub project
• Issue Entity: Represents a GitHub issue
• Repository Interfaces: Define operations for repository access

2. Infrastructure Layer

The infrastructure layer handles external integrations:

• GitHub API Client: Implements repository interfaces using Octokit
• Transport Implementations:
  • StdioTransport: For local development
  • SSETransport: For networked access

3. Service Layer

The service layer coordinates business logic:

• Repository Service: Manages repository operations
• File Service: Manages file operations
• Project Service: Manages project operations
• Issue Service: Manages issue operations

4. MCP Layer

The MCP layer defines tools and handles MCP protocol requests:

• Tool Definitions:
  • github_repository_info: Get repository information
  • github_directory_structure: Get repository directory structure
  • github_read_file: Read file content
  • github_list_branches: List repository branches
  • github_list_issues: List repository issues
  • github_create_issue: Create a new issue
  • github_update_issue: Update an existing issue
  • github_list_projects: List GitHub projects
  • github_project_details: Get project details
  • github_create_project: Create a new project
  • github_update_project: Update an existing project
• Request Handlers: Process MCP protocol requests and route to appropriate services

Transport Options

The server supports two transport options:

1. stdio Transport

• Simpler implementation
• Local development only
• Direct communication via standard input/output

2. SSE Transport

• More flexible implementation
• Can be accessed remotely
• HTTP-based communication with Server-Sent Events

Authentication

The server requires GitHub authentication:

• GitHub Personal Access Token (PAT) with permissions:
  • repo (Full repository access)
  • project (Project access)
  • write:org (Organization access)
• Environment variables:
  • GITHUB_TOKEN: GitHub Personal Access Token
  • GITHUB_OWNER: Default repository owner (optional)
  • GITHUB_REPO: Default repository name (optional)

Error Handling

The server implements comprehensive error handling:

• GitHub API errors are mapped to appropriate MCP error responses
• Rate limiting is handled with exponential backoff
• Authentication errors are properly reported
• Network errors are handled gracefully

Performance Considerations

• Caching of frequently accessed data
• Batch operations where possible
• Pagination for large result sets
• Optimistic concurrency for updates