@guiie/buda-mcp 1.3.0 → 1.4.0

package/src/tools/calculate_position_size.ts

@@ -0,0 +1,141 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { validateMarketId } from "../validation.js";
+
+export const toolSchema = {
+  name: "calculate_position_size",
+  description:
+    "Calculates position size based on your capital, risk tolerance, entry price, and stop-loss. " +
+    "Determines how many units to buy or sell so that a stop-loss hit costs exactly risk_pct% of capital. " +
+    "Fully client-side — no API call is made. " +
+    "Example: 'How many BTC can I buy on BTC-CLP if I have 1,000,000 CLP, risk 2%, entry 80,000,000 CLP, stop at 78,000,000 CLP?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-COP'). Used to derive the quote currency.",
+      },
+      capital: {
+        type: "number",
+        description: "Total available capital in the quote currency (e.g. CLP for BTC-CLP).",
+      },
+      risk_pct: {
+        type: "number",
+        description: "Percentage of capital to risk on this trade (0.1–10, e.g. 2 = 2%).",
+      },
+      entry_price: {
+        type: "number",
+        description: "Planned entry price in quote currency.",
+      },
+      stop_loss_price: {
+        type: "number",
+        description:
+          "Stop-loss price in quote currency. Must be below entry for buys, above entry for sells.",
+      },
+    },
+    required: ["market_id", "capital", "risk_pct", "entry_price", "stop_loss_price"],
+  },
+};
+
+type CalculatePositionSizeArgs = {
+  market_id: string;
+  capital: number;
+  risk_pct: number;
+  entry_price: number;
+  stop_loss_price: number;
+};
+
+export function handleCalculatePositionSize(
+  args: CalculatePositionSizeArgs,
+): { content: Array<{ type: "text"; text: string }>; isError?: boolean } {
+  const { market_id, capital, risk_pct, entry_price, stop_loss_price } = args;
+
+  const validationError = validateMarketId(market_id);
+  if (validationError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+      isError: true,
+    };
+  }
+
+  if (stop_loss_price === entry_price) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "stop_loss_price must differ from entry_price.",
+            code: "INVALID_STOP_LOSS",
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const quoteCurrency = market_id.split("-")[1].toUpperCase();
+  const baseCurrency = market_id.split("-")[0].toUpperCase();
+  const side: "buy" | "sell" = stop_loss_price < entry_price ? "buy" : "sell";
+
+  const capitalAtRisk = capital * (risk_pct / 100);
+  const riskPerUnit = Math.abs(entry_price - stop_loss_price);
+  const units = capitalAtRisk / riskPerUnit;
+  const positionValue = units * entry_price;
+  const feeImpact = parseFloat((positionValue * 0.008).toFixed(8));
+
+  const riskRewardNote =
+    `${side === "buy" ? "Buy" : "Sell"} ${units.toFixed(8)} ${baseCurrency} at ${entry_price} ${quoteCurrency} ` +
+    `with stop at ${stop_loss_price} ${quoteCurrency}. ` +
+    `Risking ${risk_pct}% of capital (${capitalAtRisk.toFixed(2)} ${quoteCurrency}) ` +
+    `on a ${riskPerUnit.toFixed(2)} ${quoteCurrency}/unit move. ` +
+    `Estimated entry fee: ${feeImpact.toFixed(2)} ${quoteCurrency} (0.8% taker, conservative estimate).`;
+
+  const result = {
+    market_id: market_id.toUpperCase(),
+    side,
+    units: parseFloat(units.toFixed(8)),
+    base_currency: baseCurrency,
+    capital_at_risk: parseFloat(capitalAtRisk.toFixed(2)),
+    position_value: parseFloat(positionValue.toFixed(2)),
+    fee_impact: feeImpact,
+    fee_currency: quoteCurrency,
+    risk_reward_note: riskRewardNote,
+  };
+
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+export function register(server: McpServer): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      market_id: z
+        .string()
+        .describe("Market ID (e.g. 'BTC-CLP', 'ETH-COP'). Used to derive the quote currency."),
+      capital: z
+        .number()
+        .positive()
+        .describe("Total available capital in the quote currency (e.g. CLP for BTC-CLP)."),
+      risk_pct: z
+        .number()
+        .min(0.1)
+        .max(10)
+        .describe("Percentage of capital to risk on this trade (0.1–10, e.g. 2 = 2%)."),
+      entry_price: z
+        .number()
+        .positive()
+        .describe("Planned entry price in quote currency."),
+      stop_loss_price: z
+        .number()
+        .positive()
+        .describe(
+          "Stop-loss price in quote currency. Must be below entry for buys, above entry for sells.",
+        ),
+    },
+    (args) => handleCalculatePositionSize(args),
+  );
+}

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/price_history.ts

@@ -3,24 +3,9 @@ import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { MemoryCache } from "../cache.js";
 import { validateMarketId } from "../validation.js";
+import { aggregateTradesToCandles } from "../utils.js";
 import type { TradesResponse } from "../types.js";
 
-const PERIOD_MS: Record<string, number> = {
-  "1h": 60 * 60 * 1000,
-  "4h": 4 * 60 * 60 * 1000,
-  "1d": 24 * 60 * 60 * 1000,
-};
-
-interface OhlcvCandle {
-  time: string;
-  open: number;
-  high: number;
-  low: number;
-  close: number;
-  volume: number;
-  trade_count: number;
-}
-
 export const toolSchema = {
   name: "get_price_history",
   description:
@@ -104,44 +89,7 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
           };
         }
 
-        // Buda returns trades newest-first; sort ascending so open = first chronological price
-        // and close = last chronological price within each candle bucket.
-        const sortedEntries = [...entries].sort(
-          ([a], [b]) => parseInt(a, 10) - parseInt(b, 10),
-        );
-
-        const periodMs = PERIOD_MS[period];
-        const buckets = new Map<number, OhlcvCandle>();
-
-        for (const [tsMs, amount, price, _direction] of sortedEntries) {
-          const ts = parseInt(tsMs, 10);
-          const bucketStart = Math.floor(ts / periodMs) * periodMs;
-          const p = parseFloat(price);
-          const v = parseFloat(amount);
-
-          if (!buckets.has(bucketStart)) {
-            buckets.set(bucketStart, {
-              time: new Date(bucketStart).toISOString(),
-              open: p,
-              high: p,
-              low: p,
-              close: p,
-              volume: v,
-              trade_count: 1,
-            });
-          } else {
-            const candle = buckets.get(bucketStart)!;
-            if (p > candle.high) candle.high = p;
-            if (p < candle.low) candle.low = p;
-            candle.close = p;
-            candle.volume = parseFloat((candle.volume + v).toFixed(8));
-            candle.trade_count++;
-          }
-        }
-
-        const candles = Array.from(buckets.entries())
-          .sort(([a], [b]) => a - b)
-          .map(([, candle]) => candle);
+        const candles = aggregateTradesToCandles(entries, period);
 
         const result = {
           market_id: market_id.toUpperCase(),