@quackai/q402-mcp 0.3.9 → 0.3.11

package/README.md

@@ -1,6 +1,6 @@
 # @quackai/q402-mcp
 
-> MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.
+> MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 7 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.
 
 [![npm](https://img.shields.io/npm/v/@quackai/q402-mcp.svg)](https://www.npmjs.com/package/@quackai/q402-mcp)
 [![license](https://img.shields.io/npm/l/@quackai/q402-mcp.svg)](./LICENSE)
@@ -13,13 +13,17 @@ Claude can now reason about stablecoin payments end to end — quote a transfer
 
 ---
 
-## Quick start (Claude Desktop)
+## 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**.
+
+### Claude Desktop / Claude Code
 
 ```bash
 claude mcp add q402 -- npx -y @quackai/q402-mcp
 ```
 
-Or, if you prefer editing the config file directly, add this entry to your `claude_desktop_config.json`:
+Or edit `claude_desktop_config.json` directly:
 
 ```json
 {
@@ -36,7 +40,56 @@ Restart Claude Desktop and ask:
 
 > *"Compare gas costs to send 50 USDC to vitalik.eth across all 7 Q402 chains."*
 
-You'll get a ranked breakdown immediately — no API key, no signup, no funds at risk.
+### OpenAI Codex CLI
+
+Three install paths — pick the one that matches your workflow.
+
+**(a) Codex plugin marketplace** (recommended — bundles the MCP config so users don't write TOML):
+
+```bash
+codex plugin marketplace add bitgett/q402-mcp
+codex /plugins        # browse and install "q402"
+```
+
+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.
+
+**(b) Single MCP server via `codex mcp add`** (no plugin wrapper — just register the stdio server):
+
+```bash
+codex mcp add q402 -- npx -y @quackai/q402-mcp
+```
+
+**(c) Direct `~/.codex/config.toml` edit** (`.codex/config.toml` for per-project scope):
+
+```toml
+[mcp_servers.q402]
+command = "npx"
+args = ["-y", "@quackai/q402-mcp"]
+startup_timeout_sec = 20.0
+```
+
+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:
+
+```toml
+[mcp_servers.q402]
+command = "npx"
+args = ["-y", "@quackai/q402-mcp"]
+startup_timeout_sec = 20.0
+env = {
+  Q402_API_KEY              = "q402_live_...",
+  Q402_PRIVATE_KEY          = "0xabc...",
+  Q402_ENABLE_REAL_PAYMENTS = "1",
+  Q402_MAX_AMOUNT_PER_CALL  = "5",
+}
+```
+
+> 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 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.
+
+### Any other MCP client
+
+The server has no client-specific code. If your client speaks stdio MCP, point it at `npx -y @quackai/q402-mcp` and the four tools listed below will appear.
 
 ---
 
@@ -47,7 +100,7 @@ You'll get a ranked breakdown immediately — no API key, no signup, no funds at
 | `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). |
-| `q402_batch_pay` | API key + private key + flag | Send a gasless payment to **multiple** recipients in one call on a single chain × token. Trial keys: 5 rows max. Paid keys: 20 rows max. Same sandbox gating as `q402_pay`. |
+| `q402_batch_pay` | API key + private key + flag | Send a gasless payment to **multiple** recipients in one call on a single chain × token. Trial keys: 5 rows max. Paid keys: 20 rows max. **Supported chains: avax, bnb, eth, mantle, injective** (default EIP-7702 mode). xlayer + stable are NOT batchable — use `q402_pay` in a loop for those. Same sandbox gating as `q402_pay`. |
 | `q402_receipt` | none | Look up a Trust Receipt by `rct_…` id and locally verify its ECDSA signature against the relayer EOA. Returns the public settlement record + a `verified` boolean. *receiptId-only today; tx-hash lookup reserved for a future release.* |
 
 `q402_pay` and `q402_batch_pay` follow a "confirm in chat first" contract: the tool description instructs the model to never call it without explicit user approval of the recipient address(es), amount(s), chain, and token. For batch calls the user must approve the **full batch**, not the individual rows.
@@ -63,7 +116,7 @@ You'll get a ranked breakdown immediately — no API key, no signup, no funds at
 
 ## Sandbox vs live mode
 
-By default the MCP server operates in **sandbox mode**: `q402_pay` returns a deterministic-looking fake transaction hash, no funds move, no gas-tank credit is consumed. That makes it safe to plug into any Claude Desktop install without worrying about an LLM hallucinating a payment.
+By default the MCP server operates in **sandbox mode**: `q402_pay` returns a deterministic-looking fake transaction hash, 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.
 
 To enable real on-chain transactions, **all three** environment variables must be set:
 

package/dist/index.js

@@ -445,28 +445,45 @@ var Q402NodeClient = class _Q402NodeClient {
    * first transfer must succeed (it installs / re-confirms the
    * delegation), after which the remaining transfers are surfaced in
    * the result array even if individual ones fail.
+   *
+   * Signature shape: `{ token, recipients }`. The previous revision took
+   * `PayInput[]` (with token on each row), which read as if rows could
+   * carry different tokens — but the request body only ships one token
+   * field, so the per-row token on rows 1..N was silently ignored.
+   * Codex audit P2: surface the constraint in the type so consumers
+   * can't accidentally build a "mixed-token batch" that quietly drops
+   * the second token. Same chain + same token across one batch, full
+   * stop.
    */
-  async batchPay(inputs) {
-    if (!Array.isArray(inputs) || inputs.length === 0) {
+  async batchPay(input) {
+    const { token, recipients: rows } = input;
+    if (!Array.isArray(rows) || rows.length === 0) {
       throw new Error("batchPay requires at least one recipient");
     }
+    if (typeof token !== "string") {
+      throw new Error("batchPay({ token, recipients }): token must be a string");
+    }
     const { chain, relayBaseUrl, apiKey, privateKey } = this.opts;
-    for (let i = 0; i < inputs.length; i++) {
-      const inp = inputs[i];
-      const tokenCfg = tokenFor(chain, inp.token);
-      if (chain.supportedTokens && !chain.supportedTokens.includes(inp.token)) {
-        throw new Error(
-          `recipient[${i}]: token ${inp.token} is not supported on chain ${chain.key}. Supported: ${chain.supportedTokens.join(", ")}.`
-        );
-      }
+    const tokenCfg = tokenFor(chain, token);
+    if (chain.supportedTokens && !chain.supportedTokens.includes(token)) {
+      throw new Error(
+        `token ${token} is not supported on chain ${chain.key}. Supported: ${chain.supportedTokens.join(", ")}.`
+      );
+    }
+    for (let i = 0; i < rows.length; i++) {
       try {
-        toRawAmount(inp.amount, tokenCfg.decimals);
+        toRawAmount(rows[i].amount, tokenCfg.decimals);
       } catch (e) {
         throw new Error(
           `recipient[${i}]: ${e instanceof Error ? e.message : String(e)}`
         );
       }
     }
+    if (chain.key === "xlayer" || chain.key === "stable") {
+      throw new Error(
+        `batchPay does not yet support chain "${chain.key}". Supported batch chains: avax, bnb, eth, mantle, injective (default EIP-7702 mode). For "${chain.key}" use pay() in a client-side loop.`
+      );
+    }
     const rpcUrl = this.opts.rpcUrl ?? DEFAULT_RPC[chain.chainId];
     if (!rpcUrl) {
       throw new Error(
@@ -479,11 +496,10 @@ var Q402NodeClient = class _Q402NodeClient {
     const facilitator = await this.fetchFacilitator();
     const baseAuthNonce = await provider.getTransactionCount(owner);
     const deadline = Math.floor(Date.now() / 1e3) + 600;
-    const recipients = [];
-    for (let i = 0; i < inputs.length; i++) {
-      const inp = inputs[i];
-      const tokenCfg = tokenFor(chain, inp.token);
-      const amountRaw = toRawAmount(inp.amount, tokenCfg.decimals);
+    const signedRows = [];
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const amountRaw = toRawAmount(row.amount, tokenCfg.decimals);
       const paymentNonce = toBigInt(randomBytes(32));
       const witnessSig = await wallet.signTypedData(
         {
@@ -497,7 +513,7 @@ var Q402NodeClient = class _Q402NodeClient {
           owner,
           facilitator,
           token: tokenCfg.address,
-          recipient: inp.to,
+          recipient: row.to,
           amount: BigInt(amountRaw),
           nonce: paymentNonce,
           deadline: BigInt(deadline)
@@ -508,16 +524,15 @@ var Q402NodeClient = class _Q402NodeClient {
         address: chain.implContract,
         nonce: baseAuthNonce + i
       });
-      const baseRow = {
+      signedRows.push({
         from: owner,
-        to: inp.to,
+        to: row.to,
         amount: amountRaw,
+        nonce: paymentNonce.toString(),
         deadline,
         witnessSig,
         authorization
-      };
-      const row = chain.key === "xlayer" ? { ...baseRow, xlayerNonce: paymentNonce.toString() } : chain.key === "stable" ? { ...baseRow, stableNonce: paymentNonce.toString() } : { ...baseRow, nonce: paymentNonce.toString() };
-      recipients.push(row);
+      });
     }
     const resp = await fetch(`${relayBaseUrl.replace(/\/$/, "")}/relay/batch`, {
       method: "POST",
@@ -525,15 +540,23 @@ var Q402NodeClient = class _Q402NodeClient {
       body: JSON.stringify({
         apiKey,
         chain: chain.key,
-        token: inputs[0].token,
-        // all recipients must share token; pre-validated above
+        token,
         facilitator,
-        recipients
+        recipients: signedRows
       })
     });
     const data = await resp.json();
-    if (!resp.ok) {
-      throw new Error(data.error ?? `relay/batch failed (HTTP ${resp.status})`);
+    if (!resp.ok || data.ok === false) {
+      const err = new BatchPayError(
+        data.aborted ? `Batch aborted: recipient[0] failed (${data.results?.[0]?.error ?? "unknown"}). No transfers landed.` : data.totalFailed > 0 ? `Batch completed with ${data.totalFailed}/${data.results?.length ?? "?"} failed rows.` : data.error ?? `relay/batch failed (HTTP ${resp.status})`,
+        {
+          aborted: !!data.aborted,
+          totalSuccess: data.totalSuccess ?? 0,
+          totalFailed: data.totalFailed ?? signedRows.length,
+          results: data.results ?? []
+        }
+      );
+      throw err;
     }
     data.results = data.results.map((r) => ({
       ...r,
@@ -542,6 +565,20 @@ var Q402NodeClient = class _Q402NodeClient {
     return data;
   }
 };
+var BatchPayError = class extends Error {
+  aborted;
+  totalSuccess;
+  totalFailed;
+  results;
+  constructor(message, details) {
+    super(message);
+    this.name = "BatchPayError";
+    this.aborted = details.aborted;
+    this.totalSuccess = details.totalSuccess;
+    this.totalFailed = details.totalFailed;
+    this.results = details.results;
+  }
+};
 function sandboxPay(chain, input) {
   const tokenCfg = tokenFor(chain, input.token);
   const tokenAmount = toRawAmount(input.amount, tokenCfg.decimals);
@@ -678,7 +715,7 @@ var RECIPIENT_LIMIT_TRIAL = 5;
 var RECIPIENT_LIMIT_PAID = 20;
 var CLIENT_RECIPIENT_CAP = RECIPIENT_LIMIT_PAID;
 var BatchPayInputSchema = z3.object({
-  chain: z3.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective"]),
+  chain: z3.enum(["avax", "bnb", "eth", "mantle", "injective"]),
   token: z3.enum(["USDC", "USDT", "RLUSD"]).describe(
     "Stablecoin symbol. USDC / USDT supported on most chains (Injective is USDT-only). RLUSD (Ripple USD, NY DFS regulated, decimals 18) is Ethereum-only. The same token applies to every recipient in the batch."
   ),
@@ -741,6 +778,7 @@ async function runBatchPay(input) {
     guardsApplied.push("mode=sandbox");
     return {
       mode: "sandbox",
+      status: "sandbox",
       result: { sandbox: sandboxResults, reason: describeSandboxReason2() },
       guardsApplied,
       setupHint: describeSandboxReason2()
@@ -752,13 +790,38 @@ async function runBatchPay(input) {
     chain,
     relayBaseUrl: CONFIG.relayBaseUrl
   });
-  const result = await client.batchPay(
-    input.recipients.map((r) => ({ to: r.to, amount: r.amount, token: input.token }))
-  );
-  guardsApplied.push("mode=live");
-  guardsApplied.push(`scope=${result.scope} (server enforced)`);
-  guardsApplied.push(`batch_size=${input.recipients.length}/${result.limit}`);
-  return { mode: "live", result, guardsApplied };
+  try {
+    const result = await client.batchPay({
+      token: input.token,
+      recipients: input.recipients.map((r) => ({ to: r.to, amount: r.amount }))
+    });
+    guardsApplied.push("mode=live");
+    guardsApplied.push(`scope=${result.scope} (server enforced)`);
+    guardsApplied.push(`batch_size=${input.recipients.length}/${result.limit}`);
+    return { mode: "live", status: "success", result, guardsApplied };
+  } catch (err) {
+    if (err instanceof BatchPayError) {
+      guardsApplied.push("mode=live");
+      guardsApplied.push(`batch_${err.aborted ? "aborted" : "partial_failure"}`);
+      const status = err.aborted ? "aborted" : "partial_failure";
+      return {
+        mode: "live",
+        status,
+        result: {
+          ok: false,
+          scope: "paid",
+          limit: input.recipients.length,
+          totalSuccess: err.totalSuccess,
+          totalFailed: err.totalFailed,
+          aborted: err.aborted,
+          results: err.results
+        },
+        guardsApplied,
+        error: err.message
+      };
+    }
+    throw err;
+  }
 }
 function describeSandboxReason2() {
   const missing = [];
@@ -770,14 +833,17 @@ function describeSandboxReason2() {
 }
 var BATCH_PAY_TOOL = {
   name: "q402_batch_pay",
-  description: `Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Trial keys (q402_live_* with plan='trial'): max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Paid keys: max ${RECIPIENT_LIMIT_PAID} recipients per call, full 7-chain support. SANDBOX BY DEFAULT \u2014 real on-chain TX only when Q402_API_KEY (live), Q402_PRIVATE_KEY, and Q402_ENABLE_REAL_PAYMENTS=1 are all set. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. ALWAYS get explicit user confirmation of the complete recipient + amount list, chain, and token in conversation immediately before calling this tool \u2014 the user must approve the full batch, not the individual rows.`,
+  description: `Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Trial keys (q402_live_* with plan='trial'): max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Paid keys: max ${RECIPIENT_LIMIT_PAID} recipients per call across 5 EIP-7702 default chains (avax, bnb, eth, mantle, injective). xlayer + stable are NOT batchable \u2014 use q402_pay in a loop. SANDBOX BY DEFAULT \u2014 real on-chain TX only when Q402_API_KEY (live), Q402_PRIVATE_KEY, and Q402_ENABLE_REAL_PAYMENTS=1 are all set. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. ALWAYS get explicit user confirmation of the complete recipient + amount list, chain, and token in conversation immediately before calling this tool \u2014 the user must approve the full batch, not the individual rows.`,
   inputSchema: {
     type: "object",
     properties: {
       chain: {
         type: "string",
-        enum: CHAIN_KEYS,
-        description: "Target chain. Applies to every recipient in the batch."
+        // Narrower than the full chain set — xlayer and stable are NOT batchable
+        // (chain-specific nonce field shapes). Use q402_pay in a loop for
+        // those chains.
+        enum: ["avax", "bnb", "eth", "mantle", "injective"],
+        description: "Target chain. Applies to every recipient in the batch. xlayer + stable are NOT supported here \u2014 use q402_pay in a loop."
       },
       token: {
         type: "string",
@@ -1028,7 +1094,7 @@ var RECEIPT_TOOL = {
 
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.3.9";
+var PACKAGE_VERSION = "0.3.11";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.3.9",
-  "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.",
+  "version": "0.3.11",
+  "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 7 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",
     "model-context-protocol",
     "claude",
+    "claude-desktop",
+    "claude-code",
+    "codex",
+    "openai-codex",
+    "cline",
     "q402",
     "x402",
     "stablecoin",