verify402-mcp 1.0.2 → 1.0.3

package/README.md

@@ -14,7 +14,7 @@ wallet that pays in USDC; the bridge never signs or sends a trade.
 |---|---|---|
 | `preflight_gate` | **free** | "Should I sign this payment request or transaction?" — PASS / CAUTION / BLOCK with reasons, `checked` / `notChecked`, and a short-lived receipt |
 | `verify_arbitrage` | $0.05 | "Is this cross-venue arbitrage opportunity real, right now?" |
-| `check_token_safety` | $0.10 | "Is this token safe to buy?" — TRUST / CAUTION / AVOID with evidence |
+| `check_token_safety` | $0.10 | "Is this token sellable at a realistic size, and what does the round trip cost?" — TRUST / CAUTION / AVOID with evidence; not a code audit |
 | `get_best_route` | $0.03 | "What would the chain actually pay for this swap?" — best route + every quoted venue |
 | `verify_quote_fairness` | $0.05 | "A broker/bot offered me this number — is it honest?" fair / overpaying / too_good_to_be_true |
 | `get_trade_depth` | $0.05 | "How big can I trade here before the round trip eats me?" — per-size impact, round-trip cost, capacity |
@@ -31,23 +31,24 @@ belongs in the executor that signs — verify the receipt, then sign. See
 for a deny-by-default reference that refuses to call the signer without a
 verified receipt.
 
-## Run
+## Distribution & Run
 
-The package is distributed as a versioned GitHub release tarball. No npm
-account is required.
+The package is officially published on npm as **[`verify402-mcp`](https://www.npmjs.com/package/verify402-mcp)** and indexed on the official [Model Context Protocol Registry](https://registry.modelcontextprotocol.io/).
+
+Run directly via `npx` (stdio transport):
 
 ```bash
-npx -y \
-  --package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz \
-  verify402-mcp --help
+npx -y verify402-mcp --help
 ```
 
-**Warm the cache first.** The first `npx` run installs the MCP SDK and `viem`;
-some clients kill a server that takes more than 30 seconds to start. Run the
-`--help` command once before adding it to an MCP client. After that, startup is
-fast.
+You can also install it globally:
+
+```bash
+npm install -g verify402-mcp
+verify402-mcp --help
+```
 
-From source:
+Or run from source:
 
 ```bash
 git clone https://github.com/a32116150-ctrl/verify402
@@ -56,47 +57,20 @@ npm ci
 node index.mjs --help
 ```
 
-## Free gate only (no key)
+---
 
-Omit `EVM_PRIVATE_KEY`. The server registers only `preflight_gate` and logs
-`free preflight_gate only`. Nothing can be charged.
+## AI Agent Integration (Step-by-Step)
 
-## Paid tools (dedicated hot wallet)
-
-Set a wallet with USDC on the payment network. Use a wallet with only the money
-you are willing to spend — never a main wallet. The key stays in your MCP client
-configuration or environment; the package never contains it.
-
-```
-EVM_PRIVATE_KEY=0x...        # optional; omit for free-only
-VERIFY402_URL=https://verify402.onrender.com
-MAX_PAYMENT_USD=0.25         # hard cap on ONE payment, enforced at signature time
-MAX_DAILY_USD=0.50           # optional cap for the UTC day, persisted
-SPEND_LEDGER_PATH=           # optional ledger path (default .spend-ledger.json)
-VERIFY402_NETWORKS=eip155:8453   # paid calls only; comma-separated EVM networks
-VERIFY402_PAY_TO=0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb
-# VERIFY402_RESOURCE_PREFIX=https://verify402.onrender.com
-```
-
-The paid client refuses a 402 that names another network or payee, a resource
-outside the configured server, or a non-paid route. It also refuses redirects.
-The amount cap and the USDC-only default-asset allowlist are enforced inside
-the x402 client, before a signature exists.
-
-### Claude Desktop / Cursor
-
-`claude_desktop_config.json`, or `.cursor/mcp.json`:
+### Step 1: Free Mode (Zero Config, No Wallet)
+To give your AI agent the free **`preflight_gate`** (checks transaction calldata, payment challenges, payee/amount, approvals, and block freshness before signing), paste this into your client configuration. Honeypot/sellability evidence is the paid `check_token_safety` check, not a free-gate guarantee.
 
+**Claude Desktop** (`claude_desktop_config.json`) or **Cursor** (`.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {
     "verify402": {
       "command": "npx",
-      "args": [
-        "-y",
-        "--package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz",
-        "verify402-mcp"
-      ],
+      "args": ["-y", "verify402-mcp"],
       "env": {
         "VERIFY402_URL": "https://verify402.onrender.com"
       }
@@ -105,14 +79,41 @@ the x402 client, before a signature exists.
 }
 ```
 
-For paid tools, add `"EVM_PRIVATE_KEY": "0x..."`, `"MAX_PAYMENT_USD": "0.25"`
-and optionally `"MAX_DAILY_USD": "0.50"` to `env`. The free gate works without
-them.
+### Step 2: Paid Mode (Setting Up the Hot Wallet)
+To enable the 5 deep on-chain truth checks (`verify_arbitrage`, `check_token_safety`, `get_best_route`, `verify_quote_fairness`, `get_trade_depth`), configure a dedicated hot wallet that pays per call in USDC via x402:
 
-### OpenCode V2
+1. **Create a Dedicated Hot Wallet**:
+   - Create a brand new wallet in MetaMask, Rabby, or via `cast wallet new`.
+   - ⚠️ **SECURITY WARNING**: Never use your primary personal wallet, cold storage, or vault.
+2. **Fund the Wallet on Base (EIP-155:8453)**:
+   - **USDC**: Transfer $2 to $10 of USDC on Base (the bridge pays per call: $0.03 to $0.10).
+   - **Gas (ETH on Base)**: Transfer ~$0.50 worth of ETH on Base for minimal gas allowances if needed.
+3. **Configure Environment Variables in Your MCP Client**:
+   - Set `EVM_PRIVATE_KEY` to the 64-character private key of the hot wallet.
+   - Set safety caps `MAX_PAYMENT_USD` (e.g., `"0.25"`) and `MAX_DAILY_USD` (e.g., `"1.00"`).
 
-`opencode.jsonc`, or the global `~/.config/opencode/opencode.jsonc`:
+**Paid Configuration Block (Claude Desktop, Cursor, Cline, Windsurf)**:
+```json
+{
+  "mcpServers": {
+    "verify402": {
+      "command": "npx",
+      "args": ["-y", "verify402-mcp"],
+      "env": {
+        "VERIFY402_URL": "https://verify402.onrender.com",
+        "EVM_PRIVATE_KEY": "0xYOUR_HOT_WALLET_PRIVATE_KEY",
+        "MAX_PAYMENT_USD": "0.25",
+        "MAX_DAILY_USD": "1.00",
+        "VERIFY402_NETWORKS": "eip155:8453",
+        "VERIFY402_PAY_TO": "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb"
+      }
+    }
+  }
+}
+```
 
+### OpenCode V2 Configuration
+In `opencode.jsonc` (or `~/.config/opencode/opencode.jsonc`):
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
@@ -120,14 +121,12 @@ them.
     "servers": {
       "verify402": {
         "type": "local",
-        "command": [
-          "npx",
-          "-y",
-          "--package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz",
-          "verify402-mcp"
-        ],
+        "command": ["npx", "-y", "verify402-mcp"],
         "environment": {
-          "VERIFY402_URL": "https://verify402.onrender.com"
+          "VERIFY402_URL": "https://verify402.onrender.com",
+          "EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}",
+          "MAX_PAYMENT_USD": "0.25",
+          "MAX_DAILY_USD": "1.00"
         }
       }
     }
@@ -135,9 +134,22 @@ them.
 }
 ```
 
-For paid tools, add `"EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}"` to
-`environment` and export the key in the environment that starts OpenCode. Keep
-the secret out of the config file.
+---
+
+## How AI Agents Use verify402 (Prompt Examples)
+
+Once configured, your agent automatically sees the tools in its context. You can prompt it directly:
+
+- **Preflight Gate (Free)**:
+  > *"Before signing this transaction, call `preflight_gate` on the payment request / calldata. If it returns BLOCK, abort and explain why."*
+- **Token Safety / Sellability Check ($0.10, not a code audit)**:
+  > *"Analyze token `0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE` using `check_token_safety`. Is it sellable at a realistic size, what is the round-trip cost, and is the result TRUST / CAUTION / AVOID?"*
+- **Arbitrage Verification ($0.05)**:
+  > *"Use `verify_arbitrage` to verify if there is an arbitrage opportunity between Uniswap V3 and Sushiswap for WETH/USDC on chain 1 at the current block."*
+- **Quote Fairness Audit ($0.05)**:
+  > *"I was offered 0.35 WETH for 1,000 USDC. Run `verify_quote_fairness` to see if this is fair or if I'm overpaying."*
+- **Market Depth & Capacity ($0.05)**:
+  > *"Check `get_trade_depth` for WETH on Uniswap V3 to see how much slippage and impact a $50,000 swap would suffer."*
 
 ## Safety
 
@@ -150,11 +162,13 @@ the secret out of the config file.
   `VERIFY402_NETWORKS`, `VERIFY402_PAY_TO`, and `VERIFY402_RESOURCE_PREFIX`.
   Defaults are Base mainnet and the public verify402 payee.
 - `MAX_PAYMENT_USD` is enforced inside the x402 client, before a signature
-  exists; removing it is a security regression.
+  exists; removing it is a security regression. The caps limit what the bridge
+  can authorize; they do **not** protect a compromised private key.
 - `preflight_gate` is a check, not a guarantee. Read `notChecked`: it does not
   screen recipient reputation or sanctions, audit contracts, simulate full
-  balance deltas, or protect against MEV. It catches the measurable signing
-  mistakes, not every scam.
+  balance deltas, audit the counterparty, scan tool descriptions or responses
+  for prompt injection, or protect against MEV. It catches the measurable
+  signing mistakes, not every scam.
 - Use the [reference executor](https://github.com/a32116150-ctrl/verify402/blob/master/examples/preflight-guard.mjs)
   when you want enforcement rather than advice.
 

package/index.mjs

@@ -32,12 +32,20 @@ import { z } from "zod";
 
 config();
 
+const VERSION = "1.0.3";
 const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;
 const SERVER_URL = process.env.VERIFY402_URL || "https://verify402.onrender.com";
+// Tell the server which client made the call. This is a label, not an identity:
+// it helps separate MCP use from generic HTTP probes without collecting keys or
+// wallet addresses.
+const CLIENT_HEADERS = {
+  "User-Agent": `verify402-mcp/${VERSION}`,
+  "X-Verify402-Client": `mcp/${VERSION}`,
+};
 // Preflight is free, so it does not go through the paying client. Keeping the
 // two clients separate means a misconfigured 402 on a free route can never
 // turn into a signature.
-const freeApi = axios.create({ baseURL: SERVER_URL, timeout: 30_000, maxRedirects: 0 });
+const freeApi = axios.create({ baseURL: SERVER_URL, timeout: 30_000, maxRedirects: 0, headers: CLIENT_HEADERS });
 // Spend guard: the x402 client refuses to SIGN any payment above this, before
 // a signature exists. Enforced inside x402Client (applySpendControls), not by
 // our own request code - so it cannot be bypassed by a caller.
@@ -73,7 +81,7 @@ The bridge signs x402 payments only; it never signs or sends a trade.
   process.exit(0);
 }
 if (process.argv.includes("--version") || process.argv.includes("-v")) {
-  console.log("1.0.2");
+  console.log(VERSION);
   process.exit(0);
 }
 
@@ -103,7 +111,7 @@ async function createPaidClient() {
       `payee=${policy.allowedPayTo} resources=${policy.resourcePrefix} ` +
       `{${policy.paidRoutes.join(",")}}`,
   );
-  const axiosInstance = axios.create({ baseURL: SERVER_URL, timeout: 120_000, maxRedirects: 0 });
+  const axiosInstance = axios.create({ baseURL: SERVER_URL, timeout: 120_000, maxRedirects: 0, headers: CLIENT_HEADERS });
   return wrapAxiosWithPayment(axiosInstance, client);
 }
 
@@ -157,7 +165,7 @@ const DESCRIPTIONS = {
 async function main() {
   const paidApi = PAID_ENABLED ? await createPaidClient() : null;
 
-  const server = new McpServer({ name: "verify402", version: "1.0.2" });
+  const server = new McpServer({ name: "verify402", version: VERSION });
 
   server.tool(
     "preflight_gate",
@@ -221,7 +229,11 @@ async function main() {
           isError: true,
           content: [{
             type: "text",
-            text: `preflight failed${status ? ` (${status})` : ""}: ${JSON.stringify(body ?? e.message)}. Do not sign without a verifiable receipt.`,
+            text: `preflight failed${status ? ` (${status})` : ""}: ${JSON.stringify(body ?? e.message)}. ${
+              status === 503
+                ? "No receipt was issued; stop and retry later."
+                : "Do not sign without a verifiable receipt."
+            }`,
           }],
         };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verify402-mcp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "mcpName": "io.github.a32116150-ctrl/verify402-mcp",
   "description": "MCP server for verify402: a free, fail-closed preflight gate before signing, plus five paid on-chain checks paid per call via x402.",
   "type": "module",