feat: OpenDigger MCP Server (OSPP 2025)

[Neilblaze]

Description

This Pull Request (PR) delivers the OpenDigger MCP Server with complete integration of OpenDigger metrics and full MCP support, enabling seamless interaction between LLM clients and OpenDigger’s analytics ecosystem.

The implementation focuses on robustness, real-time streaming, and developer usability. It introduces a caching layer, supports Server-Sent Events (SSE), and provides advanced prompts for improved output quality. Documentation, setup guides, and performance validation have been added to ensure smooth adoption across different MCP clients (Cursor, VS Code, Claude, MCP Inspector, etc.).

💡 This work is done as a part of OSPP '25.

---

✅ Expected Deliverables (Completed)

• 🟢 Enhanced MCP Server with most (if not all) OpenDigger metrics support.
• 🟢 Server-Sent Events (SSE) support for real-time data streaming
• 🟢 Advanced Prompts for robust and context-aware outputs
• 🟢 Complete Documentation (API reference, tutorials, usage examples)

---

🔄 Future Work (TBD)

Once the check is complete by @birdflyi, we can start working on setting up a test suite (if required), and for the same, it needs some discussion with @frank-zsy. Besides, the same shall also allow us to perform a marketplace publication on major MCP platforms (specifically on npm and modelcontextprotocol/servers), but that has to be done via creating a PR from the main repository by the code-owner i.e. @frank-zsy once this PR gets merged with main.

---

High-Level System Architecture

flowchart LR
    LLMClient["LLM Client"] --> MCPServer["OpenDigger<br>MCP Server"]
    MCPServer <--> OpenDigger["OpenDigger<br>(API Layer)"]
    MCPServer --> CacheLayer["Cache Layer<br>(In-Memory)"]

Loading

---

🟦 Data Flow Diagram (Cache)

flowchart TD
    subgraph Client
        LLMClient["👨‍💻 LLM Client<br>(e.g., Cursor IDE)"]
    end

    subgraph "OpenDigger MCP Server"
        direction LR
        
        subgraph "1. Request Handling"
            Validate["✅ Validate Input"]
            CheckCache{"💾 Check Cache?"}
        end

        subgraph "2. Data Fetching"
            FetchAPI["📡 Fetch from API"]
            UpdateCache["📝 Update Cache"]
        end
        
        subgraph "3. Response Generation"
            ProcessData["⚙️ Process & Format Data"]
            SendResponse["📤 Stream (SSE) or<br>Return Complete Response"]
        end
        
        Validate --> CheckCache
        CheckCache -- Cache Miss --> FetchAPI
        FetchAPI --> UpdateCache
        UpdateCache --> ProcessData
        CheckCache -- Cache Hit --> ProcessData
        ProcessData --> SendResponse
    end

    subgraph "External Services"
        OpenDigger["🌐 OpenDigger API"]
        Cache["💾 In-Memory Cache"]
    end

    LLMClient -- "1. MCP Request" --> Validate
    FetchAPI <--> OpenDigger
    CheckCache <--> Cache
    UpdateCache --> Cache
    SendResponse -- "4. Formatted Data" --> LLMClient

    class LLMClient client;
    class OpenDigger,Cache external;
    class Validate,CheckCache,FetchAPI,UpdateCache,ProcessData,SendResponse server;

Loading

---

📌 Resolves #1698
🦄 Tested on local, build running successfully!

cc: @birdflyi, @frank-zsy

---

Before submitting the PR, please take the following into consideration

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. If you don't have an issue, please create one.
• The description should clearly illustrate what problems it solves.
• Ensure that the commit messages follow our guidelines.
• Resolve merge conflicts (if any).

[birdflyi]

npm start NODE_OPTIONS='--inspect'

[Neilblaze]

Similar to this, but here,

"sse:test": "SSE_PORT=3001 npm start"

This actually sets the environment variable SSE_PORT=3001 first, and then runs npm start (sequentially) with that variable available in the environment, which is exactly what we intend to do.

[birdflyi]

You're right. The solution is the same as above.

[birdflyi]

The command here needs to be replaced with "NODE_OPTIONS='--inspect' npm start".

[Neilblaze]

@birdflyi Fixed via 2997217 🚀

[birdflyi]

Agree~

[Neilblaze]

@birdflyi I was playing around with Ant Design's Charts or something simple as Chart.js, but for this iteration, I thought it might be overkill 😅. So I added a note that, if things go well, I can probably spend some time later integrating it directly into our MCP server.

To be honest, I actually tried it out a couple of days ago. The only catch is that I need to craft an efficient prompt (which is quite challenging, since I'll have to do some benchmarking stuff as output data varies with input queries) that, given the data (basically JSON structured in a specific way), can render the diagrams, and ideally save them as PNG or JPEG. 🤔

[birdflyi]

That's nice. It could be opened as another issue or repository. Visualization is always important for user experience. Both generic chart.exe packages and SVG rendering tailored to specific needs are highly recommended~

[birdflyi]

Very well implemented and supported by batch metrics, cache, and platform deployment. As an initial version, it should be sufficient.
My main concern is the license change. If there are no conflicts, changing to Apache 2.0 would also be good, as it is consistent with open finger.

[Neilblaze]

@birdflyi It's now ready to be merged! 🚀

[birdflyi]

All clear! These functions have been tested on the Cursor~