@guiie/buda-mcp 1.1.2 → 1.2.1

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}`,

package/src/tools/orderbook.ts

@@ -2,13 +2,34 @@ 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 { OrderBookResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "get_orderbook",
+  description:
+    "Get the current order book (bids and asks) for a Buda.com market. Returns sorted arrays of " +
+    "bids (buy orders) and asks (sell orders), each as [price, amount] pairs.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of levels to return per side (default: all).",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
 export function register(server: McpServer, client: BudaClient, cache: MemoryCache): void {
   server.tool(
-    "get_orderbook",
-    "Get the current order book (bids and asks) for a Buda.com market. Returns sorted arrays of " +
-      "bids (buy orders) and asks (sell orders), each as [price, amount] pairs.",
+    toolSchema.name,
+    toolSchema.description,
     {
       market_id: z
         .string()
@@ -22,6 +43,14 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
     },
     async ({ market_id, limit }) => {
       try {
+        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<OrderBookResponse>(
           `orderbook:${id}`,

package/src/tools/orders.ts

@@ -1,13 +1,43 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
+import { validateMarketId } from "../validation.js";
 import type { OrdersResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "get_orders",
+  description:
+    "Get orders for a given Buda.com market. Filter by state (pending, active, traded, canceled). " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+      },
+      state: {
+        type: "string",
+        description:
+          "Filter by order state: 'pending', 'active', 'traded', 'canceled', 'canceled_and_traded'.",
+      },
+      per: {
+        type: "number",
+        description: "Results per page (default: 20, max: 300).",
+      },
+      page: {
+        type: "number",
+        description: "Page number (default: 1).",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
 export function register(server: McpServer, client: BudaClient): void {
   server.tool(
-    "get_orders",
-    "Get orders for a given Buda.com market. Filter by state (pending, active, traded, canceled). " +
-      "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+    toolSchema.name,
+    toolSchema.description,
     {
       market_id: z
         .string()
@@ -35,6 +65,14 @@ export function register(server: McpServer, client: BudaClient): void {
     },
     async ({ market_id, state, per, page }) => {
       try {
+        const validationError = validateMarketId(market_id);
+        if (validationError) {
+          return {
+            content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+            isError: true,
+          };
+        }
+
         const params: Record<string, string | number> = {};
         if (state) params.state = state;
         if (per !== undefined) params.per = per;

package/src/tools/place_order.ts

@@ -1,16 +1,143 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
+import { validateMarketId } from "../validation.js";
 import type { OrderResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "place_order",
+  description:
+    "Place a limit or market order on Buda.com. " +
+    "IMPORTANT: To prevent accidental execution from ambiguous prompts, you must pass " +
+    "confirmation_token='CONFIRM' to execute the order. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables. " +
+    "WARNING: Only use this tool on a locally-run instance — never on a publicly exposed server.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+      },
+      type: {
+        type: "string",
+        description: "Order side: 'Bid' to buy, 'Ask' to sell.",
+      },
+      price_type: {
+        type: "string",
+        description: "Order type: 'limit' places at a specific price, 'market' executes immediately.",
+      },
+      amount: {
+        type: "number",
+        description: "Order size in the market's base currency (e.g. BTC amount for BTC-CLP).",
+      },
+      limit_price: {
+        type: "number",
+        description:
+          "Limit price in quote currency. Required when price_type is 'limit'. " +
+          "For Bid orders: highest price you will pay. For Ask orders: lowest price you will accept.",
+      },
+      confirmation_token: {
+        type: "string",
+        description:
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute the order. " +
+          "Any other value will reject the request without placing an order.",
+      },
+    },
+    required: ["market_id", "type", "price_type", "amount", "confirmation_token"],
+  },
+};
+
+type PlaceOrderArgs = {
+  market_id: string;
+  type: "Bid" | "Ask";
+  price_type: "limit" | "market";
+  amount: number;
+  limit_price?: number;
+  confirmation_token: string;
+};
+
+export async function handlePlaceOrder(
+  args: PlaceOrderArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { market_id, type, price_type, amount, limit_price, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Order not placed. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Review the order details and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            order_preview: { market_id, type, price_type, amount, limit_price },
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const validationError = validateMarketId(market_id);
+  if (validationError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+      isError: true,
+    };
+  }
+
+  try {
+    const payload: Record<string, unknown> = {
+      type,
+      price_type,
+      amount,
+    };
+
+    if (price_type === "limit") {
+      if (limit_price === undefined) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "limit_price is required when price_type is 'limit'.",
+                code: "VALIDATION_ERROR",
+              }),
+            },
+          ],
+          isError: true,
+        };
+      }
+      payload.limit = { price: limit_price, type: "gtc" };
+    }
+
+    const data = await client.post<OrderResponse>(
+      `/markets/${market_id.toLowerCase()}/orders`,
+      payload,
+    );
+
+    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(
-    "place_order",
-    "Place a limit or market order on Buda.com. " +
-      "IMPORTANT: To prevent accidental execution from ambiguous prompts, you must pass " +
-      "confirmation_token='CONFIRM' to execute the order. " +
-      "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables. " +
-      "WARNING: Only use this tool on a locally-run instance — never on a publicly exposed server.",
+    toolSchema.name,
+    toolSchema.description,
     {
       market_id: z
         .string()
@@ -40,68 +167,6 @@ export function register(server: McpServer, client: BudaClient): void {
             "Any other value will reject the request without placing an order.",
         ),
     },
-    async ({ market_id, type, price_type, amount, limit_price, confirmation_token }) => {
-      if (confirmation_token !== "CONFIRM") {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error:
-                  "Order not placed. confirmation_token must equal 'CONFIRM' to execute. " +
-                  "Review the order details and set confirmation_token='CONFIRM' to proceed.",
-                code: "CONFIRMATION_REQUIRED",
-                order_preview: { market_id, type, price_type, amount, limit_price },
-              }),
-            },
-          ],
-          isError: true,
-        };
-      }
-
-      try {
-        const payload: Record<string, unknown> = {
-          type,
-          price_type,
-          amount,
-        };
-
-        if (price_type === "limit") {
-          if (limit_price === undefined) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify({
-                    error: "limit_price is required when price_type is 'limit'.",
-                    code: "VALIDATION_ERROR",
-                  }),
-                },
-              ],
-              isError: true,
-            };
-          }
-          payload.limit = { price: limit_price, type: "gtc" };
-        }
-
-        const data = await client.post<OrderResponse>(
-          `/markets/${market_id.toLowerCase()}/orders`,
-          payload,
-        );
-
-        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) => handlePlaceOrder(args, client),
   );
 }

package/src/tools/price_history.ts

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { MemoryCache } from "../cache.js";
+import { validateMarketId } from "../validation.js";
 import type { TradesResponse } from "../types.js";
 
 const PERIOD_MS: Record<string, number> = {
@@ -20,13 +21,40 @@ interface OhlcvCandle {
   trade_count: number;
 }
 
+export const toolSchema = {
+  name: "get_price_history",
+  description:
+    "IMPORTANT: Candles are aggregated client-side from raw trades (Buda has no native candlestick " +
+    "endpoint) — fetching more trades via the 'limit' parameter gives deeper history but slower " +
+    "responses. Returns OHLCV (open/high/low/close/volume) price history for a Buda.com market. " +
+    "Candle timestamps are UTC bucket boundaries (e.g. '2026-04-10T12:00:00.000Z' for 1h). " +
+    "Supports 1h, 4h, and 1d candle periods.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+      },
+      period: {
+        type: "string",
+        description: "Candle period: '1h' (1 hour), '4h' (4 hours), or '1d' (1 day). Default: '1h'.",
+      },
+      limit: {
+        type: "number",
+        description:
+          "Raw trades to fetch before aggregation (default: 100, max: 1000). " +
+          "More trades = deeper history but slower response.",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
 export function register(server: McpServer, client: BudaClient, _cache: MemoryCache): void {
   server.tool(
-    "get_price_history",
-    "Get OHLCV (open/high/low/close/volume) price history for a Buda.com market, derived from " +
-      "recent trade history (up to 100 trades). Buda does not provide a native candlestick endpoint; " +
-      "candles are aggregated client-side from raw trades. Use the 'period' parameter to control " +
-      "candle size (1h, 4h, or 1d).",
+    toolSchema.name,
+    toolSchema.description,
     {
       market_id: z
         .string()
@@ -39,12 +67,23 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
         .number()
         .int()
         .min(1)
-        .max(100)
+        .max(1000)
         .optional()
-        .describe("Number of raw trades to fetch before aggregation (default: 100, max: 100)."),
+        .describe(
+          "Raw trades to fetch before aggregation (default: 100, max: 1000). " +
+            "More trades = deeper history but slower response.",
+        ),
     },
     async ({ market_id, period, limit }) => {
       try {
+        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 tradesLimit = limit ?? 100;
 
@@ -108,7 +147,10 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
           market_id: market_id.toUpperCase(),
           period,
           candle_count: candles.length,
-          note: "Candles derived from trade history (up to 100 trades). For deeper history, use pagination via the get_trades tool.",
+          trades_fetched: entries.length,
+          note:
+            "Candles derived from raw trade history. Candle timestamps are UTC bucket boundaries. " +
+            "Increase 'limit' (max 1000) for deeper history.",
           candles,
         };
 

package/src/tools/spread.ts

@@ -2,13 +2,30 @@ 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 { TickerResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "get_spread",
+  description:
+    "Calculate the bid/ask spread for a Buda.com market. " +
+    "Returns the best bid, best ask, absolute spread, and spread as a percentage of the ask price.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC', 'BTC-COP').",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
 export function register(server: McpServer, client: BudaClient, cache: MemoryCache): void {
   server.tool(
-    "get_spread",
-    "Calculate the bid/ask spread for a Buda.com market. " +
-      "Returns the best bid, best ask, absolute spread, and spread as a percentage of the ask price.",
+    toolSchema.name,
+    toolSchema.description,
     {
       market_id: z
         .string()
@@ -16,6 +33,14 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
     },
     async ({ market_id }) => {
       try {
+        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<TickerResponse>(
           `ticker:${id}`,