@quackai/q402-mcp 0.8.6 → 0.8.8

package/README.md

@@ -22,12 +22,15 @@ Quote → route → (optional) settle stablecoin payments across 10 EVM chains,
 
 | Client | Command / config |
 |---|---|
-| **Claude Desktop / Claude Code** | `claude mcp add q402 -- npx -y @quackai/q402-mcp` |
+| **Claude Code (CLI)** | `claude mcp add q402 -- npx -y @quackai/q402-mcp` |
+| **Claude Desktop (app)** | Edit `claude_desktop_config.json` (Settings → Developer → Edit Config): `{ "mcpServers": { "q402": { "command": "npx", "args": ["-y", "@quackai/q402-mcp"] } } }`. Restart the app. |
 | **OpenAI Codex CLI** | `codex mcp add q402 -- npx -y @quackai/q402-mcp` (Windows fallback: see below) |
 | **Cursor** | Add to `~/.cursor/mcp.json`: `{ "mcpServers": { "q402": { "command": "npx", "args": ["-y", "@quackai/q402-mcp"] } } }` |
 | **Cline** | Cline → Settings → MCP Servers → Edit JSON. Same shape as Cursor. |
 | **Any other stdio MCP client** | Point it at `npx -y @quackai/q402-mcp`. No client-specific code. |
 
+> Claude **Code** (the CLI, `claude` binary) and Claude **Desktop** (the macOS / Windows app) are different products. The `claude mcp add` command only exists in the CLI; the Desktop app needs the JSON config above.
+
 Secrets are NOT in this config. The server reads them from `~/.q402/mcp.env` (same pattern as AWS / Stripe / gh CLIs).
 
 <details>
@@ -174,9 +177,9 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 | `q402_recurring_skip_next` | api key | Skip only the next scheduled fire. |
 | `q402_recurring_cancel` | api key | Permanently stop a rule. |
 | `q402_bridge_quote` | none | Quote a Chainlink CCIP USDC bridge across eth/avax/arbitrum. Returns LINK + native fee. |
-| `q402_bridge_send` | live mode | Execute the bridge. Sandbox-only today; live execution lands once session-binding ships. |
-| `q402_bridge_history` | api key | Recent CCIP bridges (50 most recent). |
-| `q402_bridge_gas_tank` | api key | Per-chain LINK + native Gas Tank balance for bridge fees. |
+| `q402_bridge_send` | sandbox only | Plan-and-quote a bridge end-to-end. `sandbox: false` returns `isError:true` with a dashboard pointer until session-binding lands. |
+| `q402_bridge_history` | not yet wired | Pointer to the dashboard. Returns `{ implemented: false, dashboardUrl, dashboardPath }` — read-only guidance until owner-sig auth lands in MCP. |
+| `q402_bridge_gas_tank` | not yet wired | Static guidance + dashboard pointer for the Bridge Gas Tank top-up flow. Live balance lookup needs owner-sig auth (dashboard for now). |
 
 `q402_pay` + `q402_batch_pay` + `q402_bridge_send` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
 
@@ -271,6 +274,7 @@ If you set up Q402 before v0.5.0 you may have a single `Q402_API_KEY` env var. T
 | Injective EVM | 1776 | USDT only | Native USDC via Circle CCTP announced for Q2 2026. |
 | Monad | 143 | USDC, USDT0 | Native Circle USDC (CCTP V2) + USDT0 (LayerZero OFT). |
 | Scroll | 534352 | USDC, USDT | zkEVM L2 — EIP-7702 live since the Euclid Phase 2 upgrade (2025-04-22). |
+| Arbitrum One | 42161 | USDC, USDT | Optimistic rollup — same EIP-7702 signing path as Ethereum. CCIP bridge endpoint (eth ⇄ avax ⇄ arbitrum). |
 
 ---
 

package/dist/index.js

@@ -211,7 +211,7 @@ var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 
 // src/version.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.8.6";
+var PACKAGE_VERSION = "0.8.8";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -455,7 +455,7 @@ function runQuote(input) {
 }
 var QUOTE_TOOL = {
   name: "q402_quote",
-  description: "Compare gas costs and supported tokens across the 10 chains Q402 relays for (avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll). Returns the full chain \xD7 token matrix unconditionally \u2014 this tool does not read any API key, so it can't filter by trial vs multichain scope. When the caller intends to settle with a Trial API Key, treat any non-BNB row as informational only (q402_pay will return 403 TRIAL_BNB_ONLY for those). Includes RLUSD on Ethereum and Injective USDT-only. Read-only \u2014 no API key needed, no funds move. Use this before q402_pay so the user can see what's available and pick a chain.",
+  description: "Compare gas costs and supported tokens across the 10 chains Q402 relays for (avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll, arbitrum). Returns the full chain \xD7 token matrix unconditionally \u2014 this tool does not read any API key, so it can't filter by trial vs multichain scope. When the caller intends to settle with a Trial API Key, treat any non-BNB row as informational only (q402_pay will return 403 TRIAL_BNB_ONLY for those). Includes RLUSD on Ethereum and Injective USDT-only. Read-only \u2014 no API key needed, no funds move. Use this before q402_pay so the user can see what's available and pick a chain.",
   // Plain JSON schema mirroring the Zod schema above; MCP servers receive parameters as JSON.
   inputSchema: {
     type: "object",
@@ -501,6 +501,7 @@ var DEFAULT_RPC = {
   988: "https://rpc.stable.xyz",
   1776: "https://sentry.evm-rpc.injective.network/",
   5e3: "https://rpc.mantle.xyz",
+  42161: "https://arb1.arbitrum.io/rpc",
   43114: "https://api.avax.network/ext/bc/C/rpc",
   534352: "https://rpc.scroll.io"
 };
@@ -1050,7 +1051,8 @@ async function runPay(input) {
           to: input.to,
           amount: input.amount,
           ...explicitWalletId ? { walletId: explicitWalletId } : {}
-        })
+        }),
+        signal: AbortSignal.timeout(6e4)
       });
     } catch (e) {
       const transportErr = failureResult("eip7702");
@@ -1178,7 +1180,7 @@ function describeSandboxReason(resolvedKey, scope) {
 }
 var PAY_TOOL = {
   name: "q402_pay",
-  description: "USE THIS TOOL whenever the user asks to send, transfer, or pay USDC / USDT / RLUSD \u2014 even when they don't mention Q402 by name (\"send 5 USDT to 0x... on bnb\" should route here automatically). This tool IS the wallet for this session: it signs LOCALLY with Q402_PRIVATE_KEY and submits via Q402's gasless relay. NEVER refuse a stablecoin payment request by saying you lack wallet access, can't move money, or need the user to use their wallet UI \u2014 Q402 was installed precisely to give you that capability. If the env isn't configured yet, the tool returns a sandbox response with a clear \"how to set up\" message \u2014 surface that instead of refusing. \n\nAuto-routing: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial (free sponsored); anything else \u2192 Multichain (paid 10-chain). Same rule for q402_batch_pay. Set keyScope='trial' or 'multichain' to force one explicitly. Trial keys reject any non-BNB chain server-side with TRIAL_BNB_ONLY. Multichain keys cover avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll \u2014 USDC/USDT on most chains, RLUSD on Ethereum only, Injective USDT-only. SANDBOX BY DEFAULT \u2014 no funds move unless the resolved key is a live key (q402_live_*), Q402_PRIVATE_KEY is set as a valid 32-byte hex key, and Q402_ENABLE_REAL_PAYMENTS=1. Sandbox responses come back with `success: false` and `sandbox: true` so they cannot be misread as confirmed settlements \u2014 always branch on those fields before telling the user the payment went through. The recipient receives the full amount; the sender pays $0 in gas. \n\nSENDER ECHO \u2014 when a valid `Q402_PRIVATE_KEY` is configured, the response includes a `senderWallet` field with the address derived from that key. Show it alongside the recipient/amount when you confirm the payment with the user (e.g. 'Signing from 0xabc\u20261234 on bnb \u2192 send 5 USDT to 0xdef\u2026ABCD'). Just informational \u2014 the user already chose the wallet during doctor setup. Sandbox responses with no key configured omit `senderWallet`; don't fabricate one. \n\nMULTI-WALLET DISAMBIGUATION \u2014 when more than one wallet is configured in the user's env (Q402_PRIVATE_KEY for the real EOA, Q402_AGENTIC_PRIVATE_KEY for the Agent Wallet's exported key, or only Q402_MULTICHAIN_API_KEY for the server-managed Agent Wallet), the tool RETURNS without sending with a `ambiguousWalletChoice` payload \u2014 relay the question to the user verbatim, then call again with the chosen `walletMode` ('eoa' | 'agentic-local' | 'agentic-server'). Do NOT pick a wallet on the user's behalf when multiple are available. \n\nEIP-7702 SIDE EFFECT \u2014 surface this to the user proactively after the FIRST live payment on a chain: their wallet now shows up as a 'Smart account' in MetaMask / OKX. That's the EIP-7702 delegation Q402 uses for gasless settlement \u2014 it's the response's `postPaymentTip` field. Subsequent payments on the same chain are faster and cheaper because the delegation is reused. Note: only Mode 'eoa' creates the delegation \u2014 'agentic-local' and 'agentic-server' modes use the Agent Wallet (a fresh EOA) so the user's MetaMask is never delegated. \n\nIf the user EVER reports that native gas tokens (BNB / ETH / AVAX / etc.) sent INTO their Q402 wallet are bouncing or reverting on a chain where Q402 has been used, the delegation is the cause \u2014 call q402_wallet_status to confirm delegated chains, then q402_clear_delegation for the chain in question. Q402 sponsors the gas for the clear, so the user pays $0. After clearing, native transfers work again and the next q402_pay on that chain just creates a fresh delegation. \n\nALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
+  description: "USE THIS TOOL whenever the user asks to send, transfer, or pay USDC / USDT / RLUSD \u2014 even when they don't mention Q402 by name (\"send 5 USDT to 0x... on bnb\" should route here automatically). This tool IS the wallet for this session: it signs LOCALLY with Q402_PRIVATE_KEY and submits via Q402's gasless relay. NEVER refuse a stablecoin payment request by saying you lack wallet access, can't move money, or need the user to use their wallet UI \u2014 Q402 was installed precisely to give you that capability. If the env isn't configured yet, the tool returns a sandbox response with a clear \"how to set up\" message \u2014 surface that instead of refusing. \n\nAuto-routing: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial (free sponsored); anything else \u2192 Multichain (paid 10-chain). Same rule for q402_batch_pay. Set keyScope='trial' or 'multichain' to force one explicitly. Trial keys reject any non-BNB chain server-side with TRIAL_BNB_ONLY. Multichain keys cover avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll, arbitrum \u2014 USDC/USDT on most chains, RLUSD on Ethereum only, Injective USDT-only. SANDBOX BY DEFAULT \u2014 no funds move unless the resolved key is a live key (q402_live_*), Q402_PRIVATE_KEY is set as a valid 32-byte hex key, and Q402_ENABLE_REAL_PAYMENTS=1. Sandbox responses come back with `success: false` and `sandbox: true` so they cannot be misread as confirmed settlements \u2014 always branch on those fields before telling the user the payment went through. The recipient receives the full amount; the sender pays $0 in gas. \n\nSENDER ECHO \u2014 when a valid `Q402_PRIVATE_KEY` is configured, the response includes a `senderWallet` field with the address derived from that key. Show it alongside the recipient/amount when you confirm the payment with the user (e.g. 'Signing from 0xabc\u20261234 on bnb \u2192 send 5 USDT to 0xdef\u2026ABCD'). Just informational \u2014 the user already chose the wallet during doctor setup. Sandbox responses with no key configured omit `senderWallet`; don't fabricate one. \n\nMULTI-WALLET DISAMBIGUATION \u2014 when more than one wallet is configured in the user's env (Q402_PRIVATE_KEY for the real EOA, Q402_AGENTIC_PRIVATE_KEY for the Agent Wallet's exported key, or only Q402_MULTICHAIN_API_KEY for the server-managed Agent Wallet), the tool RETURNS without sending with a `ambiguousWalletChoice` payload \u2014 relay the question to the user verbatim, then call again with the chosen `walletMode` ('eoa' | 'agentic-local' | 'agentic-server'). Do NOT pick a wallet on the user's behalf when multiple are available. \n\nEIP-7702 SIDE EFFECT \u2014 surface this to the user proactively after the FIRST live payment on a chain: their wallet now shows up as a 'Smart account' in MetaMask / OKX. That's the EIP-7702 delegation Q402 uses for gasless settlement \u2014 it's the response's `postPaymentTip` field. Subsequent payments on the same chain are faster and cheaper because the delegation is reused. Note: only Mode 'eoa' creates the delegation \u2014 'agentic-local' and 'agentic-server' modes use the Agent Wallet (a fresh EOA) so the user's MetaMask is never delegated. \n\nIf the user EVER reports that native gas tokens (BNB / ETH / AVAX / etc.) sent INTO their Q402 wallet are bouncing or reverting on a chain where Q402 has been used, the delegation is the cause \u2014 call q402_wallet_status to confirm delegated chains, then q402_clear_delegation for the chain in question. Q402 sponsors the gas for the clear, so the user pays $0. After clearing, native transfers work again and the next q402_pay on that chain just creates a fresh delegation. \n\nALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
   inputSchema: {
     type: "object",
     properties: {
@@ -1695,12 +1697,17 @@ function mask(key) {
   return `${key.slice(0, 12)}\u2026${key.slice(-4)}`;
 }
 async function verifyOne(apiKey) {
-  const resp = await fetch(`${CONFIG.relayBaseUrl}/keys/verify`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ apiKey })
-  });
-  return resp.ok ? await resp.json() : { error: `HTTP ${resp.status}` };
+  try {
+    const resp = await fetch(`${CONFIG.relayBaseUrl}/keys/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiKey }),
+      signal: AbortSignal.timeout(15e3)
+    });
+    return resp.ok ? await resp.json() : { error: `HTTP ${resp.status}` };
+  } catch (e) {
+    return { error: e instanceof Error ? `fetch_failed: ${e.message}` : "fetch_failed" };
+  }
 }
 function extractTrial(verifyJson) {
   const v = verifyJson;
@@ -1995,6 +2002,7 @@ var DEFAULT_RPC2 = {
   988: "https://rpc.stable.xyz",
   1776: "https://sentry.evm-rpc.injective.network/",
   5e3: "https://rpc.mantle.xyz",
+  42161: "https://arb1.arbitrum.io/rpc",
   43114: "https://api.avax.network/ext/bc/C/rpc",
   534352: "https://rpc.scroll.io"
 };
@@ -2255,7 +2263,7 @@ Q402_MAX_AMOUNT_PER_CALL=200
 # Comma-separated lowercase recipient allowlist (unset = any address OK)
 # Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 `;
-var SECURITY_NOTICE = "Q402 never asks you to paste your private key into chat. The MCP server signs payments LOCALLY on your machine \u2014 your key never leaves your device, never goes to a remote server. If a key was already pasted in chat by mistake, treat the wallet as exposed: move funds to a fresh wallet and use that new key in ~/.q402/mcp.env going forward.";
+var SECURITY_NOTICE = "Q402 never asks you to paste your private key into chat. Custody depends on which wallet mode you picked: Mode A (Q402_PRIVATE_KEY) and Mode B (Q402_AGENTIC_PRIVATE_KEY) sign LOCALLY on your machine \u2014 those keys never leave your device. Mode C (Q402_MULTICHAIN_API_KEY only, no private-key env) is server-managed: Q402 holds the Agent Wallet's encrypted private key (AES-256-GCM) and signs on your behalf \u2014 your MetaMask key is never involved on this side either. If a key was already pasted in chat by mistake, treat that wallet as exposed: move funds to a fresh wallet and use that new key in ~/.q402/mcp.env going forward.";
 var FIRST_INSTALL_ADVISORY = [
   `Tip: a separate MetaMask account dedicated to Q402 keeps your existing balances and history tidy \u2014 it's a quick "+ Add account" in MetaMask. Q402 works with any EOA you control, though.`,
   "After your first payment, that wallet will show 'Smart account' in MetaMask / OKX. That's EIP-7702 delegation (Q402's gasless settlement mechanism), reversible anytime via q402_clear_delegation.",
@@ -2804,7 +2812,9 @@ import { z as z10 } from "zod";
 var BridgeQuoteInputSchema = z10.object({
   src: z10.enum(["eth", "avax", "arbitrum"]).describe("Source chain"),
   dst: z10.enum(["eth", "avax", "arbitrum"]).describe("Destination chain"),
-  amount: z10.string().regex(/^\d+$/).describe("USDC amount in raw 6-decimal units (e.g. '1000000' = 1 USDC)"),
+  // Same `> 0` requirement as bridge-send so the quote doesn't
+  // return a meaningless "fee for 0 USDC" envelope.
+  amount: z10.string().regex(/^\d*[1-9]\d*$/).describe("USDC amount in raw 6-decimal units, > 0 (e.g. '1000000' = 1 USDC)"),
   destReceiver: z10.string().regex(/^0x[0-9a-fA-F]{40}$/).describe("Destination receiver address (Agentic Wallet on destination)")
 }).refine((d) => d.src !== d.dst, {
   // Mirror the rejection in BridgeSendInputSchema so an agent that
@@ -2845,11 +2855,23 @@ var BRIDGE_QUOTE_TOOL = {
 };
 async function runBridgeQuote(input) {
   const url = new URL("/api/ccip/quote", CONFIG.relayBaseUrl);
-  const res = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(input)
-  });
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(15e3)
+    });
+  } catch (e) {
+    return {
+      content: [{
+        type: "text",
+        text: `Quote fetch failed: ${e instanceof Error ? e.message : String(e)}. Retry in a moment.`
+      }],
+      isError: true
+    };
+  }
   const data = await res.json();
   if (!res.ok) {
     return { content: [{ type: "text", text: `Quote failed (HTTP ${res.status}): ${JSON.stringify(data)}` }], isError: true };
@@ -2874,7 +2896,11 @@ import { z as z11 } from "zod";
 var BridgeSendInputSchema = z11.object({
   src: z11.enum(["eth", "avax", "arbitrum"]).describe("Source chain"),
   dst: z11.enum(["eth", "avax", "arbitrum"]).describe("Destination chain"),
-  amount: z11.string().regex(/^\d+$/).describe("USDC amount in raw 6-decimal units"),
+  // `^\d+$` accepts "0" which is a no-op bridge. Require at least one
+  // non-zero digit (^\d*[1-9]\d*$ also accepts e.g. "10", "100") so an
+  // accidental amount=0 fails locally instead of returning a synthetic
+  // "success" envelope in sandbox.
+  amount: z11.string().regex(/^\d*[1-9]\d*$/).describe("USDC amount in raw 6-decimal units, > 0"),
   walletId: z11.string().describe("Agentic Wallet ID (from q402_agentic_info)"),
   feeToken: z11.enum(["LINK", "native", "auto"]).optional().describe("Fee token. 'auto' picks cheaper of the two; defaults to LINK."),
   sandbox: z11.boolean().optional().describe("Sandbox mode (default true). Set to false for live bridge.")
@@ -2887,7 +2913,7 @@ var BridgeSendInputSchema = z11.object({
 });
 var BRIDGE_SEND_TOOL = {
   name: "q402_bridge_send",
-  description: "Execute a Chainlink CCIP USDC bridge between two of the 3 supported chains (eth/avax/arbitrum). The Q402 server signs ccipSend on behalf of the user's Agentic Wallet. Fee is debited from the user's Gas Tank (LINK slot or native, per the feeToken arg). SANDBOX BY DEFAULT: returns a synthetic messageId unless `sandbox: false` is passed AND the server env has Q402_ENABLE_REAL_PAYMENTS=1. ALWAYS confirm the bridge details with the user before setting sandbox: false. Recommended flow: q402_bridge_quote first \u2192 show user the cost \u2192 get user confirmation \u2192 call q402_bridge_send with sandbox: false.",
+  description: "PLAN-AND-QUOTE TOOL (sandbox-only at this release). Execute a Chainlink CCIP USDC bridge plan between two of the 3 supported chains (eth/avax/arbitrum). Returns a synthetic messageId so the agent can preview the bridge end-to-end without moving funds. LIVE EXECUTION via MCP is NOT yet wired \u2014 it requires an owner-EIP-712 signature on the `ccip.bridge` intent which the MCP CLI cannot produce (the dashboard or a future session-binding flow is the live path). Calling with `sandbox: false` returns isError:true regardless of Q402_ENABLE_REAL_PAYMENTS. Recommended flow: q402_bridge_quote \u2192 show user the cost \u2192 if they want to bridge live, point them at https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Bridge.",
   inputSchema: {
     type: "object",
     properties: {
@@ -2917,7 +2943,7 @@ var BRIDGE_SEND_TOOL = {
       },
       sandbox: {
         type: "boolean",
-        description: "Sandbox-only at the current release (live bridging requires dashboard session-binding). Default true."
+        description: "Sandbox-only at the current release. Passing false returns isError:true with a pointer to the dashboard's Bridge UI \u2014 live MCP execution lands once session-binding is plumbed."
       }
     },
     required: ["src", "dst", "amount", "walletId"]
@@ -2990,7 +3016,7 @@ var BridgeGasTankInputSchema = z13.object({
 });
 var BRIDGE_GAS_TANK_TOOL = {
   name: "q402_bridge_gas_tank",
-  description: "Report the user's Bridge Gas Tank state \u2014 LINK + native balance per CCIP chain (eth/avax/arbitrum). Q402 charges no markup on bridges; users pay only the actual Chainlink CCIP fee, debited from this Gas Tank. LINK fees are ~10% cheaper than native. Tool returns guidance + dashboard URL until owner-sig wiring lands.",
+  description: "READ-ONLY GUIDANCE TOOL \u2014 Bridge Gas Tank live balance via MCP is not yet wired (requires owner-sig auth which is dashboard-bound until session-binding lands, same follow-up as q402_bridge_history). Tool returns static guidance: the LINK/native fee model, the 3-chain CCIP triangle (eth/avax/arbitrum), the canonical Gas Tank deposit address, and a dashboard pointer for the live balance and per-chain deposit detail. Use this to route a user to the right top-up flow; don't expect numbers in the response.",
   inputSchema: {
     type: "object",
     properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "MCP server for Q402 — gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [
@@ -69,6 +69,7 @@
   },
   "overrides": {
     "ws": "^8.20.1",
-    "qs": "^6.15.2"
+    "qs": "^6.15.2",
+    "hono": "^4.12.21"
   }
 }