zebpay/zebpay-mcp-server

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.