# zebpay/zebpay-mcp-server architecture

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

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

## Overview

1. **Overall shape**
   This repository is a single-process **Node.js/TypeScript MCP server** for Zebpay. It does not expose an HTTP server; it runs over **stdio only** so an MCP client like Cursor or Claude Desktop launches it as a local subprocess and exchanges protocol messages through standard input/output.

2. **Entry point and orchestration**
   `src/index.ts` is the top-level bootstrap. It reads environment-driven configuration, wires up MCP transport, and registers the server’s tools, resources, prompts, and logging/error handling. That file is the main composition boundary for the whole system.

3. **MCP-facing layer**
   The `src/mcp/` folder is the protocol boundary. It contains:
   - `tools_spot.ts` and `tools_futures.ts` for the callable MCP tools
   - `resources.ts` for read-only resource exposure
   - `prompts.ts` for reusable agent prompts
   - `errors.ts` and `logging.ts` for normalized MCP errors and telemetry
   This is the layer that converts MCP requests into internal service calls and then into protocol-shaped responses.

4. **Domain split: spot vs futures**
   The codebase is intentionally split into two product domains:
   - `src/public/` and `src/private/SpotClient.ts` for **spot**
   - `src/public/PublicFuturesClient.ts` and `src/private/FuturesClient.ts` for **futures**
   That separation matters architecturally because the two APIs have different endpoints, authentication needs, and tool sets, even though they share infrastructure.

5. **Public vs authenticated flows**
   Public market-data requests go through the `src/public/` clients and do not require credentials. Private trading/account requests go through `src/private/`, where requests are signed and authenticated before being sent to Zebpay. This creates a clean boundary between unauthenticated market reads and credentialed trading operations.

6. **Shared HTTP and API integration**
   `src/http/httpClient.ts` and `src/private/ZebpayAPI.ts` form the outbound integration core. The shared HTTP client handles request execution, timeout/retry behavior, and likely response/error normalization. The API wrapper is the central connector to Zebpay endpoints across spot, futures, and market data base URLs from configuration.

7. **Security and signing**
   `src/security/credentials.ts` and `src/security/signing.ts` isolate secret handling from business logic. Private tool calls depend on environment-provided API key/secret plus HMAC-style signing before dispatch. This is a critical boundary: credentials are never meant to leak into MCP-facing layers or logs.

8. **Validation and response shaping**
   `src/validation/` contains Zod-based schemas and validators that gate every tool input before outbound calls occur. `src/utils/responseFormatter.ts` and `src/types/responses.ts` standardize the shape of successful results and error payloads so the MCP layer can return consistent, predictable outputs to clients.

9. **Operational helpers**
   `src/utils/` provides support functions that are cross-cutting rather than domain-specific:
   - `cache.ts` for memoized or short-lived data reuse
   - `metrics.ts` for operational counters/measurements
   - `fileLogger.ts` for optional persistence of logs
   These sit beneath the MCP and client layers and are used to improve observability and reduce redundant API calls.

10. **Logging and observability**
   Logging is first-class but optional. The README and `docs/LOGGING.md` show a file-backed mode in addition to normal runtime logs, and the `scripts/` folder includes log inspection, stats, and cleanup utilities. This suggests the server is meant to be debuggable in local MCP workflows without changing its runtime protocol boundary.

11. **Configuration boundary**
   `src/config.ts` centralizes environment-driven settings such as base URLs, log level, timeouts, retry counts, and required API credentials. The repo explicitly relies on environment variables with no fallback defaults in code, which makes deployment configuration an external concern rather than a hidden runtime dependency.

12. **Testing and contract protection**
   Tests under `src/__tests__/` cover errors, prompts, resources, and validation. That implies the most important contracts are not UI behavior but protocol correctness, input validation, and MCP-facing semantics. These tests likely protect the server’s shape as an agent tool provider.

13. **How data flows through the system**
   The typical path is: MCP client request → `src/index.ts` transport → MCP tool/resource/prompt handler in `src/mcp/` → validation in `src/validation/` → public or authenticated Zebpay client → shared HTTP layer → Zebpay API → formatted result/error back through the MCP layer. Private trading flows add credential lookup and request signing before the HTTP call.

14. **External dependencies that matter**
   The architecture depends materially on `@modelcontextprotocol/sdk` for protocol handling, `undici` for outbound HTTP, and `zod` for input validation. The server’s external runtime dependency is Zebpay’s public and private API surface; everything else is internal orchestration around that integration.

Main entry points: [`src/index.ts`](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/index.ts) (Entry point), [`src/mcp/tools_spot.ts`](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/tools_spot.ts) (Spot tools), [`src/mcp/tools_futures.ts`](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/tools_futures.ts) (Futures tools), [`src/__tests__/validation.test.ts`](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/__tests__/validation.test.ts) (Contract tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & protocol"]
  node_src_index["Entry point<br/>stdio bootstrap<br/>[index.ts]"]
  node_mcp_tools_spot["Spot tools<br/>mcp tools<br/>[tools_spot.ts]"]
  node_mcp_tools_futures["Futures tools<br/>mcp tools<br/>[tools_futures.ts]"]
  node_mcp_resources["Resources<br/>[resources.ts]"]
  node_mcp_prompts["Prompts<br/>[prompts.ts]"]
  node_mcp_errors["MCP errors<br/>protocol errors<br/>[errors.ts]"]
  node_mcp_logging["MCP logging<br/>telemetry bridge<br/>[logging.ts]"]
end

subgraph group_domain["Domain clients"]
  node_spot_public["Spot public<br/>spot market client<br/>[PublicClient.ts]"]
  node_spot_private["Spot private<br/>spot trading client<br/>[SpotClient.ts]"]
  node_futures_public["Futures public<br/>futures market client"]
  node_futures_private["Futures private<br/>futures trading client<br/>[FuturesClient.ts]"]
end

subgraph group_integration["Integration core"]
  node_zebpay_api["Zebpay API<br/>api gateway<br/>[ZebpayAPI.ts]"]
  node_http_client["HTTP client<br/>outbound http<br/>[httpClient.ts]"]
  node_config["Config<br/>[config.ts]"]
  node_credentials["Credentials<br/>secret loader<br/>[credentials.ts]"]
  node_signing["Signing<br/>[signing.ts]"]
end

subgraph group_ops["Support & tests"]
  node_validation["Validation<br/>[validators.ts]"]
  node_schemas["Schemas<br/>[schemas.ts]"]
  node_formatter["Formatter<br/>response shaping"]
  node_responses["Response types<br/>result models<br/>[responses.ts]"]
  node_cache["Cache<br/>[cache.ts]"]
  node_metrics["Metrics<br/>[metrics.ts]"]
  node_file_logger["File logger<br/>optional logging<br/>[fileLogger.ts]"]
  node_tests["Contract tests<br/>test suite<br/>[validation.test.ts]"]
end

node_src_index -->|"registers"| node_mcp_tools_spot
node_src_index -->|"registers"| node_mcp_tools_futures
node_src_index -->|"registers"| node_mcp_resources
node_src_index -->|"registers"| node_mcp_prompts
node_src_index -->|"wires"| node_mcp_errors
node_src_index -->|"wires"| node_mcp_logging
node_mcp_tools_spot -->|"validates"| node_validation
node_mcp_tools_futures -->|"validates"| node_validation
node_validation -->|"uses"| node_schemas
node_mcp_tools_spot -->|"calls"| node_spot_public
node_mcp_tools_spot -->|"calls"| node_spot_private
node_mcp_tools_futures -->|"calls"| node_futures_public
node_mcp_tools_futures -->|"calls"| node_futures_private
node_spot_public -->|"requests"| node_http_client
node_spot_private -->|"signs"| node_signing
node_spot_private -->|"loads"| node_credentials
node_spot_private -->|"uses"| node_zebpay_api
node_futures_public -->|"requests"| node_http_client
node_futures_private -->|"signs"| node_signing
node_futures_private -->|"loads"| node_credentials
node_futures_private -->|"uses"| node_zebpay_api
node_zebpay_api -->|"dispatches"| node_http_client
node_src_index -->|"reads"| node_config
node_spot_public -->|"reads"| node_config
node_futures_public -->|"reads"| node_config
node_zebpay_api -->|"reads"| node_config
node_mcp_tools_spot -->|"formats"| node_formatter
node_mcp_tools_futures -->|"formats"| node_formatter
node_formatter -->|"adapts"| node_responses
node_mcp_logging -.->|"records"| node_metrics
node_mcp_logging -.->|"optionally writes"| node_file_logger
node_tests -.->|"covers"| node_mcp_tools_spot
node_tests -.->|"covers"| node_mcp_tools_futures
node_tests -.->|"covers"| node_validation
node_tests -.->|"covers"| node_mcp_resources
node_tests -.->|"covers"| node_mcp_prompts

click node_src_index "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/index.ts"
click node_mcp_tools_spot "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/tools_spot.ts"
click node_mcp_tools_futures "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/tools_futures.ts"
click node_mcp_resources "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/resources.ts"
click node_mcp_prompts "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/prompts.ts"
click node_mcp_errors "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/errors.ts"
click node_mcp_logging "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/logging.ts"
click node_spot_public "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/public/PublicClient.ts"
click node_spot_private "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/private/SpotClient.ts"
click node_futures_public "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/public/PublicFuturesClient.ts"
click node_futures_private "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/private/FuturesClient.ts"
click node_zebpay_api "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/private/ZebpayAPI.ts"
click node_http_client "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/http/httpClient.ts"
click node_config "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/config.ts"
click node_credentials "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/security/credentials.ts"
click node_signing "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/security/signing.ts"
click node_validation "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/validation/validators.ts"
click node_schemas "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/validation/schemas.ts"
click node_formatter "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/utils/responseFormatter.ts"
click node_responses "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/types/responses.ts"
click node_cache "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/utils/cache.ts"
click node_metrics "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/utils/metrics.ts"
click node_file_logger "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/utils/fileLogger.ts"
click node_tests "https://github.com/zebpay/zebpay-mcp-server/blob/main/src/__tests__/validation.test.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_src_index,node_mcp_tools_spot,node_mcp_tools_futures,node_mcp_resources,node_mcp_prompts,node_mcp_errors,node_mcp_logging toneBlue
class node_spot_public,node_spot_private,node_futures_public,node_futures_private toneAmber
class node_zebpay_api,node_http_client,node_config,node_credentials,node_signing toneMint
class node_validation,node_schemas,node_formatter,node_responses,node_cache,node_metrics,node_file_logger,node_tests toneRose
```

## Components

### Runtime & protocol

Bootstrap and MCP-facing boundary

- [Entry point](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/index.ts): stdio bootstrap · Loads config, wires MCP transport, and registers handlers · `src/index.ts`
- [Spot tools](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/tools_spot.ts): mcp tools · MCP tool handlers for spot workflows · `src/mcp/tools_spot.ts`
- [Futures tools](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/tools_futures.ts): mcp tools · MCP tool handlers for futures workflows · `src/mcp/tools_futures.ts`
- [Resources](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/resources.ts): mcp resources · Read-only MCP resource exposure · `src/mcp/resources.ts`
- [Prompts](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/prompts.ts): mcp prompts · Reusable MCP prompt definitions · `src/mcp/prompts.ts`
- [MCP errors](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/errors.ts): protocol errors · Normalizes errors for MCP responses · `src/mcp/errors.ts`
- [MCP logging](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/mcp/logging.ts): telemetry bridge · Logging and request tracing at the protocol boundary · `src/mcp/logging.ts`

### Domain clients

Spot and futures API surfaces

- [Spot public](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/public/PublicClient.ts): spot market client · Unauthenticated spot market data access · `src/public/PublicClient.ts`
- [Spot private](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/private/SpotClient.ts): spot trading client · Authenticated spot trading and account operations · `src/private/SpotClient.ts`
- [Futures public](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/public/PublicFuturesClient.ts): futures market client · Unauthenticated futures market data access · `src/public/PublicFuturesClient.ts`
- [Futures private](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/private/FuturesClient.ts): futures trading client · Authenticated futures trading and account operations · `src/private/FuturesClient.ts`

### Integration core

HTTP, auth, config, and shared response shaping

- [Zebpay API](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/private/ZebpayAPI.ts): api gateway · Central wrapper around Zebpay endpoint families · `src/private/ZebpayAPI.ts`
- [HTTP client](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/http/httpClient.ts): outbound http · Shared request execution, retry, and timeout behavior · `src/http/httpClient.ts`
- [Config](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/config.ts): env config · Centralizes base URLs, credentials, and runtime settings · `src/config.ts`
- [Credentials](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/security/credentials.ts): secret loader · Loads API key and secret from environment · `src/security/credentials.ts`
- [Signing](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/security/signing.ts): request signing · Signs authenticated requests before dispatch · `src/security/signing.ts`

### Support & tests

Cross-cutting utilities and contract tests

- [Validation](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/validation/validators.ts): zod validation · Validates tool inputs before calling Zebpay · `src/validation/validators.ts`
- [Schemas](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/validation/schemas.ts): input schemas · Shared Zod schemas for request shape definitions · `src/validation/schemas.ts`
- [Formatter](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/utils/responseFormatter.ts): response shaping · Standardizes success and error payloads · `src/utils/responseFormatter.ts`
- [Response types](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/types/responses.ts): result models · Shared response and error type definitions · `src/types/responses.ts`
- [Cache](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/utils/cache.ts): utility cache · Short-lived reuse of frequently requested data · `src/utils/cache.ts`
- [Metrics](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/utils/metrics.ts): utility metrics · Operational counters and measurements · `src/utils/metrics.ts`
- [File logger](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/utils/fileLogger.ts): optional logging · Persists logs for local debugging workflows · `src/utils/fileLogger.ts`
- [Contract tests](https://github.com/zebpay/zebpay-mcp-server/blob/main/src/__tests__/validation.test.ts): test suite · Covers errors, prompts, resources, and validation contracts · `src/__tests__/validation.test.ts`

## Connections

- Entry point → Spot tools: registers · Bootstraps spot tool handlers
- Entry point → Futures tools: registers · Bootstraps futures tool handlers
- Entry point → Resources: registers · Exposes read-only resources
- Entry point → Prompts: registers · Exposes reusable prompts
- Entry point → MCP errors: wires · Connects shared error handling
- Entry point → MCP logging: wires · Connects runtime logging
- Spot tools → Validation: validates · Checks tool inputs before execution
- Futures tools → Validation: validates · Checks tool inputs before execution
- Validation → Schemas: uses · Relies on shared schemas
- Spot tools → Spot public: calls · Routes market-data requests to public spot client
- Spot tools → Spot private: calls · Routes authenticated spot operations to private client
- Futures tools → Futures public: calls · Routes market-data requests to public futures client
- Futures tools → Futures private: calls · Routes authenticated futures operations to private client
- Spot public → HTTP client: requests · Executes outbound HTTP calls
- Spot private → Signing: signs · Signs authenticated spot requests
- Spot private → Credentials: loads · Reads API credentials
- Spot private → Zebpay API: uses · Delegates API endpoint composition
- Futures public → HTTP client: requests · Executes outbound HTTP calls
- Futures private → Signing: signs · Signs authenticated futures requests
- Futures private → Credentials: loads · Reads API credentials
- Futures private → Zebpay API: uses · Delegates API endpoint composition
- Zebpay API → HTTP client: dispatches · Uses shared HTTP execution
- Entry point → Config: reads · Initializes runtime from environment config
- Spot public → Config: reads · Uses public base URLs and settings
- Futures public → Config: reads · Uses futures base URLs and settings
- Zebpay API → Config: reads · Uses endpoint and timeout configuration
- Spot tools → Formatter: formats · Shapes protocol-friendly responses
- Futures tools → Formatter: formats · Shapes protocol-friendly responses
- Formatter → Response types: adapts · Maps results into shared response types
- MCP logging → Metrics: records · Emits operational measurements
- MCP logging → File logger: optionally writes · Can persist logs to disk
- Contract tests → Spot tools: covers · Protects MCP spot contracts
- Contract tests → Futures tools: covers · Protects MCP futures contracts
- Contract tests → Validation: covers · Protects validation behavior
- Contract tests → Resources: covers · Protects resource semantics
- Contract tests → Prompts: covers · Protects prompt definitions