@guiie/buda-mcp 1.2.2 → 1.4.0

package/src/tools/orders.ts

@@ -2,13 +2,17 @@ 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";
+import { flattenAmount } from "../utils.js";
+import type { OrdersResponse, Amount } 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.",
+    "Returns orders for a given Buda.com market as flat typed objects. All monetary amounts are floats " +
+    "with separate _currency fields (e.g. amount + amount_currency). Filterable by state: pending, " +
+    "active, traded, canceled. Supports pagination via per and page. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Show my open limit orders on BTC-CLP.'",
   inputSchema: {
     type: "object" as const,
     properties: {
@@ -34,6 +38,10 @@ export const toolSchema = {
   },
 };
 
+function flattenAmountField(amount: Amount): { value: number; currency: string } {
+  return flattenAmount(amount);
+}
+
 export function register(server: McpServer, client: BudaClient): void {
   server.tool(
     toolSchema.name,
@@ -83,11 +91,44 @@ export function register(server: McpServer, client: BudaClient): void {
           Object.keys(params).length > 0 ? params : undefined,
         );
 
+        const orders = data.orders.map((o) => {
+          const amount = flattenAmountField(o.amount);
+          const originalAmount = flattenAmountField(o.original_amount);
+          const tradedAmount = flattenAmountField(o.traded_amount);
+          const totalExchanged = flattenAmountField(o.total_exchanged);
+          const paidFee = flattenAmountField(o.paid_fee);
+          const limitPrice = o.limit ? flattenAmountField(o.limit) : null;
+
+          return {
+            id: o.id,
+            type: o.type,
+            state: o.state,
+            created_at: o.created_at,
+            market_id: o.market_id,
+            fee_currency: o.fee_currency,
+            price_type: o.price_type,
+            order_type: o.order_type,
+            client_id: o.client_id,
+            limit_price: limitPrice ? limitPrice.value : null,
+            limit_price_currency: limitPrice ? limitPrice.currency : null,
+            amount: amount.value,
+            amount_currency: amount.currency,
+            original_amount: originalAmount.value,
+            original_amount_currency: originalAmount.currency,
+            traded_amount: tradedAmount.value,
+            traded_amount_currency: tradedAmount.currency,
+            total_exchanged: totalExchanged.value,
+            total_exchanged_currency: totalExchanged.currency,
+            paid_fee: paidFee.value,
+            paid_fee_currency: paidFee.currency,
+          };
+        });
+
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({ orders: data.orders, meta: data.meta }, null, 2),
+              text: JSON.stringify({ orders, meta: data.meta }, null, 2),
             },
           ],
         };

package/src/tools/price_history.ts

@@ -3,32 +3,17 @@ 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: string;
-  high: string;
-  low: string;
-  close: string;
-  volume: string;
-  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.",
+    "responses. Returns OHLCV candles (open/high/low/close as floats in quote currency; volume as float " +
+    "in base currency) for periods 1h, 4h, or 1d. Candle timestamps are UTC bucket boundaries. " +
+    "Example: 'Show me the hourly BTC-CLP price chart for the past 24 hours.'",
   inputSchema: {
     type: "object" as const,
     properties: {
@@ -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: price,
-              high: price,
-              low: price,
-              close: price,
-              volume: amount,
-              trade_count: 1,
-            });
-          } else {
-            const candle = buckets.get(bucketStart)!;
-            if (p > parseFloat(candle.high)) candle.high = price;
-            if (p < parseFloat(candle.low)) candle.low = price;
-            candle.close = price;
-            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(),

package/src/tools/simulate_order.ts

@@ -0,0 +1,182 @@
+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, MarketResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "simulate_order",
+  description:
+    "Simulates a buy or sell order on Buda.com using live ticker data — no order is placed. " +
+    "Returns estimated fill price, fee, total cost, and slippage vs mid-price. " +
+    "Omit 'price' for a market order simulation; supply 'price' for a limit order simulation. " +
+    "All outputs are labelled simulation: true — this tool never places a real order. " +
+    "Example: 'How much would it cost to buy 0.01 BTC on BTC-CLP right now?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+      },
+      side: {
+        type: "string",
+        description: "'buy' or 'sell'.",
+      },
+      amount: {
+        type: "number",
+        description: "Order size in base currency (e.g. BTC for BTC-CLP).",
+      },
+      price: {
+        type: "number",
+        description:
+          "Limit price in quote currency. Omit for a market order simulation.",
+      },
+    },
+    required: ["market_id", "side", "amount"],
+  },
+};
+
+type SimulateOrderArgs = {
+  market_id: string;
+  side: "buy" | "sell";
+  amount: number;
+  price?: number;
+};
+
+export async function handleSimulateOrder(
+  args: SimulateOrderArgs,
+  client: BudaClient,
+  cache: MemoryCache,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { market_id, side, amount, price } = args;
+
+  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, marketData] = await Promise.all([
+      cache.getOrFetch<TickerResponse>(
+        `ticker:${id}`,
+        CACHE_TTL.TICKER,
+        () => client.get<TickerResponse>(`/markets/${id}/ticker`),
+      ),
+      cache.getOrFetch<MarketResponse>(
+        `market:${id}`,
+        CACHE_TTL.MARKETS,
+        () => client.get<MarketResponse>(`/markets/${id}`),
+      ),
+    ]);
+
+    const ticker = tickerData.ticker;
+    const market = marketData.market;
+
+    const minAsk = parseFloat(ticker.min_ask[0]);
+    const maxBid = parseFloat(ticker.max_bid[0]);
+    const quoteCurrency = ticker.min_ask[1];
+
+    if (isNaN(minAsk) || isNaN(maxBid) || minAsk <= 0 || maxBid <= 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: "Unable to simulate: invalid or zero bid/ask values in ticker.",
+              code: "INVALID_TICKER",
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const mid = (minAsk + maxBid) / 2;
+    const takerFeeRate = parseFloat(market.taker_fee);
+    const orderTypeAssumed = price !== undefined ? "limit" : "market";
+
+    let estimatedFillPrice: number;
+
+    if (orderTypeAssumed === "market") {
+      estimatedFillPrice = side === "buy" ? minAsk : maxBid;
+    } else {
+      // Limit order: fill at provided price if it crosses the spread, otherwise at limit price
+      if (side === "buy") {
+        estimatedFillPrice = price! >= minAsk ? minAsk : price!;
+      } else {
+        estimatedFillPrice = price! <= maxBid ? maxBid : price!;
+      }
+    }
+
+    const grossValue = amount * estimatedFillPrice;
+    const feeAmount = parseFloat((grossValue * takerFeeRate).toFixed(8));
+    const totalCost = side === "buy"
+      ? parseFloat((grossValue + feeAmount).toFixed(8))
+      : parseFloat((grossValue - feeAmount).toFixed(8));
+
+    const slippageVsMidPct = parseFloat(
+      (((estimatedFillPrice - mid) / mid) * 100).toFixed(4),
+    );
+
+    const result = {
+      simulation: true,
+      market_id: ticker.market_id,
+      side,
+      amount,
+      order_type_assumed: orderTypeAssumed,
+      estimated_fill_price: parseFloat(estimatedFillPrice.toFixed(2)),
+      price_currency: quoteCurrency,
+      fee_amount: feeAmount,
+      fee_currency: quoteCurrency,
+      fee_rate_pct: parseFloat((takerFeeRate * 100).toFixed(3)),
+      total_cost: totalCost,
+      slippage_vs_mid_pct: slippageVsMidPct,
+      mid_price: parseFloat(mid.toFixed(2)),
+    };
+
+    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')."),
+      side: z
+        .enum(["buy", "sell"])
+        .describe("'buy' or 'sell'."),
+      amount: z
+        .number()
+        .positive()
+        .describe("Order size in base currency (e.g. BTC for BTC-CLP)."),
+      price: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Limit price in quote currency. Omit for a market order simulation."),
+    },
+    (args) => handleSimulateOrder(args, client, cache),
+  );
+}

package/src/tools/spread.ts

@@ -8,8 +8,10 @@ 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.",
+    "Returns the best bid, best ask, absolute spread, and spread percentage for a Buda.com market. " +
+    "All prices are floats in the quote currency (e.g. CLP). spread_percentage is a float in percent " +
+    "(e.g. 0.15 means 0.15%). Use this to evaluate liquidity before placing a large order. " +
+    "Example: 'Is BTC-CLP liquid enough to buy 10M CLP without significant slippage?'",
   inputSchema: {
     type: "object" as const,
     properties: {
@@ -70,12 +72,12 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
 
         const result = {
           market_id: ticker.market_id,
-          currency,
-          best_bid: bid.toString(),
-          best_ask: ask.toString(),
-          spread_absolute: spreadAbs.toFixed(2),
-          spread_percentage: spreadPct.toFixed(4) + "%",
-          last_price: ticker.last_price[0],
+          price_currency: currency,
+          best_bid: bid,
+          best_ask: ask,
+          spread_absolute: parseFloat(spreadAbs.toFixed(2)),
+          spread_percentage: parseFloat(spreadPct.toFixed(4)),
+          last_price: parseFloat(ticker.last_price[0]),
         };
 
         return {

package/src/tools/technical_indicators.ts

@@ -0,0 +1,282 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { validateMarketId } from "../validation.js";
+import { aggregateTradesToCandles } from "../utils.js";
+import type { TradesResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "get_technical_indicators",
+  description:
+    "Computes RSI (14), MACD (12/26/9), Bollinger Bands (20, 2σ), SMA 20, and SMA 50 " +
+    "from Buda trade history — no external data or libraries. " +
+    "Uses at least 500 trades for reliable results (set limit=1000 for maximum depth). " +
+    "Returns latest indicator values and signal interpretations (overbought/oversold, crossover, band position). " +
+    "If fewer than 50 candles are available after aggregation, returns a structured warning instead. " +
+    "Example: 'Is BTC-CLP RSI overbought on the 4-hour chart?'",
+  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', '4h', or '1d'. Default: '1h'.",
+      },
+      limit: {
+        type: "number",
+        description:
+          "Number of raw trades to fetch (default: 500, max: 1000). " +
+          "More trades = more candles = more reliable indicators.",
+      },
+    },
+    required: ["market_id"],
+  },
+};
+
+// ---- Pure math helpers ----
+
+function sma(values: number[], n: number): number {
+  const slice = values.slice(-n);
+  return slice.reduce((sum, v) => sum + v, 0) / slice.length;
+}
+
+function ema(values: number[], period: number): number[] {
+  if (values.length < period) return [];
+  const k = 2 / (period + 1);
+  const result: number[] = [];
+  // Seed with SMA of first `period` values
+  result.push(values.slice(0, period).reduce((s, v) => s + v, 0) / period);
+  for (let i = period; i < values.length; i++) {
+    result.push(values[i] * k + result[result.length - 1] * (1 - k));
+  }
+  return result;
+}
+
+function rsi(closes: number[], period: number = 14): number | null {
+  if (closes.length < period + 1) return null;
+  const gains: number[] = [];
+  const losses: number[] = [];
+  for (let i = 1; i < closes.length; i++) {
+    const diff = closes[i] - closes[i - 1];
+    gains.push(diff > 0 ? diff : 0);
+    losses.push(diff < 0 ? -diff : 0);
+  }
+  // Use simple average for initial, then Wilder's smoothing
+  let avgGain = gains.slice(0, period).reduce((s, v) => s + v, 0) / period;
+  let avgLoss = losses.slice(0, period).reduce((s, v) => s + v, 0) / period;
+  for (let i = period; i < gains.length; i++) {
+    avgGain = (avgGain * (period - 1) + gains[i]) / period;
+    avgLoss = (avgLoss * (period - 1) + losses[i]) / period;
+  }
+  if (avgLoss === 0) return 100;
+  const rs = avgGain / avgLoss;
+  return parseFloat((100 - 100 / (1 + rs)).toFixed(2));
+}
+
+interface MacdResult {
+  line: number;
+  signal: number;
+  histogram: number;
+  prev_histogram: number | null;
+}
+
+function macd(
+  closes: number[],
+  fast: number = 12,
+  slow: number = 26,
+  signalPeriod: number = 9,
+): MacdResult | null {
+  if (closes.length < slow + signalPeriod) return null;
+  const ema12 = ema(closes, fast);
+  const ema26 = ema(closes, slow);
+  // Align: ema26 starts at index (slow-1) of closes; ema12 starts at index (fast-1)
+  // The MACD line length = ema26.length (shorter)
+  const offset = slow - fast;
+  const macdLine: number[] = ema26.map((e26, i) => ema12[i + offset] - e26);
+  const signalLine = ema(macdLine, signalPeriod);
+  if (signalLine.length === 0) return null;
+  const lastMacd = macdLine[macdLine.length - 1];
+  const lastSignal = signalLine[signalLine.length - 1];
+  const histogram = lastMacd - lastSignal;
+  const prevHistogram =
+    macdLine.length > 1 && signalLine.length > 1
+      ? macdLine[macdLine.length - 2] - signalLine[signalLine.length - 2]
+      : null;
+  return {
+    line: parseFloat(lastMacd.toFixed(2)),
+    signal: parseFloat(lastSignal.toFixed(2)),
+    histogram: parseFloat(histogram.toFixed(2)),
+    prev_histogram: prevHistogram !== null ? parseFloat(prevHistogram.toFixed(2)) : null,
+  };
+}
+
+interface BollingerResult {
+  upper: number;
+  mid: number;
+  lower: number;
+}
+
+function bollingerBands(closes: number[], period: number = 20, stdMult: number = 2): BollingerResult | null {
+  if (closes.length < period) return null;
+  const slice = closes.slice(-period);
+  const mid = slice.reduce((s, v) => s + v, 0) / period;
+  const variance = slice.reduce((s, v) => s + (v - mid) ** 2, 0) / period;
+  const std = Math.sqrt(variance);
+  return {
+    upper: parseFloat((mid + stdMult * std).toFixed(2)),
+    mid: parseFloat(mid.toFixed(2)),
+    lower: parseFloat((mid - stdMult * std).toFixed(2)),
+  };
+}
+
+// ---- Tool handler ----
+
+const MIN_CANDLES = 50;
+
+type TechnicalIndicatorsArgs = {
+  market_id: string;
+  period: "1h" | "4h" | "1d";
+  limit?: number;
+};
+
+export async function handleTechnicalIndicators(
+  args: TechnicalIndicatorsArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { market_id, period, limit } = args;
+
+  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 tradesLimit = Math.max(limit ?? 500, 500);
+
+    const data = await client.get<TradesResponse>(
+      `/markets/${id}/trades`,
+      { limit: tradesLimit },
+    );
+
+    const candles = aggregateTradesToCandles(data.trades.entries, period);
+    const closes = candles.map((c) => c.close);
+
+    if (candles.length < MIN_CANDLES) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              market_id: market_id.toUpperCase(),
+              period,
+              indicators: null,
+              warning: "insufficient_data",
+              candles_available: candles.length,
+              minimum_required: MIN_CANDLES,
+            }),
+          },
+        ],
+      };
+    }
+
+    const rsiValue = rsi(closes, 14);
+    const macdResult = macd(closes, 12, 26, 9);
+    const bbResult = bollingerBands(closes, 20, 2);
+    const sma20 = parseFloat(sma(closes, 20).toFixed(2));
+    const sma50 = parseFloat(sma(closes, 50).toFixed(2));
+    const lastClose = closes[closes.length - 1];
+
+    // Signal interpretations
+    const rsiSignal: "overbought" | "oversold" | "neutral" =
+      rsiValue !== null && rsiValue > 70
+        ? "overbought"
+        : rsiValue !== null && rsiValue < 30
+          ? "oversold"
+          : "neutral";
+
+    let macdSignal: "bullish_crossover" | "bearish_crossover" | "neutral" = "neutral";
+    if (macdResult && macdResult.prev_histogram !== null) {
+      if (macdResult.histogram > 0 && macdResult.prev_histogram <= 0) {
+        macdSignal = "bullish_crossover";
+      } else if (macdResult.histogram < 0 && macdResult.prev_histogram >= 0) {
+        macdSignal = "bearish_crossover";
+      }
+    }
+
+    const bbSignal: "above_upper" | "below_lower" | "within_bands" =
+      bbResult && lastClose > bbResult.upper
+        ? "above_upper"
+        : bbResult && lastClose < bbResult.lower
+          ? "below_lower"
+          : "within_bands";
+
+    const result = {
+      market_id: market_id.toUpperCase(),
+      period,
+      candles_used: candles.length,
+      indicators: {
+        rsi: rsiValue,
+        macd: macdResult
+          ? { line: macdResult.line, signal: macdResult.signal, histogram: macdResult.histogram }
+          : null,
+        bollinger_bands: bbResult,
+        sma_20: sma20,
+        sma_50: sma50,
+      },
+      signals: {
+        rsi_signal: rsiSignal,
+        macd_signal: macdSignal,
+        bb_signal: bbSignal,
+      },
+      disclaimer:
+        "Technical indicators are computed from Buda trade history. 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): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      market_id: z
+        .string()
+        .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC')."),
+      period: z
+        .enum(["1h", "4h", "1d"])
+        .default("1h")
+        .describe("Candle period: '1h', '4h', or '1d'. Default: '1h'."),
+      limit: z
+        .number()
+        .int()
+        .min(500)
+        .max(1000)
+        .optional()
+        .describe(
+          "Number of raw trades to fetch (default: 500, max: 1000). " +
+            "More trades = more candles = more reliable indicators.",
+        ),
+    },
+    (args) => handleTechnicalIndicators(args, client),
+  );
+}