@quackai/q402-mcp 0.8.1 → 0.8.3

package/README.md

@@ -153,7 +153,7 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 ## Tools exposed
 
-**16 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
+**20 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
 
 | Tool | Auth | Purpose |
 |---|---|---|
@@ -173,8 +173,12 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 | `q402_recurring_resume` | api key | Resume a paused / stopped rule. |
 | `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. v0.8.2 ships sandbox-only; 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_pay` + `q402_batch_pay` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
+`q402_pay` + `q402_batch_pay` + `q402_bridge_send` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
 
 > ℹ️ `q402_pay` expects a 0x address — ENS isn't resolved server-side. Resolve client-side first.
 > Per-chain Gas Tank balances + full TX history live in the [dashboard](https://q402.quackai.ai/dashboard) (wallet-signature only).

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.1";
+var PACKAGE_VERSION = "0.8.3";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -2799,10 +2799,216 @@ async function runAgenticInfo(input = {}) {
   };
 }
 
-// src/tools/recurring-list.ts
+// src/tools/bridge-quote.ts
 import { z as z10 } from "zod";
-var RecurringListInputSchema = z10.object({
-  walletId: z10.string().optional().describe(
+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)"),
+  destReceiver: z10.string().regex(/^0x[0-9a-fA-F]{40}$/).describe("Destination receiver address (Agentic Wallet on destination)")
+});
+var BRIDGE_QUOTE_TOOL = {
+  name: "q402_bridge_quote",
+  description: "Quote the Chainlink CCIP fee for bridging USDC across the 3-chain triangle (eth/avax/arbitrum). Returns BOTH the LINK fee (~10% cheaper) and the native fee, so the agent can pick the cheaper path or surface both options to the user. Read-only; no auth required.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      src: {
+        type: "string",
+        enum: ["eth", "avax", "arbitrum"],
+        description: "Source chain."
+      },
+      dst: {
+        type: "string",
+        enum: ["eth", "avax", "arbitrum"],
+        description: "Destination chain (MUST differ from src; pool only routes inside the 3-chain triangle)."
+      },
+      amount: {
+        type: "string",
+        pattern: "^[0-9]+$",
+        description: "USDC amount in raw 6-decimal units (e.g. '1000000' = 1 USDC). Integer string only."
+      },
+      destReceiver: {
+        type: "string",
+        pattern: "^0x[0-9a-fA-F]{40}$",
+        description: "Destination receiver (0x 20-byte address). Same EOA on the destination chain."
+      }
+    },
+    required: ["src", "dst", "amount", "destReceiver"]
+  }
+};
+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)
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    return { content: [{ type: "text", text: `Quote failed (HTTP ${res.status}): ${JSON.stringify(data)}` }], isError: true };
+  }
+  const recommended = data.recommended;
+  const link = data.fee?.link;
+  const native = data.fee?.native;
+  const otherKey = recommended === "link" ? "native" : "link";
+  const recUsd = recommended ? data.fee?.[recommended]?.usd : void 0;
+  const otherUsd = recommended ? data.fee?.[otherKey]?.usd : void 0;
+  const cheaper = recommended && typeof recUsd === "number" ? `Cheaper: ${recommended.toUpperCase()} (~$${recUsd.toFixed(4)} vs $${(otherUsd ?? 0).toFixed(4)})` : "Quote returned.";
+  return {
+    content: [
+      { type: "text", text: cheaper },
+      { type: "text", text: JSON.stringify({ recommended, link, native }, null, 2) }
+    ]
+  };
+}
+
+// src/tools/bridge-send.ts
+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"),
+  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.")
+});
+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.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      src: {
+        type: "string",
+        enum: ["eth", "avax", "arbitrum"],
+        description: "Source chain."
+      },
+      dst: {
+        type: "string",
+        enum: ["eth", "avax", "arbitrum"],
+        description: "Destination chain (MUST differ from src)."
+      },
+      amount: {
+        type: "string",
+        pattern: "^[0-9]+$",
+        description: "USDC amount in raw 6-decimal units (e.g. '1000000' = 1 USDC). Integer string only."
+      },
+      walletId: {
+        type: "string",
+        description: "Agentic Wallet ID (from q402_agentic_info)."
+      },
+      feeToken: {
+        type: "string",
+        enum: ["LINK", "native", "auto"],
+        description: "Fee token. Default: LINK (~10% cheaper). 'auto' picks cheaper at quote time."
+      },
+      sandbox: {
+        type: "boolean",
+        description: "Sandbox-only in v0.8.3 (live bridging requires dashboard session-binding). Default true."
+      }
+    },
+    required: ["src", "dst", "amount", "walletId"]
+  }
+};
+async function runBridgeSend(input) {
+  const sandbox = input.sandbox !== false;
+  if (sandbox) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          sandbox: true,
+          messageId: "0x" + "00".repeat(32),
+          txHash: "0x" + "00".repeat(32),
+          note: "Sandbox response. To execute a real bridge, pass `sandbox: false` AND ensure the server has Q402_ENABLE_REAL_PAYMENTS=1.",
+          src: input.src,
+          dst: input.dst,
+          amount: input.amount
+        }, null, 2)
+      }]
+    };
+  }
+  return {
+    content: [{
+      type: "text",
+      text: "Live CCIP bridge via MCP is not yet wired in v0.8.2 \u2014 agents can quote and plan via q402_bridge_quote and q402_bridge_send (sandbox), but actual execution must happen via https://q402.quackai.ai/dashboard for now. Live MCP execution lands in a follow-up release."
+    }],
+    isError: true
+  };
+}
+
+// src/tools/bridge-history.ts
+import { z as z12 } from "zod";
+var BridgeHistoryInputSchema = z12.object({
+  ownerAddress: z12.string().regex(/^0x[0-9a-fA-F]{40}$/).optional().describe("Owner EOA. Defaults to the configured Agentic Wallet owner.")
+});
+var BRIDGE_HISTORY_TOOL = {
+  name: "q402_bridge_history",
+  description: "List the user's recent Chainlink CCIP bridges (most-recent first, up to 50 records). Each record includes messageId, source/destination chains, USDC amount, fee paid, and CCIP Explorer link. v0.8.2 returns dashboard URL guidance \u2014 full MCP wiring lands in a follow-up.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ownerAddress: {
+        type: "string",
+        pattern: "^0x[0-9a-fA-F]{40}$",
+        description: "Owner EOA (0x address, optional \u2014 defaults to configured wallet)."
+      }
+    }
+  }
+};
+async function runBridgeHistory(_input) {
+  return {
+    content: [{
+      type: "text",
+      text: "Bridge history via MCP requires owner-sig auth, which is dashboard-managed in v0.8.3. View at https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Bridge History."
+    }],
+    isError: true
+  };
+}
+
+// src/tools/bridge-gas-tank.ts
+import { z as z13 } from "zod";
+var BridgeGasTankInputSchema = z13.object({
+  ownerAddress: z13.string().regex(/^0x[0-9a-fA-F]{40}$/).optional().describe("Owner EOA. Defaults to configured wallet.")
+});
+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 in v0.8.3.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ownerAddress: {
+        type: "string",
+        pattern: "^0x[0-9a-fA-F]{40}$",
+        description: "Owner EOA (0x address, optional \u2014 defaults to configured wallet)."
+      }
+    }
+  }
+};
+async function runBridgeGasTank(_input) {
+  return {
+    content: [{
+      type: "text",
+      text: [
+        "Bridge Gas Tank covers Chainlink CCIP fees on the 3-chain triangle (eth/avax/arbitrum).",
+        "",
+        "Two fee tokens supported:",
+        "  \u2022 LINK (default, ~10% cheaper)",
+        "  \u2022 native (ETH / AVAX / ETH respectively)",
+        "",
+        "Top up by sending LINK or native to the Q402 facilitator address on the source chain. The next deposit-scan cron tick (~5 min) credits your Gas Tank.",
+        "",
+        "Live balance + deposit addresses: https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Bridge Gas Tank"
+      ].join("\n")
+    }]
+  };
+}
+
+// src/tools/recurring-list.ts
+import { z as z14 } from "zod";
+var RecurringListInputSchema = z14.object({
+  walletId: z14.string().optional().describe(
     "Optional lowercased Agent Wallet address to list rules for when the user holds multiple wallets. Omit to use Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -2886,29 +3092,29 @@ async function runRecurringList(input = {}) {
 }
 
 // src/tools/recurring-create.ts
-import { z as z11 } from "zod";
+import { z as z15 } from "zod";
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 var AMOUNT_RE = /^\d+(\.\d{1,18})?$/;
-var RecurringCreateInputSchema = z11.object({
-  confirm: z11.literal(true).describe(
+var RecurringCreateInputSchema = z15.object({
+  confirm: z15.literal(true).describe(
     'REQUIRED. Must be literally `true`. Authoring a recurring rule schedules future on-chain payments that the user does not click through one-by-one \u2014 the user has to explicitly say yes BEFORE this is called. Echo back the frequency + recipient + amount + chain + token + cancelWindow you intend to create, get a plain-language confirmation from the user (e.g. "yes, create the schedule"), and ONLY then call this with confirm: true. Mirrors the same guard q402_pay / q402_batch_pay use on one-shot sends.'
   ),
-  frequency: z11.string().min(1).describe(
+  frequency: z15.string().min(1).describe(
     'Cadence string. One of: "hourly:N" (N=1..23), "daily", "weekly:{mon|tue|wed|thu|fri|sat|sun}", "monthly:N" (N=1..31), "monthly:last". Examples: "hourly:1" fires every hour, "weekly:fri" fires every Friday, "monthly:1" fires on the 1st of each month.'
   ),
-  recipient: z11.string().regex(ADDRESS_RE).describe("0x-prefixed 20-byte recipient address. Required."),
-  amount: z11.string().regex(AMOUNT_RE).describe(
+  recipient: z15.string().regex(ADDRESS_RE).describe("0x-prefixed 20-byte recipient address. Required."),
+  amount: z15.string().regex(AMOUNT_RE).describe(
     'Amount per fire, as a decimal string (e.g. "1.5", "0.0001"). Counted in the same unit as `token` (USDC or USDT, both 1:1 USD).'
   ),
-  chain: z11.enum(["bnb", "eth", "avax", "xlayer", "mantle", "injective", "monad", "scroll", "stable", "arbitrum"]).default("bnb").describe(
+  chain: z15.enum(["bnb", "eth", "avax", "xlayer", "mantle", "injective", "monad", "scroll", "stable", "arbitrum"]).default("bnb").describe(
     "Chain to fire the recurring TX on. Defaults to bnb. Recurring requires the paid Multichain subscription on EVERY chain, including bnb \u2014 Trial keys are rejected at create time with MULTICHAIN_REQUIRED. Trial keys can still pay one-shot via q402_pay on BNB."
   ),
-  token: z11.enum(["USDC", "USDT"]).default("USDT").describe("Stablecoin to send. USDC or USDT. Both peg to USD-1."),
-  label: z11.string().max(64).optional().describe("Optional human-readable label (\u226464 chars). Shows up in q402_recurring_list and the dashboard."),
-  cancelWindowHours: z11.number().min(0).optional().describe(
+  token: z15.enum(["USDC", "USDT"]).default("USDT").describe("Stablecoin to send. USDC or USDT. Both peg to USD-1."),
+  label: z15.string().max(64).optional().describe("Optional human-readable label (\u226464 chars). Shows up in q402_recurring_list and the dashboard."),
+  cancelWindowHours: z15.number().min(0).optional().describe(
     "Hours of advance notice before each fire during which the rule can be cancelled. 0 = fire immediately at the next slot, no alert. Capped at the cadence interval (e.g. \u2264 N-0.5h for hourly:N, \u226424 for daily). Defaults to 0."
   ),
-  walletId: z11.string().optional().describe(
+  walletId: z15.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet on the server."
   )
 });
@@ -3037,12 +3243,12 @@ async function runRecurringCreate(input) {
 }
 
 // src/tools/recurring-cancel.ts
-import { z as z12 } from "zod";
-var RecurringCancelInputSchema = z12.object({
-  ruleId: z12.string().min(1).describe(
+import { z as z16 } from "zod";
+var RecurringCancelInputSchema = z16.object({
+  ruleId: z16.string().min(1).describe(
     "Rule id to cancel. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field. Cancelling is immediate."
   ),
-  walletId: z12.string().optional().describe(
+  walletId: z16.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3130,15 +3336,15 @@ async function runRecurringCancel(input) {
 }
 
 // src/tools/recurring-fires.ts
-import { z as z13 } from "zod";
-var RecurringFiresInputSchema = z13.object({
-  ruleId: z13.string().min(1).describe(
+import { z as z17 } from "zod";
+var RecurringFiresInputSchema = z17.object({
+  ruleId: z17.string().min(1).describe(
     "Rule id whose fire history to fetch. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field."
   ),
-  limit: z13.number().int().min(1).max(50).optional().describe(
+  limit: z17.number().int().min(1).max(50).optional().describe(
     "Max number of fires to return (newest first). Defaults to 50 (the server cap). Pass a smaller number when you only need the most recent few."
   ),
-  walletId: z13.string().optional().describe(
+  walletId: z17.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3244,12 +3450,12 @@ async function runRecurringFires(input) {
 }
 
 // src/tools/recurring-pause.ts
-import { z as z14 } from "zod";
-var RecurringPauseInputSchema = z14.object({
-  ruleId: z14.string().min(1).describe(
+import { z as z18 } from "zod";
+var RecurringPauseInputSchema = z18.object({
+  ruleId: z18.string().min(1).describe(
     "Rule id to pause. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field. Pausing is immediate and reversible."
   ),
-  walletId: z14.string().optional().describe(
+  walletId: z18.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3337,12 +3543,12 @@ async function runRecurringPause(input) {
 }
 
 // src/tools/recurring-resume.ts
-import { z as z15 } from "zod";
-var RecurringResumeInputSchema = z15.object({
-  ruleId: z15.string().min(1).describe(
+import { z as z19 } from "zod";
+var RecurringResumeInputSchema = z19.object({
+  ruleId: z19.string().min(1).describe(
     "Rule id to resume. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field. Resume is immediate; nextRunAt advances to the next valid slot."
   ),
-  walletId: z15.string().optional().describe(
+  walletId: z19.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3430,12 +3636,12 @@ async function runRecurringResume(input) {
 }
 
 // src/tools/recurring-skip-next.ts
-import { z as z16 } from "zod";
-var RecurringSkipNextInputSchema = z16.object({
-  ruleId: z16.string().min(1).describe(
+import { z as z20 } from "zod";
+var RecurringSkipNextInputSchema = z20.object({
+  ruleId: z20.string().min(1).describe(
     "Rule id whose next scheduled fire to skip. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field."
   ),
-  walletId: z16.string().optional().describe(
+  walletId: z20.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3550,7 +3756,14 @@ async function main() {
       RECURRING_RESUME_TOOL,
       RECURRING_SKIP_NEXT_TOOL,
       RECURRING_CANCEL_TOOL,
-      CLEAR_DELEGATION_TOOL
+      CLEAR_DELEGATION_TOOL,
+      // CCIP bridge surface (v0.8.2) — USDC routing on the eth/avax/arbitrum
+      // triangle. Bridge_send is sandbox-only in v0.8.2; live execution
+      // happens through the dashboard until session-binding ships.
+      BRIDGE_QUOTE_TOOL,
+      BRIDGE_SEND_TOOL,
+      BRIDGE_HISTORY_TOOL,
+      BRIDGE_GAS_TANK_TOOL
     ]
   }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -3621,6 +3834,22 @@ async function main() {
           const parsed = RecurringSkipNextInputSchema.parse(args ?? {});
           return { content: [jsonText(await runRecurringSkipNext(parsed))] };
         }
+        case "q402_bridge_quote": {
+          const parsed = BridgeQuoteInputSchema.parse(args ?? {});
+          return await runBridgeQuote(parsed);
+        }
+        case "q402_bridge_send": {
+          const parsed = BridgeSendInputSchema.parse(args ?? {});
+          return await runBridgeSend(parsed);
+        }
+        case "q402_bridge_history": {
+          const parsed = BridgeHistoryInputSchema.parse(args ?? {});
+          return await runBridgeHistory(parsed);
+        }
+        case "q402_bridge_gas_tank": {
+          const parsed = BridgeGasTankInputSchema.parse(args ?? {});
+          return await runBridgeGasTank(parsed);
+        }
         default:
           return {
             isError: true,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.8.1",
-  "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 10 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
+  "version": "0.8.3",
+  "description": "MCP server for Q402 — gasless USDC/USDT/RLUSD payments + Chainlink CCIP bridge across 10 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [
     "mcp",