@guiie/buda-mcp 1.2.2 → 1.4.0

package/src/tools/dead_mans_switch.ts

@@ -0,0 +1,314 @@
+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, OrderResponse } from "../types.js";
+
+// ---- Module-level timer state (persists across HTTP requests / tool invocations) ----
+
+interface TimerEntry {
+  timeout: ReturnType<typeof setTimeout>;
+  expiresAt: number;
+  ttlSeconds: number;
+}
+
+const timers = new Map<string, TimerEntry>();
+
+async function cancelAllOrdersForMarket(marketId: string, client: BudaClient): Promise<void> {
+  try {
+    const data = await client.get<OrdersResponse>(
+      `/markets/${marketId}/orders`,
+      { state: "pending", per: 300 },
+    );
+    const orders = data.orders ?? [];
+    await Promise.allSettled(
+      orders.map((order) =>
+        client.put<OrderResponse>(`/orders/${order.id}`, { state: "canceling" }),
+      ),
+    );
+    timers.delete(marketId);
+  } catch {
+    // Swallow errors — the timer has fired; we cannot surface them to the caller
+    timers.delete(marketId);
+  }
+}
+
+function armTimer(marketId: string, ttlSeconds: number, client: BudaClient): TimerEntry {
+  const existing = timers.get(marketId);
+  if (existing) clearTimeout(existing.timeout);
+
+  const expiresAt = Date.now() + ttlSeconds * 1000;
+  const timeout = setTimeout(() => {
+    void cancelAllOrdersForMarket(marketId, client);
+  }, ttlSeconds * 1000);
+
+  const entry: TimerEntry = { timeout, expiresAt, ttlSeconds };
+  timers.set(marketId, entry);
+  return entry;
+}
+
+// ---- Tool schemas ----
+
+export const toolSchema = {
+  name: "schedule_cancel_all",
+  description:
+    "WARNING: timer state is lost on server restart. Not suitable as a production dead man's switch " +
+    "on hosted deployments (e.g. Railway). Use only on locally-run instances.\n\n" +
+    "Arms an in-memory dead man's switch: if not renewed within ttl_seconds, all open orders for the " +
+    "market are automatically cancelled. Requires confirmation_token='CONFIRM' to activate. " +
+    "Use renew_cancel_timer to reset the countdown, or disarm_cancel_timer to cancel without touching orders. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID to protect (e.g. 'BTC-CLP').",
+      },
+      ttl_seconds: {
+        type: "number",
+        description: "Seconds before all orders are cancelled if not renewed (10–300).",
+      },
+      confirmation_token: {
+        type: "string",
+        description: "Must equal exactly 'CONFIRM' (case-sensitive) to arm the switch.",
+      },
+    },
+    required: ["market_id", "ttl_seconds", "confirmation_token"],
+  },
+};
+
+export const renewToolSchema = {
+  name: "renew_cancel_timer",
+  description:
+    "Resets the dead man's switch TTL for a market, preventing automatic order cancellation. " +
+    "No confirmation required. Requires an active timer set by schedule_cancel_all. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID whose timer should be renewed (e.g. 'BTC-CLP').",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
+export const disarmToolSchema = {
+  name: "disarm_cancel_timer",
+  description:
+    "Disarms the dead man's switch for a market without cancelling any orders. " +
+    "No confirmation required. Safe to call even if no timer is active. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID whose timer should be disarmed (e.g. 'BTC-CLP').",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
+// ---- Handlers (exported for unit tests) ----
+
+type ScheduleArgs = {
+  market_id: string;
+  ttl_seconds: number;
+  confirmation_token: string;
+};
+
+export async function handleScheduleCancelAll(
+  args: ScheduleArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { market_id, ttl_seconds, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Dead man's switch not armed. confirmation_token must equal 'CONFIRM' to activate. " +
+              "Review the parameters and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            market_id,
+            ttl_seconds,
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  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 entry = armTimer(id, ttl_seconds, client);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          active: true,
+          market_id: market_id.toUpperCase(),
+          expires_at: new Date(entry.expiresAt).toISOString(),
+          ttl_seconds,
+          warning: "in-memory only — timer is lost on server restart. Not suitable for hosted deployments.",
+        }),
+      },
+    ],
+  };
+}
+
+type MarketOnlyArgs = { market_id: string };
+
+export function handleRenewCancelTimer(
+  { market_id }: MarketOnlyArgs,
+  client: BudaClient,
+): { content: Array<{ type: "text"; text: string }>; isError?: boolean } {
+  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 existing = timers.get(id);
+  if (!existing) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: `No active dead man's switch for market ${market_id.toUpperCase()}. Arm one first with schedule_cancel_all.`,
+            code: "NO_ACTIVE_TIMER",
+            market_id: market_id.toUpperCase(),
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const entry = armTimer(id, existing.ttlSeconds, client);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          active: true,
+          market_id: market_id.toUpperCase(),
+          expires_at: new Date(entry.expiresAt).toISOString(),
+          ttl_seconds: entry.ttlSeconds,
+        }),
+      },
+    ],
+  };
+}
+
+export function handleDisarmCancelTimer(
+  { market_id }: MarketOnlyArgs,
+): { content: Array<{ type: "text"; text: string }>; isError?: boolean } {
+  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 existing = timers.get(id);
+  if (!existing) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            disarmed: false,
+            market_id: market_id.toUpperCase(),
+            note: "No active timer for this market.",
+          }),
+        },
+      ],
+    };
+  }
+
+  clearTimeout(existing.timeout);
+  timers.delete(id);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          disarmed: true,
+          market_id: market_id.toUpperCase(),
+        }),
+      },
+    ],
+  };
+}
+
+// ---- Registration ----
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      market_id: z
+        .string()
+        .describe("Market ID to protect (e.g. 'BTC-CLP')."),
+      ttl_seconds: z
+        .number()
+        .int()
+        .min(10)
+        .max(300)
+        .describe("Seconds before all orders are cancelled if not renewed (10–300)."),
+      confirmation_token: z
+        .string()
+        .describe("Must equal exactly 'CONFIRM' (case-sensitive) to arm the switch."),
+    },
+    (args) => handleScheduleCancelAll(args, client),
+  );
+
+  server.tool(
+    renewToolSchema.name,
+    renewToolSchema.description,
+    {
+      market_id: z
+        .string()
+        .describe("Market ID whose timer should be renewed (e.g. 'BTC-CLP')."),
+    },
+    (args) => handleRenewCancelTimer(args, client),
+  );
+
+  server.tool(
+    disarmToolSchema.name,
+    disarmToolSchema.description,
+    {
+      market_id: z
+        .string()
+        .describe("Market ID whose timer should be disarmed (e.g. 'BTC-CLP')."),
+    },
+    (args) => handleDisarmCancelTimer(args),
+  );
+}

package/src/tools/market_sentiment.ts

@@ -0,0 +1,141 @@
+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, VolumeResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "get_market_sentiment",
+  description:
+    "Computes a composite sentiment score (−100 to +100) for a Buda.com market based on " +
+    "24h price variation (40%), volume vs 7-day average (35%), and bid/ask spread vs baseline (25%). " +
+    "Returns a score, a label (bearish/neutral/bullish), and a full component breakdown. " +
+    "Example: 'Is the BTC-CLP market currently bullish or bearish?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC', 'BTC-USDT').",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function isStablecoinPair(marketId: string): boolean {
+  return /-(USDT|USDC|DAI|TUSD)$/i.test(marketId);
+}
+
+type MarketSentimentArgs = { market_id: string };
+
+export async function handleMarketSentiment(
+  { market_id }: MarketSentimentArgs,
+  client: BudaClient,
+  cache: MemoryCache,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const validationError = validateMarketId(market_id);
+  if (validationError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+      isError: true,
+    };
+  }
+
+  try {
+    const id = market_id.toLowerCase();
+
+    const [tickerData, volumeData] = await Promise.all([
+      cache.getOrFetch<TickerResponse>(
+        `ticker:${id}`,
+        CACHE_TTL.TICKER,
+        () => client.get<TickerResponse>(`/markets/${id}/ticker`),
+      ),
+      client.get<VolumeResponse>(`/markets/${id}/volume`),
+    ]);
+
+    const ticker = tickerData.ticker;
+    const vol = volumeData.volume;
+
+    const bid = parseFloat(ticker.max_bid[0]);
+    const ask = parseFloat(ticker.min_ask[0]);
+    const priceVariation24h = parseFloat(ticker.price_variation_24h);
+
+    const ask24h = parseFloat(vol.ask_volume_24h[0]);
+    const bid24h = parseFloat(vol.bid_volume_24h[0]);
+    const ask7d = parseFloat(vol.ask_volume_7d[0]);
+    const bid7d = parseFloat(vol.bid_volume_7d[0]);
+
+    const spreadPct = ask > 0 ? ((ask - bid) / ask) * 100 : 0;
+    const spreadBaseline = isStablecoinPair(market_id) ? 0.3 : 1.0;
+
+    const volume24h = ask24h + bid24h;
+    const volume7d = ask7d + bid7d;
+    const volumeRatio = volume7d > 0 ? (volume24h * 7) / volume7d : 1;
+
+    // Price component: ±5% daily change → ±100 on this sub-score
+    const priceRaw = clamp(priceVariation24h * 2000, -100, 100);
+    const priceScore = parseFloat((priceRaw * 0.4).toFixed(4));
+
+    // Volume component: ratio vs 7d daily average
+    const volumeRaw = clamp((volumeRatio - 1) * 100, -100, 100);
+    const volumeScore = parseFloat((volumeRaw * 0.35).toFixed(4));
+
+    // Spread component: tighter spread is bullish
+    const spreadRaw = clamp((1 - spreadPct / spreadBaseline) * 100, -100, 100);
+    const spreadScore = parseFloat((spreadRaw * 0.25).toFixed(4));
+
+    const score = parseFloat((priceScore + volumeScore + spreadScore).toFixed(1));
+    const label: "bearish" | "neutral" | "bullish" =
+      score < -20 ? "bearish" : score > 20 ? "bullish" : "neutral";
+
+    const result = {
+      market_id: ticker.market_id,
+      score,
+      label,
+      component_breakdown: {
+        price_variation_24h_pct: parseFloat((priceVariation24h * 100).toFixed(4)),
+        volume_ratio: parseFloat(volumeRatio.toFixed(4)),
+        spread_pct: parseFloat(spreadPct.toFixed(4)),
+        spread_baseline_pct: spreadBaseline,
+        price_score: priceScore,
+        volume_score: volumeScore,
+        spread_score: spreadScore,
+      },
+      data_timestamp: new Date().toISOString(),
+      disclaimer:
+        "Sentiment is derived from market microstructure data only. Not investment advice.",
+    };
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, 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, cache: MemoryCache): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      market_id: z
+        .string()
+        .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC', 'BTC-USDT')."),
+    },
+    (args) => handleMarketSentiment(args, client, cache),
+  );
+}

package/src/tools/market_summary.ts

@@ -0,0 +1,124 @@
+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 { flattenAmount, getLiquidityRating } from "../utils.js";
+import type { TickerResponse, VolumeResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "get_market_summary",
+  description:
+    "One-call summary of everything relevant about a market: last price, best bid/ask, spread %, " +
+    "24h volume, 24h and 7d price change, and a liquidity_rating ('high' / 'medium' / 'low' based on " +
+    "spread thresholds: < 0.3% = high, 0.3–1% = medium, > 1% = low). All prices and volumes are floats. " +
+    "Best first tool to call when a user asks about any specific market. " +
+    "Example: 'Give me a complete overview of the BTC-CLP market right now.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-COP', 'BTC-PEN').",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
+export interface MarketSummaryResult {
+  market_id: string;
+  last_price: number;
+  last_price_currency: string;
+  bid: number;
+  ask: number;
+  spread_pct: number;
+  volume_24h: number;
+  volume_24h_currency: string;
+  price_change_24h: number;
+  price_change_7d: number;
+  liquidity_rating: "high" | "medium" | "low";
+}
+
+interface MarketSummaryInput {
+  market_id: string;
+}
+
+export async function handleMarketSummary(
+  { market_id }: MarketSummaryInput,
+  client: BudaClient,
+  cache: MemoryCache,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  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();
+
+    // Fetch ticker and volume in parallel
+    const [tickerData, volumeData] = await Promise.all([
+      cache.getOrFetch<TickerResponse>(
+        `ticker:${id}`,
+        CACHE_TTL.TICKER,
+        () => client.get<TickerResponse>(`/markets/${id}/ticker`),
+      ),
+      client.get<VolumeResponse>(`/markets/${id}/volume`),
+    ]);
+
+    const t = tickerData.ticker;
+    const v = volumeData.volume;
+
+    const lastPrice = flattenAmount(t.last_price);
+    const bid = parseFloat(t.max_bid[0]);
+    const ask = parseFloat(t.min_ask[0]);
+    const volume24h = flattenAmount(v.ask_volume_24h);
+
+    const spreadAbs = ask - bid;
+    const spreadPct = ask > 0 ? parseFloat(((spreadAbs / ask) * 100).toFixed(4)) : 0;
+
+    const result: MarketSummaryResult = {
+      market_id: t.market_id,
+      last_price: lastPrice.value,
+      last_price_currency: lastPrice.currency,
+      bid,
+      ask,
+      spread_pct: spreadPct,
+      volume_24h: volume24h.value,
+      volume_24h_currency: volume24h.currency,
+      price_change_24h: parseFloat((parseFloat(t.price_variation_24h) * 100).toFixed(4)),
+      price_change_7d: parseFloat((parseFloat(t.price_variation_7d) * 100).toFixed(4)),
+      liquidity_rating: getLiquidityRating(spreadPct),
+    };
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, 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, cache: MemoryCache): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      market_id: z
+        .string()
+        .describe("Market ID (e.g. 'BTC-CLP', 'ETH-COP', 'BTC-PEN')."),
+    },
+    (args) => handleMarketSummary(args, client, cache),
+  );
+}

package/src/tools/markets.ts

@@ -8,8 +8,10 @@ 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.",
+    "Lists all available trading pairs on Buda.com, or returns details for a specific market " +
+    "(base/quote currencies, taker/maker fees as decimals, minimum order size in base currency, " +
+    "and fee discount tiers). Omit market_id to get all ~26 markets at once. " +
+    "Example: 'What is the taker fee and minimum order size for BTC-CLP?'",
   inputSchema: {
     type: "object" as const,
     properties: {

package/src/tools/orderbook.ts

@@ -8,8 +8,10 @@ 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.",
+    "Returns the current order book for a Buda.com market as typed objects with float price and amount fields. " +
+    "Bids are sorted highest-price first; asks lowest-price first. " +
+    "Prices are in the quote currency; amounts are in the base currency. " +
+    "Example: 'What are the top 5 buy and sell orders for BTC-CLP right now?'",
   inputSchema: {
     type: "object" as const,
     properties: {
@@ -59,9 +61,18 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
         );
 
         const book = data.order_book;
+        const bids = limit ? book.bids.slice(0, limit) : book.bids;
+        const asks = limit ? book.asks.slice(0, limit) : book.asks;
+
         const result = {
-          bids: limit ? book.bids.slice(0, limit) : book.bids,
-          asks: limit ? book.asks.slice(0, limit) : book.asks,
+          bids: bids.map(([price, amount]) => ({
+            price: parseFloat(price),
+            amount: parseFloat(amount),
+          })),
+          asks: asks.map(([price, amount]) => ({
+            price: parseFloat(price),
+            amount: parseFloat(amount),
+          })),
           bid_count: book.bids.length,
           ask_count: book.asks.length,
         };