# g-simmons/mcp-github-projects architecture

> Architecture diagram of the GitHub repository g-simmons/mcp-github-projects, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/g-simmons/mcp-github-projects
- Repository: https://github.com/g-simmons/mcp-github-projects

## Overview

##### Project type and purpose
- This is a backend CLI application (“MCP server”) written in TypeScript/Node (using Bun) that exposes GitHub Projects v2, Issues, and Repositories operations over the Model Context Protocol (MCP) to AI agents or other clients.
- Its purpose is to accept MCP-style JSON requests (from tools like Smithery or Claude Desktop), execute the corresponding GitHub GraphQL API calls, and return structured responses.

##### File structure
- Top-level files:
- Dockerfile, bun.lock, package.json, tsconfig.json – project configuration and build
- smithery.yaml – MCP server metadata/commands definitions
- build.ts, codegen.ts – build and code-generation scripts
- src/:
- src/index.ts – MCP server entry point and request router
- src/common/ – shared error and utility functions
- src/graphql/ – .graphql query definitions organized by domain (issues, projects, repositories) and loader (graphql-loader.ts)
- src/operations/ – high-level operation handlers that invoke the GitHub client (issues.ts, projects.ts, repositories.ts, github-client.ts)
- src/types/ – generated TypeScript types for GraphQL schemas and GitHub API
- src/utils/ – helpers to load GraphQL documents

##### README for additional insights
- “Features” showing which GitHub API domains are covered
- Describes environment variables (GITHUB_TOKEN, GITHUB_OWNER) used for authenticating with GitHub’s GraphQL endpoint
- Provides CLI usage pattern: “bun build/index.js” plus env, which wires up to Smithery’s MCP client

a. Main components
- MCP Server Process (Node/Bun)
- MCP Request Router (index.ts)
- Operation Modules (issues, projects, repositories)
- GraphQL Loader (graphql-loader.ts + .graphql files)
- GitHub GraphQL Client (github-client.ts)
- External GitHub GraphQL API Endpoint
- MCP Client (e.g., Smithery or Claude Desktop)
- Build & Codegen Tools (build.ts, codegen.ts)
- Environment Configuration (.env / .env.example)
b. Relationships and interactions
- MCP Client → (stdin/stdout or socket) → MCP Server Process
- MCP Server uses Router → dispatches to Operation Module
- Operation Module → invokes GraphQL Client with query loaded by GraphQL Loader → sends HTTP request to GitHub API
- GitHub API responds → GraphQL Client returns data → Operation Module formats response → Router returns JSON to MCP Client
- Build/Codegen Tools read schema.docs.graphql + .graphql files → generate src/types GraphQL type definitions
c. Architectural patterns and design principles
- Modular separation: loader, client, operations, router
- Single responsibility: each module has one domain (issues/projects/repos)
- Code generation for type safety: GraphQL codegen script produces strongly typed operations
- Environmental configuration: credentials are injected via env vars
d. Key technologies and libraries
- Bun (runtime & build)
- TypeScript, tsconfig
- GraphQL (query files + codegen)
- Smithery MCP protocol (smithery.yaml)
- GitHub GraphQL API
- dotenv / .env files

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Services"
        direction TB
        MCPClient["MCP Client"]:::external
        GitHubAPI["GitHub GraphQL API"]:::external
    end

    %% Runtime Server
    subgraph "Runtime Components"
        direction TB
        Server["MCP Server (Bun)"]:::runtime
        Router["Router (index.ts)"]:::runtime
        subgraph "Operation Modules"
            direction TB
            IssuesOp["Issues Operations"]:::runtime
            ProjectsOp["Projects Operations"]:::runtime
            ReposOp["Repositories Operations"]:::runtime
        end
        Client["GitHub GraphQL Client"]:::runtime
        Loader["GraphQL Loader"]:::utility
        subgraph "Common Utilities"
            direction TB
            Utils["Utility Functions"]:::utility
            Errors["Error Handling"]:::utility
        end
        Types["Generated Types"]:::types
    end

    %% Build and Codegen
    subgraph "Offline Build/Codegen" 
        direction TB
        Build["build.ts"]:::codegen
        Codegen["codegen.ts"]:::codegen
        SchemaDocs["schema.docs.graphql"]:::codegen
    end

    %% Configuration
    Env[".env.example"]:::config
    Smithery["smithery.yaml"]:::config
    ConfigFiles["Dockerfile\npackage.json\ntsconfig.json\nbun.lock"]:::config

    %% Data Flow
    MCPClient -->|"MCP Request"| Server
    Server --> Router
    Router --> IssuesOp
    Router --> ProjectsOp
    Router --> ReposOp
    IssuesOp --> Loader
    ProjectsOp --> Loader
    ReposOp --> Loader
    Loader --> Client
    Client -->|"HTTP Request"| GitHubAPI
    GitHubAPI -->|"Response"| Client
    Client --> IssuesOp
    Client --> ProjectsOp
    Client --> ReposOp
    IssuesOp --> Router
    ProjectsOp --> Router
    ReposOp --> Router
    Router --> MCPClient

    %% Build/Dataflow to types
    SchemaDocs --> Codegen
    Build --> Codegen
    Codegen --> Types

    %% Configuration links
    Env -.-> Client
    Smithery -.-> Server
    ConfigFiles -.-> Server

    %% Click Events
    click Router "https://github.com/g-simmons/mcp-github-projects/blob/main/src/index.ts"
    click IssuesOp "https://github.com/g-simmons/mcp-github-projects/blob/main/src/operations/issues.ts"
    click ProjectsOp "https://github.com/g-simmons/mcp-github-projects/blob/main/src/operations/projects.ts"
    click ReposOp "https://github.com/g-simmons/mcp-github-projects/blob/main/src/operations/repositories.ts"
    click Client "https://github.com/g-simmons/mcp-github-projects/blob/main/src/operations/github-client.ts"
    click Loader "https://github.com/g-simmons/mcp-github-projects/blob/main/src/utils/graphql-loader.ts"
    click Utils "https://github.com/g-simmons/mcp-github-projects/blob/main/src/common/utils.ts"
    click Errors "https://github.com/g-simmons/mcp-github-projects/blob/main/src/common/errors.ts"
    click Types "https://github.com/g-simmons/mcp-github-projects/blob/main/src/types/graphql.d.ts"
    click Types "https://github.com/g-simmons/mcp-github-projects/blob/main/src/types/github-api-types.ts"
    click Build "https://github.com/g-simmons/mcp-github-projects/blob/main/build.ts"
    click Codegen "https://github.com/g-simmons/mcp-github-projects/blob/main/codegen.ts"
    click Smithery "https://github.com/g-simmons/mcp-github-projects/blob/main/smithery.yaml"
    click Env "https://github.com/g-simmons/mcp-github-projects/blob/main/.env.example"

    %% Styles
    classDef external fill:#ffebcc,stroke:#f39c12,color:#000;
    classDef runtime fill:#e0f7fa,stroke:#00acc1,color:#000;
    classDef utility fill:#f1f8e9,stroke:#7cb342,color:#000;
    classDef types fill:#ede7f6,stroke:#5e35b1,color:#000;
    classDef codegen fill:#fff3e0,stroke:#fb8c00,color:#000;
    classDef config fill:#f5f5f5,stroke:#9e9e9e,color:#000;
```
