@forgemeshlabs/x402-ads-mcp 0.2.4 → 0.2.6

package/Dockerfile

@@ -5,10 +5,9 @@ WORKDIR /app
 COPY package.json package-lock.json ./
 RUN npm ci --omit=dev
 
-COPY index.js README.md LICENSE server.json glama.json GLAMA.md ./
+COPY index.js x402-guard.js README.md LICENSE server.json glama.json GLAMA.md ./
 
-ENV NODE_ENV=production \
-  X402_ADS_BASE_URL=https://ads.forgemesh.io
+ENV NODE_ENV=production
 
 USER node
 

package/README.md

@@ -60,10 +60,10 @@ One $0.10 USDC payment on Base; the paying wallet becomes your identity and your
 |---|---|---|
 | `WALLET_PRIVATE_KEY` | no | Base mainnet wallet holding USDC; enables automatic settlement of paid tools |
 | `X402_ADS_PUBLISHER_KEY` | no | Publisher key from ads.forgemesh.io; free lane for your own reports |
-| `X402_ADS_BASE_URL` | no | Override the network base URL (default `https://ads.forgemesh.io`) |
-| `BASE_RPC_URL` | no | Override the Base RPC (default `https://mainnet.base.org`) |
+| `X402_MAX_PRICE_USD` | no | Per-call price cap in USD; can only LOWER the built-in cap ($0.05, or $0.10 for `register`) |
+| `X402_SESSION_BUDGET_USD` | no | Cumulative cap per process; can only LOWER the built-in $10 |
 
-Use a dedicated hot wallet holding only small working balances. The key never leaves your machine — payments are signed locally (EIP-3009) and settle on-chain.
+The backend URL is fixed to `https://ads.forgemesh.io` (the publisher key is only ever sent there). The server refuses to sign for any payee other than the ForgeMesh Ads wallet, any network other than Base mainnet, any asset other than USDC, or any amount over the cap. Use a dedicated, low-balance wallet. The key never leaves your machine — payments are signed locally (EIP-3009) and settle on-chain.
 
 Ready-made configs live in [`examples/`](./examples): a Claude Desktop `mcpServers` block and a commented env-var template.
 

package/glama.json

@@ -25,5 +25,6 @@
     "machine-commerce",
     "mcp",
     "autonomous-agents"
-  ]
+  ],
+  "version": "0.2.6"
 }

package/index.js

@@ -8,20 +8,23 @@ const { x402Client, x402HTTPClient } = require("@x402/core/client");
 const { ExactEvmScheme } = require("@x402/evm/exact/client");
 const { toClientEvmSigner } = require("@x402/evm");
 const { privateKeyToAccount } = require("viem/accounts");
-const { createPublicClient, http } = require("viem");
-const { base } = require("viem/chains");
+const { createGuard } = require("./x402-guard");
 
-const BASE_URL = (process.env.X402_ADS_BASE_URL || "https://ads.forgemesh.io").replace(/\/+$/, "");
-const BASE_RPC_URL = process.env.BASE_RPC_URL || "https://mainnet.base.org";
+const BASE_URL = "https://ads.forgemesh.io";
+const ADS_PAY_TO = ["0x65E02cB7Fee27630bB7d1a3ADd02Ef7Aa2D21701"];
+// Tool calls cap at the highest tool price ($0.05); the register CLI needs its own $0.10 cap.
+const guard = createGuard({ baseUrl: BASE_URL, payTo: ADS_PAY_TO, maxPriceUsd: 0.05, sessionBudgetUsd: 10 });
+const registerGuard = createGuard({ baseUrl: BASE_URL, payTo: ADS_PAY_TO, maxPriceUsd: 0.1, sessionBudgetUsd: 10 });
 const WINDOWS = ["24h", "7d", "30d", "all"];
+const ID_PATTERN = /^[A-Za-z0-9._:@-]+$/; // service ids and categories: no slashes, spaces or control chars
 
 const TOOL_SCHEMAS = {
   list_tools: {},
   get_network_counters: {},
   preview_recommendations: {
-    service: z.string().max(120).optional().describe("Your service identifier, used only for self-exclusion in results"),
-    endpoint: z.string().max(300).optional().describe("The probed endpoint path, e.g. /api/forecast"),
-    category: z.string().max(60).optional().describe("Category to match recommendations against, e.g. finance, blockchain, images"),
+    service: z.string().max(120).regex(ID_PATTERN).optional().describe("Your service identifier, used only for self-exclusion in results"),
+    endpoint: z.string().max(300).regex(/^\/[A-Za-z0-9/._~%-]*$/).optional().describe("The probed endpoint path, e.g. /api/forecast"),
+    category: z.string().max(60).regex(ID_PATTERN).optional().describe("Category to match recommendations against, e.g. finance, blockchain, images"),
   },
   get_network_stats: {},
   get_intent_trends: {
@@ -29,11 +32,11 @@ const TOOL_SCHEMAS = {
     limit: z.number().int().min(1).max(100).optional().describe("Max rows, 1-100 (default 20)"),
   },
   get_category_demand: {
-    category: z.string().min(1).max(60).describe("Category to measure, e.g. finance, blockchain, images, tts"),
+    category: z.string().min(1).max(60).regex(ID_PATTERN).describe("Category to measure, e.g. finance, blockchain, images, tts"),
     window: z.enum(WINDOWS).optional().describe("Time window: 24h, 7d, 30d, or all (default 30d)"),
   },
   get_intent_report: {
-    service: z.string().min(1).max(120).describe("Service identifier to report on"),
+    service: z.string().min(1).max(120).regex(ID_PATTERN).describe("Service identifier to report on"),
     window: z.enum(WINDOWS).optional().describe("Time window: 24h, 7d, 30d, or all (default 30d)"),
   },
   get_terms: {},
@@ -138,12 +141,13 @@ const TOOLS = [
   },
 ];
 
-function walletClient() {
+function walletClient(g = guard) {
   const key = process.env.WALLET_PRIVATE_KEY;
   if (!key) return null;
   const pk = key.startsWith("0x") ? key : "0x" + key;
   const account = privateKeyToAccount(pk);
-  const coreClient = new x402Client().register("eip155:*", new ExactEvmScheme(toClientEvmSigner(account)));
+  const coreClient = new x402Client().register("eip155:*", new ExactEvmScheme(toClientEvmSigner(account)))
+    .registerPolicy(g.policy);
   return new x402HTTPClient(coreClient);
 }
 
@@ -172,49 +176,26 @@ function slimChallenge(res, body) {
   };
 }
 
-async function createChainTimedPaymentPayload(httpClient, paymentRequired) {
-  try {
-    const publicClient = createPublicClient({ chain: base, transport: http(BASE_RPC_URL) });
-    const block = await publicClient.getBlock();
-    const chainNow = Number(block.timestamp);
-    const originalNow = Date.now;
-    const localNow = Math.floor(originalNow() / 1000);
-    const timeout = Number(paymentRequired.accepts?.[0]?.maxTimeoutSeconds || 300);
-    const signingNow = Math.min(Math.max(chainNow, localNow + 30 - timeout), chainNow + 600);
-    Date.now = () => signingNow * 1000;
-    try {
-      return await httpClient.createPaymentPayload(paymentRequired);
-    } finally {
-      Date.now = originalNow;
-    }
-  } catch (_) {
-    return httpClient.createPaymentPayload(paymentRequired);
-  }
-}
-
 // Challenge-first paid GET: publisher free lane → settle if wallet → structured 402 otherwise.
 async function paidGet(path) {
   const headers = {};
   if (process.env.X402_ADS_PUBLISHER_KEY) headers["x-publisher-key"] = process.env.X402_ADS_PUBLISHER_KEY;
-  const url = BASE_URL + path;
 
-  const res = await fetch(url, { headers });
+  const res = await guard.fetchBounded(path, { headers });
   if (res.ok) {
     const viaPublisherKey = !!process.env.X402_ADS_PUBLISHER_KEY;
-    return { paid: false, ...(viaPublisherKey ? { free_via_publisher_key: true } : {}), data: await res.json() };
-  }
-  if (res.status !== 402) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`GET ${path} failed: ${res.status} ${text.slice(0, 240)}`);
+    return { paid: false, ...(viaPublisherKey ? { free_via_publisher_key: true } : {}), data: JSON.parse(res.text) };
   }
-
-  let challengeBody;
-  try {
-    challengeBody = await res.clone().json();
-  } catch (_) {}
+  if (res.status !== 402) throw new Error(`GET ${path} failed: ${res.status} ${res.text.slice(0, 200)}`);
 
   const httpClient = walletClient();
   if (!httpClient) {
+    let challengeBody;
+    try {
+      challengeBody = JSON.parse(res.text);
+    } catch (_) {
+      challengeBody = undefined; // header carries the full challenge; the body is only a summary
+    }
     return {
       payment_required: true,
       challenge: slimChallenge(res, challengeBody),
@@ -223,26 +204,14 @@ async function paidGet(path) {
     };
   }
 
-  const paymentRequired = httpClient.getPaymentRequiredResponse((name) => res.headers.get(name), challengeBody);
-  const paymentPayload = await createChainTimedPaymentPayload(httpClient, paymentRequired);
-  const paidRes = await fetch(url, {
-    headers: { ...headers, ...httpClient.encodePaymentSignatureHeader(paymentPayload) },
-  });
-  if (!paidRes.ok) {
-    const text = await paidRes.text().catch(() => paidRes.statusText);
-    throw new Error(`Paid call failed: ${paidRes.status} ${text.slice(0, 240)}`);
-  }
-  return {
-    paid: true,
-    payment_response: paidRes.headers.get("payment-response"),
-    data: await paidRes.json(),
-  };
+  const { _payment, ...data } = await guard.callPaid(httpClient, path, { headers });
+  return { paid: true, payment_response: _payment, data };
 }
 
 async function freeGet(path, asText = false) {
-  const res = await fetch(BASE_URL + path);
+  const res = await guard.fetchBounded(path);
   if (!res.ok) throw new Error(`GET ${path} failed: ${res.status}`);
-  return asText ? res.text() : res.json();
+  return asText ? res.text : JSON.parse(res.text);
 }
 
 function qs(params) {
@@ -260,7 +229,7 @@ async function callTool(name, args = {}) {
   if (name === "get_network_counters") return freeGet("/v1/counters");
 
   if (name === "preview_recommendations") {
-    const res = await fetch(BASE_URL + "/v1/decide", {
+    const res = await guard.fetchBounded("/v1/decide", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -270,7 +239,7 @@ async function callTool(name, args = {}) {
       }),
     });
     if (!res.ok) throw new Error(`POST /v1/decide failed: ${res.status}`);
-    return res.json();
+    return JSON.parse(res.text);
   }
 
   if (name === "get_network_stats") return paidGet("/api/network/stats");
@@ -292,7 +261,7 @@ function textResult(value) {
   return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
 }
 
-const server = new McpServer({ name: "x402-ads-mcp", version: "0.2.4" });
+const server = new McpServer({ name: "x402-ads-mcp", version: require("./package.json").version });
 server.server.onerror = (error) => {
   console.error(error instanceof Error ? error.message : String(error));
 };
@@ -344,7 +313,7 @@ async function registerCli(argv) {
     console.error("--accept-terms is required — read them first: " + BASE_URL + "/terms");
     process.exit(1);
   }
-  const httpClient = walletClient();
+  const httpClient = walletClient(registerGuard);
   if (!httpClient) {
     console.error("WALLET_PRIVATE_KEY is required: a Base mainnet wallet holding at least $0.10 USDC.");
     process.exit(1);
@@ -353,24 +322,18 @@ async function registerCli(argv) {
   if (!args.contact) delete args.contact;
   if (!args.categories.length) delete args.categories;
 
-  const url = BASE_URL + "/v1/publishers/register";
-  const init = { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(args) };
-  const res = await fetch(url, init);
-  if (res.status === 400) {
-    const body = await res.json().catch(() => ({}));
-    console.error("Rejected before payment (nothing was charged): " + (body.error || res.statusText));
+  const path = "/v1/publishers/register";
+  const body = JSON.stringify(args);
+  // Pre-flight unpaid request so a rejected body is reported before any payment is attempted.
+  const pre = await registerGuard.fetchBounded(path, { method: "POST", headers: { "content-type": "application/json" }, body });
+  if (pre.status === 400) {
+    let msg = pre.text.slice(0, 200);
+    try { msg = JSON.parse(pre.text).error || msg; } catch (_) { /* keep raw text */ }
+    console.error("Rejected before payment (nothing was charged): " + msg);
     process.exit(1);
   }
-  if (res.status !== 402) throw new Error(`expected x402 challenge, got ${res.status}`);
-  let challengeBody;
-  try {
-    challengeBody = await res.clone().json();
-  } catch (_) {}
-  const paymentRequired = httpClient.getPaymentRequiredResponse((n) => res.headers.get(n), challengeBody);
-  const paymentPayload = await createChainTimedPaymentPayload(httpClient, paymentRequired);
-  const paidRes = await fetch(url, { ...init, headers: { ...init.headers, ...httpClient.encodePaymentSignatureHeader(paymentPayload) } });
-  const out = await paidRes.json().catch(() => ({}));
-  if (!paidRes.ok) throw new Error(`registration failed (${paidRes.status}): ${JSON.stringify(out).slice(0, 240)}`);
+  if (pre.status !== 402) throw new Error(`expected x402 challenge, got ${pre.status}`);
+  const { _payment, ...out } = await registerGuard.callPaid(httpClient, path, { method: "POST", body: args });
   console.log("Registered: " + out.publisher_id);
   console.log("");
   console.log("Your publisher key (shown once — store it now):");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgemeshlabs/x402-ads-mcp",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "mcpName": "io.github.forgemeshlabs/x402-ads-mcp",
   "description": "Install one middleware. Monetize unused 402 responses with recommendations, discovery, and machine commerce analytics. MCP server: 7 tools for agent demand analytics, paid per call in USDC on Base; free for publishers on their own traffic.",
   "main": "index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "index.js",
+    "x402-guard.js",
     "README.md",
     "LICENSE",
     "glama.json",
@@ -58,11 +59,11 @@
     "url": "https://github.com/forgemeshlabs/x402-ads-mcp/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "@x402/core": "2.11.0",
-    "@x402/evm": "2.11.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@x402/core": "^2.29.0",
+    "@x402/evm": "^2.29.0",
     "viem": "^2.0.0",
-    "zod": "^3.25.76"
+    "zod": "^4.6.7"
   },
   "overrides": {
     "ws": "8.21.0"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/forgemeshlabs/x402-ads-mcp",
     "source": "github"
   },
-  "version": "0.2.4",
+  "version": "0.2.6",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@forgemeshlabs/x402-ads-mcp",
-      "version": "0.2.4",
+      "version": "0.2.6",
       "transport": {
         "type": "stdio"
       },
@@ -29,20 +29,6 @@
           "isRequired": false,
           "isSecret": true,
           "format": "string"
-        },
-        {
-          "name": "X402_ADS_BASE_URL",
-          "description": "Optional intent network base URL. Defaults to https://ads.forgemesh.io.",
-          "isRequired": false,
-          "isSecret": false,
-          "format": "string"
-        },
-        {
-          "name": "BASE_RPC_URL",
-          "description": "Optional Base mainnet RPC URL. Defaults to https://mainnet.base.org.",
-          "isRequired": false,
-          "isSecret": false,
-          "format": "string"
         }
       ]
     }

package/x402-guard.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * x402-guard — client-side payment and HTTP guard for ForgeMesh MCP servers (vendored copy per repo).
+ *
+ *   const { createGuard } = require("./x402-guard");
+ *   const guard = createGuard({
+ *     baseUrl: "https://x402.coinopai.com",          // the ONLY origin this server talks to
+ *     payTo: ["0x1304EC1A8945365e43A5c18a734065f107B417cA"], // wallets a 402 may name
+ *     maxPriceUsd: 1.00,                               // per-call ceiling (env X402_MAX_PRICE_USD overrides, lower only)
+ *     sessionBudgetUsd: 10.00,                         // cumulative ceiling per process (env X402_SESSION_BUDGET_USD)
+ *   });
+ *   const client = new x402Client().register("eip155:*", new ExactEvmScheme(signer)).registerPolicy(guard.policy);
+ *   const data = await guard.callPaid(httpClient, "/api/route", { method: "POST", body: {...} });
+ *
+ * What it enforces, before any signature is produced:
+ *   network  = eip155:8453 (Base mainnet), asset = USDC on Base, payTo in the allowlist,
+ *   amount  <= maxPriceUsd, running total <= sessionBudgetUsd.
+ * What it enforces on every HTTP call: same origin as baseUrl, https, no redirects,
+ *   REQUEST_TIMEOUT_MS, MAX_RESPONSE_BYTES. No global monkeypatching anywhere.
+ */
+
+const BASE_MAINNET = "eip155:8453";
+const USDC_BASE = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+const REQUEST_TIMEOUT_MS = 60_000;
+const MAX_RESPONSE_BYTES = 2_000_000;
+
+function usdFromRequirement(r) {
+  const raw = r.amount ?? r.maxAmountRequired ?? r.value;
+  if (raw === undefined || raw === null) return NaN;
+  const s = String(raw);
+  if (s.startsWith("$")) return Number(s.slice(1));
+  return Number(BigInt(s)) / 1e6; // USDC atomic units
+}
+
+function lowerCap(defaultUsd, envName) {
+  const env = Number(process.env[envName]);
+  return Number.isFinite(env) && env > 0 ? Math.min(env, defaultUsd) : defaultUsd;
+}
+
+function createGuard(opts) {
+  if (!opts || !opts.baseUrl) throw new Error("x402-guard: baseUrl is required");
+  const base = new URL(opts.baseUrl);
+  if (base.protocol !== "https:") throw new Error("x402-guard: baseUrl must be https");
+  const origin = base.origin;
+  // An empty allowlist means "this server never signs payments": the policy refuses every 402 and
+  // only fetchBounded is useful. Pass payTo: [] explicitly for free-only servers.
+  if (!Array.isArray(opts.payTo)) throw new Error("x402-guard: payTo allowlist is required (use [] for a server that never signs)");
+  const payTo = new Set(opts.payTo.map((a) => String(a).toLowerCase()));
+  const maxPriceUsd = lowerCap(opts.maxPriceUsd ?? 1.0, "X402_MAX_PRICE_USD");
+  const sessionBudgetUsd = lowerCap(opts.sessionBudgetUsd ?? 10.0, "X402_SESSION_BUDGET_USD");
+  let spentUsd = 0; // reserved at signing time, never released: a signed authorization can be settled even if our retry fails
+
+  function policy(_version, requirements) {
+    if (payTo.size === 0) throw new Error("x402-guard refused to sign: this server has no payee allowlist and never signs payments");
+    const kept = requirements.filter((r) => {
+      if (r.network !== BASE_MAINNET) return false;
+      if (String(r.asset || "").toLowerCase() !== USDC_BASE) return false;
+      if (!payTo.has(String(r.payTo || "").toLowerCase())) return false;
+      const usd = usdFromRequirement(r);
+      if (!Number.isFinite(usd) || usd <= 0 || usd > maxPriceUsd) return false;
+      if (spentUsd + usd > sessionBudgetUsd) return false;
+      return true;
+    });
+    if (kept.length === 0) {
+      const seen = requirements.map((r) => `${r.network} ${r.payTo} $${usdFromRequirement(r)}`).join("; ");
+      throw new Error(`x402-guard refused to sign: no payment option passed the guard (network must be ${BASE_MAINNET}, asset USDC, payTo in allowlist, price <= $${maxPriceUsd}, session total <= $${sessionBudgetUsd}). Offered: ${seen}`);
+    }
+    // Hand the selector exactly one option so the amount we reserve is the amount that gets signed.
+    const chosen = kept.reduce((a, b) => (usdFromRequirement(b) < usdFromRequirement(a) ? b : a));
+    spentUsd += usdFromRequirement(chosen);
+    return [chosen];
+  }
+
+  async function fetchBounded(url, init = {}) {
+    const target = new URL(String(url), origin);
+    if (target.origin !== origin) throw new Error(`x402-guard: refusing request to ${target.origin}; this server only talks to ${origin}`);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const res = await fetch(target.toString(), { ...init, signal: ctrl.signal, redirect: "error" });
+      const declared = Number(res.headers.get("content-length") || 0);
+      if (declared > MAX_RESPONSE_BYTES) { ctrl.abort(); throw new Error(`x402-guard: response too large (${declared} bytes)`); }
+      const chunks = [];
+      let received = 0;
+      if (res.body) {
+        const reader = res.body.getReader();
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          received += value.byteLength;
+          if (received > MAX_RESPONSE_BYTES) { ctrl.abort(); throw new Error("x402-guard: response too large"); }
+          chunks.push(value);
+        }
+      }
+      const bytes = Buffer.concat(chunks);
+      return { status: res.status, ok: res.ok, headers: res.headers, bytes, text: bytes.toString("utf8") };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  function parseJson(res) {
+    try { return JSON.parse(res.text); } catch { throw new Error(`HTTP ${res.status}: non-JSON response`); }
+  }
+
+  // GET or POST a paid route: unpaid request → 402 → guarded signature → retry. Returns parsed JSON;
+  // on a paid response attaches the settlement receipt as `_payment` when the body is an object.
+  async function callPaid(httpClient, path, { method = "GET", body, query, headers = {} } = {}) {
+    const url = new URL(path, origin);
+    if (query) for (const [k, v] of Object.entries(query)) if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+    const init = { method, headers: { ...headers, ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) };
+    const res = await fetchBounded(url, init);
+    if (res.status !== 402) {
+      if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.text.slice(0, 200)}`);
+      return parseJson(res);
+    }
+    let challenge;
+    try { challenge = JSON.parse(res.text); } catch { challenge = undefined; }
+    const paymentRequired = httpClient.getPaymentRequiredResponse((n) => res.headers.get(n), challenge);
+    const payload = await httpClient.createPaymentPayload(paymentRequired); // policy runs (and reserves budget) inside
+    const paid = await fetchBounded(url, { ...init, headers: { ...init.headers, ...httpClient.encodePaymentSignatureHeader(payload) } });
+    if (!paid.ok) throw new Error(`Payment failed — HTTP ${paid.status}: ${paid.text.slice(0, 200)}`);
+    let settle = null;
+    try { settle = httpClient.getPaymentSettleResponse((n) => paid.headers.get(n)) || null; } catch { settle = null; }
+    const contentType = paid.headers.get("content-type") || "";
+    // Non-JSON paid responses (audio, images) come back as raw bytes, never decoded as text.
+    if (!contentType.includes("json")) return { _binary: true, content_type: contentType, bytes: paid.bytes, _payment: settle };
+    const data = parseJson(paid);
+    if (settle && data && typeof data === "object" && !Array.isArray(data)) return { ...data, _payment: settle };
+    return data;
+  }
+
+  return {
+    policy,
+    fetchBounded,
+    callPaid,
+    limits: () => ({ maxPriceUsd, sessionBudgetUsd, spentUsd, origin, payTo: [...payTo] }),
+  };
+}
+
+module.exports = { createGuard, REQUEST_TIMEOUT_MS, MAX_RESPONSE_BYTES, BASE_MAINNET, USDC_BASE };