@guiie/buda-mcp 1.2.1 → 1.3.0

package/src/tools/price_history.ts

@@ -13,11 +13,11 @@ const PERIOD_MS: Record<string, number> = {
 
 interface OhlcvCandle {
   time: string;
-  open: string;
-  high: string;
-  low: string;
-  close: string;
-  volume: string;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
   trade_count: number;
 }
 
@@ -26,9 +26,9 @@ export const toolSchema = {
   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: {
@@ -122,19 +122,19 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
           if (!buckets.has(bucketStart)) {
             buckets.set(bucketStart, {
               time: new Date(bucketStart).toISOString(),
-              open: price,
-              high: price,
-              low: price,
-              close: price,
-              volume: amount,
+              open: p,
+              high: p,
+              low: p,
+              close: p,
+              volume: v,
               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);
+            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++;
           }
         }

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

@@ -3,13 +3,16 @@ import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { MemoryCache, CACHE_TTL } from "../cache.js";
 import { validateMarketId } from "../validation.js";
+import { flattenAmount } from "../utils.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.",
+    "Returns the current market snapshot for a Buda.com market: last traded price, best bid, " +
+    "best ask, 24h volume, and price change over 24h and 7d. All prices are floats in the quote " +
+    "currency (e.g. CLP for BTC-CLP). price_variation_24h is a decimal fraction (0.012 = +1.2%). " +
+    "Example: 'What is the current Bitcoin price in Chilean pesos?'",
   inputSchema: {
     type: "object" as const,
     properties: {
@@ -47,8 +50,29 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
           CACHE_TTL.TICKER,
           () => client.get<TickerResponse>(`/markets/${id}/ticker`),
         );
+
+        const t = data.ticker;
+        const lastPrice = flattenAmount(t.last_price);
+        const minAsk = flattenAmount(t.min_ask);
+        const maxBid = flattenAmount(t.max_bid);
+        const volume = flattenAmount(t.volume);
+
+        const result = {
+          market_id: t.market_id,
+          last_price: lastPrice.value,
+          last_price_currency: lastPrice.currency,
+          min_ask: minAsk.value,
+          min_ask_currency: minAsk.currency,
+          max_bid: maxBid.value,
+          max_bid_currency: maxBid.currency,
+          volume: volume.value,
+          volume_currency: volume.currency,
+          price_variation_24h: parseFloat(t.price_variation_24h),
+          price_variation_7d: parseFloat(t.price_variation_7d),
+        };
+
         return {
-          content: [{ type: "text", text: JSON.stringify(data.ticker, null, 2) }],
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
       } catch (err) {
         const msg =

package/src/tools/trades.ts

@@ -8,8 +8,10 @@ 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'.",
+    "Returns recent trade history for a Buda.com market as typed objects. Each entry has " +
+    "timestamp_ms (integer), amount (float, base currency), price (float, quote currency), " +
+    "and direction ('buy' or 'sell'). " +
+    "Example: 'What was the last executed price for BTC-CLP and was it a buy or sell?'",
   inputSchema: {
     type: "object" as const,
     properties: {
@@ -73,8 +75,21 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
           Object.keys(params).length > 0 ? params : undefined,
         );
 
+        const t = data.trades;
+        const result = {
+          timestamp: t.timestamp,
+          last_timestamp: t.last_timestamp,
+          market_id: t.market_id,
+          entries: t.entries.map(([tsMs, amount, price, direction]) => ({
+            timestamp_ms: parseInt(tsMs, 10),
+            amount: parseFloat(amount),
+            price: parseFloat(price),
+            direction,
+          })),
+        };
+
         return {
-          content: [{ type: "text", text: JSON.stringify(data.trades, null, 2) }],
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
       } catch (err) {
         const msg =

package/src/tools/volume.ts

@@ -3,13 +3,15 @@ import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { MemoryCache } from "../cache.js";
 import { validateMarketId } from "../validation.js";
+import { flattenAmount } from "../utils.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.",
+    "Returns 24h and 7-day transacted volume for a Buda.com market, split by buy (bid) and sell (ask) side. " +
+    "All volume values are floats in the base currency (e.g. BTC for BTC-CLP). " +
+    "Example: 'How much Bitcoin was sold on BTC-CLP in the last 24 hours?'",
   inputSchema: {
     type: "object" as const,
     properties: {
@@ -44,8 +46,27 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
         const data = await client.get<VolumeResponse>(
           `/markets/${market_id.toLowerCase()}/volume`,
         );
+
+        const v = data.volume;
+        const ask24 = flattenAmount(v.ask_volume_24h);
+        const ask7d = flattenAmount(v.ask_volume_7d);
+        const bid24 = flattenAmount(v.bid_volume_24h);
+        const bid7d = flattenAmount(v.bid_volume_7d);
+
+        const result = {
+          market_id: v.market_id,
+          ask_volume_24h: ask24.value,
+          ask_volume_24h_currency: ask24.currency,
+          ask_volume_7d: ask7d.value,
+          ask_volume_7d_currency: ask7d.currency,
+          bid_volume_24h: bid24.value,
+          bid_volume_24h_currency: bid24.currency,
+          bid_volume_7d: bid7d.value,
+          bid_volume_7d_currency: bid7d.currency,
+        };
+
         return {
-          content: [{ type: "text", text: JSON.stringify(data.volume, null, 2) }],
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
       } catch (err) {
         const msg =

package/src/utils.ts

@@ -0,0 +1,21 @@
+import type { Amount } from "./types.js";
+
+/**
+ * Flattens a Buda API Amount tuple [value_string, currency] into a typed object.
+ * All numeric strings are cast to float via parseFloat.
+ */
+export function flattenAmount(amount: Amount): { value: number; currency: string } {
+  return { value: parseFloat(amount[0]), currency: amount[1] };
+}
+
+/**
+ * Returns a liquidity rating based on the bid/ask spread percentage.
+ * < 0.3%  → "high"
+ * 0.3–1%  → "medium"
+ * > 1%    → "low"
+ */
+export function getLiquidityRating(spreadPct: number): "high" | "medium" | "low" {
+  if (spreadPct < 0.3) return "high";
+  if (spreadPct <= 1.0) return "medium";
+  return "low";
+}

package/test/unit.ts

@@ -9,6 +9,9 @@ import { MemoryCache } from "../src/cache.js";
 import { validateMarketId } from "../src/validation.js";
 import { handlePlaceOrder } from "../src/tools/place_order.js";
 import { handleCancelOrder } from "../src/tools/cancel_order.js";
+import { flattenAmount, getLiquidityRating } from "../src/utils.js";
+import { handleArbitrageOpportunities } from "../src/tools/arbitrage.js";
+import { handleMarketSummary } from "../src/tools/market_summary.js";
 
 // ----------------------------------------------------------------
 // Minimal test harness
@@ -401,6 +404,257 @@ await test("defaults to 1000ms when Retry-After header is absent", async () => {
   }
 });
 
+// ----------------------------------------------------------------
+// f. Numeric flattening — flattenAmount returns typed float, not string
+// ----------------------------------------------------------------
+
+section("f. Numeric flattening — flattenAmount");
+
+await test("flattenAmount returns a number value, not a string", () => {
+  const result = flattenAmount(["65000000", "CLP"]);
+  assert(typeof result.value === "number", "value should be a number");
+  assertEqual(result.value, 65000000, "value should equal 65000000");
+  assertEqual(result.currency, "CLP", "currency should equal CLP");
+});
+
+await test("flattenAmount handles decimal strings correctly", () => {
+  const result = flattenAmount(["4.99123456", "BTC"]);
+  assert(typeof result.value === "number", "value should be a number");
+  assertEqual(result.value, 4.99123456, "value should equal 4.99123456");
+  assertEqual(result.currency, "BTC", "currency should equal BTC");
+});
+
+await test("flattenAmount on zero amount", () => {
+  const result = flattenAmount(["0.0", "CLP"]);
+  assertEqual(result.value, 0, "zero should parse to 0");
+});
+
+await test("flattenAmount value is not a string array", () => {
+  const result = flattenAmount(["65000000", "CLP"]);
+  assert(!Array.isArray(result), "result should not be an array");
+  assert(typeof result.value !== "string", "value should not be a string");
+});
+
+// ----------------------------------------------------------------
+// g. get_arbitrage_opportunities — discrepancy calculation
+// ----------------------------------------------------------------
+
+section("g. get_arbitrage_opportunities — discrepancy calculation");
+
+await test("correctly computes USDC-normalized price discrepancy between CLP and PEN markets", async () => {
+  const savedFetch = globalThis.fetch;
+
+  // BTC-CLP: 65000000 CLP, USDC-CLP: 1000 CLP → BTC in USDC = 65000
+  // BTC-PEN: 250000000 PEN, USDC-PEN: 3700 PEN → BTC in USDC ≈ 67567.567...
+  // Discrepancy: (67567.567 - 65000) / 65000 * 100 ≈ 3.95%
+  const mockTickers = {
+    tickers: [
+      { market_id: "BTC-CLP", last_price: ["65000000", "CLP"], max_bid: ["64900000", "CLP"], min_ask: ["65100000", "CLP"], volume: ["4.99", "BTC"], price_variation_24h: "0.01", price_variation_7d: "0.05" },
+      { market_id: "BTC-PEN", last_price: ["250000000", "PEN"], max_bid: ["249500000", "PEN"], min_ask: ["250500000", "PEN"], volume: ["1.5", "BTC"], price_variation_24h: "0.012", price_variation_7d: "0.04" },
+      { market_id: "USDC-CLP", last_price: ["1000", "CLP"], max_bid: ["999", "CLP"], min_ask: ["1001", "CLP"], volume: ["100", "USDC"], price_variation_24h: "0.001", price_variation_7d: "0.002" },
+      { market_id: "USDC-PEN", last_price: ["3700", "PEN"], max_bid: ["3695", "PEN"], min_ask: ["3705", "PEN"], volume: ["50", "USDC"], price_variation_24h: "0.001", price_variation_7d: "0.002" },
+    ],
+  };
+
+  globalThis.fetch = async (): Promise<Response> => {
+    return new Response(JSON.stringify(mockTickers), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const client = new BudaClient("https://www.buda.com/api/v2");
+    const cache = new MemoryCache();
+    const result = await handleArbitrageOpportunities(
+      { base_currency: "BTC", threshold_pct: 0.5 },
+      client,
+      cache,
+    );
+
+    assert(!result.isError, "should not return an error");
+    const parsed = JSON.parse(result.content[0].text) as {
+      opportunities: Array<{ market_a: string; market_b: string; discrepancy_pct: number }>;
+      markets_analyzed: Array<{ market_id: string; price_usdc: number }>;
+    };
+
+    assertEqual(parsed.markets_analyzed.length, 2, "should have 2 markets analyzed");
+    assertEqual(parsed.opportunities.length, 1, "should have exactly 1 opportunity");
+
+    const opp = parsed.opportunities[0];
+    const expectedDiscrepancy = ((67567.5676 - 65000) / 65000) * 100;
+    assert(
+      Math.abs(opp.discrepancy_pct - expectedDiscrepancy) < 0.01,
+      `discrepancy_pct should be ≈${expectedDiscrepancy.toFixed(2)}%, got ${opp.discrepancy_pct}`,
+    );
+  } finally {
+    globalThis.fetch = savedFetch;
+  }
+});
+
+await test("threshold filtering excludes opportunities below threshold", async () => {
+  const savedFetch = globalThis.fetch;
+
+  // ~3.95% discrepancy between CLP and PEN — threshold 5% should exclude it
+  const mockTickers = {
+    tickers: [
+      { market_id: "BTC-CLP", last_price: ["65000000", "CLP"], max_bid: ["64900000", "CLP"], min_ask: ["65100000", "CLP"], volume: ["4.99", "BTC"], price_variation_24h: "0.01", price_variation_7d: "0.05" },
+      { market_id: "BTC-PEN", last_price: ["250000000", "PEN"], max_bid: ["249500000", "PEN"], min_ask: ["250500000", "PEN"], volume: ["1.5", "BTC"], price_variation_24h: "0.012", price_variation_7d: "0.04" },
+      { market_id: "USDC-CLP", last_price: ["1000", "CLP"], max_bid: ["999", "CLP"], min_ask: ["1001", "CLP"], volume: ["100", "USDC"], price_variation_24h: "0.001", price_variation_7d: "0.002" },
+      { market_id: "USDC-PEN", last_price: ["3700", "PEN"], max_bid: ["3695", "PEN"], min_ask: ["3705", "PEN"], volume: ["50", "USDC"], price_variation_24h: "0.001", price_variation_7d: "0.002" },
+    ],
+  };
+
+  globalThis.fetch = async (): Promise<Response> => {
+    return new Response(JSON.stringify(mockTickers), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const client = new BudaClient("https://www.buda.com/api/v2");
+    const cache = new MemoryCache();
+    const result = await handleArbitrageOpportunities(
+      { base_currency: "BTC", threshold_pct: 5.0 },
+      client,
+      cache,
+    );
+
+    assert(!result.isError, "should not return an error");
+    const parsed = JSON.parse(result.content[0].text) as {
+      opportunities: Array<unknown>;
+    };
+    assertEqual(parsed.opportunities.length, 0, "threshold 5% should exclude the ~3.95% discrepancy");
+  } finally {
+    globalThis.fetch = savedFetch;
+  }
+});
+
+await test("returns error when fewer than 2 markets are found", async () => {
+  const savedFetch = globalThis.fetch;
+
+  // Only CLP market available, no PEN or COP
+  const mockTickers = {
+    tickers: [
+      { market_id: "BTC-CLP", last_price: ["65000000", "CLP"], max_bid: ["64900000", "CLP"], min_ask: ["65100000", "CLP"], volume: ["4.99", "BTC"], price_variation_24h: "0.01", price_variation_7d: "0.05" },
+      { market_id: "USDC-CLP", last_price: ["1000", "CLP"], max_bid: ["999", "CLP"], min_ask: ["1001", "CLP"], volume: ["100", "USDC"], price_variation_24h: "0.001", price_variation_7d: "0.002" },
+    ],
+  };
+
+  globalThis.fetch = async (): Promise<Response> => {
+    return new Response(JSON.stringify(mockTickers), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const client = new BudaClient("https://www.buda.com/api/v2");
+    const cache = new MemoryCache();
+    const result = await handleArbitrageOpportunities(
+      { base_currency: "BTC", threshold_pct: 0.5 },
+      client,
+      cache,
+    );
+    assert(result.isError === true, "should return isError when not enough markets");
+  } finally {
+    globalThis.fetch = savedFetch;
+  }
+});
+
+// ----------------------------------------------------------------
+// h. get_market_summary — liquidity_rating thresholds
+// ----------------------------------------------------------------
+
+section("h. get_market_summary — liquidity_rating thresholds");
+
+await test("getLiquidityRating: spread < 0.3% → 'high'", () => {
+  assertEqual(getLiquidityRating(0), "high", "0% spread should be high");
+  assertEqual(getLiquidityRating(0.1), "high", "0.1% spread should be high");
+  assertEqual(getLiquidityRating(0.29), "high", "0.29% spread should be high");
+});
+
+await test("getLiquidityRating: spread at 0.3% boundary → 'medium'", () => {
+  assertEqual(getLiquidityRating(0.3), "medium", "exactly 0.3% spread should be medium");
+});
+
+await test("getLiquidityRating: spread 0.3–1% → 'medium'", () => {
+  assertEqual(getLiquidityRating(0.5), "medium", "0.5% spread should be medium");
+  assertEqual(getLiquidityRating(1.0), "medium", "exactly 1.0% spread should be medium");
+});
+
+await test("getLiquidityRating: spread > 1% → 'low'", () => {
+  assertEqual(getLiquidityRating(1.01), "low", "1.01% spread should be low");
+  assertEqual(getLiquidityRating(5.0), "low", "5% spread should be low");
+});
+
+await test("handleMarketSummary returns correct liquidity_rating from mocked API", async () => {
+  const savedFetch = globalThis.fetch;
+  let callCount = 0;
+
+  // Ticker: bid 64870, ask 65000 → spread = 130 / 65000 * 100 = 0.2% → "high"
+  const mockTicker = {
+    ticker: {
+      market_id: "BTC-CLP",
+      last_price: ["65000", "CLP"],
+      max_bid: ["64870", "CLP"],
+      min_ask: ["65000", "CLP"],
+      volume: ["4.99", "BTC"],
+      price_variation_24h: "0.012",
+      price_variation_7d: "0.05",
+    },
+  };
+  const mockVolume = {
+    volume: {
+      market_id: "BTC-CLP",
+      ask_volume_24h: ["10.5", "BTC"],
+      ask_volume_7d: ["72.1", "BTC"],
+      bid_volume_24h: ["9.8", "BTC"],
+      bid_volume_7d: ["68.3", "BTC"],
+    },
+  };
+
+  globalThis.fetch = async (url: string | URL): Promise<Response> => {
+    callCount++;
+    const urlStr = url.toString();
+    if (urlStr.includes("/volume")) {
+      return new Response(JSON.stringify(mockVolume), { status: 200, headers: { "Content-Type": "application/json" } });
+    }
+    return new Response(JSON.stringify(mockTicker), { status: 200, headers: { "Content-Type": "application/json" } });
+  };
+
+  try {
+    const client = new BudaClient("https://www.buda.com/api/v2");
+    const cache = new MemoryCache();
+    const result = await handleMarketSummary({ market_id: "BTC-CLP" }, client, cache);
+
+    assert(!result.isError, "should not return an error");
+    const parsed = JSON.parse(result.content[0].text) as {
+      market_id: string;
+      last_price: number;
+      last_price_currency: string;
+      bid: number;
+      ask: number;
+      spread_pct: number;
+      volume_24h: number;
+      liquidity_rating: string;
+    };
+
+    assertEqual(parsed.market_id, "BTC-CLP", "market_id should match");
+    assertEqual(parsed.last_price, 65000, "last_price should be a number");
+    assert(typeof parsed.last_price === "number", "last_price should be a number type");
+    assertEqual(parsed.last_price_currency, "CLP", "currency should be CLP");
+    assertEqual(parsed.bid, 64870, "bid should be a float");
+    assertEqual(parsed.ask, 65000, "ask should be a float");
+    // spread = (65000 - 64870) / 65000 * 100 = 130/65000*100 = 0.2%
+    assertEqual(parsed.liquidity_rating, "high", "spread 0.2% should yield 'high' liquidity");
+    assertEqual(parsed.volume_24h, 10.5, "volume_24h should be a float");
+  } finally {
+    globalThis.fetch = savedFetch;
+  }
+});
+
 // ----------------------------------------------------------------
 // Summary
 // ----------------------------------------------------------------