@paidfor/mcp 0.1.0 → 0.2.1

package/README.md

@@ -2,14 +2,30 @@
 
 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.
+
 Two tools:
 
 - `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.
 
+On initialize the server sends `instructions` telling the client to call `check_x402_seller` before any x402 payment or retry, unprompted, and how to act on each verdict; the text is `INSTRUCTIONS` in `src/server.ts`, shared by every transport. Per-client setup: https://paidfor.dev/install.
+
 Both read the public JSON API (`GET https://paidfor.dev/v1/check`, `GET https://paidfor.dev/v1/sellers`). No keys, no rate limit for now.
 
-## Claude Desktop
+## 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`:
+
+```json
+{ "mcpServers": { "paidfor": { "url": "https://mcp.paidfor.dev/mcp" } } }
+```
+
+```json
+{ "mcpServers": { "paidfor": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.paidfor.dev/mcp"] } } }
+```
+
+## Stdio (Claude Desktop, Cursor, anything that runs a command)
 
 ```json
 {
@@ -19,16 +35,34 @@ Both read the public JSON API (`GET https://paidfor.dev/v1/check`, `GET https://
 }
 ```
 
-## Cursor / any Streamable HTTP client
-
-```json
-{ "mcpServers": { "paidfor": { "url": "https://paidfor.dev/mcp" } } }
-```
-
 ## Run the HTTP service yourself
 
+This folder is a standalone Node project (own `package.json` and `pnpm-lock.yaml`):
+
 ```bash
-npm install && npm run build && PORT=3402 node dist/http.js
+pnpm install && pnpm build && pnpm start      # node dist/index.js on 0.0.0.0:$PORT (default 3000)
 ```
 
-`PAIDFOR_URL` overrides the site origin it reads from. `railway up` or `fly launch` in this folder deploys it with the included Dockerfile.
+- `PORT` (default `3000`), `HOST` (default `0.0.0.0`).
+- `PAIDFOR_API_BASE` (default `https://paidfor.dev`): the site it reads from. The older `PAIDFOR_URL` still works.
+- `GET /mcp` without `Accept: text/event-stream`, `GET /status` and `GET /health` all return `{ ok, site, data_generated_at, uptime_s, tools, ... }`; `POST /mcp` is the MCP endpoint. Behind Manufact's gateway `/health` is answered by the gateway, so use `/mcp` or `/status` there.
+
+The server is plain `@modelcontextprotocol/sdk`; there is no platform SDK in the dependencies, so the same folder runs on any Node host.
+
+## Where it is deployed
+
+Manufact Cloud, from the `mcp/` subfolder of `sarmadahsan/paidfor-index` (root directory `mcp`), on the **Node auto-detect path**: `package.json` plus `pnpm-lock.yaml` select pnpm, the pinned `packageManager` version is used, and the `build` then `start` scripts run. There is deliberately no `Dockerfile` at this level, since Manufact would use one as-is; the container build lives in `deploy/Dockerfile` for the exit path (Fly, Railway, any VM), see `deploy/README.md`. The custom domain `mcp.paidfor.dev` is a CNAME to Manufact; the slug URL Manufact assigns keeps working too.
+
+Usage is counted by Manufact's gateway (every `tools/call` with client and session); the service itself keeps no counters. The site's own `/mcp` route serves the same server for the case where the hosted one is down.
+
+## Trigger eval
+
+`pnpm build && pnpm eval` runs ten user messages that never mention paidfor through the Anthropic API (`ANTHROPIC_API_KEY` from the environment or an untracked `eval/.env`; model `claude-sonnet-5-5` or `EVAL_MODEL`) with the server's tools and instructions attached, by default with the tools deferred as Claude Code presents them, and prints which ones called the right tool first. Results by date in `eval/RESULTS.md`.
+
+## Claude Desktop extension
+
+`pnpm mcpb` bundles the stdio server with esbuild, writes `manifest.json` at the package version, validates and packs it with `@anthropic-ai/mcpb`, and copies it to the site's `public/paidfor.mcpb` (served at https://paidfor.dev/paidfor.mcpb).
+
+## 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`.

package/dist/index.js

@@ -0,0 +1,78 @@
+/**
+ * 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
+ * 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 { createServer as createHttpServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { 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";
+const started = Date.now();
+/** generated_at of the paidfor-data export as last seen in a tool response (or the boot-time summary). */
+let dataGeneratedAt = null;
+const noteGeneratedAt = (g) => {
+    if (g)
+        dataGeneratedAt = g;
+};
+fetch(`${base}/v1/summary`, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}` } })
+    .then((r) => (r.ok ? r.json() : null))
+    .then((j) => noteGeneratedAt(j?.generated_at))
+    .catch(() => undefined);
+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 });
+    res.end(JSON.stringify(body, null, 2));
+};
+createHttpServer(async (req, res) => {
+    const path = (req.url ?? "/").split("?")[0].replace(/\/+$/, "") || "/";
+    if (req.method === "OPTIONS") {
+        res.writeHead(204, CORS);
+        res.end();
+        return;
+    }
+    const status = () => ({
+        ok: true,
+        service: "paidfor-mcp",
+        name: "paidfor",
+        version: VERSION,
+        transport: "streamable-http",
+        endpoint: "/mcp",
+        site: base,
+        data_generated_at: dataGeneratedAt,
+        uptime_s: Math.round((Date.now() - started) / 1000),
+        tools: TOOL_NAMES,
+        usage: "POST JSON-RPC 2.0 to /mcp with Accept: application/json, text/event-stream",
+        docs: `${base}/api`,
+    });
+    if (path === "/health" || path === "/status") {
+        sendJson(res, 200, status());
+        return;
+    }
+    if (path === "/" || path === "/mcp") {
+        if (req.method === "GET" && !(req.headers.accept ?? "").includes("text/event-stream")) {
+            sendJson(res, 200, status());
+            return;
+        }
+        for (const [k, v] of Object.entries(CORS))
+            res.setHeader(k, v);
+        const server = createServer({ baseUrl: base, onResponse: noteGeneratedAt });
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+        return;
+    }
+    sendJson(res, 404, { error: "not found", endpoints: ["/mcp", "/status", "/health"] });
+}).listen(port, host, () => {
+    console.log(`paidfor MCP ${VERSION} (streamable http) listening on ${host}:${port}, MCP at /mcp, reading ${base}`);
+});

package/dist/server.d.ts

@@ -1,16 +1,27 @@
 /**
  * The paidfor MCP server. One factory, three transports: stdio (npx @paidfor/mcp),
- * the standalone Streamable HTTP service (http.ts) and the Next.js route at /mcp.
+ * the hosted Streamable HTTP service (index.ts) and the Next.js route at /mcp on the site.
  * Both tools are thin readers of the public JSON API; the verdict logic lives on the site.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.1";
 export declare const DEFAULT_BASE = "https://paidfor.dev";
 export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers"];
+/**
+ * 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.
+ */
+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. */
+export declare const INSTRUCTIONS: string;
+export declare const CHECK_DESCRIPTION: string;
+export declare const LIST_DESCRIPTION: string;
 export type ServerOptions = {
-    /** Site origin to read from. Defaults to PAIDFOR_URL or https://paidfor.dev. */
+    /** Site origin to read from. Defaults to PAIDFOR_API_BASE (or the older PAIDFOR_URL) or https://paidfor.dev. */
     baseUrl?: string;
-    /** Called with the tool name on every call, for usage counting. */
+    /** Called with the tool name on every call, for usage counting (the site's /mcp route uses it). */
     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;
 };
 export declare function createServer(opts?: ServerOptions): McpServer;

package/dist/server.js

@@ -1,14 +1,37 @@
 /**
  * The paidfor MCP server. One factory, three transports: stdio (npx @paidfor/mcp),
- * the standalone Streamable HTTP service (http.ts) and the Next.js route at /mcp.
+ * the hosted Streamable HTTP service (index.ts) and the Next.js route at /mcp on the site.
  * Both tools are thin readers of the public JSON API; the verdict logic lives on the site.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.1";
 export const DEFAULT_BASE = "https://paidfor.dev";
 export const TOOL_NAMES = ["check_x402_seller", "list_reliable_sellers"];
 const CATEGORIES = ["inference", "data", "scraping", "compute", "other"];
+/**
+ * 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.
+ */
+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. */
+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. " +
+    "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" +
+    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. " +
+    "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).";
+/** Both 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)
@@ -16,22 +39,17 @@ async function getJson(url) {
     return (await res.json());
 }
 export function createServer(opts = {}) {
-    const base = (opts.baseUrl ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
-    const server = new McpServer({ name: "paidfor", version: VERSION }, {
-        instructions: "paidfor.dev pays x402 sellers on Base mainnet and records which ones fail the buyer. " +
-            "Call check_x402_seller with the resource URL or seller domain before paying an x402 402 quote; " +
-            "treat verdict=avoid as a reason not to pay, caution as pay only if the price is small, ok as safe, unknown as no data. " +
-            "list_reliable_sellers returns zero-failure sellers with at least 30 paid calls.",
-    });
+    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: INSTRUCTIONS });
     server.registerTool("check_x402_seller", {
         title: "Check an x402 seller before paying",
-        description: "Look up an x402 resource URL or seller domain in the paidfor.dev index. 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, the resource's listed price, " +
-            "modal quote and max overcharge ratio when known, and links to the seller page and raw evidence.",
+        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") },
     }, async ({ url }) => {
         opts.onToolCall?.("check_x402_seller");
         const r = await getJson(`${base}/v1/check?url=${encodeURIComponent(url)}`);
+        opts.onResponse?.(r.generated_at);
         const short = {
             verdict: r.verdict,
             verdict_text: r.verdict_text,
@@ -52,7 +70,8 @@ export function createServer(opts = {}) {
     });
     server.registerTool("list_reliable_sellers", {
         title: "List reliable x402 sellers",
-        description: "Sellers with zero failures across at least 30 paid calls in the paidfor.dev index, most-called first. Optional category filter: inference, data, scraping, compute, other.",
+        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"),
@@ -63,6 +82,7 @@ export function createServer(opts = {}) {
         if (category)
             q.set("category", category);
         const r = await getJson(`${base}/v1/sellers?${q}`);
+        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)}` }] };

package/package.json

@@ -1,29 +1,53 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
+  "mcpName": "io.github.sarmadahsan/paidfor",
   "description": "MCP server for the paidfor.dev x402 seller index: check_x402_seller and list_reliable_sellers",
   "license": "MIT",
   "type": "module",
-  "bin": { "paidfor-mcp": "./dist/stdio.js" },
-  "publishConfig": { "access": "public" },
+  "bin": {
+    "paidfor-mcp": "dist/stdio.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "./dist/server.js",
-  "exports": { ".": "./dist/server.js" },
-  "files": ["dist", "README.md"],
-  "engines": { "node": ">=20" },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "start": "node dist/http.js",
-    "dev": "tsc -p tsconfig.json && node dist/http.js",
-    "prepublishOnly": "pnpm build"
+  "exports": {
+    ".": "./dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^1.3.0",
     "@types/node": "^22",
     "typescript": "^5.9"
   },
-  "repository": { "type": "git", "url": "https://github.com/sarmadahsan/paidfor-index", "directory": "mcp" },
-  "keywords": ["mcp", "x402", "paidfor", "base", "usdc"]
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sarmadahsan/paidfor-index.git",
+    "directory": "mcp"
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "paidfor",
+    "base",
+    "usdc"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "tsc -p tsconfig.json && node dist/index.js",
+    "eval": "node --env-file-if-exists=eval/.env eval/run.mjs",
+    "mcpb": "node mcpb/build.mjs"
+  }
+}

package/dist/http.js

@@ -1,49 +0,0 @@
-/**
- * Standalone Streamable HTTP service (Railway / Fly / any Node host). Stateless: one
- * transport per request. GET /health for the platform health check.
- */
-import { createServer as createHttpServer } from "node:http";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createServer, TOOL_NAMES, VERSION } from "./server.js";
-const port = Number(process.env.PORT ?? 3402);
-const counts = new Map();
-const bump = (k) => counts.set(k, (counts.get(k) ?? 0) + 1);
-const CORS = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS", "Access-Control-Allow-Headers": "*" };
-createHttpServer(async (req, res) => {
-    const path = (req.url ?? "/").split("?")[0];
-    if (req.method === "OPTIONS") {
-        res.writeHead(204, CORS);
-        res.end();
-        return;
-    }
-    if (path === "/health") {
-        res.writeHead(200, { "Content-Type": "text/plain", ...CORS });
-        res.end("ok");
-        return;
-    }
-    if (path === "/usage") {
-        res.writeHead(200, { "Content-Type": "application/json", ...CORS });
-        res.end(JSON.stringify(Object.fromEntries(counts)));
-        return;
-    }
-    if (path === "/" || path === "/mcp") {
-        if (req.method === "GET" && !(req.headers.accept ?? "").includes("text/event-stream")) {
-            res.writeHead(200, { "Content-Type": "application/json", ...CORS });
-            res.end(JSON.stringify({ name: "paidfor", version: VERSION, transport: "streamable-http", tools: TOOL_NAMES, usage: "POST JSON-RPC 2.0 to this URL" }));
-            return;
-        }
-        bump("request");
-        for (const [k, v] of Object.entries(CORS))
-            res.setHeader(k, v);
-        const server = createServer({ onToolCall: bump });
-        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-        res.on("close", () => { void transport.close(); void server.close(); });
-        await server.connect(transport);
-        await transport.handleRequest(req, res);
-        return;
-    }
-    res.writeHead(404, CORS);
-    res.end();
-}).listen(port, () => {
-    console.log(`paidfor MCP (streamable http) listening on :${port}, reading ${process.env.PAIDFOR_URL ?? "https://paidfor.dev"}`);
-});