x402-gateway-mcp 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# x402-gateway-mcp
+
+Stdio MCP server that exposes every [x402-gateway](../README.md) data endpoint as an
+MCP tool and **pays for calls with your wallet** (USDC on Base, x402 protocol).
+Tool list is fetched from the gateway's `/.well-known/x402.json` at startup —
+new gateway endpoints appear automatically.
+
+> ⚠️ **Funded-wallet warning:** `WALLET_PRIVATE_KEY` signs real payments. Use a
+> dedicated wallet holding only small balances (a few dollars of USDC). Never
+> your main wallet. The key is read from env, never logged, and payment headers
+> are never echoed into agent-visible output.
+
+## 5-minute setup (Claude Desktop / Claude Code)
+
+1. Create a fresh wallet and fund it with a small amount of USDC on Base
+   (or Base Sepolia test USDC from <https://faucet.circle.com> while testing).
+2. `npm install -g x402-gateway-mcp` (or use `npx`).
+3. Add to your MCP config (Claude Desktop `claude_desktop_config.json`, or
+   `claude mcp add` for Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "x402-gateway": {
+      "command": "npx",
+      "args": ["-y", "x402-gateway-mcp"],
+      "env": {
+        "GATEWAY_URL": "https://<your-gateway-host>",
+        "WALLET_PRIVATE_KEY": "0x<small-balance-wallet-key>",
+        "MAX_PER_CALL_USD": "0.25",
+        "MAX_SESSION_USD": "2.00"
+      }
+    }
+  }
+}
+```
+
+4. Restart the client. Every tool description states its price, e.g.
+   `[costs $0.005 USDC per call] Get the current USD price of a cryptocurrency…`
+
+## Spend guardrails
+
+- `MAX_PER_CALL_USD` (default **0.25**): tools priced above this are refused.
+- `MAX_SESSION_USD` (default **2.00**): cumulative settled spend per server
+  session; calls that would exceed it are refused with a clear message the
+  agent can relay. Restart the server to reset.
+
+Refusals happen **before** any payment is signed.
+
+## Env reference
+
+| Var | Default | Purpose |
+|---|---|---|
+| `GATEWAY_URL` | `https://gateway.stride20k.com` | Gateway base URL (override for local/testnet) |
+| `WALLET_PRIVATE_KEY` | — | Buyer key (small balance!). Without it, tools list but calls fail with a clear error |
+| `MAX_PER_CALL_USD` | `0.25` | Per-call cap |
+| `MAX_SESSION_USD` | `2.00` | Per-session cap |

package/dist/guards.js

@@ -0,0 +1,19 @@
+/** Spend guardrails — pure so they're trivially testable. */
+export function parsePriceUsd(price) {
+    const n = Number(price.replace(/^\$/, ""));
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+/** Returns null when the call may proceed, or a refusal message the agent can relay. */
+export function checkSpend(priceUsd, state, config) {
+    if (priceUsd > config.maxPerCallUsd) {
+        return (`Refused: this tool costs $${priceUsd} per call, above the MAX_PER_CALL_USD cap of ` +
+            `$${config.maxPerCallUsd}. Raise the cap in the MCP server env if this is intended.`);
+    }
+    if (state.sessionSpentUsd + priceUsd > config.maxSessionUsd) {
+        return (`Refused: paying $${priceUsd} would bring this session's spend to ` +
+            `$${(state.sessionSpentUsd + priceUsd).toFixed(3)}, above the MAX_SESSION_USD cap of ` +
+            `$${config.maxSessionUsd}. Session spend so far: $${state.sessionSpentUsd.toFixed(3)}. ` +
+            `Restart the MCP server or raise the cap to continue.`);
+    }
+    return null;
+}

package/dist/index.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * x402-gateway-mcp: stdio MCP server that mirrors the gateway's endpoint
+ * registry as tools and pays per call with a user-supplied wallet.
+ *
+ * On startup it fetches GATEWAY_URL/.well-known/x402.json and registers one
+ * tool per endpoint — new gateway endpoints appear with zero code changes here.
+ *
+ * Env:
+ *   GATEWAY_URL          gateway base URL (default http://localhost:8787)
+ *   WALLET_PRIVATE_KEY   buyer key — SMALL BALANCES ONLY; signs real payments
+ *   MAX_PER_CALL_USD     per-call spend cap (default 0.25)
+ *   MAX_SESSION_USD      session spend cap (default 2.00)
+ *
+ * The private key is never logged; payment headers are never echoed.
+ */
+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 { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+import { checkSpend, parsePriceUsd } from "./guards.js";
+// Canonical production gateway; override with GATEWAY_URL for local/testnet.
+const GATEWAY_URL = (process.env.GATEWAY_URL ?? "https://gateway.stride20k.com").replace(/\/$/, "");
+const spendConfig = {
+    maxPerCallUsd: Number(process.env.MAX_PER_CALL_USD ?? "0.25"),
+    maxSessionUsd: Number(process.env.MAX_SESSION_USD ?? "2.00"),
+};
+const spendState = { sessionSpentUsd: 0 };
+/** "/crypto/price/:coinId" -> "crypto_price" */
+function toolName(route) {
+    return route
+        .split("/")
+        .filter((seg) => seg && !seg.startsWith(":"))
+        .join("_")
+        .replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function buildUrl(endpoint, args) {
+    let path = endpoint.route;
+    const used = new Set();
+    path = path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+        used.add(name);
+        const v = args[name];
+        if (v === undefined)
+            throw new Error(`missing required parameter: ${name}`);
+        return encodeURIComponent(String(v));
+    });
+    const query = new URLSearchParams();
+    for (const [k, v] of Object.entries(args)) {
+        if (!used.has(k) && v !== undefined && v !== null)
+            query.set(k, String(v));
+    }
+    const qs = query.toString();
+    return `${GATEWAY_URL}${path}${qs ? `?${qs}` : ""}`;
+}
+/** Belt-and-braces: strip anything key-shaped from text we return to agents. */
+const redact = (s) => s.replace(/0x[a-fA-F0-9]{64}/g, "0x[REDACTED]");
+async function main() {
+    // Manifest fetch (free route) — tool list derives entirely from it.
+    const manifestRes = await fetch(`${GATEWAY_URL}/.well-known/x402.json`);
+    if (!manifestRes.ok) {
+        console.error(`Failed to fetch gateway manifest from ${GATEWAY_URL}: HTTP ${manifestRes.status}`);
+        process.exit(1);
+    }
+    const manifest = (await manifestRes.json());
+    const byTool = new Map(manifest.endpoints.map((e) => [toolName(e.route), e]));
+    // Paying fetch is built lazily so listing tools works without a wallet.
+    let payingFetch = null;
+    const getPayingFetch = () => {
+        const key = process.env.WALLET_PRIVATE_KEY;
+        if (!key) {
+            throw new Error("WALLET_PRIVATE_KEY is not configured — cannot pay for calls. Set it in the MCP server env (testnet/small balance only).");
+        }
+        if (!payingFetch) {
+            const account = privateKeyToAccount(key);
+            payingFetch = wrapFetchWithPaymentFromConfig(fetch, {
+                schemes: [{ network: "eip155:*", client: new ExactEvmScheme(account) }],
+            });
+        }
+        return payingFetch;
+    };
+    const server = new Server({ name: "x402-gateway-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: manifest.endpoints.map((e) => ({
+            name: toolName(e.route),
+            description: `[costs ${e.price} USDC per call] ${e.summary} ${e.description}`,
+            inputSchema: e.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const endpoint = byTool.get(req.params.name);
+        const fail = (text) => ({ content: [{ type: "text", text: redact(text) }], isError: true });
+        if (!endpoint)
+            return fail(`Unknown tool: ${req.params.name}`);
+        const priceUsd = parsePriceUsd(endpoint.price);
+        if (priceUsd === null)
+            return fail(`Gateway advertised an unparseable price: ${endpoint.price}`);
+        const refusal = checkSpend(priceUsd, spendState, spendConfig);
+        if (refusal)
+            return fail(refusal);
+        let url;
+        try {
+            url = buildUrl(endpoint, (req.params.arguments ?? {}));
+        }
+        catch (err) {
+            return fail(String(err instanceof Error ? err.message : err));
+        }
+        try {
+            const res = await getPayingFetch()(url, { method: "GET" });
+            const body = await res.text();
+            let paid = false;
+            const settleHeader = res.headers.get("PAYMENT-RESPONSE");
+            if (settleHeader) {
+                try {
+                    const settle = decodePaymentResponseHeader(settleHeader);
+                    paid = settle.success !== false;
+                }
+                catch {
+                    paid = res.status === 200; // settled header unparseable; count conservatively
+                }
+            }
+            if (paid)
+                spendState.sessionSpentUsd += priceUsd;
+            const note = paid
+                ? `\n\n[paid ${endpoint.price}; session spend $${spendState.sessionSpentUsd.toFixed(3)} of $${spendConfig.maxSessionUsd}]`
+                : "";
+            return {
+                content: [{ type: "text", text: redact(body) + note }],
+                isError: res.status !== 200,
+            };
+        }
+        catch (err) {
+            return fail(`Call failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    await server.connect(new StdioServerTransport());
+    console.error(`x402-gateway-mcp ready: ${byTool.size} tools from ${GATEWAY_URL} (caps: $${spendConfig.maxPerCallUsd}/call, $${spendConfig.maxSessionUsd}/session)`);
+}
+main().catch((err) => {
+    console.error("x402-gateway-mcp failed to start:", err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "x402-gateway-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing every x402-gateway data endpoint as a tool, paying per call with a user-supplied wallet (USDC on Base via x402). Built-in per-call and per-session spend caps. Tools: crypto prices, DeFi TVL, on-chain DEX pools, gas, FX rates, US Treasury yields, US weather, WHOIS, DNS, email validation, web-to-markdown extraction, Hacker News, Wikipedia, npm/PyPI package health, token risk scoring.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://gateway.stride20k.com",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "x402",
+    "micropayments",
+    "usdc",
+    "base",
+    "agent-tools",
+    "data-api",
+    "crypto-prices",
+    "web-scraping",
+    "token-risk"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "x402-gateway-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@x402/evm": "2.17.0",
+    "@x402/fetch": "2.17.0",
+    "viem": "2.54.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.9",
+    "typescript": "5.9.3"
+  }
+}