# neilblaze/opendigger-mcp-server architecture

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

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

## Overview

##### Project type and purpose
- This is a backend-only, TypeScript-based Model Context Protocol (MCP) server that exposes a set of JSON-RPC tools and prompts for advanced repository analytics (via OpenDigger).
- Its sole responsibility is to load configuration, listen on stdio (and optionally SSE), handle incoming JSON-RPC method calls, invoke analysis routines, and return JSON results.

##### File structure
- Top-level:
- `.cursor/` – MCP client configuration (Cursor AI IDE integration).
- `mcp-server/` – the entire server implementation.
- `INSTALLATION.md`, `README.md`, `LICENSE` – docs.
- Inside `mcp-server/`:
- `src/index.ts` – entrypoint that bootstraps the JSON-RPC server (stdio or SSE).
- `src/analysis.ts` – core “tools” handlers (e.g., get_open_digger_metric, compare_repositories).
- `src/utils.ts` – shared utilities (cache management, HTTP calls).
- `src/version.ts` – version metadata.
- `.env.example` – environment variables (CACHE_TTL_SECONDS, SSE_PORT, SSE_HOST).
- `package.json`, `tsconfig.json` – build and dependency definitions.

##### README for additional insights
- The server communicates over JSON-RPC 2.0 on standard I/O by default, with an optional SSE endpoint for event streams.
- It registers exactly six tools and three prompts.
- It expects a Cursor MCP client to spawn the Node process via `.cursor/mcp.json` with environment overrides.

##### Components
a. MCP Server Process (Node.js + TypeScript)
- Entrypoint (index.ts)
- JSON-RPC Protocol Handler
- Tool Handlers (analysis.ts)
- Utility Layer (utils.ts)
- Version Module (version.ts)
b. Configuration
- Environment Variables (`.env`)
- Cursor Configuration (`.cursor/mcp.json`)
c. Communication Interfaces
- Standard I/O (stdin/stdout JSON-RPC)
- Optional SSE Server (HTTP)
d. External Dependencies
- OpenDigger Data APIs (HTTP endpoints)
- NPM libraries (e.g., `json-rpc`, `axios` or `node-fetch`)
- Cursor AI IDE (MCP client)
e. Build & Deployment
- TypeScript compiler (tsc)
- npm scripts (build, watch, start)

##### Relationships and data flows
- The **Cursor IDE** (or any MCP client) spawns the MCP Server using the command/args from `.cursor/mcp.json`.
- Client → (stdin) → **JSON-RPC Handler** in `index.ts`.
- Handler dispatches to **Tool Handlers** in `analysis.ts`.
- Handlers use **Utils** to:
- Fetch data from external OpenDigger APIs
- Cache results (based on `CACHE_TTL_SECONDS`)
- Responses flow back → (stdout) → Client.
- If enabled, **SSE module** listens on `SSE_HOST:SSE_PORT` to stream events (health checks, diagnostics).
- Build artifacts (`dist/`) are produced by the TypeScript compiler, invoked via `npm run build`.

##### Architectural patterns and design principles
- Layered architecture:
- Protocol Layer (JSON-RPC entrypoint)
- Application Layer (tool & prompt handlers)
- Utility Layer (caching, HTTP)
- Config Layer (env & client config)
- Single-process microservice focused on one domain.
- Separation of concerns: index.ts for wiring, analysis.ts for business logic, utils.ts for cross-cutting concerns.
- Configuration-driven integration (Cursor MCP via JSON file).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Layer
    subgraph "External Systems"
        direction TB
        CursorIDE["Cursor AI IDE (MCP Client)"]:::external
        OpenDiggerAPI[("OpenDigger Data API")]:::external
    end

    %% Configuration Layer
    subgraph "Configuration" 
        direction TB
        EnvExample[".env.example"]:::config
        CursorConfig[".cursor/mcp.json"]:::config
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        TSConfig["tsconfig.json"]:::build
        PackageJSON["package.json"]:::build
        Compile["tsc compile"]:::build
        Dist["dist/"]:::build
        TSConfig --> Compile
        PackageJSON --> Compile
        Compile --> Dist
    end

    %% Runtime Layers
    subgraph "Runtime (mcp-server)"
        direction TB
        NodeProcess["Node.js Process"]:::runtime
        subgraph "Protocol Layer"
            direction TB
            JSONRPC["JSON-RPC Handler (stdin/stdout)"]:::protocol
            SSE["SSE Server Module"]:::protocol
        end
        subgraph "Application Layer"
            direction TB
            Analysis["Tool Handlers (analysis.ts)"]:::business
        end
        subgraph "Utility Layer"
            direction TB
            Utils["Utility Layer (utils.ts)"]:::util
            Version["Version Module (version.ts)"]:::util
        end
        ConfigLayer["Env & Client Config"]:::config
        NodeProcess --> JSONRPC
        NodeProcess --> SSE
        NodeProcess --> Analysis
        NodeProcess --> Utils
        NodeProcess --> Version
        NodeProcess --> ConfigLayer
    end

    %% Data Flows
    CursorIDE -->|spawns via MCP config| NodeProcess
    CursorIDE -->|JSON-RPC Request| JSONRPC
    JSONRPC -->|"dispatch"| Analysis
    Analysis -->|uses| Utils
    Utils -->|HTTP GET/POST| OpenDiggerAPI
    OpenDiggerAPI -->|data| Utils
    Analysis -->|result| JSONRPC
    JSONRPC -->|JSON-RPC Response| CursorIDE
    SSE -.->|SSE Event Stream| CursorIDE

    %% Click Events
    click JSONRPC "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/src/index.ts"
    click SSE "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/src/index.ts"
    click NodeProcess "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/src/index.ts"
    click Analysis "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/src/analysis.ts"
    click Utils "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/src/utils.ts"
    click Version "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/src/version.ts"
    click EnvExample "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/.env.example"
    click CursorConfig "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/.cursor/mcp.json"
    click TSConfig "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/tsconfig.json"
    click PackageJSON "https://github.com/neilblaze/opendigger-mcp-server/blob/mcp-server-wip/mcp-server/package.json"

    %% Styles
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef config fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef build fill:#add8e6,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef runtime fill:#ffffff,stroke:#333,stroke-width:1px
    classDef protocol fill:#87cefa,stroke:#333,stroke-width:1px
    classDef business fill:#98fb98,stroke:#333,stroke-width:1px
    classDef util fill:#ffff99,stroke:#333,stroke-width:1px
```
