@paidfor/mcp 0.3.2 → 0.4.0

package/README.md

@@ -1,14 +1,19 @@
 # @paidfor/mcp
 
+**[Listed in the Claude connector directory](https://claude.ai/directory/paidfor).** In claude.ai or Claude Desktop: Settings, Connectors, browse the directory, paidfor, Connect; no key, no configuration.
+
 MCP server for [paidfor.dev](https://paidfor.dev), the x402 seller failure index on Base mainnet.
 
 **No account, no key.** Everything that reads the index or contributes data (the site, the API, the MCP tools, the client, telemetry and the changes feed) needs no account and no key, now and later. An email address is asked for only to deliver alerts or to join a waitlist, as a confirmation link, never a profile.
 
-Three read tools on every transport, plus two paying tools on stdio only when a wallet is configured:
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=paidfor&config=eyJ1cmwiOiJodHRwczovL21jcC5wYWlkZm9yLmRldi9tY3AifQ%3D%3D)
+
+Three read tools and one report tool on every transport, plus two paying tools on stdio only when a wallet is configured:
 
 - `check_x402_seller({ url })`: verdict (`avoid`, `caution`, `ok`, `unknown`) and one sentence for an x402 resource URL or seller domain, with the seller's paid-call count, failure rate and 95% interval, the resource's listed price, modal quote and max overcharge ratio when known, and links to the seller page and raw evidence.
 - `list_reliable_sellers({ category?, limit? })`: zero-failure sellers with at least 30 paid calls.
 - `recent_changes({ host?, since? })`: what changed, newest first (verdicts, new failures, moved quotes, pay-to addresses, replies, the operator series maturing or disagreeing); called when the user asks what changed or before relying on a verdict older than a day. Reads `GET https://paidfor.dev/v1/changes`.
+- `report_x402_payment({ url, tx_hash, outcome, quoted_usdc?, http_status? })`: after your agent pays an x402 seller with any wallet, reports what came back (`ok`, `non_delivery`, `wrong_goods`, `overcharge`, `duplicate`) with the settlement transaction hash. No key, no wallet: the index reads the payer and the amount from the transaction on Base and answers in one sentence (accepted and verified, pending, already reported, or rejected with the reason). It moves no money; the same hash never makes a second row. Posts the tx_only row to `POST https://paidfor.dev/v1/telemetry`.
 - `pay_x402({ url, method?, headers?, body?, intent_id?, max_usd? })` (stdio, wallet configured): pays through [`@paidfor/x402-safe-fetch`](https://www.npmjs.com/package/@paidfor/x402-safe-fetch) with your own wallet. See "Let your agent pay, safely" below.
 - `wallet_status()` (stdio, wallet configured): the paying address, its USDC balance on Base, the limits and today's spend. Never the key.
 
@@ -18,7 +23,7 @@ The read tools use the public JSON API (`GET https://paidfor.dev/v1/check`, `/v1
 
 ## Hosted (Streamable HTTP)
 
-`https://mcp.paidfor.dev/mcp`; a plain `GET` on it (or on `/status`) returns the service status with the data `generated_at` it last saw. `/health` on that host is answered by Manufact's gateway. Cursor, Claude Code and any Streamable HTTP client take the URL directly; Claude Desktop takes it under Settings, Connectors, or through `mcp-remote`:
+`https://mcp.paidfor.dev/mcp`; a plain `GET` on it (or on `/status`) returns the service status with the data `generated_at` it last saw. A browser (`Accept` preferring `text/html`) gets a setup page from `src/setup.ts` on `/mcp` and `/` instead; `?format=json` brings the status back. `/health` on that host is answered by Manufact's gateway. Cursor, Claude Code and any Streamable HTTP client take the URL directly; Claude Desktop takes it under Settings, Connectors, or through `mcp-remote`:
 
 ```json
 { "mcpServers": { "paidfor": { "url": "https://mcp.paidfor.dev/mcp" } } }
@@ -105,4 +110,4 @@ Usage is counted by Manufact's gateway (every `tools/call` with client and sessi
 
 ## Registry
 
-`server.json` is the Official MCP Registry entry (`io.github.sarmadahsan/paidfor`, matching `mcpName` in `package.json`). Publish npm first, then `mcp-publisher login github && mcp-publisher publish`.
+`server.json` is the Official MCP Registry entry (`dev.paidfor/paidfor`, matching `mcpName` in `package.json` from 0.3.3) and the manifest the site serves at https://paidfor.dev/.well-known/mcp.json and `/mcp.json`. Its `_meta` is `MANIFEST_META` from `src/setup.ts`; the site test fails when they differ. Publish npm first, then `mcp-publisher login dns --domain paidfor.dev` and `mcp-publisher publish` (checklist in `docs/listings.md` at the repo root).

package/dist/index.js

@@ -2,15 +2,18 @@
  * The hosted Streamable HTTP service: `node dist/index.js`. Plain @modelcontextprotocol/sdk,
  * no platform SDK, so the same folder runs on Manufact Cloud, Fly, Railway or a bare VM.
  * Stateless: one transport per request. GET /mcp (without Accept: text/event-stream) and
- * GET /status describe the service, including the site it reads and the export's
+ * GET /status describe the service (a browser, Accept preferring text/html, gets the setup page from setup.ts instead,
+ * and ?format=json brings the JSON back), including the site it reads and the export's
  * generated_at it last saw; the warm-up ping uses GET /mcp. GET /health is the plain
  * platform check (Manufact's gateway answers /health itself, Fly and Railway forward it).
  *
  * Env: PORT (default 3000), HOST (default 0.0.0.0), PAIDFOR_API_BASE (default https://paidfor.dev).
  */
+import { randomUUID } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createServer, DEFAULT_BASE, HOSTED_CLIENT_HEADER, HOSTED_INSTRUCTIONS, TOOL_NAMES, VERSION } from "./server.js";
+import { clientTag, CLIENT_TAGS, createServer, DEFAULT_BASE, HOSTED_CLIENT_HEADER, HOSTED_INSTRUCTIONS, TOOL_NAMES, VERSION, taggedClientHeader } from "./server.js";
+import { HOSTED_URL, prefersHtml, setupPageHtml, wantsJsonFormat } from "./setup.js";
 const base = (process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
 const port = Number(process.env.PORT ?? 3000);
 const host = process.env.HOST ?? "0.0.0.0";
@@ -25,6 +28,21 @@ fetch(`${base}/v1/summary`, { headers: { Accept: "application/json", "User-Agent
     .then((r) => (r.ok ? r.json() : null))
     .then((j) => noteGeneratedAt(j?.generated_at))
     .catch(() => undefined);
+/**
+ * The server is stateless, so the client tag read on initialize rides in the Mcp-Session-Id it answers with
+ * (`<tag>.<uuid>`), which clients send back on every later request; the stateless transport ignores the header itself.
+ */
+const SESSION_TAG = new RegExp(`^(${CLIENT_TAGS.join("|")})\\.`);
+const sessionTag = (req) => {
+    const id = req.headers["mcp-session-id"];
+    return (typeof id === "string" && SESSION_TAG.exec(id)?.[1]) || null;
+};
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+});
 const CORS = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS", "Access-Control-Allow-Headers": "*" };
 const sendJson = (res, status, body) => {
     res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", ...CORS });
@@ -57,19 +75,40 @@ createHttpServer(async (req, res) => {
     }
     if (path === "/" || path === "/mcp") {
         if (req.method === "GET" && !(req.headers.accept ?? "").includes("text/event-stream")) {
+            if (prefersHtml(req.headers.accept) && !wantsJsonFormat(req.url)) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "private, max-age=600", Vary: "Accept", ...CORS });
+                res.end(setupPageHtml({ endpoint: HOSTED_URL, statusUrl: `${HOSTED_URL}?format=json` }));
+                return;
+            }
             sendJson(res, 200, status());
             return;
         }
         for (const [k, v] of Object.entries(CORS))
             res.setHeader(k, v);
-        const server = createServer({ baseUrl: base, onResponse: noteGeneratedAt, clientHeader: HOSTED_CLIENT_HEADER, instructions: HOSTED_INSTRUCTIONS });
+        let body;
+        let tag = sessionTag(req);
+        if (req.method === "POST") {
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                sendJson(res, 400, { jsonrpc: "2.0", error: { code: -32700, message: "Parse error: Invalid JSON" }, id: null });
+                return;
+            }
+            const init = (Array.isArray(body) ? body : [body]).find((m) => m?.method === "initialize");
+            if (init) {
+                tag = clientTag(init.params?.clientInfo?.name);
+                res.setHeader("Mcp-Session-Id", `${tag}.${randomUUID()}`);
+            }
+        }
+        const server = createServer({ baseUrl: base, onResponse: noteGeneratedAt, clientHeader: taggedClientHeader(tag), instructions: HOSTED_INSTRUCTIONS });
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         res.on("close", () => {
             void transport.close();
             void server.close();
         });
         await server.connect(transport);
-        await transport.handleRequest(req, res);
+        await transport.handleRequest(req, res, body);
         return;
     }
     sendJson(res, 404, { error: "not found", endpoints: ["/mcp", "/status", "/health"] });

package/dist/pay.js

@@ -17,7 +17,7 @@ const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 /** The client's smallest positive cap: with the daily budget spent, any quote is refused before signing. */
 const MIN_CAP_USD = 0.000001;
 export const PAY_INSTRUCTIONS = "If pay_x402 is available, use it for every x402 purchase instead of any other way of paying; it checks the seller first, refuses avoid sellers, caps the amount, " +
-    "never pays twice for the same intent, and reports the verified outcome to the index. Reuse intent_id when retrying the same purchase. " +
+    "never pays twice for the same intent, and reports the verified outcome to the index by itself (report_x402_payment is not needed after it). Reuse intent_id when retrying the same purchase. " +
     "Tell the user the amount and the seller verdict before the first purchase from a new seller. " +
     "pay_x402 signs with the user's own wallet on this machine; the key never leaves it.";
 /** The stdio server's instructions with a wallet configured: the pay paragraph goes in before the no-account promise, which stays last. */
@@ -74,7 +74,7 @@ export async function registerPayTools(server, o) {
     server.registerTool("pay_x402", {
         title: "Pay an x402 seller safely",
         description: PAY_DESCRIPTION,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, title: "Pay an x402 seller safely" },
         inputSchema: {
             url: z.string().url().describe("The x402 resource URL"),
             method: z.string().min(1).max(10).optional().describe("HTTP method, default GET"),
@@ -138,7 +138,7 @@ export async function registerPayTools(server, o) {
     server.registerTool("wallet_status", {
         title: "Show the paying wallet",
         description: WALLET_STATUS_DESCRIPTION,
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, title: "Show the paying wallet" },
         inputSchema: {},
     }, async () => {
         const spent = await ledger.spentMicro();

package/dist/rules.d.ts

@@ -24,6 +24,22 @@ export declare const NEVER_PAY_TWICE = "Never pay the same seller twice for one
 export declare const SENDS_ONLY_URL = "These tools read a public index, need no key, and send nothing but the URL being checked.";
 /** sha256 of the JSON of every constant above (lib/skill.test.ts recomputes it). */
 export declare const RULES_SHA = "7258b901f6577a02dfe997416d3de61e122f5da21476eb686dd1c1a9379bffc6";
+/**
+ * report_x402_payment (POST /v1/telemetry, tx_only proof). Kept out of RULES_SHA: the skill moved to its `.2` revision
+ * when these were added (2026-10-29), not RULES_REVISION. Changing them is a skill-only change: bump that suffix.
+ */
+export declare const REPORT_TRIGGER = "after your agent pays an x402 seller with any wallet";
+export declare const REPORT_DESCRIPTION: string;
+/** The outcomes a reporter can name, in the index's words. */
+export declare const REPORT_OUTCOMES: {
+    readonly ok: "the response was usable for its purpose";
+    readonly non_delivery: "an error, an empty body or nothing usable after paying";
+    readonly wrong_goods: "a usable response, but not what was asked for";
+    readonly overcharge: "charged more than the quoted or listed price";
+    readonly duplicate: "two settlements for one purchase";
+};
+/** What the report sends, for the instructions and the skill. */
+export declare const REPORT_SENDS = "the resource URL, the settlement transaction hash, the outcome and the quote if given";
 /** "a, b, and c" */
 export declare function listAnd(xs: readonly string[]): string;
 /** "a, b, or c" */

package/dist/rules.js

@@ -28,6 +28,23 @@ export const NEVER_PAY_TWICE = "Never pay the same seller twice for one task bec
 export const SENDS_ONLY_URL = "These tools read a public index, need no key, and send nothing but the URL being checked.";
 /** sha256 of the JSON of every constant above (lib/skill.test.ts recomputes it). */
 export const RULES_SHA = "7258b901f6577a02dfe997416d3de61e122f5da21476eb686dd1c1a9379bffc6";
+/**
+ * report_x402_payment (POST /v1/telemetry, tx_only proof). Kept out of RULES_SHA: the skill moved to its `.2` revision
+ * when these were added (2026-10-29), not RULES_REVISION. Changing them is a skill-only change: bump that suffix.
+ */
+export const REPORT_TRIGGER = "after your agent pays an x402 seller with any wallet";
+export const REPORT_DESCRIPTION = "After your agent pays an x402 seller with any wallet, report what came back. Needs the resource URL, the settlement transaction hash and the outcome. " +
+    "Free, no account, no key; the report counts only with on-chain proof.";
+/** The outcomes a reporter can name, in the index's words. */
+export const REPORT_OUTCOMES = {
+    ok: "the response was usable for its purpose",
+    non_delivery: "an error, an empty body or nothing usable after paying",
+    wrong_goods: "a usable response, but not what was asked for",
+    overcharge: "charged more than the quoted or listed price",
+    duplicate: "two settlements for one purchase",
+};
+/** What the report sends, for the instructions and the skill. */
+export const REPORT_SENDS = "the resource URL, the settlement transaction hash, the outcome and the quote if given";
 /** "a, b, and c" */
 export function listAnd(xs) {
     return xs.length < 2 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")}, and ${xs.at(-1)}`;

package/dist/server.d.ts

@@ -1,18 +1,22 @@
-/**
- * The paidfor MCP server. One factory, three transports: stdio (npx @paidfor/mcp),
- * the hosted Streamable HTTP service (index.ts) and the Next.js route at /mcp on the site.
- * The read tools are thin readers of the public JSON API; the verdict logic lives on the site.
- * The paying tools (pay.ts) are added by stdio.ts alone, and only when a wallet is configured.
- */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { REPORT_OUTCOMES } from "./rules.js";
 export * from "./rules.js";
-export declare const VERSION = "0.3.2";
+export declare const VERSION = "0.4.0";
 /** Sent on every request to the index so usage can be counted by channel (never anything else). */
-export declare const CLIENT_HEADER = "mcp/0.3.2";
+export declare const CLIENT_HEADER = "mcp/0.4.0";
 /** What the hosted service (index.ts) sends instead, so the index can count hosted and stdio use apart. */
-export declare const HOSTED_CLIENT_HEADER = "mcp-hosted/0.3.2";
+export declare const HOSTED_CLIENT_HEADER = "mcp-hosted/0.4.0";
+/**
+ * Which client product a hosted session comes from, read from `clientInfo.name` on initialize and nothing else from the
+ * handshake: a product name, never a user. The hosted service appends it to its header (`mcp-hosted/<version>+claude`),
+ * so the index's channel counts split directory traffic by client with no change on the index side.
+ */
+export declare const CLIENT_TAGS: readonly ["claude", "chatgpt", "cursor", "other"];
+export type ClientTag = (typeof CLIENT_TAGS)[number];
+export declare function clientTag(name: unknown): ClientTag;
+export declare const taggedClientHeader: (tag: ClientTag | null) => string;
 export declare const DEFAULT_BASE = "https://paidfor.dev";
-export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
+export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers", "recent_changes", "report_x402_payment"];
 /**
  * The no-account promise, word for word wherever it appears: the server instructions (last line),
  * this package's README, /methodology, /install.md and /privacy on the site.
@@ -27,6 +31,8 @@ export declare const INSTRUCTIONS: string;
  * tools unprompted. stdio and the skill keep INSTRUCTIONS; the tool descriptions are shared by both.
  */
 export declare const HOSTED_INSTRUCTIONS: string;
+/** The first sentence of each read tool description: when to call it. The manifest and the setup page list these as they are. */
+export declare const TOOL_TRIGGERS: Record<(typeof TOOL_NAMES)[number], string>;
 export declare const CHECK_DESCRIPTION: string;
 export declare const LIST_DESCRIPTION: string;
 export declare const CHANGES_DESCRIPTION: string;
@@ -55,4 +61,74 @@ export declare const SERVER_INFO: {
         sizes: string[];
     }[];
 };
+type TelemetryAnswer = {
+    status?: string;
+    error?: string;
+    reason?: string;
+    payer?: string;
+    pay_to?: string;
+    amount_usdc?: string;
+    block?: number;
+    own?: boolean;
+    unattributed_seller?: boolean;
+    verification_url?: string;
+};
+/** The tx_only telemetry row the skill also sends (paidfor-client docs/telemetry.md, "tx_only"); the index reads the rest from Base. */
+export declare function reportPayload(i: {
+    url: string;
+    tx_hash: string;
+    outcome: keyof typeof REPORT_OUTCOMES;
+    quoted_usdc?: string | number;
+    http_status?: number;
+    client: string;
+}): {
+    latency_ms: number;
+    validator_failures: string[];
+    client: string;
+    proof: {
+        network: string;
+        tx_hash: string;
+    };
+    amount_usdc?: string | undefined;
+    path_hash: string;
+    outcome: "ok" | "duplicate" | "non_delivery" | "wrong_goods" | "overcharge";
+    path?: string | undefined;
+    v: number;
+    proof_level: string;
+    host: string;
+};
+/** The index's answer as one sentence and the structured result. */
+export declare function reportResult(httpStatus: number, a: TelemetryAnswer): {
+    sentence: string;
+    reason: null;
+    payer: string | null;
+    pay_to: string | null;
+    amount_usdc: string | null;
+    verification_url: string | null;
+    status: "verified";
+} | {
+    sentence: string;
+    reason: null;
+    payer: string | null;
+    pay_to: string | null;
+    amount_usdc: string | null;
+    verification_url: string | null;
+    status: "pending";
+} | {
+    sentence: string;
+    reason: null;
+    payer: string | null;
+    pay_to: string | null;
+    amount_usdc: string | null;
+    verification_url: string | null;
+    status: "duplicate";
+} | {
+    reason: string;
+    sentence: string;
+    payer: string | null;
+    pay_to: string | null;
+    amount_usdc: string | null;
+    verification_url: string | null;
+    status: "rejected";
+};
 export declare function createServer(opts?: ServerOptions): McpServer;

package/dist/server.js

@@ -4,17 +4,36 @@
  * The read tools are thin readers of the public JSON API; the verdict logic lives on the site.
  * The paying tools (pay.ts) are added by stdio.ts alone, and only when a wallet is configured.
  */
+import { createHash } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { CHANGES_TRIGGER, CHECK_TRIGGERS, CHOOSE_TRIGGER, NEVER_PAY_TWICE, SENDS_ONLY_URL, VERDICT_SENTENCE, cap, listAnd, listOr } from "./rules.js";
+import { CHANGES_TRIGGER, CHECK_TRIGGERS, CHOOSE_TRIGGER, NEVER_PAY_TWICE, REPORT_DESCRIPTION, REPORT_OUTCOMES, REPORT_SENDS, SENDS_ONLY_URL, VERDICT_SENTENCE, cap, listAnd, listOr } from "./rules.js";
 export * from "./rules.js";
-export const VERSION = "0.3.2";
+export const VERSION = "0.4.0";
 /** Sent on every request to the index so usage can be counted by channel (never anything else). */
 export const CLIENT_HEADER = `mcp/${VERSION}`;
 /** What the hosted service (index.ts) sends instead, so the index can count hosted and stdio use apart. */
 export const HOSTED_CLIENT_HEADER = `mcp-hosted/${VERSION}`;
+/**
+ * Which client product a hosted session comes from, read from `clientInfo.name` on initialize and nothing else from the
+ * handshake: a product name, never a user. The hosted service appends it to its header (`mcp-hosted/<version>+claude`),
+ * so the index's channel counts split directory traffic by client with no change on the index side.
+ */
+export const CLIENT_TAGS = ["claude", "chatgpt", "cursor", "other"];
+export function clientTag(name) {
+    const n = typeof name === "string" ? name.toLowerCase() : "";
+    if (n.includes("claude"))
+        return "claude";
+    if (n.includes("chatgpt") || n.includes("openai"))
+        return "chatgpt";
+    if (n.includes("cursor"))
+        return "cursor";
+    return "other";
+}
+export const taggedClientHeader = (tag) => (tag ? `${HOSTED_CLIENT_HEADER}+${tag}` : HOSTED_CLIENT_HEADER);
 export const DEFAULT_BASE = "https://paidfor.dev";
-export const TOOL_NAMES = ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
+export const TOOL_NAMES = ["check_x402_seller", "list_reliable_sellers", "recent_changes", "report_x402_payment"];
 const CATEGORIES = ["inference", "data", "scraping", "compute", "other"];
 /**
  * The no-account promise, word for word wherever it appears: the server instructions (last line),
@@ -30,7 +49,8 @@ export const INSTRUCTIONS = "paidfor rates x402 sellers by paying them and verif
     `${cap(CHOOSE_TRIGGER)}, prefer results from list_reliable_sellers. ` +
     `${cap(CHANGES_TRIGGER)}, call recent_changes. ` +
     `${NEVER_PAY_TWICE} ` +
-    SENDS_ONLY_URL +
+    `${SENDS_ONLY_URL} ` +
+    `After any x402 payment made with any wallet outside this server, call report_x402_payment with the resource URL, the settlement transaction hash and the outcome; it moves no money and sends only ${REPORT_SENDS}.` +
     "\n" +
     NO_ACCOUNT_PROMISE;
 /**
@@ -43,15 +63,23 @@ export const HOSTED_INSTRUCTIONS = "paidfor rates x402 sellers by paying them an
     '"avoid" means the seller failed paid calls (the evidence link shows how), "caution" carries the failure rate, "ok" means no failures across its paid calls, and "unknown" means the index has no data on it. ' +
     "list_reliable_sellers returns sellers with zero failures across at least 30 paid calls, for choosing among sellers. " +
     "recent_changes returns what changed in the index, which is diffed hourly. " +
-    `${SENDS_ONLY_URL}\n` +
+    `${SENDS_ONLY_URL} ` +
+    `report_x402_payment records what came back after a payment the user's own wallet already made, from the resource URL, the settlement transaction hash and the outcome; it moves no money, sends only ${REPORT_SENDS}, and the report counts only once the transaction is verified as a USDC transfer on Base.\n` +
     NO_ACCOUNT_PROMISE;
-export const CHECK_DESCRIPTION = `Call this ${listOr(CHECK_TRIGGERS)}. ` +
+/** The first sentence of each read tool description: when to call it. The manifest and the setup page list these as they are. */
+export const TOOL_TRIGGERS = {
+    check_x402_seller: `Call this ${listOr(CHECK_TRIGGERS)}.`,
+    list_reliable_sellers: `Call this ${CHOOSE_TRIGGER}, or when the user asks for a safe or reliable API.`,
+    recent_changes: `Call this ${CHANGES_TRIGGER}.`,
+    report_x402_payment: REPORT_DESCRIPTION.split(". ")[0] + ".",
+};
+export const CHECK_DESCRIPTION = `${TOOL_TRIGGERS.check_x402_seller} ` +
     "Returns a verdict (avoid, caution, ok, unknown), one sentence to act on, the seller's paid-call count and failure rate with a 95% interval, " +
     "listed price, modal quote and max overcharge ratio when known, and links to the seller page and raw evidence.";
-export const LIST_DESCRIPTION = `Call this ${CHOOSE_TRIGGER}, or when the user asks for a safe or reliable API. ` +
+export const LIST_DESCRIPTION = `${TOOL_TRIGGERS.list_reliable_sellers} ` +
     "Returns sellers with zero failures across at least 30 paid calls, most-called first. For each: domain, category, paid-call count, " +
     "the 95% upper bound on its failure rate, median quoted price in USDC, USDC paid to it in the last 30 days, when it was last seen, and its paidfor seller page.";
-export const CHANGES_DESCRIPTION = `Call this ${CHANGES_TRIGGER}. ` +
+export const CHANGES_DESCRIPTION = `${TOOL_TRIGGERS.recent_changes} ` +
     "Returns recent changes, newest first: verdict changes, new failures by type, moved quotes, changed pay-to addresses, sellers added or reaching 30 paid calls, published seller replies, " +
     "the operator-reported series maturing or disagreeing with ours. Each change has its time, type, seller domain, seller page and type-specific details (for example the old and new quote).";
 /** Advertised on initialize (Implementation in the MCP schema) for clients and directories. */
@@ -109,7 +137,54 @@ const CHANGES_OUTPUT = {
         data: z.record(z.string(), z.unknown()).describe("Type-specific details"),
     })),
 };
-/** The read tools only read the public index; the directories ask for these hints. */
+const REPORT_OUTPUT = {
+    status: z.enum(["verified", "pending", "duplicate", "rejected"]).describe("verified: counted once folded in (minutes); pending: checked on Base again within minutes; duplicate: this transaction was already reported; rejected: not counted, see reason"),
+    sentence: z.string().describe("The result in one sentence"),
+    reason: z.string().nullable().describe("Why a report was rejected; null otherwise"),
+    payer: z.string().nullable().describe("The paying wallet, read from the transaction (never from the report)"),
+    pay_to: z.string().nullable(),
+    amount_usdc: z.string().nullable().describe("USDC moved, read from the transaction"),
+    verification_url: z.string().nullable(),
+};
+/** The longest plain path sent; a longer one goes as its hash only. */
+const MAX_REPORT_PATH = 512;
+/** The tx_only telemetry row the skill also sends (paidfor-client docs/telemetry.md, "tx_only"); the index reads the rest from Base. */
+export function reportPayload(i) {
+    const u = new URL(i.url);
+    const path = u.pathname || "/";
+    const quoted = i.quoted_usdc === undefined ? undefined : Number(i.quoted_usdc);
+    return {
+        v: 2,
+        proof_level: "tx_only",
+        host: u.hostname.toLowerCase(),
+        ...(path.length <= MAX_REPORT_PATH ? { path } : {}),
+        path_hash: createHash("sha256").update(path.replace(/\/$/, "") || "/").digest("hex"),
+        outcome: i.outcome,
+        ...(quoted !== undefined && Number.isFinite(quoted) && quoted > 0 ? { amount_usdc: quoted.toFixed(6) } : {}),
+        latency_ms: 0,
+        validator_failures: i.http_status !== undefined && (i.http_status < 200 || i.http_status > 299) ? [`http_status:${i.http_status}`] : [],
+        client: i.client,
+        proof: { network: "eip155:8453", tx_hash: i.tx_hash.toLowerCase() },
+    };
+}
+/** The index's answer as one sentence and the structured result. */
+export function reportResult(httpStatus, a) {
+    const base = { reason: null, payer: a.payer ?? null, pay_to: a.pay_to ?? null, amount_usdc: a.amount_usdc ?? null, verification_url: a.verification_url ?? null };
+    if (httpStatus === 202 && a.status === "verified") {
+        const extra = [
+            a.own ? "it is one of paidfor's own wallets, so it is kept apart from the operator series" : null,
+            a.unattributed_seller ? "the seller is not in the index yet, so the payment is kept unattributed and the seller is queued for measurement" : null,
+        ].filter(Boolean);
+        return { status: "verified", ...base, sentence: `Accepted and verified: ${a.amount_usdc} USDC from ${a.payer} to ${a.pay_to} in Base block ${a.block}${extra.length ? `; ${extra.join("; ")}` : ""}.` };
+    }
+    if (httpStatus === 202)
+        return { status: "pending", ...base, sentence: `Accepted pending verification: the transaction is not readable on Base yet and is checked again within minutes (${a.verification_url}).` };
+    if (httpStatus === 200 && a.status === "duplicate")
+        return { status: "duplicate", ...base, sentence: `Already reported: this transaction is in the index once and was not counted again (${a.verification_url}).` };
+    const why = (a.error ?? `HTTP ${httpStatus}`).replace(/^not accepted: /, "");
+    return { status: "rejected", ...base, reason: a.reason ?? why, sentence: `Rejected: ${why}.` };
+}
+/** The read tools only read the public index; the directories ask for these hints, and for the title repeated as annotations.title. */
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 async function getJsonAs(url, client = CLIENT_HEADER) {
     const res = await fetch(url, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}`, "X-Paidfor-Client": client } });
@@ -124,10 +199,16 @@ export function createServer(opts = {}) {
     const base = (opts.baseUrl ?? process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
     const getJson = (url) => getJsonAs(url, opts.clientHeader);
     const server = new McpServer(SERVER_INFO, { instructions: opts.instructions ?? INSTRUCTIONS });
+    // No resources, templates or prompts, but answer the list calls with empty lists instead of
+    // "Method not found": directory scanners (ChatGPT's looks for widget resources) fail the scan otherwise.
+    server.server.registerCapabilities({ resources: {}, prompts: {} });
+    server.server.setRequestHandler(ListResourcesRequestSchema, () => ({ resources: [] }));
+    server.server.setRequestHandler(ListResourceTemplatesRequestSchema, () => ({ resourceTemplates: [] }));
+    server.server.setRequestHandler(ListPromptsRequestSchema, () => ({ prompts: [] }));
     server.registerTool("check_x402_seller", {
         title: "Check an x402 seller before paying",
         description: CHECK_DESCRIPTION,
-        annotations: READ_ONLY,
+        annotations: { ...READ_ONLY, title: "Check an x402 seller before paying" },
         inputSchema: { url: z.string().min(1).describe("x402 resource URL, or a bare seller domain such as api.example.com") },
         outputSchema: CHECK_OUTPUT,
     }, async ({ url }) => {
@@ -157,7 +238,7 @@ export function createServer(opts = {}) {
     server.registerTool("list_reliable_sellers", {
         title: "List reliable pay-per-call API sellers",
         description: LIST_DESCRIPTION,
-        annotations: READ_ONLY,
+        annotations: { ...READ_ONLY, title: "List reliable pay-per-call API sellers" },
         inputSchema: {
             category: z.enum(CATEGORIES).optional().describe("Kind of service to list sellers for; omit to list every kind"),
             limit: z.number().int().min(1).max(500).optional().describe("How many sellers to return, most-called first; 50 when omitted"),
@@ -177,7 +258,7 @@ export function createServer(opts = {}) {
     server.registerTool("recent_changes", {
         title: "Recent changes to x402 sellers",
         description: CHANGES_DESCRIPTION,
-        annotations: READ_ONLY,
+        annotations: { ...READ_ONLY, title: "Recent changes to x402 sellers" },
         inputSchema: {
             host: z.string().min(1).optional().describe("Seller to show changes for, as a bare domain such as api.example.com; omit for every seller"),
             since: z.string().min(1).optional().describe("Show only changes after this time, in ISO 8601 (such as the generated_at of a verdict you already have); omit for the latest changes"),
@@ -197,5 +278,34 @@ export function createServer(opts = {}) {
             : `No changes${host ? ` for ${host}` : ""}${since ? ` since ${since}` : ""}. The index is diffed hourly.`;
         return { content: [{ type: "text", text: `${head}\n\n${JSON.stringify(rows, null, 2)}` }], structuredContent: { count: r.count, events: rows } };
     });
+    server.registerTool("report_x402_payment", {
+        title: "Report an x402 payment outcome",
+        description: REPORT_DESCRIPTION,
+        // It writes one row to the index (not read-only), changes nothing else (not destructive), and the same tx_hash never makes a second row.
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true, title: "Report an x402 payment outcome" },
+        inputSchema: {
+            url: z.string().url().describe("The x402 resource URL that was paid for"),
+            tx_hash: z.string().regex(/^0x[0-9a-fA-F]{64}$/).describe("The settlement transaction hash on Base: the `transaction` field of the seller's PAYMENT-RESPONSE or X-PAYMENT-RESPONSE header (base64 JSON)"),
+            outcome: z.enum(Object.keys(REPORT_OUTCOMES)).describe(`What came back: ${Object.entries(REPORT_OUTCOMES).map(([k, v]) => `${k} (${v})`).join(", ")}`),
+            quoted_usdc: z.union([z.number().positive(), z.string().regex(/^\d{1,12}(\.\d{1,6})?$/)]).optional().describe("The price the 402 quoted, in USDC, if known"),
+            http_status: z.number().int().min(100).max(599).optional().describe("The HTTP status of the paid response, if known"),
+        },
+        outputSchema: REPORT_OUTPUT,
+    }, async ({ url, tx_hash, outcome, quoted_usdc, http_status }) => {
+        opts.onToolCall?.("report_x402_payment");
+        const client = opts.clientHeader ?? CLIENT_HEADER;
+        const res = await fetch(`${base}/v1/telemetry`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}`, "X-Paidfor-Client": client },
+            body: JSON.stringify(reportPayload({ url, tx_hash, outcome, quoted_usdc, http_status, client })),
+            redirect: "error",
+            signal: AbortSignal.timeout(30_000),
+        });
+        const a = (await res.json().catch(() => ({})));
+        if (res.status >= 500)
+            throw new Error(`${base}/v1/telemetry returned HTTP ${res.status}${a.error ? `: ${a.error}` : ""}; nothing was recorded, try again later`);
+        const r = reportResult(res.status, a);
+        return { content: [{ type: "text", text: r.sentence }], structuredContent: r };
+    });
     return server;
 }

package/dist/setup.d.ts

@@ -0,0 +1,48 @@
+export declare const HOSTED_URL = "https://mcp.paidfor.dev/mcp";
+export declare const SETUP_URL = "https://paidfor.dev/install";
+export declare const SKILL_URL = "https://paidfor.dev/skill.md";
+export declare const PRIVACY_URL = "https://paidfor.dev/privacy";
+export declare const MANIFEST_URL = "https://paidfor.dev/.well-known/mcp.json";
+export declare const AGENT_SETUP = "Tell your agent to read https://paidfor.dev/skill.md";
+/** What the hosted transports put in X-Paidfor-Client on every call to the index (taggedClientHeader: mcp-hosted/<version>+<client tag>). */
+export declare const CLIENT_HEADER_NOTE = "Every call the server makes to the index carries X-Paidfor-Client: mcp-hosted/<version>+<client>, so use can be counted by channel; <client> is your client product (claude, chatgpt, cursor or other, from its name on initialize), never you.";
+export declare const claudeCodeCommand: (url: string) => string;
+export declare const cursorServer: (url: string) => {
+    url: string;
+};
+export declare const cursorDeepLink: (url: string) => string;
+export declare const cursorConfig: (url: string) => string;
+/**
+ * True when the Accept header ranks text/html above JSON, which is a browser opening the URL. Anything else
+ * (no header, *\/*, application/json, text/event-stream, the MCP clients' "application/json, text/event-stream")
+ * keeps the JSON status body or the MCP transport.
+ */
+export declare function prefersHtml(accept: string | null | undefined): boolean;
+export type SetupPageOptions = {
+    /** The URL this page answers on. The snippets always name HOSTED_URL, as /install does. */
+    endpoint: string;
+    /** Where the JSON status body is for a browser: the same URL with ?format=json. */
+    statusUrl: string;
+};
+/** The page a browser gets from GET on the MCP URL. Plain HTML, no script, the same copy as /install. */
+export declare function setupPageHtml({ endpoint, statusUrl }: SetupPageOptions): string;
+/** Status JSON for a browser that asks: GET <mcp url>?format=json. */
+export declare const wantsJsonFormat: (url: string | undefined) => boolean;
+/**
+ * The manifest's `_meta`, under the registry's publisher-provided key (the one `_meta` key the server.json schema
+ * names). mcp/server.json carries a copy; lib/manifest.test.ts on the site fails when the two differ.
+ */
+export declare const MANIFEST_META: {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+        tools: {
+            name: "check_x402_seller" | "list_reliable_sellers" | "recent_changes" | "report_x402_payment";
+            trigger: string;
+        }[];
+        setup_url: string;
+        setup_page: string;
+        skill_url: string;
+        privacy_url: string;
+        auth: string;
+        no_account: string;
+    };
+};

package/dist/setup.js

@@ -0,0 +1,118 @@
+/**
+ * What a person or a directory sees of the server without speaking MCP: the setup snippets (shared with the site's
+ * /install), the HTML page a browser gets from GET on the MCP URL, and the `_meta` block of the manifest at
+ * paidfor.dev/.well-known/mcp.json. All of it is generated from server.ts and rules.ts, like the tool descriptions.
+ */
+import { DEFAULT_BASE, HOSTED_INSTRUCTIONS, NO_ACCOUNT_PROMISE, TOOL_NAMES, TOOL_TRIGGERS, VERSION } from "./server.js";
+export const HOSTED_URL = "https://mcp.paidfor.dev/mcp";
+export const SETUP_URL = `${DEFAULT_BASE}/install`;
+export const SKILL_URL = `${DEFAULT_BASE}/skill.md`;
+export const PRIVACY_URL = `${DEFAULT_BASE}/privacy`;
+export const MANIFEST_URL = `${DEFAULT_BASE}/.well-known/mcp.json`;
+export const AGENT_SETUP = `Tell your agent to read ${SKILL_URL}`;
+/** What the hosted transports put in X-Paidfor-Client on every call to the index (taggedClientHeader: mcp-hosted/<version>+<client tag>). */
+export const CLIENT_HEADER_NOTE = "Every call the server makes to the index carries X-Paidfor-Client: mcp-hosted/<version>+<client>, so use can be counted by channel; <client> is your client product (claude, chatgpt, cursor or other, from its name on initialize), never you.";
+export const claudeCodeCommand = (url) => `claude mcp add --transport http --scope user paidfor ${url}`;
+export const cursorServer = (url) => ({ url });
+export const cursorDeepLink = (url) => `cursor://anysphere.cursor-deeplink/mcp/install?name=paidfor&config=${encodeURIComponent(Buffer.from(JSON.stringify(cursorServer(url)), "utf8").toString("base64"))}`;
+export const cursorConfig = (url) => JSON.stringify({ mcpServers: { paidfor: cursorServer(url) } }, null, 2);
+/**
+ * True when the Accept header ranks text/html above JSON, which is a browser opening the URL. Anything else
+ * (no header, *\/*, application/json, text/event-stream, the MCP clients' "application/json, text/event-stream")
+ * keeps the JSON status body or the MCP transport.
+ */
+export function prefersHtml(accept) {
+    if (!accept)
+        return false;
+    const q = (type) => {
+        let best = 0;
+        for (const part of accept.split(",")) {
+            const [t, ...params] = part.trim().toLowerCase().split(";");
+            if (t.trim() !== type)
+                continue;
+            const qp = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
+            best = Math.max(best, qp ? Number(qp.slice(2)) || 0 : 1);
+        }
+        return best;
+    };
+    const html = q("text/html");
+    return html > 0 && html > q("application/json") && q("text/event-stream") === 0;
+}
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** Tailwind v4's neutral scale, the site's tokens (app/globals.css), mirrored for dark the same way. */
+const CSS = `:root{color-scheme:light dark;--bg:#fff;--fg:oklch(20.5% 0 0);--muted:oklch(43.9% 0 0);--line:oklch(92.2% 0 0);--code:oklch(97% 0 0);--link:oklch(87% 0 0)}
+@media (prefers-color-scheme:dark){:root{--bg:#000;--fg:oklch(97% 0 0);--muted:oklch(70.8% 0 0);--line:oklch(26.9% 0 0);--code:oklch(20.5% 0 0);--link:oklch(37.1% 0 0)}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.6 ui-sans-serif,system-ui,sans-serif,"Apple Color Emoji","Segoe UI Emoji";-webkit-font-smoothing:antialiased}
+main{max-width:44rem;margin:0 auto;padding:24px 16px 48px}h1{font-size:1.5rem;font-weight:600;margin:8px 0 4px}h2{font-size:1.05rem;font-weight:600;margin:28px 0 6px}
+p{margin:6px 0}.muted{color:var(--muted);font-size:.9rem}a{color:inherit;text-decoration:underline;text-decoration-color:var(--link);text-underline-offset:2px}a:hover{text-decoration-color:var(--fg)}
+code,pre{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.85em}code{background:var(--code);padding:0 4px;border-radius:4px}
+pre{background:var(--code);border:1px solid var(--line);border-radius:6px;padding:10px 12px;overflow-x:auto;white-space:pre-wrap;overflow-wrap:anywhere}pre code{background:none;padding:0}
+.btn{display:inline-block;border:1px solid var(--fg);border-radius:6px;padding:4px 12px;text-decoration:none;font-size:.9rem;margin:4px 0}
+ul{padding-left:20px;margin:6px 0}li{margin:4px 0}details{border:1px solid var(--line);border-radius:6px;padding:8px 12px;margin-top:8px}summary{cursor:pointer;font-weight:500}
+details p{white-space:pre-wrap;font-size:.9rem}footer{border-top:1px solid var(--line);margin-top:32px;padding-top:12px}`;
+/** The page a browser gets from GET on the MCP URL. Plain HTML, no script, the same copy as /install. */
+export function setupPageHtml({ endpoint, statusUrl }) {
+    const pre = (s) => `<pre><code>${esc(s)}</code></pre>`;
+    const tools = TOOL_NAMES.map((t) => `<li><code>${t}</code>: ${esc(TOOL_TRIGGERS[t].replace(/^Call this /, "call it "))}</li>`).join("");
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>paidfor MCP server</title>
+<meta name="description" content="Set up the paidfor MCP server: check an x402 seller before your agent pays. No account, no key.">
+<link rel="icon" href="${DEFAULT_BASE}/icon.png"><link rel="alternate" type="application/json" href="${esc(MANIFEST_URL)}">
+<style>${CSS}</style></head>
+<body><main>
+<p class="muted"><a href="${DEFAULT_BASE}">paidfor.dev</a> · MCP server ${VERSION}</p>
+<h1>paidfor MCP server</h1>
+<p>It rates x402 sellers by paying them and verifying delivery, so your agent can check a seller before it pays one.</p>
+<p class="muted">${endpoint === HOSTED_URL
+        ? `This is a Streamable HTTP MCP endpoint: <code>${esc(endpoint)}</code>. Add it to your MCP client; opening it in a browser shows this page.`
+        : `<code>${esc(endpoint)}</code> is a Streamable HTTP MCP endpoint serving the same tools as <code>${HOSTED_URL}</code>, the URL the setup below uses.`}</p>
+
+<h2>One line for any agent</h2>
+${pre(AGENT_SETUP)}
+<p class="muted">The skill installs the server where it can and keeps the rules where it cannot.</p>
+
+<h2>Claude Code</h2>
+${pre(claudeCodeCommand(HOSTED_URL))}
+
+<h2>Claude (claude.ai, desktop, mobile)</h2>
+<p>Customize, Connectors, + Add, Add custom connector. Name <code>paidfor</code>, URL:</p>
+${pre(HOSTED_URL)}
+<p class="muted">Choose No sign in. On Team and Enterprise an owner adds it under Organization settings, Connectors.</p>
+
+<h2>Cursor</h2>
+<p><a class="btn" href="${esc(cursorDeepLink(HOSTED_URL))}">Add to Cursor</a></p>
+<p class="muted">Or merge into <code>~/.cursor/mcp.json</code>:</p>
+${pre(cursorConfig(HOSTED_URL))}
+
+<p>VS Code, Windsurf, Codex, ChatGPT and stdio: <a href="${SETUP_URL}">${SETUP_URL.replace("https://", "")}</a>.</p>
+
+<h2>Tools</h2>
+<ul>${tools}</ul>
+<details><summary>Server instructions, as sent on initialize</summary><p>${esc(HOSTED_INSTRUCTIONS)}</p></details>
+
+<h2>No account, no key</h2>
+<p>${esc(NO_ACCOUNT_PROMISE)}</p>
+<p class="muted">${esc(CLIENT_HEADER_NOTE)}</p>
+
+<footer class="muted"><a href="${MANIFEST_URL}">Manifest</a> · <a href="${DEFAULT_BASE}/api">API</a> · <a href="${PRIVACY_URL}">Privacy</a> · <a href="${esc(statusUrl)}">Status JSON</a></footer>
+</main></body></html>
+`;
+}
+/** Status JSON for a browser that asks: GET <mcp url>?format=json. */
+export const wantsJsonFormat = (url) => /[?&]format=json(&|$)/.test(url ?? "");
+/**
+ * The manifest's `_meta`, under the registry's publisher-provided key (the one `_meta` key the server.json schema
+ * names). mcp/server.json carries a copy; lib/manifest.test.ts on the site fails when the two differ.
+ */
+export const MANIFEST_META = {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+        tools: TOOL_NAMES.map((name) => ({ name, trigger: TOOL_TRIGGERS[name] })),
+        setup_url: SETUP_URL,
+        setup_page: HOSTED_URL,
+        skill_url: SKILL_URL,
+        privacy_url: PRIVACY_URL,
+        auth: "none",
+        no_account: NO_ACCOUNT_PROMISE,
+    },
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.3.2",
-  "mcpName": "io.github.sarmadahsan/paidfor",
+  "version": "0.4.0",
+  "mcpName": "dev.paidfor/paidfor",
   "description": "MCP server for the paidfor.dev x402 seller index: check_x402_seller, list_reliable_sellers and recent_changes, plus pay_x402 (stdio, your own wallet)",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,8 @@
   },
   "main": "./dist/server.js",
   "exports": {
-    ".": "./dist/server.js"
+    ".": "./dist/server.js",
+    "./setup": "./dist/setup.js"
   },
   "files": [
     "dist",