# kaavyabaranwal/merchant-agent-connector architecture

> Architecture diagram of the GitHub repository kaavyabaranwal/merchant-agent-connector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaavyabaranwal/merchant-agent-connector
- Repository: https://github.com/kaavyabaranwal/merchant-agent-connector

## Overview

This is a read-only Zoho Inventory MCP connector: an MCP client invokes registered item or sales-order tools, the matching connector normalizes Zoho responses, and the Zoho client performs authenticated API requests with centralized error handling and rate-limit retries. OAuth token exchange and the external Zoho services are shown as distinct dependencies. The graph focuses on runtime behavior; seed and token-generation scripts are setup utilities, not product workflow. Edges are limited to relationships visible in the README or excerpted source.

Main entry points: [`src/connectors/zoho/client.ts`](https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/client.ts) (Zoho API client), [`src/mcp/server.ts`](https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/mcp/server.ts) (MCP tool server), [`src/connectors/zoho/items.ts`](https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/items.ts) (Item tools), [`src/connectors/zoho/sales-orders.ts`](https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/sales-orders.ts) (Sales-order tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_server["MCP tool server<br/>[server.ts]"]
end

subgraph group_domain["Inventory and Orders"]
  node_items["Item tools<br/>[items.ts]"]
  node_orders["Sales-order tools<br/>[sales-orders.ts]"]
end

subgraph group_integration["Zoho Integration"]
  node_client["Zoho API client<br/>[client.ts]"]
  node_oauth["Zoho OAuth service"]
  node_inventory_api["Zoho Inventory API"]
end

node_agent(("MCP client / agent"))

node_agent -->|"invokes tools"| node_server
node_server -->|"dispatches item calls"| node_items
node_server -->|"dispatches order calls"| node_orders
node_items -->|"requests item data"| node_client
node_orders -->|"requests order data"| node_client
node_client -->|"exchanges refresh token"| node_oauth
node_client -->|"fetches inventory data"| node_inventory_api

click node_server "https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/mcp/server.ts"
click node_items "https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/items.ts"
click node_orders "https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/sales-orders.ts"
click node_client "https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_agent toneBlue
class node_items,node_orders toneAmber
class node_client,node_oauth,node_inventory_api toneMint
```

## Components

### MCP Interface

- [MCP tool server](https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/mcp/server.ts): `src/mcp/server.ts`

### Inventory and Orders

- [Item tools](https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/items.ts): `src/connectors/zoho/items.ts`
- [Sales-order tools](https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/sales-orders.ts): `src/connectors/zoho/sales-orders.ts`

### Zoho Integration

- [Zoho API client](https://github.com/kaavyabaranwal/merchant-agent-connector/blob/main/src/connectors/zoho/client.ts): `src/connectors/zoho/client.ts`
- **Zoho OAuth service**
- **Zoho Inventory API**

### Other components

- **MCP client / agent**

## Connections

- MCP client / agent → MCP tool server: invokes tools (evidence: `README.md`)
- MCP tool server → Item tools: dispatches item calls (evidence: `src/mcp/server.ts`)
- MCP tool server → Sales-order tools: dispatches order calls (evidence: `src/mcp/server.ts`)
- Item tools → Zoho API client: requests item data (evidence: `src/connectors/zoho/items.ts`)
- Sales-order tools → Zoho API client: requests order data (evidence: `src/connectors/zoho/sales-orders.ts`)
- Zoho API client → Zoho OAuth service: exchanges refresh token (evidence: `src/connectors/zoho/client.ts`)
- Zoho API client → Zoho Inventory API: fetches inventory data (evidence: `src/connectors/zoho/client.ts`)
