z-zero-mcp-server 1.0.2 → 1.0.3

package/dist/api_backend.d.ts

@@ -0,0 +1,22 @@
+import type { CardData } from "./types.js";
+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 getDepositAddressesRemote(): Promise<{
+    evm: string;
+    tron: string;
+} | null>;
+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<{
+    success: boolean;
+    refunded_amount: number;
+}>;
+export declare function refundUnderspendRemote(token: string, actualSpent: number): Promise<void>;

package/dist/api_backend.js

@@ -0,0 +1,111 @@
+"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("❌ Missing Z_ZERO_API_KEY (Your Passport) in environment variables.");
+}
+async function apiRequest(endpoint, method = 'GET', body = null) {
+    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 null;
+        }
+        return await res.json();
+    }
+    catch (err) {
+        console.error(`[NETWORK ERROR] ${endpoint}:`, err.message);
+        return null;
+    }
+}
+async function listCardsRemote() {
+    const data = await apiRequest('/api/tokens/cards', 'GET');
+    return data?.cards || [];
+}
+async function getBalanceRemote(cardAlias) {
+    const cards = await listCardsRemote();
+    const card = cards.find(c => c.alias === cardAlias);
+    if (!card)
+        return null;
+    return { balance: card.balance, currency: card.currency };
+}
+async function getDepositAddressesRemote() {
+    const data = await apiRequest('/api/tokens/cards', 'GET');
+    return data?.deposit_addresses || null;
+}
+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 });
+    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

@@ -7,7 +7,7 @@ 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
@@ -20,7 +20,7 @@ const server = new mcp_js_1.McpServer({
 // 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 cards = await (0, api_backend_js_1.listCardsRemote)();
     return {
         content: [
             {
@@ -41,7 +41,7 @@ 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);
+    const balance = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
     if (!balance) {
         return {
             content: [
@@ -63,6 +63,45 @@ server.tool("check_balance", "Check the remaining balance of a virtual card by i
     };
 });
 // ============================================================
+// 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 () => {
+    const addresses = await (0, api_backend_js_1.getDepositAddressesRemote)();
+    if (!addresses) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Failed to retrieve deposit addresses. Please ensure your API key (passport) is valid.",
+                },
+            ],
+            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 real JIT card)
 // ============================================================
 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.", {
@@ -78,9 +117,9 @@ 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);
+    const token = await (0, api_backend_js_1.issueTokenRemote)(card_alias, amount, merchant);
     if (!token) {
-        const balance = await (0, supabase_backend_js_1.getBalanceRemote)(card_alias);
+        const balance = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
         return {
             content: [
                 {
@@ -127,7 +166,7 @@ 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);
+    const cardData = await (0, api_backend_js_1.resolveTokenRemote)(token);
     if (!cardData) {
         return {
             content: [
@@ -142,10 +181,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,7 +213,7 @@ 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);
+    const result = await (0, api_backend_js_1.cancelTokenRemote)(token);
     if (!result.success) {
         return {
             content: [
@@ -244,6 +283,55 @@ 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() {

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/supabase_backend.d.ts

@@ -12,6 +12,10 @@ export declare function getBalanceRemote(cardAlias: string): Promise<{
     balance: number;
     currency: string;
 } | null>;
+export declare function getDepositAddressesRemote(): Promise<{
+    evm: string;
+    tron: 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<{

package/dist/supabase_backend.js

@@ -8,6 +8,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listCardsRemote = listCardsRemote;
 exports.getBalanceRemote = getBalanceRemote;
+exports.getDepositAddressesRemote = getDepositAddressesRemote;
 exports.issueTokenRemote = issueTokenRemote;
 exports.resolveTokenRemote = resolveTokenRemote;
 exports.cancelTokenRemote = cancelTokenRemote;
@@ -21,10 +22,18 @@ const crypto_1 = __importDefault(require("crypto"));
 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");
+let supabase = null;
+if (SUPABASE_URL && SUPABASE_ANON_KEY) {
+    try {
+        supabase = (0, supabase_js_1.createClient)(SUPABASE_URL, SUPABASE_ANON_KEY);
+    }
+    catch (err) {
+        console.error("Failed to initialize Supabase client:", err);
+    }
+}
+else {
+    console.error("⚠️ Supabase backend is disabled (Missing Z_ZERO_SUPABASE_URL/ANON_KEY).");
 }
-const supabase = (0, supabase_js_1.createClient)(SUPABASE_URL, SUPABASE_ANON_KEY);
 // ============================================================
 // AIRWALLEX CONFIG
 // ============================================================
@@ -107,6 +116,24 @@ async function getBalanceRemote(cardAlias) {
         return null;
     return { balance: info.walletBalance, currency: "USD" };
 }
+async function getDepositAddressesRemote() {
+    const info = await resolveApiKey();
+    if (!info)
+        return null;
+    const { data: wallet, error } = await supabase
+        .from("deposit_wallets")
+        .select("evm_address, tron_address")
+        .eq("user_id", info.userId)
+        .single();
+    if (error || !wallet) {
+        console.error("Deposit wallets not found for user:", info.userId);
+        return null;
+    }
+    return {
+        evm: wallet.evm_address,
+        tron: wallet.tron_address,
+    };
+}
 async function issueTokenRemote(cardAlias, amount, merchant, ttlSeconds = 1800 // 30 minutes default
 ) {
     // 1. Validate business rules

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "z-zero-mcp-server",
-    "version": "1.0.2",
+    "version": "1.0.3",
     "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",