@forgemeshlabs/x402-ads-mcp 0.2.7 → 0.2.8

package/README.md

@@ -49,7 +49,7 @@ One $0.10 USDC payment on Base; the paying wallet becomes your identity and your
 | `get_terms` | free | Canonical terms + complete data-collection disclosure |
 | `get_network_stats` | $0.005 | Network totals + monitor/indexer/agent classification split |
 | `get_intent_trends` | $0.01 | Top endpoints & categories autonomous agents request |
-| `get_category_demand` | $0.02 | Demand depth for one category: volume, buyer share, price points |
+| `get_category_demand` | $0.02 | Demand depth for one category: probes, agent probes, conversions, price points (404 no_data is not charged) |
 | `get_intent_report` | $0.05 / **free*** | Why-agents-didn't-buy funnel for one service |
 
 \* `get_intent_report` is free with `X402_ADS_PUBLISHER_KEY` for services you contribute events to — the data co-op rule: your own data is free, forever.

package/glama.json

@@ -26,5 +26,5 @@
     "mcp",
     "autonomous-agents"
   ],
-  "version": "0.2.7"
+  "version": "0.2.8"
 }

package/index.js

@@ -32,7 +32,7 @@ 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).regex(ID_PATTERN).describe("Category to measure, e.g. finance, blockchain, images, tts"),
+    category: z.string().min(1).max(60).regex(ID_PATTERN).describe("Category as reported by publishers, e.g. blockchain, developer-tools (get_intent_trends lists categories with data)"),
     window: z.enum(WINDOWS).optional().describe("Time window: 24h, 7d, 30d, or all (default 30d)"),
   },
   get_intent_report: {
@@ -89,7 +89,7 @@ const TOOLS = [
       openWorldHint: true,
     },
     description:
-      "Paid, $0.005 USDC on Base via x402. x402 network traffic stats: network-wide totals (events, services), traffic classification split and ad activity. Without WALLET_PRIVATE_KEY, returns the x402 payment challenge instead of settling.",
+      "Paid, $0.005 USDC on Base via x402. x402 network traffic stats, no parameters: network-wide totals (x402 events, services), a breakdown of traffic by user-agent class (agent, browser, bot) and ad_activity. Use it to benchmark your service's agent-traffic share. Without WALLET_PRIVATE_KEY, returns the x402 payment challenge instead of settling.",
   },
   {
     name: "get_intent_trends",
@@ -101,7 +101,7 @@ const TOOLS = [
       openWorldHint: true,
     },
     description:
-      "Paid, $0.01 USDC on Base via x402. x402 agent demand trends: the most-requested x402 endpoints and categories by autonomous agents in a time window, with total and agent-only probe counts. Without WALLET_PRIVATE_KEY, returns the x402 payment challenge instead of settling.",
+      "Paid, $0.01 USDC on Base via x402. x402 agent demand trends: the most-requested x402 endpoints (service, endpoint, probes, agent_probes) and the categories with data, in a time window (24h, 7d, 30d or all; limit 1-100). Without WALLET_PRIVATE_KEY, returns the x402 payment challenge instead of settling.",
   },
   {
     name: "get_category_demand",
@@ -113,7 +113,7 @@ const TOOLS = [
       openWorldHint: true,
     },
     description:
-      "Paid, $0.02 USDC on Base via x402. x402 category demand depth: probe volume, agent probes, conversions, price points probed and a daily series for one API category. Without WALLET_PRIVATE_KEY, returns the x402 payment challenge instead of settling.",
+      "Paid, $0.02 USDC on Base via x402. x402 category demand depth for one API category: summary (probes, agent_probes, conversions), price points probed and a daily series. The category must be one publishers report (get_intent_trends lists categories that have data); a category with no reported traffic in the window answers 404 no_data and is not charged. Without WALLET_PRIVATE_KEY, returns the x402 payment challenge instead of settling.",
   },
   {
     name: "get_intent_report",
@@ -125,7 +125,7 @@ const TOOLS = [
       openWorldHint: true,
     },
     description:
-      "x402 conversion funnel report for one service (why agents probe but do not pay): bounce funnel, traffic classes, top abandoned endpoints, retry signals. FREE with X402_ADS_PUBLISHER_KEY for your registered services (the service id is bound to your key at registration); otherwise $0.05 USDC on Base via x402. Without a publisher key or WALLET_PRIVATE_KEY, returns the x402 payment challenge.",
+      "x402 conversion funnel report for one service (why agents probe but do not pay): funnel (total_probes, bounces, paid, conversion_rate), traffic_classes and top_abandoned_endpoints. Data exists only for services that report through the publisher middleware; a service with no events in the window answers 404 no_data and is not charged. FREE with X402_ADS_PUBLISHER_KEY for your registered services (the service id is bound to your key at registration); otherwise $0.05 USDC on Base via x402. Without a publisher key or WALLET_PRIVATE_KEY, returns the x402 payment challenge.",
   },
   {
     name: "get_terms",
@@ -186,7 +186,7 @@ async function paidGet(path) {
     const viaPublisherKey = !!process.env.X402_ADS_PUBLISHER_KEY;
     return { paid: false, ...(viaPublisherKey ? { free_via_publisher_key: true } : {}), data: JSON.parse(res.text) };
   }
-  if (res.status !== 402) throw new Error(`GET ${path} failed: ${res.status} ${res.text.slice(0, 200)}`);
+  if (res.status !== 402) throw guard.httpError(res, `GET ${path} failed: `, false); // nothing was signed, so nothing was charged
 
   const httpClient = walletClient();
   if (!httpClient) {
@@ -210,7 +210,7 @@ async function paidGet(path) {
 
 async function freeGet(path, asText = false) {
   const res = await guard.fetchBounded(path);
-  if (!res.ok) throw new Error(`GET ${path} failed: ${res.status}`);
+  if (!res.ok) throw guard.httpError(res, `GET ${path} failed: `, false);
   return asText ? res.text : JSON.parse(res.text);
 }
 
@@ -238,7 +238,7 @@ async function callTool(name, args = {}) {
         category: args.category,
       }),
     });
-    if (!res.ok) throw new Error(`POST /v1/decide failed: ${res.status}`);
+    if (!res.ok) throw guard.httpError(res, "POST /v1/decide failed: ", false);
     return JSON.parse(res.text);
   }
 
@@ -280,7 +280,7 @@ for (const tool of TOOLS) {
       } catch (error) {
         return {
           isError: true,
-          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+          content: [{ type: "text", text: error && error.status !== undefined ? JSON.stringify({ error: error.message, status: error.status, ...(typeof error.charged === "boolean" ? { charged: error.charged } : {}), upstream: error.upstream, untrusted: true }) : error instanceof Error ? error.message : String(error) }],
         };
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgemeshlabs/x402-ads-mcp",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "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",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/forgemeshlabs/x402-ads-mcp",
     "source": "github"
   },
-  "version": "0.2.7",
+  "version": "0.2.8",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@forgemeshlabs/x402-ads-mcp",
-      "version": "0.2.7",
+      "version": "0.2.8",
       "transport": {
         "type": "stdio"
       },

package/x402-guard.js

@@ -99,6 +99,21 @@ function createGuard(opts) {
     }
   }
 
+  // Keep the service's refusal intact: HTTP status, charged flag, and the body in err.upstream only.
+  // The message is short and fixed; upstream content is untrusted and never interpolated into prose.
+  function httpError(res, prefix, charged) {
+    let upstream;
+    try { upstream = JSON.parse(res.text); } catch { upstream = res.text.slice(0, 500); }
+    if (typeof upstream !== "string" && JSON.stringify(upstream).length > 1500) upstream = JSON.stringify(upstream).slice(0, 1500);
+    const code = upstream && typeof upstream === "object" && typeof upstream.error === "string" && /^[A-Za-z0-9_.:-]{1,64}$/.test(upstream.error) ? `: ${upstream.error}` : "";
+    const err = new Error(`${prefix}HTTP ${res.status}${code}`);
+    err.status = res.status;
+    err.upstream = upstream;
+    if (charged !== undefined) err.charged = charged;
+    else if (upstream && typeof upstream === "object" && typeof upstream.charged === "boolean") err.charged = upstream.charged;
+    return err;
+  }
+
   function parseJson(res) {
     try { return JSON.parse(res.text); } catch { throw new Error(`HTTP ${res.status}: non-JSON response`); }
   }
@@ -111,7 +126,7 @@ function createGuard(opts) {
     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)}`);
+      if (!res.ok) throw httpError(res, "", false); // nothing was signed, so nothing was charged
       return parseJson(res);
     }
     let challenge;
@@ -119,7 +134,7 @@ function createGuard(opts) {
     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)}`);
+    if (!paid.ok) throw httpError(paid, "Payment failed — ");
     let settle = null;
     try { settle = httpClient.getPaymentSettleResponse((n) => paid.headers.get(n)) || null; } catch { settle = null; }
     const contentType = paid.headers.get("content-type") || "";
@@ -134,6 +149,7 @@ function createGuard(opts) {
     policy,
     fetchBounded,
     callPaid,
+    httpError,
     limits: () => ({ maxPriceUsd, sessionBudgetUsd, spentUsd, origin, payTo: [...payTo] }),
   };
 }