@aibtc/mcp-server 1.57.0 → 1.59.0

package/README.md

@@ -45,32 +45,53 @@ This detects your OS and writes to the correct Claude Desktop config file:
 
 Restart Claude Desktop after installing.
 
-### Testnet Mode
+### Other MCP Clients
 
-Add `--testnet` to either command:
+This is a standard stdio MCP server, so it works with **any** MCP-compatible client. Claude Code is the default `--install` target; select another client with a flag:
 
 ```bash
-# Claude Code on testnet
-npx @aibtc/mcp-server@latest --install --testnet
+npx @aibtc/mcp-server@latest --install --cursor     # Cursor
+npx @aibtc/mcp-server@latest --install --windsurf   # Windsurf
+npx @aibtc/mcp-server@latest --install --gemini     # Gemini CLI
+npx @aibtc/mcp-server@latest --install --codex      # OpenAI Codex CLI
+npx @aibtc/mcp-server@latest --install --vscode     # VS Code (writes ./.vscode/mcp.json)
+```
+
+| Flag | Client | Config written |
+|------|--------|----------------|
+| _(none)_ | Claude Code | `~/.claude.json` |
+| `--desktop` | Claude Desktop | `claude_desktop_config.json` (see path table above) |
+| `--cursor` | Cursor | `~/.cursor/mcp.json` |
+| `--windsurf` | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| `--gemini` | Gemini CLI | `~/.gemini/settings.json` |
+| `--codex` | OpenAI Codex CLI | `~/.codex/config.toml` |
+| `--vscode` | VS Code (Copilot agent) | `./.vscode/mcp.json` (project-scoped) |
+
+Each installer merges into the existing config — it won't clobber other servers or settings. Restart the client afterward.
 
-# Claude Desktop on testnet
-npx @aibtc/mcp-server@latest --install --desktop --testnet
+### Testnet Mode
+
+Add `--testnet` to any install command:
+
+```bash
+npx @aibtc/mcp-server@latest --install --testnet            # Claude Code, testnet
+npx @aibtc/mcp-server@latest --install --cursor --testnet   # Cursor, testnet
 ```
 
 > **Why npx?** Using `npx @aibtc/mcp-server@latest` ensures you always get the newest version automatically. Global installs (`npm install -g`) won't auto-update.
 
 ### Manual Configuration
 
-If you prefer to configure manually, add the following to your config file.
+If you prefer to configure manually, add the following to your client's config file. The `-y` flag stops npx from prompting for confirmation.
 
-**Claude Code** (`~/.claude.json`):
+**Claude Code / Claude Desktop / Cursor / Windsurf / Gemini CLI** — `mcpServers` JSON:
 
 ```json
 {
   "mcpServers": {
     "aibtc": {
       "command": "npx",
-      "args": ["@aibtc/mcp-server@latest"],
+      "args": ["-y", "@aibtc/mcp-server@latest"],
       "env": {
         "NETWORK": "mainnet"
       }
@@ -79,23 +100,50 @@ If you prefer to configure manually, add the following to your config file.
 }
 ```
 
-**Claude Desktop** (`claude_desktop_config.json` -- see path table above):
+**VS Code** (`.vscode/mcp.json`) — uses a `servers` key and a typed entry:
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "aibtc": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@aibtc/mcp-server@latest"],
-      "env": {
-        "NETWORK": "mainnet"
-      }
+      "env": { "NETWORK": "mainnet" }
+    }
+  }
+}
+```
+
+**OpenAI Codex CLI** (`~/.codex/config.toml`) — TOML, not JSON:
+
+```toml
+[mcp_servers.aibtc]
+command = "npx"
+args = ["-y", "@aibtc/mcp-server@latest"]
+
+[mcp_servers.aibtc.env]
+NETWORK = "mainnet"
+```
+
+**Zed** (`settings.json`) — uses a `context_servers` key:
+
+```json
+{
+  "context_servers": {
+    "aibtc": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "@aibtc/mcp-server@latest"],
+      "env": { "NETWORK": "mainnet" }
     }
   }
 }
 ```
 
-> **Note:** Claude Desktop requires the `-y` flag in args so npx doesn't prompt for confirmation.
+**Cline / Roo Code** (VS Code extension) — add the same `mcpServers` JSON block above via the extension's MCP settings panel (the exact `cline_mcp_settings.json` path varies by OS and VS Code build).
+
+> Any other MCP client works too — point it at `npx -y @aibtc/mcp-server@latest` over stdio with `NETWORK` in the env.
 
 ## Giving Claude a Wallet
 

package/dist/index.js

@@ -13,8 +13,13 @@ import { initializeStorage } from "./utils/storage.js";
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 // =============================================================================
-// AUTO-INSTALL FOR CLAUDE CODE AND CLAUDE DESKTOP
+// AUTO-INSTALL FOR MCP CLIENTS
+//
+// The server is a standard stdio MCP server, so it works with any MCP client.
+// `--install` writes the correct config for a target client. Claude Code is the
+// default; other clients are selected with a flag (e.g. --cursor, --codex).
 // =============================================================================
+const SERVER_NPM = "@aibtc/mcp-server@latest";
 function getClaudeDesktopConfigPath() {
     const platform = process.platform;
     const home = os.homedir();
@@ -31,13 +36,24 @@ function getClaudeDesktopConfigPath() {
     }
 }
 async function readJsonConfig(filePath) {
+    let content;
+    try {
+        content = await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {}; // No config yet - fresh install
+        }
+        throw error;
+    }
     try {
-        const content = await fs.readFile(filePath, "utf8");
         return JSON.parse(content);
     }
     catch {
-        // File doesn't exist or isn't valid JSON, start fresh
-        return {};
+        // Never silently replace an unparseable config: it may hold the user's
+        // other MCP servers, and "merging" into {} would discard them on write.
+        throw new Error(`Existing config at ${filePath} is not valid JSON. ` +
+            `Fix or remove it, then re-run the install.`);
     }
 }
 async function writeJsonConfig(filePath, config) {
@@ -46,56 +62,145 @@ async function writeJsonConfig(filePath, config) {
     await fs.mkdir(dir, { recursive: true });
     await fs.writeFile(filePath, JSON.stringify(config, null, 2));
 }
-async function installToClaudeCode() {
-    const claudeConfigPath = path.join(os.homedir(), ".claude.json");
-    const network = process.argv.includes("--testnet") ? "testnet" : "mainnet";
-    console.log("🔧 Installing @aibtc/mcp-server to Claude Code...\n");
-    const config = await readJsonConfig(claudeConfigPath);
-    if (!config.mcpServers) {
-        config.mcpServers = {};
-    }
-    config.mcpServers["aibtc"] = {
+// Standard MCP server entry shared by every JSON-based client config.
+function serverEntry(network) {
+    return {
         command: "npx",
-        args: ["@aibtc/mcp-server@latest"],
-        env: {
-            NETWORK: network,
-        },
+        args: ["-y", SERVER_NPM],
+        env: { NETWORK: network },
     };
-    await writeJsonConfig(claudeConfigPath, config);
-    console.log("✅ Successfully installed!\n");
-    console.log(`   Config: ${claudeConfigPath}`);
-    console.log(`   Network: ${network}`);
-    console.log("\n📋 Next steps:");
-    console.log("   1. Restart Claude Code (close and reopen terminal)");
-    console.log("   2. Ask Claude: \"What's your wallet address?\"");
-    console.log("   3. Claude will guide you through wallet setup\n");
-    if (network === "testnet") {
-        console.log("💡 Tip: Get testnet STX at https://explorer.hiro.so/sandbox/faucet?chain=testnet\n");
-    }
 }
-async function installToClaudeDesktop() {
-    const configPath = getClaudeDesktopConfigPath();
-    const network = process.argv.includes("--testnet") ? "testnet" : "mainnet";
-    console.log("🔧 Installing @aibtc/mcp-server to Claude Desktop...\n");
+// Most clients (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI) use
+// the same `{ "mcpServers": { "aibtc": {...} } }` JSON shape.
+async function writeMcpServersJson(configPath, network) {
     const config = await readJsonConfig(configPath);
-    if (!config.mcpServers) {
-        config.mcpServers = {};
-    }
-    config.mcpServers["aibtc"] = {
+    const servers = (config.mcpServers ??= {});
+    servers["aibtc"] = serverEntry(network);
+    await writeJsonConfig(configPath, config);
+}
+// VS Code (.vscode/mcp.json) uses a `servers` key and a typed stdio entry.
+async function writeVsCodeJson(configPath, network) {
+    const config = await readJsonConfig(configPath);
+    const servers = (config.servers ??= {});
+    servers["aibtc"] = {
+        type: "stdio",
         command: "npx",
-        args: ["-y", "@aibtc/mcp-server@latest"],
-        env: {
-            NETWORK: network,
-        },
+        args: ["-y", SERVER_NPM],
+        env: { NETWORK: network },
     };
     await writeJsonConfig(configPath, config);
+}
+// Codex uses TOML, not JSON. Rewrite only the `[mcp_servers.aibtc]` section so
+// the rest of the user's config.toml (including comments) is preserved.
+function stripCodexSection(content) {
+    const out = [];
+    let skipping = false;
+    for (const line of content.split("\n")) {
+        const header = line.trim();
+        if (header.startsWith("[")) {
+            skipping = header === "[mcp_servers.aibtc]" || header.startsWith("[mcp_servers.aibtc.");
+        }
+        if (!skipping)
+            out.push(line);
+    }
+    return out.join("\n");
+}
+async function writeCodexToml(configPath, network) {
+    let existing = "";
+    try {
+        existing = await fs.readFile(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error; // Unreadable existing config must not be clobbered
+        }
+    }
+    const preserved = stripCodexSection(existing).replace(/\s+$/, "");
+    const block = [
+        "[mcp_servers.aibtc]",
+        'command = "npx"',
+        `args = ["-y", "${SERVER_NPM}"]`,
+        "",
+        "[mcp_servers.aibtc.env]",
+        `NETWORK = "${network}"`,
+    ].join("\n");
+    const content = (preserved ? `${preserved}\n\n` : "") + block + "\n";
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, content);
+}
+const INSTALL_TARGETS = [
+    {
+        flag: "--desktop",
+        label: "Claude Desktop",
+        configPath: getClaudeDesktopConfigPath,
+        write: writeMcpServersJson,
+        restart: "Restart Claude Desktop (quit and reopen the app)",
+    },
+    {
+        flag: "--cursor",
+        label: "Cursor",
+        configPath: () => path.join(os.homedir(), ".cursor", "mcp.json"),
+        write: writeMcpServersJson,
+        restart: "Restart Cursor",
+    },
+    {
+        flag: "--windsurf",
+        label: "Windsurf",
+        configPath: () => path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json"),
+        write: writeMcpServersJson,
+        restart: "Restart Windsurf",
+    },
+    {
+        flag: "--gemini",
+        label: "Gemini CLI",
+        configPath: () => path.join(os.homedir(), ".gemini", "settings.json"),
+        write: writeMcpServersJson,
+        restart: "Restart the Gemini CLI",
+    },
+    {
+        flag: "--vscode",
+        label: "VS Code",
+        configPath: () => path.join(process.cwd(), ".vscode", "mcp.json"),
+        write: writeVsCodeJson,
+        restart: "Reload VS Code, then start the MCP server from the .vscode/mcp.json gutter",
+    },
+    {
+        flag: "--codex",
+        label: "Codex CLI",
+        configPath: () => path.join(os.homedir(), ".codex", "config.toml"),
+        write: writeCodexToml,
+        restart: "Restart the Codex CLI",
+    },
+    {
+        flag: null,
+        label: "Claude Code",
+        configPath: () => path.join(os.homedir(), ".claude.json"),
+        write: writeMcpServersJson,
+        restart: "Restart Claude Code (close and reopen terminal)",
+    },
+];
+function resolveInstallTarget() {
+    const matched = INSTALL_TARGETS.filter((t) => t.flag && process.argv.includes(t.flag));
+    if (matched.length > 1) {
+        console.warn(`⚠️  Multiple client flags passed (${matched.map((t) => t.flag).join(", ")}); using ${matched[0].label}.`);
+    }
+    // Default to the entry explicitly marked as default (flag === null) — Claude Code.
+    return matched[0] ?? INSTALL_TARGETS.find((t) => t.flag === null);
+}
+async function runInstall() {
+    const network = process.argv.includes("--testnet") ? "testnet" : "mainnet";
+    const target = resolveInstallTarget();
+    const configPath = target.configPath();
+    console.log(`🔧 Installing @aibtc/mcp-server to ${target.label}...\n`);
+    await target.write(configPath, network);
     console.log("✅ Successfully installed!\n");
-    console.log(`   Config: ${configPath}`);
+    console.log(`   Client:  ${target.label}`);
+    console.log(`   Config:  ${configPath}`);
     console.log(`   Network: ${network}`);
     console.log("\n📋 Next steps:");
-    console.log("   1. Restart Claude Desktop (quit and reopen the app)");
-    console.log("   2. Ask Claude: \"What's your wallet address?\"");
-    console.log("   3. Claude will guide you through wallet setup\n");
+    console.log(`   1. ${target.restart}`);
+    console.log("   2. Ask the agent: \"What's your wallet address?\"");
+    console.log("   3. The agent will guide you through wallet setup\n");
     if (network === "testnet") {
         console.log("💡 Tip: Get testnet STX at https://explorer.hiro.so/sandbox/faucet?chain=testnet\n");
     }
@@ -126,9 +231,7 @@ if (process.argv[2] === "yield-hunter") {
 }
 // Check for --install flag
 else if (process.argv.includes("--install") || process.argv.includes("install")) {
-    const isDesktop = process.argv.includes("--desktop");
-    const installFn = isDesktop ? installToClaudeDesktop : installToClaudeCode;
-    installFn()
+    runInstall()
         .then(() => process.exit(0))
         .catch((error) => {
         console.error("❌ Installation failed:", redactSensitive(error.message));

package/dist/services/credentials.js

@@ -39,6 +39,7 @@ async function encrypt(data, password) {
     const iv = crypto.randomBytes(12);
     const key = await deriveKey(password, salt);
     const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    key.fill(0); // cipher holds its own copy
     const encrypted = Buffer.concat([cipher.update(data, "utf8"), cipher.final()]);
     const authTag = cipher.getAuthTag();
     return {
@@ -53,6 +54,7 @@ async function encrypt(data, password) {
 async function decrypt(encrypted, password) {
     const key = await deriveKey(password, Buffer.from(encrypted.salt, "base64"));
     const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(encrypted.iv, "base64"));
+    key.fill(0); // decipher holds its own copy
     decipher.setAuthTag(Buffer.from(encrypted.authTag, "base64"));
     const decrypted = Buffer.concat([
         decipher.update(Buffer.from(encrypted.ciphertext, "base64")),
@@ -67,12 +69,15 @@ function emptyStore() {
 async function save() {
     if (!_store || !_password)
         throw new Error("Store not unlocked");
-    await fs.mkdir(getStoreDir(), { recursive: true });
+    await fs.mkdir(getStoreDir(), { recursive: true, mode: 0o700 });
     const file = {
         version: VERSION,
         encrypted: await encrypt(JSON.stringify(_store), _password),
     };
-    await fs.writeFile(getStoreFile(), JSON.stringify(file, null, 2));
+    // Owner-only perms + atomic rename, same pattern as the wallet keystores
+    const tempFile = getStoreFile() + ".tmp";
+    await fs.writeFile(tempFile, JSON.stringify(file, null, 2), { mode: 0o600 });
+    await fs.rename(tempFile, getStoreFile());
 }
 async function load(password) {
     const raw = await fs.readFile(getStoreFile(), "utf-8");

package/dist/services/defi.service.js

@@ -1,6 +1,6 @@
 import { uintCV, contractPrincipalCV, cvToJSON, hexToCV, PostConditionMode, Pc, principalCV, noneCV, someCV, listCV, bufferCV, } from "@stacks/transactions";
 import { AlexSDK, Currency } from "alex-sdk";
-import { getHiroApi } from "./hiro-api.js";
+import { getHiroApi, isNotFoundError } from "./hiro-api.js";
 import { getAlexContracts, getZestContracts, parseContractId, ZEST_ASSETS, ZEST_V2_MARKET, ZEST_V2_MARKET_VAULT, } from "../config/index.js";
 import { callContract } from "../transactions/builder.js";
 // ============================================================================
@@ -129,8 +129,10 @@ export class AlexDexService {
             }
             return null;
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     /**
@@ -360,8 +362,10 @@ export class ZestProtocolService {
                 healthFactor: position["health-factor"]?.value,
             };
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     /**
@@ -377,8 +381,10 @@ export class ZestProtocolService {
             }
             return cvToJSON(hexToCV(result.result));
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     /**
@@ -411,8 +417,12 @@ export class ZestProtocolService {
                 }
             }
         }
-        catch {
-            // Fall back to shares as lower bound estimate
+        catch (error) {
+            // Only fall back to the shares lower-bound estimate when the vault
+            // function is missing — network/server failures must surface, or the
+            // post-conditions built from this value would be silently wrong.
+            if (!isNotFoundError(error))
+                throw error;
         }
         return shares;
     }
@@ -431,8 +441,10 @@ export class ZestProtocolService {
                 }
             }
         }
-        catch {
-            // Fall back to amount as upper bound
+        catch (error) {
+            // Same rationale as getUnderlyingFromShares: estimate only on 404.
+            if (!isNotFoundError(error))
+                throw error;
         }
         return amount;
     }

package/dist/services/hiro-api.d.ts

@@ -7,6 +7,16 @@ export declare class HiroApiRateLimitError extends Error {
     readonly retryAfterSeconds: number;
     constructor(message: string, retryAfterSeconds: number);
 }
+/**
+ * HTTP error from the Hiro / BNS V2 APIs, carrying the status code so
+ * callers can treat 404 as "not found" without swallowing other failures.
+ */
+export declare class HiroApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** True when the error is an expected "resource does not exist" response. */
+export declare function isNotFoundError(error: unknown): boolean;
 export interface AccountInfo {
     balance: string;
     locked: string;

package/dist/services/hiro-api.js

@@ -16,6 +16,22 @@ export class HiroApiRateLimitError extends Error {
         this.name = "HiroApiRateLimitError";
     }
 }
+/**
+ * HTTP error from the Hiro / BNS V2 APIs, carrying the status code so
+ * callers can treat 404 as "not found" without swallowing other failures.
+ */
+export class HiroApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "HiroApiError";
+    }
+}
+/** True when the error is an expected "resource does not exist" response. */
+export function isNotFoundError(error) {
+    return error instanceof HiroApiError && error.status === 404;
+}
 // ============================================================================
 // Hiro API Service
 // ============================================================================
@@ -51,7 +67,7 @@ export class HiroApiService {
                 throw new HiroApiRateLimitError(`Hiro API rate limit exceeded. Retry after ${retryAfterSeconds}s`, retryAfterSeconds);
             }
             const errorText = await response.text();
-            throw new Error(`Hiro API error (${response.status}): ${errorText}`);
+            throw new HiroApiError(`Hiro API error (${response.status}): ${errorText}`, response.status);
         }
         return response.json();
     }
@@ -123,8 +139,10 @@ export class HiroApiService {
         try {
             return await this.fetch(`/metadata/v1/ft/${contractId}`);
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     async getTokenHolders(contractId, options) {
@@ -329,8 +347,10 @@ export class HiroApiService {
             const info = await this.getBnsNameInfo(name);
             return info.address;
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     // ==========================================================================
@@ -385,7 +405,7 @@ export class BnsV2ApiService {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`BNS V2 API error (${response.status}): ${errorText}`);
+            throw new HiroApiError(`BNS V2 API error (${response.status}): ${errorText}`, response.status);
         }
         return response.json();
     }
@@ -431,8 +451,10 @@ export class BnsV2ApiService {
             }
             return null;
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
 }

package/dist/services/nft.service.js

@@ -1,5 +1,5 @@
 import { uintCV, principalCV } from "@stacks/transactions";
-import { getHiroApi } from "./hiro-api.js";
+import { getHiroApi, HiroApiError } from "./hiro-api.js";
 import { parseContractId } from "../config/index.js";
 import { callContract } from "../transactions/builder.js";
 import { createNftSendPostCondition } from "../transactions/post-conditions.js";
@@ -51,8 +51,13 @@ export class NftService {
             }
             return null;
         }
-        catch {
-            return null;
+        catch (error) {
+            // 4xx means the contract doesn't implement get-owner (or rejects the
+            // call) — that is "no owner". Network/server failures must surface.
+            if (error instanceof HiroApiError && error.status < 500) {
+                return null;
+            }
+            throw error;
         }
     }
     /**
@@ -75,8 +80,12 @@ export class NftService {
                 }
             }
         }
-        catch {
-            // Function may not exist or may fail
+        catch (error) {
+            // 4xx means the contract doesn't implement get-last-token-id —
+            // supply is simply unknown. Network/server failures must surface.
+            if (!(error instanceof HiroApiError && error.status < 500)) {
+                throw error;
+            }
         }
         return {
             contractId,

package/dist/services/pillar-api.service.d.ts

@@ -1,3 +1,11 @@
+/**
+ * HTTP error from the Pillar API, carrying the status code so callers can
+ * treat 4xx ("no such wallet / no position") differently from infra failures.
+ */
+export declare class PillarApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
 declare class PillarApiService {
     private baseUrl;
     private apiKey;

package/dist/services/pillar-api.service.js

@@ -1,4 +1,16 @@
 import { PILLAR_API_URL, PILLAR_API_KEY } from "../config/pillar.js";
+/**
+ * HTTP error from the Pillar API, carrying the status code so callers can
+ * treat 4xx ("no such wallet / no position") differently from infra failures.
+ */
+export class PillarApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "PillarApiError";
+    }
+}
 class PillarApiService {
     baseUrl;
     apiKey;
@@ -32,7 +44,7 @@ class PillarApiService {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Pillar API error (${response.status}): ${errorText}`);
+            throw new PillarApiError(`Pillar API error (${response.status}): ${errorText}`, response.status);
         }
         return response.json();
     }