@paidfor/mcp 0.3.1 → 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 { CLIENT_HEADER, 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}`, "X-Paidfor-Client": CLIENT_HEADER } })
+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/server.d.ts

@@ -6,9 +6,11 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export * from "./rules.js";
-export declare const VERSION = "0.3.1";
+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.1";
+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"];
 /**
@@ -19,6 +21,12 @@ 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.
  * 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;
@@ -29,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

@@ -8,9 +8,11 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.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";
 export * from "./rules.js";
-export const VERSION = "0.3.1";
+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"];
@@ -31,30 +33,103 @@ export const INSTRUCTIONS = "paidfor rates x402 sellers by paying them and verif
     SENDS_ONLY_URL +
     "\n" +
     NO_ACCOUNT_PROMISE;
+/**
+ * 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 ${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; optional category filter (inference, data, scraping, compute, other).";
+    "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}`, "X-Paidfor-Client": CLIENT_HEADER } });
-    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)}`);
@@ -70,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) });
@@ -94,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();
@@ -116,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.1",
+  "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",