z-zero-mcp-server 1.2.0 → 1.2.1

package/README.md

@@ -1,14 +1,47 @@
 # OpenClaw: Z-ZERO AI Agent MCP Server
 
-[![npm](https://img.shields.io/npm/v/z-zero-mcp-server)](https://www.npmjs.com/package/z-zero-mcp-server)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
-[![Built with Tether WDK](https://img.shields.io/badge/Built%20with-Tether%20WDK-00A86B)](https://wdk.tether.to)
+A Zero-Trust Payment Protocol built for AI Agents using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Give your agents (Claude, Cursor, Antigravity) the ability to make real-world purchases — securely, without ever seeing a real card number.
 
-A Zero-Trust Payment Protocol built specifically for AI Agents using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Give your local agents (Claude, Cursor, AntiGravity) the ability to make real-world purchases — securely, without ever seeing a real card number.
+**What makes it different:**
+- 🔐 **Zero-trust** — AI never sees PAN, CVV, or expiry. Card data exists only in RAM, injected via Playwright, then wiped.
+- 🌐 **Web3 + Fiat** — Auto-detects crypto checkout (EIP-681) and routes to on-chain USDT transfer. Falls back to JIT Visa for fiat.
+- 🧠 **Smart Routing** — Cloud Knowledge Base (`get_merchant_hints`) provides platform-specific checkout playbooks for Shopify, Etsy, WooCommerce, and more.
+- 🔄 **Self-Healing** — Failed checkouts are logged via `report_checkout_fail` for admin review, improving future success rates.
+
+---
 
 ## How It Works
 
-Instead of giving your AI direct access to a credit card number, OpenClaw issues **temporary, single-use JIT tokens**. The token is resolved in RAM, Playwright injects the card data directly into the payment form, and the virtual card is burned milliseconds later. Your AI never sees the PAN, CVV, or expiry.
+```mermaid
+sequenceDiagram
+    actor User
+    participant AI as AI Agent
+    participant MCP as MCP Tools
+    participant API as Z-ZERO API
+    participant DB as Supabase DB
+
+    User->>AI: "Buy me this Shopify item"
+    Note over AI: Scans available MCP Tools
+    AI->>MCP: Reads description of auto_pay_checkout
+    MCP-->>AI: "⚠️ MANDATORY: Read mcp://resources/sop first"
+    Note over AI: Fetches SOP before proceeding
+    AI->>MCP: Fetch resource mcp://resources/sop
+    MCP-->>AI: Platform rules + 3-Group payment SOP
+    Note over AI: "Shopify = physical goods. Must collect shipping first."
+    AI->>MCP: get_merchant_hints("_platform_shopify")
+    MCP->>API: GET /api/checkout-hints?domain=_platform_shopify&fields=merchant
+    API->>DB: Query checkout_hints table
+    DB-->>API: Platform hints data
+    API-->>MCP: Returns pre_steps + notes only
+    MCP-->>AI: "Fill shipping form first, click Next..."
+    Note over AI: Navigates checkout, fills shipping, waits for payment page
+    AI->>MCP: request_payment_token(amount, card_alias)
+    MCP-->>AI: Token: temp_auth_XYZ (1hr TTL)
+    AI->>MCP: execute_payment(token, checkout_url)
+    Note over MCP: Playwright auto-fills card form, burns token after use
+    MCP-->>AI: Success — payment complete
+    AI-->>User: "Done! Your Shopify item has been ordered."
+```
 
 ---
 
@@ -47,18 +80,34 @@ Get your Passport Key at: **[clawcard.store/dashboard/agents](https://www.clawca
 
 ## Available MCP Tools
 
+### Group 1 — Wallet Config (Passive)
+
 | Tool | Description |
 |------|-------------|
-| `list_cards` | View your virtual card aliases and balances |
-| `check_balance` | Query a specific card's real-time balance |
-| `get_deposit_addresses` | Get deposit addresses to top up your balance |
-| `request_payment_token` | Generate a JIT auth token for a specific amount |
-| `execute_payment` | Auto-fill checkout form and execute payment |
-| `cancel_payment_token` | Cancel unused token, refund to wallet |
-| `request_human_approval` | Pause and ask human for approval |
-| `set_api_key` | **(Hot-Swap)** Update the Passport Key *without restarting Claude* |
-| `show_api_key_status` | Check if a Passport Key is currently loaded |
-| `check_for_updates` | **(Maintenance)** Check if a new MCP version is available |
+| `list_cards` | List all virtual card aliases and balances |
+| `check_balance` | Check spendable USD balance for a card alias |
+| `get_deposit_addresses` | Get crypto deposit addresses (EVM + Tron) to top up balance |
+| `set_api_key` | Activate a new Passport Key instantly, no restart needed |
+| `show_api_key_status` | Check if a Passport Key is currently loaded (prefix only) |
+
+### Group 2 — Manual 4-Step Payment (Active)
+
+| Tool | Description |
+|------|-------------|
+| `request_payment_token` | Issue a JIT single-use Visa token for a specific amount (1hr TTL) |
+| `execute_payment` | Auto-fill checkout form using a payment token via Playwright |
+| `cancel_payment_token` | Cancel an unused token and refund to wallet |
+| `request_human_approval` | Pause and request human confirmation before proceeding |
+
+### Group 3 — Smart Autopilot
+
+| Tool | Description |
+|------|-------------|
+| `auto_pay_checkout` | Fully autonomous checkout — auto-detects Web3 or Fiat and completes payment |
+| `get_merchant_hints` | Fetch platform-specific checkout playbook (pre-steps + selectors) from Knowledge Base |
+| `report_checkout_fail` | Log a failed checkout URL for admin review (self-healing feedback loop) |
+
+> 📖 **Note:** Version checking is handled automatically in each API call. No separate tool needed.
 
 ---
 

package/dist/index.js

@@ -115,7 +115,7 @@ server.tool("list_cards", "List all available virtual card aliases and their bal
 // ============================================================
 // TOOL 2: Check card balance (safe)
 // ============================================================
-server.tool("check_balance", "Check the wallet balance (human-level total). This is the spendable USD available for issuing new cards. Cards themselves have 'limits' (set at creation), not 'balances' — use list_cards to see active token limits.", {
+server.tool("check_balance", "Check spendable USD balance for a card alias. For active token limits, use list_cards instead.", {
     card_alias: zod_1.z
         .string()
         .describe("The alias of the card to check, e.g. 'Card_01'"),
@@ -155,7 +155,7 @@ server.tool("check_balance", "Check the wallet balance (human-level total). This
 // ============================================================
 // TOOL 2.5: Get deposit addresses (Phase 14 feature)
 // ============================================================
-server.tool("get_deposit_addresses", "Get your unique deposit addresses for EVM networks (Base, BSC, Ethereum) and Tron. Provide these to the human user when they need to add funds to their Z-ZERO balance.", {}, async () => {
+server.tool("get_deposit_addresses", "Get crypto deposit addresses (EVM + Tron) to top up wallet balance.", {}, async () => {
     const data = await getDepositAddressesRemote();
     if (data?.error === "AUTH_REQUIRED") {
         return {
@@ -201,7 +201,7 @@ server.tool("get_deposit_addresses", "Get your unique deposit addresses for EVM
 // ============================================================
 // TOOL 3: Request a temporary payment token (issues secure JIT card)
 // ============================================================
-server.tool("request_payment_token", "Request a temporary payment token for a specific amount. A secure single-use virtual card is issued via the Z-ZERO network. The token is valid for 1 hour. Min: $1, Max: $100. Use this token with execute_payment to complete a purchase.", {
+server.tool("request_payment_token", "⚠️ MANDATORY: Read mcp://resources/sop first. Collect shipping info and check get_merchant_hints before calling. Request a JIT virtual card ($1-$100).", {
     card_alias: zod_1.z
         .string()
         .describe("Which card to charge, e.g. 'Card_01'"),
@@ -274,7 +274,7 @@ server.tool("request_payment_token", "Request a temporary payment token for a sp
 // Agent MUST call this before execute_payment if unsure about a checkout page.
 // Returns domain-specific selectors and pre-steps from Z-ZERO cloud DB.
 // ============================================================
-server.tool("get_merchant_hints", "Fetch checkout hints for a specific domain from the Z-ZERO Knowledge Base. Call this BEFORE execute_payment when the checkout page is unusual, multi-step, or if a previous execute_payment attempt failed. Returns pre_steps (what to click first) and CSS selectors for card fields.", {
+server.tool("get_merchant_hints", "Get merchant navigation flow for a domain or platform key (e.g. '_platform_etsy'). Returns pre_steps (how to navigate checkout) and platform notes. Call BEFORE starting checkout to understand the multi-step flow.", {
     domain: zod_1.z
         .string()
         .describe("The main domain of the checkout page, e.g. 'amazon.com' or 'shopify.com'. Strip 'www.' prefix."),
@@ -282,7 +282,7 @@ server.tool("get_merchant_hints", "Fetch checkout hints for a specific domain fr
     const ZZERO_API = process.env.Z_ZERO_API_BASE || "https://www.clawcard.store";
     const INTERNAL_SECRET = process.env.Z_ZERO_INTERNAL_SECRET || "";
     try {
-        const resp = await fetch(`${ZZERO_API}/api/checkout-hints?domain=${encodeURIComponent(domain)}`, {
+        const resp = await fetch(`${ZZERO_API}/api/checkout-hints?domain=${encodeURIComponent(domain)}&fields=merchant`, {
             headers: {
                 "x-internal-secret": INTERNAL_SECRET,
                 "x-mcp-version": version_js_2.CURRENT_MCP_VERSION,
@@ -304,60 +304,6 @@ server.tool("get_merchant_hints", "Fetch checkout hints for a specific domain fr
     }
 });
 // ============================================================
-// TOOL 4b: Report Checkout Fail (Self-Healing Feedback Loop)
-// Agent calls this when a purchase task could not be completed.
-// Logs the checkout URL for admin review → future hints creation.
-// ============================================================
-server.tool("report_checkout_fail", "Report a checkout URL that you could not complete. Call this when you failed to finish a purchase — for any reason (field not found, bot blocked, timeout, unknown form). The URL will be logged for admin review to improve future checkout success rates. This is part of Z-ZERO's self-healing loop.", {
-    url: zod_1.z
-        .string()
-        .url()
-        .describe("The checkout/payment page URL where the purchase failed."),
-    error_type: zod_1.z
-        .string()
-        .optional()
-        .describe("Short error category: 'field_not_found', 'timeout', 'bot_blocked', 'unknown_form', 'price_mismatch', or 'other'."),
-    error_message: zod_1.z
-        .string()
-        .optional()
-        .describe("Brief description of what went wrong, e.g. 'Could not find card number field' or 'Page redirected to CAPTCHA'."),
-}, async ({ url, error_type, error_message }) => {
-    const ZZERO_API = process.env.Z_ZERO_API_BASE || "https://www.clawcard.store";
-    const INTERNAL_SECRET = process.env.Z_ZERO_INTERNAL_SECRET || "";
-    try {
-        const resp = await fetch(`${ZZERO_API}/api/checkout-hints`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "x-internal-secret": INTERNAL_SECRET,
-                "x-mcp-version": version_js_2.CURRENT_MCP_VERSION,
-            },
-            body: JSON.stringify({
-                url,
-                error_type: error_type || "other",
-                error_message: error_message || null,
-                mcp_version: version_js_2.CURRENT_MCP_VERSION,
-            }),
-        });
-        const data = await resp.json();
-        return {
-            content: [{ type: "text", text: JSON.stringify({
-                        reported: true,
-                        message: "Checkout failure logged. An admin will review this URL to create or update hints for future agents. Thank you for contributing to the self-healing loop.",
-                        ...data,
-                    }, null, 2) }],
-        };
-    }
-    catch (err) {
-        return {
-            content: [{ type: "text", text: JSON.stringify({
-                        reported: false,
-                        message: `Could not reach fail-report API: ${err?.message || "unknown error"}. Please inform the user manually.`,
-                    }, null, 2) }],
-        };
-    }
-});
-// ============================================================
 // TOOL 4b: Execute payment (The "Invisible Hand")
 // ============================================================
 server.tool("execute_payment", "Execute a payment using a temporary token. This tool will securely fill the checkout form on the target website. You will NEVER see the real card number - it is handled securely in the background.", {
@@ -454,7 +400,6 @@ server.tool("execute_payment", "Execute a payment using a temporary token. This
                         message: result.message || "Payment was declined by merchant.",
                         token_status: "ACTIVE",
                         note: "Token NOT burned. Funds will be refunded automatically via webhook within minutes.",
-                        self_heal_hint: "If this failure was caused by the checkout form (wrong selector, unknown iframe, CAPTCHA, etc.), call report_checkout_fail(checkout_url) to help improve future checkouts. Do NOT report if the user cancelled or had insufficient balance.",
                     }, null, 2),
                 },
             ],
@@ -484,7 +429,7 @@ server.tool("execute_payment", "Execute a payment using a temporary token. This
 // ============================================================
 // TOOL 5: Cancel payment token (returns funds to wallet)
 // ============================================================
-server.tool("cancel_payment_token", "Cancel a payment token that has not been used yet. This will cancel the virtual card at the issuing network and refund the full amount back to the wallet. Use this when: (1) checkout price is higher than token amount, (2) purchase is no longer needed, or (3) human requests cancellation. IMPORTANT: Do NOT auto-cancel without human awareness — always inform the human first.", {
+server.tool("cancel_payment_token", "Cancel unused token and refund instantly. Use when user cancels the purchase or to free up a card slot.", {
     token: zod_1.z
         .string()
         .describe("The payment token to cancel"),
@@ -531,7 +476,7 @@ server.tool("cancel_payment_token", "Cancel a payment token that has not been us
 // ============================================================
 // TOOL 6: Request human approval (Human-in-the-loop)
 // ============================================================
-server.tool("request_human_approval", "Request human approval before proceeding with an action that requires human judgment. Use this when: (1) checkout price is higher than token amount and you need authorization for a new token, (2) any unusual or irreversible action is required. This PAUSES the bot and waits for human decision.", {
+server.tool("request_human_approval", "Pause and ask the user for approval before risky actions (price mismatch, large amount, unusual request).", {
     situation: zod_1.z
         .string()
         .describe("Clear description of what the bot found, e.g. 'Checkout shows $20 total (includes $3 tax) but current token is only $15'"),
@@ -574,7 +519,7 @@ server.tool("request_human_approval", "Request human approval before proceeding
 // ============================================================
 // TOOL 6.5: Set API Key (Hot-Swap Passport Key — NO restart needed)
 // ============================================================
-server.tool("set_api_key", "Update the Z-ZERO Passport Key immediately WITHOUT restarting the AI tool. Call this when the human provides a new key (e.g. 'zk_live_xxxxx'). The key is validated and activated instantly for all subsequent API calls. IMPORTANT: Never ask for the key proactively — only call this when the human explicitly provides it.", {
+server.tool("set_api_key", "Activate a new Passport Key instantly, no restart needed. Only call when user explicitly provides a key.", {
     api_key: zod_1.z
         .string()
         .describe("The new Passport Key to activate. Must start with 'zk_live_' or 'zk_test_'. Get from: https://www.clawcard.store/dashboard/agents"),
@@ -601,7 +546,7 @@ server.tool("set_api_key", "Update the Z-ZERO Passport Key immediately WITHOUT r
 // ============================================================
 // TOOL 6.6: Show current API Key status (for debugging)
 // ============================================================
-server.tool("show_api_key_status", "Show whether a Passport Key is currently configured, and its prefix (first 12 chars). Does NOT reveal the full key. Use this to debug authentication issues.", {}, async () => {
+server.tool("show_api_key_status", "Check if Passport Key is configured. Shows prefix only, for debugging.", {}, async () => {
     const key = (0, key_store_js_1.getPassportKey)();
     const hasKey = key.length > 0;
     return {
@@ -618,14 +563,7 @@ server.tool("show_api_key_status", "Show whether a Passport Key is currently con
             }],
     };
 });
-server.tool("auto_pay_checkout", "[Phase 2] Autonomous Smart Routing checkout tool. Provide a checkout URL and this tool will:\n" +
-    "1. Scan the page to detect if it supports Web3 (Crypto) payments via window.ethereum or EIP-681 links.\n" +
-    "2. SCENARIO A (Web3): If detected, automatically send USDT on-chain via WDK (gas ~$0.001). No Visa card needed.\n" +
-    "3. SCENARIO B (Fiat): If no Web3 detected, scan DOM for total price, issue a JIT Visa card for exact amount, auto-fill form.\n" +
-    "WARNING: For PHYSICAL GOODS (Shopify, multi-step checkout), this tool may return PRICE_NOT_FOUND because the final price " +
-    "(including shipping) only appears after filling th shipping info. In that case, use browser tools to navigate manually, " +
-    "call get_merchant_hints to get platform-specific card selectors, fill shipping info first, then call " +
-    "request_payment_token + execute_payment once card fields are visible and the final total is confirmed.", {
+server.tool("auto_pay_checkout", "⚠️ MANDATORY: Read mcp://resources/sop first. Only use on PAYMENT pages where final total is visible. Auto-detects Web3 or Fiat and completes payment. For physical goods (Shopify, Etsy), get_merchant_hints first.", {
     checkout_url: zod_1.z
         .string()
         .url()
@@ -777,82 +715,143 @@ server.tool("auto_pay_checkout", "[Phase 2] Autonomous Smart Routing checkout to
     }
 });
 // ============================================================
+// TOOL: Report a failed checkout URL (Group 3 self-healing feedback)
+// Call when Group 3 navigation was started but could not complete.
+// Triggers: stuck mid pre_steps, bot blocked, selector not found, etc.
+// Does NOT apply to: user cancelled, insufficient balance, price mismatch.
+// ============================================================
+server.tool("report_checkout_fail", "Report a checkout URL that you could not complete. Call this when you failed to finish a purchase — for any reason (field not found, bot blocked, timeout, unknown form). The URL will be logged for admin review to improve future checkout success rates. This is part of Z-ZERO's self-healing loop.", {
+    url: zod_1.z
+        .string()
+        .url()
+        .describe("The checkout/payment page URL where the purchase failed."),
+    error_type: zod_1.z
+        .string()
+        .describe("Short error category: 'field_not_found', 'timeout', 'bot_blocked', 'unknown_form', 'price_mismatch', or 'other'."),
+    error_message: zod_1.z
+        .string()
+        .optional()
+        .describe("Brief description of what went wrong, e.g. 'Could not find card number field' or 'Page redirected to CAPTCHA'."),
+}, async ({ url, error_type, error_message }) => {
+    const ZZERO_API = process.env.Z_ZERO_API_BASE || "https://www.clawcard.store";
+    const INTERNAL_SECRET = process.env.Z_ZERO_INTERNAL_SECRET || "";
+    try {
+        await fetch(`${ZZERO_API}/api/checkout-hints`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-internal-secret": INTERNAL_SECRET,
+                "x-mcp-version": version_js_2.CURRENT_MCP_VERSION,
+            },
+            body: JSON.stringify({ url, error_type, error_message, mcp_version: version_js_2.CURRENT_MCP_VERSION }),
+        });
+    }
+    catch {
+        // Fire-and-forget — never block the agent on a logging call
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({
+                    logged: true,
+                    url,
+                    error_type,
+                    message: "Checkout failure logged. Admin will review and improve hints for this domain.",
+                }, null, 2) }],
+    };
+});
+// ============================================================
 // RESOURCE: Z-ZERO Autonomous Payment SOP
 // ============================================================
 server.resource("Standard Operating Procedure (SOP) for Autonomous Payments", "mcp://resources/sop", {
     description: "A comprehensive guide on how AI agents should use the Z-ZERO tools to execute secure, zero-trust payments."
 }, async (uri) => {
     const sopContent = `
-# Z-ZERO Autonomous Payment Skill SOP (v1.0.0)
+# Z-ZERO Autonomous Payment Skill SOP (v2.0.0)
+
+This SOP tells the AI Agent how to use Z-ZERO tools to autonomously purchase goods on behalf of the user — without ever handling raw credit card data.
+
+---
+
+## Group 1: Wallet Config (READ FIRST)
+
+Tools: \`check_balance\`, \`list_cards\`, \`get_deposit_addresses\`, \`set_api_key\`, \`show_api_key_status\`
+
+Before ANY purchase:
+1. Confirm exactly what the user wants to buy and the expected price (in USD).
+2. Call \`check_balance\` using your default \`card_alias\` to verify sufficient funds.
+   - If balance is insufficient → STOP. Ask the human to deposit USDT to their wallet.
+3. Use \`list_cards\` to see available card aliases, NOT to check spendable balance.
+4. Never ask for the API key proactively — only call \`set_api_key\` when the user explicitly gives you one.
+
+---
+
+## Group 2: Manual 4-Step Payment (Core Flow)
+
+Tools: \`request_payment_token\`, \`execute_payment\`, \`cancel_payment_token\`, \`request_human_approval\`
 
-This skill provides you (the AI Agent) with the capability to autonomously purchase digital goods, APIs, and subscriptions on the internet on behalf of your human user, without ever handling raw credit card data. 
+Execute in this exact order:
 
-## Workflow: The 4-Step Zero-Trust Payment
-When asked to make a purchase, execute the following steps precisely in order:
+### Step 1 — Verify
+Confirm item, price, and check balance (see Group 1).
 
-## Step 1: Verification & Intent
-1. Confirm exactly what the user wants to buy and the total expected price (in USD).
-2. Call Check Balance: Call the \`check_balance\` tool using your default \`card_alias\` to ensure you have sufficient funds.
-   - If balance is insufficient, STOP and ask the human to deposit Crypto into their Z-ZERO Web Dashboard.
+### Step 2 — Navigate to Payment Page
+Use browser tools to navigate to the final payment page where card fields are visible and the FINAL total (including shipping + tax) is displayed.
+- ⛔ DO NOT call \`request_payment_token\` until BOTH conditions are true:
+  1. Shipping/personal info submitted successfully
+  2. Card input fields are visible on screen
 
-## Step 2: Requesting the JIT Token
-1. Request Token: Call the \`request_payment_token\` tool with the exact \`amount\` required and the \`merchant\` name.
-2. Receive Token: You will receive a temporary \`token\` (e.g., \`temp_auth_1a2b...\`). This token is locked to the requested amount and is valid for 1 hour.
+### Step 3 — Request Token
+Call \`request_payment_token\` with exact final amount and merchant name.
+Receive a single-use \`token\` (valid 1 hour, locked to that amount).
 
-## Step 3: Locating the Checkout
-1. Identify Checkout URL: Find the merchant's checkout/payment page where credit card details are normally entered.
-2. Full URL Required: e.g., \`https://checkout.stripe.dev/pay\`.
+### Step 4 — Blind Execution
+Call \`execute_payment\` with the token + checkout URL.
+Z-ZERO opens a headless browser, injects the card securely, clicks Pay. Token burns instantly after success.
 
-## Step 4: Blind Execution (The MCP Bridge)
-1. Execute Payment: Call the \`execute_payment\` tool, passing in:
-   - The \`token\` obtained in Step 2.
-   - The \`checkout_url\` identified in Step 3.
-2. Background Magic: Z-ZERO opens a headless browser, securely injects the real card data directly into the form, and clicks "Pay". 
-3. Burn: The token self-destructs instantly after use.
+### Error Rules
+- NEVER print raw tokens in chat.
+- NO MANUAL ENTRY: If a site asks you to type a card number into a text box — REFUSE.
+- FAIL GRACEFULLY: If \`execute_payment\` returns \`success: false\` → report it. Do NOT retry blindly.
+- PRICE MISMATCH: If actual checkout total > token amount → call \`cancel_payment_token\` + \`request_human_approval\` for new amount.
 
-## Rules & Error Handling
-- NEVER print full tokens in the human chat logs.
-- NO MANUAL ENTRY: If a merchant asks you to type a credit card number into a text box, REFUSE. 
-- FAIL GRACEFULLY: If \`execute_payment\` returns \`success: false\`, report the error message to the human. Do not try again.
+---
 
-## ⚡ Smart Route Alternative (Recommended)
-For most purchases, use \`auto_pay_checkout\` instead of the 4-step flow above.
-It auto-detects Web3 checkout (pay on-chain with USDT) vs Fiat checkout (JIT Visa card), all in a single call.
-- Web3 route: sends USDT directly on-chain to merchant wallet
-- Fiat route: issues JIT card + fills checkout form automatically
-Call \`auto_pay_checkout\` with just \`checkout_url\` and \`card_alias\`. The tool handles the rest.
+## Group 3: Smart Autopilot (Fast Route)
 
-## 🛒 Physical Goods / Multi-Step Checkout
+Tools: \`auto_pay_checkout\`, \`get_merchant_hints\`
 
-For physical goods (clothing, shoes, collectibles, etc.) the final price includes shipping
-and only appears AFTER filling the shipping form. \`auto_pay_checkout\` may return PRICE_NOT_FOUND.
+### Option A — Digital Goods / SaaS / APIs (Use auto_pay_checkout directly)
+For pages where the final total is already visible, call \`auto_pay_checkout\`:
+- It auto-detects Web3 (sends USDT on-chain via WDK) vs Fiat (issues JIT Visa card + auto-fills form).
+- One call handles everything.
 
-### ⛔ Card Issuance Gate — wait for BOTH conditions before calling request_payment_token:
-1. Shipping/personal info has been submitted successfully on this or a previous page
-2. Card input fields (or payment iframe) are visible on the current page
+### Option B — Physical Goods (Shopify, Etsy, WooCommerce)
+⛔ DO NOT call \`auto_pay_checkout\` directly. The final price is only visible AFTER shipping is submitted.
 
-If EITHER is false → DO NOT call \`request_payment_token\`. Keep navigating first.
+Recommended flow:
+1. Call \`get_merchant_hints\` with checkout domain or platform key (e.g. \`_platform_shopify\`).
+   - Returns \`pre_steps\` (navigation instructions) + \`notes\` + \`platform\`.
+2. Follow the \`pre_steps\` — navigate, add to cart, fill shipping form.
+   - Ask user for shipping info via \`request_human_approval\` if not already known.
+3. Wait for payment/card section to appear + FINAL total is visible.
+4. Call \`request_payment_token\` with the exact final amount (Group 2).
+5. Call \`execute_payment\` with token + checkout URL (Group 2).
 
 ### Platform Detection Signals
-| Platform | Signals |
-|----------|---------|
-| Shopify | URL contains /checkouts/, "Powered by Shopify" in footer, cdn.shopify.com scripts |
-| Etsy | URL contains etsy.com/checkout |
-| WooCommerce | /checkout/ URL, woocommerce in body class |
+| Platform | Detection Signal |
+|---|---|
+| Shopify | JS object \`window.Shopify\` exists, OR \`<script src="cdn.shopify.com">\`, OR \`<meta name="shopify-checkout-api-token">\` |
+| Etsy | URL matches \`*.etsy.com\` (any path) |
+| WooCommerce | \`<body class="... woocommerce ...\`>\`, OR script/link tags from \`wp-content/plugins/woocommerce\` |
 
-### Recommended Flow for Physical Goods:
-1. Navigate to product page using browser tools
-2. Select variant (color, size, etc.) → Add to cart → Proceed to checkout
-3. Fill shipping info (ask human via \`request_human_approval\` if not already known)
-4. Wait for payment/card fields section to appear
-5. Call \`get_merchant_hints\` with checkout domain (or \`_platform_shopify\` if Shopify detected)
-6. Read the FINAL total (after shipping + tax — hover over/scroll to order summary)
-7. Call \`request_payment_token\` with exact final amount
-8. Call \`execute_payment\` with token + checkout URL + hints
+### Known Limitations
+- Cloudflare-protected sites (e.g. TeePublic) may block headless browser → inform user.
+- Card fields inside iframes: \`execute_payment\` handles this via \`iframe_selector\` in hints automatically.
 
-### Known Limitations:
-- Some sites use Cloudflare bot detection (e.g. TeePublic) → \`execute_payment\` may be blocked → inform user
-- Card fields in iframes → \`execute_payment\` handles this automatically via \`iframe_selector\` in hints
+### Failure Reporting (Self-Healing Loop)
+If you started Group 3 (called \`get_merchant_hints\` and began following \`pre_steps\`) but CANNOT complete the checkout due to a technical reason:
+→ Call \`report_checkout_fail(url, error_type, error_message)\` before giving up.
+→ Use \`url\` = the page you were on when stuck.
+→ Do NOT call this if user cancelled or balance was insufficient — those are not technical failures.
 `;
     return {
         contents: [
@@ -872,6 +871,6 @@ async function main() {
     await server.connect(transport);
     console.error(`🔐 OpenClaw MCP Server v${version_js_2.CURRENT_MCP_VERSION} running (Phase 2: Smart Routing enabled)...`);
     console.error("Status: Secure & Connected to Z-ZERO Gateway");
-    console.error("Tools: list_cards, check_balance, request_payment_token, execute_payment, cancel_payment_token, request_human_approval, auto_pay_checkout");
+    console.error("Tools: list_cards, check_balance, request_payment_token, execute_payment, cancel_payment_token, request_human_approval, auto_pay_checkout, report_checkout_fail");
 }
 main().catch(console.error);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CURRENT_MCP_VERSION = "1.2.0";
+export declare const CURRENT_MCP_VERSION = "1.1.2";

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CURRENT_MCP_VERSION = void 0;
 // Single source of truth for MCP version
 // Imported by both index.ts and wdk_backend.ts to avoid circular dependency
-exports.CURRENT_MCP_VERSION = "1.2.0";
+exports.CURRENT_MCP_VERSION = "1.1.2";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "z-zero-mcp-server",
-    "version": "1.2.0",
+    "version": "1.2.1",
     "description": "Z-ZERO MCP Server — Secure JIT Virtual Card Payment tools for AI Agents (Claude, Cursor, AutoGPT) — Real Single-Use Visa Cards",
     "main": "dist/index.js",
     "bin": "dist/index.js",