@paidfor/mcp 0.3.0 → 0.3.2

package/dist/index.js

@@ -10,7 +10,7 @@
  */
 import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createServer, DEFAULT_BASE, TOOL_NAMES, VERSION } from "./server.js";
+import { createServer, DEFAULT_BASE, HOSTED_CLIENT_HEADER, HOSTED_INSTRUCTIONS, TOOL_NAMES, VERSION } from "./server.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";
@@ -21,7 +21,7 @@ const noteGeneratedAt = (g) => {
     if (g)
         dataGeneratedAt = g;
 };
-fetch(`${base}/v1/summary`, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}` } })
+fetch(`${base}/v1/summary`, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}`, "X-Paidfor-Client": HOSTED_CLIENT_HEADER } })
     .then((r) => (r.ok ? r.json() : null))
     .then((j) => noteGeneratedAt(j?.generated_at))
     .catch(() => undefined);
@@ -62,7 +62,7 @@ createHttpServer(async (req, res) => {
         }
         for (const [k, v] of Object.entries(CORS))
             res.setHeader(k, v);
-        const server = createServer({ baseUrl: base, onResponse: noteGeneratedAt });
+        const server = createServer({ baseUrl: base, onResponse: noteGeneratedAt, clientHeader: HOSTED_CLIENT_HEADER, instructions: HOSTED_INSTRUCTIONS });
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         res.on("close", () => {
             void transport.close();

package/dist/rules.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The one copy of the rules an agent follows: when to check, what each verdict means, and never paying twice.
+ * The server instructions and the tool descriptions (server.ts) and the skill at paidfor.dev/skill.md (lib/skill.ts on
+ * the site) are all generated from these constants, so the three copies cannot drift.
+ *
+ * Changing any text here changes the skill: bump RULES_REVISION (the skill's `skill-revision`) and update RULES_SHA;
+ * lib/skill.test.ts fails until both move together.
+ */
+export declare const RULES_REVISION = "2026-10-29";
+/** When to call check_x402_seller (GET /v1/check), in order. */
+export declare const CHECK_TRIGGERS: readonly ["before any x402 payment", "before retrying a request that answered HTTP 402", "whenever the user is about to buy an API call with USDC on Base or names an API they intend to pay per call"];
+/** When to call list_reliable_sellers (GET /v1/sellers?zero_failures=1). */
+export declare const CHOOSE_TRIGGER = "when choosing among sellers for a task";
+/** When to call recent_changes (GET /v1/changes). */
+export declare const CHANGES_TRIGGER = "when the user asks what changed, or before relying on a verdict older than a day";
+/** What to do for each verdict. */
+export declare const VERDICT_RULES: {
+    readonly avoid: "do not pay an \"avoid\" seller and say why with the evidence link";
+    readonly caution: "before paying a \"caution\" seller tell the user the failure rate";
+    readonly ok: "\"ok\" needs no comment";
+    readonly unknown: "\"unknown\" means no data, say so and proceed only on the user's say-so";
+};
+export declare const NEVER_PAY_TWICE = "Never pay the same seller twice for one task because of a timeout or error without checking first.";
+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";
+/** "a, b, and c" */
+export declare function listAnd(xs: readonly string[]): string;
+/** "a, b, or c" */
+export declare function listOr(xs: readonly string[]): string;
+export declare const cap: (s: string) => string;
+/** The verdict rules as one sentence (server instructions, skill). */
+export declare const VERDICT_SENTENCE: string;

package/dist/rules.js

@@ -0,0 +1,41 @@
+/**
+ * The one copy of the rules an agent follows: when to check, what each verdict means, and never paying twice.
+ * The server instructions and the tool descriptions (server.ts) and the skill at paidfor.dev/skill.md (lib/skill.ts on
+ * the site) are all generated from these constants, so the three copies cannot drift.
+ *
+ * Changing any text here changes the skill: bump RULES_REVISION (the skill's `skill-revision`) and update RULES_SHA;
+ * lib/skill.test.ts fails until both move together.
+ */
+export const RULES_REVISION = "2026-10-29";
+/** When to call check_x402_seller (GET /v1/check), in order. */
+export const CHECK_TRIGGERS = [
+    "before any x402 payment",
+    "before retrying a request that answered HTTP 402",
+    "whenever the user is about to buy an API call with USDC on Base or names an API they intend to pay per call",
+];
+/** When to call list_reliable_sellers (GET /v1/sellers?zero_failures=1). */
+export const CHOOSE_TRIGGER = "when choosing among sellers for a task";
+/** When to call recent_changes (GET /v1/changes). */
+export const CHANGES_TRIGGER = "when the user asks what changed, or before relying on a verdict older than a day";
+/** What to do for each verdict. */
+export const VERDICT_RULES = {
+    avoid: 'do not pay an "avoid" seller and say why with the evidence link',
+    caution: 'before paying a "caution" seller tell the user the failure rate',
+    ok: '"ok" needs no comment',
+    unknown: '"unknown" means no data, say so and proceed only on the user\'s say-so',
+};
+export const NEVER_PAY_TWICE = "Never pay the same seller twice for one task because of a timeout or error without checking first.";
+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";
+/** "a, b, and c" */
+export function listAnd(xs) {
+    return xs.length < 2 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")}, and ${xs.at(-1)}`;
+}
+/** "a, b, or c" */
+export function listOr(xs) {
+    return xs.length < 2 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")}, or ${xs.at(-1)}`;
+}
+export const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** The verdict rules as one sentence (server instructions, skill). */
+export const VERDICT_SENTENCE = `Follow the verdict: ${[VERDICT_RULES.avoid, VERDICT_RULES.caution, VERDICT_RULES.ok, VERDICT_RULES.unknown].join("; ")}.`;

package/dist/server.d.ts

@@ -5,7 +5,12 @@
  * 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";
-export declare const VERSION = "0.3.0";
+export * from "./rules.js";
+export declare const VERSION = "0.3.2";
+/** 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";
+/** 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 DEFAULT_BASE = "https://paidfor.dev";
 export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
 /**
@@ -13,8 +18,15 @@ export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_s
  * this package's README, /methodology, /install.md and /privacy on the site.
  */
 export declare const NO_ACCOUNT_PROMISE: string;
-/** Sent on initialize by every transport (stdio, the hosted service, the site's /mcp route), so clients call the tools unprompted. */
+/** Sent on initialize by every transport (stdio, the hosted service, the site's /mcp route), so clients call the tools unprompted.
+ * Generated from rules.ts, like the tool descriptions below and the skill at paidfor.dev/skill.md. */
 export declare const INSTRUCTIONS: string;
+/**
+ * What the hosted transports (index.ts, the site's /mcp route) send instead of INSTRUCTIONS: the same facts, described
+ * rather than directed, because the Connectors Directory review rejects text that tells Claude how to behave or to call
+ * tools unprompted. stdio and the skill keep INSTRUCTIONS; the tool descriptions are shared by both.
+ */
+export declare const HOSTED_INSTRUCTIONS: string;
 export declare const CHECK_DESCRIPTION: string;
 export declare const LIST_DESCRIPTION: string;
 export declare const CHANGES_DESCRIPTION: string;
@@ -25,7 +37,22 @@ export type ServerOptions = {
     onToolCall?: (tool: string) => void;
     /** Called with the export's generated_at from every successful response (the hosted service shows it on /health). */
     onResponse?: (generated_at: string) => void;
-    /** Replaces INSTRUCTIONS; stdio.ts passes INSTRUCTIONS_WITH_PAY when it registers pay_x402. */
+    /** The X-Paidfor-Client header on every index call; defaults to CLIENT_HEADER (stdio). */
+    clientHeader?: string;
+    /** Replaces INSTRUCTIONS; stdio.ts passes INSTRUCTIONS_WITH_PAY when it registers pay_x402, the hosted transports HOSTED_INSTRUCTIONS. */
     instructions?: string;
 };
+/** Advertised on initialize (Implementation in the MCP schema) for clients and directories. */
+export declare const SERVER_INFO: {
+    name: string;
+    title: string;
+    version: string;
+    description: string;
+    websiteUrl: string;
+    icons: {
+        src: string;
+        mimeType: string;
+        sizes: string[];
+    }[];
+};
 export declare function createServer(opts?: ServerOptions): McpServer;

package/dist/server.js

@@ -6,7 +6,13 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-export const VERSION = "0.3.0";
+import { CHANGES_TRIGGER, CHECK_TRIGGERS, CHOOSE_TRIGGER, NEVER_PAY_TWICE, SENDS_ONLY_URL, VERDICT_SENTENCE, cap, listAnd, listOr } from "./rules.js";
+export * from "./rules.js";
+export const VERSION = "0.3.2";
+/** 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}`;
 export const DEFAULT_BASE = "https://paidfor.dev";
 export const TOOL_NAMES = ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
 const CATEGORIES = ["inference", "data", "scraping", "compute", "other"];
@@ -16,41 +22,114 @@ const CATEGORIES = ["inference", "data", "scraping", "compute", "other"];
  */
 export const NO_ACCOUNT_PROMISE = "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.";
-/** Sent on initialize by every transport (stdio, the hosted service, the site's /mcp route), so clients call the tools unprompted. */
+/** Sent on initialize by every transport (stdio, the hosted service, the site's /mcp route), so clients call the tools unprompted.
+ * Generated from rules.ts, like the tool descriptions below and the skill at paidfor.dev/skill.md. */
 export const INSTRUCTIONS = "paidfor rates x402 sellers by paying them and verifying delivery. " +
-    "Before any x402 payment, before retrying a request that answered HTTP 402, and whenever the user is about to buy an API call with USDC on Base, " +
-    "call check_x402_seller on the URL or seller domain first, without being asked. " +
-    'Follow the verdict: do not pay an "avoid" seller and say why with the evidence link; before paying a "caution" seller tell the user the failure rate; ' +
-    '"ok" needs no comment; "unknown" means no data, say so and proceed only on the user\'s say-so. ' +
-    "When choosing among sellers for a task, prefer results from list_reliable_sellers. " +
-    "When the user asks what changed, or before relying on a verdict older than a day, call recent_changes. " +
-    "Never pay the same seller twice for one task because of a timeout or error without checking first. " +
-    "These tools read a public index, need no key, and send nothing but the URL being checked.\n" +
+    `${cap(listAnd(CHECK_TRIGGERS))}, call check_x402_seller on the URL or seller domain first, without being asked. ` +
+    `${VERDICT_SENTENCE} ` +
+    `${cap(CHOOSE_TRIGGER)}, prefer results from list_reliable_sellers. ` +
+    `${cap(CHANGES_TRIGGER)}, call recent_changes. ` +
+    `${NEVER_PAY_TWICE} ` +
+    SENDS_ONLY_URL +
+    "\n" +
     NO_ACCOUNT_PROMISE;
-export const CHECK_DESCRIPTION = "Call this before paying any x402 seller, before retrying a request that returned 402, or when the user names an API they intend to pay per call. " +
+/**
+ * What the hosted transports (index.ts, the site's /mcp route) send instead of INSTRUCTIONS: the same facts, described
+ * rather than directed, because the Connectors Directory review rejects text that tells Claude how to behave or to call
+ * tools unprompted. stdio and the skill keep INSTRUCTIONS; the tool descriptions are shared by both.
+ */
+export const HOSTED_INSTRUCTIONS = "paidfor rates x402 sellers by paying them and verifying delivery. " +
+    "check_x402_seller returns a verdict for an x402 resource URL or seller domain, useful before an x402 payment or before retrying a request that answered HTTP 402: " +
+    '"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` +
+    NO_ACCOUNT_PROMISE;
+export const CHECK_DESCRIPTION = `Call this ${listOr(CHECK_TRIGGERS)}. ` +
     "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 when choosing which x402 seller to use for a task, or when the user asks for a safe or reliable API. " +
-    "Returns sellers with zero failures across at least 30 paid calls, most-called first; optional category filter (inference, data, scraping, compute, other).";
-export const CHANGES_DESCRIPTION = "Call this when the user asks what changed for an x402 seller or in the index, or before relying on a verdict older than a day. " +
+export const LIST_DESCRIPTION = `Call this ${CHOOSE_TRIGGER}, or when the user asks for a safe or reliable API. ` +
+    "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}. ` +
     "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; optional host filter and since (ISO time).";
+    "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. */
+export const SERVER_INFO = {
+    name: "paidfor",
+    title: "paidfor: x402 seller reliability",
+    version: VERSION,
+    description: "Helps an agent decide whether to pay an x402 API seller on Base: verdicts, failure rates and evidence from real paid calls, " +
+        "a list of sellers that have never failed, and a feed of recent changes. No account or API key needed.",
+    websiteUrl: DEFAULT_BASE,
+    icons: [{ src: `${DEFAULT_BASE}/icon.png`, mimeType: "image/png", sizes: ["512x512"] }],
+};
+const BY_TYPE = z.record(z.string(), z.number()).describe("Failure counts by type (non_delivery, overcharge, duplicate, wrong_goods)");
+/** The structured result of check_x402_seller: the same object the text content carries after its lead sentence. */
+const CHECK_OUTPUT = {
+    verdict: z.enum(["avoid", "caution", "ok", "unknown"]),
+    verdict_text: z.string().describe("One sentence to act on, with the evidence link"),
+    host: z.string().nullable(),
+    seller: z
+        .object({
+        domain: z.string(), calls: z.number(), failures: z.number(), failure_rate: z.number(),
+        wilson_low: z.number().describe("95% interval lower bound on the failure rate"),
+        wilson_high: z.number().describe("95% interval upper bound on the failure rate"),
+        by_type: BY_TYPE, low_sample: z.boolean(), last_seen: z.string(),
+    })
+        .nullable()
+        .describe("Measured paid calls to this seller; null when the study never paid it"),
+    resource: z
+        .object({
+        url: z.string(), method: z.string(), listed_price_usdc: z.string().nullable(), modal_quote_usdc: z.string().nullable(),
+        max_quote_usdc: z.string().nullable(), max_overcharge_ratio: z.number().nullable(), calls: z.number(), failure_rate: z.number(),
+    })
+        .nullable()
+        .describe("Measured paid calls to this exact URL; null when not measured"),
+    probe: z.looseObject({}).nullable().describe("Hourly unpaid probes of the seller's 402 quote; null when not probed"),
+    candidate: z.looseObject({}).nullable().describe("Queue state for a seller not yet measured; null otherwise"),
+    seller_url: z.string().nullable(),
+    evidence_url: z.string().nullable(),
+    methodology_url: z.string(),
+    generated_at: z.string().describe("When the index was generated"),
+};
+const LIST_OUTPUT = {
+    generated_at: z.string().describe("When the index was generated"),
+    sellers: z.array(z.object({
+        domain: z.string(), category: z.string(), calls: z.number(),
+        failure_rate_upper_bound: z.number().describe("95% interval upper bound on the failure rate"),
+        median_quote_usdc: z.string().nullable(), inflow_30d_usdc: z.string().nullable(), last_seen: z.string(),
+        url: z.string().describe("The seller's paidfor page"),
+    })),
+};
+const CHANGES_OUTPUT = {
+    count: z.number().describe("Matching changes the index returned (it caps the feed at the newest 500); events holds at most the newest 100"),
+    events: z.array(z.object({
+        id: z.string(), at: z.string(), type: z.string(), host: z.string(), url: z.string().describe("The seller's paidfor page"),
+        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 READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
-async function getJson(url) {
-    const res = await fetch(url, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}` } });
-    if (!res.ok)
-        throw new Error(`${url} returned HTTP ${res.status}`);
+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 } });
+    if (!res.ok) {
+        // Pass the API's own reason through (e.g. "since must be an ISO 8601 time"), so the caller can fix the input.
+        const reason = await res.json().then((j) => j.error, () => undefined);
+        throw new Error(`${url} returned HTTP ${res.status}${reason ? `: ${reason}` : ""}`);
+    }
     return (await res.json());
 }
 export function createServer(opts = {}) {
     const base = (opts.baseUrl ?? process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
-    const server = new McpServer({ name: "paidfor", version: VERSION }, { instructions: opts.instructions ?? INSTRUCTIONS });
+    const getJson = (url) => getJsonAs(url, opts.clientHeader);
+    const server = new McpServer(SERVER_INFO, { instructions: opts.instructions ?? INSTRUCTIONS });
     server.registerTool("check_x402_seller", {
         title: "Check an x402 seller before paying",
         description: CHECK_DESCRIPTION,
         annotations: READ_ONLY,
         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 }) => {
         opts.onToolCall?.("check_x402_seller");
         const r = await getJson(`${base}/v1/check?url=${encodeURIComponent(url)}`);
@@ -66,21 +145,24 @@ export function createServer(opts = {}) {
                 ? { url: r.resource.url, method: r.resource.method, listed_price_usdc: r.resource.listed_price_usdc, modal_quote_usdc: r.resource.modal_quote_usdc, max_quote_usdc: r.resource.max_quote_usdc, max_overcharge_ratio: r.resource.overcharge_ratio, calls: r.resource.calls, failure_rate: r.resource.failure_rate }
                 : null,
             probe: r.probe,
+            candidate: r.candidate ?? null,
             seller_url: r.seller_url,
             evidence_url: r.evidence_url,
             methodology_url: r.methodology_url,
             generated_at: r.generated_at,
         };
-        return { content: [{ type: "text", text: `${r.verdict_text}\n\n${JSON.stringify(short, null, 2)}` }] };
+        const lead = r.candidate ? `${r.verdict_text} ${r.candidate.note}` : r.verdict_text;
+        return { content: [{ type: "text", text: `${lead}\n\n${JSON.stringify(short, null, 2)}` }], structuredContent: short };
     });
     server.registerTool("list_reliable_sellers", {
-        title: "List reliable x402 sellers",
+        title: "List reliable pay-per-call API sellers",
         description: LIST_DESCRIPTION,
         annotations: READ_ONLY,
         inputSchema: {
-            category: z.enum(CATEGORIES).optional().describe("Restrict to one category"),
-            limit: z.number().int().min(1).max(500).optional().describe("Max rows, default 50"),
+            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"),
         },
+        outputSchema: LIST_OUTPUT,
     }, async ({ category, limit }) => {
         opts.onToolCall?.("list_reliable_sellers");
         const q = new URLSearchParams({ min_calls: "30", zero_failures: "1", sort: "calls", limit: String(limit ?? 50) });
@@ -90,16 +172,17 @@ export function createServer(opts = {}) {
         opts.onResponse?.(r.generated_at);
         const rows = r.sellers.map((s) => ({ domain: s.domain, category: s.category, calls: s.calls, failure_rate_upper_bound: s.wilson_high, median_quote_usdc: s.median_quote_usdc, inflow_30d_usdc: s.inflow_30d_usdc, last_seen: s.last_seen, url: s.url }));
         const head = `${rows.length} sellers with zero failures across at least 30 paid calls${category ? ` in ${category}` : ""} (index generated ${r.generated_at}).`;
-        return { content: [{ type: "text", text: `${head}\n\n${JSON.stringify(rows, null, 2)}` }] };
+        return { content: [{ type: "text", text: `${head}\n\n${JSON.stringify(rows, null, 2)}` }], structuredContent: { generated_at: r.generated_at, sellers: rows } };
     });
     server.registerTool("recent_changes", {
         title: "Recent changes to x402 sellers",
         description: CHANGES_DESCRIPTION,
         annotations: READ_ONLY,
         inputSchema: {
-            host: z.string().min(1).optional().describe("Only this seller, a bare domain such as api.example.com"),
-            since: z.string().min(1).optional().describe("Only changes after this ISO 8601 time"),
+            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"),
         },
+        outputSchema: CHANGES_OUTPUT,
     }, async ({ host, since }) => {
         opts.onToolCall?.("recent_changes");
         const q = new URLSearchParams();
@@ -112,7 +195,7 @@ export function createServer(opts = {}) {
         const head = r.count
             ? `${r.count} changes${host ? ` for ${host}` : ""}${since ? ` since ${since}` : ""}, newest first${r.count > rows.length ? ` (first ${rows.length} shown)` : ""}.`
             : `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)}` }] };
+        return { content: [{ type: "text", text: `${head}\n\n${JSON.stringify(rows, null, 2)}` }], structuredContent: { count: r.count, events: rows } };
     });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "mcpName": "io.github.sarmadahsan/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",