# loidodev/github-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/loidodev/github-mcp-server
- Repository: https://github.com/loidodev/github-mcp-server

## Overview

##### Project type and purpose
- This is a standalone backend microservice (“GitHub MCP Server”) built in Node.js/TypeScript.
- It implements the Model Context Protocol to expose “tools” that wrap GitHub API operations (list_user_repos, get_repo, create_repo, create_commit, push, pull).

##### File structure
- Top-level:
- package.json / tsconfig.json / build scripts
- src/ (all TypeScript source code)
- src/index.ts
- Application entrypoint (loads env, starts server)
- src/server.ts
- HTTP server setup, route or RPC dispatch
- src/tools/handlers.ts
- Implements each MCP “tool” by calling GitHub API
- src/tools/schemas.ts
- JSON schemas for validating tool parameters
- src/types.ts
- Shared TypeScript types (requests, responses, GitHub models)
- src/utils.ts
- HTTP client wrapper, auth, error handling

##### README
- Confirms it’s a service requiring GITHUB_TOKEN, exposes endpoints via MCP Inspector or npm start.
- No internal database—interacts directly with GitHub’s REST API.
- Provides a list of tools and parameters.

## Diagram (Mermaid)

```mermaid
graph TB
    Client["Client / MCP Inspector"]:::client

    subgraph "MCP Server"
        Index["Entrypoint (index.ts)"]:::internal
        Server["API Layer (server.ts)"]:::internal
        Validators["Validation Module (schemas.ts)"]:::internal
        Handlers["Handler Module (handlers.ts)"]:::internal
        Utils["Utility Layer (utils.ts)"]:::internal
        Types["Shared Types (types.ts)"]:::internal
        Env["Environment (GITHUB_TOKEN)"]:::env
    end

    GitHub["GitHub REST API"]:::external

    Client -->|"Request"| Server
    Server -->|"Validate payload"| Validators
    Validators -->|"Validated data"| Server
    Server -->|"Dispatch to handler"| Handlers
    Handlers -->|"Use shared types"| Types
    Handlers -->|"Call utils"| Utils
    Utils -->|"Authenticated HTTP call"| GitHub
    GitHub -->|"API response"| Utils
    Utils -->|"Return data"| Handlers
    Handlers -->|"Format response"| Server
    Server -->|"Response"| Client

    PackageJSON["Project config (package.json)"]:::config
    TSConfig["TypeScript config (tsconfig.json)"]:::config

    subgraph "Legend"
        L1["Blue = Internal modules"]:::internal
        L2["Green = External services"]:::external
        L3["Grey = Clients"]:::client
        L4["Orange = Env/Config"]:::env
    end

    click Index "https://github.com/loidodev/github-mcp-server/blob/main/src/index.ts"
    click Server "https://github.com/loidodev/github-mcp-server/blob/main/src/server.ts"
    click Handlers "https://github.com/loidodev/github-mcp-server/blob/main/src/tools/handlers.ts"
    click Validators "https://github.com/loidodev/github-mcp-server/blob/main/src/tools/schemas.ts"
    click Utils "https://github.com/loidodev/github-mcp-server/blob/main/src/utils.ts"
    click Types "https://github.com/loidodev/github-mcp-server/blob/main/src/types.ts"
    click PackageJSON "https://github.com/loidodev/github-mcp-server/blob/main/package.json"
    click TSConfig "https://github.com/loidodev/github-mcp-server/blob/main/tsconfig.json"

    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef client fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef env fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#FFA500,stroke:#333,stroke-width:1px
```
