@paidfor/mcp 0.5.0 → 0.7.0

package/README.md

@@ -4,8 +4,6 @@
 
 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.
-
 [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=paidfor&config=eyJ1cmwiOiJodHRwczovL21jcC5wYWlkZm9yLmRldi9tY3AifQ%3D%3D)
 
 Three read tools and one report tool on every transport, plus two paying tools on stdio only when a wallet is configured:
@@ -21,6 +19,36 @@ On initialize the server sends `instructions` telling the client to call `check_
 
 The read tools use the public JSON API (`GET https://paidfor.dev/v1/check`, `/v1/sellers`, `/v1/changes`). No keys, no rate limit for now.
 
+## Install in one command (0.7.0)
+
+```bash
+npx -y @paidfor/mcp init
+```
+
+It finds the MCP clients on this machine (Claude Code, Codex CLI, Cursor, Claude Desktop, Windsurf / Devin Desktop, VS Code) and asks which to set up; asks whether this agent may pay x402 sellers and, only on a yes, makes a wallet in `~/.paidfor/wallet.key` (mode 600) with caps of $0.50 a call and $5 a day, or uses the one already there; offers to link that wallet to a paidfor account, which you approve in the browser after checking the code it prints matches; then shows each config change (key names, never values) and writes it after you say yes. Each client gets a stdio server named `paidfor` running `npx -y @paidfor/mcp@<this version>` (pinned), with `PAIDFOR_WALLET_KEY_FILE`, the two caps and `PAIDFOR_TEAM_KEY` in its env only when they apply. Last it checks `api-xpay.com` against the index (expected: `avoid`) and says what is left: which clients to restart, the address to fund, and whether the wallet is live or paused on the account.
+
+Config files are merged, never replaced: other servers stay, an existing `paidfor` entry (such as the hosted URL, which cannot pay) is replaced but the caps you set in its env are kept, the original is copied once to `<file>.paidfor-bak`, the write is atomic and keeps the file's mode, and a file that is not valid JSON is left alone with a message. Claude Code, Codex and VS Code are set up through their own CLIs (`claude mcp add --scope user`, `codex mcp add`, `code --add-mcp`), which take the env on the command line; that command is never printed.
+
+| flag | |
+|---|---|
+| `--yes` | no questions: every client found (or those in `--client`), no wallet unless `--wallet`, no link unless `--link`. Also what happens without a terminal |
+| `--client <id>[,<id>]` | only these: `claude-code`, `codex`, `cursor`, `claude-desktop`, `windsurf`, `vscode` |
+| `--wallet` / `--no-wallet` | let the agent pay, or not; an agent running init never makes a wallet unless told to |
+| `--link` / `--no-link` | link the wallet to a paidfor account, or not |
+| `--wait` | with `--yes` (or without a terminal), wait for the approval in the browser instead of saving the link for `link` to finish |
+| `--key-file <path>` | use this wallet key instead of `~/.paidfor/wallet.key` (implies `--wallet`) |
+| `--label <name>` | the wallet's name on the account (default: this machine's host name) |
+| `--dry-run` | print what would change; writes nothing, makes no wallet, starts no link |
+
+`npx -y @paidfor/mcp link` is the link, register and config steps alone, for a wallet set up without an account: it takes `--label`, `--key-file`, `--client`, `--wait`, `--yes` and `--dry-run`. A link that is denied, expires or was already used leaves everything else in place and says so; run `link` again later. The output is safe for an agent to read and relay: it never contains the wallet key, the team key or the link's device code.
+
+**When an agent runs it.** An agent's shell shows output only when the command exits, so with `--yes` (or without a terminal) the link step does not wait for the approval. It is two steps:
+
+1. `npx -y @paidfor/mcp init --yes --wallet --link` prints the approval link and the code, saves the pending link to `~/.paidfor/link-pending.json` (mode 600; the only place its device code is written), writes the config without a team key, and exits. Its next steps start with `1. Open the link above and approve it. 2. Then run: npx -y @paidfor/mcp@<version> link`. The agent hands the link and the code to its user.
+2. After the user approves, `npx -y @paidfor/mcp link --yes` resumes the saved link: it checks at once and for up to 20 seconds, then registers the wallet, writes the team key into the clients the first run configured (or `--client`), says whether the wallet is live or paused, and deletes the record. Still not approved: it says so, keeps the record and exits 0, so it can be run again. Denied, expired or already used: it says so and deletes the record.
+
+A saved link is resumed only by a run against the same `PAIDFOR_API_BASE` and wallet, before it expires; otherwise `link` starts a new one. If the browser approval went through but registering the wallet failed, the approved team key is kept in that same file (never in a client config) and the next `link` (or `init --link`) registers again with it, no new approval needed; the record is deleted once it succeeds, or dropped if paidfor answers 401 for the key (revoked). In a terminal, `init` and `link` wait for the approval as before.
+
 ## 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. A browser (`Accept` preferring `text/html`) gets a setup page from `src/setup.ts` on `/mcp` and `/` instead; `?format=json` brings the status back. `/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`:
@@ -45,9 +73,11 @@ The read tools use the public JSON API (`GET https://paidfor.dev/v1/check`, `/v1
 
 ## Let your agent pay, safely (stdio only)
 
-`pay_x402` pays an x402 seller with **your own wallet**, through `@paidfor/x402-safe-fetch` 0.2.0: it checks the seller on paidfor first and refuses `avoid` sellers, refuses quotes over 1.1x the listed price, caps the amount per call and per day, never pays twice for the same `intent_id` (a retry returns the stored result), keeps receipts in `~/.paidfor/receipts/`, and reports the outcome with its proof of payment (payer, nonce, pay-to, tx hash) to `https://paidfor.dev/v1/telemetry`, where it is checked on Base. It returns the status, the body (truncated at 64 KB) and a receipt with the amount, pay-to, tx hash and basescan link, the seller verdict at purchase, the validator results and the `verification_url` that shows whether the index verified it.
+`pay_x402` pays an x402 seller with **your own wallet**, through `@paidfor/x402-safe-fetch` 0.4.0: it checks the seller on paidfor first and refuses `avoid` sellers, refuses quotes over 1.1x the listed price, caps the amount per call and per day, never pays twice for the same `intent_id` (a retry returns the stored result), keeps receipts in `~/.paidfor/receipts/`, and reports the outcome with its proof of payment (payer, nonce, pay-to, tx hash) to `https://paidfor.dev/v1/telemetry`, where it is checked on Base. It returns the status, the body (truncated at 64 KB) and a receipt with the amount, pay-to, tx hash and basescan link, the seller verdict at purchase, the validator results and the `verification_url` that shows whether the index verified it.
+
+**Use a dedicated wallet holding a few dollars, never your main wallet.** There is no custody: the key stays on your machine, is read only to sign, and is never logged, returned by a tool or sent anywhere.
 
-**Use a dedicated wallet holding a few dollars, never your main wallet.** There is no custody and no account: the key stays on your machine, is read only to sign, and is never logged, returned by a tool or sent anywhere.
+`npx -y @paidfor/mcp init` does all of the below for you. By hand:
 
 ```bash
 npx -y @paidfor/mcp wallet new
@@ -76,7 +106,15 @@ Verify by asking the agent to call `wallet_status`.
 PAIDFOR_TEAM_KEY=pft_... npx -y @paidfor/mcp wallet register --label "research agent"
 ```
 
-It asks paidfor for a challenge, signs it with the wallet's key (the key is sent nowhere) and sends the signature back. The wallet is `PAIDFOR_WALLET_KEY_FILE` or `PAIDFOR_WALLET_KEY` when set, else `~/.paidfor/wallet.key`. A wallet registered with a key starts paused: open the team page, check its limits, untick Paused and save. The team key is read from the environment only, never from an argument.
+It asks paidfor for a challenge, signs it with the wallet's key (the key is sent nowhere) and sends the signature back. The wallet is `PAIDFOR_WALLET_KEY_FILE` or `PAIDFOR_WALLET_KEY` when set, else `~/.paidfor/wallet.key`; if the MCP client is configured with a key file elsewhere, set `PAIDFOR_WALLET_KEY_FILE` to that same path for this command too, or it registers the default wallet instead. A wallet registered with a key starts paused: open the team page, check its limits, untick Paused and save. The team key is read from the environment only, never from an argument. Written into the command it stays in your shell history; to keep it out, `read -rs PAIDFOR_TEAM_KEY && export PAIDFOR_TEAM_KEY` first and run the command without the prefix. Registering does not configure the server: `pay_x402` still needs `PAIDFOR_WALLET_KEY_FILE` in the MCP client config, as above.
+
+**Ask the team before each payment (0.6.0).** Registering alone does not put payments under the team's rules. Give the server the team key too:
+
+```json
+"env": { "PAIDFOR_WALLET_KEY_FILE": "/Users/you/.paidfor/wallet.key", "PAIDFOR_TEAM_KEY": "pft_..." }
+```
+
+With `PAIDFOR_TEAM_KEY` set, `pay_x402` asks `POST /v1/team/authorize` after its own checks and before it signs, and the local caps still apply. It pays only on an approval, and signs with the approval's reference as the EIP-3009 nonce and its deadline as `validBefore`, so the payment can be matched to the ledger. If the server is unreachable or answers anything but a clear decision, nothing is paid. A decline comes back with the team's reason. A payment waiting for a person comes back with the link to approve it and the `intent_id` to call again with. After a payment the outcome goes to `POST /v1/team/outcome`; a report the server cannot take is kept in `~/.paidfor/team-outcomes/` and sent before the next payment. The key sits in your MCP client's config, so treat that file as a secret. The key cannot change rules, keys or approvals. The agent holds its own wallet key here, so a payment made some other way is not stopped. Stdio only: the hosted server never pays.
 
 **Routing a paid URL (0.4.1).** The model should reach for `pay_x402` whenever a URL is paid, metered, pay-per-call, x402, priced in USDC, said to charge a fee, or has answered 402 to any other fetch, even when the client also has a generic web fetch tool and the user never says how to pay. The tool is described as the way to fetch such a URL end to end (it sends the request, handles the 402, pays under the caps and returns the body), the description says a plain fetch fails on these URLs with 402, and the stdio server adds the same rule to its `instructions` only when the paying tools are registered; the hosted server's text is unchanged. `eval/routing.mjs` measures the first-call rate per model and prompt shape (`pnpm eval:routing`; results by date in `eval/routing-<date>.md`). `PAIDFOR_FETCH_ALIAS=1` also registers the same handler as `fetch_paid_url`, for clients that route by a fetch-shaped name; the eval compares both and the alias is off by default.
 
@@ -87,6 +125,7 @@ It asks paidfor for a challenge, signs it with the wallet's key (the key is sent
 | `PAIDFOR_MAX_PER_CALL_USD` | `0.50` | most one call may pay; `max_usd` can lower it, never raise it |
 | `PAIDFOR_DAILY_CAP_USD` | `5` | most all calls may pay per UTC day (tracked in `~/.paidfor/spend.json`) |
 | `BASE_RPC_URL` | `https://mainnet.base.org` | used only by `wallet_status` for the balance |
+| `PAIDFOR_TEAM_KEY` | | with a wallet: ask the team's rules before each payment and report the outcome (`https` only, or a server on this machine); also used by `wallet register` |
 | `PAIDFOR_FETCH_ALIAS` | off | `1` also registers `pay_x402` as `fetch_paid_url` (same handler, schema and caps) |
 
 Without a key (or with a misconfigured one, reported on stderr) the stdio server is the read-only server. The hosted server at `mcp.paidfor.dev` and the site's `/mcp` route never register `pay_x402` or `wallet_status`, by design: they never hold a key.
@@ -121,7 +160,7 @@ Usage is counted by Manufact's gateway (every `tools/call` with client and sessi
 
 ## Tests
 
-`pnpm test` builds and runs `test/*.test.mjs` with Node's test runner: `hosted-snapshot` fails on any change to the hosted server's tool list, instructions or empty resources/prompts lists (the ChatGPT app review rescans them daily; regenerate on purpose with `UPDATE_SNAPSHOT=1`), `pay-wording` checks the `pay_x402` framing, guarantees, annotations and the alias, `pay-replay` the replay line and the `intent_id` guidance against a local seller. The site's `vitest` suite (`test/mcp-pay.test.ts` at the repo root) covers the paying tools end to end against a local seller.
+`pnpm test` builds and runs `test/*.test.mjs` with Node's test runner: `hosted-snapshot` fails on any change to the hosted server's tool list, instructions or empty resources/prompts lists (the ChatGPT app review rescans them daily; regenerate on purpose with `UPDATE_SNAPSHOT=1`), `pay-wording` checks the `pay_x402` framing, guarantees, annotations and the alias, `pay-replay` the replay line and the `intent_id` guidance against a local seller, `pay-team` team mode against a local seller and a scripted server, `wallet-register` the challenge signing, `init` the one-command install against a fake home, fake client CLIs and a stand-in server. The site's `vitest` suite (`test/mcp-pay.test.ts` at the repo root) covers the paying tools end to end against a local seller, and `test/mcp-team.test.ts` runs team mode against the real server code.
 
 ## Claude Desktop extension
 
@@ -133,6 +172,9 @@ Usage is counted by Manufact's gateway (every `tools/call` with client and sessi
 
 ## Changelog
 
-- **0.5.0** (unpublished): `paidfor-mcp wallet register` registers the configured wallet to a paidfor team (`PAIDFOR_TEAM_KEY`), signing the team's challenge locally; new test `wallet-register.test.mjs`. The hosted server's tools and instructions are unchanged.
+- **0.7.0**: `paidfor-mcp init`, the install in one command (detects the clients, offers a wallet, links it to an account in the browser, writes the config, verifies), and `paidfor-mcp link`, which also finishes a link that `init --yes` saved instead of waiting for (`--wait` waits). `wallet register` takes the link's code so a wallet a person approved starts unpaused. `INIT_COMMAND` in `@paidfor/mcp/setup`. New test `init.test.mjs`. The hosted server's tools and instructions are unchanged.
+
+- **0.6.0**: team mode. With `PAIDFOR_TEAM_KEY` set, `pay_x402` asks the team before signing, fails closed, signs the approval's nonce and deadline and reports the outcome. Needs `@paidfor/x402-safe-fetch` 0.4.0. The hosted server's tools and instructions are unchanged.
+- **0.5.0**: `paidfor-mcp wallet register` registers the configured wallet to a paidfor team (`PAIDFOR_TEAM_KEY`), signing the team's challenge locally; new test `wallet-register.test.mjs`. The hosted server's tools and instructions are unchanged.
 - **0.4.1** (unpublished): `pay_x402` is framed as the way to fetch a paid (x402) URL end to end, its description says a generic fetch fails on such URLs with 402 and that any URL called paid, metered, x402 or that answered 402 goes to it with the same method, headers and body; the stdio server with a wallet adds the same routing rule to its instructions (`PAY_ROUTING_RULE` in `rules.ts`). A replayed result (same `intent_id`) now opens with the age and time of the stored result and says to call again with a new id for a new purchase; the description, the schema and the stdio rules say to reuse an `intent_id` only when retrying the same purchase after an error or timeout and to omit it otherwise (a date-only id chosen in three fresh sessions replayed instead of buying). Optional `fetch_paid_url` alias (`PAIDFOR_FETCH_ALIAS=1`). New `pnpm test` (hosted-surface snapshot, wording) and `pnpm eval:routing`. The hosted server's tools and instructions are unchanged.
 - **0.4.0**: `report_x402_payment` on every transport; `mcpName` `dev.paidfor/paidfor`.

package/dist/clients.d.ts

@@ -0,0 +1,114 @@
+import type { Env } from "./wallet.js";
+/** The clients init knows, in the order they are found and listed. */
+export declare const CLIENT_IDS: readonly ["claude-code", "codex", "cursor", "claude-desktop", "windsurf", "vscode"];
+/** One of CLIENT_IDS. */
+export type ClientId = (typeof CLIENT_IDS)[number];
+/** Whether a --client value names a known client. */
+export declare const isClientId: (s: string) => s is ClientId;
+/** The env keys whose values are secrets: never printed, masked in any command shown. */
+export declare const SECRET_ENV: string[];
+/** Values a person may have tuned in an existing entry; init keeps them. */
+export declare const CAP_ENV: string[];
+/** The stdio server entry init writes: command, args and env. */
+export type ServerEntry = {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+};
+/** What a child process left: its exit code and output. */
+export type ExecResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/** Runs a command without a shell (injected in tests). */
+export type Exec = (cmd: string, args: string[]) => Promise<ExecResult>;
+/** Where to look for clients: the home, the platform, the env and PATH. */
+export type ClientContext = {
+    home: string;
+    platform: NodeJS.Platform;
+    env: Env;
+    /** The absolute path of `bin` on PATH, or null. */
+    which: (bin: string) => Promise<string | null>;
+};
+/** What every target has: its id, its name and how to restart it. */
+type Base = {
+    id: ClientId;
+    name: string;
+    restart: string;
+};
+/** A client configured by editing its JSON file. */
+export type FileTarget = Base & {
+    kind: "file";
+    file: string;
+    key: "mcpServers";
+};
+/** A client configured through its own CLI's mcp add. */
+export type CliTarget = Base & {
+    kind: "cli";
+    bin: string; /** where its user config is, read only to keep the caps already set */
+    existing?: {
+        file: string;
+        format: "json" | "toml";
+        key?: string;
+    };
+};
+/** A client init can configure. */
+export type Target = FileTarget | CliTarget;
+/** The target for one client, and whether it looks installed here. */
+export declare function targetFor(id: ClientId, ctx: ClientContext): Promise<{
+    target: Target;
+    found: boolean;
+}>;
+/** The clients installed on this machine, in CLIENT_IDS order. */
+export declare function detectClients(ctx: ClientContext): Promise<Target[]>;
+/** PATH lookup without running anything. */
+export declare function pathWhich(env: Env, platform: NodeJS.Platform): (bin: string) => Promise<string | null>;
+/** Was this existing entry the hosted URL (which cannot pay)? */
+export declare const isHostedEntry: (e: unknown) => boolean;
+/**
+ * Our entry over an existing one: command and args are ours, the env keeps what the person set (their caps win over
+ * the defaults, other keys stay) and takes ours for everything else.
+ */
+export declare function mergeEntry(existing: unknown, ours: ServerEntry): ServerEntry;
+/** What writing a config file would do, or why it is refused. */
+export type FilePlan = {
+    ok: true;
+    action: "create" | "add" | "replace";
+    wasHosted: boolean;
+    entry: ServerEntry;
+    text: string;
+    others: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The new file text for a config, or why it is left alone. `text` null means the file does not exist. */
+export declare function planJson(text: string | null, key: string, ours: ServerEntry): FilePlan;
+/** The file text, or null when it does not exist; other errors are thrown. */
+export declare function readIfExists(file: string): Promise<string | null>;
+/** Where the one-time backup of a config goes. */
+export declare const backupPath: (file: string) => string;
+/**
+ * Writes `text` to `file`: a symlink is followed and the file it points at is written; the original is copied to
+ * <file>.paidfor-bak the first time (an existing backup is never overwritten); the write is a temp file and a rename,
+ * with the file's mode kept (a new file is 600, since it may hold the team key). Returns whether a backup was made.
+ */
+export declare function writeConfigAtomic(file: string, text: string, o?: {
+    secret?: boolean;
+}): Promise<{
+    backup: string | null;
+    tightened: boolean;
+}>;
+/** The env of an existing paidfor entry in a CLI client's own config, best effort (only to keep the caps). */
+export declare function existingCliEnv(t: CliTarget): Promise<Record<string, string>>;
+/** The argv for a CLI client: the remove that clears an old entry (its failure is fine), then the add. */
+export declare function cliCommands(t: CliTarget, entry: ServerEntry): {
+    remove?: string[];
+    add: string[];
+};
+/** A command as it may be shown: secret values masked. */
+export declare function maskedCommand(bin: string, args: string[]): string;
+/** Render the stdio block to paste by hand, for a client init could not find. Secret values are placeholders. */
+export declare function pasteBlock(entry: ServerEntry): string;
+export {};

package/dist/clients.js

@@ -0,0 +1,330 @@
+/**
+ * The MCP clients `paidfor-mcp init` can configure: where each keeps its servers, how to tell it is installed, and how
+ * to put the stdio `paidfor` server in it. Formats follow lib/install.ts on the site (checked against each client's
+ * docs). File clients are edited in place: merged, backed up once, written atomically, mode kept. CLI clients are
+ * driven through their own `mcp add`, which is the only way to give them env; that command line carries the team key,
+ * so it is never printed.
+ */
+import { constants } from "node:fs";
+import { access, chmod, copyFile, mkdir, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { delimiter, dirname, join } from "node:path";
+/** The clients init knows, in the order they are found and listed. */
+export const CLIENT_IDS = ["claude-code", "codex", "cursor", "claude-desktop", "windsurf", "vscode"];
+/** Whether a --client value names a known client. */
+export const isClientId = (s) => CLIENT_IDS.includes(s);
+/** The env keys whose values are secrets: never printed, masked in any command shown. */
+export const SECRET_ENV = ["PAIDFOR_TEAM_KEY", "PAIDFOR_WALLET_KEY"];
+/** Values a person may have tuned in an existing entry; init keeps them. */
+export const CAP_ENV = ["PAIDFOR_MAX_PER_CALL_USD", "PAIDFOR_DAILY_CAP_USD"];
+const NAMES = {
+    "claude-code": "Claude Code",
+    codex: "Codex CLI",
+    cursor: "Cursor",
+    "claude-desktop": "Claude Desktop",
+    windsurf: "Windsurf / Devin Desktop",
+    vscode: "VS Code",
+};
+const RESTART = {
+    "claude-code": "start a new session (or run /mcp) so the tools load",
+    codex: "start a new Codex session",
+    cursor: "Cursor picks it up; if the tools do not show, toggle the server in Settings, MCP",
+    "claude-desktop": "quit and restart Claude Desktop",
+    windsurf: "press refresh in Cascade's MCP settings",
+    vscode: "run MCP: List Servers, start paidfor, and trust it when asked",
+};
+/** Windows' roaming AppData, from APPDATA or its usual place under the home. */
+const appData = (ctx) => ctx.env.APPDATA ?? join(ctx.home, "AppData", "Roaming");
+/** Whether a path exists. */
+async function exists(p) {
+    return stat(p).then(() => true, () => false);
+}
+/** Claude Desktop's config directory on this platform. */
+function claudeDesktopDir(ctx) {
+    if (ctx.platform === "darwin")
+        return join(ctx.home, "Library", "Application Support", "Claude");
+    if (ctx.platform === "win32")
+        return join(appData(ctx), "Claude");
+    return join(ctx.home, ".config", "Claude");
+}
+/** VS Code's user settings directory on this platform. */
+function vscodeUserDir(ctx) {
+    if (ctx.platform === "darwin")
+        return join(ctx.home, "Library", "Application Support", "Code", "User");
+    if (ctx.platform === "win32")
+        return join(appData(ctx), "Code", "User");
+    return join(ctx.home, ".config", "Code", "User");
+}
+/** Windsurf (now Devin Desktop) moved its config; the newer directory wins when both exist. */
+async function windsurfFile(ctx) {
+    const devin = ctx.platform === "win32" ? join(appData(ctx), "devin") : join(ctx.home, ".config", "devin");
+    const older = join(ctx.home, ".codeium", "windsurf");
+    if (await exists(devin))
+        return { file: join(devin, "mcp_config.json"), found: true };
+    if (await exists(older))
+        return { file: join(older, "mcp_config.json"), found: true };
+    return { file: join(devin, "mcp_config.json"), found: false };
+}
+/** The target for one client, and whether it looks installed here. */
+export async function targetFor(id, ctx) {
+    const base = { id, name: NAMES[id], restart: RESTART[id] };
+    switch (id) {
+        case "claude-code":
+            return { target: { ...base, kind: "cli", bin: "claude", existing: { file: join(ctx.home, ".claude.json"), format: "json", key: "mcpServers" } }, found: !!(await ctx.which("claude")) };
+        case "codex": {
+            const dir = ctx.env.CODEX_HOME?.trim() || join(ctx.home, ".codex");
+            return { target: { ...base, kind: "cli", bin: "codex", existing: { file: join(dir, "config.toml"), format: "toml" } }, found: !!(await ctx.which("codex")) };
+        }
+        case "vscode":
+            return { target: { ...base, kind: "cli", bin: "code", existing: { file: join(vscodeUserDir(ctx), "mcp.json"), format: "json", key: "servers" } }, found: !!(await ctx.which("code")) };
+        case "cursor": {
+            const dir = join(ctx.home, ".cursor");
+            return { target: { ...base, kind: "file", file: join(dir, "mcp.json"), key: "mcpServers" }, found: await exists(dir) };
+        }
+        case "claude-desktop": {
+            const dir = claudeDesktopDir(ctx);
+            return { target: { ...base, kind: "file", file: join(dir, "claude_desktop_config.json"), key: "mcpServers" }, found: await exists(dir) };
+        }
+        case "windsurf": {
+            const w = await windsurfFile(ctx);
+            return { target: { ...base, kind: "file", file: w.file, key: "mcpServers" }, found: w.found };
+        }
+    }
+}
+/** The clients installed on this machine, in CLIENT_IDS order. */
+export async function detectClients(ctx) {
+    const out = [];
+    for (const id of CLIENT_IDS) {
+        const t = await targetFor(id, ctx);
+        if (t.found)
+            out.push(t.target);
+    }
+    return out;
+}
+/** PATH lookup without running anything. */
+export function pathWhich(env, platform) {
+    return async (bin) => {
+        const exts = platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean) : [""];
+        for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
+            for (const ext of exts) {
+                const p = join(dir, bin + ext);
+                try {
+                    await access(p, platform === "win32" ? constants.F_OK : constants.X_OK);
+                    if ((await stat(p)).isFile())
+                        return p;
+                }
+                catch {
+                    /* not here */
+                }
+            }
+        }
+        return null;
+    };
+}
+/** A plain JSON object (not null, not an array). */
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** The string values of an env object; anything else is dropped. */
+function stringEnv(v) {
+    const out = {};
+    if (isObj(v))
+        for (const [k, x] of Object.entries(v))
+            if (typeof x === "string")
+                out[k] = x;
+    return out;
+}
+/** Was this existing entry the hosted URL (which cannot pay)? */
+export const isHostedEntry = (e) => isObj(e) && (typeof e.url === "string" || typeof e.serverUrl === "string");
+/**
+ * Our entry over an existing one: command and args are ours, the env keeps what the person set (their caps win over
+ * the defaults, other keys stay) and takes ours for everything else.
+ */
+export function mergeEntry(existing, ours) {
+    const old = stringEnv(isObj(existing) ? existing.env : undefined);
+    const keptCaps = Object.fromEntries(CAP_ENV.filter((k) => old[k]?.trim()).map((k) => [k, old[k]]));
+    return { command: ours.command, args: [...ours.args], env: { ...old, ...ours.env, ...keptCaps } };
+}
+/** The file's own indentation, so a rewrite keeps its look. */
+function indentOf(text) {
+    const m = /\n([ \t]+)\S/.exec(text);
+    if (!m)
+        return 2;
+    return m[1].includes("\t") ? "\t" : m[1].length;
+}
+/** The new file text for a config, or why it is left alone. `text` null means the file does not exist. */
+export function planJson(text, key, ours) {
+    let doc = {};
+    if (text !== null && text.trim() !== "") {
+        try {
+            doc = JSON.parse(text);
+        }
+        catch {
+            return { ok: false, reason: "it is not valid JSON (comments or a trailing comma?)" };
+        }
+    }
+    if (!isObj(doc))
+        return { ok: false, reason: "it does not hold a JSON object" };
+    const servers = doc[key] ?? {};
+    if (!isObj(servers))
+        return { ok: false, reason: `its "${key}" is not an object` };
+    const prev = servers.paidfor;
+    const entry = mergeEntry(prev, ours);
+    const next = { ...doc, [key]: { ...servers, paidfor: entry } };
+    const others = Object.keys(servers).filter((k) => k !== "paidfor").length;
+    return {
+        ok: true,
+        action: text === null ? "create" : prev === undefined ? "add" : "replace",
+        wasHosted: isHostedEntry(prev),
+        entry,
+        text: JSON.stringify(next, null, text ? indentOf(text) : 2) + "\n",
+        others,
+    };
+}
+/** The file text, or null when it does not exist; other errors are thrown. */
+export async function readIfExists(file) {
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+}
+/** Where the one-time backup of a config goes. */
+export const backupPath = (file) => `${file}.paidfor-bak`;
+/**
+ * Writes `text` to `file`: a symlink is followed and the file it points at is written; the original is copied to
+ * <file>.paidfor-bak the first time (an existing backup is never overwritten); the write is a temp file and a rename,
+ * with the file's mode kept (a new file is 600, since it may hold the team key). Returns whether a backup was made.
+ */
+export async function writeConfigAtomic(file, text, o = {}) {
+    let real = file;
+    let mode = 0o600;
+    let existed = false;
+    try {
+        real = await realpath(file);
+        mode = (await stat(real)).mode & 0o7777;
+        existed = true;
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    let backup = null;
+    if (existed) {
+        const bak = backupPath(file);
+        try {
+            if (o.secret) {
+                // The file being replaced may already hold the key: its backup is owner-only from the moment it exists.
+                await writeFile(bak, await readFile(real), { flag: "wx", mode: mode & ~0o077 });
+                await chmod(bak, mode & ~0o077);
+            }
+            else {
+                await copyFile(real, bak, constants.COPYFILE_EXCL);
+                await chmod(bak, mode);
+            }
+            backup = bak;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            // A backup from an earlier run may hold the key too. If it cannot be made owner-only, say so and write nothing.
+            if (o.secret) {
+                const bakMode = (await stat(bak)).mode & 0o7777;
+                if ((bakMode & 0o077) !== 0) {
+                    await chmod(bak, bakMode & ~0o077).catch(() => {
+                        throw new Error(`the earlier backup ${bak} may hold the account's key and could not be made readable by you only; fix its permissions or remove it, then run this again`);
+                    });
+                }
+            }
+        }
+    }
+    else {
+        await mkdir(dirname(real), { recursive: true });
+    }
+    // A config that carries the team key is readable by its owner only, like the wallet key file.
+    const tightened = !!o.secret && (mode & 0o077) !== 0;
+    if (o.secret)
+        mode &= ~0o077;
+    const tmp = `${real}.paidfor-tmp-${process.pid}`;
+    try {
+        await writeFile(tmp, text, { mode });
+        await chmod(tmp, mode);
+        await rename(tmp, real);
+    }
+    catch (e) {
+        await unlink(tmp).catch(() => undefined);
+        throw e;
+    }
+    return { backup, tightened };
+}
+/** The env of an existing paidfor entry in a CLI client's own config, best effort (only to keep the caps). */
+export async function existingCliEnv(t) {
+    if (!t.existing)
+        return {};
+    const text = await readIfExists(t.existing.file).catch(() => null);
+    if (!text)
+        return {};
+    if (t.existing.format === "json") {
+        try {
+            const doc = JSON.parse(text);
+            const servers = doc[t.existing.key ?? "mcpServers"];
+            return isObj(servers) && isObj(servers.paidfor) ? stringEnv(servers.paidfor.env) : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    // TOML: the [mcp_servers.paidfor.env] table, or an inline `env = { ... }` under [mcp_servers.paidfor].
+    const out = {};
+    const lines = text.split(/\r?\n/);
+    let section = "";
+    for (const line of lines) {
+        const h = /^\s*\[([^\]]+)\]\s*$/.exec(line);
+        if (h) {
+            section = h[1].trim();
+            continue;
+        }
+        if (section === "mcp_servers.paidfor.env") {
+            const m = /^\s*"?([A-Za-z_][A-Za-z0-9_]*)"?\s*=\s*"([^"]*)"/.exec(line);
+            if (m)
+                out[m[1]] = m[2];
+        }
+        else if (section === "mcp_servers.paidfor") {
+            const m = /^\s*env\s*=\s*\{(.*)\}\s*$/.exec(line);
+            if (m)
+                for (const p of m[1].matchAll(/"?([A-Za-z_][A-Za-z0-9_]*)"?\s*=\s*"([^"]*)"/g))
+                    out[p[1]] = p[2];
+        }
+    }
+    return out;
+}
+/** The argv for a CLI client: the remove that clears an old entry (its failure is fine), then the add. */
+export function cliCommands(t, entry) {
+    const envPairs = Object.entries(entry.env).map(([k, v]) => `${k}=${v}`);
+    if (t.id === "claude-code") {
+        // The name goes before -e: -e takes several values and would swallow it.
+        return { remove: ["mcp", "remove", "paidfor", "--scope", "user"], add: ["mcp", "add", "paidfor", "--scope", "user", ...envPairs.flatMap((p) => ["-e", p]), "--", entry.command, ...entry.args] };
+    }
+    if (t.id === "codex") {
+        return { remove: ["mcp", "remove", "paidfor"], add: ["mcp", "add", "paidfor", ...envPairs.flatMap((p) => ["--env", p]), "--", entry.command, ...entry.args] };
+    }
+    // VS Code: --add-mcp takes the server as JSON and puts it in the user profile's mcp.json.
+    return { add: ["--add-mcp", JSON.stringify({ name: "paidfor", command: entry.command, args: entry.args, env: entry.env })] };
+}
+/** A command as it may be shown: secret values masked. */
+export function maskedCommand(bin, args) {
+    /** One argument with the secret env values masked. */
+    const mask = (s) => {
+        let out = s;
+        for (const k of SECRET_ENV) {
+            out = out.replace(new RegExp(`(${k}=)[^\\s"']+`, "g"), "$1***").replace(new RegExp(`("${k}":")[^"]*`, "g"), "$1***");
+        }
+        return out;
+    };
+    return [bin, ...args.map((a) => (/[\s"'{}]/.test(a) ? `'${mask(a)}'` : mask(a)))].join(" ");
+}
+/** Render the stdio block to paste by hand, for a client init could not find. Secret values are placeholders. */
+export function pasteBlock(entry) {
+    const env = Object.fromEntries(Object.entries(entry.env).map(([k, v]) => [k, SECRET_ENV.includes(k) ? `<${k}>` : v]));
+    return JSON.stringify({ mcpServers: { paidfor: { command: entry.command, args: entry.args, ...(Object.keys(env).length ? { env } : {}) } } }, null, 2);
+}

package/dist/init.d.ts

@@ -0,0 +1,61 @@
+import { type Exec } from "./clients.js";
+import { type Env } from "./wallet.js";
+/** The package as the configs pin it: this exact version, never latest. */
+export declare const PKG = "@paidfor/mcp@0.7.0";
+/** What init and link send as X-Paidfor-Client and as the link's `client`, so the funnel can be counted. */
+export declare const INIT_CLIENT = "mcp-init/0.7.0";
+/** How long `link` in --yes mode checks a resumed link before it exits and leaves the record for the next run. */
+export declare const RESUME_WINDOW_MS = 20000;
+/** Everything runInit touches outside itself, injected so the tests can fake the home, the server and the client CLIs. */
+export type InitDeps = {
+    env: Env;
+    home: string;
+    platform: NodeJS.Platform;
+    cwd: string;
+    /** stdin is a terminal a person can answer on. */
+    interactive: boolean;
+    /** stdout is a terminal (the browser is only opened for one). */
+    stdoutTTY: boolean;
+    out: (s: string) => void;
+    err: (s: string) => void;
+    prompt: (question: string) => Promise<string>;
+    fetch: typeof fetch;
+    exec: Exec;
+    which: (bin: string) => Promise<string | null>;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    openBrowser: (url: string) => void;
+    hostname: string;
+};
+/** The parsed command line; null means the flag was not given. */
+type Flags = {
+    yes: boolean;
+    dryRun: boolean;
+    wait: boolean;
+    clients: string[] | null;
+    wallet: boolean | null;
+    link: boolean | null;
+    keyFile: string | null;
+    label: string | null;
+};
+/** Printed with any usage error. */
+export declare const INIT_USAGE: string;
+/** Parses the init or link command line; throws UsageError on an unknown or misused flag. */
+export declare function parseFlags(argv: string[], mode: "init" | "link"): Flags;
+/** Runs `paidfor-mcp init` or `paidfor-mcp link`. Returns the exit code. */
+export declare function runInit(argv: string[], d: InitDeps, mode?: "init" | "link"): Promise<number>;
+/**
+ * One argument for a cmd.exe command line. First quoted the way the Windows C runtime splits arguments (backslashes
+ * before a quote doubled, quotes escaped), then every character cmd.exe gives a meaning to is escaped with ^. The CLIs
+ * are .cmd shims, and a shim passes its arguments through cmd.exe a second time, so the ^ escaping is applied twice.
+ * The same rules as cross-spawn.
+ */
+export declare function winArg(arg: string): string;
+/** What to spawn on Windows for a CLI shim: cmd.exe with one verbatim, fully escaped command line. */
+export declare function winSpawn(cmd: string, args: string[], env: Env): {
+    file: string;
+    args: string[];
+};
+/** The real world: process env, this home, a TTY prompt, node's fetch, child processes. */
+export declare function realDeps(): InitDeps;
+export {};