# doitintl/doit-mcp-server architecture

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

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

## Overview

##### Project type and purpose
- This is a TypeScript-based Node.js microservice (the “DoiT MCP Server”) that implements the Model Context Protocol (MCP) to expose DoiT platform data to LLM clients (e.g. Claude).
- The repo is structured as a small monorepo:
- A core “tools” library (root/src/tools) that implements individual API calls (incidents, anomalies, reports, invoices, etc.)
- The MCP server app (doit-mcp-server/) that wires the library into an SSE/HTTP server, serving static assets and handling STDIO mode for local use.

##### File structure
- Top level: CI config (.github/), Dockerfile, license, readme.
- Root package.json + tsconfig.json with a “src/” containing:
- index.ts – entry point for the core tools library or CLI shim
- tools/ – one file per API tool (allocations.ts, anomalies.ts, …)
- utils/ – support modules (filterFields, prompts, toolsHandler)
- Sub-project “doit-mcp-server/”:
- src/app.ts – sets up HTTP/SSE endpoints and static file routes
- src/index.ts – entry script, reads env, starts server or STDIO mode
- src/utils.ts – helper functions for message parsing, streaming
- static/ – bundled frontend/static files under “.doit”
- wrangler.jsonc – config for Cloudflare Workers deployment

##### Key insights from README
- The MCP server exposes an SSE endpoint at /sse for LLM clients.
- It requires DOIT_API_KEY and optional CUSTOMER_CONTEXT.
- Clients (Claude Desktop, Cursor) invoke it via STDIO or TCP/HTTP.
- It supports a fixed set of “tools” (API calls) which it dispatches based on natural-language prompts.

- Labels: each component (Client, SSE Listener, STDIO Adapter, Router, Tool Modules, DoiT API)
- Client → SSE Listener / STDIO Adapter
- SSE Listener → Router → Tool Module → DoiT API
- DoiT API → Tool Module → Router → Client

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Client["LLM Client"]:::client
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        subgraph "MCP Server"
            direction TB

            %% Adapters
            subgraph "Adapters"
                direction TB
                SSEListener["HTTP/SSE Listener"]:::service
                STDIOAdapter["STDIO Adapter"]:::service
            end

            %% Core Handler
            subgraph "Core Handler"
                direction TB
                Router["Request Router & Stream Handler"]:::service
                click Router "https://github.com/doitintl/doit-mcp-server/blob/main/src/utils/toolsHandler.ts"
            end

            %% Supporting Utils
            subgraph "Utility Modules"
                direction TB
                FilterFields["filterFields.ts"]:::utils
                click FilterFields "https://github.com/doitintl/doit-mcp-server/blob/main/src/utils/filterFields.ts"
                Prompts["prompts.ts"]:::utils
                click Prompts "https://github.com/doitintl/doit-mcp-server/blob/main/src/utils/prompts.ts"
                UtilModule["util.ts"]:::utils
                click UtilModule "https://github.com/doitintl/doit-mcp-server/blob/main/src/utils/util.ts"
            end

            %% Core Tools Library
            subgraph "Core Tools Library"
                direction TB
                Allocations["allocations.ts"]:::tool
                click Allocations "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/allocations.ts"
                Anomalies["anomalies.ts"]:::tool
                click Anomalies "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/anomalies.ts"
                Assets["assets.ts"]:::tool
                click Assets "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/assets.ts"
                ChangeCustomer["changeCustomer.ts"]:::tool
                click ChangeCustomer "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/changeCustomer.ts"
                CloudIncidents["cloudIncidents.ts"]:::tool
                click CloudIncidents "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/cloudIncidents.ts"
                Dimension["dimension.ts"]:::tool
                click Dimension "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/dimension.ts"
                Dimensions["dimensions.ts"]:::tool
                click Dimensions "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/dimensions.ts"
                Invoices["invoices.ts"]:::tool
                click Invoices "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/invoices.ts"
                Reports["reports.ts"]:::tool
                click Reports "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/reports.ts"
                Tickets["tickets.ts"]:::tool
                click Tickets "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/tickets.ts"
                ValidateUser["validateUser.ts"]:::tool
                click ValidateUser "https://github.com/doitintl/doit-mcp-server/blob/main/src/tools/validateUser.ts"
                click CoreLib "https://github.com/doitintl/doit-mcp-server/tree/main/src/tools/"
            end

            %% Entry Point
            EntryPoint["Core Library / CLI Entry Point (index.ts)"]:::service
            click EntryPoint "https://github.com/doitintl/doit-mcp-server/blob/main/src/index.ts"
        end

        %% Server App
        subgraph "MCP Server App"
            direction TB
            AppSetup["HTTP/SSE & Static Setup (app.ts)"]:::service
            click AppSetup "https://github.com/doitintl/doit-mcp-server/blob/main/doit-mcp-server/src/app.ts"
            ServerIndex["Startup & STDIO Mode (index.ts)"]:::service
            click ServerIndex "https://github.com/doitintl/doit-mcp-server/blob/main/doit-mcp-server/src/index.ts"
            ServerUtils["Server Utils (utils.ts)"]:::utils
            click ServerUtils "https://github.com/doitintl/doit-mcp-server/blob/main/doit-mcp-server/src/utils.ts"
            StaticAssets["Static Assets (.doit)"]:::data
            click StaticAssets "https://github.com/doitintl/doit-mcp-server/tree/main/doit-mcp-server/static/doit/"
            WranglerConfig["Cloudflare Worker Config"]:::infra
            click WranglerConfig "https://github.com/doitintl/doit-mcp-server/blob/main/doit-mcp-server/wrangler.jsonc"
            TSConfigServer["TS Config (mcp server)"]:::infra
            click TSConfigServer "https://github.com/doitintl/doit-mcp-server/blob/main/doit-mcp-server/tsconfig.json"
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DoiTAPI["DoiT REST API"]:::external
    end

    %% Deployment & CI
    subgraph "Infrastructure"
        direction TB
        Dockerfile["Dockerfile"]:::infra
        click Dockerfile "https://github.com/doitintl/doit-mcp-server/tree/main/Dockerfile"
        CI["CI Workflows"]:::infra
        click CI "https://github.com/doitintl/doit-mcp-server/blob/main/.github/workflows/test.yml"
        TSConfigRoot["TS Config (root)"]:::infra
        click TSConfigRoot "https://github.com/doitintl/doit-mcp-server/blob/main/tsconfig.json"
    end

    %% Connections
    Client -->|HTTP/SSE| SSEListener
    Client -->|STDIO| STDIOAdapter
    Client -->|GET Static| StaticAssets
    SSEListener --> Router
    STDIOAdapter --> Router
    Router --> FilterFields
    Router --> Prompts
    Router --> UtilModule
    Router -->|dispatch| Allocations
    Router --> Anomalies
    Router --> Assets
    Router --> ChangeCustomer
    Router --> CloudIncidents
    Router --> Dimension
    Router --> Dimensions
    Router --> Invoices
    Router --> Reports
    Router --> Tickets
    Router --> ValidateUser
    Allocations --> DoiTAPI
    Anomalies --> DoiTAPI
    Assets --> DoiTAPI
    ChangeCustomer --> DoiTAPI
    CloudIncidents --> DoiTAPI
    Dimension --> DoiTAPI
    Dimensions --> DoiTAPI
    Invoices --> DoiTAPI
    Reports --> DoiTAPI
    Tickets --> DoiTAPI
    ValidateUser --> DoiTAPI
    DoiTAPI --> Router
    Router -->|SSE Stream| SSEListener
    Router -->|STDIO Stream| STDIOAdapter

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef service fill:#bbf,stroke:#333,stroke-width:1px
    classDef tool fill:#bfb,stroke:#333,stroke-width:1px
    classDef utils fill:#ffb,stroke:#333,stroke-width:1px
    classDef external fill:#fbf,stroke:#333,stroke-width:1px
    classDef data fill:#dfd,stroke:#333,stroke-width:1px
    classDef infra fill:#ffd,stroke:#333,stroke-width:1px
```
