How kkeeling/zoho-mcp works
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