@guiie/buda-mcp 1.3.0 → 1.4.1

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(),

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) / 100;
+    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/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),
+  );
+}

package/src/types.ts

@@ -133,3 +133,15 @@ export interface OrdersResponse {
     total_pages: number;
   };
 }
+
+// ----- OHLCV Candles -----
+
+export interface OhlcvCandle {
+  time: string;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+  trade_count: number;
+}

package/src/utils.ts

@@ -1,4 +1,4 @@
-import type { Amount } from "./types.js";
+import type { Amount, OhlcvCandle } from "./types.js";
 
 /**
  * Flattens a Buda API Amount tuple [value_string, currency] into a typed object.
@@ -19,3 +19,55 @@ export function getLiquidityRating(spreadPct: number): "high" | "medium" | "low"
   if (spreadPct <= 1.0) return "medium";
   return "low";
 }
+
+const PERIOD_MS: Record<string, number> = {
+  "1h": 60 * 60 * 1000,
+  "4h": 4 * 60 * 60 * 1000,
+  "1d": 24 * 60 * 60 * 1000,
+};
+
+/**
+ * Aggregates raw Buda trade entries (newest-first) into OHLCV candles for the given period.
+ * Entries must be in the format [timestamp_ms, amount, price, direction].
+ * Returns candles sorted ascending by bucket start time.
+ */
+export function aggregateTradesToCandles(
+  entries: [string, string, string, string][],
+  period: string,
+): OhlcvCandle[] {
+  const periodMs = PERIOD_MS[period];
+  if (!periodMs) throw new Error(`Unknown period: ${period}`);
+
+  const sorted = [...entries].sort(([a], [b]) => parseInt(a, 10) - parseInt(b, 10));
+  const buckets = new Map<number, OhlcvCandle>();
+
+  for (const [tsMs, amount, price] of sorted) {
+    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++;
+    }
+  }
+
+  return Array.from(buckets.entries())
+    .sort(([a], [b]) => a - b)
+    .map(([, candle]) => candle);
+}