@quackai/q402-mcp 0.6.3 → 0.6.5

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.3";
+var PACKAGE_VERSION = "0.6.5";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -2869,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) };
@@ -2892,6 +2994,7 @@ async function main() {
       AGENTIC_INFO_TOOL,
       RECURRING_LIST_TOOL,
       RECURRING_CREATE_TOOL,
+      RECURRING_FIRES_TOOL,
       RECURRING_CANCEL_TOOL,
       CLEAR_DELEGATION_TOOL
     ]
@@ -2948,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.3",
+  "version": "0.6.5",
   "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": [