@aibtc/mcp-server 1.57.0 → 1.59.0

package/dist/services/x402.service.js

@@ -1,5 +1,5 @@
 import axios from "axios";
-import { makeSTXTokenTransfer, makeContractCall, uintCV, principalCV, noneCV, PostConditionMode, } from "@stacks/transactions";
+import { makeSTXTokenTransfer, makeContractCall, uintCV, principalCV, noneCV, Pc, PostConditionMode, } from "@stacks/transactions";
 import { decodePaymentRequired, encodePaymentPayload, generatePaymentId, buildPaymentIdentifierExtension, X402_HEADERS, } from "../utils/x402-protocol.js";
 import { generateWallet, getStxAddress } from "@stacks/wallet-sdk";
 import { NETWORK, API_URL, getStacksNetwork } from "../config/networks.js";
@@ -11,6 +11,7 @@ import { getHiroApi } from "./hiro-api.js";
 import { createHash } from "crypto";
 import { InsufficientBalanceError } from "../utils/errors.js";
 import { getContracts, parseContractId } from "../config/contracts.js";
+import { resolveDefaultFee } from "../utils/fee.js";
 import { classifyCanonicalPaymentStatus, formatCanonicalPaymentStatus, resolveCanonicalPaymentStatus, } from "../utils/x402-payment-state.js";
 import { extractPaymentIdFromPaymentSignature } from "../utils/x402-recovery.js";
 import { emitCanonicalPaymentDecisionLogs, emitCanonicalPaymentPollLogs, emitPaymentLog, } from "../utils/x402-payment-logging.js";
@@ -42,6 +43,16 @@ function parseSatsCap(envName, fallback) {
     return parsed;
 }
 const L402_MAX_SATS_PER_INVOICE = parseSatsCap("L402_MAX_SATS_PER_INVOICE", DEFAULT_L402_MAX_SATS);
+/**
+ * Per-payment caps for the Stacks x402 interceptor, mirroring the L402 cap
+ * above: a malicious endpoint can demand an arbitrary amount in its 402
+ * response and an autoApprove'd call would pay it, bounded only by wallet
+ * balance. Known registry endpoints cost at most 0.02 STX / 100 sats, so the
+ * defaults leave generous headroom. Overridable via env vars.
+ */
+const X402_MAX_USTX_PER_PAYMENT = parseSatsCap("X402_MAX_USTX_PER_PAYMENT", 1_000_000 // 1 STX
+);
+const X402_MAX_SATS_PER_PAYMENT = parseSatsCap("X402_MAX_SATS_PER_PAYMENT", 10_000);
 // Track payment attempts per client instance (auto-cleanup via WeakMap)
 const paymentAttempts = new WeakMap();
 // Track 429 retry counts per client instance
@@ -457,6 +468,16 @@ export async function createApiClient(baseUrl, options) {
                 const networks = paymentRequired.accepts.map((a) => a.network).join(", ");
                 return Promise.reject(new Error(`No compatible Stacks payment option found. Available networks: ${networks}`));
             }
+            const tokenType = detectTokenType(selectedOption.asset);
+            const amount = BigInt(selectedOption.amount);
+            const isSbtc = tokenType === "sBTC";
+            const cap = isSbtc ? X402_MAX_SATS_PER_PAYMENT : X402_MAX_USTX_PER_PAYMENT;
+            const unit = isSbtc ? "sats" : "uSTX";
+            if (amount > BigInt(Math.floor(cap))) {
+                return Promise.reject(new Error(`x402 payment of ${amount} ${unit} exceeds the per-payment cap of ${cap} ${unit}. ` +
+                    `If this cost is expected, raise the cap via the ` +
+                    `${isSbtc ? "X402_MAX_SATS_PER_PAYMENT" : "X402_MAX_USTX_PER_PAYMENT"} env var.`));
+            }
             // Lazy-load account on first 402 — free endpoints never reach here
             const acct = await ensureAccount();
             // Verify the payment network matches our configured network
@@ -476,9 +497,11 @@ export async function createApiClient(baseUrl, options) {
                     account: acct,
                 });
             }
-            // Build a sponsored signed transaction (relay pays gas; fee: 0n)
-            const tokenType = detectTokenType(selectedOption.asset);
-            const amount = BigInt(selectedOption.amount);
+            // Build a non-sponsored signed transaction: the sender pays its own
+            // STX gas (fee + nonce auto-estimated by @stacks), and the x402
+            // facilitator simply verifies and broadcasts it. No relay sponsorship
+            // — this is the same tx shape the x402-stacks lib produces, and the
+            // balance check in onBeforePayment already accounts for the gas.
             const networkName = getStacksNetwork(acct.network);
             let transaction;
             if (tokenType === "sBTC") {
@@ -496,9 +519,18 @@ export async function createApiClient(baseUrl, options) {
                     ],
                     senderKey: acct.privateKey,
                     network: networkName,
-                    postConditionMode: PostConditionMode.Allow,
-                    sponsored: true,
-                    fee: 0n,
+                    // The payment amount is known at build time, so pin it: a
+                    // compromised token contract must not be able to pull more.
+                    postConditionMode: PostConditionMode.Deny,
+                    postConditions: [
+                        Pc.principal(acct.address)
+                            .willSendEq(amount)
+                            .ft(contracts.SBTC_TOKEN, "sbtc-token"),
+                    ],
+                    // Clamped medium fee — do NOT let @stacks auto-estimate, since
+                    // Hiro's contract_call high_priority tier is polluted by outliers
+                    // (observed >2000 STX). resolveDefaultFee caps it at 0.05 STX.
+                    fee: await resolveDefaultFee(acct.network, "contract_call"),
                 });
             }
             else {
@@ -508,8 +540,7 @@ export async function createApiClient(baseUrl, options) {
                     senderKey: acct.privateKey,
                     network: networkName,
                     memo: "",
-                    sponsored: true,
-                    fee: 0n,
+                    fee: await resolveDefaultFee(acct.network, "token_transfer"),
                 });
             }
             const txHex = "0x" + transaction.serialize();
@@ -716,8 +747,9 @@ export async function checkSufficientBalance(account, amount, asset, sponsored =
             const hiroApiForSbtc = getHiroApi(account.network);
             const stxInfoForSbtc = await hiroApiForSbtc.getStxBalance(account.address);
             const stxBalanceForSbtc = BigInt(stxInfoForSbtc.balance);
-            const sbtcFees = await hiroApiForSbtc.getMempoolFees();
-            const estimatedSbtcFee = BigInt(sbtcFees.contract_call.high_priority);
+            // Same clamped fee the interceptor actually sets on the sBTC contract
+            // call — so this check is exact, not a high-priority over-estimate.
+            const estimatedSbtcFee = await resolveDefaultFee(account.network, "contract_call");
             if (stxBalanceForSbtc < estimatedSbtcFee) {
                 const stxShortfall = estimatedSbtcFee - stxBalanceForSbtc;
                 throw new InsufficientBalanceError(`Insufficient STX balance to cover sBTC transfer fee: need ${formatStx(estimatedSbtcFee.toString())} estimated fee, ` +
@@ -733,8 +765,8 @@ export async function checkSufficientBalance(account, amount, asset, sponsored =
     const balance = BigInt(balanceInfo.balance);
     let totalRequired = requiredAmount;
     if (!sponsored) {
-        const mempoolFees = await hiroApi.getMempoolFees();
-        const estimatedFee = BigInt(mempoolFees.contract_call.high_priority);
+        // Same clamped fee the interceptor sets on the STX transfer.
+        const estimatedFee = await resolveDefaultFee(account.network, "token_transfer");
         totalRequired = requiredAmount + estimatedFee;
     }
     if (balance >= totalRequired)

package/dist/tools/bitcoin.tools.js

@@ -33,6 +33,19 @@ async function getBtcAddress(providedAddress) {
     throw new Error("No Bitcoin address provided and wallet is not unlocked. " +
         "Either provide an address or unlock your wallet first.");
 }
+/**
+ * Reject recipient addresses that belong to the other Bitcoin network before
+ * any UTXO fetching. The tx builder (@scure/btc-signer) rejects these too, but
+ * late and with a cryptic bech32/version-byte error.
+ */
+function validateRecipientNetwork(address) {
+    const prefixes = NETWORK === "mainnet" ? ["bc1", "1", "3"] : ["tb1", "m", "n", "2"];
+    if (!prefixes.some((p) => address.startsWith(p))) {
+        throw new Error(`Recipient "${address}" is not a ${NETWORK} address. ` +
+            `Expected a prefix of ${prefixes.join(", ")} — check that the address ` +
+            `matches the configured NETWORK.`);
+    }
+}
 /**
  * Format satoshis as BTC string
  */
@@ -231,6 +244,7 @@ export function registerBitcoinTools(server) {
         },
     }, async ({ recipient, amount, feeRate, includeOrdinals }) => {
         try {
+            validateRecipientNetwork(recipient);
             // Get wallet account (requires unlocked wallet)
             const walletManager = getWalletManager();
             const account = walletManager.getActiveAccount();

package/dist/tools/endpoint.tools.js

@@ -276,7 +276,9 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
             const api = await createApiClient(parsed.baseUrl, {
                 toolName: "execute_x402_endpoint",
                 onBeforePayment: async (requirements) => {
-                    await checkSufficientBalance(requirements.account, requirements.amount, requirements.asset, true);
+                    // Non-sponsored: sender pays its own gas, so validate STX for the
+                    // fee too (sponsored=false is the default, passed explicitly here).
+                    await checkSufficientBalance(requirements.account, requirements.amount, requirements.asset, false);
                 },
             });
             const response = await api.request({ method, url: parsed.requestPath, params, data });

package/dist/tools/inbox.tools.js

@@ -40,21 +40,18 @@ async function getNextNonce(address) {
     const hiroApi = getHiroApi(NETWORK);
     const accountInfo = await hiroApi.getAccountInfo(address);
     const confirmedNonce = accountInfo.nonce;
+    // The mempool scan is what makes the nonce safe against pending txs —
+    // silently skipping it on failure risks a nonce collision, so let it fail.
     let highestMempoolNonce = -1;
-    try {
-        const mempool = await hiroApi.getMempoolTransactions({
-            sender_address: address,
-            limit: 50,
-        });
-        for (const tx of mempool.results) {
-            if (tx.nonce > highestMempoolNonce) {
-                highestMempoolNonce = tx.nonce;
-            }
+    const mempool = await hiroApi.getMempoolTransactions({
+        sender_address: address,
+        limit: 50,
+    });
+    for (const tx of mempool.results) {
+        if (tx.nonce > highestMempoolNonce) {
+            highestMempoolNonce = tx.nonce;
         }
     }
-    catch {
-        // Non-fatal: fall back to confirmed nonce only
-    }
     const chainNext = Math.max(confirmedNonce, highestMempoolNonce + 1);
     // 3. Reconcile tracker with chain state
     await reconcileWithChain(address, chainNext);

package/dist/tools/news.tools.js

@@ -56,21 +56,18 @@ async function getNextNonce(address) {
     const hiroApi = getHiroApi(NETWORK);
     const accountInfo = await hiroApi.getAccountInfo(address);
     const confirmedNonce = accountInfo.nonce;
+    // The mempool scan is what makes the nonce safe against pending txs —
+    // silently skipping it on failure risks a nonce collision, so let it fail.
     let highestMempoolNonce = -1;
-    try {
-        const mempool = await hiroApi.getMempoolTransactions({
-            sender_address: address,
-            limit: 50,
-        });
-        for (const tx of mempool.results) {
-            if (tx.nonce > highestMempoolNonce) {
-                highestMempoolNonce = tx.nonce;
-            }
+    const mempool = await hiroApi.getMempoolTransactions({
+        sender_address: address,
+        limit: 50,
+    });
+    for (const tx of mempool.results) {
+        if (tx.nonce > highestMempoolNonce) {
+            highestMempoolNonce = tx.nonce;
         }
     }
-    catch {
-        // Non-fatal
-    }
     const chainNext = Math.max(confirmedNonce, highestMempoolNonce + 1);
     await reconcileWithChain(address, chainNext);
     return Math.max(chainNext, localNext ?? 0);

package/dist/tools/pillar-direct.tools.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import crypto from "crypto";
 import { tupleCV, stringAsciiCV, uintCV, principalCV, noneCV, trueCV, falseCV, } from "@stacks/transactions";
 import { getSigningKeyService, generateAuthId, } from "../services/signing-key.service.js";
-import { getPillarApi } from "../services/pillar-api.service.js";
+import { getPillarApi, PillarApiError } from "../services/pillar-api.service.js";
 import { getHiroApi } from "../services/hiro-api.js";
 import { NETWORK } from "../config/networks.js";
 import { PILLAR_API_KEY } from "../config/pillar.js";
@@ -497,8 +497,12 @@ export function registerPillarDirectTools(server) {
                 const walletInfo = await api.get(`/api/smart-wallet/${walletName}`);
                 walletStatus = walletInfo.data?.status || null;
             }
-            catch {
-                // Wallet not found in backend
+            catch (error) {
+                // 404 = wallet not registered in backend. Anything else (network,
+                // 5xx) must surface, or an initialized wallet gets misreported.
+                if (!(error instanceof PillarApiError && error.status === 404)) {
+                    throw error;
+                }
             }
             if (!walletStatus || walletStatus === "pending_init") {
                 return createJsonResponse({
@@ -554,8 +558,11 @@ export function registerPillarDirectTools(server) {
                 });
                 position = unwindQuote.data;
             }
-            catch {
-                // unwind-quote may fail for fresh wallets with no position
+            catch (error) {
+                // 4xx = fresh wallet with no position. Infra failures must surface.
+                if (!(error instanceof PillarApiError && error.status < 500)) {
+                    throw error;
+                }
             }
             return createJsonResponse({
                 success: true,
@@ -1146,21 +1153,16 @@ export function registerPillarDirectTools(server) {
                 const frac = (micro % BigInt(1_000_000)).toString().padStart(6, "0");
                 return `${whole}.${frac} STX`;
             };
-            // Fetch PoX cycle info
-            let poxInfo = null;
-            try {
-                const pox = await hiro.getPoxInfo();
-                poxInfo = {
-                    currentCycleId: pox.current_cycle.id,
-                    nextCycleId: pox.next_cycle.id,
-                    blocksUntilNextCycle: pox.next_cycle.blocks_until_reward_phase,
-                    minAmountUstx: pox.min_amount_ustx,
-                    isPoxActive: pox.current_cycle.is_pox_active,
-                };
-            }
-            catch {
-                // PoX info fetch failed, continue without it
-            }
+            // Fetch PoX cycle info — a global endpoint with no "not found" case,
+            // so any failure is infrastructure and should surface.
+            const pox = await hiro.getPoxInfo();
+            const poxInfo = {
+                currentCycleId: pox.current_cycle.id,
+                nextCycleId: pox.next_cycle.id,
+                blocksUntilNextCycle: pox.next_cycle.blocks_until_reward_phase,
+                minAmountUstx: pox.min_amount_ustx,
+                isPoxActive: pox.current_cycle.is_pox_active,
+            };
             // Check enrollment status via backend
             const api = getPillarApi();
             const contractParts = session.smartWallet.split(".");
@@ -1175,8 +1177,13 @@ export function registerPillarDirectTools(server) {
                     };
                 }
             }
-            catch {
-                // Backend lookup failed, continue without enrollment info
+            catch (error) {
+                // 404 = wallet not registered, so not enrolled. Other failures
+                // must surface — defaulting to enrolled:false on a backend outage
+                // misreports an enrolled wallet and could prompt re-enrollment.
+                if (!(error instanceof PillarApiError && error.status === 404)) {
+                    throw error;
+                }
             }
             const isStacking = lockedMicro > BigInt(0);
             return createJsonResponse({

package/dist/tools/sbtc.tools.js

@@ -283,16 +283,9 @@ Signers later process the request and send BTC on L1.`,
         description: "Get information about how to deposit BTC to receive sBTC.",
     }, async () => {
         try {
-            // Try to get wallet account (don't throw if not unlocked)
+            // getActiveAccount returns null when locked - generic instructions then
             const walletManager = getWalletManager();
-            let account;
-            try {
-                account = walletManager.getActiveAccount();
-            }
-            catch {
-                // Wallet not unlocked - return generic instructions
-                account = null;
-            }
+            const account = walletManager.getActiveAccount();
             // If wallet is unlocked and has Taproot keys, generate real deposit address
             if (account?.taprootPublicKey) {
                 const depositService = getSbtcDepositService(NETWORK);

package/dist/tools/scaffold.tools.js

@@ -8,20 +8,15 @@ import { getWalletAddress } from "../services/x402.service.js";
  * Check if a directory contains an existing x402 project
  */
 async function isExistingX402Project(dir) {
-    try {
-        const indexPath = path.join(dir, "src", "index.ts");
-        const middlewarePath = path.join(dir, "src", "x402-middleware.ts");
-        const packagePath = path.join(dir, "package.json");
-        const [hasIndex, hasMiddleware, hasPackage] = await Promise.all([
-            fs.access(indexPath).then(() => true).catch(() => false),
-            fs.access(middlewarePath).then(() => true).catch(() => false),
-            fs.access(packagePath).then(() => true).catch(() => false),
-        ]);
-        return hasIndex && hasMiddleware && hasPackage;
-    }
-    catch {
-        return false;
-    }
+    const indexPath = path.join(dir, "src", "index.ts");
+    const middlewarePath = path.join(dir, "src", "x402-middleware.ts");
+    const packagePath = path.join(dir, "package.json");
+    const [hasIndex, hasMiddleware, hasPackage] = await Promise.all([
+        fs.access(indexPath).then(() => true).catch(() => false),
+        fs.access(middlewarePath).then(() => true).catch(() => false),
+        fs.access(packagePath).then(() => true).catch(() => false),
+    ]);
+    return hasIndex && hasMiddleware && hasPackage;
 }
 /**
  * Validate that a project directory does not already exist.

package/dist/tools/settings.tools.js

@@ -198,7 +198,7 @@ Example: http://localhost:3999`,
     server.registerTool("get_server_version", {
         description: `Check the currently running MCP server version and compare with the latest published version on npm.
 Use this to detect if you're running a stale cached version (common with npx).
-If your version is outdated, clear the npx cache and reinstall: npx clear-npx-cache && npx @aibtc/mcp-server@latest --install`,
+If your version is outdated, clear the npx cache and restart your MCP client: npx clear-npx-cache (the client config already points at @latest, so the next launch pulls the newest version).`,
         inputSchema: {},
     }, async () => {
         try {
@@ -237,7 +237,7 @@ If your version is outdated, clear the npx cache and reinstall: npx clear-npx-ca
                 updateAvailable,
                 package: "@aibtc/mcp-server",
                 hint: updateAvailable
-                    ? "⚠️  Update available! Clear npx cache and reinstall: npx clear-npx-cache && npx @aibtc/mcp-server@latest --install"
+                    ? "⚠️  Update available! Clear the npx cache and restart your MCP client: npx clear-npx-cache (config already points at @latest, so the next launch pulls the newest version)."
                     : fetched
                         ? "✅ Running the latest version"
                         : "Unable to verify latest version (network error)",

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { uintCV, contractPrincipalCV, PostConditionMode, deserializeCV, cvToJSON, } from "@stacks/transactions";
 import { getAccount, NETWORK } from "../services/x402.service.js";
-import { getHiroApi } from "../services/hiro-api.js";
+import { getHiroApi, isNotFoundError } from "../services/hiro-api.js";
 import { callContract } from "../transactions/builder.js";
 import { getExplorerTxUrl } from "../config/networks.js";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
@@ -100,14 +100,17 @@ Note: Stackspot is only available on mainnet.`,
                 try {
                     currentValueUstx = await callPotReadOnly(pot.contractName, "get-pot-value", []);
                 }
-                catch {
-                    // pot may not be deployed or reachable — skip gracefully
+                catch (error) {
+                    // 404 = pot contract not deployed; other failures surface
+                    if (!isNotFoundError(error))
+                        throw error;
                 }
                 try {
                     isLocked = await callPotReadOnly(pot.contractName, "is-locked", []);
                 }
-                catch {
-                    // same
+                catch (error) {
+                    if (!isNotFoundError(error))
+                        throw error;
                 }
                 return {
                     name: pot.name,

package/dist/tools/yield-dashboard.tools.js

@@ -251,21 +251,17 @@ async function readStackingPosition(walletAddress) {
     return pos;
 }
 async function getWalletBalances(walletAddress) {
-    try {
-        const res = await fetch(`${MAINNET_HIRO_API}/extended/v1/address/${walletAddress}/balances`);
-        if (!res.ok)
-            return { stxMicroStx: 0, sbtcSats: 0 };
-        const data = (await res.json());
-        const stxMicroStx = parseInt(data.stx?.balance ?? "0", 10);
-        const sbtcKey = Object.keys(data.fungible_tokens ?? {}).find((k) => k.toLowerCase().includes("sbtc"));
-        const sbtcSats = sbtcKey
-            ? parseInt(data.fungible_tokens?.[sbtcKey]?.balance ?? "0", 10)
-            : 0;
-        return { stxMicroStx, sbtcSats };
-    }
-    catch {
-        return { stxMicroStx: 0, sbtcSats: 0 };
+    const res = await fetch(`${MAINNET_HIRO_API}/extended/v1/address/${walletAddress}/balances`);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch wallet balances for ${walletAddress}: HTTP ${res.status}`);
     }
+    const data = (await res.json());
+    const stxMicroStx = parseInt(data.stx?.balance ?? "0", 10);
+    const sbtcKey = Object.keys(data.fungible_tokens ?? {}).find((k) => k.toLowerCase().includes("sbtc"));
+    const sbtcSats = sbtcKey
+        ? parseInt(data.fungible_tokens?.[sbtcKey]?.balance ?? "0", 10)
+        : 0;
+    return { stxMicroStx, sbtcSats };
 }
 async function checkZestV2() {
     try {

package/dist/utils/encryption.js

@@ -37,6 +37,7 @@ export async function encrypt(plaintext, password) {
     const key = await deriveKey(password, salt);
     // Encrypt with AES-256-GCM
     const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    key.fill(0); // cipher holds its own copy
     const encrypted = Buffer.concat([
         cipher.update(plaintext, "utf8"),
         cipher.final(),
@@ -64,6 +65,7 @@ export async function decrypt(encrypted, password) {
     const key = await deriveKeyWithParams(password, salt, encrypted.scryptParams);
     // Decrypt with AES-256-GCM
     const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    key.fill(0); // decipher holds its own copy
     decipher.setAuthTag(authTag);
     try {
         const decrypted = Buffer.concat([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.57.0",
+  "version": "1.59.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",
@@ -18,9 +18,13 @@
   },
   "files": [
     "dist",
+    "!dist/**/*.map",
     "README.md",
     "skill"
   ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "keywords": [
     "claude",
     "claude-code",
@@ -60,7 +64,7 @@
     "@stacks/transactions": "^7.3.1",
     "@stacks/wallet-sdk": "^7.2.0",
     "alex-sdk": "^3.2.1",
-    "axios": "^1.15.0",
+    "axios": "^1.17.0",
     "dotenv": "^17.3.1",
     "light-bolt11-decoder": "^3.2.0",
     "micro-ordinals": "^0.3.0",
@@ -68,7 +72,7 @@
     "path-to-regexp": "^8.4.0",
     "sbtc": "^0.3.2",
     "tslib": "^2.8.1",
-    "ws": "^8.19.0",
+    "ws": "^8.21.0",
     "x402-stacks": "^2.0.3",
     "zod": "^4.3.6"
   },
@@ -77,9 +81,10 @@
     "@types/ws": "^8.18.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.8"
   },
   "overrides": {
-    "lodash": "^4.18.0"
+    "lodash": "^4.18.0",
+    "axios": "^1.17.0"
   }
 }

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.57.0 # x-release-please-version
+  version: 1.59.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---
@@ -15,13 +15,24 @@ A skill for managing Bitcoin L1 wallets with optional Pillar smart wallet and St
 
 ## Install
 
-One-command installation:
+One-command installation (Claude Code is the default):
 
 ```bash
 npx @aibtc/mcp-server@latest --install
 ```
 
-For testnet:
+Other MCP clients are selected with a flag:
+
+```bash
+npx @aibtc/mcp-server@latest --install --cursor     # Cursor
+npx @aibtc/mcp-server@latest --install --codex      # OpenAI Codex CLI
+npx @aibtc/mcp-server@latest --install --gemini     # Gemini CLI
+npx @aibtc/mcp-server@latest --install --windsurf   # Windsurf
+npx @aibtc/mcp-server@latest --install --vscode     # VS Code
+npx @aibtc/mcp-server@latest --install --desktop    # Claude Desktop
+```
+
+For testnet, add `--testnet` to any command:
 
 ```bash
 npx @aibtc/mcp-server@latest --install --testnet