@zebpay_rajesh/zebpay-mcp-server 0.1.0

package/src/security/credentials.ts

@@ -0,0 +1,114 @@
+/*
+  Credential provider abstraction. Current implementation reads from env vars.
+  Secrets are never logged directly; use redact() for any visibility.
+*/
+
+import { redact } from "../config.js";
+
+export interface CredentialsProvider {
+  getApiKey(): string;
+  getSecretKey(): string;
+}
+
+export class EnvCredentialsProvider implements CredentialsProvider {
+  private readonly apiKeyEnv: string;
+  private readonly secretKeyEnv: string;
+
+  constructor(
+    apiKeyEnvName: string = "ZEBPAY_API_KEY",
+    secretKeyEnvName: string = "ZEBPAY_API_SECRET"
+  ) {
+    this.apiKeyEnv = apiKeyEnvName;
+    this.secretKeyEnv = secretKeyEnvName;
+  }
+
+  getApiKey(): string {
+    const value = process.env[this.apiKeyEnv];
+    if (!value) {
+      throw new Error(
+        `Missing API key in env ${this.apiKeyEnv}. Configure securely.`
+      );
+    }
+    return value;
+  }
+
+  getSecretKey(): string {
+    const value = process.env[this.secretKeyEnv];
+    if (!value) {
+      throw new Error(
+        `Missing API secret in env ${this.secretKeyEnv}. Configure securely.`
+      );
+    }
+    return value;
+  }
+
+  /**
+   * Returns safe-to-log shapes for debugging without exposing secrets.
+   */
+  describeRedacted(): { apiKey: string; secretKey: string } {
+    return {
+      apiKey: redact(process.env[this.apiKeyEnv] ?? ""),
+      secretKey: redact(process.env[this.secretKeyEnv] ?? ""),
+    };
+  }
+}
+
+/**
+ * Credentials provider that stores credentials in memory.
+ * Used for accepting credentials from client during initialization.
+ * Credentials are optional - if not provided, authenticated tools will fail with a clear error.
+ */
+export class InMemoryCredentialsProvider implements CredentialsProvider {
+  private apiKey: string | undefined;
+  private secretKey: string | undefined;
+
+  constructor(apiKey?: string, secretKey?: string) {
+    this.apiKey = apiKey;
+    this.secretKey = secretKey;
+  }
+
+  setCredentials(apiKey: string, secretKey: string): void {
+    if (!apiKey || !secretKey) {
+      throw new Error("API key and secret are required.");
+    }
+    this.apiKey = apiKey;
+    this.secretKey = secretKey;
+  }
+
+  getApiKey(): string {
+    if (!this.apiKey) {
+      throw new Error(
+        "API credentials are required for this operation. Please provide ZEBPAY_API_KEY and ZEBPAY_API_SECRET headers or include credentials in initialization params."
+      );
+    }
+    return this.apiKey;
+  }
+
+  getSecretKey(): string {
+    if (!this.secretKey) {
+      throw new Error(
+        "API credentials are required for this operation. Please provide ZEBPAY_API_KEY and ZEBPAY_API_SECRET headers or include credentials in initialization params."
+      );
+    }
+    return this.secretKey;
+  }
+
+  /**
+   * Returns safe-to-log shapes for debugging without exposing secrets.
+   */
+  describeRedacted(): { apiKey: string; secretKey: string } {
+    return {
+      apiKey: redact(this.apiKey),
+      secretKey: redact(this.secretKey),
+    };
+  }
+
+  /**
+   * Check if credentials are set
+   */
+  hasCredentials(): boolean {
+    return !!(this.apiKey && this.secretKey);
+  }
+}
+
+

package/src/security/signing.ts

@@ -0,0 +1,98 @@
+/*
+  HMAC signing utilities for ZebPay.
+  The exact prehash format and header names are configurable via config to match ZebPay docs.
+*/
+
+import crypto from "node:crypto";
+import { SigningHeaderNames } from "../config.js";
+
+export interface SignatureResult {
+  signature: string;
+  timestamp: string;
+}
+
+export interface SigningOptions {
+  headers: SigningHeaderNames;
+  /** If true, include body in prehash; set false for GETs without body. */
+  includeBody?: boolean;
+  /** Allows overriding timestamp for testing. */
+  now?: () => number;
+}
+
+export function stableStringify(value: unknown): string {
+  // Deterministic JSON stringify for signing.
+  return JSON.stringify(value, Object.keys(value as object).sort());
+}
+
+/**
+ * Sign a query string using HMAC-SHA256 (Zebpay API format).
+ * This matches the Postman script format where query parameters are signed directly.
+ */
+export function signQueryString(
+  queryString: string,
+  secretKey: string
+): string {
+  return crypto.createHmac("sha256", secretKey).update(queryString).digest("hex");
+}
+
+/**
+ * Sign a JSON payload string using HMAC-SHA256 (Zebpay API format for POST requests).
+ * This matches the Postman script format where the JSON body string is signed directly.
+ */
+export function signPayloadString(
+  payloadString: string,
+  secretKey: string
+): string {
+  return crypto.createHmac("sha256", secretKey).update(payloadString).digest("hex");
+}
+
+/**
+ * Produce an HMAC-SHA256 signature. Default prehash: `${method}\n${path}\n${timestamp}\n${body}`.
+ */
+export function signRequest(
+  method: string,
+  path: string,
+  body: unknown,
+  secretKey: string,
+  opts: SigningOptions
+): SignatureResult {
+  const timestamp = String((opts.now ? opts.now() : Date.now()));
+  const useBody = opts.includeBody ?? (method.toUpperCase() !== "GET" && body !== undefined && body !== null);
+  const bodyString = useBody ? (typeof body === "string" ? body : stableStringify(body)) : "";
+  const prehash = `${method.toUpperCase()}\n${path}\n${timestamp}\n${bodyString}`;
+  const signature = crypto.createHmac("sha256", secretKey).update(prehash).digest("hex");
+  return { signature, timestamp };
+}
+
+export function buildAuthHeaders(
+  apiKey: string,
+  sig: SignatureResult,
+  headerNames: SigningHeaderNames
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    [headerNames.apiKeyHeader]: apiKey,
+    [headerNames.signatureHeader]: sig.signature,
+  };
+  // Only include timestamp header if it's configured (for non-query-string signing)
+  if (headerNames.timestampHeader) {
+    headers[headerNames.timestampHeader] = sig.timestamp;
+  }
+  return headers;
+}
+
+/**
+ * Build auth headers for query-string based signing (Zebpay format).
+ * Only includes API key and signature headers, no timestamp header.
+ */
+export function buildQueryStringAuthHeaders(
+  apiKey: string,
+  signature: string,
+  headerNames: SigningHeaderNames
+): Record<string, string> {
+  return {
+    [headerNames.apiKeyHeader]: apiKey,
+    [headerNames.signatureHeader]: signature,
+  };
+}
+
+

package/src/types/responses.ts

@@ -0,0 +1,146 @@
+/*
+  TypeScript type definitions for API responses.
+  These help LLMs understand the structure of tool responses.
+*/
+
+/**
+ * Common response structure for order operations
+ */
+export interface OrderResponse {
+  orderId?: string;
+  clientOrderId?: string;
+  symbol: string;
+  side: "buy" | "sell";
+  type: "market" | "limit";
+  quantity: string;
+  price?: string;
+  status: string;
+  executedPrice?: string;
+  executedQuantity?: string;
+  timestamp?: number;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Balance information for a single currency
+ */
+export interface CurrencyBalance {
+  currency: string;
+  available: string;
+  locked?: string;
+  total?: string;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Balance response structure
+ */
+export interface BalanceResponse {
+  balances?: CurrencyBalance[];
+  currencies?: Record<string, CurrencyBalance>;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Ticker information for a trading pair
+ */
+export interface TickerResponse {
+  symbol: string;
+  lastPrice: string;
+  bidPrice?: string;
+  askPrice?: string;
+  high24h?: string;
+  low24h?: string;
+  volume24h?: string;
+  priceChange24h?: string;
+  priceChangePercent24h?: string;
+  timestamp?: number;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Order book entry
+ */
+export interface OrderBookEntry {
+  price: string;
+  quantity: string;
+}
+
+/**
+ * Order book response
+ */
+export interface OrderBookResponse {
+  symbol: string;
+  bids: OrderBookEntry[];
+  asks: OrderBookEntry[];
+  timestamp?: number;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Trade information
+ */
+export interface TradeResponse {
+  symbol: string;
+  price: string;
+  quantity: string;
+  side: "buy" | "sell";
+  timestamp: number;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Kline/Candlestick data
+ */
+export interface KlineResponse {
+  openTime: number;
+  open: string;
+  high: string;
+  low: string;
+  close: string;
+  volume: string;
+  closeTime: number;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Exchange information
+ */
+export interface ExchangeInfoResponse {
+  symbols?: Array<{
+    symbol: string;
+    baseAsset: string;
+    quoteAsset: string;
+    status: string;
+    [key: string]: unknown;
+  }>;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Currency information
+ */
+export interface CurrencyInfo {
+  currency: string;
+  name?: string;
+  fullName?: string;
+  precision?: number;
+  type?: string;
+  chains?: Array<{
+    chainName: string;
+    withdrawalFee?: string;
+    depositMinSize?: string;
+    withdrawalMinSize?: string;
+    [key: string]: unknown;
+  }>;
+  [key: string]: unknown; // Allow additional fields from API
+}
+
+/**
+ * Currencies response
+ */
+export interface CurrenciesResponse {
+  currencies?: CurrencyInfo[];
+  [key: string]: unknown; // Allow additional fields from API
+}
+

package/src/utils/cache.ts

@@ -0,0 +1,90 @@
+/*
+  Simple in-memory cache for public endpoints to reduce API calls.
+*/
+
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  ttl: number;
+}
+
+export class SimpleCache<T = unknown> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private defaultTtl: number;
+
+  constructor(defaultTtlMs: number = 5000) {
+    this.defaultTtl = defaultTtlMs;
+  }
+
+  /**
+   * Get cached value if not expired
+   */
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return null;
+    }
+
+    const now = Date.now();
+    if (now - entry.timestamp > entry.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  /**
+   * Set cached value with optional TTL
+   */
+  set(key: string, data: T, ttlMs?: number): void {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      ttl: ttlMs || this.defaultTtl,
+    });
+  }
+
+  /**
+   * Clear expired entries
+   */
+  clearExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now - entry.timestamp > entry.ttl) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache size
+   */
+  size(): number {
+    return this.cache.size;
+  }
+}
+
+// Cache instances for different endpoint types
+export const tickerCache = new SimpleCache(5000); // 5 seconds for tickers
+export const orderBookCache = new SimpleCache(2000); // 2 seconds for order books
+export const exchangeInfoCache = new SimpleCache(60000); // 1 minute for exchange info
+export const currenciesCache = new SimpleCache(300000); // 5 minutes for currencies
+
+// Clean up expired entries periodically
+if (typeof setInterval !== "undefined") {
+  setInterval(() => {
+    tickerCache.clearExpired();
+    orderBookCache.clearExpired();
+    exchangeInfoCache.clearExpired();
+    currenciesCache.clearExpired();
+  }, 10000); // Clean every 10 seconds
+}
+

package/src/utils/fileLogger.ts

@@ -0,0 +1,88 @@
+/*
+  File logging utility for writing logs to both console and file.
+*/
+
+import { createWriteStream, WriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+class FileLogger {
+  private stream: WriteStream | null = null;
+  private logPath: string | null = null;
+
+  async initialize(logPath?: string): Promise<void> {
+    if (!logPath) {
+      // Default log path
+      this.logPath = null;
+      return;
+    }
+
+    try {
+      // Ensure log directory exists
+      const logDir = dirname(logPath);
+      await mkdir(logDir, { recursive: true });
+      
+      // Create write stream in append mode
+      this.stream = createWriteStream(logPath, { flags: "a" });
+      this.logPath = logPath;
+      
+      // Write initial log entry
+      this.writeToFile(JSON.stringify({
+        level: "info",
+        type: "log_init",
+        timestamp: new Date().toISOString(),
+        message: `Logging initialized to file: ${logPath}`,
+      }) + "\n");
+    } catch (error) {
+      console.error(JSON.stringify({
+        level: "error",
+        type: "log_init_error",
+        timestamp: new Date().toISOString(),
+        error: error instanceof Error ? error.message : String(error),
+      }));
+      // Continue without file logging if file can't be opened
+      this.stream = null;
+      this.logPath = null;
+    }
+  }
+
+  log(message: string): void {
+    // Always write to console.error
+    console.error(message);
+    
+    // Also write to file if initialized
+    if (this.stream) {
+      this.writeToFile(message + "\n");
+    }
+  }
+
+  private writeToFile(message: string): void {
+    if (this.stream) {
+      try {
+        this.stream.write(message);
+      } catch (error) {
+        // If file write fails, log to console but don't crash
+        console.error(JSON.stringify({
+          level: "error",
+          type: "log_write_error",
+          timestamp: new Date().toISOString(),
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.stream) {
+      return new Promise((resolve) => {
+        this.stream!.end(() => {
+          this.stream = null;
+          resolve();
+        });
+      });
+    }
+  }
+}
+
+export const fileLogger = new FileLogger();
+

package/src/utils/metrics.ts

@@ -0,0 +1,135 @@
+/*
+  Basic metrics collection for monitoring tool usage and performance.
+*/
+
+interface Metric {
+  toolName: string;
+  timestamp: number;
+  durationMs: number;
+  success: boolean;
+  errorType?: string;
+}
+
+class MetricsCollector {
+  private metrics: Metric[] = [];
+  private maxMetrics = 1000; // Keep last 1000 metrics
+
+  record(
+    toolName: string,
+    durationMs: number,
+    success: boolean,
+    errorType?: string
+  ): void {
+    this.metrics.push({
+      toolName,
+      timestamp: Date.now(),
+      durationMs,
+      success,
+      errorType,
+    });
+
+    // Keep only last N metrics
+    if (this.metrics.length > this.maxMetrics) {
+      this.metrics = this.metrics.slice(-this.maxMetrics);
+    }
+  }
+
+  /**
+   * Get metrics summary for a tool
+   */
+  getToolStats(toolName: string, timeWindowMs?: number): {
+    count: number;
+    successCount: number;
+    errorCount: number;
+    avgDurationMs: number;
+    minDurationMs: number;
+    maxDurationMs: number;
+  } {
+    const now = Date.now();
+    const window = timeWindowMs || Infinity;
+    const relevant = this.metrics.filter(
+      (m) =>
+        m.toolName === toolName && now - m.timestamp < window
+    );
+
+    if (relevant.length === 0) {
+      return {
+        count: 0,
+        successCount: 0,
+        errorCount: 0,
+        avgDurationMs: 0,
+        minDurationMs: 0,
+        maxDurationMs: 0,
+      };
+    }
+
+    const successCount = relevant.filter((m) => m.success).length;
+    const durations = relevant.map((m) => m.durationMs);
+    const sum = durations.reduce((a, b) => a + b, 0);
+
+    return {
+      count: relevant.length,
+      successCount,
+      errorCount: relevant.length - successCount,
+      avgDurationMs: sum / relevant.length,
+      minDurationMs: Math.min(...durations),
+      maxDurationMs: Math.max(...durations),
+    };
+  }
+
+  /**
+   * Get all tool names
+   */
+  getToolNames(): string[] {
+    return Array.from(new Set(this.metrics.map((m) => m.toolName)));
+  }
+
+  /**
+   * Get overall stats
+   */
+  getOverallStats(timeWindowMs?: number): {
+    totalRequests: number;
+    successRate: number;
+    avgDurationMs: number;
+    toolStats: Record<string, ReturnType<MetricsCollector["getToolStats"]>>;
+  } {
+    const now = Date.now();
+    const window = timeWindowMs || Infinity;
+    const relevant = this.metrics.filter((m) => now - m.timestamp < window);
+
+    if (relevant.length === 0) {
+      return {
+        totalRequests: 0,
+        successRate: 0,
+        avgDurationMs: 0,
+        toolStats: {},
+      };
+    }
+
+    const successCount = relevant.filter((m) => m.success).length;
+    const durations = relevant.map((m) => m.durationMs);
+    const sum = durations.reduce((a, b) => a + b, 0);
+
+    const toolStats: Record<string, ReturnType<typeof this.getToolStats>> = {};
+    for (const toolName of this.getToolNames()) {
+      toolStats[toolName] = this.getToolStats(toolName, timeWindowMs);
+    }
+
+    return {
+      totalRequests: relevant.length,
+      successRate: successCount / relevant.length,
+      avgDurationMs: sum / relevant.length,
+      toolStats,
+    };
+  }
+
+  /**
+   * Clear all metrics
+   */
+  clear(): void {
+    this.metrics = [];
+  }
+}
+
+export const metricsCollector = new MetricsCollector();
+