perly-pay-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# perly-pay-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sell your work for crypto from your AI coding assistant. `perly-pay-mcp` is a
+local [MCP](https://modelcontextprotocol.io) server for
+[Perly Pay](https://pay.perly.io): your assistant can create products, prices,
+payment links and invoices, pay them in test mode, read payments and receipts,
+and check a buyer's access. Bitcoin, USDC and USDT land straight in your own
+wallet; Perly Pay never holds them.
+
+It runs on your machine over stdio and talks only to Perly Pay's public API
+with your key. There is no server of ours in between.
+
+## Set up
+
+Get a test key in Perly Pay: **Dashboard → Developers → API keys** (`sk_test_…`).
+
+**Claude Code**
+
+```bash
+claude mcp add perly-pay --env PERLY_PAY_SECRET_KEY=sk_test_… -- npx -y perly-pay-mcp
+```
+
+**Cursor**: `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project
+
+```json
+{
+  "mcpServers": {
+    "perly-pay": {
+      "command": "npx",
+      "args": ["-y", "perly-pay-mcp"],
+      "env": { "PERLY_PAY_SECRET_KEY": "sk_test_…" }
+    }
+  }
+}
+```
+
+**Codex**: `~/.codex/config.toml`
+
+```toml
+[mcp_servers.perly-pay]
+command = "npx"
+args = ["-y", "perly-pay-mcp"]
+env = { PERLY_PAY_SECRET_KEY = "sk_test_…" }
+```
+
+Keep the key out of git: a config file in a project is often committed. Node 20
+or newer.
+
+| Variable | |
+| --- | --- |
+| `PERLY_PAY_SECRET_KEY` | `sk_test_…` while you build. `sk_live_…` works too, with the limits below. |
+| `PERLY_PAY_API` | Default `https://pay.perly.io`. Plain `http` only for `localhost`. |
+| `PERLY_PAY_WEBHOOK_SECRET` | Optional `whsec_…`, the default for `verify_webhook_signature`. |
+
+## Try it
+
+> Sell a one-hour consultation for $49 with a payment link, then pay it in test mode and show me the payment.
+
+The assistant calls `create_product`, `create_price`, `create_payment_link`,
+`simulate_payment` and `list_payments`.
+
+## Tools
+
+| Area | Tools |
+| --- | --- |
+| Products and prices | `create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price` |
+| Payment links | `create_payment_link`, `list_payment_links`, `update_payment_link` |
+| Invoices and checkout | `create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session` |
+| Customers | `create_customer`, `list_customers`, `retrieve_customer` |
+| Subscriptions (renewed by invoice) | `create_subscription`, `list_subscriptions`, `retrieve_subscription` |
+| Access and credits | `check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage` |
+| Money in, read only | `list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events` |
+| Refunds | `create_refund`, `list_refunds` |
+| Webhooks | `create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint` |
+| Test mode | `simulate_payment`: pays an invoice, or buys from a payment link and pays that |
+| On your machine | `verify_webhook_signature` checks a `Perly-Signature`; `pay_links` gives the dashboard pages only you can use: plan, wallet, go live, two-factor, keys |
+
+The tools are generated from Perly Pay's OpenAPI document, so their arguments
+are the API's own.
+
+## What it will not do
+
+- **With a live key**, it refuses anything that moves or redirects money,
+  spends a buyer's credits or deletes: simulated payments, refunds, credit
+  spending, new or deleted webhook endpoints. It says why and where you do it.
+  Reading, and making products, prices, links and invoices, work as in test.
+- **Wallets, API keys, plans, live mode and two-factor** have no tool at all.
+  You set them in the dashboard; `pay_links` gives the pages.
+- **What cannot be undone** (cancelling an invoice, opening a refund, deleting
+  a webhook endpoint) waits for `confirm: true`, which the assistant should
+  only send after asking you.
+- **Your secret key is never repeated** in an answer or a log.
+- **Text others wrote is marked as data.** Customer names, emails, descriptions
+  and metadata can come from buyers, or from anyone who opens a payment link;
+  every API answer ends with a note telling the assistant not to follow them.
+  Still read what a tool is about to change before you approve it.
+
+Docs: <https://pay.perly.io/docs/mcp>. API reference:
+<https://pay.perly.io/docs/api>. MIT licence.

package/dist/api.js

@@ -0,0 +1,82 @@
+export const MCP_VERSION = "0.1.1";
+function retryAfterMs(header, attempt) {
+    const seconds = header !== null ? Number(header) : NaN;
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.min(seconds * 1000, 30_000);
+    return 500 * 2 ** attempt;
+}
+export async function callApi(config, deps, method, path, query, body) {
+    const url = new URL(config.apiUrl + path);
+    for (const [k, v] of Object.entries(query ?? {})) {
+        if (v !== undefined && v !== null)
+            url.searchParams.set(k, String(v));
+    }
+    const headers = {
+        Accept: "application/json",
+        Authorization: `Bearer ${config.secretKey ?? ""}`,
+        "Perly-Client": `mcp/${MCP_VERSION}`,
+    };
+    let payload;
+    if (method === "POST") {
+        headers["Content-Type"] = "application/json";
+        headers["Idempotency-Key"] = (deps.uuid ?? (() => crypto.randomUUID()))();
+        payload = JSON.stringify(body ?? {});
+    }
+    const retries = deps.maxRetries ?? 2;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let attempt = 0;; attempt++) {
+        let response;
+        try {
+            response = await deps.fetch(url.toString(), {
+                method,
+                headers,
+                body: payload,
+                signal: AbortSignal.timeout(deps.timeoutMs ?? 30_000),
+            });
+        }
+        catch (error) {
+            if (attempt < retries) {
+                await sleep(retryAfterMs(null, attempt));
+                continue;
+            }
+            const timedOut = error?.name === "TimeoutError";
+            return {
+                ok: false,
+                status: 0,
+                error: {
+                    type: "connection_error",
+                    code: timedOut ? "timeout" : "connection_failed",
+                    message: `Could not reach Perly Pay at ${config.siteUrl}${timedOut ? " (no answer in time)" : ""}.`,
+                },
+            };
+        }
+        const text = await response.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = null;
+        }
+        if (response.ok)
+            return { ok: true, status: response.status, data: json };
+        const error = json?.error;
+        const inProgress = response.status === 409 && error?.code === "idempotency_in_progress";
+        const retriable = response.status === 429 || response.status >= 500 || inProgress;
+        if (retriable && attempt < retries) {
+            await sleep(retryAfterMs(response.headers.get("retry-after"), attempt));
+            continue;
+        }
+        return {
+            ok: false,
+            status: response.status,
+            error: {
+                type: error?.type ?? "api_error",
+                code: error?.code ?? `http_${response.status}`,
+                message: error?.message ?? `Perly Pay answered ${response.status}.`,
+                ...(error?.param ? { param: error.param } : {}),
+            },
+            ...(response.headers.get("perly-request-id") ? { requestId: response.headers.get("perly-request-id") } : {}),
+        };
+    }
+}

package/dist/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * `npx perly-pay-mcp`: Perly Pay's MCP server on stdio, for an AI coding
+ * assistant on this machine. It talks only to Perly Pay's public API with
+ * the key it is given; no server of ours sits in between.
+ *
+ *   PERLY_PAY_SECRET_KEY=sk_test_… npx -y perly-pay-mcp
+ */
+import { readConfig } from "./config.js";
+import { serve } from "./server.js";
+import { createToolbox, MCP_VERSION, SERVER_NAME } from "./toolbox.js";
+const args = process.argv.slice(2);
+if (args.includes("--version") || args.includes("-v")) {
+    process.stdout.write(`${MCP_VERSION}\n`);
+    process.exit(0);
+}
+if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write([
+        "perly-pay-mcp: Perly Pay's MCP server on stdio.",
+        "",
+        "  PERLY_PAY_SECRET_KEY      sk_test_… (or sk_live_…: then nothing that moves money or deletes)",
+        "  PERLY_PAY_API         default https://pay.perly.io",
+        "  PERLY_PAY_WEBHOOK_SECRET  optional whsec_…, for verify_webhook_signature",
+        "",
+        "  claude mcp add perly-pay --env PERLY_PAY_SECRET_KEY=sk_test_… -- npx -y perly-pay-mcp",
+        "",
+        "Docs: https://pay.perly.io/docs/mcp",
+        "",
+    ].join("\n"));
+    process.exit(0);
+}
+const config = readConfig(process.env);
+const toolbox = createToolbox(config, { fetch: globalThis.fetch });
+await serve(toolbox, { name: SERVER_NAME, version: MCP_VERSION, siteUrl: config.siteUrl });
+// The log never names the key, only its mode.
+process.stderr.write(`perly-pay-mcp ${MCP_VERSION}: ${config.mode ? `${config.mode} mode` : (config.keyProblem ?? "no key")} · ${config.siteUrl}${config.urlProblem ? ` · ${config.urlProblem}` : ""}\n`);

package/dist/config.js

@@ -0,0 +1,64 @@
+/**
+ * What the server is started with, from its environment:
+ *
+ *   PERLY_PAY_SECRET_KEY      sk_test_… or sk_live_… (Dashboard → Developers)
+ *   PERLY_PAY_API         default https://pay.perly.io (http only for this machine)
+ *   PERLY_PAY_WEBHOOK_SECRET  optional whsec_…, the default for verify_webhook_signature
+ *
+ * A missing or wrong key does not stop the server: every API tool answers
+ * how to set it, which an assistant can repeat, where a server that exits
+ * shows only "failed to connect".
+ */
+export const DEFAULT_SITE_URL = "https://pay.perly.io";
+const KEY = /^sk_(test|live)_[0-9A-Za-z]{32}$/;
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** The key's mode from its prefix, or why it is not a key. */
+export function checkKey(raw) {
+    const key = raw?.trim() ?? "";
+    if (!key) {
+        return { key: null, mode: null, problem: "No secret key. Set PERLY_PAY_SECRET_KEY to your sk_test_… key (Dashboard → Developers) in this MCP server's config." };
+    }
+    if (key.startsWith("whsec_"))
+        return { key: null, mode: null, problem: "PERLY_PAY_SECRET_KEY holds a webhook signing secret (whsec_…), not a secret key (sk_test_…)." };
+    const match = KEY.exec(key);
+    if (!match)
+        return { key: null, mode: null, problem: "PERLY_PAY_SECRET_KEY is not a Perly Pay secret key: it starts sk_test_ or sk_live_, then 32 letters and digits." };
+    return { key, mode: match[1], problem: null };
+}
+/** The site's origin from PERLY_PAY_API, with or without `/api/v1`. Plain http only to this machine: a key never crosses a network unencrypted. */
+export function checkUrl(raw) {
+    const text = raw?.trim() || DEFAULT_SITE_URL;
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return { siteUrl: DEFAULT_SITE_URL, problem: `PERLY_PAY_API is not a URL: ${text}` };
+    }
+    const local = LOCAL_HOSTS.has(url.hostname) || url.hostname.endsWith(".localhost");
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+        return { siteUrl: DEFAULT_SITE_URL, problem: "PERLY_PAY_API must be https (plain http only for localhost)." };
+    }
+    const path = url.pathname.replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+    return { siteUrl: `${url.origin}${path}`, problem: null };
+}
+export function readConfig(env) {
+    const key = checkKey(env.PERLY_PAY_SECRET_KEY);
+    const url = checkUrl(env.PERLY_PAY_API);
+    const webhookSecret = env.PERLY_PAY_WEBHOOK_SECRET?.trim() || null;
+    return {
+        secretKey: key.key,
+        mode: key.mode,
+        keyProblem: key.problem,
+        siteUrl: url.siteUrl,
+        apiUrl: `${url.siteUrl}/api/v1`,
+        urlProblem: url.problem,
+        webhookSecret,
+    };
+}
+/** Takes any secret key out of text before it reaches the assistant: the configured one, and anything shaped like one. */
+export function redact(text, secretKey) {
+    let out = secretKey ? text.split(secretKey).join("sk_…[hidden]") : text;
+    out = out.replace(/sk_(test|live)_[0-9A-Za-z]{8,}/g, "sk_$1_…[hidden]");
+    return out;
+}

package/dist/curation.js

@@ -0,0 +1,119 @@
+/**
+ * Which of the API's operations an assistant gets as a tool, and on what
+ * terms. Every operation in the OpenAPI document is named here, exposed or
+ * left out with a reason: `operations.drift.test.ts` fails when the API
+ * gains one this table does not decide on, so a new endpoint is a choice,
+ * never an accident.
+ *
+ * The line it draws: an assistant may build and test a shop end to end, and
+ * read a live one. With a live key it may not move or redirect money, send
+ * live events somewhere new, spend a buyer's credits or delete anything —
+ * those are for the merchant, in the dashboard (`pay_links`), or for their
+ * app's own code. Wallets, API keys, plans and live mode have no endpoint at
+ * all; an assistant can only point at the page.
+ */
+const allow = { expose: true, live: "allow" };
+/**
+ * Some clients read only so many tools (Cursor stops at 40, across every
+ * server), so the set stays under that: where a list or another tool
+ * already answers, the extra call is left out.
+ */
+const covered = (by) => ({ expose: false, why: `Covered by ${by}; left out to keep the set under clients' tool limits.` });
+export const CURATION = {
+    createInvoice: allow,
+    listInvoices: allow,
+    retrieveInvoice: allow,
+    cancelInvoice: { ...allow, confirm: "Cancels the invoice: its buyer can no longer pay it." },
+    simulatePayment: {
+        expose: true,
+        live: "refuse",
+        liveWhy: "Simulated payments exist only in test mode. Use a test key (sk_test_…) to try the flow.",
+    },
+    createCheckoutSession: allow,
+    listCheckoutSessions: covered("retrieve_checkout_session and list_invoices"),
+    retrieveCheckoutSession: allow,
+    expireCheckoutSession: covered("the session's own expiry (expires_in_minutes)"),
+    openCheckoutSession: { expose: false, why: "The buyer's page (pay.js opens it), not a merchant call." },
+    createProduct: allow,
+    listProducts: allow,
+    retrieveProduct: covered("list_products"),
+    updateProduct: allow,
+    createPrice: allow,
+    listPrices: allow,
+    retrievePrice: covered("list_prices"),
+    updatePrice: allow,
+    createCustomer: allow,
+    listCustomers: allow,
+    retrieveCustomer: allow,
+    updateCustomer: covered("create_customer (customers are found or made by email)"),
+    createSubscription: allow,
+    listSubscriptions: allow,
+    retrieveSubscription: allow,
+    updateSubscription: { expose: false, why: "Changing a subscriber's plan or quantity is the merchant's call, in the dashboard or their code." },
+    cancelSubscription: { expose: false, why: "Ends a buyer's access; the merchant's call, in the dashboard or their code." },
+    pauseSubscription: { expose: false, why: "Stops a buyer's billing; the merchant's call, in the dashboard or their code." },
+    resumeSubscription: { expose: false, why: "Restarts a buyer's billing; the merchant's call, in the dashboard or their code." },
+    prepaySubscription: { expose: false, why: "Bills a buyer ahead; the merchant's call, in the dashboard or their code." },
+    createPaymentLink: allow,
+    listPaymentLinks: allow,
+    retrievePaymentLink: covered("list_payment_links"),
+    updatePaymentLink: allow,
+    createCoupon: { expose: false, why: "Not in the first set: discounts are made in the dashboard." },
+    listCoupons: { expose: false, why: "Not in the first set: discounts are made in the dashboard." },
+    retrieveCoupon: { expose: false, why: "Not in the first set: discounts are made in the dashboard." },
+    updateCoupon: { expose: false, why: "Not in the first set: discounts are made in the dashboard." },
+    checkEntitlement: allow,
+    listEntitlements: allow,
+    retrieveEntitlement: covered("check_entitlement and list_entitlements"),
+    consumeEntitlementCredits: {
+        expose: true,
+        live: "refuse",
+        liveWhy: "Spending a real buyer's credits is for your app's own code (the SDK's credits helpers), not an assistant. Try it with a test key.",
+    },
+    retrieveCreditBalance: covered("check_entitlement (its credits_remaining)"),
+    consumeCredits: covered("consume_entitlement_credits, which refuses a live key for the same reason"),
+    listCreditUsage: allow,
+    validateLicenseKey: { expose: false, why: "Called by the merchant's software on a buyer's machine, with the buyer's key." },
+    activateLicenseKey: { expose: false, why: "Called by the merchant's software on a buyer's machine, with the buyer's key." },
+    deactivateLicenseKey: { expose: false, why: "Called by the merchant's software on a buyer's machine, with the buyer's key." },
+    listLicenseKeys: { expose: false, why: "Buyers' license keys are secrets; they stay in the dashboard." },
+    retrieveLicenseKey: { expose: false, why: "Buyers' license keys are secrets; they stay in the dashboard." },
+    revokeLicenseKey: { expose: false, why: "Takes a buyer's software away; the merchant's call, in the dashboard." },
+    createPortalSession: { expose: false, why: "A sign-in link for one buyer; made by the merchant's app when that buyer asks." },
+    listPayments: allow,
+    retrievePayment: allow,
+    quoteRefund: covered("create_refund and list_refunds"),
+    createRefund: {
+        expose: true,
+        live: "refuse",
+        liveWhy: "A live refund is real money sent from your own wallet. Open it in the dashboard (pay_links: refunds).",
+        confirm: "Opens a refund to the buyer.",
+    },
+    listRefunds: allow,
+    retrieveRefund: covered("list_refunds"),
+    markRefundSent: { expose: false, why: "Records real money sent; the merchant does it in the dashboard (pay_links: refunds)." },
+    listReceipts: allow,
+    retrieveReceipt: allow,
+    receiptPdf: { expose: false, why: "A binary PDF; retrieve_receipt has every figure, and the receipt's page has the file." },
+    listEvents: allow,
+    retrieveEvent: covered("list_events"),
+    createWebhookEndpoint: {
+        expose: true,
+        live: "refuse",
+        liveWhy: "Sending live events to a new address is set up in the dashboard (pay_links: webhooks).",
+    },
+    listWebhookEndpoints: allow,
+    retrieveWebhookEndpoint: covered("list_webhook_endpoints"),
+    updateWebhookEndpoint: covered("delete_webhook_endpoint and create_webhook_endpoint"),
+    deleteWebhookEndpoint: {
+        expose: true,
+        live: "refuse",
+        liveWhy: "Deleting with a live key is refused. Delete live webhook endpoints in the dashboard.",
+        confirm: "Deletes the webhook endpoint: its events stop.",
+    },
+    rollWebhookSecret: { expose: false, why: "A new signing secret breaks webhook checks until it is deployed; rolled in the dashboard." },
+};
+/** `createPaymentLink` → `create_payment_link`. */
+export function toolName(operationId) {
+    return operationId.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}

package/dist/generate.js

@@ -0,0 +1,159 @@
+/**
+ * Turns Perly Pay's OpenAPI document into the operations the MCP server
+ * exposes: for each operation the curation table exposes, its method and
+ * path, its words, and ONE input schema — path parameters, query parameters
+ * and the JSON body side by side, the shape a tool call carries.
+ *
+ * Pure: no app code, no network. `operations.drift.test.ts` runs it on the
+ * document the API serves (built from the same zod schemas that validate
+ * requests) and holds `operations.generated.ts` to the result.
+ */
+import { CURATION, toolName } from "./curation.js";
+const METHODS = ["get", "post", "delete"];
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Every operation in the document, in its order. */
+export function operationsOf(doc) {
+    const out = [];
+    for (const [path, item] of Object.entries((doc.paths ?? {}))) {
+        for (const method of METHODS) {
+            const op = item[method];
+            if (isObject(op))
+                out.push({ operationId: String(op.operationId), method: method.toUpperCase(), path, op });
+        }
+    }
+    return out;
+}
+function parametersOf(op) {
+    // `$ref`ed parameters are the shared Idempotency-Key header, which the server sets itself.
+    return (op.parameters ?? []).filter((p) => !("$ref" in p) && typeof p.name === "string");
+}
+/** A body that is one of several objects (a price's models) becomes one object: every field any variant has, required only where all require it. */
+function flattenBody(schema, where) {
+    if (schema.type === "object" && isObject(schema.properties)) {
+        return { properties: schema.properties, required: schema.required ?? [] };
+    }
+    const variants = (schema.oneOf ?? schema.anyOf);
+    if (!variants?.every((v) => v.type === "object" && isObject(v.properties))) {
+        throw new Error(`${where}: the body is neither an object nor a choice of objects`);
+    }
+    const seen = new Map();
+    for (const variant of variants) {
+        for (const [name, prop] of Object.entries(variant.properties)) {
+            const list = seen.get(name) ?? [];
+            if (!list.some((p) => JSON.stringify(p) === JSON.stringify(prop)))
+                list.push(prop);
+            seen.set(name, list);
+        }
+    }
+    const properties = {};
+    for (const [name, list] of seen) {
+        if (list.length === 1)
+            properties[name] = list[0];
+        else if (list.every((p) => p.type === "string" && "const" in p && Object.keys(p).length === 2)) {
+            properties[name] = { type: "string", enum: list.map((p) => p.const) };
+        }
+        else {
+            properties[name] = { anyOf: list };
+        }
+    }
+    const required = (variants[0].required ?? []).filter((name) => variants.every((v) => (v.required ?? []).includes(name)));
+    return { properties, required };
+}
+function describeFlattened(schema) {
+    const variants = (schema.oneOf ?? schema.anyOf);
+    if (!variants)
+        return null;
+    const lines = variants.map((v) => {
+        const props = v.properties;
+        const tag = Object.entries(props).find(([, p]) => "const" in p);
+        const req = (v.required ?? []).join(", ");
+        return tag ? `${tag[0]} = ${String(tag[1].const)}: needs ${req}` : `needs ${req}`;
+    });
+    return `Body is one of: ${lines.join("; ")}.`;
+}
+export function buildOperation(entry) {
+    const { operationId, method, path, op } = entry;
+    const where = `${method} ${path} (${operationId})`;
+    const properties = {};
+    const required = [];
+    const add = (name, schema, isRequired, kind) => {
+        if (name in properties)
+            throw new Error(`${where}: "${name}" is both a ${kind} field and another kind of field`);
+        properties[name] = schema;
+        if (isRequired)
+            required.push(name);
+    };
+    const pathParams = [];
+    const queryParams = [];
+    for (const p of parametersOf(op)) {
+        if (p.in === "path") {
+            pathParams.push(p.name);
+            add(p.name, { type: "string", description: p.description ?? "The object's id." }, true, "path");
+        }
+        else if (p.in === "query") {
+            queryParams.push(p.name);
+            add(p.name, { ...(p.schema ?? {}), ...(p.description ? { description: p.description } : {}) }, p.required ?? false, "query");
+        }
+    }
+    for (const name of path.match(/\{(\w+)\}/g)?.map((m) => m.slice(1, -1)) ?? []) {
+        if (!pathParams.includes(name))
+            throw new Error(`${where}: path parameter {${name}} is not declared`);
+    }
+    const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+    const bodyParams = [];
+    let note = null;
+    if (bodySchema) {
+        if (JSON.stringify(bodySchema).includes('"$ref"'))
+            throw new Error(`${where}: the body refers to a shared schema; inline it`);
+        const flat = flattenBody(bodySchema, where);
+        note = describeFlattened(bodySchema);
+        for (const [name, schema] of Object.entries(flat.properties)) {
+            bodyParams.push(name);
+            add(name, schema, flat.required.includes(name), "body");
+        }
+    }
+    const description = [op.description, note].filter((s) => typeof s === "string" && s.length > 0).join("\n\n");
+    return {
+        operationId,
+        tool: toolName(operationId),
+        method,
+        path,
+        summary: String(op.summary),
+        ...(description ? { description } : {}),
+        testOnly: op["x-test-mode-only"] === true,
+        pathParams,
+        queryParams,
+        bodyParams,
+        hasBody: Boolean(bodySchema),
+        inputSchema: {
+            type: "object",
+            properties,
+            ...(required.length ? { required } : {}),
+            additionalProperties: false,
+        },
+    };
+}
+/** The exposed operations, in the document's order. */
+export function buildOperations(doc) {
+    return operationsOf(doc)
+        .filter((entry) => CURATION[entry.operationId]?.expose === true)
+        .map(buildOperation);
+}
+/** The operations as the source of `operations.generated.ts`. */
+export function renderOperations(operations) {
+    return [
+        "/*",
+        " * GENERATED from Perly Pay's OpenAPI document (src/services/api/openapi.ts,",
+        " * served at /api/v1/openapi.json) by packages/mcp/src/generate.ts. Do not edit.",
+        " * After the API or src/curation.ts changes, regenerate:",
+        " *",
+        " *   npx vitest run packages/mcp/src/operations.drift.test.ts -u",
+        " */",
+        'import type { Operation } from "./generate.js";',
+        "",
+        `export const OPERATIONS: readonly Operation[] = ${JSON.stringify(operations, null, 2)};`,
+        "",
+    ].join("\n");
+}

package/dist/links.js

@@ -0,0 +1,26 @@
+/**
+ * What only a person can do, and where: the dashboard pages behind the
+ * steps no API key may take — choosing a plan, connecting a wallet, going
+ * live, two-factor sign-in, keys and live webhooks, live refunds.
+ */
+export const LINK_TOPICS = ["choose_plan", "connect_wallet", "go_live", "two_factor", "api_keys", "webhooks", "refunds", "checklist"];
+const LINKS = {
+    choose_plan: { path: "/dashboard/billing", what: "Choose or change the Perly Pay plan. Flat price, 0% of volume." },
+    connect_wallet: {
+        path: "/dashboard/wallets",
+        what: "Connect a wallet by its PUBLIC key or address. Payments land there directly; Perly Pay never asks for a seed or private key.",
+    },
+    go_live: { path: "/dashboard/wallets", what: "Turn on live mode once a wallet is connected. Test mode stays as it is." },
+    two_factor: { path: "/dashboard/settings/security", what: "Set up two-factor sign-in (a passkey or an authenticator app)." },
+    api_keys: { path: "/dashboard/developers", what: "Make, roll or revoke secret keys (sk_test_…, sk_live_…)." },
+    webhooks: { path: "/dashboard/developers", what: "Add, change or delete live webhook endpoints and roll their signing secrets." },
+    refunds: { path: "/dashboard/refunds", what: "Refund a live payment: you send it from your own wallet, then record the transaction." },
+    checklist: { path: "/dashboard/integrate", what: "What is left before the first real payment, ticked off as it is done." },
+};
+export function link(siteUrl, topic) {
+    const { path, what } = LINKS[topic];
+    return { topic, url: `${siteUrl}${path}`, what };
+}
+export function links(siteUrl, topic) {
+    return (topic ? [topic] : LINK_TOPICS).map((t) => link(siteUrl, t));
+}