# srinathpasupathi/zoho-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/srinathpasupathi/zoho-mcp-server
- Repository: https://github.com/srinathpasupathi/zoho-mcp-server

## Overview

##### Project type and purpose
- This is a middleware “MCP” (Model-Context Protocol) server that sits between downstream clients (e.g., Claude Desktop, Cursor, Windsurf, or the built-in Inspector UI) and the upstream Sentry REST API.
- It supports two transports:
a) HTTP+SSE exposed via a Cloudflare Worker (for remote hosting)
b) STDIO (for local testing and CLI integration via the `mcp-remote` tool)

##### File structure
- Top-level deployment artifacts:
- `worker/` – Cloudflare Worker entrypoints (auth, app, SSE)
- `src/mcp/` – Core MCP server logic, tool definitions, transport adapters (cloudflare-worker vs stdio)
- `src/evals/` – Individual “tool” implementations (list-projects, create-team, etc.)
- `src/lib/sentry-api/` – Sentry REST client, schemas, utilities
- `src/lib/oauth.ts` – OAuth handshake with Sentry
- `src/web/` + `index.html` – Inspector UI (React + Vite) for testing tools over SSE
- Configs: `wrangler.jsonc`, `vite.config.ts`, multiple `tsconfig.*` for different targets, Dockerfile

##### README for additional insights
- Describes two modes (remote vs stdio), OAuth scopes, local-dev setup, how to launch the Inspector, how to configure Claude Desktop.
- No persistent datastore—pure proxy + tool-invocation layer.

##### Main components & relationships
A. Clients
1. Inspector UI (browser React app served via Vite or static from Worker)
2. Third-party MCP clients (Claude Desktop, Cursor, Windsurf) using STDIO or HTTP+SSE
3. CLI shim – `mcp-remote` (local Node script that proxies SSE over STDIO)
B. Transport layer
1. Cloudflare Worker endpoint (`/sse`) – handles inbound SSE connections, routes to MCP core
2. STDIO transport – local Node process for testing, communicates via stdin/stdout
C. Core MCP server (in `src/mcp/`)
1. `server.ts` – central dispatcher for MCP protocol messages
2. `toolDefinitions.ts` – registers available tools, input/output schemas
3. `transports/` – adapter implementations for Cloudflare Worker vs stdio
D. Tool implementations (`src/evals/`)
- Each file implements one REST call: list-projects, create-team, get-issue, etc.
- Utilities in `src/evals/utils.ts` factor out common request/response logic
E. Sentry integration (`src/lib/sentry-api/`)
- `client.ts` + `schema.ts` + `utils.ts` – wraps HTTP calls to Sentry’s API
- `oauth.ts` – performs OAuth handshake, token refresh
F. External dependency
- Sentry API (REST endpoint)

Data / control flow:
1. Client → (HTTP+SSE or STDIO) → MCP transport adapter
2. Transport → MCP core dispatcher → selects tool handler
3. Tool handler (`eval` module) → invokes Sentry API client → receives data
4. MCP core → streams events/results back over SSE or STDIO → Client

##### Architectural patterns & design principles
- Transport abstraction: same core logic works over HTTP (Worker) or STDIO
- Plugin-style tools: each API operation is a separate “eval” module, auto-discovered by `toolDefinitions.ts`
- Event-driven SSE protocol for streaming responses
- OAuth 2.0 authorization layer separate from business logic
- CI/CD via GitHub Actions, Dockerfile for containerized deploy

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer: Clients
    subgraph "Clients" 
        classDef client fill:#bbdefb,stroke:#1e88e5
        InspectorUI["Inspector UI (React + Vite)"]:::client
        ThirdParty["Third-Party MCP Clients\n(Claude, Cursor, Windsurf)"]:::client
        CLIShim["CLI Shim (mcp-remote)"]:::client
    end

    %% Transport Layer
    subgraph "Transport Layer"
        classDef transport fill:#c8e6c9,stroke:#43a047
        Worker["Cloudflare Worker\n(HTTP + SSE)"]:::transport
        STDIOTransport["STDIO Transport\n(Node.js)"]:::transport
    end

    %% Core Layer
    subgraph "Core Layer"
        classDef core fill:#e3f2fd,stroke:#1976d2
        Server["MCP Core Dispatcher"]:::core
        ToolRegistry["Tool Definitions / Registry"]:::core
    end

    %% Eval Modules
    subgraph "Eval Modules" 
        classDef evals fill:#fff9c4,stroke:#fbc02d
        EvalsDir["Tool Implementations (src/evals/)"]:::evals
    end

    %% Integration Layer
    subgraph "Integration Layer"
        classDef integration fill:#ffe0b2,stroke:#fb8c00
        SentryClient["Sentry API Client"]:::integration
        OAuth["OAuth 2.0 Handshake"]:::integration
    end

    %% External
    subgraph "External"
        classDef external fill:#ffccbc,stroke:#e64a19
        SentryAPI["Sentry REST API"]:::external
    end

    %% Connections - Requests
    InspectorUI -->|HTTP/SSE| Worker
    ThirdParty -->|STDIO| STDIOTransport
    CLIShim -->|STDIO| STDIOTransport

    Worker -->|Protocol Messages| Server
    STDIOTransport -->|Protocol Messages| Server

    Server -->|invoke| ToolRegistry
    ToolRegistry -->|dispatch to| EvalsDir

    EvalsDir -->|calls| SentryClient
    SentryClient -->|OAuth| OAuth
    OAuth -->|token| SentryClient
    SentryClient -->|HTTP REST| SentryAPI

    %% Connections - Responses
    SentryAPI -->|response| SentryClient
    SentryClient -->|events/results| Server
    Server -->|stream| Worker
    Server -->|stream| STDIOTransport
    Worker -->|SSE| InspectorUI
    STDIOTransport -->|STDIO| ThirdParty
    STDIOTransport -->|STDIO| CLIShim

    %% Click Events
    click InspectorUI "https://github.com/srinathpasupathi/zoho-mcp-server/tree/main/src/web/"
    click Worker "https://github.com/srinathpasupathi/zoho-mcp-server/tree/main/src/worker/"
    click STDIOTransport "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/src/mcp/transports/stdio.ts"
    click CLIShim "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/src/mcp/start-stdio.ts"
    click Server "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/src/mcp/server.ts"
    click ToolRegistry "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/src/mcp/toolDefinitions.ts"
    click SentryClient "https://github.com/srinathpasupathi/zoho-mcp-server/tree/main/src/lib/sentry-api/"
    click OAuth "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/src/lib/oauth.ts"
    click EvalsDir "https://github.com/srinathpasupathi/zoho-mcp-server/tree/main/src/evals/"
    click Worker "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/wrangler.jsonc"
    click Dockerfile "https://github.com/srinathpasupathi/zoho-mcp-server/tree/main/Dockerfile"
    click viteConfig "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/vite.config.ts"
    click tsWorker "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/tsconfig.worker.json"
    click tsNode "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/tsconfig.node.json"
    click GH_Eval "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/github/workflows/eval.yml"
    click GH_Test "https://github.com/srinathpasupathi/zoho-mcp-server/blob/main/github/workflows/test.yml"

    %% Styles
    classDef client fill:#bbdefb,stroke:#1e88e5
    classDef transport fill:#c8e6c9,stroke:#43a047
    classDef core fill:#e3f2fd,stroke:#1976d2
    classDef evals fill:#fff9c4,stroke:#fbc02d
    classDef integration fill:#ffe0b2,stroke:#fb8c00
    classDef external fill:#ffccbc,stroke:#e64a19
```
