@guiie/buda-mcp 1.5.0 → 1.5.2

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/gtorreal/buda-mcp",
     "source": "github"
   },
-  "version": "1.5.0",
+  "version": "1.5.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@guiie/buda-mcp",
-      "version": "1.5.0",
+      "version": "1.5.2",
       "transport": {
         "type": "stdio"
       }

package/src/audit.ts

@@ -0,0 +1,24 @@
+/**
+ * Structured audit logging for destructive MCP tool calls.
+ *
+ * Writes newline-delimited JSON to stderr so it never pollutes the stdio MCP transport
+ * and is captured by Railway / any log aggregator attached to the process.
+ *
+ * Rules for args_summary:
+ *   - Include: market_id, currency, price_type, type, amount ranges
+ *   - NEVER include: confirmation_token, invoice, address, bank_account_id
+ */
+
+export interface AuditEvent {
+  ts: string;
+  tool: string;
+  transport: "http" | "stdio";
+  ip?: string;
+  args_summary: Record<string, unknown>;
+  success: boolean;
+  error_code?: string | number;
+}
+
+export function logAudit(event: AuditEvent): void {
+  process.stderr.write(JSON.stringify({ audit: true, ...event }) + "\n");
+}

package/src/client.ts

@@ -34,8 +34,10 @@ export class BudaClient {
     return Boolean(this.apiKey && this.apiSecret);
   }
 
+  private _nonceCounter = 0;
+
   private nonce(): string {
-    return String(Math.floor(Date.now() * 1000));
+    return String(Date.now() * 1000 + (this._nonceCounter++ % 1000));
   }
 
   private sign(method: string, pathWithQuery: string, body: string, nonce: string): string {

package/src/http.ts

@@ -1,9 +1,12 @@
 import express from "express";
+import rateLimit from "express-rate-limit";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { BudaClient } from "./client.js";
 import { MemoryCache, CACHE_TTL } from "./cache.js";
+import { safeTokenEqual, parseEnvInt } from "./utils.js";
 import { VERSION } from "./version.js";
+import { validateMarketId } from "./validation.js";
 import type { MarketsResponse, TickerResponse } from "./types.js";
 import * as markets from "./tools/markets.js";
 import * as ticker from "./tools/ticker.js";
@@ -41,7 +44,13 @@ import * as batchOrders from "./tools/batch_orders.js";
 import * as lightning from "./tools/lightning.js";
 import { handleMarketSummary } from "./tools/market_summary.js";
 
-const PORT = parseInt(process.env.PORT ?? "3000", 10);
+let PORT: number;
+try {
+  PORT = parseEnvInt(process.env.PORT, 3000, 1, 65535, "PORT");
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}
 
 const client = new BudaClient(
   undefined,
@@ -133,7 +142,7 @@ function createServer(): McpServer {
     orders.register(server, client);
     placeOrder.register(server, client);
     cancelOrder.register(server, client);
-    deadMansSwitch.register(server, client);
+    deadMansSwitch.register(server, client, "http");
     account.register(server, client);
     balance.register(server, client);
     orderLookup.register(server, client);
@@ -175,7 +184,10 @@ function createServer(): McpServer {
     "buda-ticker",
     new ResourceTemplate("buda://ticker/{market}", { list: undefined }),
     async (uri, params) => {
-      const marketId = (params.market as string).toLowerCase();
+      const raw = params.market as string;
+      const validationError = validateMarketId(raw);
+      if (validationError) throw new Error(validationError);
+      const marketId = raw.toLowerCase();
       const data = await reqCache.getOrFetch<TickerResponse>(
         `ticker:${marketId}`,
         CACHE_TTL.TICKER,
@@ -197,9 +209,12 @@ function createServer(): McpServer {
     "buda-summary",
     new ResourceTemplate("buda://summary/{market}", { list: undefined }),
     async (uri, params) => {
-      const marketId = (params.market as string).toUpperCase();
+      const raw = params.market as string;
+      const validationError = validateMarketId(raw);
+      if (validationError) throw new Error(validationError);
+      const marketId = raw.toUpperCase();
       const result = await handleMarketSummary({ market_id: marketId }, client, reqCache);
-      const text = result.content[0].text;
+      const text = result.content[0]?.text ?? JSON.stringify({ error: "No content returned" });
       return {
         contents: [
           {
@@ -216,8 +231,61 @@ function createServer(): McpServer {
 }
 
 const app = express();
+// Required for correct client IP detection behind Railway's reverse proxy.
+// Without this, express-rate-limit sees the proxy IP instead of the real client.
+app.set("trust proxy", 1);
 app.use(express.json());
 
+const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN;
+
+if (authEnabled && !MCP_AUTH_TOKEN) {
+  console.error(
+    "[buda-mcp] FATAL: BUDA_API_KEY/BUDA_API_SECRET are set but MCP_AUTH_TOKEN is not.\n" +
+    "  The /mcp endpoint would be publicly accessible with full account access.\n" +
+    "  Set MCP_AUTH_TOKEN to a long random secret, or run in stdio mode instead.",
+  );
+  process.exit(1);
+}
+
+if (MCP_AUTH_TOKEN && MCP_AUTH_TOKEN.length < 32) {
+  console.warn(
+    "[buda-mcp] WARNING: MCP_AUTH_TOKEN has fewer than 32 characters. Use a longer random secret.",
+  );
+}
+
+let rateLimitMax: number;
+try {
+  rateLimitMax = parseEnvInt(process.env.MCP_RATE_LIMIT, 120, 1, 10_000, "MCP_RATE_LIMIT");
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}
+
+const mcpRateLimiter = rateLimit({
+  windowMs: 60_000,
+  max: rateLimitMax,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: "Too many requests. Retry after 60 seconds.", code: "RATE_LIMITED" },
+});
+
+function mcpAuthMiddleware(
+  req: express.Request,
+  res: express.Response,
+  next: express.NextFunction,
+): void {
+  if (!MCP_AUTH_TOKEN) {
+    next();
+    return;
+  }
+  const auth = req.headers.authorization ?? "";
+  if (!safeTokenEqual(auth, `Bearer ${MCP_AUTH_TOKEN}`)) {
+    res.status(401).json({ error: "Unauthorized" });
+    return;
+  }
+  next();
+}
+
 // Health check for Railway / uptime monitors
 app.get("/health", (_req, res) => {
   res.json({
@@ -245,7 +313,7 @@ app.get("/.well-known/mcp/server-card.json", (_req, res) => {
 });
 
 // Stateless StreamableHTTP — new server instance per request (no session state needed)
-app.post("/mcp", async (req, res) => {
+app.post("/mcp", mcpRateLimiter, mcpAuthMiddleware, async (req, res) => {
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: undefined,
   });
@@ -260,7 +328,7 @@ app.post("/mcp", async (req, res) => {
 });
 
 // SSE upgrade for clients that prefer streaming
-app.get("/mcp", async (req, res) => {
+app.get("/mcp", mcpRateLimiter, mcpAuthMiddleware, async (req, res) => {
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: undefined,
   });

package/src/index.ts

@@ -5,6 +5,7 @@ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BudaClient } from "./client.js";
 import { cache, CACHE_TTL } from "./cache.js";
 import { VERSION } from "./version.js";
+import { validateMarketId } from "./validation.js";
 import type { MarketsResponse, TickerResponse } from "./types.js";
 import * as markets from "./tools/markets.js";
 import * as ticker from "./tools/ticker.js";
@@ -119,7 +120,10 @@ server.resource(
   "buda-ticker",
   new ResourceTemplate("buda://ticker/{market}", { list: undefined }),
   async (uri, params) => {
-    const marketId = (params.market as string).toLowerCase();
+    const raw = params.market as string;
+    const validationError = validateMarketId(raw);
+    if (validationError) throw new Error(validationError);
+    const marketId = raw.toLowerCase();
     const data = await cache.getOrFetch<TickerResponse>(
       `ticker:${marketId}`,
       CACHE_TTL.TICKER,
@@ -141,9 +145,12 @@ server.resource(
   "buda-summary",
   new ResourceTemplate("buda://summary/{market}", { list: undefined }),
   async (uri, params) => {
-    const marketId = (params.market as string).toUpperCase();
+    const raw = params.market as string;
+    const validationError = validateMarketId(raw);
+    if (validationError) throw new Error(validationError);
+    const marketId = raw.toUpperCase();
     const result = await handleMarketSummary({ market_id: marketId }, client, cache);
-    const text = result.content[0].text;
+    const text = result.content[0]?.text ?? JSON.stringify({ error: "No content returned" });
     return {
       contents: [
         {

package/src/tools/account.ts

@@ -47,7 +47,7 @@ export async function handleGetAccountInfo(
   } catch (err) {
     const msg =
       err instanceof BudaApiError
-        ? { error: err.message, code: err.status, path: err.path }
+        ? { error: err.message, code: err.status }
         : { error: String(err), code: "UNKNOWN" };
     return {
       content: [{ type: "text", text: JSON.stringify(msg) }],

package/src/tools/arbitrage.ts

@@ -171,7 +171,7 @@ export async function handleArbitrageOpportunities(
   } catch (err) {
     const msg =
       err instanceof BudaApiError
-        ? { error: err.message, code: err.status, path: err.path }
+        ? { error: err.message, code: err.status }
         : { error: String(err), code: "UNKNOWN" };
     return {
       content: [{ type: "text", text: JSON.stringify(msg) }],

package/src/tools/balance.ts

@@ -73,7 +73,7 @@ export async function handleGetBalance(
   } catch (err) {
     const msg =
       err instanceof BudaApiError
-        ? { error: err.message, code: err.status, path: err.path }
+        ? { error: err.message, code: err.status }
         : { error: String(err), code: "UNKNOWN" };
     return {
       content: [{ type: "text", text: JSON.stringify(msg) }],

package/src/tools/balances.ts

@@ -51,7 +51,7 @@ export function register(server: McpServer, client: BudaClient): void {
       } catch (err) {
         const msg =
           err instanceof BudaApiError
-            ? { error: err.message, code: err.status, path: err.path }
+            ? { error: err.message, code: err.status }
             : { error: String(err), code: "UNKNOWN" };
         return {
           content: [{ type: "text", text: JSON.stringify(msg) }],

package/src/tools/banks.ts

@@ -73,7 +73,7 @@ export async function handleGetAvailableBanks(
     }
     const msg =
       err instanceof BudaApiError
-        ? { error: err.message, code: err.status, path: err.path }
+        ? { error: err.message, code: err.status }
         : { error: String(err), code: "UNKNOWN" };
     return {
       content: [{ type: "text", text: JSON.stringify(msg) }],

package/src/tools/batch_orders.ts

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { validateMarketId } from "../validation.js";
+import { logAudit } from "../audit.js";
 import type { OrderResponse } from "../types.js";
 
 export const toolSchema = {
@@ -10,6 +11,7 @@ export const toolSchema = {
     "Place multiple orders sequentially on Buda.com (up to 20). " +
     "All orders are pre-validated before any API call — a validation failure stops execution with zero orders placed. " +
     "Partial API failures do NOT roll back already-placed orders. " +
+    "Use max_notional to cap total exposure (computed as sum of amount × limit_price for limit orders; market orders contribute 0). " +
     "IMPORTANT: Pass confirmation_token='CONFIRM' to execute. " +
     "Requires BUDA_API_KEY and BUDA_API_SECRET.",
   inputSchema: {
@@ -30,6 +32,13 @@ export const toolSchema = {
           required: ["market_id", "type", "price_type", "amount"],
         },
       },
+      max_notional: {
+        type: "number",
+        description:
+          "Optional spending cap: total notional (sum of amount × limit_price for limit orders). " +
+          "Batch is rejected before any API call if the sum exceeds this value. " +
+          "Market orders contribute 0 to the notional since their execution price is unknown.",
+      },
       confirmation_token: {
         type: "string",
         description:
@@ -61,14 +70,16 @@ type BatchResult = {
 
 type BatchOrdersArgs = {
   orders: SingleOrderInput[];
+  max_notional?: number;
   confirmation_token: string;
 };
 
 export async function handlePlaceBatchOrders(
   args: BatchOrdersArgs,
   client: BudaClient,
+  transport: "http" | "stdio" = "stdio",
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
-  const { orders, confirmation_token } = args;
+  const { orders, max_notional, confirmation_token } = args;
 
   if (confirmation_token !== "CONFIRM") {
     return {
@@ -124,6 +135,27 @@ export async function handlePlaceBatchOrders(
     }
   }
 
+  // Notional cap check (limit orders only; market orders have unknown execution price)
+  if (max_notional !== undefined) {
+    const totalNotional = orders.reduce((sum, o) => {
+      return sum + (o.price_type === "limit" && o.limit_price ? o.amount * o.limit_price : 0);
+    }, 0);
+    if (totalNotional > max_notional) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            error: `Total notional ${totalNotional} exceeds max_notional cap of ${max_notional}. No orders were placed.`,
+            code: "NOTIONAL_CAP_EXCEEDED",
+            total_notional: totalNotional,
+            max_notional,
+          }),
+        }],
+        isError: true,
+      };
+    }
+  }
+
   // Execute sequentially
   const results: BatchResult[] = [];
   for (let i = 0; i < orders.length; i++) {
@@ -172,9 +204,18 @@ export async function handlePlaceBatchOrders(
     response.warning = "Some orders failed. Already-placed orders were NOT rolled back.";
   }
 
+  const isError = failed > 0 && succeeded === 0 ? true : undefined;
+  logAudit({
+    ts: new Date().toISOString(),
+    tool: "place_batch_orders",
+    transport,
+    args_summary: { order_count: orders.length, succeeded, failed },
+    success: !isError,
+    error_code: isError ? "PARTIAL_OR_FULL_FAILURE" : undefined,
+  });
   return {
     content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
-    isError: failed > 0 && succeeded === 0 ? true : undefined,
+    isError,
   };
 }
 
@@ -188,6 +229,15 @@ export function register(server: McpServer, client: BudaClient): void {
         .min(1)
         .max(20)
         .describe("Array of 1–20 orders to place."),
+      max_notional: z
+        .number()
+        .positive()
+        .optional()
+        .describe(
+          "Optional spending cap: total notional (sum of amount × limit_price for limit orders). " +
+          "Batch is rejected before any API call if the sum exceeds this value. " +
+          "Market orders contribute 0 to the notional since their execution price is unknown.",
+        ),
       confirmation_token: z
         .string()
         .describe(

package/src/tools/cancel_all_orders.ts

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { validateMarketId } from "../validation.js";
+import { logAudit } from "../audit.js";
 import type { CancelAllOrdersResponse } from "../types.js";
 
 export const toolSchema = {
@@ -37,6 +38,7 @@ type CancelAllOrdersArgs = {
 export async function handleCancelAllOrders(
   args: CancelAllOrdersArgs,
   client: BudaClient,
+  transport: "http" | "stdio" = "stdio",
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
   const { market_id, confirmation_token } = args;
 
@@ -76,23 +78,19 @@ export async function handleCancelAllOrders(
 
     const data = await client.delete<CancelAllOrdersResponse>(`/orders`, params);
 
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({ canceled_count: data.canceled_count, market_id }),
-        },
-      ],
+    const result = {
+      content: [{ type: "text" as const, text: JSON.stringify({ canceled_count: data.canceled_count, market_id }) }],
     };
+    logAudit({ ts: new Date().toISOString(), tool: "cancel_all_orders", transport, args_summary: { market_id }, success: true });
+    return result;
   } catch (err) {
     const msg =
       err instanceof BudaApiError
-        ? { error: err.message, code: err.status, path: err.path }
+        ? { error: err.message, code: err.status }
         : { error: String(err), code: "UNKNOWN" };
-    return {
-      content: [{ type: "text", text: JSON.stringify(msg) }],
-      isError: true,
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(msg) }], isError: true as const };
+    logAudit({ ts: new Date().toISOString(), tool: "cancel_all_orders", transport, args_summary: { market_id }, success: false, error_code: msg.code });
+    return result;
   }
 }
 

package/src/tools/cancel_order.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
+import { logAudit } from "../audit.js";
 import type { OrderResponse } from "../types.js";
 
 export const toolSchema = {
@@ -36,6 +37,7 @@ type CancelOrderArgs = {
 export async function handleCancelOrder(
   args: CancelOrderArgs,
   client: BudaClient,
+  transport: "http" | "stdio" = "stdio",
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
   const { order_id, confirmation_token } = args;
 
@@ -59,21 +61,20 @@ export async function handleCancelOrder(
 
   try {
     const data = await client.put<OrderResponse>(`/orders/${order_id}`, {
-      state: "canceling",
+      order: { state: "canceling" },
     });
 
-    return {
-      content: [{ type: "text", text: JSON.stringify(data.order, null, 2) }],
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(data.order, null, 2) }] };
+    logAudit({ ts: new Date().toISOString(), tool: "cancel_order", transport, args_summary: { order_id }, success: true });
+    return result;
   } catch (err) {
     const msg =
       err instanceof BudaApiError
-        ? { error: err.message, code: err.status, path: err.path }
+        ? { error: err.message, code: err.status }
         : { error: String(err), code: "UNKNOWN" };
-    return {
-      content: [{ type: "text", text: JSON.stringify(msg) }],
-      isError: true,
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(msg) }], isError: true as const };
+    logAudit({ ts: new Date().toISOString(), tool: "cancel_order", transport, args_summary: { order_id }, success: false, error_code: msg.code });
+    return result;
   }
 }
 

package/src/tools/cancel_order_by_client_id.ts

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { flattenAmount } from "../utils.js";
+import { logAudit } from "../audit.js";
 import type { OrderResponse, Order } from "../types.js";
 
 export const toolSchema = {
@@ -69,6 +70,7 @@ function normalizeOrder(o: Order) {
 export async function handleCancelOrderByClientId(
   args: CancelOrderByClientIdArgs,
   client: BudaClient,
+  transport: "http" | "stdio" = "stdio",
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
   const { client_id, confirmation_token } = args;
 
@@ -96,18 +98,17 @@ export async function handleCancelOrderByClientId(
       { order: { state: "canceling" } },
     );
 
-    return {
-      content: [{ type: "text", text: JSON.stringify(normalizeOrder(data.order), null, 2) }],
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(normalizeOrder(data.order), null, 2) }] };
+    logAudit({ ts: new Date().toISOString(), tool: "cancel_order_by_client_id", transport, args_summary: {}, success: true });
+    return result;
   } catch (err) {
     const msg =
       err instanceof BudaApiError
-        ? { error: err.message, code: err.status, path: err.path }
+        ? { error: err.message, code: err.status }
         : { error: String(err), code: "UNKNOWN" };
-    return {
-      content: [{ type: "text", text: JSON.stringify(msg) }],
-      isError: true,
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(msg) }], isError: true as const };
+    logAudit({ ts: new Date().toISOString(), tool: "cancel_order_by_client_id", transport, args_summary: {}, success: false, error_code: msg.code });
+    return result;
   }
 }