@aibtc/mcp-server 1.61.0 → 1.62.0

package/README.md

@@ -99,6 +99,8 @@ npx @aibtc/mcp-server@latest bridge --read-only --list-tools
 npx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx "send 1 STX to SP3..."
 ```
 
+Before any agent loop runs (and on `--list-tools`), the bridge prints a compact **safety receipt** to stderr — network, read-only mode, exposed/write/blocked tool counts, the session spend cap, and the number of known x402 endpoints — so the configured execution boundaries are visible up front. It reports boundaries only; it never claims any value moved.
+
 The allowlist is re-enforced at execution time, so a model can never call a tool outside the exposed set. Any MCP-capable agent framework (`@openrouter/agent`, OpenAI Agents SDK, Claude Agent SDK) can also point at this server directly — the bridge is for driving it through OpenRouter's raw API without adopting a framework.
 
 ### Testnet Mode

package/dist/bridge/index.js

@@ -29,6 +29,7 @@
  */
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { ALL_ENDPOINTS } from "../endpoints/registry.js";
 const OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions";
 const DEFAULT_MODEL = "anthropic/claude-3.5-haiku";
 /**
@@ -136,6 +137,28 @@ function parseArgs(argv) {
     opts.prompt = promptWords.join(" ").trim();
     return opts;
 }
+/**
+ * Compact safety receipt printed before any agent loop runs (#583). Makes the
+ * configured execution boundaries visible up front so a user can trust the
+ * bridge without digging through flags/config. It reports ONLY configured
+ * boundaries — it never claims that any value moved. Emitted on stderr so it
+ * can't pollute stdout (the final assistant reply / --list-tools piping).
+ */
+function printSafetyReceipt(opts, exposed, totalTools) {
+    const writeToolCount = exposed.filter((t) => !isReadOnly(t.name)).length;
+    const lines = [
+        "aibtc-mcp bridge — safety receipt",
+        `  network=${opts.network}`,
+        `  read_only=${opts.readOnly}`,
+        `  exposed_tools=${exposed.length}/${totalTools}`,
+        `  write_tool_count=${writeToolCount}`,
+        `  blocked_tool_count=${opts.block.size}`,
+        `  session_spend_cap=${opts.maxSpendUstx ?? "default"} uSTX / ${opts.maxSpendSats ?? "default"} sats`,
+        `  x402_endpoints_known=${ALL_ENDPOINTS.length}`,
+        "  (reports configured execution boundaries only; no value has moved)",
+    ];
+    console.error(lines.join("\n"));
+}
 /** Apply read-only + allow + block to the raw MCP tool list. */
 function selectTools(tools, opts) {
     return tools.filter((t) => {
@@ -193,6 +216,7 @@ export async function runBridge(argv) {
     const { tools: allTools } = await client.listTools();
     const exposed = selectTools(allTools, opts);
     if (opts.listTools) {
+        printSafetyReceipt(opts, exposed, allTools.length);
         console.log(`Exposed ${exposed.length}/${allTools.length} tools` +
             (opts.readOnly ? " (read-only)" : "") + ":");
         for (const t of exposed)
@@ -211,12 +235,8 @@ export async function runBridge(argv) {
         await client.close();
         process.exit(1);
     }
-    const writeCount = exposed.filter((t) => !isReadOnly(t.name)).length;
-    console.error(`Bridge: ${exposed.length} tools -> ${opts.model}` +
-        (opts.readOnly ? " [read-only]" : ` [${writeCount} can write/spend]`) +
-        (opts.maxSpendUstx || opts.maxSpendSats
-            ? ` (cap ${opts.maxSpendUstx ?? "-"} uSTX / ${opts.maxSpendSats ?? "-"} sats)`
-            : ""));
+    printSafetyReceipt(opts, exposed, allTools.length);
+    console.error(`  model=${opts.model}, max_turns=${opts.maxTurns}`);
     const openaiTools = exposed.map(toOpenAITool);
     const messages = [
         {

package/dist/tools/dual-stacking.tools.js

@@ -64,13 +64,33 @@ Note: Dual Stacking is only available on mainnet.`,
                 });
             }
             const resolvedAddress = address || (await getWalletAddress());
-            const [enrolledThisCycleRaw, enrolledNextCycleRaw, minimumAmountRaw, aprDataRaw, cycleOverviewRaw,] = await Promise.all([
+            // Use allSettled, not all: `is-enrolled-this-cycle` fails contract-side
+            // on mainnet with RuntimeCheck(AtBlockUnavailable) (it reads historical
+            // block state Hiro has pruned). With Promise.all a single failing read
+            // sinks the whole response, hiding the other 4 useful fields. Recover
+            // per-call and surface a `warnings` array instead. (#554)
+            const warnings = [];
+            const settled = await Promise.allSettled([
                 callDualStackingReadOnly("is-enrolled-this-cycle", [principalCV(resolvedAddress)]),
                 callDualStackingReadOnly("is-enrolled-in-next-cycle", [principalCV(resolvedAddress)]),
                 callDualStackingReadOnly("get-minimum-enrollment-amount", []),
                 callDualStackingReadOnly("get-apr-data", []),
                 callDualStackingReadOnly("current-overview-data", []),
             ]);
+            const readNames = [
+                "is-enrolled-this-cycle",
+                "is-enrolled-in-next-cycle",
+                "get-minimum-enrollment-amount",
+                "get-apr-data",
+                "current-overview-data",
+            ];
+            const values = settled.map((r, i) => {
+                if (r.status === "fulfilled")
+                    return r.value;
+                warnings.push(`${readNames[i]}: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
+                return null;
+            });
+            const [enrolledThisCycleRaw, enrolledNextCycleRaw, minimumAmountRaw, aprDataRaw, cycleOverviewRaw,] = values;
             // Parse APR data — returns {min-apr: uint, max-apr: uint} divided by 1_000_000 for %
             let apr = {
                 minApr: 0,
@@ -107,10 +127,11 @@ Note: Dual Stacking is only available on mainnet.`,
                 const raw = minimumAmountRaw;
                 minimumEnrollmentSats = raw.value !== undefined ? Number(raw.value) : 0;
             }
-            // Parse boolean enrollment flags
+            // Parse boolean enrollment flags. A failed read stays null (unknown)
+            // rather than collapsing to a misleading `false`.
             const parseBoolean = (raw) => {
                 if (raw === null || raw === undefined)
-                    return false;
+                    return null;
                 if (typeof raw === "boolean")
                     return raw;
                 const obj = raw;
@@ -126,6 +147,7 @@ Note: Dual Stacking is only available on mainnet.`,
                 minimumEnrollmentSats,
                 apr,
                 cycleOverview,
+                ...(warnings.length > 0 && { warnings }),
             });
         }
         catch (error) {

package/dist/tools/lightning.tools.js

@@ -7,9 +7,11 @@
  * same LightningProvider singleton to auto-pay invoice challenges on 402s.
  */
 import { z } from "zod";
+import { decode as decodeBolt11 } from "light-bolt11-decoder";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
 import { getLightningManager } from "../services/lightning-manager.js";
 import { getWalletManager } from "../services/wallet-manager.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { MempoolApi, getMempoolTxUrl, } from "../services/mempool-api.js";
 import { buildAndSignBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { UnisatIndexer } from "../services/unisat-indexer.js";
@@ -284,11 +286,39 @@ export function registerLightningTools(server) {
             if (!provider) {
                 throw new Error("Lightning wallet is locked. Use lightning_unlock first.");
             }
+            // Meter the invoice face value against the cumulative sats spend limit
+            // (#572). maxFeeSats only bounds the routing fee, not the payable amount,
+            // so without this a single invoice can pay out an unbounded amount.
+            // Decode the invoice to read the amount (millisats), mirroring the L402
+            // auto-pay path in x402.service.ts.
+            let decoded;
+            try {
+                decoded = decodeBolt11(bolt11);
+            }
+            catch (decodeErr) {
+                throw new Error(`BOLT-11 invoice could not be decoded: ${decodeErr instanceof Error ? decodeErr.message : String(decodeErr)}`);
+            }
+            const amountSection = decoded.sections.find((s) => s.name === "amount");
+            const amountMsat = amountSection?.value ? BigInt(amountSection.value) : 0n;
+            const amountSats = Number(amountMsat / 1000n);
+            if (amountSats === 0) {
+                throw new Error("Invoice has no amount; refusing to pay amountless invoices for safety (an unmeterable spend defeats the spending cap).");
+            }
+            // Key the sats ledger by the active Stacks address so BTC L1 / sBTC /
+            // L402 / Lightning spends share one budget. When the main wallet is
+            // locked (Lightning has its own session), fall back to a dedicated
+            // Lightning bucket so the pay is always metered. Note: a locked-STX
+            // user therefore gets a separate Lightning ledger from their STX-address
+            // ledger — see SECURITY.md.
+            const ledgerKey = getWalletManager().getActiveAccount()?.address ?? "__lightning__";
+            await getSpendLimiter().check("sats", BigInt(amountSats), ledgerKey);
             const result = await provider.payInvoice(bolt11, maxFeeSats);
+            await getSpendLimiter().record("sats", BigInt(amountSats), ledgerKey);
             return createJsonResponse({
                 success: true,
                 preimage: result.preimage,
                 feesPaidSats: result.feesPaid,
+                amountSats,
             });
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "description": "Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.",
   "mcpName": "io.github.aibtcdev/mcp-server",
   "type": "module",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Bitcoin L1 wallet for agents - check balances, send BTC, manage UTX
 license: MIT
 metadata:
   author: aibtcdev
-  version: 1.61.0 # x-release-please-version
+  version: 1.62.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---