z-zero-mcp-server 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +74 -49
  2. package/dist/api_backend.js +6 -3
  3. package/dist/index.js +31 -8
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -1,80 +1,105 @@
1
1
  # OpenClaw: Z-ZERO AI Agent MCP Server
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- ## The Concept (Tokenized JIT Payments)
6
- 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**.
5
+ ## How It Works
7
6
 
8
- 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.
7
+ 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.
9
8
 
10
- ## Getting Started
9
+ ---
11
10
 
12
- ### 1. Requirements
13
- - **Node.js** (v18+)
14
- - **Git**
15
- - **Z-ZERO Passport Key** (Get yours at [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents))
11
+ ## Quick Install (Recommended)
16
12
 
17
- ### 2. Installation
18
13
  ```bash
19
- git clone https://github.com/openclaw/z-zero-mcp-server.git
20
- cd z-zero-mcp-server
21
- npm install
22
- npx playwright install chromium
23
- npm run build
14
+ npx z-zero-mcp-server
24
15
  ```
25
16
 
26
- ### 3. Integration into AI Tools
27
-
28
- #### Claude Desktop
29
- Add the following to your `~/Library/Application Support/Claude/claude_desktop_config.json`:
17
+ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
30
18
 
31
19
  ```json
32
20
  {
33
21
  "mcpServers": {
34
22
  "openclaw": {
35
- "command": "node",
36
- "args": ["/ABSOLUTE/PATH/TO/z-zero-mcp-server/dist/index.js"],
23
+ "command": "npx",
24
+ "args": ["-y", "z-zero-mcp-server@latest"],
37
25
  "env": {
38
- "Z_ZERO_API_KEY": "your_passport_key_here",
39
- "Z_ZERO_API_BASE_URL": "https://clawcard.store"
26
+ "Z_ZERO_API_KEY": "zk_live_your_passport_key_here"
40
27
  }
41
28
  }
42
29
  }
43
30
  }
44
31
  ```
45
32
 
46
- #### Cursor / IDEs
47
- 1. Go to **Settings** > **Cursor Settings** > **Features** > **MCP**.
48
- 2. Click **+ Add New MCP Server**.
49
- 3. Name: `openclaw`
50
- 4. Type: `command`
51
- 5. Command: `env Z_ZERO_API_KEY=your_passport_key_here node /ABSOLUTE/PATH/TO/z-zero-mcp-server/dist/index.js`
33
+ Get your Passport Key at: **[clawcard.store/dashboard/agents](https://www.clawcard.store/dashboard/agents)**
52
34
 
53
- ## Available Tools
54
- - `list_cards`: View available virtual card aliases and balances.
55
- - `check_balance`: Query a specific card's real-time balance.
56
- - `request_payment_token`: Generate a JIT auth token for a specific amount.
57
- - `execute_payment`: Securely auto-fills checkout URLs and executes the payment.
58
- - `get_deposit_addresses`: Get your unique addresses to top up your balance.
35
+ ---
59
36
 
60
- ## Troubleshooting
37
+ ## Requirements
61
38
 
62
- ### Error: "Z_ZERO_API_KEY is missing"
63
- If your AI Agent reports this error, it means the `Z_ZERO_API_KEY` environment variable is not set correctly in your MCP configuration.
64
- 1. Go to [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents).
65
- 2. Generate or Copy your **Passport Key** (starts with `zk_live_`).
66
- 3. Ensure it is correctly pasted into your `claude_desktop_config.json` or your IDE's MCP settings.
67
- 4. **Restart** your AI Agent (Claude Desktop or IDE) for the changes to take effect.
39
+ - **Node.js v18+** — [nodejs.org](https://nodejs.org)
40
+ - **Passport Key** — starts with `zk_live_`, get it from the dashboard above
41
+
42
+ ---
43
+
44
+ ## Available MCP Tools
45
+
46
+ | Tool | Description |
47
+ |------|-------------|
48
+ | `list_cards` | View your virtual card aliases and balances |
49
+ | `check_balance` | Query a specific card's real-time balance |
50
+ | `get_deposit_addresses` | Get deposit addresses to top up your balance |
51
+ | `request_payment_token` | Generate a JIT auth token for a specific amount |
52
+ | `execute_payment` | Auto-fill checkout form and execute payment |
53
+ | `cancel_payment_token` | Cancel unused token, refund to wallet |
54
+ | `request_human_approval` | Pause and ask human for approval |
55
+
56
+ ---
57
+
58
+ ## REST API Reference
59
+
60
+ The Z-ZERO backend is hosted at `https://www.clawcard.store`. All endpoints require a `Bearer` token using your Passport Key.
61
+
62
+ > ⚠️ **Use the MCP tools above instead of calling REST directly.** If you must call REST, use the exact paths below.
63
+
64
+ ### `GET /api/tokens/cards`
65
+ Returns your card list, balance, and deposit addresses.
66
+ ```bash
67
+ curl -X GET "https://www.clawcard.store/api/tokens/cards" \
68
+ -H "Authorization: Bearer zk_live_your_key"
69
+ ```
70
+
71
+ **Aliases (also work):**
72
+ - `GET /api/v1/cards` ← for agents that guess REST-style paths
73
+
74
+ ### `POST /api/tokens/issue`
75
+ Issue a JIT payment token.
76
+
77
+ ### `POST /api/tokens/resolve`
78
+ Resolve a token to card data (server-side only).
79
+
80
+ ### `POST /api/tokens/burn`
81
+ Burn a used token.
82
+
83
+ ### `POST /api/tokens/cancel`
84
+ Cancel an unused token (refunds balance).
68
85
 
69
86
  ---
70
87
 
71
88
  ## Troubleshooting
72
89
 
73
- ### Error: "Z_ZERO_API_KEY is missing"
74
- This error means your AI Agent (Claude/Cursor) doesn't have your **Passport Key** yet.
75
- 1. Go to [clawcard.store/dashboard/agents](https://clawcard.store/dashboard/agents).
76
- 2. Copy your **Passport Key** (starts with `zk_live_`).
77
- 3. Add it to your config (e.g., `claude_desktop_config.json`) as `Z_ZERO_API_KEY`.
78
- 4. **Restart** your AI Agent (Claude Desktop or IDE).
90
+ ### "Z_ZERO_API_KEY is missing"
91
+ 1. Go to [clawcard.store/dashboard/agents](https://www.clawcard.store/dashboard/agents)
92
+ 2. Copy your Passport Key (starts with `zk_live_`)
93
+ 3. Add it to your config as `Z_ZERO_API_KEY`
94
+ 4. **Restart** Claude Desktop / Cursor
95
+
96
+ ### "Invalid API Key" (401)
97
+ - Double-check you copied the full key (e.g. `zk_live_c0g3l`)
98
+ - Make sure there are no extra spaces or line breaks
99
+
100
+ ### "404 Not Found" on `/api/v1/cards`
101
+ - This is a legacy path alias — it should now work. If not, use `/api/tokens/cards` directly.
102
+
103
+ ---
79
104
 
80
- *Security Note: OpenClaw never stores your Passport Key. It is passed via environment variables and card data exists only in RAM during execution.*
105
+ *Security: OpenClaw never stores your Passport Key. It is passed via environment variables and card data exists only in volatile RAM during execution.*
package/dist/api_backend.js CHANGED
@@ -11,11 +11,11 @@ exports.resolveTokenRemote = resolveTokenRemote;
11
11
  exports.burnTokenRemote = burnTokenRemote;
12
12
  exports.cancelTokenRemote = cancelTokenRemote;
13
13
  exports.refundUnderspendRemote = refundUnderspendRemote;
14
- const API_BASE_URL = process.env.Z_ZERO_API_BASE_URL || "https://clawcard.store";
14
+ const API_BASE_URL = process.env.Z_ZERO_API_BASE_URL || "https://www.clawcard.store";
15
15
  const PASSPORT_KEY = process.env.Z_ZERO_API_KEY || "";
16
16
  if (!PASSPORT_KEY) {
17
17
  console.error("❌ ERROR: Z_ZERO_API_KEY (Passport Key) is missing!");
18
- console.error("🔐 Please get your Passport Key from: https://clawcard.store/dashboard/agents");
18
+ console.error("🔐 Please get your Passport Key from: https://www.clawcard.store/dashboard/agents");
19
19
  console.error("🛠️ Setup: Ensure 'Z_ZERO_API_KEY' is set in your environment variables.");
20
20
  }
21
21
  async function apiRequest(endpoint, method = 'GET', body = null) {
@@ -71,6 +71,9 @@ async function issueTokenRemote(cardAlias, amount, merchant) {
71
71
  });
72
72
  if (!data)
73
73
  return null;
74
+ // Forward API errors (402 insufficient, 429 max cards, etc.)
75
+ if (data.error)
76
+ return data;
74
77
  // Adapt Dashboard API response to MCP expected format
75
78
  return {
76
79
  token: data.token,
@@ -78,7 +81,7 @@ async function issueTokenRemote(cardAlias, amount, merchant) {
78
81
  amount: amount,
79
82
  merchant: merchant,
80
83
  created_at: Date.now(),
81
- ttl_seconds: 1800, // Matching Dashboard TTL
84
+ ttl_seconds: 1800,
82
85
  used: false
83
86
  };
84
87
  }
package/dist/index.js CHANGED
@@ -26,19 +26,32 @@ server.tool("list_cards", "List all available virtual card aliases and their bal
26
26
  content: [{
27
27
  type: "text",
28
28
  text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
29
- "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
29
+ "👉 Please GET your key here: https://www.clawcard.store/dashboard/agents\n" +
30
30
  "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable in your AI tool (Claude Desktop/Cursor) and RESTART the tool."
31
31
  }],
32
32
  isError: true
33
33
  };
34
34
  }
35
+ if (data?.error) {
36
+ return {
37
+ content: [{
38
+ type: "text",
39
+ text: `❌ API ERROR: ${data.message || data.error}\n\nCould not fetch cards. Please verify your Passport Key is correct.`
40
+ }],
41
+ isError: true
42
+ };
43
+ }
35
44
  const cards = data?.cards || [];
45
+ const activeTokens = data?.active_tokens || [];
46
+ const recentTokens = data?.recent_tokens || [];
36
47
  return {
37
48
  content: [
38
49
  {
39
50
  type: "text",
40
51
  text: JSON.stringify({
41
52
  cards,
53
+ active_tokens: activeTokens,
54
+ recent_tokens: recentTokens,
42
55
  note: "Use card aliases to request payment tokens. Never ask for real card numbers.",
43
56
  }, null, 2),
44
57
  },
@@ -59,7 +72,7 @@ server.tool("check_balance", "Check the remaining balance of a virtual card by i
59
72
  content: [{
60
73
  type: "text",
61
74
  text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
62
- "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
75
+ "👉 Please GET your key here: https://www.clawcard.store/dashboard/agents\n" +
63
76
  "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable and RESTART."
64
77
  }],
65
78
  isError: true
@@ -95,7 +108,7 @@ server.tool("get_deposit_addresses", "Get your unique deposit addresses for EVM
95
108
  content: [{
96
109
  type: "text",
97
110
  text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
98
- "👉 Please GET your key here: https://clawcard.store/dashboard/agents\n" +
111
+ "👉 Please GET your key here: https://www.clawcard.store/dashboard/agents\n" +
99
112
  "👉 Then SET it as the 'Z_ZERO_API_KEY' environment variable and RESTART."
100
113
  }],
101
114
  isError: true
@@ -107,7 +120,7 @@ server.tool("get_deposit_addresses", "Get your unique deposit addresses for EVM
107
120
  content: [
108
121
  {
109
122
  type: "text",
110
- 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",
123
+ text: "Failed to retrieve deposit addresses. Please ensure your Z_ZERO_API_KEY (Passport Key) is valid. You can find it at https://www.clawcard.store/dashboard/agents",
111
124
  },
112
125
  ],
113
126
  isError: true,
@@ -158,12 +171,22 @@ server.tool("request_payment_token", "Request a temporary payment token for a sp
158
171
  content: [{
159
172
  type: "text",
160
173
  text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
161
- "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
174
+ "👉 Please GET your key here: https://www.clawcard.store/dashboard/agents"
162
175
  }],
163
176
  isError: true
164
177
  };
165
178
  }
166
179
  if (!token || token.error) {
180
+ // Show actual API error if available (e.g. 429 max cards, 402 insufficient)
181
+ if (token?.message) {
182
+ return {
183
+ content: [{
184
+ type: "text",
185
+ text: `❌ ${token.message}`
186
+ }],
187
+ isError: true,
188
+ };
189
+ }
167
190
  const balanceData = await (0, api_backend_js_1.getBalanceRemote)(card_alias);
168
191
  const balance = balanceData?.balance;
169
192
  return {
@@ -218,7 +241,7 @@ server.tool("execute_payment", "Execute a payment using a temporary token. This
218
241
  content: [{
219
242
  type: "text",
220
243
  text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
221
- "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
244
+ "👉 Please GET your key here: https://www.clawcard.store/dashboard/agents"
222
245
  }],
223
246
  isError: true
224
247
  };
@@ -261,7 +284,7 @@ server.tool("execute_payment", "Execute a payment using a temporary token. This
261
284
  // ============================================================
262
285
  // TOOL 5: Cancel payment token (returns funds to wallet)
263
286
  // ============================================================
264
- server.tool("cancel_payment_token", "Cancel a payment token that has not been used yet. This will cancel the Airwallex card 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.", {
287
+ 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.", {
265
288
  token: zod_1.z
266
289
  .string()
267
290
  .describe("The payment token to cancel"),
@@ -275,7 +298,7 @@ server.tool("cancel_payment_token", "Cancel a payment token that has not been us
275
298
  content: [{
276
299
  type: "text",
277
300
  text: "❌ AUTHENTICATION REQUIRED: Your Z_ZERO_API_KEY (Passport Key) is missing from the MCP configuration.\n\n" +
278
- "👉 Please GET your key here: https://clawcard.store/dashboard/agents"
301
+ "👉 Please GET your key here: https://www.clawcard.store/dashboard/agents"
279
302
  }],
280
303
  isError: true
281
304
  };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "z-zero-mcp-server",
3
- "version": "1.0.4",
4
- "description": "Z-ZERO MCP Server — Secure JIT Virtual Card Payment tools for AI Agents (Claude, AutoGPT, CrewAI) — Real Airwallex Mastercards",
3
+ "version": "1.0.6",
4
+ "description": "Z-ZERO MCP Server — Secure JIT Virtual Card Payment tools for AI Agents (Claude, Cursor, AutoGPT) — Real Single-Use Visa Cards",
5
5
  "main": "dist/index.js",
6
6
  "bin": "dist/index.js",
7
7
  "scripts": {