@guiie/buda-mcp 1.1.2 → 1.2.0

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

package/src/tools/ticker.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_ticker",
+  description:
+    "Get the current ticker for a Buda.com market: last traded price, best bid/ask, " +
+    "24h volume, and price change over 24h and 7d.",
+  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_ticker",
-    "Get the current ticker for a Buda.com market: last traded price, best bid/ask, " +
-      "24h volume, and price change over 24h and 7d.",
+    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}`,

package/src/tools/trades.ts

@@ -2,13 +2,39 @@ 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";
 
+export const toolSchema = {
+  name: "get_trades",
+  description:
+    "Get recent trade history for a Buda.com market. Each entry contains " +
+    "[timestamp_ms, amount, price, direction]. Direction is 'buy' or 'sell'.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+      },
+      limit: {
+        type: "number",
+        description: "Number of trades to return (default: 50, max: 100).",
+      },
+      timestamp: {
+        type: "number",
+        description:
+          "Unix timestamp (seconds) to paginate from. Returns trades older than this timestamp.",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
 export function register(server: McpServer, client: BudaClient, _cache: MemoryCache): void {
   server.tool(
-    "get_trades",
-    "Get recent trade history for a Buda.com market. Each entry contains " +
-      "[timestamp_ms, amount, price, direction]. Direction is 'buy' or 'sell'.",
+    toolSchema.name,
+    toolSchema.description,
     {
       market_id: z
         .string()
@@ -30,6 +56,14 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
     },
     async ({ market_id, limit, timestamp }) => {
       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 (limit !== undefined) params.limit = limit;
         if (timestamp !== undefined) params.timestamp = timestamp;

package/src/tools/volume.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 } from "../cache.js";
+import { validateMarketId } from "../validation.js";
 import type { VolumeResponse } from "../types.js";
 
+export const toolSchema = {
+  name: "get_market_volume",
+  description:
+    "Get 24h and 7-day transacted volume for a Buda.com market. " +
+    "Returns ask (sell) and bid (buy) volumes in the market's base currency.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
 export function register(server: McpServer, client: BudaClient, _cache: MemoryCache): void {
   server.tool(
-    "get_market_volume",
-    "Get 24h and 7-day transacted volume for a Buda.com market. " +
-      "Returns ask (sell) and bid (buy) volumes in the market's base currency.",
+    toolSchema.name,
+    toolSchema.description,
     {
       market_id: z
         .string()
@@ -16,6 +33,14 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
     },
     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 data = await client.get<VolumeResponse>(
           `/markets/${market_id.toLowerCase()}/volume`,
         );

package/src/validation.ts

@@ -0,0 +1,16 @@
+const MARKET_ID_RE = /^[A-Z0-9]{2,10}-[A-Z0-9]{2,10}$/i;
+
+/**
+ * Validates a market ID against the expected BASE-QUOTE format.
+ * Returns an error message string if invalid, or null if valid.
+ */
+export function validateMarketId(id: string): string | null {
+  if (!MARKET_ID_RE.test(id)) {
+    return (
+      `Invalid market ID "${id}". ` +
+      `Expected format: BASE-QUOTE with 2–10 alphanumeric characters per part ` +
+      `(e.g. "BTC-CLP", "ETH-BTC").`
+    );
+  }
+  return null;
+}

package/src/version.ts

@@ -0,0 +1,8 @@
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const _dir = dirname(fileURLToPath(import.meta.url));
+export const VERSION: string = (
+  JSON.parse(readFileSync(join(_dir, "../package.json"), "utf8")) as { version: string }
+).version;

package/test/run-all.ts

@@ -2,9 +2,21 @@
  * Integration test: calls each Buda MCP tool directly via BudaClient
  * and prints a summary of the results.
  *
- * Run with: npm test
+ * Run with: npm run test:integration
+ * Skipped automatically when the Buda API is unreachable (CI without network).
  */
 
+// Connectivity pre-check — skip gracefully instead of failing CI when the API is unreachable.
+try {
+  await fetch("https://www.buda.com/api/v2/markets.json", {
+    signal: AbortSignal.timeout(3000),
+  });
+} catch {
+  console.log("\nBuda API is unreachable — skipping integration tests (no network or API down).");
+  console.log("Run unit tests only with: npm run test:unit");
+  process.exit(0);
+}
+
 import { BudaClient } from "../src/client.js";
 import type {
   MarketsResponse,