# ddukbg/github-enterprise-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/ddukbg/github-enterprise-mcp
- Repository: https://github.com/ddukbg/github-enterprise-mcp

## Overview

Based on your project’s file structure and README, this is a Node.js/TypeScript backend server that implements a Model Context Protocol (MCP) interface. Its main purpose is to provide an abstraction layer to access and manage GitHub Enterprise (and GitHub.com/Enterprise Cloud) data—such as repositories, issues, pull requests, GitHub Actions workflows, and even enterprise statistics. It is deployed either as a standalone HTTP service or linked as a global CLI command to be easily integrated with tools like Cursor and Claude Desktop.

##### Relationships and Interactions
- Additionally, note that error handling, debug logging, and response formatting are part of the internal processing. This may be drawn as annotations on the API modules or server components.

##### Architectural Patterns and Design Principles
- Modularization: The file tree clearly separates functional concerns (actions, admin, etc.). Emphasize that each module is responsible for a distinct GitHub tool, following the Single Responsibility Principle.
- Separation of Concerns: Distinguish the HTTP server (communication layer) from the business logic (API submodules) and the external integration (utils and GitHub API communication).
- Configuration Management: The presence of .env.example, cursor_mcp.json.example, and command-line options in the README indicates an emphasis on external configuration and environment-driven behavior.
- Deployment Options: Show alternative paths (URL mode vs. command mode) to indicate flexibility in how the service is run depending on the environment or integration requirements.

##### Relevant Technologies and Frameworks
- Node.js and TypeScript: Represent these as the foundational technologies powering the project.
- npm as the package management system along with build scripts (npm run build).
- HTTP Server (using the server subdirectory) and potential use of streaming endpoints (SSE shown by “/sse” in the README).
- External integrations with GitHub APIs, including the need for PAT (Personal Access Tokens) and enterprise-specific permissions outlined in the README.

- From Clients to HTTP Server.
- From HTTP Server to each API Module.
- From the API Modules to Utility Modules and then to GitHub Enterprise API.
- Annotations where necessary to highlight key details like “Handles PAT and config” or “Manages domain-specific actions (issuance, pull requests, etc.)”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client/Integration Layer"
        client["Clients: Cursor/CLI & Desktop"]:::client
    end

    subgraph "Server/HTTP Layer"
        mcpServer["MCP Server"]:::server
    end

    subgraph "API Modules"
        apiActions["API: Actions"]:::api
        apiAdmin["API: Admin"]:::api
        apiIssues["API: Issues"]:::api
        apiPulls["API: Pulls"]:::api
        apiRepos["API: Repos"]:::api
    end

    subgraph "Utility/Configuration Layer"
        utils["Utils: Client/Config"]:::utils
    end

    external["External: GitHub Enterprise API"]:::external
    buildDist["Build Distribution Artifact"]:::build

    %% Relationships
    client -->|"sends request"| mcpServer
    mcpServer -->|"routes request"| apiActions
    mcpServer -->|"routes request"| apiAdmin
    mcpServer -->|"routes request"| apiIssues
    mcpServer -->|"routes request"| apiPulls
    mcpServer -->|"routes request"| apiRepos

    apiActions -->|"uses"| utils
    apiAdmin -->|"uses"| utils
    apiIssues -->|"uses"| utils
    apiPulls -->|"uses"| utils
    apiRepos -->|"uses"| utils

    utils -->|"forwards to"| external

    %% Build Distribution connections (annotation that these modules compile into production artifact)
    mcpServer ---|"compiled into"| buildDist
    apiActions ---|"compiled into"| buildDist
    apiAdmin ---|"compiled into"| buildDist
    apiIssues ---|"compiled into"| buildDist
    apiPulls ---|"compiled into"| buildDist
    apiRepos ---|"compiled into"| buildDist
    utils ---|"compiled into"| buildDist

    %% Click Events for Component Mappings
    click mcpServer "https://github.com/ddukbg/github-enterprise-mcp/blob/main/server/http.ts"
    click mcpServer "https://github.com/ddukbg/github-enterprise-mcp/blob/main/server/index.ts"
    click apiActions "https://github.com/ddukbg/github-enterprise-mcp/tree/main/api/actions"
    click apiAdmin "https://github.com/ddukbg/github-enterprise-mcp/tree/main/api/admin"
    click apiIssues "https://github.com/ddukbg/github-enterprise-mcp/tree/main/api/issues"
    click apiPulls "https://github.com/ddukbg/github-enterprise-mcp/tree/main/api/pulls"
    click apiRepos "https://github.com/ddukbg/github-enterprise-mcp/tree/main/api/repos"
    click utils "https://github.com/ddukbg/github-enterprise-mcp/tree/main/utils"
    click buildDist "https://github.com/ddukbg/github-enterprise-mcp/tree/main/dist"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef server fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef api fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef utils fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef build fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
