@zebpay_rajesh/zebpay-mcp-server 0.1.0

package/src/utils/responseFormatter.ts

@@ -0,0 +1,361 @@
+/*
+  Response formatting utilities for better LLM parsing and understanding.
+*/
+
+import { randomUUID } from "node:crypto";
+
+/**
+ * Generates a correlation ID for request tracing
+ */
+export function generateCorrelationId(): string {
+  return randomUUID();
+}
+
+/**
+ * Formats API response for better LLM understanding
+ */
+export function formatResponse(
+  data: unknown,
+  metadata?: {
+    toolName?: string;
+    correlationId?: string;
+    executionTimeMs?: number;
+    timestamp?: string;
+  }
+): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  const timestamp = metadata?.timestamp || new Date().toISOString();
+  const response: Record<string, unknown> = {
+    data,
+    ...(metadata?.correlationId && { correlationId: metadata.correlationId }),
+    ...(metadata?.executionTimeMs !== undefined && { executionTimeMs: metadata.executionTimeMs }),
+    timestamp,
+  };
+
+  // Format response text with metadata
+  let text = JSON.stringify(data, null, 2);
+  
+  // Add metadata as comments for LLM context
+  if (metadata?.correlationId || metadata?.executionTimeMs !== undefined) {
+    const metadataLines: string[] = [];
+    if (metadata.correlationId) {
+      metadataLines.push(`// Request ID: ${metadata.correlationId}`);
+    }
+    if (metadata.executionTimeMs !== undefined) {
+      metadataLines.push(`// Execution time: ${metadata.executionTimeMs}ms`);
+    }
+    if (metadata.toolName) {
+      metadataLines.push(`// Tool: ${metadata.toolName}`);
+    }
+    text = metadataLines.join("\n") + "\n" + text;
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+  };
+}
+
+/**
+ * Formats balance response for better readability
+ */
+export function formatBalanceResponse(
+  data: unknown,
+  metadata?: {
+    correlationId?: string;
+    executionTimeMs?: number;
+  }
+): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  const response = formatResponse(data, metadata);
+  
+  // If data is a balance response, add a summary
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>;
+    if (obj.balances || obj.currencies) {
+      let summary = "## Balance Summary\n\n";
+      
+      if (Array.isArray(obj.balances)) {
+        summary += "Available balances:\n";
+        for (const balance of obj.balances) {
+          if (balance && typeof balance === "object") {
+            const bal = balance as Record<string, unknown>;
+            const currency = bal.currency || bal.asset || "Unknown";
+            const available = bal.available || bal.free || "0";
+            const locked = bal.locked || "0";
+            summary += `- ${currency}: ${available} available${locked !== "0" ? `, ${locked} locked` : ""}\n`;
+          }
+        }
+      } else if (obj.currencies && typeof obj.currencies === "object") {
+        summary += "Available balances:\n";
+        for (const [currency, balance] of Object.entries(obj.currencies)) {
+          if (balance && typeof balance === "object") {
+            const bal = balance as Record<string, unknown>;
+            const available = bal.available || bal.free || "0";
+            const locked = bal.locked || "0";
+            summary += `- ${currency}: ${available} available${locked !== "0" ? `, ${locked} locked` : ""}\n`;
+          }
+        }
+      }
+      
+      summary += "\n---\n\n";
+      response.content[0].text = summary + response.content[0].text;
+    }
+  }
+  
+  return response;
+}
+
+/**
+ * Formats ticker response for better readability
+ */
+export function formatTickerResponse(
+  data: unknown,
+  metadata?: {
+    correlationId?: string;
+    executionTimeMs?: number;
+  }
+): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  const response = formatResponse(data, metadata);
+  
+  // If data is a ticker response, add a summary
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>;
+    if (obj.lastPrice || obj.price) {
+      let summary = "## Price Information\n\n";
+      const symbol = obj.symbol || "Unknown";
+      const price = obj.lastPrice || obj.price || "N/A";
+      const change24h = obj.priceChange24h || obj.change24h;
+      const changePercent24h = obj.priceChangePercent24h || obj.changePercent24h;
+      
+      summary += `**Symbol:** ${symbol}\n`;
+      summary += `**Current Price:** ${price}\n`;
+      if (change24h) {
+        summary += `**24h Change:** ${change24h}`;
+        if (changePercent24h) {
+          summary += ` (${changePercent24h}%)`;
+        }
+        summary += "\n";
+      }
+      if (obj.volume24h) {
+        summary += `**24h Volume:** ${obj.volume24h}\n`;
+      }
+      
+      summary += "\n---\n\n";
+      response.content[0].text = summary + response.content[0].text;
+    }
+  }
+  
+  return response;
+}
+
+/**
+ * Formats order response for better readability
+ */
+export function formatOrderResponse(
+  data: unknown,
+  metadata?: {
+    correlationId?: string;
+    executionTimeMs?: number;
+  }
+): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  const response = formatResponse(data, metadata);
+  
+  // If data is an order response, add a summary
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>;
+    if (obj.orderId || obj.clientOrderId || obj.symbol) {
+      let summary = "## Order Status\n\n";
+      
+      if (obj.orderId) summary += `**Order ID:** ${obj.orderId}\n`;
+      if (obj.clientOrderId) summary += `**Client Order ID:** ${obj.clientOrderId}\n`;
+      if (obj.symbol) summary += `**Symbol:** ${obj.symbol}\n`;
+      if (obj.side) summary += `**Side:** ${obj.side}\n`;
+      if (obj.status) summary += `**Status:** ${obj.status}\n`;
+      if (obj.executedPrice) summary += `**Executed Price:** ${obj.executedPrice}\n`;
+      if (obj.executedQuantity) summary += `**Executed Quantity:** ${obj.executedQuantity}\n`;
+      
+      summary += "\n---\n\n";
+      response.content[0].text = summary + response.content[0].text;
+    }
+  }
+  
+  return response;
+}
+
+/**
+ * Formats order book response for better readability
+ */
+export function formatOrderBookResponse(
+  data: unknown,
+  metadata?: {
+    toolName?: string;
+    correlationId?: string;
+    executionTimeMs?: number;
+  }
+): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  const response = formatResponse(data, metadata);
+  
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>;
+    if (obj.bids || obj.asks || obj.symbol) {
+      let summary = "## Order Book Summary\n\n";
+      
+      if (obj.symbol) summary += `**Symbol:** ${obj.symbol}\n`;
+      
+      if (Array.isArray(obj.bids) && obj.bids.length > 0) {
+        const bestBid = obj.bids[0];
+        if (bestBid && typeof bestBid === "object") {
+          const bid = bestBid as Record<string, unknown>;
+          summary += `**Best Bid:** ${bid[0] || bid.price || "N/A"} (Quantity: ${bid[1] || bid.quantity || "N/A"})\n`;
+        }
+        summary += `**Total Bids:** ${obj.bids.length} price levels\n`;
+      }
+      
+      if (Array.isArray(obj.asks) && obj.asks.length > 0) {
+        const bestAsk = obj.asks[0];
+        if (bestAsk && typeof bestAsk === "object") {
+          const ask = bestAsk as Record<string, unknown>;
+          summary += `**Best Ask:** ${ask[0] || ask.price || "N/A"} (Quantity: ${ask[1] || ask.quantity || "N/A"})\n`;
+        }
+        summary += `**Total Asks:** ${obj.asks.length} price levels\n`;
+      }
+      
+      if (obj.spread) {
+        summary += `**Spread:** ${obj.spread}\n`;
+      }
+      
+      summary += "\n---\n\n";
+      response.content[0].text = summary + response.content[0].text;
+    }
+  }
+  
+  return response;
+}
+
+/**
+ * Formats trades response for better readability
+ */
+export function formatTradesResponse(
+  data: unknown,
+  metadata?: {
+    toolName?: string;
+    correlationId?: string;
+    executionTimeMs?: number;
+  }
+): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  const response = formatResponse(data, metadata);
+  
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>;
+    if (Array.isArray(obj.trades) || Array.isArray(obj.data)) {
+      const trades = (obj.trades || obj.data) as unknown[];
+      let summary = "## Recent Trades Summary\n\n";
+      
+      if (obj.symbol) summary += `**Symbol:** ${obj.symbol}\n`;
+      summary += `**Total Trades:** ${trades.length}\n\n`;
+      
+      if (trades.length > 0) {
+        summary += "**Recent Activity:**\n";
+        const displayCount = Math.min(5, trades.length);
+        for (let i = 0; i < displayCount; i++) {
+          const trade = trades[i];
+          if (trade && typeof trade === "object") {
+            const t = trade as Record<string, unknown>;
+            const price = t.price || t[0] || "N/A";
+            const quantity = t.quantity || t.qty || t[1] || "N/A";
+            const side = t.side || (t[2] === "buy" ? "BUY" : t[2] === "sell" ? "SELL" : "N/A");
+            const time = t.time || t.timestamp || t[3] || "N/A";
+            summary += `${i + 1}. ${side} ${quantity} @ ${price} (Time: ${time})\n`;
+          }
+        }
+        if (trades.length > displayCount) {
+          summary += `... and ${trades.length - displayCount} more trades\n`;
+        }
+      }
+      
+      summary += "\n---\n\n";
+      response.content[0].text = summary + response.content[0].text;
+    }
+  }
+  
+  return response;
+}
+
+/**
+ * Formats klines/candlestick response for better readability
+ */
+export function formatKlinesResponse(
+  data: unknown,
+  metadata?: {
+    toolName?: string;
+    correlationId?: string;
+    executionTimeMs?: number;
+  }
+): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  const response = formatResponse(data, metadata);
+  
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>;
+    if (Array.isArray(obj.klines) || Array.isArray(obj.data) || Array.isArray(obj)) {
+      const klines = (obj.klines || obj.data || obj) as unknown[];
+      let summary = "## Candlestick Data Summary\n\n";
+      
+      if (obj.symbol) summary += `**Symbol:** ${obj.symbol}\n`;
+      if (obj.interval) summary += `**Interval:** ${obj.interval}\n`;
+      summary += `**Total Candles:** ${klines.length}\n\n`;
+      
+      if (klines.length > 0) {
+        summary += "**Price Range:**\n";
+        // Extract OHLC from first and last candles
+        const firstCandle = klines[0];
+        const lastCandle = klines[klines.length - 1];
+        
+        if (Array.isArray(firstCandle) && firstCandle.length >= 4) {
+          summary += `- **Open (First):** ${firstCandle[0]}\n`;
+          summary += `- **High (First):** ${firstCandle[1]}\n`;
+          summary += `- **Low (First):** ${firstCandle[2]}\n`;
+          summary += `- **Close (First):** ${firstCandle[3]}\n`;
+        }
+        
+        if (Array.isArray(lastCandle) && lastCandle.length >= 4) {
+          summary += `- **Close (Last):** ${lastCandle[3]}\n`;
+        }
+        
+        // Calculate price change if possible
+        if (Array.isArray(firstCandle) && Array.isArray(lastCandle) && 
+            firstCandle.length >= 4 && lastCandle.length >= 4) {
+          const openPrice = parseFloat(String(firstCandle[0]));
+          const closePrice = parseFloat(String(lastCandle[3]));
+          if (!isNaN(openPrice) && !isNaN(closePrice)) {
+            const change = closePrice - openPrice;
+            const changePercent = ((change / openPrice) * 100).toFixed(2);
+            summary += `- **Price Change:** ${change >= 0 ? "+" : ""}${change} (${changePercent}%)\n`;
+          }
+        }
+      }
+      
+      summary += "\n---\n\n";
+      response.content[0].text = summary + response.content[0].text;
+    }
+  }
+  
+  return response;
+}
+

package/src/validation/schemas.ts

@@ -0,0 +1,66 @@
+/*
+  Zod schemas for inputs/outputs. These validate tool params and normalize outputs.
+*/
+
+import { z } from "zod";
+
+// Shared enums
+export const sideEnum = z.enum(["buy", "sell"]);
+export const orderTypeEnum = z.enum(["market", "limit"]);
+
+// Spot
+export const spotPlaceOrderInput = z.object({
+  symbol: z.string().min(1),
+  side: sideEnum,
+  type: orderTypeEnum,
+  quantity: z.string().min(1),
+  price: z.string().optional(),
+  clientOrderId: z.string().optional(),
+});
+
+export const spotCancelOrderInput = z.object({
+  orderId: z.string().min(1),
+  symbol: z.string().optional(),
+});
+
+export const spotBalancesOutput = z.object({
+  balances: z.array(
+    z.object({ asset: z.string(), free: z.string(), locked: z.string() })
+  ),
+});
+
+// Futures
+export const futuresPlaceOrderInput = z.object({
+  symbol: z.string().min(1),
+  side: sideEnum,
+  type: orderTypeEnum,
+  quantity: z.string().min(1),
+  price: z.string().optional(),
+  leverage: z.number().int().positive().max(125).optional(),
+  clientOrderId: z.string().optional(),
+});
+
+export const futuresCancelOrderInput = z.object({
+  orderId: z.string().min(1),
+  symbol: z.string().optional(),
+});
+
+export const futuresPositionsOutput = z.object({
+  positions: z.array(
+    z.object({
+      symbol: z.string(),
+      positionSide: z.enum(["long", "short"]).optional(),
+      quantity: z.string(),
+      entryPrice: z.string().optional(),
+      unrealizedPnl: z.string().optional(),
+      leverage: z.number().int().positive().optional(),
+    })
+  ),
+});
+
+export type SpotPlaceOrderInput = z.infer<typeof spotPlaceOrderInput>;
+export type SpotCancelOrderInput = z.infer<typeof spotCancelOrderInput>;
+export type FuturesPlaceOrderInput = z.infer<typeof futuresPlaceOrderInput>;
+export type FuturesCancelOrderInput = z.infer<typeof futuresCancelOrderInput>;
+
+

package/src/validation/validators.ts

@@ -0,0 +1,189 @@
+/*
+  Input validation helpers with helpful error messages for LLMs.
+*/
+
+import { z } from "zod";
+import { createInvalidParamsError } from "../mcp/errors.js";
+
+/**
+ * Validates trading pair symbol format (BASE-QUOTE)
+ * Examples: BTC-INR, ETH-INR, BTC-USDT
+ */
+export function validateSymbol(symbol: string): void {
+  if (!symbol || typeof symbol !== "string") {
+    throw createInvalidParamsError(
+      `Invalid symbol: must be a non-empty string. Expected format: BASE-QUOTE (e.g., "BTC-INR", "ETH-INR")`
+    );
+  }
+  
+  const trimmed = symbol.trim().toUpperCase();
+  const parts = trimmed.split("-");
+  
+  if (parts.length !== 2) {
+    throw createInvalidParamsError(
+      `Invalid symbol format: "${symbol}". Expected format: BASE-QUOTE (e.g., "BTC-INR", "ETH-INR", "BTC-USDT"). Use uppercase currency codes separated by a single hyphen.`
+    );
+  }
+  
+  const [base, quote] = parts;
+  
+  if (!base || base.length === 0) {
+    throw createInvalidParamsError(
+      `Invalid symbol: base currency is missing. Expected format: BASE-QUOTE (e.g., "BTC-INR")`
+    );
+  }
+  
+  if (!quote || quote.length === 0) {
+    throw createInvalidParamsError(
+      `Invalid symbol: quote currency is missing. Expected format: BASE-QUOTE (e.g., "BTC-INR")`
+    );
+  }
+  
+  // Check for valid currency code format (alphanumeric, typically 2-10 characters)
+  const currencyCodeRegex = /^[A-Z0-9]{2,10}$/;
+  if (!currencyCodeRegex.test(base)) {
+    throw createInvalidParamsError(
+      `Invalid base currency code: "${base}". Currency codes should be 2-10 uppercase alphanumeric characters (e.g., "BTC", "ETH", "USDT")`
+    );
+  }
+  if (!currencyCodeRegex.test(quote)) {
+    throw createInvalidParamsError(
+      `Invalid quote currency code: "${quote}". Currency codes should be 2-10 uppercase alphanumeric characters (e.g., "INR", "USDT", "BTC")`
+    );
+  }
+}
+
+/**
+ * Validates quantity string format
+ */
+export function validateQuantity(quantity: string): void {
+  if (!quantity || typeof quantity !== "string") {
+    throw createInvalidParamsError(
+      `Invalid quantity: must be a non-empty string. This prevents floating-point precision issues. Example: "0.001" or "100"`
+    );
+  }
+  
+  const trimmed = quantity.trim();
+  if (trimmed.length === 0) {
+    throw createInvalidParamsError(
+      `Invalid quantity: cannot be empty. Provide a positive number as a string (e.g., "0.001", "100", "0.5")`
+    );
+  }
+  
+  // Check if it's a valid number format
+  const numberRegex = /^-?\d+(\.\d+)?$/;
+  if (!numberRegex.test(trimmed)) {
+    throw createInvalidParamsError(
+      `Invalid quantity format: "${quantity}". Expected a positive number as a string. Examples: "0.001", "100", "0.5". Do not include commas or other formatting.`
+    );
+  }
+  
+  // Check if it's positive
+  const numValue = parseFloat(trimmed);
+  if (isNaN(numValue)) {
+    throw createInvalidParamsError(
+      `Invalid quantity: "${quantity}" is not a valid number. Provide a positive number as a string (e.g., "0.001")`
+    );
+  }
+  
+  if (numValue <= 0) {
+    throw createInvalidParamsError(
+      `Invalid quantity: "${quantity}" must be greater than zero. Provide a positive number as a string (e.g., "0.001", "100")`
+    );
+  }
+  
+  // Check for reasonable precision (typically up to 8 decimal places for crypto)
+  const decimalParts = trimmed.split(".");
+  if (decimalParts.length === 2 && decimalParts[1].length > 18) {
+    throw createInvalidParamsError(
+      `Invalid quantity precision: "${quantity}" has too many decimal places (max 18). Example: "0.001" or "100.123456789012345678"`
+    );
+  }
+}
+
+/**
+ * Zod schema for symbol validation
+ */
+export const symbolSchema = z.string().min(1).refine(
+  (val) => {
+    try {
+      validateSymbol(val);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: 'Invalid symbol format. Expected BASE-QUOTE (e.g., "BTC-INR", "ETH-INR")',
+  }
+);
+
+/**
+ * Zod schema for quantity validation
+ */
+export const quantitySchema = z.string().min(1).refine(
+  (val) => {
+    try {
+      validateQuantity(val);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: 'Invalid quantity format. Expected a positive number as a string (e.g., "0.001", "100")',
+  }
+);
+
+/**
+ * Validates clientOrderId format
+ * Must contain only letters, numbers, dots, colons, slashes, underscores, and hyphens
+ * Length must be between 1-36 characters
+ */
+export function validateClientOrderId(clientOrderId: string): void {
+  if (!clientOrderId || typeof clientOrderId !== "string") {
+    throw createInvalidParamsError(
+      `Invalid clientOrderId: must be a non-empty string`
+    );
+  }
+  
+  const trimmed = clientOrderId.trim();
+  
+  if (trimmed.length === 0) {
+    throw createInvalidParamsError(
+      `Invalid clientOrderId: cannot be empty`
+    );
+  }
+  
+  if (trimmed.length > 36) {
+    throw createInvalidParamsError(
+      `Invalid clientOrderId: "${clientOrderId}" exceeds maximum length of 36 characters (current: ${trimmed.length})`
+    );
+  }
+  
+  // Must contain only letters, numbers, dots, colons, slashes, underscores, and hyphens
+  const validFormat = /^[a-zA-Z0-9.:/_\-]+$/;
+  if (!validFormat.test(trimmed)) {
+    throw createInvalidParamsError(
+      `Invalid clientOrderId format: "${clientOrderId}". Must contain only letters, numbers, dots, colons, slashes, underscores, and hyphens. Examples: "my-order-123", "order:2024/01/15_001", "trade.abc-123"`
+    );
+  }
+}
+
+/**
+ * Zod schema for clientOrderId validation
+ */
+export const clientOrderIdSchema = z.string().min(1).max(36).refine(
+  (val) => {
+    try {
+      validateClientOrderId(val);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: 'Invalid clientOrderId format. Must be 1-36 characters and contain only letters, numbers, dots, colons, slashes, underscores, and hyphens',
+  }
+);
+

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["ES2020"],
+    "types": ["node"],
+    "sourceMap": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+