@quackai/q402-mcp 0.5.5 → 0.5.7

package/README.md

@@ -15,95 +15,89 @@ AI agents — Claude (Desktop / Code), OpenAI Codex CLI, Cursor, Cline, and any
 
 ## Quick start
 
-The server speaks stdio MCP, so any MCP-compatible client can use it. The two paths verified end-to-end today are **Claude (Desktop / Code)** and **OpenAI Codex CLI**.
+Two steps:
 
-### Claude Desktop / Claude Code
+1. Register the MCP server with your client (one-line install per client).
+2. Open your client and say: **"Set up Q402"**. The agent calls `q402_doctor` which walks you through creating a single secrets file at `~/.q402/mcp.env` and pasting in your API key + private key. Nothing else.
 
-```bash
-claude mcp add q402 -- npx -y @quackai/q402-mcp
-```
+### 1. Register the server
 
-Or edit `claude_desktop_config.json` directly:
-
-```json
-{
-  "mcpServers": {
-    "q402": {
-      "command": "npx",
-      "args": ["-y", "@quackai/q402-mcp"]
-    }
-  }
-}
-```
+| Client | Command / config |
+|---|---|
+| **Claude Desktop / Claude Code** | `claude mcp add q402 -- npx -y @quackai/q402-mcp` |
+| **OpenAI Codex CLI** | `codex mcp add q402 -- npx -y @quackai/q402-mcp` |
+| **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. |
 
-Restart Claude Desktop and ask:
+That's it — secrets are NOT configured here. The MCP server reads them from `~/.q402/mcp.env` at startup (same pattern as AWS CLI / Stripe CLI / gh CLI), so every client uses the same file with no per-client wiring.
 
-> *"Compare gas costs to send 50 USDC to vitalik.eth across all 9 Q402 chains."*
+### 2. First-time setup
 
-### OpenAI Codex CLI
+Restart your client, then ask your agent:
 
-Three install paths — pick the one that matches your workflow.
+> *"Set up Q402"*
 
-**(a) Codex plugin marketplace** (recommended — bundles the MCP config so users don't write TOML):
+The agent calls `q402_doctor`. On first install, the tool tells the agent to:
 
-```bash
-codex plugin marketplace add bitgett/q402-mcp
-codex /plugins        # browse and install "q402"
-```
+1. Offer to create `~/.q402/mcp.env` (placeholder values only)
+2. Open the file in your editor (`code` / `open` / `start` / `xdg-open`)
+3. Walk you through pasting in (a) your API key from <https://q402.quackai.ai/event> (free Trial) or <https://q402.quackai.ai/payment> (paid Multichain), and (b) your wallet private key — **into the file, not into chat**
+4. Restart the client and run `q402_doctor` again to verify
+
+🔒 **Q402 never asks you to paste your private key into chat.** The MCP server signs payments LOCALLY on your machine — your key never leaves your device.
 
-This repo carries a Codex plugin manifest at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and a marketplace catalog at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), so any signed-in Codex user can register it as a marketplace source and install with one click.
+### Manual setup (no AI)
 
-**(b) Single MCP server via `codex mcp add`** (no plugin wrapper — just register the stdio server):
+Create `~/.q402/mcp.env` yourself:
 
 ```bash
-codex mcp add q402 -- npx -y @quackai/q402-mcp
+# ~/.q402/mcp.env
+# Pick ONE of these:
+Q402_TRIAL_API_KEY=q402_live_...
+# Q402_MULTICHAIN_API_KEY=q402_live_...
+
+Q402_PRIVATE_KEY=0x...
+Q402_ENABLE_REAL_PAYMENTS=1
+Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
+
+# Optional safety guards:
+# Q402_MAX_AMOUNT_PER_CALL=5
+# Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 ```
 
-**(c) Direct `~/.codex/config.toml` edit** (`.codex/config.toml` for per-project scope):
+Then `chmod 600 ~/.q402/mcp.env` (Unix) and restart your client. That's the full configuration.
 
-```toml
-[mcp_servers.q402]
-command = "npx"
-args = ["-y", "@quackai/q402-mcp"]
-startup_timeout_sec = 20.0
-```
+### Advanced — explicit env injection
+
+If you'd rather skip the file and inject env vars yourself (e.g. via Codex `env_vars` allow-list, a secrets manager, or shell exports), the server falls through to `process.env` — and `process.env` wins over file values on conflicts. So existing shell-export setups keep working unchanged.
 
-To enable real on-chain payments, pass the three live-mode env vars **explicitly** under `env` — Codex does **not** forward host env vars by default:
+<details>
+<summary>Codex <code>env_vars</code> allow-list example</summary>
 
 ```toml
 [mcp_servers.q402]
 command = "npx"
 args = ["-y", "@quackai/q402-mcp"]
 startup_timeout_sec = 20.0
-env = {
-  # Two-key model: set whichever applies — both is best.
-  # Auto-routing rule (same for q402_pay AND q402_batch_pay):
-  #   chain="bnb" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
-  #   anything else                          → Multichain (paid 9-chain)
-  # Batch ambiguity: when auto would land on Trial AND recipients.length > 5,
-  # q402_batch_pay returns status="ambiguous" WITHOUT executing so the agent
-  # can ask the user — pass keyScope="trial" (first 5), "multichain" (all
-  # paid), or call twice (5 free + remainder paid).
-  # Both keys use the same q402_live_ prefix — the env var name is what
-  # carries the scope, not the key string. Get the values from the
-  # dashboard (each key has its own copy button per view).
-  Q402_TRIAL_API_KEY        = "q402_live_...",         # BNB-only sponsored (from /event)
-  Q402_MULTICHAIN_API_KEY   = "q402_live_...",         # paid 9-chain (from /payment)
-  # Legacy fallback — used if neither scoped key above is set.
-  Q402_API_KEY              = "q402_live_...",
-  Q402_PRIVATE_KEY          = "0xabc...",
-  Q402_ENABLE_REAL_PAYMENTS = "1",
-  Q402_MAX_AMOUNT_PER_CALL  = "5",
-}
+env_vars = [
+  "Q402_TRIAL_API_KEY",
+  "Q402_MULTICHAIN_API_KEY",
+  "Q402_PRIVATE_KEY",
+  "Q402_ENABLE_REAL_PAYMENTS",
+  "Q402_RELAY_BASE_URL",
+]
 ```
 
-> If you'd rather not inline secrets in `config.toml`, use the `env_vars` allow-list form to forward specific names from your shell environment instead — see the [Codex config reference](https://developers.openai.com/codex/config-reference) for the full schema.
+Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config reference](https://developers.openai.com/codex/config-reference) for the full schema.
 
-Then run `codex` and ask the same kind of question. The first call may take a few seconds while `npx` warms its cache; subsequent calls are instant.
+</details>
 
-### Any other MCP client
+### Try it without any setup
 
-The server has no client-specific code. If your client speaks stdio MCP, point it at `npx -y @quackai/q402-mcp` and the seven tools listed below will appear.
+`q402_quote` works with zero configuration — no API key, no private key, no env file. Ask:
+
+> *"Compare gas costs to send 50 USDC to vitalik.eth across all 9 Q402 chains."*
 
 ---
 
@@ -115,6 +109,7 @@ The server has no client-specific code. If your client speaks stdio MCP, point i
 
 | Tool | Auth | Purpose |
 |---|---|---|
+| `q402_doctor` | none | Health check covering BOTH first-install onboarding AND ongoing operational diagnostics. AI calls this when the user says "set up Q402" / "verify Q402" / "why isn't Q402 working". On first install, returns a `recommendedActions[]` payload telling the client to create `~/.q402/mcp.env` and open it in the user's editor. Later phases verify per-scope quota, EIP-7702 delegation state per chain, relay reachability, and surface slot-mismatch warnings (e.g. Trial-tier key sitting in `Q402_MULTICHAIN_API_KEY` would silently burn paid quota). Read-only — no signing, no on-chain action. |
 | `q402_quote` | none | Compare gas cost and supported tokens across chains. Read-only. |
 | `q402_balance` | API key | Verify the API key and report its plan tier + remaining quota credits (live vs sandbox). |
 | `q402_pay` | API key + private key + flag | Send a gasless payment to a single recipient. **Sandbox by default** — see [Sandbox vs live mode](#sandbox-vs-live-mode). |
@@ -136,12 +131,12 @@ The server has no client-specific code. If your client speaks stdio MCP, point i
 
 ## Sandbox vs live mode
 
-By default the MCP server operates in **sandbox mode**: `q402_pay` returns a random fake transaction hash (32-byte hex, no on-chain broadcast), no funds move, no gas-tank credit is consumed. That makes it safe to plug into any MCP client without worrying about an LLM hallucinating a payment.
+By default the MCP server operates in **sandbox mode**: `q402_pay` returns a random fake transaction hash (32-byte hex, no on-chain broadcast), no funds move, no gas-tank credit is consumed. That makes it safe to plug into any MCP client without worrying about an accidental payment — if the agent misreads the conversation and fires `q402_pay` before you intended, nothing moves.
 
 To enable real on-chain transactions, the resolved API key must be live (`q402_live_*`), `Q402_PRIVATE_KEY` must be set, and `Q402_ENABLE_REAL_PAYMENTS=1`:
 
 ```bash
-# Two-key model — set whichever applies. Both is best.
+# Two-key model — set whichever applies (or both for auto-routing).
 # Auto-routing (same for q402_pay AND q402_batch_pay):
 #   chain="bnb" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
 #   anything else                          → Multichain (paid 9-chain)
@@ -151,10 +146,6 @@ To enable real on-chain transactions, the resolved API key must be live (`q402_l
 Q402_TRIAL_API_KEY=q402_live_...           # BNB-only sponsored Trial key (from /event)
 Q402_MULTICHAIN_API_KEY=q402_live_...      # paid 9-chain key (per-chain Gas Tank)
 
-# Legacy fallback. Used for both scopes when the two above are unset —
-# single-env setups (only Q402_API_KEY set) keep working unchanged.
-Q402_API_KEY=q402_live_...
-
 Q402_PRIVATE_KEY=0xabc...                  # signer for the payer EOA
 Q402_ENABLE_REAL_PAYMENTS=1                # explicit opt-in
 ```
@@ -184,13 +175,14 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 |---|---|---|
 | `Q402_TRIAL_API_KEY` | live-pay (BNB) | BNB-only sponsored Trial key. Free at https://q402.quackai.ai/event. Auto-routed for `chain="bnb"` in both `q402_pay` and `q402_batch_pay` (≤5 recipients) when set. 6+ recipient BNB batches return `status="ambiguous"` so the agent can ask the user how to split. |
 | `Q402_MULTICHAIN_API_KEY` | live-pay (9-chain) | Paid 9-chain key. Get one at https://q402.quackai.ai/payment. Auto-routed for non-BNB chains AND for BNB when no Trial key is set. Cap: 20 recipients per batch. |
-| `Q402_API_KEY` | legacy fallback | Single-env legacy path. Used for both scopes when the two above are unset. Keep set if you only have one key. |
 | `Q402_PRIVATE_KEY` | live-pay | Signer for the payer EOA. **Never share. Never paste in chat.** |
 | `Q402_ENABLE_REAL_PAYMENTS` | live-pay | Set to `1` to opt in. Any other value (or unset) → sandbox. |
 | `Q402_MAX_AMOUNT_PER_CALL` | optional | USD-equivalent cap. Defaults to `5`. |
 | `Q402_ALLOWED_RECIPIENTS` | optional | Comma-separated lowercase addresses. Defaults to no allowlist. |
 | `Q402_RELAY_BASE_URL` | optional | Defaults to `https://q402.quackai.ai/api`. Override for self-hosted Q402. |
 
+> Older integrations may still set `Q402_API_KEY` as a single-env fallback — that still works silently for back-compat. New setups should use the two-key model above; `q402_doctor` only guides users to those two.
+
 ---
 
 ## Supported chains
@@ -211,11 +203,11 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 
 ## Why this exists
 
-x402 standardised "402 Payment Required" semantics for AI agents but the official Coinbase facilitator only covers a few chains and assumes ERC-3009 token support — which excludes BNB USDT, Mantle USDT0, Injective USDT, and the chains where most stablecoin volume actually lives.
+AI agents are becoming the default interface for software, but the moment they need to move money the stack breaks: holding gas tokens, signing every transaction, managing wallets across many chains. None of that scales when the agent is supposed to act on its own.
 
-Q402 implements the same payer experience (single signature, $0 gas, instant settlement) on all 9 of those chains using EIP-7702 delegated execution, which works with any ERC-20. This MCP server makes that infrastructure addressable from Claude itself.
+Q402 is the payment layer for that gap. A single signing primitive (EIP-712 + EIP-7702) settles gasless stablecoin payments across 9 EVM chains, with an ECDSA-signed Trust Receipt for every transaction. The MCP package exposes that surface inside Claude, Codex, Cursor, and Cline — your agent can quote, send, batch, and audit payments from a natural-language prompt.
 
-If you want to dig into how the wire protocol differs from x402, see [Q402 docs](https://q402.quackai.ai/docs).
+Single transfers and multi-recipient batches ship today. The next layer — recurring payouts, conditional execution, and policy-gated treasury automation — is the same primitive composed differently. We're building toward agents that operate real budgets, settle among themselves, and move value through workflows no human triggers manually.
 
 ---
 

package/dist/index.js

@@ -9,7 +9,73 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // src/config.ts
+import { existsSync, readFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 import { isAddress } from "ethers";
+var Q402_ENV_FILE = join(homedir(), ".q402", "mcp.env");
+function loadQ402EnvFileFromPath(path) {
+  if (!existsSync(path)) return {};
+  if (process.platform !== "win32") {
+    try {
+      const mode = statSync(path).mode & 511;
+      if (mode & 63) {
+        process.stderr.write(
+          `[q402-mcp] warning: ${path} is readable by group/other (mode ${mode.toString(8)}). Run: chmod 600 ${path}
+`
+        );
+      }
+    } catch {
+    }
+  }
+  const out = {};
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch (e) {
+    process.stderr.write(
+      `[q402-mcp] warning: could not read ${path}: ${e instanceof Error ? e.message : String(e)}
+`
+    );
+    return {};
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = t.indexOf("=");
+    if (eq < 0) continue;
+    const k = t.slice(0, eq).trim();
+    if (!k.startsWith("Q402_")) continue;
+    let rawVal = t.slice(eq + 1).trim();
+    const quoted = /^(['"])(.*)\1\s*(?:#.*)?$/.exec(rawVal);
+    if (quoted) {
+      rawVal = quoted[2];
+    } else {
+      const hashIdx = rawVal.search(/\s#/);
+      if (hashIdx >= 0) rawVal = rawVal.slice(0, hashIdx).trimEnd();
+    }
+    out[k] = rawVal;
+  }
+  return out;
+}
+function loadQ402EnvFile() {
+  return loadQ402EnvFileFromPath(Q402_ENV_FILE);
+}
+var FILE_ENV = loadQ402EnvFile();
+var ENV = Object.freeze({
+  ...FILE_ENV,
+  ...process.env
+});
+var Q402_ENV_FILE_PATH = Q402_ENV_FILE;
+var Q402_ENV_FILE_PRESENT = existsSync(Q402_ENV_FILE);
+var Q402_ENV_FILE_KEYS = Object.freeze(
+  new Set(
+    Object.keys(FILE_ENV).filter((k) => process.env[k] === void 0)
+  )
+);
+var Q402_ENV_FILE_KEYS_ALL = Object.freeze(
+  new Set(Object.keys(FILE_ENV))
+);
 var DEFAULT_RELAY_BASE = "https://q402.quackai.ai/api";
 var DEFAULT_MAX_AMOUNT = 5;
 function classifyApiKey(k) {
@@ -29,13 +95,13 @@ function parseMaxAmount(raw) {
   return n;
 }
 function loadConfig() {
-  const trialApiKey = process.env.Q402_TRIAL_API_KEY ?? null;
-  const multichainApiKey = process.env.Q402_MULTICHAIN_API_KEY ?? null;
-  const legacyApiKey = process.env.Q402_API_KEY ?? null;
+  const trialApiKey = ENV.Q402_TRIAL_API_KEY ?? null;
+  const multichainApiKey = ENV.Q402_MULTICHAIN_API_KEY ?? null;
+  const legacyApiKey = ENV.Q402_API_KEY ?? null;
   const apiKey = multichainApiKey ?? trialApiKey ?? legacyApiKey;
   const apiKeyKind = classifyApiKey(apiKey);
-  const privateKey = process.env.Q402_PRIVATE_KEY ?? null;
-  const realPaymentsRequested = process.env.Q402_ENABLE_REAL_PAYMENTS === "1";
+  const privateKey = ENV.Q402_PRIVATE_KEY ?? null;
+  const realPaymentsRequested = ENV.Q402_ENABLE_REAL_PAYMENTS === "1";
   const live = realPaymentsRequested && apiKeyKind === "live" && typeof privateKey === "string" && privateKey.length > 0;
   return {
     trialApiKey,
@@ -46,9 +112,9 @@ function loadConfig() {
     privateKey,
     realPaymentsRequested,
     mode: live ? "live" : "sandbox",
-    relayBaseUrl: (process.env.Q402_RELAY_BASE_URL ?? DEFAULT_RELAY_BASE).replace(/\/$/, ""),
-    maxAmountPerCallUsd: parseMaxAmount(process.env.Q402_MAX_AMOUNT_PER_CALL),
-    allowedRecipients: parseAllowedRecipients(process.env.Q402_ALLOWED_RECIPIENTS)
+    relayBaseUrl: (ENV.Q402_RELAY_BASE_URL ?? DEFAULT_RELAY_BASE).replace(/\/$/, ""),
+    maxAmountPerCallUsd: parseMaxAmount(ENV.Q402_MAX_AMOUNT_PER_CALL),
+    allowedRecipients: parseAllowedRecipients(ENV.Q402_ALLOWED_RECIPIENTS)
   };
 }
 var CONFIG = loadConfig();
@@ -90,12 +156,19 @@ function resolveApiKey(chain, scope = "auto") {
   }
   return { apiKey: key, scope: "multichain", fromLegacyFallback: !CONFIG.multichainApiKey };
 }
+var PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
 function isLiveModeFor(resolved) {
   if (!resolved.apiKey) return false;
   if (!CONFIG.realPaymentsRequested) return false;
   if (!CONFIG.privateKey) return false;
+  if (!PRIVATE_KEY_RE.test(CONFIG.privateKey)) return false;
   return resolved.apiKey.startsWith("q402_live_");
 }
+var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
+
+// src/version.ts
+var PACKAGE_NAME = "@quackai/q402-mcp";
+var PACKAGE_VERSION = "0.5.7";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -773,7 +846,7 @@ function describeSandboxReason(resolvedKey, scope) {
   if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
   const tier = scope === "trial" ? "Free Trial" : "Multichain";
   const url = scope === "trial" ? "https://q402.quackai.ai/event" : "https://q402.quackai.ai/payment";
-  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + `. Get a live ${tier} key at ${url}.`;
+  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + `. Get a live ${tier} key at ${url}, then call q402_doctor \u2014 it will walk the user through creating ~/.q402/mcp.env and pasting the key into the right slot.`;
 }
 var PAY_TOOL = {
   name: "q402_pay",
@@ -960,7 +1033,7 @@ function describeSandboxReason2(resolvedKey, scope) {
   if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
   const tier = scope === "trial" ? "Free Trial" : "Multichain";
   const url = scope === "trial" ? "https://q402.quackai.ai/event" : "https://q402.quackai.ai/payment";
-  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + `. Get a live ${tier} key at ${url}.`;
+  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + `. Get a live ${tier} key at ${url}, then call q402_doctor \u2014 it will walk the user through creating ~/.q402/mcp.env and pasting the key into the right slot.`;
 }
 var BATCH_PAY_TOOL = {
   name: "q402_batch_pay",
@@ -1056,7 +1129,7 @@ async function runBalance() {
       apiKeyMasked: null,
       scopes: [],
       dashboardUrl: "https://q402.quackai.ai/dashboard",
-      setupHint: "Set Q402_TRIAL_API_KEY (BNB-only sponsored, free at /event) and/or Q402_MULTICHAIN_API_KEY (paid 9-chain from /dashboard). Single-env legacy: Q402_API_KEY also works."
+      setupHint: "No API key configured. Call q402_doctor for guided setup \u2014 it will offer to create ~/.q402/mcp.env with placeholders that the user can fill in. (Manual path: set Q402_TRIAL_API_KEY for BNB-only sponsored free trial (https://q402.quackai.ai/event) or Q402_MULTICHAIN_API_KEY for the paid 9-chain plan (https://q402.quackai.ai/payment).)"
     };
   }
   const scopes = await Promise.all(
@@ -1453,9 +1526,311 @@ var CLEAR_DELEGATION_TOOL = {
   }
 };
 
+// src/tools/doctor.ts
+import { z as z8 } from "zod";
+import { Wallet as Wallet4 } from "ethers";
+var DoctorInputSchema = z8.object({});
+var ENV_FILE_TEMPLATE = `# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Q402 MCP \u2014 secrets
+# Read automatically by @quackai/q402-mcp on startup.
+# Edit this file in your editor. NEVER paste your private key into chat.
+# After editing, restart your MCP client (Codex / Claude / Cursor / Cline).
+# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+# \u2500\u2500\u2500 API key \u2014 uncomment ONE (or both for auto-routing) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Free Trial:        BNB Chain only, 2,000 sponsored TX
+# Get one at:        https://q402.quackai.ai/event
+# Q402_TRIAL_API_KEY=q402_live_...
+
+# Paid Multichain:   all 9 chains, per-chain Gas Tank
+# Get one at:        https://q402.quackai.ai/payment
+# Q402_MULTICHAIN_API_KEY=q402_live_...
+
+# \u2500\u2500\u2500 Your wallet \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Hex EVM private key (0x + 64 hex chars). Signs payments LOCALLY on
+# your machine \u2014 never leaves your device, never sent to any server.
+# Q402_PRIVATE_KEY=0x...
+
+# \u2500\u2500\u2500 Live mode flag \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Default 0 = sandbox (test responses, no funds move). Flip to 1 only
+# AFTER you've pasted real values into the lines above \u2014 otherwise the
+# server will refuse the placeholders.
+Q402_ENABLE_REAL_PAYMENTS=0
+
+# \u2500\u2500\u2500 Q402 relay endpoint \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Default canonical Q402 deployment. Only change for self-hosted.
+Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
+
+# \u2500\u2500\u2500 Optional safety guards \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Max USD per single q402_pay call (default: 5)
+# Q402_MAX_AMOUNT_PER_CALL=5
+#
+# 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.";
+function envSource(name) {
+  if (process.env[name] !== void 0) return "process";
+  if (Q402_ENV_FILE_KEYS.has(name)) return "file";
+  if (ENV[name] !== void 0) return "file";
+  return "unset";
+}
+function envSlot(name, purpose) {
+  const source = envSource(name);
+  return { set: source !== "unset", source, purpose };
+}
+function mask2(key) {
+  if (!key || key.length < 12) return key ?? "";
+  return `${key.slice(0, 12)}\u2026${key.slice(-4)}`;
+}
+function detectPhase() {
+  const anyKey = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
+  const allEssentials = anyKey && !!CONFIG.privateKey && CONFIG.realPaymentsRequested && CONFIG.apiKeyKind === "live";
+  if (allEssentials) return "live-check";
+  if (anyKey || CONFIG.privateKey || CONFIG.realPaymentsRequested) return "needs-completion";
+  return "first-install";
+}
+async function verifyOneKey(scope, envVar, apiKey) {
+  const url = `${CONFIG.relayBaseUrl}/keys/verify`;
+  try {
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiKey }),
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (resp.status === 429) {
+      return {
+        scope,
+        envVar,
+        apiKeyMasked: mask2(apiKey),
+        valid: false,
+        error: "rate limited by relay \u2014 wait 60s and re-run q402_doctor"
+      };
+    }
+    if (!resp.ok) {
+      return { scope, envVar, apiKeyMasked: mask2(apiKey), valid: false, error: `HTTP ${resp.status}` };
+    }
+    const body = await resp.json();
+    const result = {
+      scope,
+      envVar,
+      apiKeyMasked: mask2(apiKey),
+      valid: body.valid ?? false,
+      // Propagate the relay's specific reason ("API key has been rotated",
+      // "Subscription expired", "Trial expired") so the user gets the
+      // exact failure mode instead of a generic "verified as invalid".
+      error: body.valid === false ? body.error : void 0,
+      plan: body.plan,
+      remainingCredits: body.remainingCredits,
+      isTrial: body.isTrial,
+      trialExpiresAt: body.trialExpiresAt,
+      trialDaysLeft: body.trialDaysLeft
+    };
+    if (scope === "multichain" && body.isTrial) {
+      result.slotWarning = "Trial-tier key found in Q402_MULTICHAIN_API_KEY slot. This works but you'll lose the auto-routing benefit (BNB free via Trial). Move the key to Q402_TRIAL_API_KEY in ~/.q402/mcp.env.";
+    } else if (scope === "trial" && body.isTrial === false && body.plan && body.plan !== "trial") {
+      result.slotWarning = "Paid Multichain-tier key found in Q402_TRIAL_API_KEY slot. BNB payments will burn your paid quota instead of using free Trial sponsorship. Move the key to Q402_MULTICHAIN_API_KEY in ~/.q402/mcp.env.";
+    }
+    return result;
+  } catch (e) {
+    return {
+      scope,
+      envVar,
+      apiKeyMasked: mask2(apiKey),
+      valid: false,
+      error: e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+async function pingRelay() {
+  const url = `${CONFIG.relayBaseUrl}/keys/verify`;
+  const t0 = Date.now();
+  try {
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{}",
+      signal: AbortSignal.timeout(1e4)
+    });
+    const reachable = resp.status >= 200 && resp.status < 500;
+    return { url, reachable, latencyMs: Date.now() - t0 };
+  } catch (e) {
+    return {
+      url,
+      reachable: false,
+      latencyMs: Date.now() - t0,
+      error: e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+async function fetchDelegation(address) {
+  const url = `${CONFIG.relayBaseUrl}/wallet/delegation-status?address=${address}`;
+  try {
+    const resp = await fetch(url, { signal: AbortSignal.timeout(1e4) });
+    if (!resp.ok) {
+      return CHAIN_KEYS.map((chain) => ({ chain, delegated: false, error: `HTTP ${resp.status}` }));
+    }
+    const body = await resp.json();
+    return CHAIN_KEYS.map((chain) => {
+      const s = body.chains?.[chain];
+      if (!s) return { chain, delegated: false, error: "missing from response" };
+      return { chain, delegated: s.delegated, impl: s.impl, error: s.error };
+    });
+  } catch (e) {
+    const error = e instanceof Error ? e.message : String(e);
+    return CHAIN_KEYS.map((chain) => ({ chain, delegated: false, error }));
+  }
+}
+async function runDoctor() {
+  const phase = detectPhase();
+  const envFile = {
+    path: Q402_ENV_FILE_PATH,
+    exists: Q402_ENV_FILE_PRESENT
+  };
+  const envState = {
+    Q402_TRIAL_API_KEY: envSlot(
+      "Q402_TRIAL_API_KEY",
+      "Free Trial \u2014 BNB only, 2,000 sponsored TX. Get at https://q402.quackai.ai/event"
+    ),
+    Q402_MULTICHAIN_API_KEY: envSlot(
+      "Q402_MULTICHAIN_API_KEY",
+      "Paid Multichain \u2014 all 9 chains, per-chain Gas Tank. Get at https://q402.quackai.ai/payment"
+    ),
+    Q402_PRIVATE_KEY: envSlot(
+      "Q402_PRIVATE_KEY",
+      "Hex EVM private key. Signs LOCALLY on your machine \u2014 never leaves your device."
+    ),
+    Q402_ENABLE_REAL_PAYMENTS: envSlot(
+      "Q402_ENABLE_REAL_PAYMENTS",
+      "Must be '1' to allow real TX. Anything else = test response (fake hash)."
+    )
+  };
+  const missing = [];
+  if (!CONFIG.trialApiKey && !CONFIG.multichainApiKey && !CONFIG.legacyApiKey) {
+    missing.push(
+      "An API key (Q402_TRIAL_API_KEY for free BNB OR Q402_MULTICHAIN_API_KEY for paid 9-chain)"
+    );
+  }
+  if (!CONFIG.privateKey) {
+    missing.push("Q402_PRIVATE_KEY");
+  } else if (!isValidPrivateKey(CONFIG.privateKey)) {
+    missing.push(
+      "Q402_PRIVATE_KEY is set but malformed (expected 0x + 64 hex chars). Looks like the placeholder '0x...' is still in ~/.q402/mcp.env \u2014 paste a real key in your editor."
+    );
+  }
+  if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+  const recommendedActions = [];
+  if (!envFile.exists) {
+    recommendedActions.push({
+      id: "create-env-file",
+      type: "write_file",
+      path: Q402_ENV_FILE_PATH,
+      createParentDirs: true,
+      content: ENV_FILE_TEMPLATE,
+      requiresUserConfirm: true,
+      description: "Create ~/.q402/mcp.env with placeholder values, then open it in the user's editor.",
+      ifExists: "skip"
+    });
+  }
+  const warnings = [];
+  for (const name of Q402_ENV_FILE_KEYS_ALL) {
+    if (process.env[name] !== void 0 && Q402_ENV_FILE_KEYS_ALL.has(name) && !Q402_ENV_FILE_KEYS.has(name)) {
+      warnings.push(
+        `${name} is set in both your shell (process.env) AND ~/.q402/mcp.env \u2014 the shell value wins. Editing the file will have NO effect until you \`unset ${name}\` in your shell (or update the shell value to match).`
+      );
+    }
+  }
+  if (phase !== "live-check") {
+    return {
+      package: PACKAGE_NAME,
+      version: PACKAGE_VERSION,
+      phase,
+      ready: false,
+      envFile,
+      envState,
+      missing,
+      warnings,
+      recommendedActions,
+      greeting: phase === "first-install" ? `Q402 MCP is installed (v${PACKAGE_VERSION}).` : `Q402 MCP is installed (v${PACKAGE_VERSION}) \u2014 partially configured.`,
+      nextStep: phase === "first-install" ? "Offer to create ~/.q402/mcp.env. After yes, run the recommendedActions[].write_file action, then open the file in the user's editor (e.g. via `code` / `open` / `start` / `xdg-open`). Then walk through filling in the API key and private key, one at a time. Do NOT accept key values via chat \u2014 direct the user to edit the file in their editor." : `Tell the user which env vars are still missing (from the 'missing' list) and how to add them to ~/.q402/mcp.env. Restart needed after editing.`,
+      securityNotice: SECURITY_NOTICE
+    };
+  }
+  let walletAddress;
+  let walletError;
+  try {
+    walletAddress = new Wallet4(CONFIG.privateKey).address;
+  } catch (e) {
+    walletError = e instanceof Error ? e.message : String(e);
+    warnings.push(
+      `Q402_PRIVATE_KEY is set but does not parse as a 32-byte hex key: ${walletError}. Open ~/.q402/mcp.env in your editor and paste a real key (0x + 64 hex chars). Live calls will fail until this is fixed.`
+    );
+  }
+  const verifyTargets = [];
+  if (CONFIG.trialApiKey) verifyTargets.push({ scope: "trial", envVar: "Q402_TRIAL_API_KEY", key: CONFIG.trialApiKey });
+  if (CONFIG.multichainApiKey) verifyTargets.push({ scope: "multichain", envVar: "Q402_MULTICHAIN_API_KEY", key: CONFIG.multichainApiKey });
+  if (verifyTargets.length === 0 && CONFIG.legacyApiKey) {
+    verifyTargets.push({ scope: "legacy", envVar: "Q402_API_KEY", key: CONFIG.legacyApiKey });
+  }
+  const [keys, delegation, relay] = await Promise.all([
+    Promise.all(verifyTargets.map((t) => verifyOneKey(t.scope, t.envVar, t.key))),
+    walletAddress ? fetchDelegation(walletAddress) : Promise.resolve(void 0),
+    pingRelay()
+  ]);
+  for (const k of keys) if (k.slotWarning) warnings.push(k.slotWarning);
+  for (const k of keys) {
+    if (typeof k.remainingCredits === "number" && k.remainingCredits === 0) {
+      warnings.push(
+        `${k.envVar} has 0 credits remaining. ` + (k.isTrial ? "Trial allotment exhausted \u2014 upgrade to a Multichain plan at https://q402.quackai.ai/payment." : "Paid plan quota exhausted \u2014 top up at https://q402.quackai.ai/dashboard?tab=billing.")
+      );
+    } else if (typeof k.remainingCredits === "number" && k.remainingCredits > 0 && k.remainingCredits < 50) {
+      warnings.push(
+        `${k.envVar} has only ${k.remainingCredits} credits left \u2014 top up before you run out.`
+      );
+    }
+    if (!k.valid) {
+      warnings.push(
+        k.error ? `${k.envVar}: ${k.error}.` : `${k.envVar} verified as invalid by the relay \u2014 check the key value in ~/.q402/mcp.env.`
+      );
+    }
+  }
+  if (relay && !relay.reachable) {
+    warnings.push(
+      `Q402 relay at ${relay.url} is unreachable. Check your network or override with Q402_RELAY_BASE_URL if you self-host.`
+    );
+  }
+  const ready = warnings.length === 0 && keys.some((k) => k.valid);
+  return {
+    package: PACKAGE_NAME,
+    version: PACKAGE_VERSION,
+    phase,
+    ready,
+    envFile,
+    envState,
+    missing,
+    wallet: walletAddress ? { address: walletAddress } : void 0,
+    keys,
+    delegation,
+    relay,
+    warnings,
+    recommendedActions,
+    greeting: ready ? `Q402 MCP is ready (v${PACKAGE_VERSION}).` : `Q402 MCP is installed but has ${warnings.length} issue${warnings.length === 1 ? "" : "s"} to address.`,
+    nextStep: ready ? "Summarize the wallet address, plan tier(s), remaining quota, and any non-zero delegation counts to the user as a checklist. Then offer to make a test payment via q402_quote." : "Walk the user through each warning in order. For slot-mismatch warnings, the fix is editing ~/.q402/mcp.env and restarting the client.",
+    securityNotice: SECURITY_NOTICE
+  };
+}
+var DOCTOR_TOOL = {
+  name: "q402_doctor",
+  description: 'Run a Q402 health check \u2014 covers first-install onboarding AND ongoing diagnostics in one tool. Read-only, no API key required. Detects the current phase (first-install / needs-completion / live-check) and tailors output to it. \n\nUse when the user says any of: "set up Q402", "verify Q402", "why isn\'t Q402 working", "Q402 status", "check Q402". This is the FIRST tool to call after install, BEFORE q402_pay or q402_balance \u2014 it tells the agent what state the user is in. \n\nMulti-turn pattern the AI should follow when phase = first-install: (1) Tell user MCP is installed. (2) Ask one yes/no question: \'Want me to create your secrets file at ~/.q402/mcp.env?\' (3) On yes, execute the recommendedActions[].write_file action using the client\'s own filesystem tool, then open the file in the user\'s editor (e.g. `code ~/.q402/mcp.env`, `open` on macOS, `start` on Windows, `xdg-open` on Linux). (4) Guide the user through getting an API key (free Trial at https://q402.quackai.ai/event OR paid Multichain at /payment) and pasting it into the file (in their editor \u2014 NEVER in chat). (5) Same for the private key. (6) Tell them to save + restart the MCP client. (7) Call q402_doctor again to verify. \n\nSecurity policy carried in the response: AI MUST surface the securityNotice when first walking through setup. If the user pastes a private key directly in chat, DO NOT refuse \u2014 the exposure already happened. Help them by directing them to put it in the file themselves (via their editor), and inform them the chat history now contains the key (most clients store this locally, some sync to cloud) so they should treat the wallet as exposed if it holds valuables. \n\nLive-check phase additionally returns per-scope quota, EIP-7702 delegation state per chain, relay reachability, and slot-mismatch warnings (e.g. Trial key in Multichain slot silently burns paid quota \u2014 surface this to the user).',
+  inputSchema: {
+    type: "object",
+    properties: {},
+    additionalProperties: false
+  }
+};
+
 // src/index.ts
-var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.5.5";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }
@@ -1466,6 +1841,9 @@ async function main() {
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
+      // doctor first — it's the bootstrap tool: any "set up Q402" / "is Q402
+      // working" prompt should land here before quote/balance/pay are tried.
+      DOCTOR_TOOL,
       QUOTE_TOOL,
       BALANCE_TOOL,
       PAY_TOOL,
@@ -1479,6 +1857,10 @@ async function main() {
     const { name, arguments: args } = req.params;
     try {
       switch (name) {
+        case "q402_doctor": {
+          DoctorInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runDoctor())] };
+        }
         case "q402_quote": {
           const parsed = QuoteInputSchema.parse(args ?? {});
           return { content: [jsonText(runQuote(parsed))] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "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": [