@paidfor/mcp 0.3.0 → 0.3.1

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 { CLIENT_HEADER, createServer, DEFAULT_BASE, 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": CLIENT_HEADER } })
     .then((r) => (r.ok ? r.json() : null))
     .then((j) => noteGeneratedAt(j?.generated_at))
     .catch(() => undefined);

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,10 @@
  * 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.1";
+/** 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 DEFAULT_BASE = "https://paidfor.dev";
 export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
 /**
@@ -13,7 +16,8 @@ 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;
 export declare const CHECK_DESCRIPTION: string;
 export declare const LIST_DESCRIPTION: string;

package/dist/server.js

@@ -6,7 +6,11 @@
  */
 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.1";
+/** Sent on every request to the index so usage can be counted by channel (never anything else). */
+export const CLIENT_HEADER = `mcp/${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,29 +20,29 @@ 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. " +
+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. " +
+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).";
-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 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 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}` } });
+    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}`);
     return (await res.json());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",