@zebpay_rajesh/zebpay-mcp-server 1.0.3

package/.env.example

@@ -0,0 +1,14 @@
+ZEBPAY_API_KEY=
+ZEBPAY_API_SECRET=
+
+# Required runtime configuration (no fallback defaults in code)
+ZEBPAY_SPOT_BASE_URL=https://www.zebapi.com/api/v2
+ZEBPAY_FUTURES_BASE_URL=https://futures-api.zebpay.com/api/v1
+ZEBPAY_MARKET_BASE_URL=https://www.zebapi.com/api/v1/market
+
+MCP_TRANSPORTS=stdio
+LOG_LEVEL=info
+HTTP_TIMEOUT_MS=15000
+HTTP_RETRY_COUNT=2
+
+

package/README.md

@@ -0,0 +1,223 @@
+# Zebpay MCP Server
+
+![AI Trading Made Simple](docs/zebpay-ai-trading-beginner.png)
+
+Production-ready TypeScript **MCP (Model Context Protocol)** server for Zebpay spot and futures APIs, using **stdio transport only**.
+Model Context Protocol (MCP) is a standard way for AI assistants to securely call tools and data sources.
+It is designed for MCP clients like Cursor, Claude Desktop, and MCP Inspector that connect through local process execution.
+The server provides both market-data and trading workflows with strict validation, safe error handling, and developer-friendly observability.
+
+## What This Server Provides
+
+- Public market data tools (spot + futures)
+- Private trading/account tools (requires API credentials)
+- MCP resources and prompts for agent workflows
+- Request validation via Zod
+- Structured error handling and optional file logging
+
+## Features
+
+- Stdio-only MCP server for secure local integration with MCP clients
+- Spot and futures API coverage for both public and authenticated operations
+- HMAC-based authenticated request flow for private endpoints
+- Input validation and normalized MCP error responses
+- Outbound request retries and timeout controls
+- Optional structured file logging for debugging and auditability
+
+## Supported Tools
+
+### Spot (Public + Private)
+
+- Market data: tickers, order book, trades, klines, exchange info, currencies
+- Trading: place market/limit orders, cancel orders, cancel by symbol, cancel all
+- Account: balances, open orders, order history, trade history, exchange fee
+- Example tool names:
+  - `zebpay_public_getTicker`
+  - `zebpay_public_getOrderBook`
+  - `zebpay_spot_placeMarketOrder`
+  - `zebpay_spot_placeLimitOrder`
+  - `zebpay_spot_getBalance`
+
+### Futures (Public + Private)
+
+- Market data: health status, markets, market info, order book, 24h ticker, aggregate trades
+- Trading/account: wallet balance, place order, add/reduce margin, open orders, positions
+- History: order history, linked orders, trade history, transaction history
+- Example tool names:
+  - `zebpay_futures_public_getMarkets`
+  - `zebpay_futures_public_getOrderBook`
+  - `zebpay_futures_placeOrder`
+  - `zebpay_futures_getWalletBalance`
+  - `zebpay_futures_getPositions`
+
+## Tech Stack
+
+- Node.js (ESM)
+- TypeScript
+- `@modelcontextprotocol/sdk`
+- `undici`
+- `zod`
+
+## Project Structure
+
+```text
+src/
+├── index.ts                  # Stdio MCP server entrypoint
+├── mcp/                      # Tools, resources, prompts, MCP errors/logging
+├── private/                  # Authenticated Zebpay clients
+├── public/                   # Public market-data clients
+├── security/                 # Credentials + signing helpers
+├── http/                     # Shared outbound HTTP client to Zebpay APIs
+├── validation/               # Schemas and validation helpers
+├── utils/                    # Caching, metrics, formatting, file logging
+└── types/                    # Shared response types
+```
+
+## Prerequisites
+
+- Node.js 20+
+- npm 9+
+- Zebpay API credentials (for private tools)
+- Create your API key/secret from the official ZebPay API portal: `https://api.zebpay.com/`
+
+## Creating a ZebPay API Key
+
+Use the steps below to generate API credentials for this MCP server:
+
+1. Open the ZebPay API portal: `https://api.zebpay.com/`
+2. Sign in to your ZebPay account.
+3. Go to **API Trading** and click **Create New API Key**.
+4. Enter key details:
+   - key name (for example: `zebpay-mcp-local`)
+   - required permissions (read-only for market/account checks, trading permissions only if needed)
+   - optional IP whitelist (recommended for better security)
+5. Complete OTP verification.
+6. Copy and save:
+   - API Key
+   - Secret Key (shown once)
+
+Then add them to your local `.env` file:
+
+```env
+ZEBPAY_API_KEY=your_api_key
+ZEBPAY_API_SECRET=your_api_secret
+```
+
+Security notes:
+
+- Never commit API keys/secrets to git.
+- Prefer least-privilege API permissions.
+- Rotate keys immediately if exposed.
+
+## Setup
+
+```bash
+git clone <your-repo-url>
+cd zebpay-mcp-server
+npm install
+cp env.example .env
+```
+
+Update `.env` (all values are read from environment; there are no fallback defaults in code):
+
+```env
+ZEBPAY_API_KEY=your_api_key    # Use the API key from the step above
+ZEBPAY_API_SECRET=your_api_secret    # Use the Secret key from the step above
+ZEBPAY_SPOT_BASE_URL=https://sapi.zebpay.com/api/v2
+ZEBPAY_FUTURES_BASE_URL=https://futuresbe.zebpay.com/api/v1
+ZEBPAY_MARKET_BASE_URL=https://www.zebapi.com/api/v1/market
+MCP_TRANSPORTS=stdio
+LOG_LEVEL=info
+HTTP_TIMEOUT_MS=15000
+HTTP_RETRY_COUNT=2
+```
+
+## Build and Run
+
+```bash
+npm run build
+npm start
+```
+
+Optional logging to file:
+
+```bash
+npm run start:log
+```
+
+## MCP Client Configuration (Stdio)
+
+Example MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "zebpay": {
+      "command": "node",
+      "args": [
+          "/absolute/path/to/zebpay-mcp-server/dist/index.js"
+        ],
+      "env": {
+        "ZEBPAY_API_KEY": "YOUR_API_KEY_HERE",
+        "ZEBPAY_API_SECRET": "YOUR_API_SECRET_HERE",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=zebpay&config=eyJjb21tYW5kIjoibm9kZSIsImFyZ3MiOlsiL2Fic29sdXRlL3BhdGgvdG8vemVicGF5LW1jcC1zZXJ2ZXIvZGlzdC9pbmRleC5qcyJdLCJlbnYiOnsiWkVCUEFZX0FQSV9LRVkiOiJZT1VSX0FQSV9LRVlfSEVSRSIsIlpFQlBBWV9BUElfU0VDUkVUIjoiWU9VUl9BUElfU0VDUkVUX0hFUkUiLCJMT0dfTEVWRUwiOiJpbmZvIn19)
+
+Also see: `mcp-config.json.example`.
+
+## Environment Variables
+
+| Variable                  | Required | Description                                    | Example value                           |
+| ------------------------- | -------- | ---------------------------------------------- | --------------------------------------- |
+| `ZEBPAY_API_KEY`          | Yes      | Zebpay API key (required for private tools)    | `YOUR_API_KEY_HERE`                     |
+| `ZEBPAY_API_SECRET`       | Yes      | Zebpay API secret (required for private tools) | `YOUR_API_SECRET_HERE`                  |
+| `MCP_TRANSPORTS`          | Yes      | Must be `stdio`                                | `stdio`                                 |
+| `ZEBPAY_SPOT_BASE_URL`    | Yes      | Spot API base URL                              | `https://www.zebapi.com/api/v2`         |
+| `ZEBPAY_FUTURES_BASE_URL` | Yes      | Futures API base URL                           | `https://futures-api.zebpay.com/api/v1` |
+| `ZEBPAY_MARKET_BASE_URL`  | Yes      | Market API base URL                            | `https://www.zebapi.com/api/v1/market`  |
+| `LOG_LEVEL`               | Yes      | `debug`, `info`, `warn`, `error`               | `info`                                  |
+| `LOG_FILE`                | No       | File path for logs                             | `logs/mcp-server.log`                   |
+| `HTTP_TIMEOUT_MS`         | Yes      | Outbound request timeout (ms)                  | `15000`                                 |
+| `HTTP_RETRY_COUNT`        | Yes      | Retry count for outbound requests              | `2`                                     |
+
+## Developer Commands
+
+```bash
+npm run build
+npm test
+npm run test:watch
+npm run logs
+npm run logs:watch
+npm run logs:errors
+npm run logs:stats
+npm run logs:clear
+```
+
+## Logging
+
+- Log tools and examples: `scripts/README.md`
+- Full logging docs: `docs/LOGGING.md`
+- Keep logs out of git (`logs/` is ignored)
+
+## Issues
+
+Found a bug or want to request a feature?
+
+- Create an issue from the GitHub **Issues** tab for this repository.
+- You can also use direct links after replacing `<your-org>` and `<your-repo>`:
+  - Bug report: `https://github.com/<your-org>/<your-repo>/issues/new?template=bug_report.md`
+  - Feature request: `https://github.com/<your-org>/<your-repo>/issues/new?template=feature_request.md`
+- Include these details for faster triage:
+  - MCP client used (Cursor/Claude Desktop/other)
+  - Node.js version and OS
+  - Minimal reproduction steps
+  - Relevant logs (redact secrets)
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export type TransportKind = "stdio";
+export interface SigningHeaderNames {
+    apiKeyHeader: string;
+    signatureHeader: string;
+    timestampHeader: string;
+}
+export interface AppConfig {
+    spotBaseUrl: string;
+    futuresBaseUrl: string;
+    marketBaseUrl: string;
+    transports: TransportKind[];
+    logLevel: "debug" | "info" | "warn" | "error";
+    logFile?: string;
+    signingHeaders: SigningHeaderNames;
+    timeoutMs: number;
+    retryCount: number;
+}
+export declare function redact(value: string | undefined | null, show?: number): string;
+export declare function getConfig(): AppConfig;

package/dist/config.js

@@ -0,0 +1,81 @@
+/*
+  Centralized configuration loading and validation.
+  Secrets are never logged; use redact() when including values in logs.
+*/
+const SIGNING_HEADERS = {
+    apiKeyHeader: "X-AUTH-APIKEY",
+    signatureHeader: "X-AUTH-SIGNATURE",
+    timestampHeader: "",
+};
+export function redact(value, show = 4) {
+    if (!value)
+        return "<redacted>";
+    if (value.length <= show)
+        return "*".repeat(value.length);
+    return `${value.slice(0, show)}${"*".repeat(Math.max(4, value.length - show))}`;
+}
+function getRequiredEnv(name) {
+    const value = process.env[name];
+    if (value === undefined) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+function parseTransports(input) {
+    const raw = (input ?? "stdio").split(",").map((s) => s.trim()).filter(Boolean);
+    const valid = [];
+    for (const t of raw) {
+        if (t === "stdio")
+            valid.push(t);
+    }
+    if (!valid.length) {
+        throw new Error('Invalid MCP_TRANSPORTS. Only "stdio" is supported.');
+    }
+    return valid;
+}
+function parseLogLevel(input) {
+    if (input === undefined)
+        return "info";
+    if (input === "debug" || input === "info" || input === "warn" || input === "error") {
+        return input;
+    }
+    throw new Error('Invalid LOG_LEVEL. Use one of: "debug", "info", "warn", "error".');
+}
+export function getConfig() {
+    const spotBaseUrl = getRequiredEnv("ZEBPAY_SPOT_BASE_URL");
+    const futuresBaseUrl = getRequiredEnv("ZEBPAY_FUTURES_BASE_URL");
+    const marketBaseUrl = getRequiredEnv("ZEBPAY_MARKET_BASE_URL");
+    const transports = parseTransports(process.env.MCP_TRANSPORTS);
+    const logLevel = parseLogLevel(process.env.LOG_LEVEL);
+    const logFile = process.env.LOG_FILE; // Optional log file path
+    const timeoutMs = Number(process.env.HTTP_TIMEOUT_MS ?? 15000);
+    const retryCount = Number(process.env.HTTP_RETRY_COUNT ?? 2);
+    const signingHeaders = SIGNING_HEADERS;
+    if (!spotBaseUrl.startsWith("http")) {
+        throw new Error("Invalid spot base URL");
+    }
+    if (!futuresBaseUrl.startsWith("http")) {
+        throw new Error("Invalid futures base URL");
+    }
+    if (!marketBaseUrl.startsWith("http")) {
+        throw new Error("Invalid market base URL");
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("Invalid HTTP_TIMEOUT_MS");
+    }
+    if (!Number.isFinite(retryCount) || retryCount < 0) {
+        throw new Error("Invalid HTTP_RETRY_COUNT");
+    }
+    return {
+        spotBaseUrl,
+        futuresBaseUrl,
+        marketBaseUrl,
+        transports,
+        logLevel,
+        logFile,
+        signingHeaders,
+        timeoutMs,
+        retryCount,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/http/httpClient.d.ts

@@ -0,0 +1,40 @@
+export interface HttpRequestOptions {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeoutMs: number;
+    retryCount: number;
+}
+export interface HttpResponse<T = unknown> {
+    status: number;
+    headers: Record<string, string>;
+    data: T;
+}
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly details?: unknown;
+    readonly isHtmlResponse?: boolean;
+    constructor(message: string, status: number, details?: unknown, isHtmlResponse?: boolean);
+}
+export declare class HttpClient {
+    private readonly logLevel;
+    constructor(logLevel?: "debug" | "info" | "warn" | "error");
+    request<T = unknown>(opts: HttpRequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Sanitizes stack traces by removing file paths, keeping only function names and line numbers
+     */
+    private sanitizeStack;
+    /**
+     * Formats response body to be more user-readable
+     */
+    private formatResponseBody;
+    /**
+     * Sanitizes headers to redact sensitive information
+     */
+    private sanitizeHeaders;
+    /**
+     * Sanitizes body to prevent logging huge payloads
+     */
+    private sanitizeBody;
+}