@zebpay_rajesh/zebpay-mcp-server 0.1.0

package/src/__tests__/validation.test.ts

@@ -0,0 +1,88 @@
+/*
+  Basic test setup for ZebPay MCP Server
+  Note: Install jest dependencies first: npm install --save-dev jest @types/jest ts-jest
+  Then run: npm test
+*/
+
+import { validateSymbol, validateQuantity } from "../validation/validators.js";
+import { createInvalidParamsError } from "../mcp/errors.js";
+
+// Basic test suite (requires jest to be installed)
+describe("Validation", () => {
+  describe("validateSymbol", () => {
+    it("should accept valid symbols", () => {
+      expect(() => validateSymbol("BTC-INR")).not.toThrow();
+      expect(() => validateSymbol("ETH-INR")).not.toThrow();
+      expect(() => validateSymbol("BTC-USDT")).not.toThrow();
+    });
+
+    it("should reject invalid symbols", () => {
+      expect(() => validateSymbol("BTCINR")).toThrow();
+      expect(() => validateSymbol("BTC/INR")).toThrow();
+      // Note: "btc-inr" is converted to uppercase and becomes valid "BTC-INR"
+      // So we test with a symbol that's invalid even after conversion
+      expect(() => validateSymbol("")).toThrow();
+      expect(() => validateSymbol("BTC-INR-EXTRA")).toThrow(); // Too many parts
+    });
+
+    it("should accept lowercase symbols (converts to uppercase)", () => {
+      // The function converts to uppercase, so lowercase should work
+      expect(() => validateSymbol("btc-inr")).not.toThrow();
+      expect(() => validateSymbol("eth-inr")).not.toThrow();
+    });
+  });
+
+  describe("validateQuantity", () => {
+    it("should accept valid quantities", () => {
+      expect(() => validateQuantity("0.001")).not.toThrow();
+      expect(() => validateQuantity("100")).not.toThrow();
+      expect(() => validateQuantity("0.5")).not.toThrow();
+    });
+
+    it("should reject invalid quantities", () => {
+      expect(() => validateQuantity("")).toThrow();
+      expect(() => validateQuantity("0")).toThrow();
+      expect(() => validateQuantity("-1")).toThrow();
+      expect(() => validateQuantity("abc")).toThrow();
+    });
+  });
+});
+
+describe("Error Handling", () => {
+  it("should create invalid params error with correct code", () => {
+    const error = createInvalidParamsError("Test error");
+    // Note: These assertions require jest to be installed
+    // expect(error).toBeInstanceOf(Error);
+    // expect(error.code).toBe(-32602);
+    // expect(error.message).toBe("Test error");
+    
+    // Basic validation without jest
+    if (!(error instanceof Error)) {
+      throw new Error("Expected error to be instance of Error");
+    }
+    if (error.code !== -32602) {
+      throw new Error(`Expected error code -32602, got ${error.code}`);
+    }
+    // MCP error messages include code prefix: "MCP error -32602: <message>"
+    if (!error.message.includes("Test error")) {
+      throw new Error(`Expected error message to contain "Test error", got "${error.message}"`);
+    }
+  });
+});
+
+// Helper functions for tests (if jest is not available, these provide basic functionality)
+declare global {
+  function describe(name: string, fn: () => void): void;
+  function it(name: string, fn: () => void): void;
+  function expect(fn: () => void): {
+    not: { toThrow: () => void };
+    toThrow: () => void;
+  };
+  function expect<T>(value: T): {
+    toBeInstanceOf: (constructor: new (...args: any[]) => T) => void;
+    toBe: (expected: T) => void;
+  };
+}
+
+
+

package/src/config.ts

@@ -0,0 +1,108 @@
+/*
+  Centralized configuration loading and validation.
+  Secrets are never logged; use redact() when including values in logs.
+*/
+
+export type TransportKind = "stdio";
+
+export interface SigningHeaderNames {
+  apiKeyHeader: string;
+  signatureHeader: string;
+  timestampHeader: string;
+}
+
+const SIGNING_HEADERS: SigningHeaderNames = {
+  apiKeyHeader: "X-AUTH-APIKEY",
+  signatureHeader: "X-AUTH-SIGNATURE",
+  timestampHeader: "",
+};
+
+export interface AppConfig {
+  spotBaseUrl: string;
+  futuresBaseUrl: string;
+  marketBaseUrl: string;
+  transports: TransportKind[];
+  logLevel: "debug" | "info" | "warn" | "error";
+  logFile?: string; // Optional log file path
+  signingHeaders: SigningHeaderNames;
+  timeoutMs: number;
+  retryCount: number;
+}
+
+export function redact(value: string | undefined | null, show: number = 4): string {
+  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: string): string {
+  const value = process.env[name];
+  if (value === undefined) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+function parseTransports(input: string | undefined): TransportKind[] {
+  const raw = (input ?? "stdio").split(",").map((s) => s.trim()).filter(Boolean);
+  const valid: TransportKind[] = [];
+  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: string | undefined): AppConfig["logLevel"] {
+  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(): AppConfig {
+  const spotBaseUrl = getRequiredEnv("ZEBPAY_SPOT_BASE_URL") || 'https://www.zebapi.com/api/v2';
+  const futuresBaseUrl = getRequiredEnv("ZEBPAY_FUTURES_BASE_URL") || 'https://futures-api.zebpay.com/api/v1';
+  const marketBaseUrl = getRequiredEnv("ZEBPAY_MARKET_BASE_URL") || 'https://www.zebapi.com/api/v1/market';
+  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: SigningHeaderNames = 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,
+  };
+}
+
+

package/src/http/httpClient.ts

@@ -0,0 +1,398 @@
+/*
+  Minimal HTTP client with retries, timeout, structured errors, and redacted logs.
+*/
+
+import { setTimeout as delay } from "node:timers/promises";
+import { redact } from "../config.js";
+import { fetch } from "undici";
+import { fileLogger } from "../utils/fileLogger.js";
+
+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 class HttpError extends Error {
+  public readonly status: number;
+  public readonly details?: unknown;
+  public readonly isHtmlResponse?: boolean;
+  constructor(message: string, status: number, details?: unknown, isHtmlResponse?: boolean) {
+    super(message);
+    this.status = status;
+    this.details = details;
+    this.isHtmlResponse = isHtmlResponse;
+  }
+}
+
+/**
+ * Parses HTML error pages (like Cloudflare) to extract user-friendly error messages.
+ * 
+ * NOTE: This is transport-agnostic - it parses responses from Zebpay API (external),
+ * not from MCP clients. Works identically for both stdio and HTTP transports.
+ */
+function parseHtmlError(html: string): string | null {
+  if (!html || typeof html !== "string") {
+    return null;
+  }
+
+  // Check if it's HTML
+  if (!html.trim().toLowerCase().startsWith("<!doctype") && !html.trim().toLowerCase().startsWith("<html")) {
+    return null;
+  }
+
+  // Extract Cloudflare error messages
+  const cloudflarePatterns = [
+    // Cloudflare Error 1006 - Access denied
+    /<h2[^>]*>Access denied<\/h2>/i,
+    /The owner of this website.*?has banned your IP address[^<]*/i,
+    /<p[^>]*>The owner of this website[^<]*<\/p>/i,
+    // Cloudflare Error 1020 - Access denied
+    /<h1[^>]*>Error[^<]*<\/h1>/i,
+    // Generic error extraction from title
+    /<title>([^<]+)<\/title>/i,
+    // Extract error messages from h1/h2 tags
+    /<h[12][^>]*>([^<]+)<\/h[12]>/i,
+  ];
+
+  for (const pattern of cloudflarePatterns) {
+    const match = html.match(pattern);
+    if (match) {
+      let message = match[1] || match[0];
+      // Clean up HTML entities and tags
+      message = message
+        .replace(/<[^>]+>/g, "")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/\s+/g, " ")
+        .trim();
+
+      if (message && message.length > 10) {
+        // Check for IP ban message
+        if (html.includes("banned your IP address")) {
+          const ipMatch = html.match(/IP address[^<]*\(([^)]+)\)/i);
+          if (ipMatch) {
+            return `Access denied: Your IP address has been banned by the website. Please contact support or try again later.`;
+          }
+          return `Access denied: Your IP address has been restricted. Please contact support or try again later.`;
+        }
+
+        // Check for Cloudflare error codes
+        const errorCodeMatch = html.match(/Error\s*(\d+)/i);
+        if (errorCodeMatch) {
+          const errorCode = errorCodeMatch[1];
+          if (errorCode === "1006") {
+            return `Access denied (Error 1006): Your IP address has been banned. Please contact support or try again later.`;
+          }
+          return `Cloudflare error (${errorCode}): ${message}`;
+        }
+
+        return message;
+      }
+    }
+  }
+
+  // Fallback: try to extract any meaningful text
+  const textMatch = html.match(/<body[^>]*>([\s\S]{100,500})<\/body>/i);
+  if (textMatch) {
+    let text = textMatch[1]
+      .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+      .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+      .replace(/<[^>]+>/g, " ")
+      .replace(/\s+/g, " ")
+      .trim();
+
+    if (text.length > 20 && text.length < 200) {
+      return text;
+    }
+  }
+
+  return null;
+}
+
+export class HttpClient {
+  constructor(private readonly logLevel: "debug" | "info" | "warn" | "error" = "info") {}
+
+  async request<T = unknown>(opts: HttpRequestOptions): Promise<HttpResponse<T>> {
+    const { method, url, headers = {}, body, timeoutMs, retryCount } = opts;
+    const isIdempotent = method.toUpperCase() === "GET";
+    const maxAttempts = isIdempotent ? retryCount + 1 : 1;
+
+    const payload = body === undefined || body === null ? undefined : (typeof body === "string" ? body : JSON.stringify(body));
+    
+    // Prepare headers for request (with content-type)
+    const requestHeaders: Record<string, string> = {
+      ...headers,
+    };
+    if (payload) {
+      requestHeaders["content-type"] = "application/json";
+    }
+
+    // Log HTTP request
+    const requestTimestamp = new Date().toISOString();
+    const requestLogMessage = JSON.stringify({
+      level: "info",
+      type: "http_request",
+      timestamp: requestTimestamp,
+      method: method.toUpperCase(),
+      url,
+      headers: this.sanitizeHeaders(requestHeaders),
+      body: this.sanitizeBody(payload),
+    });
+    fileLogger.log(requestLogMessage);
+
+    let attempt = 0;
+    let lastError: unknown;
+    while (attempt < maxAttempts) {
+      attempt++;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      const attemptStartTime = Date.now();
+      try {
+        const res = await fetch(url, {
+          method,
+          headers: requestHeaders,
+          body: payload,
+          signal: controller.signal,
+        } as any);
+        clearTimeout(timer);
+
+        const text = await res.text();
+        const contentType = res.headers.get("content-type") || "";
+        const isHtml = contentType.includes("text/html") || text.trim().toLowerCase().startsWith("<!doctype") || text.trim().toLowerCase().startsWith("<html");
+        
+        let data: any = undefined;
+        let parsedError: string | null = null;
+        
+        if (isHtml && !res.ok) {
+          // Try to parse HTML error page
+          parsedError = parseHtmlError(text);
+          data = text; // Keep original HTML for logging
+        } else {
+          // Try to parse as JSON
+          try {
+            data = text ? JSON.parse(text) : undefined;
+          } catch {
+            data = text;
+          }
+        }
+
+        const response: HttpResponse<T> = {
+          status: res.status,
+          headers: Object.fromEntries(res.headers.entries()),
+          data,
+        };
+
+        const durationMs = Date.now() - attemptStartTime;
+        
+        // Log HTTP response with user-readable format
+        const responseTimestamp = new Date().toISOString();
+        const responseBody = this.formatResponseBody(data, res.status);
+        
+        const responseLogMessage = JSON.stringify({
+          level: res.ok ? "info" : "warn",
+          type: "http_response",
+          timestamp: responseTimestamp,
+          method: method.toUpperCase(),
+          url,
+          status: res.status,
+          headers: this.sanitizeHeaders(response.headers),
+          body: responseBody,
+          durationMs,
+          attempt,
+          isHtmlResponse: isHtml,
+        });
+        fileLogger.log(responseLogMessage);
+
+        if (res.ok) {
+          return response;
+        }
+
+        // Retry on 429/5xx when idempotent
+        if (isIdempotent && (res.status === 429 || (res.status >= 500 && res.status < 600)) && attempt < maxAttempts) {
+          const retryAfter = Number(response.headers["retry-after"] || 0);
+          const backoffMs = retryAfter > 0 ? retryAfter * 1000 : 250 * attempt;
+          await delay(backoffMs);
+          continue;
+        }
+
+        // Use parsed error message if available, otherwise use default
+        const errorMessage = parsedError || `HTTP ${res.status}`;
+        throw new HttpError(errorMessage, res.status, data, isHtml);
+      } catch (err) {
+        clearTimeout(timer);
+        lastError = err;
+        const durationMs = Date.now() - attemptStartTime;
+        
+        // AbortError or network error
+        if (attempt >= maxAttempts) {
+          // Log HTTP error
+          const errorTimestamp = new Date().toISOString();
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          const errorStack = err instanceof Error ? err.stack : undefined;
+          
+          const errorLogMessage = JSON.stringify({
+            level: "error",
+            type: "http_error",
+            timestamp: errorTimestamp,
+            method: method.toUpperCase(),
+            url,
+            headers: this.sanitizeHeaders(requestHeaders),
+            body: this.sanitizeBody(payload),
+            durationMs,
+            attempt,
+            error: errorMessage,
+            stack: this.sanitizeStack(errorStack),
+          });
+          fileLogger.log(errorLogMessage);
+          
+          if (err instanceof HttpError) throw err;
+          throw new HttpError((err as Error).message || "Network error", 0);
+        }
+        await delay(200 * attempt);
+      }
+    }
+
+    throw lastError instanceof Error ? lastError : new Error("Unknown HTTP error");
+  }
+
+  /**
+   * Sanitizes stack traces by removing file paths, keeping only function names and line numbers
+   */
+  private sanitizeStack(stack: string | undefined): string | undefined {
+    if (!stack) return undefined;
+    
+    try {
+      // Remove file:// URLs and absolute paths, keep only filename and line numbers
+      const lines = stack.split('\n');
+      const sanitizedLines = lines.map(line => {
+        let sanitized = line;
+        
+        // Remove file:// URLs (e.g., file:///Users/path/to/file.js:123:45)
+        sanitized = sanitized.replace(/file:\/\/\/[^\s\)]+/g, (match) => {
+          // Extract just the filename and line numbers
+          const filenameMatch = match.match(/([^\/]+\.(js|ts|mjs|cjs)):(\d+):(\d+)/);
+          if (filenameMatch) {
+            return `${filenameMatch[1]}:${filenameMatch[3]}:${filenameMatch[4]}`;
+          }
+          return '';
+        });
+        
+        // Remove absolute paths (e.g., /Users/path/to/file.js:123:45)
+        sanitized = sanitized.replace(/\/(?:[^\/\s]+\/)+([^\/\s]+\.(js|ts|mjs|cjs)):(\d+):(\d+)/g, '$1:$3:$4');
+        
+        // Simplify node_modules paths (e.g., node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js)
+        sanitized = sanitized.replace(/node_modules\/([^\/\s]+)\/[^\s\)]+/g, 'node_modules/$1');
+        
+        return sanitized.trim();
+      });
+      
+      return sanitizedLines.join('\n');
+    } catch {
+      // If sanitization fails, return a minimal version without paths
+      return stack.split('\n').slice(0, 3).join('\n'); // Keep only first 3 lines
+    }
+  }
+
+  /**
+   * Formats response body to be more user-readable
+   */
+  private formatResponseBody(body: unknown, status: number): unknown {
+    if (body === undefined || body === null) {
+      return body;
+    }
+    
+    // For error responses, extract meaningful information
+    if (status >= 400 && typeof body === "object" && body !== null) {
+      const bodyObj = body as Record<string, unknown>;
+      const formatted: Record<string, unknown> = {};
+      
+      // Extract common error fields
+      if (typeof bodyObj.statusCode === "number") {
+        formatted.statusCode = bodyObj.statusCode;
+      }
+      if (typeof bodyObj.statusDescription === "string") {
+        formatted.statusDescription = bodyObj.statusDescription;
+      }
+      if (typeof bodyObj.error === "string") {
+        formatted.error = bodyObj.error;
+      }
+      if (typeof bodyObj.message === "string") {
+        formatted.message = bodyObj.message;
+      }
+      
+      // Include data if present
+      if (bodyObj.data !== undefined) {
+        formatted.data = bodyObj.data;
+      }
+      
+      // If we extracted meaningful fields, return formatted version
+      if (Object.keys(formatted).length > 0) {
+        return formatted;
+      }
+    }
+    
+    // For non-error responses or if formatting didn't extract anything, use sanitized body
+    return this.sanitizeBody(body);
+  }
+
+  /**
+   * Sanitizes headers to redact sensitive information
+   */
+  private sanitizeHeaders(headers: Record<string, string | undefined>): Record<string, string> {
+    const sanitized: Record<string, string> = {};
+    const sensitiveKeys = ["key", "sign", "secret", "password", "token", "authorization", "auth"];
+    
+    for (const [key, value] of Object.entries(headers)) {
+      if (value === undefined) continue;
+      const lowerKey = key.toLowerCase();
+      if (sensitiveKeys.some((sk) => lowerKey.includes(sk))) {
+        sanitized[key] = redact(value);
+      } else {
+        sanitized[key] = value;
+      }
+    }
+    
+    return sanitized;
+  }
+
+  /**
+   * Sanitizes body to prevent logging huge payloads
+   */
+  private sanitizeBody(body: unknown): unknown {
+    if (body === undefined || body === null) {
+      return body;
+    }
+    
+    // If body is a string, check size
+    if (typeof body === "string") {
+      if (body.length > 5000) {
+        return body.substring(0, 5000) + "... [truncated]";
+      }
+      return body;
+    }
+    
+    // If body is an object, stringify and check size
+    try {
+      const jsonStr = JSON.stringify(body);
+      if (jsonStr.length > 5000) {
+        return JSON.parse(jsonStr.substring(0, 5000) + '..."}');
+      }
+      return body;
+    } catch {
+      return body;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+import { config as dotenvConfig } from "dotenv";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { getConfig } from "./config.js";
+import { EnvCredentialsProvider } from "./security/credentials.js";
+import { HttpClient } from "./http/httpClient.js";
+import { ZebpayAPI } from "./private/ZebpayAPI.js";
+import { SpotClient } from "./private/SpotClient.js";
+import { FuturesClient } from "./private/FuturesClient.js";
+import { PublicClient } from "./public/PublicClient.js";
+import { PublicFuturesClient } from "./public/PublicFuturesClient.js";
+import { registerSpotTools } from "./mcp/tools_spot.js";
+import { registerFuturesTools } from "./mcp/tools_futures.js";
+import { registerResources } from "./mcp/resources.js";
+import { registerPrompts } from "./mcp/prompts.js";
+import { fileLogger } from "./utils/fileLogger.js";
+
+dotenvConfig();
+
+function createServer(): McpServer {
+  return new McpServer(
+    {
+      name: "zebpay",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+        logging: {},
+        resources: {},
+        prompts: {},
+      },
+    }
+  );
+}
+
+async function main(): Promise<void> {
+  const cfg = getConfig();
+  if (cfg.logFile) {
+    await fileLogger.initialize(cfg.logFile);
+  }
+
+  const creds = new EnvCredentialsProvider();
+  const http = new HttpClient(cfg.logLevel);
+  const api = new ZebpayAPI(cfg, creds, http);
+  const spot = new SpotClient(api);
+  const futuresPrivateClient = new FuturesClient(api);
+  const publicClient = new PublicClient(cfg, http);
+  const futuresPublicClient = new PublicFuturesClient(cfg, http);
+
+  const mcp = createServer();
+  registerSpotTools(mcp, spot, publicClient, cfg);
+  registerFuturesTools(mcp, futuresPublicClient, futuresPrivateClient, cfg);
+  registerResources(mcp, publicClient, spot, cfg);
+  registerPrompts(mcp, spot, publicClient, cfg);
+
+  const transport = new StdioServerTransport();
+  await mcp.connect(transport);
+
+  process.on("SIGINT", async () => {
+    await fileLogger.close();
+    process.exit(0);
+  });
+}
+
+main().catch(async (error) => {
+  console.error("FATAL: Failed to start Zebpay MCP stdio server", error);
+  await fileLogger.close();
+  process.exit(1);
+});