@quackai/q402-mcp 0.4.4 → 0.4.5

package/README.md

@@ -76,7 +76,7 @@ command = "npx"
 args = ["-y", "@quackai/q402-mcp"]
 startup_timeout_sec = 20.0
 env = {
-  # Two-key model (v0.4.4+): set whichever applies — both is best.
+  # Two-key model (v0.4.5+): set whichever applies — both is best.
   # The server auto-routes by chain: BNB → trial key, else multichain key.
   # 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
@@ -133,14 +133,14 @@ By default the MCP server operates in **sandbox mode**: `q402_pay` returns a det
 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 (v0.4.4+) — set whichever applies. Both is best.
+# Two-key model (v0.4.5+) — set whichever applies. Both is best.
 # Auto-routing: chain="bnb" → trial key (if set), otherwise multichain key.
 # Override per call with keyScope: "auto" | "trial" | "multichain".
 Q402_TRIAL_API_KEY=q402_live_...           # BNB-only sponsored Trial key (from /event)
 Q402_MULTICHAIN_API_KEY=q402_live_...      # paid 8-chain key (per-chain Gas Tank)
 
 # Legacy fallback. Used for both scopes when the two above are unset —
-# pre-v0.4.4 users keep working without any config change.
+# pre-v0.4.5 users keep working without any config change.
 Q402_API_KEY=q402_live_...
 
 Q402_PRIVATE_KEY=0xabc...                  # signer for the payer EOA
@@ -149,6 +149,10 @@ Q402_ENABLE_REAL_PAYMENTS=1                # explicit opt-in
 
 Anything missing for the resolved scope → automatic sandbox fallback with a hint pointing at what to set.
 
+> ⚠️ **Sandbox returns a deterministic-looking fake `txHash` and a synthetic success result.** A user who *expected* a live transfer (e.g. forgot to set `Q402_ENABLE_REAL_PAYMENTS=1`, mis-typed a scoped env var, or hit an impossible chain×scope combination like `keyScope: "trial"` + `chain: "monad"`) gets a "success" back and may believe funds actually moved.
+>
+> Two-layer mitigation: every sandbox response carries a `setupHint` field on the tool result describing **exactly why** sandbox was selected, and the `q402_balance` tool's `apiKeyKind: "missing"` makes the same diagnosis explicit. Always check `setupHint` on the first call from a new install. The deterministic `txHash` pattern (`0x` + 64 hex derived from `keccak256(chain, to, amount, token, "sandbox")`) is intentional so the agent can recognise it post-hoc, but the safer habit is to inspect `setupHint` before showing the user a success message.
+
 ### Hard caps
 
 Two additional guards run before every payment regardless of mode:
@@ -168,7 +172,7 @@ 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. Used automatically for `chain="bnb"` when set. |
 | `Q402_MULTICHAIN_API_KEY` | live-pay (8-chain) | Paid 8-chain key. Get one at https://q402.quackai.ai/payment. Used for all non-BNB chains and for BNB when no Trial key is set. |
-| `Q402_API_KEY` | legacy fallback | Pre-v0.4.4 single-env path. Used for both scopes when the two above are unset. Keep set if you only have one key. |
+| `Q402_API_KEY` | legacy fallback | Pre-v0.4.5 single-env 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`. |

package/dist/index.js

@@ -230,7 +230,7 @@ var CHAIN_CONFIG = {
   }
 };
 var BNB_FOCUS_MODE = false;
-var BNB_FOCUS_REJECTION_MESSAGE = 'BNB-focus sprint: this chain/token is temporarily hidden. Full multi-chain support returns after the sprint window. Pass chain: "bnb" with token "USDC" or "USDT".';
+var BNB_FOCUS_REJECTION_MESSAGE = 'BNB-only mode active: this chain/token is temporarily hidden. Full multi-chain support is the normal state. Pass chain: "bnb" with token "USDC" or "USDT".';
 if (BNB_FOCUS_MODE) {
   for (const key of CHAIN_KEYS) {
     if (key !== "bnb") {
@@ -839,10 +839,10 @@ function maxAmountGuardBatch(recipients, cap) {
 function recipientAllowlistGuardBatch(recipients, allow) {
   if (allow.length === 0) return;
   for (let i = 0; i < recipients.length; i++) {
-    const to = recipients[i].to.toLowerCase();
-    if (!allow.includes(to)) {
+    const r = recipients[i];
+    if (!allow.includes(r.to.toLowerCase())) {
       throw new Error(
-        `recipients[${i}]: ${recipients[i].to} is not in Q402_ALLOWED_RECIPIENTS. Either add this address to the allowlist or unset the env var to disable the guard.`
+        `recipients[${i}]: ${r.to} is not in Q402_ALLOWED_RECIPIENTS. Either add this address to the allowlist or unset the env var to disable the guard.`
       );
     }
   }
@@ -1221,7 +1221,7 @@ var RECEIPT_TOOL = {
 
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.4.4";
+var PACKAGE_VERSION = "0.4.5";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 8 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [
@@ -40,7 +40,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "prepublishOnly": "npm run build",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run build",
     "start": "node dist/index.js"
   },
   "dependencies": {
@@ -65,5 +66,8 @@
   "author": "David Lee <davidlee@quackai.ai>",
   "publishConfig": {
     "access": "public"
+  },
+  "overrides": {
+    "ws": "^8.20.1"
   }
 }