Architecture - fleXRPL/github-mcp GitHub Wiki

Architecture

This document outlines the architecture of the GitHub MCP Server, including system components, data flow, and integration points.

System Overview

graph TB
    subgraph Client
        Cursor[Cursor IDE]
        AI[AI Assistant]
    end

    subgraph GitHub MCP Server
        API[FastAPI Server]
        Auth[Authentication]
        Tools[Tool Registry]
        SSE[SSE Handler]
    end

    subgraph GitHub
        GH_API[GitHub API]
        GH_Auth[GitHub Auth]
    end

    Cursor -->|MCP Protocol| API
    AI -->|Tool Calls| API
    API -->|Validate| Auth
    Auth -->|Token| GH_Auth
    API -->|Register| Tools
    Tools -->|API Calls| GH_API
    API -->|Stream| SSE
    SSE -->|Events| Cursor

    style Client fill:#f9f,stroke:#333,stroke-width:2px
    style GitHub fill:#24292e,stroke:#333,stroke-width:2px,color:#fff
    style GitHub_MCP_Server fill:#0366d6,stroke:#333,stroke-width:2px,color:#fff

Component Architecture

classDiagram
    class FastAPI {
        +app: FastAPI
        +register_tool()
        +handle_tool_call()
        +stream_events()
    }

    class ToolRegistry {
        +tools: Dict
        +register_tool()
        +get_tool()
        +list_tools()
    }

    class GitHubClient {
        +client: Github
        +authenticate()
        +get_repositories()
        +get_issues()
        +get_pull_requests()
    }

    class ToolHandler {
        +handle_repository_tools()
        +handle_issue_tools()
        +handle_pr_tools()
        +handle_content_tools()
    }

    class SSEHandler {
        +stream: EventSourceResponse
        +send_event()
        +keep_alive()
    }

    FastAPI --> ToolRegistry
    FastAPI --> GitHubClient
    FastAPI --> ToolHandler
    FastAPI --> SSEHandler
    ToolHandler --> GitHubClient

Authentication Flow

sequenceDiagram
    participant Client
    participant Server
    participant Keychain
    participant GitHub

    Client->>Server: Start Server
    Server->>Keychain: Request GitHub Token
    Keychain-->>Server: Return Token
    Server->>GitHub: Validate Token
    GitHub-->>Server: Token Valid
    Server-->>Client: Server Ready

    Client->>Server: Tool Call
    Server->>GitHub: API Request
    GitHub-->>Server: API Response
    Server-->>Client: Tool Result

Tool Execution Flow

sequenceDiagram
    participant Client
    participant Server
    participant ToolRegistry
    participant ToolHandler
    participant GitHub

    Client->>Server: Tool Call Request
    Server->>ToolRegistry: Validate Tool
    ToolRegistry-->>Server: Tool Definition
    Server->>ToolHandler: Execute Tool
    ToolHandler->>GitHub: API Request
    GitHub-->>ToolHandler: API Response
    ToolHandler-->>Server: Process Response
    Server-->>Client: Tool Result

Data Flow

graph LR
    subgraph Input
        ToolCall[Tool Call]
        Parameters[Parameters]
    end

    subgraph Processing
        Validation[Validation]
        Execution[Execution]
        Response[Response]
    end

    subgraph Output
        Result[Tool Result]
        Events[SSE Events]
    end

    ToolCall --> Validation
    Parameters --> Validation
    Validation --> Execution
    Execution --> Response
    Response --> Result
    Response --> Events

    style Input fill:#f9f,stroke:#333,stroke-width:2px
    style Processing fill:#bbf,stroke:#333,stroke-width:2px
    style Output fill:#bfb,stroke:#333,stroke-width:2px

Security Architecture

graph TB
    subgraph Security
        Auth[Authentication]
        Token[Token Management]
        RateLimit[Rate Limiting]
        Validation[Input Validation]
    end

    subgraph Storage
        Keychain[System Keychain]
        Cache[Response Cache]
    end

    subgraph Access
        API[API Access]
        Tools[Tool Access]
        SSE[SSE Access]
    end

    Auth --> Token
    Token --> Keychain
    API --> Auth
    Tools --> Auth
    SSE --> Auth
    API --> RateLimit
    API --> Validation
    Tools --> Validation
    API --> Cache

    style Security fill:#f96,stroke:#333,stroke-width:2px
    style Storage fill:#9f6,stroke:#333,stroke-width:2px
    style Access fill:#69f,stroke:#333,stroke-width:2px

Deployment Architecture

graph TB
    subgraph Production
        LoadBalancer[Load Balancer]
        Server1[Server Instance 1]
        Server2[Server Instance 2]
        Cache[Redis Cache]
        Monitor[Monitoring]
    end

    subgraph GitHub
        API[GitHub API]
        Webhooks[Webhooks]
    end

    Client --> LoadBalancer
    LoadBalancer --> Server1
    LoadBalancer --> Server2
    Server1 --> Cache
    Server2 --> Cache
    Server1 --> API
    Server2 --> API
    API --> Webhooks
    Webhooks --> Server1
    Webhooks --> Server2
    Server1 --> Monitor
    Server2 --> Monitor

    style Production fill:#f96,stroke:#333,stroke-width:2px
    style GitHub fill:#24292e,stroke:#333,stroke-width:2px,color:#fff

Key Components

  1. FastAPI Server

    • Handles HTTP requests
    • Manages tool registration
    • Processes tool calls
    • Streams SSE events

  2. Tool Registry

    • Maintains tool definitions
    • Validates tool calls
    • Routes to appropriate handlers

  3. GitHub Client

    • Manages GitHub API interactions
    • Handles authentication
    • Implements rate limiting

  4. SSE Handler

    • Manages server-sent events
    • Maintains client connections
    • Streams tool results

  5. Authentication

    • Uses system keychain
    • Manages GitHub tokens
    • Validates permissions

Design Decisions

  1. FastAPI Framework

    • Modern, high-performance
    • Built-in async support
    • Automatic OpenAPI documentation
    • Easy SSE implementation

  2. System Keychain Integration

    • Secure token storage
    • Cross-platform support
    • Integration with Git credentials

  3. Tool-based Architecture

    • Modular design
    • Easy to extend
    • Clear separation of concerns
    • Standardized interface

  4. SSE for Real-time Updates

    • Efficient server-client communication
    • Low latency
    • Reduced overhead
    • Better user experience

Scalability Considerations

  1. Horizontal Scaling

    • Stateless design
    • Load balancer support
    • Shared caching
    • Distributed monitoring

  2. Performance Optimization

    • Response caching
    • Rate limiting
    • Connection pooling
    • Async operations

  3. High Availability

    • Multiple server instances
    • Health monitoring
    • Automatic failover
    • Backup systems

Monitoring and Logging

graph LR
    subgraph Monitoring
        Metrics[Performance Metrics]
        Logs[Application Logs]
        Alerts[Alert System]
    end

    subgraph Tools
        Prometheus[Prometheus]
        Grafana[Grafana]
        ELK[ELK Stack]
    end

    Metrics --> Prometheus
    Prometheus --> Grafana
    Logs --> ELK
    Metrics --> Alerts
    Logs --> Alerts

    style Monitoring fill:#f96,stroke:#333,stroke-width:2px
    style Tools fill:#69f,stroke:#333,stroke-width:2px

Future Considerations

  1. Planned Improvements

    • Webhook support
    • Advanced caching
    • Custom tool definitions
    • Plugin system

  2. Potential Enhancements

    • GraphQL API
    • WebSocket support
    • OAuth integration
    • Enterprise features

Related Documentation