@guiie/buda-mcp 1.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@guiie/buda-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.gtorreal/buda-mcp",
+  "description": "MCP server for Buda.com's public cryptocurrency exchange API (Chile, Colombia, Peru)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "buda-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "tsx test/run-all.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "buda",
+    "cryptocurrency",
+    "exchange",
+    "bitcoin",
+    "trading",
+    "chile",
+    "colombia",
+    "peru",
+    "clp",
+    "cop",
+    "pen"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gtorreal/buda-mcp.git"
+  },
+  "homepage": "https://github.com/gtorreal/buda-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/gtorreal/buda-mcp/issues"
+  },
+  "license": "MIT",
+  "author": "Guille <guillermo@buda.com>",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.gtorreal/buda-mcp",
+  "description": "Real-time cryptocurrency market data from Buda.com — prices, order books, trades, and volume for markets in Chile (CLP), Colombia (COP), and Peru (PEN). No API key required.",
+  "repository": {
+    "url": "https://github.com/gtorreal/buda-mcp",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@guiie/buda-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/src/client.ts

@@ -0,0 +1,57 @@
+const BASE_URL = "https://www.buda.com/api/v2";
+
+export class BudaApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly path: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "BudaApiError";
+  }
+}
+
+export class BudaClient {
+  private readonly baseUrl: string;
+
+  constructor(baseUrl: string = BASE_URL) {
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * Perform an authenticated GET request.
+   *
+   * Private endpoints (balances, orders, etc.) require HMAC-SHA2 signing.
+   * To add auth later, extend this method with the `apiKey` + `apiSecret`
+   * constructor params and sign the nonce/path headers here before fetching.
+   */
+  async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
+    const url = new URL(`${this.baseUrl}${path}.json`);
+
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const response = await fetch(url.toString(), {
+      headers: {
+        Accept: "application/json",
+        "User-Agent": "buda-mcp/1.0.0",
+      },
+    });
+
+    if (!response.ok) {
+      let detail = response.statusText;
+      try {
+        const body = (await response.json()) as { message?: string };
+        if (body.message) detail = body.message;
+      } catch {
+        // ignore parse error, use statusText
+      }
+      throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { BudaClient } from "./client.js";
+import * as markets from "./tools/markets.js";
+import * as ticker from "./tools/ticker.js";
+import * as orderbook from "./tools/orderbook.js";
+import * as trades from "./tools/trades.js";
+import * as volume from "./tools/volume.js";
+
+const server = new McpServer({
+  name: "buda-mcp",
+  version: "1.0.0",
+});
+
+const client = new BudaClient();
+
+// Register all public-endpoint tools
+markets.register(server, client);
+ticker.register(server, client);
+orderbook.register(server, client);
+trades.register(server, client);
+volume.register(server, client);
+
+// Start the server over stdio (standard MCP transport)
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools/markets.ts

@@ -0,0 +1,35 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient } from "../client.js";
+import type { MarketsResponse, MarketResponse } from "../types.js";
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    "get_markets",
+    "List all available trading pairs on Buda.com, or get details for a specific market. " +
+      "Returns base/quote currencies, fees, and minimum order sizes.",
+    {
+      market_id: z
+        .string()
+        .optional()
+        .describe(
+          "Optional market ID (e.g. 'BTC-CLP', 'ETH-BTC'). Omit to list all markets.",
+        ),
+    },
+    async ({ market_id }) => {
+      if (market_id) {
+        const data = await client.get<MarketResponse>(
+          `/markets/${market_id.toLowerCase()}`,
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(data.market, null, 2) }],
+        };
+      }
+
+      const data = await client.get<MarketsResponse>("/markets");
+      return {
+        content: [{ type: "text", text: JSON.stringify(data.markets, null, 2) }],
+      };
+    },
+  );
+}

package/src/tools/orderbook.ts

@@ -0,0 +1,40 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient } from "../client.js";
+import type { OrderBookResponse } from "../types.js";
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    "get_orderbook",
+    "Get the current order book for a Buda.com market. Returns sorted arrays of " +
+      "bids (buy orders) and asks (sell orders), each as [price, amount] pairs.",
+    {
+      market_id: z
+        .string()
+        .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC')."),
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Maximum number of levels to return per side (default: all)."),
+    },
+    async ({ market_id, limit }) => {
+      const data = await client.get<OrderBookResponse>(
+        `/markets/${market_id.toLowerCase()}/order_book`,
+      );
+
+      const book = data.order_book;
+      const result = {
+        bids: limit ? book.bids.slice(0, limit) : book.bids,
+        asks: limit ? book.asks.slice(0, limit) : book.asks,
+        bid_count: book.bids.length,
+        ask_count: book.asks.length,
+      };
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+}

package/src/tools/ticker.ts

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient } from "../client.js";
+import type { TickerResponse } from "../types.js";
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    "get_ticker",
+    "Get the current ticker for a Buda.com market: last traded price, best bid/ask, " +
+      "24h volume, and price change over 24h and 7d.",
+    {
+      market_id: z
+        .string()
+        .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC', 'BTC-COP')."),
+    },
+    async ({ market_id }) => {
+      const data = await client.get<TickerResponse>(
+        `/markets/${market_id.toLowerCase()}/ticker`,
+      );
+      return {
+        content: [{ type: "text", text: JSON.stringify(data.ticker, null, 2) }],
+      };
+    },
+  );
+}

package/src/tools/trades.ts

@@ -0,0 +1,45 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient } from "../client.js";
+import type { TradesResponse } from "../types.js";
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    "get_trades",
+    "Get recent trade history for a Buda.com market. Each entry contains " +
+      "[timestamp_ms, amount, price, direction]. Direction is 'buy' or 'sell'.",
+    {
+      market_id: z
+        .string()
+        .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC')."),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Number of trades to return (default: 50, max: 100)."),
+      timestamp: z
+        .number()
+        .int()
+        .optional()
+        .describe(
+          "Unix timestamp (seconds) to paginate from. Returns trades older than this timestamp.",
+        ),
+    },
+    async ({ market_id, limit, timestamp }) => {
+      const params: Record<string, string | number> = {};
+      if (limit !== undefined) params.limit = limit;
+      if (timestamp !== undefined) params.timestamp = timestamp;
+
+      const data = await client.get<TradesResponse>(
+        `/markets/${market_id.toLowerCase()}/trades`,
+        Object.keys(params).length > 0 ? params : undefined,
+      );
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(data.trades, null, 2) }],
+      };
+    },
+  );
+}

package/src/tools/volume.ts

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient } from "../client.js";
+import type { VolumeResponse } from "../types.js";
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    "get_market_volume",
+    "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.",
+    {
+      market_id: z
+        .string()
+        .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC')."),
+    },
+    async ({ market_id }) => {
+      const data = await client.get<VolumeResponse>(
+        `/markets/${market_id.toLowerCase()}/volume`,
+      );
+      return {
+        content: [{ type: "text", text: JSON.stringify(data.volume, null, 2) }],
+      };
+    },
+  );
+}

package/src/types.ts

@@ -0,0 +1,84 @@
+// Buda.com REST API v2 — shared response types
+// All monetary amounts are returned as [amount_string, currency_string] tuples.
+
+export type Amount = [string, string];
+
+// ----- Markets -----
+
+export interface Market {
+  id: string;
+  name: string;
+  base_currency: string;
+  quote_currency: string;
+  minimum_order_amount: Amount;
+  taker_fee: string;
+  maker_fee: string;
+  max_orders_per_minute: number;
+  maker_discount_percentage: string;
+  taker_discount_percentage: string;
+  maker_discount_tiers: Record<string, number>;
+  taker_discount_tiers: Record<string, number>;
+}
+
+export interface MarketsResponse {
+  markets: Market[];
+}
+
+export interface MarketResponse {
+  market: Market;
+}
+
+// ----- Ticker -----
+
+export interface Ticker {
+  market_id: string;
+  last_price: Amount;
+  min_ask: Amount;
+  max_bid: Amount;
+  volume: Amount;
+  price_variation_24h: string;
+  price_variation_7d: string;
+}
+
+export interface TickerResponse {
+  ticker: Ticker;
+}
+
+// ----- Order Book -----
+
+export interface OrderBook {
+  asks: [string, string][];
+  bids: [string, string][];
+}
+
+export interface OrderBookResponse {
+  order_book: OrderBook;
+}
+
+// ----- Trades -----
+
+export interface Trades {
+  timestamp: string;
+  last_timestamp: string;
+  market_id: string;
+  /** Each entry: [timestamp, amount, price, direction] */
+  entries: [string, string, string, string][];
+}
+
+export interface TradesResponse {
+  trades: Trades;
+}
+
+// ----- Volume -----
+
+export interface MarketVolume {
+  market_id: string;
+  ask_volume_24h: Amount;
+  ask_volume_7d: Amount;
+  bid_volume_24h: Amount;
+  bid_volume_7d: Amount;
+}
+
+export interface VolumeResponse {
+  volume: MarketVolume;
+}

package/test/run-all.ts

@@ -0,0 +1,144 @@
+/**
+ * Integration test: calls each Buda MCP tool directly via BudaClient
+ * and prints a summary of the results.
+ *
+ * Run with: npm test
+ */
+
+import { BudaClient } from "../src/client.js";
+import type {
+  MarketsResponse,
+  TickerResponse,
+  OrderBookResponse,
+  TradesResponse,
+  VolumeResponse,
+} from "../src/types.js";
+
+const client = new BudaClient();
+const TEST_MARKET = "BTC-CLP";
+
+function section(title: string): void {
+  console.log("\n" + "=".repeat(60));
+  console.log(`  ${title}`);
+  console.log("=".repeat(60));
+}
+
+function pass(label: string, detail: string): void {
+  console.log(`  PASS  ${label}: ${detail}`);
+}
+
+function fail(label: string, error: unknown): void {
+  console.error(`  FAIL  ${label}:`, error instanceof Error ? error.message : error);
+}
+
+let failures = 0;
+
+// ----------------------------------------------------------------
+// 1. get_markets
+// ----------------------------------------------------------------
+section("get_markets — list all markets");
+try {
+  const data = await client.get<MarketsResponse>("/markets");
+  const ids = data.markets.map((m) => m.id);
+  pass("markets count", `${ids.length} markets returned`);
+  pass("includes BTC-CLP", String(ids.includes("BTC-CLP")));
+  console.log("  Sample IDs:", ids.slice(0, 6).join(", "));
+} catch (err) {
+  fail("get_markets", err);
+  failures++;
+}
+
+// ----------------------------------------------------------------
+// 2. get_ticker
+// ----------------------------------------------------------------
+section(`get_ticker — ${TEST_MARKET}`);
+try {
+  const data = await client.get<TickerResponse>(`/markets/${TEST_MARKET.toLowerCase()}/ticker`);
+  const t = data.ticker;
+  pass("market_id", t.market_id);
+  pass("last_price", `${t.last_price[0]} ${t.last_price[1]}`);
+  pass("max_bid", `${t.max_bid[0]} ${t.max_bid[1]}`);
+  pass("min_ask", `${t.min_ask[0]} ${t.min_ask[1]}`);
+  pass("volume_24h", `${t.volume[0]} ${t.volume[1]}`);
+  pass("price_variation_24h", `${(parseFloat(t.price_variation_24h) * 100).toFixed(2)}%`);
+} catch (err) {
+  fail("get_ticker", err);
+  failures++;
+}
+
+// ----------------------------------------------------------------
+// 3. get_orderbook
+// ----------------------------------------------------------------
+section(`get_orderbook — ${TEST_MARKET}`);
+try {
+  const data = await client.get<OrderBookResponse>(
+    `/markets/${TEST_MARKET.toLowerCase()}/order_book`,
+  );
+  const book = data.order_book;
+  pass("bids count", `${book.bids.length} levels`);
+  pass("asks count", `${book.asks.length} levels`);
+  if (book.bids.length > 0 && book.asks.length > 0) {
+    pass("top bid", `${book.bids[0][0]} @ ${book.bids[0][1]} BTC`);
+    pass("top ask", `${book.asks[0][0]} @ ${book.asks[0][1]} BTC`);
+    const spread =
+      parseFloat(book.asks[0][0]) - parseFloat(book.bids[0][0]);
+    pass("spread", spread.toFixed(2));
+  }
+} catch (err) {
+  fail("get_orderbook", err);
+  failures++;
+}
+
+// ----------------------------------------------------------------
+// 4. get_trades
+// ----------------------------------------------------------------
+section(`get_trades — ${TEST_MARKET} (limit 10)`);
+try {
+  const data = await client.get<TradesResponse>(
+    `/markets/${TEST_MARKET.toLowerCase()}/trades`,
+    { limit: 10 },
+  );
+  const t = data.trades;
+  pass("market_id", t.market_id);
+  pass("entries count", `${t.entries.length}`);
+  if (t.entries.length > 0) {
+    const [ts, amount, price, direction] = t.entries[0];
+    pass(
+      "latest trade",
+      `${direction} ${amount} BTC @ ${price} CLP (ts: ${ts})`,
+    );
+  }
+} catch (err) {
+  fail("get_trades", err);
+  failures++;
+}
+
+// ----------------------------------------------------------------
+// 5. get_market_volume
+// ----------------------------------------------------------------
+section(`get_market_volume — ${TEST_MARKET}`);
+try {
+  const data = await client.get<VolumeResponse>(
+    `/markets/${TEST_MARKET.toLowerCase()}/volume`,
+  );
+  const v = data.volume;
+  pass("market_id", v.market_id);
+  pass("ask_volume_24h", `${v.ask_volume_24h[0]} ${v.ask_volume_24h[1]}`);
+  pass("ask_volume_7d", `${v.ask_volume_7d[0]} ${v.ask_volume_7d[1]}`);
+  pass("bid_volume_24h", `${v.bid_volume_24h[0]} ${v.bid_volume_24h[1]}`);
+  pass("bid_volume_7d", `${v.bid_volume_7d[0]} ${v.bid_volume_7d[1]}`);
+} catch (err) {
+  fail("get_market_volume", err);
+  failures++;
+}
+
+// ----------------------------------------------------------------
+// Summary
+// ----------------------------------------------------------------
+section("Summary");
+if (failures === 0) {
+  console.log("  All tools returned valid data from the live Buda API.");
+} else {
+  console.error(`  ${failures} tool(s) failed. See errors above.`);
+  process.exit(1);
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "test"]
+}