z-zero-mcp-server 1.0.4 → 1.0.5

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 +2 -2
  3. package/dist/index.js +10 -1
  4. package/package.json +1 -1
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"],
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) {
package/dist/index.js CHANGED
@@ -26,12 +26,21 @@ 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 || [];
36
45
  return {
37
46
  content: [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "z-zero-mcp-server",
3
- "version": "1.0.4",
3
+ "version": "1.0.5",
4
4
  "description": "Z-ZERO MCP Server — Secure JIT Virtual Card Payment tools for AI Agents (Claude, AutoGPT, CrewAI) — Real Airwallex Mastercards",
5
5
  "main": "dist/index.js",
6
6
  "bin": "dist/index.js",