@paidfor/mcp 0.6.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

@@ -9,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)";

package/dist/pay.js

@@ -10,7 +10,7 @@ import { PaymentRefusedError, SafeFetchError, safeFetch } from "@paidfor/x402-sa
 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"];
@@ -29,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. " +

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,6 +2,7 @@
 /**
  * `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). With PAIDFOR_TEAM_KEY also set on
  * the server, pay_x402 asks the team's rules before every payment.
@@ -11,6 +12,18 @@ 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 {

package/dist/wallet.d.ts

@@ -26,8 +26,17 @@ export declare function newWallet(home?: string): Promise<{
 export declare const defaultKeyFile: (home?: string) => string;
 /** paidfor refused or could not answer a registration. The message never includes a key. */
 export declare class RegisterError extends Error {
+    readonly status?: number | undefined;
     name: string;
+    /** Builds the error; `status` is paidfor's HTTP status when it answered (401: the team key was refused). */
+    constructor(message: string, status?: number | undefined);
 }
+/**
+ * Team keys and link codes travel to paidfor in headers and bodies. Plain http is for a server on this machine only;
+ * anything else is refused before a request is made.
+ */
+export declare function assertKeySafeBase(base: string): void;
+/** What registerWallet reports: the address and whether it was already there, moved or starts paused. */
 export type Registered = {
     address: `0x${string}`;
     already: boolean;
@@ -46,6 +55,7 @@ export declare function registerWallet(o: {
     env?: Env;
     home?: string;
     fetchFn?: typeof fetch;
+    link?: string;
 }): Promise<Registered>;
 export type Limits = {
     maxPerCallUsd: number;

package/dist/wallet.js

@@ -76,7 +76,23 @@ export async function newWallet(home = homedir()) {
 export const defaultKeyFile = (home = homedir()) => join(paidforDir(home), "wallet.key");
 /** paidfor refused or could not answer a registration. The message never includes a key. */
 export class RegisterError extends Error {
+    status;
     name = "RegisterError";
+    /** Builds the error; `status` is paidfor's HTTP status when it answered (401: the team key was refused). */
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Team keys and link codes travel to paidfor in headers and bodies. Plain http is for a server on this machine only;
+ * anything else is refused before a request is made.
+ */
+export function assertKeySafeBase(base) {
+    const u = new URL(base);
+    if (u.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(u.hostname)) {
+        throw new RegisterError(`refusing to send a team key over ${u.protocol.replace(":", "")} to ${u.hostname}; use https`);
+    }
 }
 /**
  * `paidfor-mcp wallet register`: proves to a paidfor team that this wallet is the agent's, by signing the challenge
@@ -97,11 +113,8 @@ export async function registerWallet(o) {
         throw none;
     const f = o.fetchFn ?? fetch;
     const base = o.baseUrl.replace(/\/$/, "");
-    // The team key travels in a header. Plain http is for a server on this machine only.
-    const u = new URL(base);
-    if (u.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(u.hostname)) {
-        throw new RegisterError(`refusing to send a team key over ${u.protocol.replace(":", "")} to ${u.hostname}; use https`);
-    }
+    assertKeySafeBase(base);
+    /** POSTs to paidfor with the team key; a non-2xx answer is a RegisterError carrying the status. */
     const post = async (path, body) => {
         let res;
         try {
@@ -112,14 +125,16 @@ export async function registerWallet(o) {
         }
         const j = (await res.json().catch(() => ({})));
         if (!res.ok)
-            throw new RegisterError(`paidfor answered ${res.status}${typeof j.error === "string" ? `: ${j.error}` : ""}`);
+            throw new RegisterError(`paidfor answered ${res.status}${typeof j.error === "string" ? `: ${j.error}` : ""}`, res.status);
         return j;
     };
     const c = await post("/v1/team/wallets/challenge", { address: loaded.account.address });
     if (typeof c.message !== "string" || typeof c.token !== "string")
         throw new RegisterError("paidfor did not return a challenge to sign");
     const signature = await loaded.account.signMessage({ message: c.message });
-    const r = await post("/v1/team/wallets", { message: c.message, token: c.token, signature, label: o.label ?? "" });
+    // `link`: the device code of a link a person approved in the browser for this address (`paidfor-mcp init`), so the
+    // server can start the wallet unpaused. It is a secret, like the team key, and goes only in this body.
+    const r = await post("/v1/team/wallets", { message: c.message, token: c.token, signature, label: o.label ?? "", ...(o.link ? { link: o.link } : {}) });
     const w = (r.wallet ?? {});
     return { address: (w.address ?? loaded.account.address), already: r.already === true, moved: r.moved === true, paused: w.rules?.paused === true };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "mcpName": "dev.paidfor/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",