x402node-mcp 0.1.0 → 1.0.0

package/README.md

@@ -1,52 +1,62 @@
-# x402-mcp
+# x402node-mcp
 
-MCP server bringing 100+ x402-paid APIs to AI agents (Claude, Cursor, MCP-aware clients). Auto-discovers tools from CDP Bazaar; handles USDC micropayments on Base.
+An MCP server that drops the entire **cn402.com + x402node.dev** paid-API catalog
+into any MCP client (Claude Desktop, etc.) as two tools. Your agent discovers and
+calls 230+ endpoints; payment is handled automatically over **x402 (USDC on Base)**.
 
-## Features
+- `x402_list_endpoints` — browse the catalog (path, price, category, description), with optional `category` / `query` filters.
+- `x402_call` — call any endpoint by path; auto-pays, capped at `MAX_USDC` per call.
 
-- Auto-discovers x402 endpoints from CDP Bazaar (no hard-coded list)
-- Reads metadata directly from Bazaar (description, schema, pricing)
-- Refreshes every 5 min — new endpoints appear without restart
-- Handles HTTP 402 + USDC payment automatically
-- Multi-chain ready via x402 protocol (Base today; Solana, Polygon, BNB, EVM expansion)
-
-## Install
+## Install (local)
 
 ```bash
-git clone https://github.com/x402node/x402-mcp
-cd x402-mcp
+git clone <this folder>            # or copy it
+cd x402node-mcp
 npm install
-cp .env.example .env
 ```
 
-Edit `.env`: set `X402_PRIVATE_KEY` to a Base EOA with USDC.
-
-## Use with Claude Desktop
-
-Add to `claude_desktop_config.json`:
+Then add to your MCP client config. **Claude Desktop** (`claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
-    "x402-mcp": {
+    "x402node": {
       "command": "node",
-      "args": ["/absolute/path/to/x402-mcp/mcp-server.js"],
-      "env": { "X402_PRIVATE_KEY": "0xYOUR_KEY" }
+      "args": ["/absolute/path/to/x402node-mcp/index.mjs"],
+      "env": {
+        "PRIVATE_KEY": "0xYOUR_BASE_WALLET_KEY",
+        "MAX_USDC": "1.00"
+      }
     }
   }
 }
 ```
 
-## How it works
+## Test it before wiring into a client
+
+```bash
+PRIVATE_KEY=0x... MAX_USDC=0.50 npx @modelcontextprotocol/inspector node index.mjs
+```
+
+The Inspector gives you a UI to call `x402_list_endpoints` and `x402_call` and watch real payments settle.
+
+## Environment
 
-Agent calls tool → HTTP 402 → x402-fetch signs EIP-3009 → CDP Facilitator settles on Base → response returned. Buyer pays no gas.
+| var | required | default | meaning |
+|---|---|---|---|
+| `PRIVATE_KEY` | yes | — | Base wallet private key (`0x` + 64 hex) holding USDC. **Spends real money.** |
+| `MAX_USDC` | no | `1.00` | Hard per-call spend cap (USDC). A call costing more than this is rejected. |
+| `MANIFESTS` | no | cn402 + x402node | Comma-separated manifest URLs to load the catalog from. |
 
-## Links
+## Money / security
 
-- x402 protocol: https://x402.org
-- CDP Bazaar: https://docs.cdp.coinbase.com/x402/bazaar
-- MCP: https://modelcontextprotocol.io
+- The key spends **real USDC on Base** on every `x402_call`. Use a **dedicated low-balance wallet**, not your main one.
+- `MAX_USDC` is your safety cap — set it to the most you want any single call to spend.
+- The key lives only in your local MCP client config and is **never sent anywhere** except to sign x402 payments. It never touches cn402/x402node servers.
 
-## License
+## Publish (optional, for `npx x402node-mcp`)
 
-MIT
+```bash
+npm publish        # then anyone can run:  npx -y x402node-mcp
+```
+After publishing, the Claude Desktop config can use `"command": "npx", "args": ["-y","x402node-mcp"]`.

package/index.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// x402node-mcp — exposes the cn402.com + x402node.dev paid x402 API catalog
+// to any MCP client (Claude Desktop, etc.) as two tools, paying with USDC on Base.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { wrapFetchWithPayment } from "x402-fetch";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+
+// ---- config / env ----
+const PK = process.env.PRIVATE_KEY || "";
+if (!/^0x[0-9a-fA-F]{64}$/.test(PK)) {
+  console.error("[x402node-mcp] FATAL: set PRIVATE_KEY to a Base wallet private key (0x + 64 hex) holding USDC.");
+  process.exit(1);
+}
+const MAX_USDC = parseFloat(process.env.MAX_USDC || "1.00");          // hard per-call spend cap
+const MAX_ATOMIC = BigInt(Math.round(MAX_USDC * 1e6));               // USDC has 6 decimals
+const MANIFEST_URLS = (process.env.MANIFESTS ||
+  "https://api.cn402.com/.well-known/x402-manifest.json,https://api.x402node.dev/.well-known/x402-manifest.json"
+).split(",").map(s => s.trim()).filter(Boolean);
+
+const account = privateKeyToAccount(PK);
+const wallet = createWalletClient({ account, chain: base, transport: http() });
+const pay = wrapFetchWithPayment(fetch, wallet, MAX_ATOMIC);
+
+// ---- build catalog from the live manifests ----
+const catalog = []; // {host, path, method, price, description, category}
+async function loadCatalog() {
+  for (const url of MANIFEST_URLS) {
+    try {
+      const host = new URL(url).host;
+      const r = await fetch(url, { signal: AbortSignal.timeout(8000) });
+      if (!r.ok) { console.error(`[x402node-mcp] ${url} -> HTTP ${r.status}`); continue; }
+      const m = await r.json();
+      const catByPath = {};
+      for (const s of (m.subjects || [])) for (const p of (s.paths || [])) catByPath[p] = s.name;
+      for (const e of (m.endpoints || [])) {
+        catalog.push({
+          host,
+          path: e.path,
+          method: (e.method || "GET").toUpperCase(),
+          price: e.price || "",
+          description: e.description || "",
+          category: catByPath[e.path] || "",
+        });
+      }
+      console.error(`[x402node-mcp] loaded ${(m.endpoints || []).length} endpoints from ${host}`);
+    } catch (err) {
+      console.error(`[x402node-mcp] failed to load ${url}: ${err && err.message}`);
+    }
+  }
+  console.error(`[x402node-mcp] catalog ready: ${catalog.length} endpoints, per-call cap $${MAX_USDC}`);
+}
+
+// ---- MCP server ----
+const server = new McpServer({ name: "x402node", version: "1.0.0" });
+
+server.registerTool(
+  "x402_list_endpoints",
+  {
+    title: "List x402 endpoints",
+    description:
+      "Discover the paid API endpoints available from cn402.com (Chinese almanac / fortune / I-Ching / TCM / fengshui) and x402node.dev (developer & data tools: on-chain data, crypto, parsing, conversion, text, generation). Returns path, price in USDC, category, host and description. Call this first, then call x402_call with a chosen path. Use the category or query filter to narrow results.",
+    inputSchema: {
+      category: z.string().optional().describe("Filter by category name (case-insensitive substring)"),
+      query: z.string().optional().describe("Free-text filter over path, description and category"),
+    },
+  },
+  async ({ category, query }) => {
+    let rows = catalog;
+    if (category) { const c = category.toLowerCase(); rows = rows.filter(e => e.category.toLowerCase().includes(c)); }
+    if (query) { const q = query.toLowerCase(); rows = rows.filter(e => (e.path + " " + e.description + " " + e.category).toLowerCase().includes(q)); }
+    const endpoints = rows.map(e => ({ path: e.path, method: e.method, price: e.price, category: e.category, host: e.host, description: e.description }));
+    return { content: [{ type: "text", text: JSON.stringify({ count: endpoints.length, endpoints }, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "x402_call",
+  {
+    title: "Call a paid x402 endpoint",
+    description:
+      "Call one of the paid endpoints (find valid paths via x402_list_endpoints). Payment is automatic: USDC on Base, signed with the configured wallet, capped at MAX_USDC per call. Pass the path exactly as listed (e.g. /chain/tx-decode). Put GET parameters in `query`; put POST data in `body`.",
+    inputSchema: {
+      path: z.string().describe("Endpoint path exactly as listed, e.g. /chain/tx-decode or /almanac"),
+      method: z.enum(["GET", "POST"]).optional().describe("Override HTTP method (defaults to the catalog method, usually GET)"),
+      query: z.record(z.string()).optional().describe("Query-string parameters as key/value pairs"),
+      body: z.any().optional().describe("JSON body for POST endpoints"),
+    },
+  },
+  async ({ path, method, query, body }) => {
+    const hits = catalog.filter(e => e.path === path);
+    if (hits.length === 0) {
+      return { content: [{ type: "text", text: `Unknown path "${path}". Call x402_list_endpoints to see valid paths.` }], isError: true };
+    }
+    const e = hits[0];
+    const m = (method || e.method || "GET").toUpperCase();
+    let url = `https://${e.host}${path}`;
+    if (query && Object.keys(query).length) {
+      url += (url.includes("?") ? "&" : "?") + new URLSearchParams(query).toString();
+    }
+    const opts = { method: m };
+    if (m === "POST") { opts.headers = { "content-type": "application/json" }; opts.body = JSON.stringify(body ?? {}); }
+    try {
+      const res = await pay(url, opts);
+      const text = await res.text();
+      let out; try { out = JSON.parse(text); } catch { out = text; }
+      return { content: [{ type: "text", text: typeof out === "string" ? out : JSON.stringify(out, null, 2) }] };
+    } catch (err) {
+      const msg = (err && err.message) || String(err);
+      return { content: [{ type: "text", text: `Request/payment failed for ${m} ${url}: ${msg}. Endpoint price is ${e.price}; if this was a spend-cap error, raise MAX_USDC.` }], isError: true };
+    }
+  }
+);
+
+await loadCatalog();
+await server.connect(new StdioServerTransport());
+console.error("[x402node-mcp] ready on stdio");

package/package.json

@@ -1,54 +1,16 @@
 {
   "name": "x402node-mcp",
-  "version": "0.1.0",
-  "description": "MCP server that exposes x402 paid APIs as Model Context Protocol tools. Auto-discovers endpoints from the Coinbase Bazaar registry and handles USDC payments on Base mainnet transparently.",
+  "version": "1.0.0",
+  "description": "MCP server exposing the cn402.com + x402node.dev x402 paid-API catalog (Chinese almanac/fortune + developer & data tools) to AI agents, with automatic USDC-on-Base payment.",
   "type": "module",
-  "main": "mcp-server.js",
-  "bin": {
-    "x402node-mcp": "./mcp-server.js"
-  },
-  "files": [
-    "mcp-server.js",
-    "test-client.mjs",
-    ".env.example",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "start": "node mcp-server.js",
-    "test": "node test-client.mjs"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "x402",
-    "usdc",
-    "base",
-    "coinbase",
-    "payment",
-    "agent",
-    "claude",
-    "anthropic",
-    "ai-agent",
-    "stablecoin"
-  ],
-  "author": "CKING LLC",
+  "bin": { "x402node-mcp": "index.mjs" },
+  "files": ["index.mjs", "README.md"],
+  "engines": { "node": ">=18" },
   "license": "MIT",
-  "homepage": "https://github.com/x402node/x402-mcp#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/x402node/x402-mcp.git"
-  },
-  "bugs": {
-    "url": "https://github.com/x402node/x402-mcp/issues"
-  },
-  "engines": {
-    "node": ">=18"
-  },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "dotenv": "^17.4.2",
-    "viem": "^2.51.0",
-    "x402-fetch": "^1.2.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "x402-fetch": "^1.1.0",
+    "viem": "^2.21.0",
+    "zod": "^3.25.0"
   }
 }

package/.env.example

@@ -1,4 +0,0 @@
-X402_PRIVATE_KEY=0x_replace_with_your_64hex_private_key
-BASE_RPC_URL=https://mainnet.base.org
-X402_MAX_PRICE_USD=0.5
-X402_REFRESH_MIN=5

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 x402node
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/mcp-server.js

@@ -1,146 +0,0 @@
-#!/usr/bin/env node
-import "dotenv/config";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { privateKeyToAccount } from "viem/accounts";
-import { createWalletClient, http } from "viem";
-import { base } from "viem/chains";
-import { wrapFetchWithPayment } from "x402-fetch";
-
-const PAY_TO = process.env.X402_PAY_TO || "0x4466d4A84b7c49a6A094ec6eef4a0712D6dd125e";
-const PRIVATE_KEY = process.env.X402_PRIVATE_KEY;
-const RPC_URL = process.env.BASE_RPC_URL || "https://mainnet.base.org";
-const MAX_PRICE_USD = parseFloat(process.env.X402_MAX_PRICE_USD || "0.5");
-const REFRESH_MIN = parseInt(process.env.X402_REFRESH_MIN || "5");
-
-if (!PRIVATE_KEY) {
-  console.error("ERROR: Set X402_PRIVATE_KEY in environment");
-  process.exit(1);
-}
-
-const DISCOVERY = `https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=${PAY_TO}`;
-
-const account = privateKeyToAccount(PRIVATE_KEY);
-const wallet = createWalletClient({ account, chain: base, transport: http(RPC_URL) });
-const payFetch = wrapFetchWithPayment(fetch, wallet, BigInt(Math.floor(MAX_PRICE_USD * 1e6)));
-
-async function loadResources() {
-  const all = [];
-  let offset = 0;
-  const limit = 100;
-  while (true) {
-    const r = await fetch(`${DISCOVERY}&limit=${limit}&offset=${offset}`);
-    if (!r.ok) throw new Error(`Bazaar HTTP ${r.status}`);
-    const j = await r.json();
-    const items = j.resources || [];
-    all.push(...items);
-    const total = j.pagination?.total || items.length;
-    if (offset + items.length >= total || items.length === 0) break;
-    offset += items.length;
-  }
-  return all;
-}
-
-function pathToToolName(resourceUrl) {
-  const u = new URL(resourceUrl);
-  const site = u.hostname.replace(/^api\./, "").replace(/\.(dev|com|net|io)$/, "").replace(/[^a-z0-9]/gi, "");
-  const path = u.pathname.replace(/^\/+/, "").replace(/\//g, "_");
-  return `${site}_${path}`.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 60);
-}
-
-function resourceToTool(resource) {
-  const accept = (resource.accepts && resource.accepts[0]) || {};
-  const bazaar = (accept.extensions && accept.extensions.bazaar && accept.extensions.bazaar.info) || {};
-  const input = bazaar.input || {};
-  const queryParams = input.queryParams || {};
-  const method = (input.method || "GET").toUpperCase();
-  const priceUsd = accept.amount ? parseInt(accept.amount) / 1e6 : null;
-  const priceStr = priceUsd !== null ? `$${priceUsd.toFixed(4)} USDC` : "unknown";
-
-  const props = {};
-  const required = [];
-  for (const [k, desc] of Object.entries(queryParams)) {
-    props[k] = { type: "string", description: String(desc) };
-    if (/required/i.test(String(desc))) required.push(k);
-  }
-
-  const name = pathToToolName(resource.resource);
-  const desc = (accept.description || resource.resource).slice(0, 500);
-
-  return {
-    name,
-    description: `${desc}\n\nPrice: ${priceStr} on Base (auto-paid in USDC).`,
-    inputSchema: { type: "object", properties: props, required },
-    _resource: resource.resource,
-    _method: method,
-    _priceUsd: priceUsd,
-  };
-}
-
-const server = new Server({ name: "x402-cn402-x402node", version: "0.1.0" }, { capabilities: { tools: {} } });
-
-let TOOLS = [];
-let TOOL_MAP = {};
-
-async function refreshTools() {
-  try {
-    const resources = await loadResources();
-    const tools = resources.map(resourceToTool);
-    const seen = new Set();
-    TOOLS = tools.filter(t => {
-      if (seen.has(t.name)) return false;
-      seen.add(t.name);
-      return true;
-    });
-    TOOL_MAP = Object.fromEntries(TOOLS.map(t => [t.name, t]));
-    console.error(`[mcp] loaded ${TOOLS.length} tools from Bazaar (payTo=${PAY_TO})`);
-  } catch (e) {
-    console.error(`[mcp] refresh failed: ${e.message}`);
-  }
-}
-
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: TOOLS.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
-}));
-
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
-  const tool = TOOL_MAP[req.params.name];
-  if (!tool) {
-    return { content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }], isError: true };
-  }
-  if (tool._priceUsd !== null && tool._priceUsd > MAX_PRICE_USD) {
-    return { content: [{ type: "text", text: `Tool costs $${tool._priceUsd} > max $${MAX_PRICE_USD}` }], isError: true };
-  }
-  const url = new URL(tool._resource);
-  const args = req.params.arguments || {};
-  try {
-    let resp;
-    if (tool._method === "GET") {
-      for (const [k, v] of Object.entries(args)) {
-        if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
-      }
-      resp = await payFetch(url.toString());
-    } else {
-      resp = await payFetch(url.toString(), {
-        method: tool._method,
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(args),
-      });
-    }
-    const text = await resp.text();
-    if (resp.status !== 200) {
-      return { content: [{ type: "text", text: `HTTP ${resp.status}: ${text.slice(0, 800)}` }], isError: true };
-    }
-    return { content: [{ type: "text", text }] };
-  } catch (e) {
-    return { content: [{ type: "text", text: `x402 call failed: ${e.message}` }], isError: true };
-  }
-});
-
-await refreshTools();
-setInterval(refreshTools, REFRESH_MIN * 60 * 1000);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error("[mcp] x402-cn402-x402node MCP server ready on stdio");

package/test-client.mjs

@@ -1,21 +0,0 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-
-const transport = new StdioClientTransport({
-  command: "node",
-  args: ["mcp-server.js"],
-});
-
-const client = new Client({ name: "test", version: "1.0.0" }, { capabilities: {} });
-await client.connect(transport);
-console.log("Connected.");
-
-const tools = await client.listTools();
-console.log("Tool count:", tools.tools.length);
-
-console.log("\nCalling x402node_dev_uuid...");
-const result = await client.callTool({ name: "x402node_dev_uuid", arguments: {} });
-console.log("Result:", JSON.stringify(result, null, 2));
-
-await client.close();
-process.exit(0);