How neilblaze/opendigger-mcp-server works
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).