# kkeeling/zoho-mcp architecture

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

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

## Overview

##### Project Type and Purpose
- This is a standalone Python MCP (Model Control Protocol) microservice that exposes Zoho Books operations to AI agents (e.g., Anthropic Claude Desktop, Cursor).
- It is not a full-stack web app; rather it’s a backend integration server with multiple transports (STDIO, HTTP/SSE, WebSocket).

##### File Structure
- Top-level:
- server.py – entrypoint that parses CLI flags and spins up the chosen transport.
- config/ – environment-based settings loader (.env).
- zoho_mcp/ – core Python package:
– auth_flow.py – OAuth2 handshake with Zoho.
– transport.py – low-level HTTP/WebSocket/STDIO handlers.
– tools/ – implementations of MCP “tools” (contacts, invoices, expenses, items, sales).
– models/ – Pydantic models for request/response schemas.
– logging.py, errors.py – centralized logging and error handling.
- docs/ – client integration guides.
- tests/ – pytest test suite covering API, auth, tools, etc.

##### Key Insights from README
- Supports three transport modes (stdio, HTTP/SSE, WebSocket) selectable via CLI flags.
- Implements the MCP protocol (mcp-python-sdk) to parse incoming commands and dispatch to tool handlers.
- Uses Pydantic for input/output validation.
- Communicates with external Zoho Books REST API over OAuth2.
- Extensive error handling, logging, and configuration via .env.

##### Main Components & Relationships
a. Client Layer
- Claude Desktop (STDIO)
- Cursor or other HTTP/SSE/WebSocket clients
↕
b. Transport Layer (server.py + zoho_mcp.transport)
- STDIOHandler
- HTTP/SSE Handler
- WebSocket Handler
↕
c. MCP Core & Dispatcher (mcp-python-sdk integration)
- Command Parser
- Context Manager
↕
d. Tool Modules (zoho_mcp/tools/*.py)
- ContactsTool
- InvoicesTool
- ExpensesTool
- ItemsTool
- SalesTool
↕
e. Model & Validation Layer (zoho_mcp/models)
- Pydantic schemas for requests & responses
↕
f. Auth Layer (zoho_mcp/auth_flow)
- OAuth2 token management
↕
g. External Zoho Books API
- REST calls to Zoho endpoints
h. Config & Secrets (config/.env)
i. Logging & Error Handling (zoho_mcp/logging, errors)

##### Architectural Patterns & Principles
- Layered architecture: Transport → Core/Dispatcher → Tools → External API.
- Single Responsibility per module (each tool file focuses on one resource).
- Dependency Injection via configuration for credentials and region.
- Validation at boundaries using Pydantic (fail fast on bad input).

##### Essential Elements
- Clear labels for each module (e.g., “ContactsTool”, “InvoicesTool”).
- Notes or callouts for:
- .env configuration loading
- Error handling path (exceptions → logging → client)
- Authentication refresh flow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        A1["Claude Desktop\n(STDIO)"]:::external
        A2["Cursor & HTTP/SSE/WebSocket\nClients"]:::external
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        B0["server.py\n(Entrypoint)"]:::internal
        B1["STDIOHandler"]:::internal
        B2["HTTP/SSE Handler"]:::internal
        B3["WebSocket Handler"]:::internal
    end

    %% MCP Core & Dispatcher
    subgraph "MCP Core & Dispatcher"
        direction TB
        C1["Command Parser"]:::internal
        C2["Context Manager"]:::internal
    end

    %% Tool Modules
    subgraph "Tool Modules" 
        direction TB
        D1["ContactsTool"]:::tool
        D2["InvoicesTool"]:::tool
        D3["ExpensesTool"]:::tool
        D4["ItemsTool"]:::tool
        D5["SalesTool"]:::tool
    end

    %% Model & Validation Layer
    subgraph "Model & Validation"
        direction TB
        E0["Base Schemas"]:::model
        E1["Contacts Schemas"]:::model
        E2["Invoices Schemas"]:::model
        E3["Expenses Schemas"]:::model
        E4["Items Schemas"]:::model
        E5["Sales Schemas"]:::model
    end

    %% Auth Layer
    subgraph "Auth Layer"
        direction TB
        F1["OAuth2 Flow"]:::internal
    end

    %% External API
    subgraph "External Systems"
        direction TB
        G1["Zoho Books REST API"]:::external
    end

    %% Config & Secrets
    subgraph "Configuration"
        direction TB
        H1[".env Example"]:::config
        H2["Settings Loader"]:::config
    end

    %% Logging & Errors
    subgraph "Logging & Error Handling"
        direction TB
        I1["Logging Subsystem"]:::error
        I2["Error Handling"]:::error
    end

    %% Flows
    A1 -->|"STDIO"| B1
    A2 -->|"HTTP/SSE, WebSocket"| B2
    A2 -->|"HTTP/SSE, WebSocket"| B3
    B0 --> B1
    B0 --> B2
    B0 --> B3
    B1 -->|"MCP Protocol"| C1
    B2 -->|"MCP Protocol"| C1
    B3 -->|"MCP Protocol"| C1
    C1 --> C2
    C2 --> D1
    C2 --> D2
    C2 --> D3
    C2 --> D4
    C2 --> D5
    D1 --> E1
    D2 --> E2
    D3 --> E3
    D4 --> E4
    D5 --> E5
    D1 --> F1
    D2 --> F1
    D3 --> F1
    D4 --> F1
    D5 --> F1
    F1 -->|"HTTPS/REST"| G1
    E0 --> E1
    E0 --> E2
    E0 --> E3
    E0 --> E4
    E0 --> E5
    H1 --> H2
    H2 --> B0
    H2 --> F1
    I2 --> I1
    I1 --> B0
    I1 --> C1
    I1 --> D1
    I1 --> F1

    %% Click Events
    click B0 "https://github.com/kkeeling/zoho-mcp/blob/main/server.py"
    click H1 "https://github.com/kkeeling/zoho-mcp/blob/main/config/.env.example"
    click H2 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/config/settings.py"
    click F1 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/auth_flow.py"
    click B1 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/transport.py"
    click B2 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/transport.py"
    click B3 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/transport.py"
    click C1 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/tools/api.py"
    click C2 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/tools/api.py"
    click D1 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/tools/contacts.py"
    click D2 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/tools/invoices.py"
    click D3 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/tools/expenses.py"
    click D4 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/tools/items.py"
    click D5 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/tools/sales.py"
    click E0 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/models/base.py"
    click E1 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/models/contacts.py"
    click E2 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/models/invoices.py"
    click E3 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/models/expenses.py"
    click E4 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/models/items.py"
    click E5 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/models/sales.py"
    click I1 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/logging.py"
    click I2 "https://github.com/kkeeling/zoho-mcp/blob/main/zoho_mcp/errors.py"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#1167b1,color:#000;
    classDef external fill:#d5ead1,stroke:#38761d,color:#000;
    classDef config fill:#fff2cc,stroke:#bf9000,color:#000;
    classDef error fill:#f4cccc,stroke:#cc0000,color:#000;
    classDef tool fill:#d9d2e9,stroke:#6d26aa,color:#000;
    classDef model fill:#fce5cd,stroke:#e69138,color:#000;
```
