@guiie/buda-mcp 1.2.2 → 1.4.0

package/src/http.ts

@@ -13,10 +13,18 @@ import * as volume from "./tools/volume.js";
 import * as spread from "./tools/spread.js";
 import * as compareMarkets from "./tools/compare_markets.js";
 import * as priceHistory from "./tools/price_history.js";
+import * as arbitrage from "./tools/arbitrage.js";
+import * as marketSummary from "./tools/market_summary.js";
 import * as balances from "./tools/balances.js";
 import * as orders from "./tools/orders.js";
 import * as placeOrder from "./tools/place_order.js";
 import * as cancelOrder from "./tools/cancel_order.js";
+import * as simulateOrder from "./tools/simulate_order.js";
+import * as positionSize from "./tools/calculate_position_size.js";
+import * as marketSentiment from "./tools/market_sentiment.js";
+import * as technicalIndicators from "./tools/technical_indicators.js";
+import * as deadMansSwitch from "./tools/dead_mans_switch.js";
+import { handleMarketSummary } from "./tools/market_summary.js";
 
 const PORT = parseInt(process.env.PORT ?? "3000", 10);
 
@@ -39,6 +47,12 @@ const PUBLIC_TOOL_SCHEMAS = [
   spread.toolSchema,
   compareMarkets.toolSchema,
   priceHistory.toolSchema,
+  arbitrage.toolSchema,
+  marketSummary.toolSchema,
+  simulateOrder.toolSchema,
+  positionSize.toolSchema,
+  marketSentiment.toolSchema,
+  technicalIndicators.toolSchema,
 ];
 
 const AUTH_TOOL_SCHEMAS = [
@@ -46,6 +60,9 @@ const AUTH_TOOL_SCHEMAS = [
   orders.toolSchema,
   placeOrder.toolSchema,
   cancelOrder.toolSchema,
+  deadMansSwitch.toolSchema,
+  deadMansSwitch.renewToolSchema,
+  deadMansSwitch.disarmToolSchema,
 ];
 
 function createServer(): McpServer {
@@ -62,12 +79,19 @@ function createServer(): McpServer {
   spread.register(server, client, reqCache);
   compareMarkets.register(server, client, reqCache);
   priceHistory.register(server, client, reqCache);
+  arbitrage.register(server, client, reqCache);
+  marketSummary.register(server, client, reqCache);
+  simulateOrder.register(server, client, reqCache);
+  positionSize.register(server);
+  marketSentiment.register(server, client, reqCache);
+  technicalIndicators.register(server, client);
 
   if (authEnabled) {
     balances.register(server, client);
     orders.register(server, client);
     placeOrder.register(server, client);
     cancelOrder.register(server, client);
+    deadMansSwitch.register(server, client);
   }
 
   // MCP Resources
@@ -114,6 +138,25 @@ function createServer(): McpServer {
     },
   );
 
+  server.resource(
+    "buda-summary",
+    new ResourceTemplate("buda://summary/{market}", { list: undefined }),
+    async (uri, params) => {
+      const marketId = (params.market as string).toUpperCase();
+      const result = await handleMarketSummary({ market_id: marketId }, client, reqCache);
+      const text = result.content[0].text;
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text,
+          },
+        ],
+      };
+    },
+  );
+
   return server;
 }
 
@@ -140,6 +183,7 @@ app.get("/.well-known/mcp/server-card.json", (_req, res) => {
     resources: [
       { uri: "buda://markets", name: "All Buda.com markets", mimeType: "application/json" },
       { uri: "buda://ticker/{market}", name: "Ticker for a specific market", mimeType: "application/json" },
+      { uri: "buda://summary/{market}", name: "Full market summary with liquidity rating", mimeType: "application/json" },
     ],
     prompts: [],
   });

package/src/index.ts

@@ -14,10 +14,18 @@ import * as volume from "./tools/volume.js";
 import * as spread from "./tools/spread.js";
 import * as compareMarkets from "./tools/compare_markets.js";
 import * as priceHistory from "./tools/price_history.js";
+import * as arbitrage from "./tools/arbitrage.js";
+import * as marketSummary from "./tools/market_summary.js";
 import * as balances from "./tools/balances.js";
 import * as orders from "./tools/orders.js";
 import * as placeOrder from "./tools/place_order.js";
 import * as cancelOrder from "./tools/cancel_order.js";
+import * as simulateOrder from "./tools/simulate_order.js";
+import * as positionSize from "./tools/calculate_position_size.js";
+import * as marketSentiment from "./tools/market_sentiment.js";
+import * as technicalIndicators from "./tools/technical_indicators.js";
+import * as deadMansSwitch from "./tools/dead_mans_switch.js";
+import { handleMarketSummary } from "./tools/market_summary.js";
 
 const client = new BudaClient(
   undefined,
@@ -39,6 +47,12 @@ volume.register(server, client, cache);
 spread.register(server, client, cache);
 compareMarkets.register(server, client, cache);
 priceHistory.register(server, client, cache);
+arbitrage.register(server, client, cache);
+marketSummary.register(server, client, cache);
+simulateOrder.register(server, client, cache);
+positionSize.register(server);
+marketSentiment.register(server, client, cache);
+technicalIndicators.register(server, client);
 
 // Auth-gated tools — only registered when API credentials are present
 if (client.hasAuth()) {
@@ -46,6 +60,7 @@ if (client.hasAuth()) {
   orders.register(server, client);
   placeOrder.register(server, client);
   cancelOrder.register(server, client);
+  deadMansSwitch.register(server, client);
 }
 
 // MCP Resources
@@ -92,5 +107,24 @@ server.resource(
   },
 );
 
+server.resource(
+  "buda-summary",
+  new ResourceTemplate("buda://summary/{market}", { list: undefined }),
+  async (uri, params) => {
+    const marketId = (params.market as string).toUpperCase();
+    const result = await handleMarketSummary({ market_id: marketId }, client, cache);
+    const text = result.content[0].text;
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text,
+        },
+      ],
+    };
+  },
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/src/tools/arbitrage.ts

@@ -0,0 +1,202 @@
+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 type { AllTickersResponse, Ticker } from "../types.js";
+
+export const toolSchema = {
+  name: "get_arbitrage_opportunities",
+  description:
+    "Detects cross-country price discrepancies for a given asset across Buda's CLP, COP, and PEN markets, " +
+    "normalized to USDC. Fetches all relevant tickers, converts each local price to USDC using the " +
+    "current USDC-CLP / USDC-COP / USDC-PEN rates, then computes pairwise discrepancy percentages. " +
+    "Results above threshold_pct are returned sorted by opportunity size. Note: Buda taker fee is 0.8% " +
+    "per leg (~1.6% round-trip) — always deduct fees before acting on any discrepancy. " +
+    "Example: 'Is there an arbitrage opportunity for BTC between Chile and Peru right now?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      base_currency: {
+        type: "string",
+        description: "Base asset to scan (e.g. 'BTC', 'ETH', 'XRP').",
+      },
+      threshold_pct: {
+        type: "number",
+        description:
+          "Minimum price discrepancy percentage to include in results (default: 0.5). " +
+          "Buda taker fee is 0.8% per leg, so a round-trip requires > 1.6% to be profitable.",
+      },
+    },
+    required: ["base_currency"],
+  },
+};
+
+interface ArbitrageOpportunity {
+  market_a: string;
+  market_b: string;
+  price_a_usdc: number;
+  price_b_usdc: number;
+  discrepancy_pct: number;
+  higher_market: string;
+  lower_market: string;
+}
+
+interface ArbitrageInput {
+  base_currency: string;
+  threshold_pct?: number;
+}
+
+export async function handleArbitrageOpportunities(
+  { base_currency, threshold_pct = 0.5 }: ArbitrageInput,
+  client: BudaClient,
+  cache: MemoryCache,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const base = base_currency.toUpperCase();
+    const data = await cache.getOrFetch<AllTickersResponse>(
+      "tickers:all",
+      CACHE_TTL.TICKER,
+      () => client.get<AllTickersResponse>("/tickers"),
+    );
+
+    const tickerMap = new Map<string, Ticker>();
+    for (const t of data.tickers) {
+      tickerMap.set(t.market_id, t);
+    }
+
+    // Find USDC conversion rates for each fiat currency
+    const usdcClpTicker = tickerMap.get("USDC-CLP");
+    const usdcCopTicker = tickerMap.get("USDC-COP");
+    const usdcPenTicker = tickerMap.get("USDC-PEN");
+
+    // Build list of markets for the requested base currency with USDC-normalized prices
+    interface MarketPrice {
+      market_id: string;
+      local_price: number;
+      usdc_rate: number;
+      price_usdc: number;
+    }
+
+    const marketPrices: MarketPrice[] = [];
+
+    const candidates: Array<{ suffix: string; usdcTicker: Ticker | undefined }> = [
+      { suffix: "CLP", usdcTicker: usdcClpTicker },
+      { suffix: "COP", usdcTicker: usdcCopTicker },
+      { suffix: "PEN", usdcTicker: usdcPenTicker },
+    ];
+
+    for (const { suffix, usdcTicker } of candidates) {
+      const marketId = `${base}-${suffix}`;
+      const baseTicker = tickerMap.get(marketId);
+
+      if (!baseTicker || !usdcTicker) continue;
+
+      const localPrice = parseFloat(baseTicker.last_price[0]);
+      const usdcRate = parseFloat(usdcTicker.last_price[0]);
+
+      if (isNaN(localPrice) || isNaN(usdcRate) || usdcRate === 0) continue;
+
+      marketPrices.push({
+        market_id: marketId,
+        local_price: localPrice,
+        usdc_rate: usdcRate,
+        price_usdc: localPrice / usdcRate,
+      });
+    }
+
+    if (marketPrices.length < 2) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: `Not enough markets found for base currency '${base}' to compute arbitrage. ` +
+                `Need at least 2 of: ${base}-CLP, ${base}-COP, ${base}-PEN with USDC rates available.`,
+              code: "INSUFFICIENT_MARKETS",
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // Compute all pairwise discrepancies
+    const opportunities: ArbitrageOpportunity[] = [];
+
+    for (let i = 0; i < marketPrices.length; i++) {
+      for (let j = i + 1; j < marketPrices.length; j++) {
+        const a = marketPrices[i];
+        const b = marketPrices[j];
+        const minPrice = Math.min(a.price_usdc, b.price_usdc);
+        const discrepancyPct = (Math.abs(a.price_usdc - b.price_usdc) / minPrice) * 100;
+
+        if (discrepancyPct < threshold_pct) continue;
+
+        const higherMarket = a.price_usdc > b.price_usdc ? a.market_id : b.market_id;
+        const lowerMarket = a.price_usdc < b.price_usdc ? a.market_id : b.market_id;
+
+        opportunities.push({
+          market_a: a.market_id,
+          market_b: b.market_id,
+          price_a_usdc: parseFloat(a.price_usdc.toFixed(4)),
+          price_b_usdc: parseFloat(b.price_usdc.toFixed(4)),
+          discrepancy_pct: parseFloat(discrepancyPct.toFixed(4)),
+          higher_market: higherMarket,
+          lower_market: lowerMarket,
+        });
+      }
+    }
+
+    opportunities.sort((a, b) => b.discrepancy_pct - a.discrepancy_pct);
+
+    const result = {
+      base_currency: base,
+      threshold_pct,
+      markets_analyzed: marketPrices.map((m) => ({
+        market_id: m.market_id,
+        price_usdc: parseFloat(m.price_usdc.toFixed(4)),
+        local_price: m.local_price,
+        usdc_rate: m.usdc_rate,
+      })),
+      opportunities_found: opportunities.length,
+      opportunities,
+      fees_note:
+        "Buda taker fee is 0.8% per leg. A round-trip arbitrage (buy on one market, sell on another) " +
+        "costs approximately 1.6% in fees. Only discrepancies well above 1.6% are likely profitable.",
+    };
+
+    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,
+    {
+      base_currency: z
+        .string()
+        .describe("Base asset to scan (e.g. 'BTC', 'ETH', 'XRP')."),
+      threshold_pct: z
+        .number()
+        .min(0)
+        .default(0.5)
+        .describe(
+          "Minimum price discrepancy percentage to include in results (default: 0.5). " +
+            "Buda taker fee is 0.8% per leg, so a round-trip requires > 1.6% to be profitable.",
+        ),
+    },
+    (args) => handleArbitrageOpportunities(args, client, cache),
+  );
+}

package/src/tools/balances.ts

@@ -1,13 +1,16 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BudaClient, BudaApiError } from "../client.js";
+import { flattenAmount } from "../utils.js";
 import type { BalancesResponse } from "../types.js";
 
 export const toolSchema = {
   name: "get_balances",
   description:
-    "Get all currency balances for the authenticated Buda.com account. " +
-    "Returns total, available, frozen, and pending withdrawal amounts per currency. " +
-    "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables.",
+    "Returns all currency balances for the authenticated Buda.com account as flat typed objects. " +
+    "Each currency entry includes total amount, available amount (not frozen), frozen amount, and " +
+    "pending withdrawal amount — all as floats with separate _currency fields. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'How much BTC do I have available to trade right now?'",
   inputSchema: {
     type: "object" as const,
     properties: {},
@@ -22,8 +25,28 @@ export function register(server: McpServer, client: BudaClient): void {
     async () => {
       try {
         const data = await client.get<BalancesResponse>("/balances");
+
+        const result = data.balances.map((b) => {
+          const amount = flattenAmount(b.amount);
+          const available = flattenAmount(b.available_amount);
+          const frozen = flattenAmount(b.frozen_amount);
+          const pending = flattenAmount(b.pending_withdraw_amount);
+
+          return {
+            id: b.id,
+            amount: amount.value,
+            amount_currency: amount.currency,
+            available_amount: available.value,
+            available_amount_currency: available.currency,
+            frozen_amount: frozen.value,
+            frozen_amount_currency: frozen.currency,
+            pending_withdraw_amount: pending.value,
+            pending_withdraw_amount_currency: pending.currency,
+          };
+        });
+
         return {
-          content: [{ type: "text", text: JSON.stringify(data.balances, null, 2) }],
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
       } catch (err) {
         const msg =

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

@@ -7,9 +7,10 @@ import type { AllTickersResponse } from "../types.js";
 export const toolSchema = {
   name: "compare_markets",
   description:
-    "Compare ticker data for all trading pairs of a given base currency across Buda.com's " +
-    "supported quote currencies (CLP, COP, PEN, BTC, USDC, ETH). " +
-    "For example, passing 'BTC' returns side-by-side data for BTC-CLP, BTC-COP, BTC-PEN, etc.",
+    "Returns side-by-side ticker data for all trading pairs of a given base currency across Buda.com's " +
+    "supported quote currencies (CLP, COP, PEN, BTC, USDC, ETH). All prices are floats; " +
+    "price_change_24h and price_change_7d are floats in percent (e.g. 1.23 means +1.23%). " +
+    "Example: 'In which country is Bitcoin currently most expensive on Buda?'",
   inputSchema: {
     type: "object" as const,
     properties: {
@@ -67,16 +68,16 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
           base_currency: base,
           markets: matching.map((t) => ({
             market_id: t.market_id,
-            last_price: t.last_price[0],
-            currency: t.last_price[1],
-            best_bid: t.max_bid ? t.max_bid[0] : null,
-            best_ask: t.min_ask ? t.min_ask[0] : null,
-            volume_24h: t.volume ? t.volume[0] : null,
+            last_price: parseFloat(t.last_price[0]),
+            last_price_currency: t.last_price[1],
+            best_bid: t.max_bid ? parseFloat(t.max_bid[0]) : null,
+            best_ask: t.min_ask ? parseFloat(t.min_ask[0]) : null,
+            volume_24h: t.volume ? parseFloat(t.volume[0]) : null,
             price_change_24h: t.price_variation_24h
-              ? (parseFloat(t.price_variation_24h) * 100).toFixed(2) + "%"
+              ? parseFloat((parseFloat(t.price_variation_24h) * 100).toFixed(4))
               : null,
             price_change_7d: t.price_variation_7d
-              ? (parseFloat(t.price_variation_7d) * 100).toFixed(2) + "%"
+              ? parseFloat((parseFloat(t.price_variation_7d) * 100).toFixed(4))
               : null,
           })),
         };