@quackai/q402-mcp 0.6.2 → 0.6.4

package/README.md

@@ -157,6 +157,20 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 ---
 
+## Wallet modes — which signing path?
+
+Three signing paths. Pick one when `q402_doctor` asks on first install. You can change later by editing `~/.q402/mcp.env` and restarting your client.
+
+| Mode | Best for | Env to set | Private key in env? |
+|---|---|---|---|
+| **C — Server-managed** (recommended) | Most users. AI agents, automations, anyone who wants payments to "just work". Q402 holds an encrypted Agent Wallet for you; no MetaMask popup, no Smart-account marker. | `Q402_MULTICHAIN_API_KEY` (paid) **or** `Q402_TRIAL_API_KEY` (free BNB) | **No** |
+| **B — Local Agent Wallet PK** | You want Agent Wallet automation but prefer to hold the PK yourself. Export from the dashboard once. MCP signs locally — key never leaves your machine. Your MetaMask is never touched. | `Q402_AGENTIC_PRIVATE_KEY` + an API key | Yes (Agent Wallet's exported PK) |
+| **A — Your own EOA** | Power users who want their existing MetaMask address to be the on-chain payer. Your EOA signs directly via EIP-7702; the "Smart account" marker after first use is normal + reversible with `q402_clear_delegation`. **Use a fresh wallet.** | `Q402_PRIVATE_KEY` + an API key | Yes (your EOA's PK) |
+
+`q402_doctor` on first install reads your env and recommends one of these based on what's already configured. The default for an empty install is Mode C — simplest path. If multiple modes are configured at once (e.g. both `Q402_PRIVATE_KEY` and `Q402_AGENTIC_PRIVATE_KEY` set), `q402_pay` will ask which one to use before sending so the agent never silently picks the wrong wallet.
+
+---
+
 ## Tools exposed
 
 | Tool | Auth | Purpose |

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.6.2";
+var PACKAGE_VERSION = "0.6.4";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -2049,7 +2049,7 @@ function envSlot(name, purpose) {
 }
 function mask2(key) {
   if (!key || key.length < 12) return key ?? "";
-  return `${key.slice(0, 12)}\u2026${key.slice(-4)}`;
+  return `${key.slice(0, 12)}...${key.slice(-4)}`;
 }
 function detectPhase() {
   const anyKey = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
@@ -2435,10 +2435,10 @@ async function runDoctor() {
     nextStep: ready ? "Show userInstructions verbatim. Then offer to make a small test quote (q402_quote) to confirm everything works end-to-end." : "Walk the user through each warning in order. Show userInstructions verbatim for the cleanup steps.",
     agentInstructions: ready ? "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] Live mode is fully configured. Summarize the wallet address (mask middle), plan tier(s), remaining quota, and any non-zero delegation counts to the user as a checklist. Offer a tiny test (q402_quote, not q402_pay) to confirm. Don't echo the full keys array verbatim \u2014 pick the most useful 2-3 fields per scope." : "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] Walk the user through each warning IN ORDER, plain language. For slot-mismatch warnings, the fix is editing ~/.q402/mcp.env and restarting the client (Cursor / Cline: reload window; Claude / Codex: quit + relaunch). Surface body.error strings from any verify failure as the user-visible reason (e.g. 'your Trial expired 3 days ago', 'API key has been rotated') \u2014 don't generic-out to 'check the key value'.",
     userInstructions: ready ? [
-      `Your wallet: ${walletAddress ? walletAddress.slice(0, 6) + "\u2026" + walletAddress.slice(-4) : "(derive failed \u2014 check Q402_PRIVATE_KEY)"}`,
+      walletAddress ? `Your wallet: ${walletAddress.slice(0, 6)}...${walletAddress.slice(-4)}` : modes.modeC && !modes.modeA && !modes.modeB ? "Wallet: server-managed (Mode C) \u2014 Q402 holds your Agent Wallet key. No local wallet to show." : "(wallet derive failed \u2014 check Q402_PRIVATE_KEY or Q402_AGENTIC_PRIVATE_KEY in ~/.q402/mcp.env)",
       "Q402 is live. You can now ask me to quote, pay, batch-pay, or check Trust Receipts.",
       "Want me to run a quick gas comparison across all 9 chains as a smoke test?",
-      "Need to chain-test against sandbox without changing keys? Set Q402_ENABLE_REAL_PAYMENTS=0 in ~/.q402/mcp.env and restart \u2014 every q402_pay returns a fake hash until you flip it back to 1."
+      "Need to chain-test against sandbox without changing keys? Set Q402_ENABLE_REAL_PAYMENTS=0 in ~/.q402/mcp.env and restart - every q402_pay returns a fake hash until you flip it back to 1."
     ] : [
       `Q402 has ${warnings.length} issue${warnings.length === 1 ? "" : "s"} to fix:`,
       ...warnings.map((w) => `\u2022 ${w}`),
@@ -2650,6 +2650,9 @@ import { z as z11 } 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(
+    '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(
     '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.'
   ),
@@ -2675,6 +2678,11 @@ var RECURRING_CREATE_TOOL = {
   inputSchema: {
     type: "object",
     properties: {
+      confirm: {
+        type: "boolean",
+        const: true,
+        description: "REQUIRED. Must be literally `true`. Recurring rules schedule future on-chain payments without per-fire user prompts, so the agent must get an explicit user yes BEFORE setting `confirm: true` and calling this. Same guard q402_pay / q402_batch_pay use on one-shot sends."
+      },
       frequency: {
         type: "string",
         description: 'Required. "hourly:N" (N=1..23), "daily", "weekly:{day}", "monthly:N", or "monthly:last".'
@@ -2714,7 +2722,7 @@ var RECURRING_CREATE_TOOL = {
         description: "Optional. Defaults to default wallet on server."
       }
     },
-    required: ["frequency", "recipient", "amount"],
+    required: ["confirm", "frequency", "recipient", "amount"],
     additionalProperties: false
   }
 };
@@ -2861,6 +2869,108 @@ 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(
+    "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(
+    "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(
+    "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
+  )
+});
+var RECURRING_FIRES_TOOL = {
+  name: "q402_recurring_fires",
+  description: "Read the past-fire history of a specific recurring-payment rule. Returns up to 50 entries (newest first), each with the timestamp, scheduled slot, total USD amount that settled, on-chain tx hashes, and a partial-failure flag if some recipient rows didn't make it. Use this when the user asks 'when was the last fire?', 'did Friday's payout go out?', 'how much has rule X spent?', or before claiming a fire is missing. Authenticated by the configured Multichain API key. Read-only \u2014 does not trigger or modify anything. Call q402_recurring_list first to find the ruleId.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ruleId: {
+        type: "string",
+        description: "Rule id from q402_recurring_list. Required."
+      },
+      limit: {
+        type: "number",
+        description: "Max number of fires to return (1-50, newest first). Defaults to 50."
+      },
+      walletId: {
+        type: "string",
+        description: "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."
+      }
+    },
+    required: ["ruleId"],
+    additionalProperties: false
+  }
+};
+async function runRecurringFires(input) {
+  const base = CONFIG.relayBaseUrl;
+  const dashboardUrl = base.replace(/\/api$/, "") + "/dashboard?tab=agent";
+  if (!CONFIG.apiKey || !CONFIG.apiKey.startsWith("q402_live_")) {
+    return {
+      configured: false,
+      walletId: null,
+      ruleId: input.ruleId,
+      rule: null,
+      fires: [],
+      count: 0,
+      dashboardUrl,
+      setupHint: "No live Q402 API key configured. Run q402_doctor to set one up, or open the dashboard to view fire history from the UI."
+    };
+  }
+  const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  try {
+    const res = await fetch(`${base}/wallet/agentic/recurring-by-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        action: "fires",
+        ruleId: input.ruleId,
+        ...typeof input.limit === "number" ? { limit: input.limit } : {},
+        ...explicitWalletId ? { walletId: explicitWalletId } : {}
+      })
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      return {
+        configured: true,
+        walletId: explicitWalletId,
+        ruleId: input.ruleId,
+        rule: null,
+        fires: [],
+        count: 0,
+        dashboardUrl,
+        error: data.error ?? `HTTP_${res.status}`,
+        message: data.message ?? `Fires fetch failed with HTTP ${res.status}.`
+      };
+    }
+    return {
+      configured: true,
+      walletId: data.walletId ?? explicitWalletId,
+      ruleId: data.ruleId ?? input.ruleId,
+      rule: data.rule ?? null,
+      fires: Array.isArray(data.fires) ? data.fires : [],
+      count: typeof data.count === "number" ? data.count : data.fires?.length ?? 0,
+      dashboardUrl
+    };
+  } catch (e) {
+    return {
+      configured: true,
+      walletId: explicitWalletId,
+      ruleId: input.ruleId,
+      rule: null,
+      fires: [],
+      count: 0,
+      dashboardUrl,
+      error: "NETWORK_ERROR",
+      message: e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+
 // src/index.ts
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
@@ -2884,6 +2994,7 @@ async function main() {
       AGENTIC_INFO_TOOL,
       RECURRING_LIST_TOOL,
       RECURRING_CREATE_TOOL,
+      RECURRING_FIRES_TOOL,
       RECURRING_CANCEL_TOOL,
       CLEAR_DELEGATION_TOOL
     ]
@@ -2940,6 +3051,10 @@ async function main() {
           const parsed = RecurringCancelInputSchema.parse(args ?? {});
           return { content: [jsonText(await runRecurringCancel(parsed))] };
         }
+        case "q402_recurring_fires": {
+          const parsed = RecurringFiresInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRecurringFires(parsed))] };
+        }
         default:
           return {
             isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 9 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [
@@ -68,6 +68,7 @@
     "access": "public"
   },
   "overrides": {
-    "ws": "^8.20.1"
+    "ws": "^8.20.1",
+    "qs": "^6.15.2"
   }
 }