@guiie/buda-mcp 1.5.0 → 1.5.2

package/src/tools/receive_addresses.ts

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { validateCurrency } from "../validation.js";
+import { logAudit } from "../audit.js";
 import type { ReceiveAddressesResponse, SingleReceiveAddressResponse, ReceiveAddress } from "../types.js";
 
 export const createReceiveAddressToolSchema = {
@@ -10,6 +11,7 @@ export const createReceiveAddressToolSchema = {
     "Generates a new receive address for a crypto currency. " +
     "Creates a new blockchain deposit address for the given currency. " +
     "Each call generates a distinct address. Not idempotent. " +
+    "IMPORTANT: Pass confirmation_token='CONFIRM' to execute. " +
     "Only applicable to crypto currencies (BTC, ETH, etc.). " +
     "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
     "Example: 'Give me a fresh Bitcoin deposit address.'",
@@ -20,8 +22,12 @@ export const createReceiveAddressToolSchema = {
         type: "string",
         description: "Currency code (e.g. 'BTC', 'ETH').",
       },
+      confirmation_token: {
+        type: "string",
+        description: "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to generate a new address.",
+      },
     },
-    required: ["currency"],
+    required: ["currency", "confirmation_token"],
   },
 };
 
@@ -109,7 +115,7 @@ export async function handleListReceiveAddresses(
   } 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) }],
@@ -142,7 +148,7 @@ export async function handleGetReceiveAddress(
   } 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) }],
@@ -152,10 +158,29 @@ export async function handleGetReceiveAddress(
 }
 
 export async function handleCreateReceiveAddress(
-  args: { currency: string },
+  args: { currency: string; confirmation_token: string },
   client: BudaClient,
+  transport: "http" | "stdio" = "stdio",
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
-  const { currency } = args;
+  const { currency, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Address not generated. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Each call creates a distinct address — review and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            preview: { currency },
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
 
   const validationError = validateCurrency(currency);
   if (validationError) {
@@ -170,18 +195,17 @@ export async function handleCreateReceiveAddress(
       `/currencies/${currency.toUpperCase()}/receive_addresses`,
       {},
     );
-    return {
-      content: [{ type: "text", text: JSON.stringify(normalizeAddress(data.receive_address), null, 2) }],
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(normalizeAddress(data.receive_address), null, 2) }] };
+    logAudit({ ts: new Date().toISOString(), tool: "create_receive_address", transport, args_summary: { currency }, 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: "create_receive_address", transport, args_summary: { currency }, success: false, error_code: msg.code });
+    return result;
   }
 }
 
@@ -210,6 +234,9 @@ export function register(server: McpServer, client: BudaClient): void {
     createReceiveAddressToolSchema.description,
     {
       currency: z.string().min(2).max(10).describe("Currency code (e.g. 'BTC', 'ETH')."),
+      confirmation_token: z
+        .string()
+        .describe("Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to generate a new address."),
     },
     (args) => handleCreateReceiveAddress(args, client),
   );

package/src/tools/remittance_recipients.ts

@@ -87,7 +87,7 @@ export async function handleListRemittanceRecipients(
   } 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) }],
@@ -108,7 +108,7 @@ export async function handleGetRemittanceRecipient(
   } 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/remittances.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
 import { flattenAmount } from "../utils.js";
 import { validateCurrency } from "../validation.js";
+import { logAudit } from "../audit.js";
 import type { RemittancesResponse, SingleRemittanceResponse, Remittance } from "../types.js";
 
 export const listRemittancesToolSchema = {
@@ -34,7 +35,8 @@ export const quoteRemittanceToolSchema = {
     "Requests a price quote for a fiat remittance to a saved recipient. " +
     "Returns a remittance object in 'quoted' state with an expiry timestamp. " +
     "NOT idempotent — creates a new remittance record each call. " +
-    "To execute, call accept_remittance_quote with the returned ID before it expires. " +
+    "IMPORTANT: Pass confirmation_token='CONFIRM' to execute. " +
+    "To execute the transfer, call accept_remittance_quote with the returned ID before it expires. " +
     "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
     "Example: 'Get a remittance quote to send 100000 CLP to recipient 5.'",
   inputSchema: {
@@ -52,8 +54,12 @@ export const quoteRemittanceToolSchema = {
         type: "number",
         description: "ID of the saved remittance recipient.",
       },
+      confirmation_token: {
+        type: "string",
+        description: "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to create the quote.",
+      },
     },
-    required: ["currency", "amount", "recipient_id"],
+    required: ["currency", "amount", "recipient_id", "confirmation_token"],
   },
 };
 
@@ -147,7 +153,7 @@ export async function handleListRemittances(
   } 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) }],
@@ -168,7 +174,7 @@ export async function handleGetRemittance(
   } 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) }],
@@ -178,10 +184,29 @@ export async function handleGetRemittance(
 }
 
 export async function handleQuoteRemittance(
-  args: { currency: string; amount: number; recipient_id: number },
+  args: { currency: string; amount: number; recipient_id: number; confirmation_token: string },
   client: BudaClient,
+  transport: "http" | "stdio" = "stdio",
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
-  const { currency, amount, recipient_id } = args;
+  const { currency, amount, recipient_id, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Remittance quote not created. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Review the details and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            preview: { currency, amount, recipient_id },
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
 
   const validationError = validateCurrency(currency);
   if (validationError) {
@@ -199,24 +224,24 @@ export async function handleQuoteRemittance(
         recipient_id,
       },
     });
-    return {
-      content: [{ type: "text", text: JSON.stringify(normalizeRemittance(data.remittance), null, 2) }],
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(normalizeRemittance(data.remittance), null, 2) }] };
+    logAudit({ ts: new Date().toISOString(), tool: "quote_remittance", transport, args_summary: { currency, amount, recipient_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: "quote_remittance", transport, args_summary: { currency, amount, recipient_id }, success: false, error_code: msg.code });
+    return result;
   }
 }
 
 export async function handleAcceptRemittanceQuote(
   args: { id: number; confirmation_token: string },
   client: BudaClient,
+  transport: "http" | "stdio" = "stdio",
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
   const { id, confirmation_token } = args;
 
@@ -241,18 +266,17 @@ export async function handleAcceptRemittanceQuote(
     const data = await client.put<SingleRemittanceResponse>(`/remittances/${id}`, {
       remittance: { state: "confirming" },
     });
-    return {
-      content: [{ type: "text", text: JSON.stringify(normalizeRemittance(data.remittance), null, 2) }],
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(normalizeRemittance(data.remittance), null, 2) }] };
+    logAudit({ ts: new Date().toISOString(), tool: "accept_remittance_quote", transport, args_summary: { remittance_id: 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: "accept_remittance_quote", transport, args_summary: { remittance_id: id }, success: false, error_code: msg.code });
+    return result;
   }
 }
 
@@ -283,6 +307,9 @@ export function register(server: McpServer, client: BudaClient): void {
       currency: z.string().min(2).max(10).describe("Fiat currency code (e.g. 'CLP', 'COP')."),
       amount: z.number().positive().describe("Amount to remit (positive number)."),
       recipient_id: z.number().int().positive().describe("ID of the saved remittance recipient."),
+      confirmation_token: z
+        .string()
+        .describe("Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to create the quote."),
     },
     (args) => handleQuoteRemittance(args, client),
   );

package/src/tools/simulate_order.ts

@@ -148,7 +148,7 @@ export async function handleSimulateOrder(
   } 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/spread.ts

@@ -86,7 +86,7 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
       } 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/technical_indicators.ts

@@ -191,7 +191,7 @@ export async function handleTechnicalIndicators(
     const macdResult = macd(closes, 12, 26, 9);
     const bbResult = bollingerBands(closes, 20, 2);
     const sma20 = parseFloat(sma(closes, 20).toFixed(2));
-    const sma50 = parseFloat(sma(closes, 50).toFixed(2));
+    const sma50 = closes.length >= 50 ? parseFloat(sma(closes, 50).toFixed(2)) : null;
     const lastClose = closes[closes.length - 1];
 
     // Signal interpretations
@@ -230,6 +230,7 @@ export async function handleTechnicalIndicators(
         bollinger_bands: bbResult,
         sma_20: sma20,
         sma_50: sma50,
+        sma_50_warning: sma50 === null ? `insufficient data (need 50 candles, have ${closes.length})` : undefined,
       },
       signals: {
         rsi_signal: rsiSignal,
@@ -246,7 +247,7 @@ export async function handleTechnicalIndicators(
   } 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/ticker.ts

@@ -77,7 +77,7 @@ export function register(server: McpServer, client: BudaClient, cache: MemoryCac
       } 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/trades.ts

@@ -94,7 +94,7 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
       } 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/volume.ts

@@ -71,7 +71,7 @@ export function register(server: McpServer, client: BudaClient, _cache: MemoryCa
       } 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/withdrawals.ts

@@ -1,8 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BudaClient, BudaApiError } from "../client.js";
-import { validateCurrency } from "../validation.js";
+import { validateCurrency, validateCryptoAddress } from "../validation.js";
 import { flattenAmount } from "../utils.js";
+import { logAudit } from "../audit.js";
 import type { WithdrawalsResponse, SingleWithdrawalResponse, Withdrawal } from "../types.js";
 
 export const getWithdrawalHistoryToolSchema = {
@@ -106,7 +107,7 @@ export async function handleGetWithdrawalHistory(
   } 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) }],
@@ -120,6 +121,7 @@ export const createWithdrawalToolSchema = {
   description:
     "Create a withdrawal on Buda.com. Supports both crypto (address) and fiat (bank_account_id) withdrawals. " +
     "Exactly one of address or bank_account_id must be provided. " +
+    "WARNING: Crypto withdrawals are irreversible — verify the destination address carefully before confirming. " +
     "IMPORTANT: Pass confirmation_token='CONFIRM' to execute. " +
     "Requires BUDA_API_KEY and BUDA_API_SECRET.",
   inputSchema: {
@@ -151,6 +153,7 @@ type CreateWithdrawalArgs = {
 export async function handleCreateWithdrawal(
   args: CreateWithdrawalArgs,
   client: BudaClient,
+  transport: "http" | "stdio" = "stdio",
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
   const { currency, amount, address, network, bank_account_id, confirmation_token } = args;
 
@@ -213,6 +216,16 @@ export async function handleCreateWithdrawal(
     };
   }
 
+  if (hasAddress) {
+    const addrError = validateCryptoAddress(address!, currency);
+    if (addrError) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: addrError, code: "INVALID_ADDRESS" }) }],
+        isError: true,
+      };
+    }
+  }
+
   try {
     const payload: Record<string, unknown> = { amount: String(amount) };
     if (hasAddress) {
@@ -227,18 +240,17 @@ export async function handleCreateWithdrawal(
       payload,
     );
 
-    return {
-      content: [{ type: "text", text: JSON.stringify(normalizeWithdrawal(data.withdrawal), null, 2) }],
-    };
+    const result = { content: [{ type: "text" as const, text: JSON.stringify(normalizeWithdrawal(data.withdrawal), null, 2) }] };
+    logAudit({ ts: new Date().toISOString(), tool: "create_withdrawal", transport, args_summary: { currency, amount, type: hasAddress ? "crypto" : "fiat" }, 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: "create_withdrawal", transport, args_summary: { currency, amount, type: hasAddress ? "crypto" : "fiat" }, success: false, error_code: msg.code });
+    return result;
   }
 }
 

package/src/utils.ts

@@ -1,11 +1,46 @@
+import { timingSafeEqual } from "crypto";
 import type { Amount, OhlcvCandle } from "./types.js";
 
+/**
+ * Constant-time string comparison to prevent timing attacks on bearer tokens.
+ */
+export function safeTokenEqual(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a);
+  const bBuf = Buffer.from(b);
+  if (aBuf.length !== bBuf.length) return false;
+  return timingSafeEqual(aBuf, bBuf);
+}
+
+/**
+ * Parses a raw string (from an environment variable) as an integer within [min, max].
+ * Returns the fallback when raw is undefined.
+ * Throws a descriptive Error if the value is non-numeric or out of range.
+ */
+export function parseEnvInt(
+  raw: string | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+  name: string,
+): number {
+  if (raw === undefined) return fallback;
+  const n = parseInt(raw, 10);
+  if (isNaN(n) || n < min || n > max) {
+    throw new Error(
+      `[buda-mcp] Invalid ${name} "${raw}". Must be an integer between ${min} and ${max}.`,
+    );
+  }
+  return n;
+}
+
 /**
  * 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] };
+  const value = parseFloat(amount[0]);
+  if (isNaN(value)) throw new Error(`Invalid amount value: "${amount[0]}"`);
+  return { value, currency: amount[1] };
 }
 
 /**

package/src/validation.ts

@@ -30,3 +30,32 @@ export function validateCurrency(id: string): string | null {
   }
   return null;
 }
+
+// Per-currency address format rules.
+// Unknown currencies pass through (undefined rule) — the exchange validates those.
+const ADDRESS_RULES: Record<string, RegExp> = {
+  BTC:  /^(bc1[a-z0-9]{6,87}|[13][a-zA-HJ-NP-Z0-9]{25,34})$/,
+  ETH:  /^0x[0-9a-fA-F]{40}$/,
+  USDC: /^0x[0-9a-fA-F]{40}$/,
+  USDT: /^0x[0-9a-fA-F]{40}$/,
+  LTC:  /^(ltc1[a-z0-9]{6,87}|[LM3][a-zA-HJ-NP-Z0-9]{25,34})$/,
+  BCH:  /^(bitcoincash:)?[qp][a-z0-9]{41}$/,
+  XRP:  /^r[1-9A-HJ-NP-Za-km-z]{24,33}$/,
+};
+
+/**
+ * Validates a crypto withdrawal address against known per-currency formats.
+ * Returns an error message string if the address is invalid, or null if valid
+ * (including null for unknown currencies, where the exchange is the last line of defence).
+ */
+export function validateCryptoAddress(address: string, currency: string): string | null {
+  const rule = ADDRESS_RULES[currency.toUpperCase()];
+  if (!rule) return null;
+  if (!rule.test(address)) {
+    return (
+      `Invalid ${currency.toUpperCase()} address format. ` +
+      `Double-check the destination address — crypto withdrawals are irreversible.`
+    );
+  }
+  return null;
+}

package/src/version.ts

@@ -3,6 +3,14 @@ import { fileURLToPath } from "url";
 import { dirname, join } from "path";
 
 const _dir = dirname(fileURLToPath(import.meta.url));
-export const VERSION: string = (
-  JSON.parse(readFileSync(join(_dir, "../package.json"), "utf8")) as { version: string }
-).version;
+
+let _version = "unknown";
+try {
+  _version = (
+    JSON.parse(readFileSync(join(_dir, "../package.json"), "utf8")) as { version: string }
+  ).version;
+} catch {
+  // package.json not found in deployment — use fallback
+}
+
+export const VERSION: string = _version;