@guiie/buda-mcp 1.1.1 → 1.2.0

package/src/cache.ts

@@ -5,15 +5,31 @@ interface CacheEntry<T> {
 
 export class MemoryCache {
   private store = new Map<string, CacheEntry<unknown>>();
+  private inflight = new Map<string, Promise<unknown>>();
 
   async getOrFetch<T>(key: string, ttlMs: number, fetcher: () => Promise<T>): Promise<T> {
     const entry = this.store.get(key) as CacheEntry<T> | undefined;
     if (entry && Date.now() < entry.expiry) {
       return entry.data;
     }
-    const data = await fetcher();
-    this.store.set(key, { data, expiry: Date.now() + ttlMs });
-    return data;
+
+    // Deduplicate concurrent requests for the same expired/missing key.
+    const pending = this.inflight.get(key) as Promise<T> | undefined;
+    if (pending) return pending;
+
+    const promise = fetcher()
+      .then((data) => {
+        this.store.set(key, { data, expiry: Date.now() + ttlMs });
+        this.inflight.delete(key);
+        return data;
+      })
+      .catch((err: unknown) => {
+        this.inflight.delete(key);
+        throw err;
+      });
+
+    this.inflight.set(key, promise as Promise<unknown>);
+    return promise;
   }
 
   invalidate(key: string): void {

package/src/client.ts

@@ -1,4 +1,5 @@
 import { createHmac } from "crypto";
+import { VERSION } from "./version.js";
 
 const BASE_URL = "https://www.buda.com/api/v2";
 
@@ -7,6 +8,7 @@ export class BudaApiError extends Error {
     public readonly status: number,
     public readonly path: string,
     message: string,
+    public readonly retryAfterMs?: number,
   ) {
     super(message);
     this.name = "BudaApiError";
@@ -56,24 +58,51 @@ export class BudaClient {
     };
   }
 
-  async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
-    const url = new URL(`${this.baseUrl}${path}.json`);
+  /**
+   * Parses the Retry-After header value into milliseconds.
+   * Per RFC 7231, Retry-After is an integer number of seconds.
+   * Defaults to 1000ms (1 second) if absent or unparseable.
+   */
+  private parseRetryAfterMs(headers: Headers): number {
+    const raw = headers.get("Retry-After");
+    if (!raw) return 1000;
+    const secs = parseInt(raw, 10);
+    return isNaN(secs) ? 1000 : secs * 1000;
+  }
 
-    if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        url.searchParams.set(key, String(value));
-      }
+  /**
+   * Executes a fetch call with a single 429 retry.
+   * On the first 429, waits for Retry-After seconds (default 1s), then retries once.
+   * If the retry also returns 429, throws a BudaApiError with retryAfterMs set.
+   */
+  private async fetchWithRetry(
+    url: URL,
+    options: RequestInit,
+    path: string,
+  ): Promise<Response> {
+    const response = await fetch(url.toString(), options);
+
+    if (response.status !== 429) return response;
+
+    const retryAfterMs = this.parseRetryAfterMs(response.headers);
+    await new Promise((r) => setTimeout(r, retryAfterMs));
+
+    const retry = await fetch(url.toString(), options);
+
+    if (retry.status === 429) {
+      const retryAgainMs = this.parseRetryAfterMs(retry.headers);
+      throw new BudaApiError(
+        429,
+        path,
+        `Buda API rate limit exceeded. Retry after ${retryAgainMs}ms.`,
+        retryAgainMs,
+      );
     }
 
-    const urlPath = url.pathname + url.search;
-    const headers: Record<string, string> = {
-      Accept: "application/json",
-      "User-Agent": "buda-mcp/1.1.0",
-      ...this.authHeaders("GET", urlPath),
-    };
-
-    const response = await fetch(url.toString(), { headers });
+    return retry;
+  }
 
+  private async handleResponse<T>(response: Response, path: string): Promise<T> {
     if (!response.ok) {
       let detail = response.statusText;
       try {
@@ -84,10 +113,29 @@ export class BudaClient {
       }
       throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
     }
-
     return response.json() as Promise<T>;
   }
 
+  async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
+    const url = new URL(`${this.baseUrl}${path}.json`);
+
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const urlPath = url.pathname + url.search;
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      "User-Agent": `buda-mcp/${VERSION}`,
+      ...this.authHeaders("GET", urlPath),
+    };
+
+    const response = await this.fetchWithRetry(url, { headers }, path);
+    return this.handleResponse<T>(response, path);
+  }
+
   async post<T>(path: string, payload: unknown): Promise<T> {
     const url = new URL(`${this.baseUrl}${path}.json`);
     const bodyStr = JSON.stringify(payload);
@@ -95,28 +143,16 @@ export class BudaClient {
     const headers: Record<string, string> = {
       Accept: "application/json",
       "Content-Type": "application/json",
-      "User-Agent": "buda-mcp/1.1.0",
+      "User-Agent": `buda-mcp/${VERSION}`,
       ...this.authHeaders("POST", urlPath, bodyStr),
     };
 
-    const response = await fetch(url.toString(), {
-      method: "POST",
-      headers,
-      body: bodyStr,
-    });
-
-    if (!response.ok) {
-      let detail = response.statusText;
-      try {
-        const body = (await response.json()) as { message?: string };
-        if (body.message) detail = body.message;
-      } catch {
-        // ignore parse error, use statusText
-      }
-      throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
-    }
-
-    return response.json() as Promise<T>;
+    const response = await this.fetchWithRetry(
+      url,
+      { method: "POST", headers, body: bodyStr },
+      path,
+    );
+    return this.handleResponse<T>(response, path);
   }
 
   async put<T>(path: string, payload: unknown): Promise<T> {
@@ -126,27 +162,15 @@ export class BudaClient {
     const headers: Record<string, string> = {
       Accept: "application/json",
       "Content-Type": "application/json",
-      "User-Agent": "buda-mcp/1.1.0",
+      "User-Agent": `buda-mcp/${VERSION}`,
       ...this.authHeaders("PUT", urlPath, bodyStr),
     };
 
-    const response = await fetch(url.toString(), {
-      method: "PUT",
-      headers,
-      body: bodyStr,
-    });
-
-    if (!response.ok) {
-      let detail = response.statusText;
-      try {
-        const body = (await response.json()) as { message?: string };
-        if (body.message) detail = body.message;
-      } catch {
-        // ignore parse error, use statusText
-      }
-      throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
-    }
-
-    return response.json() as Promise<T>;
+    const response = await this.fetchWithRetry(
+      url,
+      { method: "PUT", headers, body: bodyStr },
+      path,
+    );
+    return this.handleResponse<T>(response, path);
   }
 }

package/src/http.ts

@@ -3,6 +3,7 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { BudaClient } from "./client.js";
 import { MemoryCache, CACHE_TTL } from "./cache.js";
+import { VERSION } from "./version.js";
 import type { MarketsResponse, TickerResponse } from "./types.js";
 import * as markets from "./tools/markets.js";
 import * as ticker from "./tools/ticker.js";
@@ -27,8 +28,28 @@ const client = new BudaClient(
 
 const authEnabled = client.hasAuth();
 
+// Schemas for the Smithery server-card — assembled from the same definitions used in register().
+// Adding a new tool only requires exporting its toolSchema; no changes needed here.
+const PUBLIC_TOOL_SCHEMAS = [
+  markets.toolSchema,
+  ticker.toolSchema,
+  orderbook.toolSchema,
+  trades.toolSchema,
+  volume.toolSchema,
+  spread.toolSchema,
+  compareMarkets.toolSchema,
+  priceHistory.toolSchema,
+];
+
+const AUTH_TOOL_SCHEMAS = [
+  balances.toolSchema,
+  orders.toolSchema,
+  placeOrder.toolSchema,
+  cancelOrder.toolSchema,
+];
+
 function createServer(): McpServer {
-  const server = new McpServer({ name: "buda-mcp", version: "1.1.1" });
+  const server = new McpServer({ name: "buda-mcp", version: VERSION });
 
   // Per-request cache so caching works correctly for stateless HTTP
   const reqCache = new MemoryCache();
@@ -101,160 +122,21 @@ app.use(express.json());
 
 // Health check for Railway / uptime monitors
 app.get("/health", (_req, res) => {
-  res.json({ status: "ok", server: "buda-mcp", version: "1.1.1", auth_mode: authEnabled ? "authenticated" : "public" });
+  res.json({
+    status: "ok",
+    server: "buda-mcp",
+    version: VERSION,
+    auth_mode: authEnabled ? "authenticated" : "public",
+  });
 });
 
-// Smithery static server card — lets Smithery scan tools without running the server
+// Smithery static server card — assembled programmatically from tool definitions.
+// Adding a new tool only requires exporting its toolSchema; this handler needs no changes.
 app.get("/.well-known/mcp/server-card.json", (_req, res) => {
-  const publicTools = [
-    {
-      name: "get_markets",
-      description: "List all available trading pairs on Buda.com, or get details for a specific market.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          market_id: { type: "string", description: "Optional market ID (e.g. BTC-CLP)" },
-        },
-      },
-    },
-    {
-      name: "get_ticker",
-      description: "Get current price, bid/ask, volume, and price change for a Buda.com market.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          market_id: { type: "string", description: "Market ID (e.g. BTC-CLP)" },
-        },
-        required: ["market_id"],
-      },
-    },
-    {
-      name: "get_orderbook",
-      description: "Get the full order book (bids and asks) for a Buda.com market.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          market_id: { type: "string", description: "Market ID (e.g. BTC-CLP)" },
-          limit: { type: "number", description: "Max levels per side" },
-        },
-        required: ["market_id"],
-      },
-    },
-    {
-      name: "get_trades",
-      description: "Get recent trade history for a Buda.com market.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          market_id: { type: "string", description: "Market ID (e.g. BTC-CLP)" },
-          limit: { type: "number", description: "Number of trades (max 100)" },
-          timestamp: { type: "number", description: "Unix timestamp for pagination" },
-        },
-        required: ["market_id"],
-      },
-    },
-    {
-      name: "get_market_volume",
-      description: "Get 24h and 7-day transacted volume for a Buda.com market.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          market_id: { type: "string", description: "Market ID (e.g. BTC-CLP)" },
-        },
-        required: ["market_id"],
-      },
-    },
-    {
-      name: "get_spread",
-      description: "Calculate bid/ask spread (absolute and percentage) for a Buda.com market.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          market_id: { type: "string", description: "Market ID (e.g. BTC-CLP)" },
-        },
-        required: ["market_id"],
-      },
-    },
-    {
-      name: "compare_markets",
-      description: "Compare ticker data for all trading pairs of a given base currency side by side.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          base_currency: { type: "string", description: "Base currency (e.g. BTC, ETH)" },
-        },
-        required: ["base_currency"],
-      },
-    },
-    {
-      name: "get_price_history",
-      description: "Get OHLCV price history for a market, derived from recent trade history.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          market_id: { type: "string", description: "Market ID (e.g. BTC-CLP)" },
-          period: { type: "string", enum: ["1h", "4h", "1d"], description: "Candle period" },
-          limit: { type: "number", description: "Raw trades to fetch (max 100)" },
-        },
-        required: ["market_id"],
-      },
-    },
-  ];
-
-  const authTools = authEnabled
-    ? [
-        {
-          name: "get_balances",
-          description: "Get all currency balances for the authenticated account.",
-          inputSchema: { type: "object", properties: {} },
-        },
-        {
-          name: "get_orders",
-          description: "Get orders for a given market.",
-          inputSchema: {
-            type: "object",
-            properties: {
-              market_id: { type: "string" },
-              state: { type: "string" },
-            },
-            required: ["market_id"],
-          },
-        },
-        {
-          name: "place_order",
-          description: "Place a limit or market order. Requires confirmation_token='CONFIRM'.",
-          inputSchema: {
-            type: "object",
-            properties: {
-              market_id: { type: "string" },
-              type: { type: "string", enum: ["Bid", "Ask"] },
-              price_type: { type: "string", enum: ["limit", "market"] },
-              amount: { type: "number" },
-              limit_price: { type: "number" },
-              confirmation_token: { type: "string" },
-            },
-            required: ["market_id", "type", "price_type", "amount", "confirmation_token"],
-          },
-        },
-        {
-          name: "cancel_order",
-          description: "Cancel an order by ID. Requires confirmation_token='CONFIRM'.",
-          inputSchema: {
-            type: "object",
-            properties: {
-              order_id: { type: "number" },
-              confirmation_token: { type: "string" },
-            },
-            required: ["order_id", "confirmation_token"],
-          },
-        },
-      ]
-    : [];
-
   res.json({
-    serverInfo: { name: "buda-mcp", version: "1.1.1" },
+    serverInfo: { name: "buda-mcp", version: VERSION },
     authentication: { required: authEnabled },
-    tools: [...publicTools, ...authTools],
+    tools: [...PUBLIC_TOOL_SCHEMAS, ...(authEnabled ? AUTH_TOOL_SCHEMAS : [])],
     resources: [
       { uri: "buda://markets", name: "All Buda.com markets", mimeType: "application/json" },
       { uri: "buda://ticker/{market}", name: "Ticker for a specific market", mimeType: "application/json" },

package/src/index.ts

@@ -3,6 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BudaClient } from "./client.js";
 import { cache, CACHE_TTL } from "./cache.js";
+import { VERSION } from "./version.js";
 import type { MarketsResponse, TickerResponse } from "./types.js";
 import * as markets from "./tools/markets.js";
 import * as ticker from "./tools/ticker.js";
@@ -25,7 +26,7 @@ const client = new BudaClient(
 
 const server = new McpServer({
   name: "buda-mcp",
-  version: "1.1.1",
+  version: VERSION,
 });
 
 // Public tools

package/src/tools/balances.ts

@@ -2,12 +2,22 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BudaClient, BudaApiError } from "../client.js";
 import type { BalancesResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "get_balances",
+  description:
+    "Get all currency balances for the authenticated Buda.com account. " +
+    "Returns total, available, frozen, and pending withdrawal amounts per currency. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {},
+  },
+};
+
 export function register(server: McpServer, client: BudaClient): void {
   server.tool(
-    "get_balances",
-    "Get all currency balances for the authenticated Buda.com account. " +
-      "Returns total, available, frozen, and pending withdrawal amounts per currency. " +
-      "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+    toolSchema.name,
+    toolSchema.description,
     {},
     async () => {
       try {

package/src/tools/cancel_order.ts

@@ -3,13 +3,84 @@ import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import type { OrderResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "cancel_order",
+  description:
+    "Cancel an open order by ID on Buda.com. " +
+    "IMPORTANT: To prevent accidental cancellation from ambiguous prompts, you must pass " +
+    "confirmation_token='CONFIRM' to execute. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      order_id: {
+        type: "number",
+        description: "The numeric ID of the order to cancel.",
+      },
+      confirmation_token: {
+        type: "string",
+        description:
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to cancel the order. " +
+          "Any other value will reject the request without canceling.",
+      },
+    },
+    required: ["order_id", "confirmation_token"],
+  },
+};
+
+type CancelOrderArgs = {
+  order_id: number;
+  confirmation_token: string;
+};
+
+export async function handleCancelOrder(
+  args: CancelOrderArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { order_id, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Order not canceled. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Verify the order ID and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            order_id,
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  try {
+    const data = await client.put<OrderResponse>(`/orders/${order_id}`, {
+      state: "canceling",
+    });
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(data.order, null, 2) }],
+    };
+  } catch (err) {
+    const msg =
+      err instanceof BudaApiError
+        ? { error: err.message, code: err.status, path: err.path }
+        : { error: String(err), code: "UNKNOWN" };
+    return {
+      content: [{ type: "text", text: JSON.stringify(msg) }],
+      isError: true,
+    };
+  }
+}
+
 export function register(server: McpServer, client: BudaClient): void {
   server.tool(
-    "cancel_order",
-    "Cancel an open order by ID on Buda.com. " +
-      "IMPORTANT: To prevent accidental cancellation from ambiguous prompts, you must pass " +
-      "confirmation_token='CONFIRM' to execute. " +
-      "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+    toolSchema.name,
+    toolSchema.description,
     {
       order_id: z
         .number()
@@ -23,43 +94,6 @@ export function register(server: McpServer, client: BudaClient): void {
             "Any other value will reject the request without canceling.",
         ),
     },
-    async ({ order_id, confirmation_token }) => {
-      if (confirmation_token !== "CONFIRM") {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error:
-                  "Order not canceled. confirmation_token must equal 'CONFIRM' to execute. " +
-                  "Verify the order ID and set confirmation_token='CONFIRM' to proceed.",
-                code: "CONFIRMATION_REQUIRED",
-                order_id,
-              }),
-            },
-          ],
-          isError: true,
-        };
-      }
-
-      try {
-        const data = await client.put<OrderResponse>(`/orders/${order_id}`, {
-          state: "canceling",
-        });
-
-        return {
-          content: [{ type: "text", text: JSON.stringify(data.order, null, 2) }],
-        };
-      } catch (err) {
-        const msg =
-          err instanceof BudaApiError
-            ? { error: err.message, code: err.status, path: err.path }
-            : { error: String(err), code: "UNKNOWN" };
-        return {
-          content: [{ type: "text", text: JSON.stringify(msg) }],
-          isError: true,
-        };
-      }
-    },
+    (args) => handleCancelOrder(args, client),
   );
 }

package/src/tools/compare_markets.ts

@@ -4,12 +4,29 @@ import { BudaClient, BudaApiError } from "../client.js";
 import { MemoryCache, CACHE_TTL } from "../cache.js";
 import type { AllTickersResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "compare_markets",
+  description:
+    "Compare ticker data for all trading pairs of a given base currency across Buda.com's " +
+    "supported quote currencies (CLP, COP, PEN, BTC, USDC, ETH). " +
+    "For example, passing 'BTC' returns side-by-side data for BTC-CLP, BTC-COP, BTC-PEN, etc.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      base_currency: {
+        type: "string",
+        description:
+          "Base currency to compare across all available markets (e.g. 'BTC', 'ETH', 'XRP').",
+      },
+    },
+    required: ["base_currency"],
+  },
+};
+
 export function register(server: McpServer, client: BudaClient, cache: MemoryCache): void {
   server.tool(
-    "compare_markets",
-    "Compare ticker data for all trading pairs of a given base currency across Buda.com's " +
-      "supported quote currencies (CLP, COP, PEN, BTC, USDC, ETH). " +
-      "For example, passing 'BTC' returns side-by-side data for BTC-CLP, BTC-COP, BTC-PEN, etc.",
+    toolSchema.name,
+    toolSchema.description,
     {
       base_currency: z
         .string()

package/src/tools/markets.ts

@@ -2,13 +2,29 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { MemoryCache, CACHE_TTL } from "../cache.js";
+import { validateMarketId } from "../validation.js";
 import type { MarketsResponse, MarketResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "get_markets",
+  description:
+    "List all available trading pairs on Buda.com, or get details for a specific market. " +
+    "Returns base/quote currencies, fees, and minimum order sizes.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Optional market ID (e.g. 'BTC-CLP', 'ETH-BTC'). Omit to list all markets.",
+      },
+    },
+  },
+};
+
 export function register(server: McpServer, client: BudaClient, cache: MemoryCache): void {
   server.tool(
-    "get_markets",
-    "List all available trading pairs on Buda.com, or get details for a specific market. " +
-      "Returns base/quote currencies, fees, and minimum order sizes.",
+    toolSchema.name,
+    toolSchema.description,
     {
       market_id: z
         .string()
@@ -20,6 +36,14 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
     async ({ market_id }) => {
       try {
         if (market_id) {
+          const validationError = validateMarketId(market_id);
+          if (validationError) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+              isError: true,
+            };
+          }
+
           const id = market_id.toLowerCase();
           const data = await cache.getOrFetch<MarketResponse>(
             `market:${id}`,