@forgemeshlabs/x402-ads-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,8 @@
 # @forgemeshlabs/x402-ads-mcp
 
-**Machine-commerce intent analytics for your agent.** What autonomous agents probe, want, and abandon across the x402 ecosystem — as MCP tools.
+**Install one middleware. Monetize unused 402 responses with recommendations, discovery, and machine commerce analytics.**
+
+This is the MCP side of that network: what autonomous agents probe, want, and abandon across the x402 ecosystem — as tools for your agent.
 
 Wraps the [ForgeMesh x402 Ads & Intent Network](https://ads.forgemesh.io). Paid tools settle per call in USDC on Base mainnet over the [x402 protocol](https://x402.org) — no account, no API key; your wallet is the login. Publishers get reports on their own services **free**.
 
@@ -23,6 +25,18 @@ Wraps the [ForgeMesh x402 Ads & Intent Network](https://ads.forgemesh.io). Paid
 
 Both env vars are optional. With neither set, free tools work fully and paid tools return the x402 payment challenge (price, network, payTo) instead of settling — useful for inspection before spending anything.
 
+## Bonus: one-command publisher registration
+
+This package doubles as the signup CLI for API operators (no MCP client needed):
+
+```bash
+# read the terms first: https://ads.forgemesh.io/terms
+WALLET_PRIVATE_KEY=0xYOUR_WALLET npx -y @forgemeshlabs/x402-ads-mcp register \
+  --url https://api.your-service.com --accept-terms
+```
+
+One $0.10 USDC payment on Base; the paying wallet becomes your identity and your publisher key is printed once. Invalid requests are rejected **before** payment — you can't pay for a doomed registration.
+
 ## Tools
 
 | Tool | Price | What it returns |
@@ -48,6 +62,19 @@ Both env vars are optional. With neither set, free tools work fully and paid too
 
 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.
 
+Ready-made configs live in [`examples/`](./examples): a Claude Desktop `mcpServers` block and a commented env-var template.
+
+## Testing (safe by construction)
+
+```bash
+npm test                # smoke: MCP boots over stdio and lists its 7 tools
+npm run test:free       # free tools against the live network
+npm run test:challenge  # every paid tool returns an x402 challenge — no wallet, nothing can spend
+npm run test:all        # all of the above
+```
+
+No test settles a payment. The challenge test deletes the payment env vars before loading, so it cannot move funds even if your shell has a wallet configured.
+
 ## The network in one sentence
 
 **We measure machine commerce, not API content** — publishers running the [`@forgemeshlabs/x402-ads`](https://www.npmjs.com/package/@forgemeshlabs/x402-ads) middleware contribute anonymized 402 probe metadata; this MCP sells the aggregate demand signal back to agents and builders.

package/glama.json

@@ -2,7 +2,7 @@
   "$schema": "https://glama.ai/mcp/schemas/server.json",
   "name": "x402-ads-mcp",
   "version": "0.1.0",
-  "description": "Machine-commerce intent analytics over x402: agent demand trends, category depth, and why-agents-didn't-buy funnels for the x402 ecosystem. Free network counters and recommendation previews; paid analytics settle in USDC on Base.",
+  "description": "Install one middleware. Monetize unused 402 responses with recommendations, discovery, and machine commerce analytics. MCP server for the ForgeMesh x402 Ads network.",
   "homepage": "https://ads.forgemesh.io",
   "repository": "https://github.com/forgemeshlabs/x402-ads-mcp",
   "maintainers": [

package/index.js

@@ -266,8 +266,64 @@ async function main() {
   process.stdin.on("end", () => clearInterval(keepAlive));
 }
 
+// `npx -y @forgemeshlabs/x402-ads-mcp register` — one-command publisher signup.
+async function registerCli(argv) {
+  const args = { categories: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--url") args.service_url = argv[++i];
+    else if (argv[i] === "--name") args.name = argv[++i];
+    else if (argv[i] === "--category") args.categories.push(argv[++i]);
+    else if (argv[i] === "--contact") args.contact = argv[++i];
+    else if (argv[i] === "--accept-terms") args.terms_accepted = true;
+  }
+  if (!args.service_url || !args.terms_accepted) {
+    console.error("Usage: WALLET_PRIVATE_KEY=0x... x402-ads-mcp register --url https://api.your-service.com --accept-terms");
+    console.error("       [--name \"My API\"] [--category weather] [--contact you@example.com]");
+    console.error("");
+    console.error("Registers you as a publisher for one $0.10 USDC x402 payment on Base.");
+    console.error("The paying wallet becomes your identity; your key is printed once.");
+    console.error("--accept-terms is required — read them first: " + BASE_URL + "/terms");
+    process.exit(1);
+  }
+  const httpClient = walletClient();
+  if (!httpClient) {
+    console.error("WALLET_PRIVATE_KEY is required: a Base mainnet wallet holding at least $0.10 USDC.");
+    process.exit(1);
+  }
+  if (!args.name) delete args.name;
+  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));
+    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)}`);
+  console.log("Registered: " + out.publisher_id);
+  console.log("");
+  console.log("Your publisher key (shown once — store it now):");
+  console.log("  " + out.publisher_key);
+  console.log("");
+  console.log("Next: set it as X402_ADS_PUBLISHER_KEY in your server env and mount the");
+  console.log("@forgemeshlabs/x402-ads middleware. Your own traffic reports are free.");
+}
+
 if (require.main === module) {
-  main().catch((error) => {
+  const run = process.argv[2] === "register" ? registerCli(process.argv.slice(3)) : main();
+  run.catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@forgemeshlabs/x402-ads-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "mcpName": "io.github.forgemeshlabs/x402-ads-mcp",
-  "description": "Machine-commerce intent analytics over x402: what autonomous agents probe, want, and abandon across the x402 ecosystem — trends, category demand, and why-agents-didn't-buy funnels, paid per call in USDC on Base. Free for publishers on their own traffic.",
+  "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",
   "bin": {
     "x402-ads-mcp": "index.js"
@@ -18,7 +18,10 @@
   "scripts": {
     "start": "node index.js",
     "check": "node --check index.js",
-    "test": "npm run check && node scripts/test-mcp.js"
+    "test": "node tests/smoke.test.js",
+    "test:free": "node tests/free-tools.test.js",
+    "test:challenge": "node tests/paid-challenge.test.js",
+    "test:all": "npm run check && npm test && npm run test:free && npm run test:challenge"
   },
   "engines": {
     "node": ">=18"

package/server.json

@@ -1,7 +1,7 @@
 {
   "name": "x402-ads-mcp",
   "version": "0.1.0",
-  "description": "Machine-commerce intent analytics over x402: agent demand trends, category depth, and why-agents-didn't-buy funnels for the x402 ecosystem. Free network counters and recommendation previews; paid analytics settle in USDC on Base.",
+  "description": "Install one middleware. Monetize unused 402 responses with recommendations, discovery, and machine commerce analytics. MCP server for the ForgeMesh x402 Ads network.",
   "homepage": "https://ads.forgemesh.io",
   "repository": "https://github.com/forgemeshlabs/x402-ads-mcp",
   "transport": {