@guiie/buda-mcp 1.2.2 → 1.4.0

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/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

@@ -0,0 +1,73 @@
+import type { Amount, OhlcvCandle } 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";
+}
+
+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);
+}