@paidfor/mcp 0.5.0 → 0.7.0

package/dist/link.js

@@ -0,0 +1,109 @@
+/**
+ * Linking a wallet to a paidfor account from the command line, as a device flow: `POST /v1/team/link` returns a short
+ * code a person checks and approves in the browser, and `POST /v1/team/link/poll` returns the team key once, after the
+ * approval. The device code and the team key are secrets: they are returned to the caller and never put in a message.
+ */
+import { assertKeySafeBase } from "./wallet.js";
+/** A non-empty string. */
+const str = (v) => typeof v === "string" && v.length > 0;
+/** POSTs JSON and reads the JSON answer; follows no redirect, gives up after 15 seconds. */
+async function postJson(fetchFn, url, body, client) {
+    const res = await fetchFn(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json", "X-Paidfor-Client": client },
+        body: JSON.stringify(body),
+        redirect: "error",
+        signal: AbortSignal.timeout(15_000),
+    });
+    const json = (await res.json().catch(() => ({})));
+    return { status: res.status, json: json && typeof json === "object" ? json : {} };
+}
+/** Starts a link. Throws an Error whose message is safe to show (never a code or a key) when it cannot. */
+export async function startLink(o) {
+    const base = o.baseUrl.replace(/\/$/, "");
+    assertKeySafeBase(base);
+    let r;
+    try {
+        r = await postJson(o.fetchFn ?? fetch, `${base}/v1/team/link`, { address: o.address, label: o.label, client: o.client }, o.client);
+    }
+    catch (e) {
+        throw new Error(`could not reach ${base}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (r.status === 429)
+        throw new Error("paidfor is taking too many link requests right now (HTTP 429)");
+    if (r.status === 503)
+        throw new Error("paidfor cannot link accounts right now (HTTP 503)");
+    if (r.status !== 201 && r.status !== 200)
+        throw new Error(`paidfor answered HTTP ${r.status}${str(r.json.error) ? `: ${r.json.error.slice(0, 200)}` : ""}`);
+    const j = r.json;
+    const interval = typeof j.interval === "number" && Number.isFinite(j.interval) && j.interval > 0 ? j.interval : 5;
+    if (!str(j.user_code) || !str(j.device_code) || !str(j.verify_url) || !str(j.expires_at) || Number.isNaN(Date.parse(j.expires_at))) {
+        throw new Error("paidfor's answer to the link request could not be read");
+    }
+    return { user_code: j.user_code, device_code: j.device_code, verify_url: j.verify_url, expires_at: j.expires_at, interval };
+}
+/**
+ * Polls until the link is approved, denied, expired or already used, or `expires_at` passes. A network error or a 5xx
+ * is tried again on the next tick; a 429 slows the polling down. `immediate` asks once before the first wait (a link
+ * resumed from an earlier run); `stopAt` (epoch ms) gives up with { kind: "pending" } when the next poll would be later.
+ */
+export async function pollLink(o) {
+    const base = o.baseUrl.replace(/\/$/, "");
+    const fetchFn = o.fetchFn ?? fetch;
+    const sleep = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = o.now ?? Date.now;
+    const deadline = Date.parse(o.start.expires_at);
+    let interval = o.start.interval;
+    let first = true;
+    const stillPending = { kind: "pending", message: "not approved yet" };
+    // Whether to wait for another tick, or stop here because the window closes first.
+    /** Whether another poll fits before stopAt. */
+    const goOn = () => o.stopAt === undefined || now() + interval * 1000 <= o.stopAt;
+    for (;;) {
+        if (!(first && o.immediate))
+            await sleep(interval * 1000);
+        first = false;
+        if (now() >= deadline)
+            return { kind: "expired", message: "the code expired before it was approved" };
+        let r;
+        try {
+            r = await postJson(fetchFn, `${base}/v1/team/link/poll`, { device_code: o.start.device_code }, o.client);
+        }
+        catch {
+            if (!goOn())
+                return stillPending;
+            continue; // try again on the next tick, until the deadline
+        }
+        if (r.status === 410)
+            return { kind: "used", message: "this link was already used" };
+        if (r.status === 429) {
+            interval += 5;
+            if (!goOn())
+                return stillPending;
+            continue;
+        }
+        if (r.status >= 500) {
+            if (!goOn())
+                return stillPending;
+            continue;
+        }
+        if (r.status !== 200)
+            return { kind: "failed", message: `paidfor answered HTTP ${r.status}${str(r.json.error) ? `: ${r.json.error.slice(0, 200)}` : ""}` };
+        switch (r.json.status) {
+            case "pending":
+                if (!goOn())
+                    return stillPending;
+                continue;
+            case "approved":
+                if (!str(r.json.team_key))
+                    return { kind: "failed", message: "paidfor approved the link but sent no key" };
+                return { kind: "approved", team_key: r.json.team_key, team_name: str(r.json.team_name) ? r.json.team_name : "your account" };
+            case "denied":
+                return { kind: "denied", message: "the link was denied in the browser" };
+            case "expired":
+                return { kind: "expired", message: "the code expired before it was approved" };
+            default:
+                return { kind: "failed", message: "paidfor's answer could not be read" };
+        }
+    }
+}

package/dist/pay.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Receipt, type SafeNetwork } from "@paidfor/x402-safe-fetch";
+import { type TeamDecision } from "./team.js";
 import { type Limits, type LoadedWallet } from "./wallet.js";
 export declare const PAY_TOOL_NAMES: readonly ["pay_x402", "fetch_paid_url", "wallet_status"];
 /** The second name for the pay_x402 handler, registered only with PayOptions.fetchAlias (PAIDFOR_FETCH_ALIAS=1 on stdio). */
@@ -8,7 +9,7 @@ export declare const BODY_LIMIT_BYTES: number;
 /** When to reuse an intent_id: a retry of the same purchase only. A date-only id (observed: "bitcoin-price-2026-11-01" chosen in three fresh sessions) replays instead of buying. */
 export declare const INTENT_RULE: string;
 export declare const PAY_INSTRUCTIONS: string;
-/** The stdio server's instructions with a wallet configured: the pay paragraph goes in before the no-account promise, which stays last. */
+/** The stdio server's instructions with a wallet configured: the pay paragraph goes last. */
 export declare const INSTRUCTIONS_WITH_PAY: string;
 export declare const PAY_TITLE = "Fetch a paid (x402) URL, paying with your wallet";
 export declare const PAY_ALIAS_TITLE = "Fetch a paid URL (same as pay_x402)";
@@ -30,6 +31,10 @@ export type PayOptions = {
     balanceOf?: (address: `0x${string}`) => Promise<bigint>;
     /** Also register the same handler as fetch_paid_url (PAY_ALIAS). Off by default; stdio turns it on with PAIDFOR_FETCH_ALIAS=1. */
     fetchAlias?: boolean;
+    /** PAIDFOR_TEAM_KEY: ask the team's rules before every payment and report the outcome. Stdio only. */
+    teamKey?: string;
+    /** Tests only: how long to wait before the second try of an outcome report. */
+    teamRetryDelayMs?: number;
 };
 /** The receipt as pay_x402 reports it: what was paid, to whom, the proof, and how to check it. */
 export declare function receiptSummary(r: Receipt): {
@@ -57,6 +62,16 @@ export declare function receiptSummary(r: Receipt): {
 export declare function describeAge(ms: number): string;
 /** The first line of a replayed pay_x402 result: the age and time of the stored result, so a second genuine purchase is not mistaken for a retry. */
 export declare function replayHead(r: Receipt, now?: number): string;
+/** What pay_x402 says when the team's rules, not the seller or the local caps, stop a payment. Nothing was paid in any of these. */
+export declare function teamRefusal(d: Exclude<TeamDecision, {
+    kind: "approve";
+}>, intentId: string, limits: unknown): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
 export declare function truncateBody(body: string): {
     body: string;
     note: string | null;

package/dist/pay.js

@@ -3,13 +3,15 @@
  * user's own wallet and report the verified outcome to the index. Only stdio.ts imports this module;
  * the hosted service (index.ts) and the site's /mcp route never do, because they never hold a key.
  */
+import { randomUUID } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { PaymentRefusedError, SafeFetchError, safeFetch } from "@paidfor/x402-safe-fetch";
 import { createPublicClient, erc20Abi, http } from "viem";
 import { base as baseChain } from "viem/chains";
 import { z } from "zod";
-import { INSTRUCTIONS, NO_ACCOUNT_PROMISE, PAID_URL_SIGNALS, PAY_ROUTING_RULE, PLAIN_FETCH_FAILS } from "./server.js";
+import { INSTRUCTIONS, PAID_URL_SIGNALS, PAY_ROUTING_RULE, PLAIN_FETCH_FAILS } from "./server.js";
+import { TeamClient, outcomeFor } from "./team.js";
 import { SpendLedger, fromMicro, paidforDir, toMicro } from "./wallet.js";
 export const PAY_TOOL_NAMES = ["pay_x402", "fetch_paid_url", "wallet_status"];
 /** The second name for the pay_x402 handler, registered only with PayOptions.fetchAlias (PAIDFOR_FETCH_ALIAS=1 on stdio). */
@@ -27,8 +29,8 @@ export const PAY_INSTRUCTIONS = `${PAY_ROUTING_RULE} ` +
     `${INTENT_RULE} ` +
     "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. */
-export const INSTRUCTIONS_WITH_PAY = INSTRUCTIONS.replace(`\n${NO_ACCOUNT_PROMISE}`, `\n${PAY_INSTRUCTIONS}\n${NO_ACCOUNT_PROMISE}`);
+/** The stdio server's instructions with a wallet configured: the pay paragraph goes last. */
+export const INSTRUCTIONS_WITH_PAY = `${INSTRUCTIONS}\n${PAY_INSTRUCTIONS}`;
 export const PAY_TITLE = "Fetch a paid (x402) URL, paying with your wallet";
 export const PAY_ALIAS_TITLE = "Fetch a paid URL (same as pay_x402)";
 export const PAY_DESCRIPTION = "Fetches a paid (x402) URL end to end: sends the request, handles the HTTP 402 and pays the quoted USDC on Base with the user's own wallet under the configured caps, and returns the response body. " +
@@ -83,6 +85,20 @@ export function replayHead(r, now = Date.now()) {
     const when = at && Number.isFinite(Date.parse(at)) ? `stored ${describeAge(now - Date.parse(at))} ago (${at})` : "stored earlier (time unknown, the original receipt file is gone)";
     return `Replayed the result ${when} for intent ${r.intent_id}; nothing was paid again. If this is a new purchase, call again with a new intent_id.`;
 }
+/** What pay_x402 says when the team's rules, not the seller or the local caps, stop a payment. Nothing was paid in any of these. */
+export function teamRefusal(d, intentId, limits) {
+    const res = (head, detail, isError = false) => text(`${head}\n\n${json({ ...detail, paid: false, intent_id: intentId, limits })}`, isError);
+    switch (d.kind) {
+        case "decline":
+            return res(`Declined by your team's rules: ${d.message}\nNothing was paid.`, { refused: "team_decline", reason: d.reason, ...(d.retry_after !== undefined ? { retry_after: d.retry_after } : {}) });
+        case "needs_approval":
+            return res(`A person has to approve this payment before it can be made. Nothing was paid.\nGive the user this link: ${d.approve_url}\nAfter they approve it, call pay_x402 again with intent_id "${intentId}". The request waits until ${d.expires_at}.${d.message ? ` ${d.message}` : ""}`, { refused: "team_needs_approval", approve_url: d.approve_url, expires_at: d.expires_at });
+        case "already_settled":
+            return res(`This purchase was already paid (settlement ${d.settlement_ref}, outcome ${d.outcome}); nothing was paid again. If this is a new purchase, call again with a new intent_id.`, { refused: "team_already_settled", settlement_ref: d.settlement_ref, outcome: d.outcome });
+        case "failed":
+            return res(`The team's rules could not be checked, so nothing was paid: ${d.message}\nCalling again with intent_id "${intentId}" is safe.`, { refused: "team_authorize_failed" }, true);
+    }
+}
 export function truncateBody(body) {
     const buf = Buffer.from(body, "utf8");
     if (buf.byteLength <= BODY_LIMIT_BYTES)
@@ -103,6 +119,9 @@ export async function registerPayTools(server, o) {
     const base = o.baseUrl.replace(/\/$/, "");
     const address = o.wallet.account.address;
     const logger = { warn: (m) => void process.stderr.write(`${m}\n`) };
+    const team = o.teamKey ? new TeamClient({ baseUrl: base, teamKey: o.teamKey, dir, ...(o.fetch ? { fetch: o.fetch } : {}), warn: logger.warn, ...(o.teamRetryDelayMs !== undefined ? { retryDelayMs: o.teamRetryDelayMs } : {}) }) : null;
+    if (team)
+        void team.flush();
     const payInput = {
         url: z.string().url().describe("The URL to fetch and, if it answers 402, pay for"),
         method: z.string().min(1).max(10).optional().describe("HTTP method, default GET"),
@@ -124,6 +143,20 @@ export async function registerPayTools(server, o) {
             spent_today_usdc: fromMicro(spent),
             ...(max_usd !== undefined && max_usd > o.limits.maxPerCallUsd ? { note: `max_usd ${max_usd} is above PAIDFOR_MAX_PER_CALL_USD; capped at ${o.limits.maxPerCallUsd}` } : {}),
         };
+        // Team mode needs the id before the first call: a person's approval is claimed by asking again with the same one.
+        const intentId = intent_id ?? (team ? randomUUID() : undefined);
+        const asked = {};
+        /** Say what happened to an approved payment. Undefined when the server approved nothing. */
+        const settle = async (r) => {
+            const d = asked.decision;
+            if (!team || d?.kind !== "approve")
+                return undefined;
+            if (!r) {
+                logger.warn(`paidfor-mcp: no receipt for approved intent ${intentId}, so no outcome was reported; the approval keeps counting against the budgets`);
+                return undefined;
+            }
+            return team.report(outcomeFor(r, address, d.auth_ref));
+        };
         const sf = safeFetch(o.wallet.account, {
             maxPerCallUsd: cap,
             maxOverListedRatio: 1.1,
@@ -134,31 +167,48 @@ export async function registerPayTools(server, o) {
             logger,
             ...(o.network ? { network: o.network } : {}),
             ...(o.fetch ? { fetch: o.fetch } : {}),
+            ...(team
+                ? {
+                    authorize: async (q) => {
+                        const d = await team.authorize({ wallet: q.payer, intent_id: q.intentId, resource_url: q.url, pay_to: q.payTo, amount_atomic: q.amountAtomic, network: q.network, asset: q.asset, scheme: q.scheme, protocol: "x402" });
+                        asked.decision = d;
+                        return d.kind === "approve" ? { approve: true, nonce: d.auth_ref, validBefore: d.valid_before } : { approve: false, message: d.message };
+                    },
+                }
+                : {}),
         });
         try {
-            const res = await sf(url, { method: method ?? "GET", headers, body }, { intentId: intent_id });
+            // Owed reports go first: until the server has them it answers the same purchase with pending_settlement.
+            await team?.flush();
+            const res = await sf(url, { method: method ?? "GET", headers, body }, { intentId });
             const r = res.receipt;
             if (r.paid && !r.replayed)
                 await ledger.add(toMicro(r.amount_usdc));
+            const teamReport = await settle(r);
             const { body: out, note } = truncateBody(await res.text());
             const head = r.replayed
                 ? replayHead(r)
                 : r.paid
                     ? `Paid ${r.amount_usdc} USDC to ${r.quote?.pay_to}; the seller answered HTTP ${res.status} (${r.outcome}).`
                     : `No payment was needed; the server answered HTTP ${res.status}.`;
-            return text(`${head}\n\n${json({ status: res.status, receipt: receiptSummary(r), limits, ...(note ? { body_note: note } : {}) })}\n\n--- response body ---\n${out}`);
+            return text(`${head}\n\n${json({ status: res.status, receipt: receiptSummary(r), limits, ...(teamReport ? { team_outcome_report: teamReport } : {}), ...(note ? { body_note: note } : {}) })}\n\n--- response body ---\n${out}`);
         }
         catch (e) {
+            if (asked.decision && asked.decision.kind !== "approve" && e instanceof PaymentRefusedError && e.code === "refused_authorize") {
+                return teamRefusal(asked.decision, e.receipt?.intent_id ?? intentId, limits);
+            }
+            const teamReport = await settle(e instanceof SafeFetchError ? e.receipt : undefined);
+            const reported = teamReport ? { team_outcome_report: teamReport } : {};
             if (e instanceof PaymentRefusedError) {
                 const why = e.code === "refused_max_per_call" && dailyBinds
                     ? `refused: today's cap of ${o.limits.dailyCapUsd} USD (PAIDFOR_DAILY_CAP_USD) leaves ${fromMicro(Math.max(leftMicro, 0))} USDC. ${e.message}`
                     : e.code === "refused_max_per_call"
                         ? `refused: the quote is above this call's cap of ${cap} USD (max_usd, capped by PAIDFOR_MAX_PER_CALL_USD ${o.limits.maxPerCallUsd}). ${e.message}`
                         : `refused: ${e.message}`;
-                return text(`${why}\nNothing was paid.\n\n${json({ refused: e.code, paid: false, seller_url: e.sellerUrl ?? e.receipt?.seller.seller_url ?? null, intent_id: e.receipt?.intent_id ?? intent_id ?? null, limits })}`);
+                return text(`${why}\nNothing was paid.\n\n${json({ refused: e.code, paid: false, seller_url: e.sellerUrl ?? e.receipt?.seller.seller_url ?? null, intent_id: e.receipt?.intent_id ?? intentId ?? null, limits, ...reported })}`);
             }
             if (e instanceof SafeFetchError) {
-                return text(`${e.code}: ${e.message}\n\n${json({ error: e.code, paid: e.receipt?.paid ?? false, receipt: e.receipt ? receiptSummary(e.receipt) : null, limits })}`, true);
+                return text(`${e.code}: ${e.message}\n\n${json({ error: e.code, paid: e.receipt?.paid ?? false, receipt: e.receipt ? receiptSummary(e.receipt) : null, limits, ...reported })}`, true);
             }
             return text(`error: ${e instanceof Error ? e.message : String(e)}`, true);
         }
@@ -193,6 +243,7 @@ export async function registerPayTools(server, o) {
             max_per_call_usd: o.limits.maxPerCallUsd,
             daily_cap_usd: o.limits.dailyCapUsd,
             spent_today_usdc: fromMicro(spent),
+            ...(team ? { team_mode: true } : {}),
         };
         return text(`${usdc === null ? "Balance unavailable" : `${usdc} USDC on Base`} at ${address}.\n\n${json(s)}`);
     });

package/dist/pending.d.ts

@@ -0,0 +1,25 @@
+/** The saved link: what `link` needs to poll it, register the wallet and write the configs. */
+export type PendingLink = {
+    v: 1;
+    device_code: string;
+    user_code: string;
+    verify_url: string;
+    expires_at: string;
+    interval: number;
+    base_url: string;
+    label: string;
+    key_file: string;
+    address: string;
+    clients: string[];
+    /** Set once the link was approved but the registration failed: the key handed over, kept for the retry. */
+    team_key?: string;
+    team_name?: string;
+};
+/** Where the record lives: ~/.paidfor/link-pending.json. */
+export declare const pendingPath: (home: string) => string;
+/** The saved record, or null when there is none or it is unreadable or malformed. Never throws. */
+export declare function readPending(home: string): Promise<PendingLink | null>;
+/** Saves the record atomically (dir 700, file 600), replacing any earlier one. Returns the file's path. */
+export declare function writePending(home: string, rec: Omit<PendingLink, "v">): Promise<string>;
+/** Removes the record; a record already gone is fine. */
+export declare function deletePending(home: string): Promise<void>;

package/dist/pending.js

@@ -0,0 +1,66 @@
+/**
+ * A link started by `init --yes --link` (or `link --yes`) that nobody waited for: an agent's shell returns output only
+ * when the command exits, so the command prints the approval link, saves this record and exits, and a later
+ * `paidfor-mcp link` resumes it. ~/.paidfor/link-pending.json (dir 700, file 600, atomic write) is the only place the
+ * device code is ever written. A record that cannot be read is treated as absent and replaced.
+ *
+ * A record that carries `team_key` means "approved, registration owed": the browser approval went through and the key
+ * was handed over (once), but registering the wallet failed. `link` retries the registration with that key instead of
+ * asking for a new approval. Such a record does not expire with the link: the key does not.
+ */
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { paidforDir } from "./wallet.js";
+/** Where the record lives: ~/.paidfor/link-pending.json. */
+export const pendingPath = (home) => join(paidforDir(home), "link-pending.json");
+/** A non-empty string. */
+const str = (v) => typeof v === "string" && v.length > 0;
+/** The saved record, or null when there is none or it is unreadable or malformed. Never throws. */
+export async function readPending(home) {
+    try {
+        const j = JSON.parse(await readFile(pendingPath(home), "utf8"));
+        if (!j || typeof j !== "object")
+            return null;
+        const ok = str(j.device_code) &&
+            str(j.user_code) &&
+            str(j.verify_url) &&
+            str(j.expires_at) &&
+            !Number.isNaN(Date.parse(j.expires_at)) &&
+            typeof j.interval === "number" &&
+            j.interval > 0 &&
+            str(j.base_url) &&
+            typeof j.label === "string" &&
+            str(j.key_file) &&
+            str(j.address) &&
+            Array.isArray(j.clients) &&
+            j.clients.every((c) => typeof c === "string") &&
+            (j.team_key === undefined || str(j.team_key)) &&
+            (j.team_name === undefined || typeof j.team_name === "string");
+        return ok ? j : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Saves the record atomically (dir 700, file 600), replacing any earlier one. Returns the file's path. */
+export async function writePending(home, rec) {
+    const dir = paidforDir(home);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700).catch(() => undefined);
+    const file = pendingPath(home);
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify({ v: 1, ...rec }) + "\n", { mode: 0o600 });
+        await chmod(tmp, 0o600);
+        await rename(tmp, file);
+    }
+    catch (e) {
+        await unlink(tmp).catch(() => undefined);
+        throw e;
+    }
+    return file;
+}
+/** Removes the record; a record already gone is fine. */
+export async function deletePending(home) {
+    await unlink(pendingPath(home)).catch(() => undefined);
+}

package/dist/rules.js

@@ -34,7 +34,7 @@ export const RULES_SHA = "7258b901f6577a02dfe997416d3de61e122f5da21476eb686dd1c1
  */
 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.";
+    "Free; 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",

package/dist/server.d.ts

@@ -1,11 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { REPORT_OUTCOMES } from "./rules.js";
 export * from "./rules.js";
-export declare const VERSION = "0.4.1";
+export declare const VERSION = "0.7.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.4.1";
+export declare const CLIENT_HEADER = "mcp/0.7.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.4.1";
+export declare const HOSTED_CLIENT_HEADER = "mcp-hosted/0.7.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`),
@@ -17,11 +17,6 @@ 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", "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.
- */
-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;

package/dist/server.js

@@ -10,7 +10,7 @@ import { ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTempl
 import { z } from "zod";
 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.4.1";
+export const VERSION = "0.7.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. */
@@ -35,12 +35,6 @@ export const taggedClientHeader = (tag) => (tag ? `${HOSTED_CLIENT_HEADER}+${tag
 export const DEFAULT_BASE = "https://paidfor.dev";
 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),
- * 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.
  * 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. " +
@@ -50,9 +44,7 @@ export const INSTRUCTIONS = "paidfor rates x402 sellers by paying them and verif
     `${cap(CHANGES_TRIGGER)}, call recent_changes. ` +
     `${NEVER_PAY_TWICE} ` +
     `${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;
+    `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}.`;
 /**
  * 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
@@ -64,8 +56,7 @@ export const HOSTED_INSTRUCTIONS = "paidfor rates x402 sellers by paying them an
     "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} ` +
-    `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;
+    `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.`;
 /** 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)}.`,
@@ -88,7 +79,7 @@ export const SERVER_INFO = {
     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.",
+        "a list of sellers that have never failed, and a feed of recent changes.",
     websiteUrl: DEFAULT_BASE,
     icons: [{ src: `${DEFAULT_BASE}/icon.png`, mimeType: "image/png", sizes: ["512x512"] }],
 };

package/dist/setup.d.ts

@@ -6,6 +6,9 @@ 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.";
+/** The one-command install (`paidfor-mcp init`): detects the clients, offers a wallet and a link to an account, writes the config. */
+export declare const INIT_COMMAND: (pkg: string) => string;
+/** The Claude Code command that adds the hosted server, user scope. */
 export declare const claudeCodeCommand: (url: string) => string;
 export declare const cursorServer: (url: string) => {
     url: string;
@@ -43,6 +46,5 @@ export declare const MANIFEST_META: {
         skill_url: string;
         privacy_url: string;
         auth: string;
-        no_account: string;
     };
 };

package/dist/setup.js

@@ -3,7 +3,7 @@
  * /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";
+import { DEFAULT_BASE, HOSTED_INSTRUCTIONS, 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`;
@@ -12,6 +12,9 @@ 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.";
+/** The one-command install (`paidfor-mcp init`): detects the clients, offers a wallet and a link to an account, writes the config. */
+export const INIT_COMMAND = (pkg) => `npx -y ${pkg} init`;
+/** The Claude Code command that adds the hosted server, user scope. */
 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"))}`;
@@ -57,7 +60,7 @@ export function setupPageHtml({ endpoint, statusUrl }) {
     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.">
+<meta name="description" content="Set up the paidfor MCP server: check an x402 seller before your agent pays.">
 <link rel="icon" href="${DEFAULT_BASE}/icon.png"><link rel="alternate" type="application/json" href="${esc(MANIFEST_URL)}">
 <style>${CSS}</style></head>
 <body><main>
@@ -91,8 +94,6 @@ ${pre(cursorConfig(HOSTED_URL))}
 <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>
@@ -113,6 +114,5 @@ export const MANIFEST_META = {
         skill_url: SKILL_URL,
         privacy_url: PRIVACY_URL,
         auth: "none",
-        no_account: NO_ACCOUNT_PROMISE,
     },
 };

package/dist/stdio.js

@@ -2,14 +2,28 @@
 /**
  * `npx @paidfor/mcp`: the stdio server. With PAIDFOR_WALLET_KEY_FILE (or PAIDFOR_WALLET_KEY) set it also
  * registers pay_x402 and wallet_status; without one it is the same read-only server as the hosted one.
+ * `paidfor-mcp init` does the whole install: finds the MCP clients, offers a wallet and a link to an account, writes the config.
  * `paidfor-mcp wallet new` writes a fresh key to ~/.paidfor/wallet.key (mode 600) and prints the address.
- * `paidfor-mcp wallet register` proves that wallet to a paidfor team (PAIDFOR_TEAM_KEY), so the team's rules apply to it.
+ * `paidfor-mcp wallet register` proves that wallet to a paidfor team (PAIDFOR_TEAM_KEY). With PAIDFOR_TEAM_KEY also set on
+ * the server, pay_x402 asks the team's rules before every payment.
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { DEFAULT_BASE, createServer } from "./server.js";
 import { FUND_SENTENCE, WalletConfigError, loadWallet, newWallet, readLimits, registerWallet } from "./wallet.js";
 const [cmd, sub, ...rest] = process.argv.slice(2);
 const baseUrl = (process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
+if (cmd === "init" || cmd === "link") {
+    // The one-command install (init.ts); `link` is its link, register and config steps alone.
+    const { realDeps, runInit } = await import("./init.js");
+    const args = process.argv.slice(3);
+    try {
+        process.exit(await runInit(args, realDeps(), cmd));
+    }
+    catch (e) {
+        process.stderr.write(`paidfor-mcp: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
+    }
+}
 if (cmd === "wallet") {
     const usage = "usage: paidfor-mcp wallet new | PAIDFOR_TEAM_KEY=pft_... paidfor-mcp wallet register [--label \"research agent\"]\n";
     try {
@@ -63,7 +77,9 @@ if (pay && limits) {
     const { INSTRUCTIONS_WITH_PAY, registerPayTools } = await import("./pay.js");
     const server = createServer({ baseUrl, instructions: INSTRUCTIONS_WITH_PAY });
     // PAIDFOR_FETCH_ALIAS=1 also registers the handler as fetch_paid_url (eval/routing.mjs measures whether the second name helps).
-    await registerPayTools(server, { wallet: pay, limits, baseUrl, fetchAlias: process.env.PAIDFOR_FETCH_ALIAS === "1" });
+    // PAIDFOR_TEAM_KEY: every payment asks the team's rules first (docs/team-api.md).
+    const teamKey = process.env.PAIDFOR_TEAM_KEY?.trim() || undefined;
+    await registerPayTools(server, { wallet: pay, limits, baseUrl, fetchAlias: process.env.PAIDFOR_FETCH_ALIAS === "1", ...(teamKey ? { teamKey } : {}) });
     await server.connect(new StdioServerTransport());
 }
 else {