z-zero-mcp-server 1.0.2 → 1.0.4

package/README.md

@@ -1,53 +1,80 @@
-# Z-ZERO: AI Virtual Card MCP Server
+# OpenClaw: Z-ZERO AI Agent MCP Server
 
-A Zero-Trust Payment Protocol built specifically for AI Agents utilizing the Model Context Protocol (MCP).
+A Zero-Trust Payment Protocol built specifically for AI Agents utilizing the Model Context Protocol (MCP). Use this to give your local agents (Claude, Cursor, AutoGPT) the power to make real-world purchases securely.
 
 ## The Concept (Tokenized JIT Payments)
 This MCP server acts as an "Invisible Bridge" for your AI Agents. Instead of giving your LLM direct access to a 16-digit credit card number (which triggers safety filters and risks prompt injection theft), the AI only handles **temporary, single-use tokens**.
 
-The local MCP client resolves the token securely in RAM, injects the real card data directly into the payment form (via Playwright headless browser), and clicks "Pay". The virtual card and token are burned milliseconds later.
-
-## Features
-- **Zero PII (Blind Execution):** AI never sees card numbers.
-- **Exact-Match Funding:** Tokens are tied to virtual cards locked to the exact requested amount.
-- **Phantom Burn:** Single-use architecture. Cards self-destruct after checking out.
-- **Stripe/HTML Form Injection:** Automatically fills common checkout domains.
-
-## Documentation
-Check the `docs/` folder for complete system design and architecture:
-- [Product Plan & Core Concept](docs/ai_card_product_plan.md)
-- [MCP Implementation Plan](docs/implementation_plan.md)
-- [Mock Backend Architecture](docs/backend_architecture.md)
-- [Live Demo Walkthrough & Test Results](docs/walkthrough.md)
+The local MCP client resolves the token securely in RAM, injects the real card data directly into the payment form (via Playwright), and clicks "Pay". The virtual card and token are burned milliseconds later.
 
 ## Getting Started
 
-### 1. Install Dependencies
+### 1. Requirements
+- **Node.js** (v18+)
+- **Git**
+- **Z-ZERO Passport Key** (Get yours at [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents))
+
+### 2. Installation
 ```bash
+git clone https://github.com/openclaw/z-zero-mcp-server.git
+cd z-zero-mcp-server
 npm install
 npx playwright install chromium
-```
-
-### 2. Build the Server
-```bash
 npm run build
 ```
 
-### 3. Usage with Claude Desktop
-Add this to your `mcp_config.json`:
+### 3. Integration into AI Tools
+
+#### Claude Desktop
+Add the following to your `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
 ```json
 {
   "mcpServers": {
-    "ai-card-mcp": {
+    "openclaw": {
       "command": "node",
-      "args": ["/absolute/path/to/ai-card-mcp/dist/index.js"]
+      "args": ["/ABSOLUTE/PATH/TO/z-zero-mcp-server/dist/index.js"],
+      "env": {
+        "Z_ZERO_API_KEY": "your_passport_key_here",
+        "Z_ZERO_API_BASE_URL": "https://clawcard.store"
+      }
     }
   }
 }
 ```
 
-## Available MCP Tools
-- `list_cards`: View available virtual cards and balances.
+#### Cursor / IDEs
+1. Go to **Settings** > **Cursor Settings** > **Features** > **MCP**.
+2. Click **+ Add New MCP Server**.
+3. Name: `openclaw`
+4. Type: `command`
+5. Command: `env Z_ZERO_API_KEY=your_passport_key_here node /ABSOLUTE/PATH/TO/z-zero-mcp-server/dist/index.js`
+
+## Available Tools
+- `list_cards`: View available virtual card aliases and balances.
 - `check_balance`: Query a specific card's real-time balance.
-- `request_payment_token`: Generate a JIT auth token locked to a specific amount.
-- `execute_payment`: Passes the token to the Playwright bridge to auto-fill the checkout URL and burn the token.
+- `request_payment_token`: Generate a JIT auth token for a specific amount.
+- `execute_payment`: Securely auto-fills checkout URLs and executes the payment.
+- `get_deposit_addresses`: Get your unique addresses to top up your balance.
+
+## Troubleshooting
+
+### Error: "Z_ZERO_API_KEY is missing"
+If your AI Agent reports this error, it means the `Z_ZERO_API_KEY` environment variable is not set correctly in your MCP configuration.
+1.  Go to [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents).
+2.  Generate or Copy your **Passport Key** (starts with `zk_live_`).
+3.  Ensure it is correctly pasted into your `claude_desktop_config.json` or your IDE's MCP settings.
+4.  **Restart** your AI Agent (Claude Desktop or IDE) for the changes to take effect.
+
+---
+
+## Troubleshooting
+
+### Error: "Z_ZERO_API_KEY is missing"
+This error means your AI Agent (Claude/Cursor) doesn't have your **Passport Key** yet. 
+1. Go to [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents).
+2. Copy your **Passport Key** (starts with `zk_live_`).
+3. Add it to your config (e.g., `claude_desktop_config.json`) as `Z_ZERO_API_KEY`.
+4. **Restart** your AI Agent (Claude Desktop or IDE).
+
+*Security Note: OpenClaw never stores your Passport Key. It is passed via environment variables and card data exists only in RAM during execution.*

package/dist/api_backend.d.ts

@@ -0,0 +1,9 @@
+import type { CardData } from "./types.js";
+export declare function listCardsRemote(): Promise<any>;
+export declare function getBalanceRemote(cardAlias: string): Promise<any>;
+export declare function getDepositAddressesRemote(): Promise<any>;
+export declare function issueTokenRemote(cardAlias: string, amount: number, merchant: string): Promise<any | null>;
+export declare function resolveTokenRemote(token: string): Promise<CardData | null>;
+export declare function burnTokenRemote(token: string, receipt_id?: string): Promise<boolean>;
+export declare function cancelTokenRemote(token: string): Promise<any>;
+export declare function refundUnderspendRemote(token: string, actualSpent: number): Promise<void>;

package/dist/api_backend.js

@@ -0,0 +1,119 @@
+"use strict";
+// Z-ZERO Unified API Backend
+// Connects to the Dashboard Next.js API for all card and token operations.
+// This preserves the "Issuer Abstraction Layer" - the bot never sees direct DB or Banking keys.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCardsRemote = listCardsRemote;
+exports.getBalanceRemote = getBalanceRemote;
+exports.getDepositAddressesRemote = getDepositAddressesRemote;
+exports.issueTokenRemote = issueTokenRemote;
+exports.resolveTokenRemote = resolveTokenRemote;
+exports.burnTokenRemote = burnTokenRemote;
+exports.cancelTokenRemote = cancelTokenRemote;
+exports.refundUnderspendRemote = refundUnderspendRemote;
+const API_BASE_URL = process.env.Z_ZERO_API_BASE_URL || "https://clawcard.store";
+const PASSPORT_KEY = process.env.Z_ZERO_API_KEY || "";
+if (!PASSPORT_KEY) {
+    console.error("❌ ERROR: Z_ZERO_API_KEY (Passport Key) is missing!");
+    console.error("🔐 Please get your Passport Key from: https://clawcard.store/dashboard/agents");
+    console.error("🛠️ Setup: Ensure 'Z_ZERO_API_KEY' is set in your environment variables.");
+}
+async function apiRequest(endpoint, method = 'GET', body = null) {
+    if (!PASSPORT_KEY) {
+        return { error: "AUTH_REQUIRED", message: "Z_ZERO_API_KEY is missing. Human needs to set it in MCP config." };
+    }
+    const url = `${API_BASE_URL.replace(/\/$/, '')}${endpoint}`;
+    try {
+        const res = await fetch(url, {
+            method,
+            headers: {
+                "Authorization": `Bearer ${PASSPORT_KEY}`,
+                "Content-Type": "application/json",
+            },
+            body: body ? JSON.stringify(body) : null,
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            console.error(`[API ERROR] ${endpoint}:`, err.error);
+            return { error: "API_ERROR", message: err.error || res.statusText };
+        }
+        return await res.json();
+    }
+    catch (err) {
+        console.error(`[NETWORK ERROR] ${endpoint}:`, err.message);
+        return { error: "NETWORK_ERROR", message: err.message };
+    }
+}
+async function listCardsRemote() {
+    return await apiRequest('/api/tokens/cards', 'GET');
+}
+async function getBalanceRemote(cardAlias) {
+    const data = await listCardsRemote();
+    if (data?.error)
+        return data;
+    const cards = data?.cards || [];
+    const card = cards.find((c) => c.alias === cardAlias);
+    if (!card)
+        return null;
+    return { balance: card.balance, currency: card.currency };
+}
+async function getDepositAddressesRemote() {
+    return await apiRequest('/api/tokens/cards', 'GET');
+}
+async function issueTokenRemote(cardAlias, amount, merchant) {
+    const data = await apiRequest('/api/tokens/issue', 'POST', {
+        card_alias: cardAlias,
+        amount,
+        merchant,
+        device_fingerprint: `mcp-host-${process.platform}-${process.arch}`,
+        network_id: process.env.NETWORK_ID || "unknown-local-net",
+        session_id: `sid-${Math.random().toString(36).substring(7)}`
+    });
+    if (!data)
+        return null;
+    // Adapt Dashboard API response to MCP expected format
+    return {
+        token: data.token,
+        card_alias: cardAlias,
+        amount: amount,
+        merchant: merchant,
+        created_at: Date.now(),
+        ttl_seconds: 1800, // Matching Dashboard TTL
+        used: false
+    };
+}
+async function resolveTokenRemote(token) {
+    const data = await apiRequest('/api/tokens/resolve', 'POST', { token });
+    if (!data)
+        return null;
+    return {
+        number: data.number,
+        exp_month: data.exp?.split('/')[0] || "12",
+        exp_year: "20" + (data.exp?.split('/')[1] || "30"),
+        cvv: data.cvv || "123",
+        name: data.name || "Z-ZERO AI AGENT"
+    };
+}
+async function burnTokenRemote(token, receipt_id) {
+    const data = await apiRequest('/api/tokens/burn', 'POST', {
+        token,
+        receipt_id,
+        success: true
+    });
+    return !!data;
+}
+async function cancelTokenRemote(token) {
+    const data = await apiRequest('/api/tokens/cancel', 'POST', { token });
+    if (data?.error)
+        return data;
+    return {
+        success: !!data,
+        refunded_amount: data?.refunded_amount || 0
+    };
+}
+async function refundUnderspendRemote(token, actualSpent) {
+    // Underspend is a complex feature that usually happens at the bank level, 
+    // but for JIT tokens, the burn tool in the dashboard could handle this in the future.
+    // Currently we burn the full authorized amount.
+    console.log(`[MCP] Burned token ${token} after spending $${actualSpent}`);
+}

package/dist/index.js

@@ -1,26 +1,38 @@
 #!/usr/bin/env node
 "use strict";
-// Z-ZERO MCP Server (z-zero-mcp-server) v1.0.2
+// OpenClaw MCP Server (z-zero-mcp-server) v1.0.3
 // Exposes secure JIT payment tools to AI Agents via Model Context Protocol
-// Now connected to REAL Airwallex Issuing API — produces real Mastercards
+// Status: Connected to Z-ZERO Gateway — produces secure JIT virtual cards
 Object.defineProperty(exports, "__esModule", { value: true });
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const zod_1 = require("zod");
-const supabase_backend_js_1 = require("./supabase_backend.js");
+const api_backend_js_1 = require("./api_backend.js");
 const playwright_bridge_js_1 = require("./playwright_bridge.js");
 // ============================================================
 // CREATE MCP SERVER
 // ============================================================
 const server = new mcp_js_1.McpServer({
     name: "z-zero-mcp-server",
-    version: "1.0.2",
+    version: "1.0.3",
 });
 // ============================================================
 // TOOL 1: List available cards (safe - no sensitive data)
 // ============================================================
 server.tool("list_cards", "List all available virtual card aliases and their balances. No sensitive data is returned.", {}, async () => {
-    const cards = await (0, supabase_backend_js_1.listCardsRemote)();
+    const data = await (0, api_backend_js_1.listCardsRemote)();
+    if (data?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
+                        "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable in your AI tool (Claude Desktop/Cursor) and RESTART the tool."
+                }],
+            isError: true
+        };
+    }
+    const cards = data?.cards || [];
     return {
         content: [
             {
@@ -41,13 +53,24 @@ server.tool("check_balance", "Check the remaining balance of a virtual card by i
         .string()
         .describe("The alias of the card to check, e.g. 'Card_01'"),
 }, async ({ card_alias }) => {
-    const balance = await (0, supabase_backend_js_1.getBalanceRemote)(card_alias);
-    if (!balance) {
+    const data = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
+    if (data?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
+                        "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable and RESTART."
+                }],
+            isError: true
+        };
+    }
+    if (!data || data.error) {
         return {
             content: [
                 {
                     type: "text",
-                    text: `Card "${card_alias}" not found or API key is invalid. Use list_cards to see available cards.`,
+                    text: `Card "${card_alias}" not found or API issue. Use list_cards to see available cards.`,
                 },
             ],
             isError: true,
@@ -57,15 +80,66 @@ server.tool("check_balance", "Check the remaining balance of a virtual card by i
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ card_alias, ...balance }, null, 2),
+                text: JSON.stringify({ card_alias, ...data }, null, 2),
             },
         ],
     };
 });
 // ============================================================
-// TOOL 3: Request a temporary payment token (issues real JIT card)
+// TOOL 2.5: Get deposit addresses (Phase 14 feature)
 // ============================================================
-server.tool("request_payment_token", "Request a temporary payment token for a specific amount. A real single-use virtual Mastercard is issued via Airwallex. The token is valid for 30 minutes. Min: $1, Max: $100. Use this token with execute_payment to complete a purchase.", {
+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 () => {
+    const data = await (0, api_backend_js_1.getDepositAddressesRemote)();
+    if (data?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
+                        "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable and RESTART."
+                }],
+            isError: true
+        };
+    }
+    const addresses = data?.deposit_addresses;
+    if (!addresses) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Failed to retrieve deposit addresses. Please ensure your Z_ZERO_API_KEY (Passport Key) is valid. You can find it at https://clawcard.store/dashboard/agents",
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    networks: {
+                        evm: {
+                            address: addresses.evm,
+                            supported_chains: ["Base", "BNB Smart Chain (BSC)", "Ethereum"],
+                            tokens: ["USDC", "USDT"]
+                        },
+                        tron: {
+                            address: addresses.tron,
+                            supported_chains: ["Tron (TRC-20)"],
+                            tokens: ["USDT"]
+                        }
+                    },
+                    note: "Funds sent to these addresses will be automatically credited to your Z-ZERO balance within minutes."
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ============================================================
+// 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 30 minutes. Min: $1, Max: $100. Use this token with execute_payment to complete a purchase.", {
     card_alias: zod_1.z
         .string()
         .describe("Which card to charge, e.g. 'Card_01'"),
@@ -78,16 +152,27 @@ server.tool("request_payment_token", "Request a temporary payment token for a sp
         .string()
         .describe("Name or URL of the merchant/service being purchased"),
 }, async ({ card_alias, amount, merchant }) => {
-    const token = await (0, supabase_backend_js_1.issueTokenRemote)(card_alias, amount, merchant);
-    if (!token) {
-        const balance = await (0, supabase_backend_js_1.getBalanceRemote)(card_alias);
+    const token = await (0, api_backend_js_1.issueTokenRemote)(card_alias, amount, merchant);
+    if (token?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
+                }],
+            isError: true
+        };
+    }
+    if (!token || token.error) {
+        const balanceData = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
+        const balance = balanceData?.balance;
         return {
             content: [
                 {
                     type: "text",
-                    text: balance
-                        ? `Insufficient balance. Card "${card_alias}" has $${balance.balance} but you requested $${amount}. Or amount is outside the $1-$100 limit.`
-                        : `Card "${card_alias}" not found or API key is invalid.`,
+                    text: balance !== undefined
+                        ? `Insufficient balance. Card "${card_alias}" has $${balance} but you requested $${amount}. Or amount is outside the $1-$100 limit.`
+                        : `Card "${card_alias}" not found, API key is invalid, or amount limit exceeded.`,
                 },
             ],
             isError: true,
@@ -103,7 +188,7 @@ server.tool("request_payment_token", "Request a temporary payment token for a sp
                     amount: token.amount,
                     merchant: token.merchant,
                     expires_at: expiresAt,
-                    real_card_issued: !!token.airwallex_card_id,
+                    card_issued: true,
                     instructions: "Use this token with execute_payment within 30 minutes. IMPORTANT: If the actual checkout price is HIGHER than the token amount, do NOT proceed — call cancel_payment_token first and request a new token with the correct amount.",
                 }, null, 2),
             },
@@ -127,8 +212,18 @@ server.tool("execute_payment", "Execute a payment using a temporary token. This
         .describe("The actual final amount on the checkout page. If different from token amount, system will auto-refund the difference."),
 }, async ({ token, checkout_url, actual_amount }) => {
     // Step 1: Resolve token → card data (RAM only)
-    const cardData = await (0, supabase_backend_js_1.resolveTokenRemote)(token);
-    if (!cardData) {
+    const cardData = await (0, api_backend_js_1.resolveTokenRemote)(token);
+    if (cardData?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
+                }],
+            isError: true
+        };
+    }
+    if (!cardData || cardData.error) {
         return {
             content: [
                 {
@@ -142,10 +237,10 @@ server.tool("execute_payment", "Execute a payment using a temporary token. This
     // Step 2: Use Playwright to inject card into checkout form
     const result = await (0, playwright_bridge_js_1.fillCheckoutForm)(checkout_url, cardData);
     // Step 3: Burn the token (wallet was pre-debited at issue time)
-    await (0, supabase_backend_js_1.burnTokenRemote)(token);
+    await (0, api_backend_js_1.burnTokenRemote)(token);
     // Step 4: Refund underspend if actual amount was less than token amount
     if (actual_amount !== undefined && result.success) {
-        await (0, supabase_backend_js_1.refundUnderspendRemote)(token, actual_amount);
+        await (0, api_backend_js_1.refundUnderspendRemote)(token, actual_amount);
     }
     // Step 5: Return result (NEVER includes card numbers)
     return {
@@ -174,8 +269,18 @@ server.tool("cancel_payment_token", "Cancel a payment token that has not been us
         .string()
         .describe("Reason for cancellation, e.g. 'Price mismatch: checkout shows $20 but token is $15'"),
 }, async ({ token, reason }) => {
-    const result = await (0, supabase_backend_js_1.cancelTokenRemote)(token);
-    if (!result.success) {
+    const result = await (0, api_backend_js_1.cancelTokenRemote)(token);
+    if (result?.error === "AUTH_REQUIRED") {
+        return {
+            content: [{
+                    type: "text",
+                    text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
+                        "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
+                }],
+            isError: true
+        };
+    }
+    if (!result || !result.success) {
         return {
             content: [
                 {
@@ -244,13 +349,62 @@ server.tool("request_human_approval", "Request human approval before proceeding
     };
 });
 // ============================================================
+// 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)
+
+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. 
+
+## Workflow: The 4-Step Zero-Trust Payment
+When asked to make a purchase, execute the following steps precisely in order:
+
+## 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: 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 30 minutes.
+
+## 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 (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.
+
+## 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.
+`;
+    return {
+        contents: [
+            {
+                uri: "mcp://resources/sop",
+                mimeType: "text/markdown",
+                text: sopContent,
+            }
+        ]
+    };
+});
+// ============================================================
 // START SERVER
 // ============================================================
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
-    console.error("🔐 Z-ZERO MCP Server v1.0.2 running...");
-    console.error("Backend: Supabase + Airwallex Issuing API (Real JIT Cards)");
+    console.error("🔐 OpenClaw MCP Server v1.0.3 running...");
+    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");
 }
 main().catch(console.error);

package/dist/playwright_bridge.js

@@ -13,7 +13,7 @@ async function fillCheckoutForm(checkoutUrl, cardData) {
     const context = await browser.newContext();
     const page = await context.newPage();
     try {
-        await page.goto(checkoutUrl, { waitUntil: "networkidle", timeout: 30000 });
+        await page.goto(checkoutUrl, { waitUntil: "domcontentloaded", timeout: 30000 });
         // ============================================================
         // STRATEGY 1: Standard HTML form fields
         // ============================================================

package/dist/types.d.ts

@@ -7,6 +7,8 @@ export interface VirtualCard {
     name: string;
     balance: number;
     currency: string;
+    error?: string;
+    message?: string;
 }
 export interface PaymentToken {
     token: string;
@@ -16,6 +18,8 @@ export interface PaymentToken {
     created_at: number;
     ttl_seconds: number;
     used: boolean;
+    error?: string;
+    message?: string;
 }
 export interface CardData {
     number: string;
@@ -23,6 +27,8 @@ export interface CardData {
     exp_year: string;
     cvv: string;
     name: string;
+    error?: string;
+    message?: string;
 }
 export interface PaymentResult {
     success: boolean;

package/package.json

@@ -1,13 +1,14 @@
 {
     "name": "z-zero-mcp-server",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "description": "Z-ZERO MCP Server — Secure JIT Virtual Card Payment tools for AI Agents (Claude, AutoGPT, CrewAI) — Real Airwallex Mastercards",
     "main": "dist/index.js",
     "bin": "dist/index.js",
     "scripts": {
         "build": "tsc",
         "start": "node dist/index.js",
-        "dev": "npx tsx src/index.ts"
+        "dev": "npx tsx src/index.ts",
+        "postinstall": "echo 'IMPORTANT: Run \"npx playwright install chromium\" to enable automated checkouts.'"
     },
     "keywords": [
         "mcp",
@@ -28,14 +29,13 @@
     ],
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.12.1",
-        "@supabase/supabase-js": "^2.49.4",
         "dotenv": "^16.5.0",
         "playwright": "^1.52.0",
         "zod": "^3.25.11"
     },
     "devDependencies": {
-        "typescript": "^5.8.3",
+        "@types/node": "^22.15.21",
         "tsx": "^4.19.4",
-        "@types/node": "^22.15.21"
+        "typescript": "^5.8.3"
     }
 }

package/dist/supabase_backend.d.ts

@@ -1,23 +0,0 @@
-import type { CardData, PaymentToken } from "./types.js";
-interface ExtendedToken extends PaymentToken {
-    airwallex_card_id?: string;
-    cancelled?: boolean;
-}
-export declare function listCardsRemote(): Promise<Array<{
-    alias: string;
-    balance: number;
-    currency: string;
-}>>;
-export declare function getBalanceRemote(cardAlias: string): Promise<{
-    balance: number;
-    currency: string;
-} | null>;
-export declare function issueTokenRemote(cardAlias: string, amount: number, merchant: string, ttlSeconds?: number): Promise<ExtendedToken | null>;
-export declare function resolveTokenRemote(tokenId: string): Promise<CardData | null>;
-export declare function cancelTokenRemote(tokenId: string): Promise<{
-    success: boolean;
-    refunded_amount: number;
-}>;
-export declare function burnTokenRemote(tokenId: string): Promise<boolean>;
-export declare function refundUnderspendRemote(tokenId: string, actualSpent: number): Promise<void>;
-export {};

package/dist/supabase_backend.js

@@ -1,326 +0,0 @@
-"use strict";
-// Z-ZERO Supabase Backend v2
-// Connects to real Supabase DB + Airwallex Issuing API for real JIT Mastercards
-// Card data is looked up via Z_ZERO_API_KEY, cards are issued via Airwallex
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.listCardsRemote = listCardsRemote;
-exports.getBalanceRemote = getBalanceRemote;
-exports.issueTokenRemote = issueTokenRemote;
-exports.resolveTokenRemote = resolveTokenRemote;
-exports.cancelTokenRemote = cancelTokenRemote;
-exports.burnTokenRemote = burnTokenRemote;
-exports.refundUnderspendRemote = refundUnderspendRemote;
-const supabase_js_1 = require("@supabase/supabase-js");
-const crypto_1 = __importDefault(require("crypto"));
-// ============================================================
-// SUPABASE CLIENT
-// ============================================================
-const SUPABASE_URL = process.env.Z_ZERO_SUPABASE_URL || process.env.NEXT_PUBLIC_SUPABASE_URL || "";
-const SUPABASE_ANON_KEY = process.env.Z_ZERO_SUPABASE_ANON_KEY || process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY || "";
-const API_KEY = process.env.Z_ZERO_API_KEY || "";
-if (!SUPABASE_URL || !SUPABASE_ANON_KEY) {
-    console.error("❌ Missing Z_ZERO_SUPABASE_URL or Z_ZERO_SUPABASE_ANON_KEY env vars");
-}
-const supabase = (0, supabase_js_1.createClient)(SUPABASE_URL, SUPABASE_ANON_KEY);
-// ============================================================
-// AIRWALLEX CONFIG
-// ============================================================
-const AIRWALLEX_API_KEY = process.env.Z_ZERO_AIRWALLEX_API_KEY || "";
-const AIRWALLEX_CLIENT_ID = process.env.Z_ZERO_AIRWALLEX_CLIENT_ID || "";
-const AIRWALLEX_ENV = process.env.Z_ZERO_AIRWALLEX_ENV || "demo";
-const AIRWALLEX_BASE = AIRWALLEX_ENV === "prod"
-    ? "https://api.airwallex.com/api/v1"
-    : "https://api-demo.airwallex.com/api/v1";
-// Cached auth token for Airwallex (avoids re-login per call)
-let airwallexToken = null;
-let airwallexTokenExpiry = 0;
-async function getAirwallexToken() {
-    if (!AIRWALLEX_API_KEY || !AIRWALLEX_CLIENT_ID)
-        return null;
-    if (airwallexToken && Date.now() < airwallexTokenExpiry)
-        return airwallexToken;
-    try {
-        const res = await fetch(`${AIRWALLEX_BASE}/authentication/login`, {
-            method: "POST",
-            headers: {
-                "x-api-key": AIRWALLEX_API_KEY,
-                "x-client-id": AIRWALLEX_CLIENT_ID,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!res.ok)
-            throw new Error(await res.text());
-        const data = await res.json();
-        airwallexToken = data.token;
-        airwallexTokenExpiry = Date.now() + 25 * 60 * 1000; // 25 min cache
-        return airwallexToken;
-    }
-    catch (err) {
-        console.error("[AIRWALLEX] Auth failed:", err);
-        return null;
-    }
-}
-const tokenStore = new Map();
-// ============================================================
-// RESOLVE API KEY → USER INFO
-// ============================================================
-async function resolveApiKey() {
-    if (!API_KEY)
-        return null;
-    const { data: card, error } = await supabase
-        .from("cards")
-        .select("id, alias, user_id, allocated_limit_usd, is_active")
-        .eq("card_number_encrypted", API_KEY)
-        .eq("is_active", true)
-        .single();
-    if (error || !card) {
-        console.error("API Key not found:", error?.message);
-        return null;
-    }
-    const { data: wallet } = await supabase
-        .from("wallets")
-        .select("balance")
-        .eq("user_id", card.user_id)
-        .single();
-    return {
-        userId: card.user_id,
-        walletBalance: Number(wallet?.balance || 0),
-        cardId: card.id,
-        cardAlias: card.alias,
-    };
-}
-// ============================================================
-// PUBLIC API
-// ============================================================
-async function listCardsRemote() {
-    const info = await resolveApiKey();
-    if (!info)
-        return [];
-    return [{ alias: info.cardAlias, balance: info.walletBalance, currency: "USD" }];
-}
-async function getBalanceRemote(cardAlias) {
-    const info = await resolveApiKey();
-    if (!info || info.cardAlias !== cardAlias)
-        return null;
-    return { balance: info.walletBalance, currency: "USD" };
-}
-async function issueTokenRemote(cardAlias, amount, merchant, ttlSeconds = 1800 // 30 minutes default
-) {
-    // 1. Validate business rules
-    if (amount < 1) {
-        console.error("[ISSUE] Card amount must be at least $1.00");
-        return null;
-    }
-    if (amount > 100) {
-        console.error("[ISSUE] Card amount exceeds $100 maximum limit");
-        return null;
-    }
-    // 2. Resolve user from API key
-    const info = await resolveApiKey();
-    if (!info)
-        return null;
-    if (info.cardAlias !== cardAlias)
-        return null;
-    if (info.walletBalance < amount) {
-        console.error(`[ISSUE] Insufficient balance: $${info.walletBalance} < $${amount}`);
-        return null;
-    }
-    const tokenId = `z_jit_${crypto_1.default.randomBytes(8).toString("hex")}`;
-    // 3. Try to create a REAL Airwallex card
-    let airwallexCardId;
-    const airwallexAuth = await getAirwallexToken();
-    if (airwallexAuth) {
-        try {
-            const expiryTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
-            const payload = {
-                request_id: tokenId,
-                issue_to: "ORGANISATION",
-                name_on_card: "Z-ZERO AI AGENT",
-                form_factor: "VIRTUAL",
-                primary_currency: "USD",
-                valid_to: expiryTime,
-                authorization_controls: {
-                    allowed_transaction_count: "SINGLE",
-                    transaction_limits: {
-                        currency: "USD",
-                        limits: [{ amount, interval: "ALL_TIME" }],
-                    },
-                },
-            };
-            const res = await fetch(`${AIRWALLEX_BASE}/issuing/cards/create`, {
-                method: "POST",
-                headers: {
-                    Authorization: `Bearer ${airwallexAuth}`,
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify(payload),
-            });
-            if (res.ok) {
-                const data = await res.json();
-                airwallexCardId = data.card_id;
-                console.error(`[AIRWALLEX] ✅ Real card issued: ${data.card_id} for $${amount}`);
-            }
-            else {
-                const errText = await res.text();
-                console.error("[AIRWALLEX] Card creation failed:", errText);
-                // Fall through — will still create token but without real card ID
-            }
-        }
-        catch (err) {
-            console.error("[AIRWALLEX] Error creating card:", err);
-        }
-    }
-    else {
-        console.error("[AIRWALLEX] No auth token — running in mock mode");
-    }
-    const token = {
-        token: tokenId,
-        card_alias: cardAlias,
-        amount,
-        merchant,
-        created_at: Date.now(),
-        ttl_seconds: ttlSeconds,
-        used: false,
-        cancelled: false,
-        airwallex_card_id: airwallexCardId,
-    };
-    tokenStore.set(tokenId, token);
-    // 4. Pre-hold the amount in Supabase (deduct immediately, refund on cancel or underspend)
-    const newBalance = info.walletBalance - amount;
-    await supabase
-        .from("wallets")
-        .update({ balance: newBalance })
-        .eq("user_id", info.userId);
-    console.error(`[ISSUE] Token ${tokenId} created. Balance: $${info.walletBalance} → $${newBalance}`);
-    return token;
-}
-async function resolveTokenRemote(tokenId) {
-    const token = tokenStore.get(tokenId);
-    if (!token || token.used || token.cancelled)
-        return null;
-    const age = (Date.now() - token.created_at) / 1000;
-    if (age > token.ttl_seconds) {
-        tokenStore.delete(tokenId);
-        return null;
-    }
-    // Try to fetch REAL card details from Airwallex
-    if (token.airwallex_card_id) {
-        const airwallexAuth = await getAirwallexToken();
-        if (airwallexAuth) {
-            try {
-                const res = await fetch(`${AIRWALLEX_BASE}/issuing/cards/${token.airwallex_card_id}`, {
-                    headers: { Authorization: `Bearer ${airwallexAuth}` },
-                });
-                if (res.ok) {
-                    const data = await res.json();
-                    console.error("[AIRWALLEX] ✅ Real card details fetched.");
-                    return {
-                        number: data.card_number || "4242424242424242",
-                        exp_month: data.expiry_month || "12",
-                        exp_year: data.expiry_year || "2030",
-                        cvv: data.cvv || "123",
-                        name: data.name_on_card || "Z-ZERO AI AGENT",
-                    };
-                }
-            }
-            catch (err) {
-                console.error("[AIRWALLEX] Failed to fetch card details:", err);
-            }
-        }
-    }
-    // Fallback to Stripe test card (demo/sandbox mode)
-    console.error("[AIRWALLEX] ⚠️ Using test card fallback (4242...)");
-    return {
-        number: "4242424242424242",
-        exp_month: "12",
-        exp_year: "2030",
-        cvv: "123",
-        name: "Z-ZERO Agent",
-    };
-}
-async function cancelTokenRemote(tokenId) {
-    const token = tokenStore.get(tokenId);
-    if (!token || token.used || token.cancelled) {
-        return { success: false, refunded_amount: 0 };
-    }
-    // Mark token as cancelled in memory
-    token.cancelled = true;
-    // Cancel the Airwallex card (if one was issued)
-    if (token.airwallex_card_id) {
-        const airwallexAuth = await getAirwallexToken();
-        if (airwallexAuth) {
-            try {
-                await fetch(`${AIRWALLEX_BASE}/issuing/cards/${token.airwallex_card_id}/deactivate`, {
-                    method: "POST",
-                    headers: { Authorization: `Bearer ${airwallexAuth}`, "Content-Type": "application/json" },
-                    body: JSON.stringify({ cancellation_reason: "CANCELLED_BY_USER" }),
-                });
-                console.error(`[AIRWALLEX] Card ${token.airwallex_card_id} cancelled.`);
-            }
-            catch (err) {
-                console.error("[AIRWALLEX] Failed to cancel card:", err);
-            }
-        }
-    }
-    // Refund the held amount back to wallet
-    const info = await resolveApiKey();
-    if (info) {
-        const currentBalanceRes = await supabase
-            .from("wallets")
-            .select("balance")
-            .eq("user_id", info.userId)
-            .single();
-        const currentBalance = Number(currentBalanceRes.data?.balance || 0);
-        await supabase
-            .from("wallets")
-            .update({ balance: currentBalance + token.amount })
-            .eq("user_id", info.userId);
-        console.error(`[CANCEL] Refunded $${token.amount}. New balance: $${currentBalance + token.amount}`);
-    }
-    setTimeout(() => tokenStore.delete(tokenId), 5000);
-    return { success: true, refunded_amount: token.amount };
-}
-async function burnTokenRemote(tokenId) {
-    const token = tokenStore.get(tokenId);
-    if (!token || token.cancelled)
-        return false;
-    token.used = true;
-    // Log the transaction — NOTE: wallet was already debited at issue time
-    const info = await resolveApiKey();
-    if (info) {
-        await supabase.from("transactions").insert({
-            card_id: info.cardId,
-            amount: token.amount,
-            merchant: token.merchant,
-            status: "SUCCESS",
-        });
-    }
-    setTimeout(() => tokenStore.delete(tokenId), 5000);
-    return true;
-}
-// Handle underspend: called when transaction amount < token amount
-async function refundUnderspendRemote(tokenId, actualSpent) {
-    const token = tokenStore.get(tokenId);
-    if (!token)
-        return;
-    const overheld = token.amount - actualSpent;
-    if (overheld <= 0)
-        return;
-    const info = await resolveApiKey();
-    if (!info)
-        return;
-    const currentBalanceRes = await supabase
-        .from("wallets")
-        .select("balance")
-        .eq("user_id", info.userId)
-        .single();
-    const currentBalance = Number(currentBalanceRes.data?.balance || 0);
-    await supabase
-        .from("wallets")
-        .update({ balance: currentBalance + overheld })
-        .eq("user_id", info.userId);
-    console.error(`[REFUND] Underspend refunded: $${overheld} (Spent $${actualSpent} of $${token.amount})`);
-}