@checkbox-site/mcp 0.2.0 → 0.2.1

package/dist/format.d.ts

@@ -57,6 +57,9 @@ export declare function fitJson(data: unknown, max?: number): {
     json: string;
     page?: string;
 };
+/** The "Next:" line of a result whose API object names no next step. */
+export declare const FALLBACK_NEXT = "Next: nothing more is needed for this result; get_compliance_plan names the site's next step.";
+export declare const FALLBACK_NEXT_ERROR = "Next: fix what the error names (see the hint above, if any) and call the tool again.";
 export declare function renderOutput(out: ToolOutput): CallToolResult;
 /** An API error as a tool result: stable code, message, param and the API's own next_action. */
 export declare function renderError(err: unknown): CallToolResult;

package/dist/format.js

@@ -15,6 +15,7 @@ export const OPERATION_TOOLS = {
     answerTask: 'answer_task',
     verifySite: 'verify_site',
     retrieveVerification: 'get_verification',
+    createTestCredential: 'store_stripe_test_key',
     createTestRun: 'start_test_run',
     retrieveTestRun: 'get_test_run',
     listTestRuns: 'get_test_run',
@@ -128,7 +129,10 @@ const OP_RE = new RegExp(`\\b(${[...Object.keys(OPERATION_TOOLS), ...Object.keys
  * the CLI is unpublished.
  */
 export function mcpText(text) {
-    let s = text.replace(/(?:POST )?\/v1\/checks\/(disclosure|stripe_checkout_session|stripe_payment_link|email|page|notice_schedule)\b/g, (_m, k) => CHECK_PATH_TOOLS[k]);
+    // Round 23 (pilot 22 item 9): the REST body `{ type: "stripe_test", secret_key }` is said as the MCP tool's own
+    // arguments (store_stripe_test_key takes { secret_key }; `type` is accepted but not needed).
+    let s = text.replace(/\{ ?type: ?"stripe_test", ?secret_key\b/g, '{ secret_key');
+    s = s.replace(/(?:POST )?\/v1\/checks\/(disclosure|stripe_checkout_session|stripe_payment_link|email|page|notice_schedule)\b/g, (_m, k) => CHECK_PATH_TOOLS[k]);
     s = s.replace(OP_RE, (op) => {
         // Round 16 (pilot 15, sveltekit): "verifySetupSession" became plain get_setup_status, which only reads the checklist,
         // so the agent looped on "Snippet installed: pending". The re-check is get_setup_status with verify=true.
@@ -191,6 +195,9 @@ export function describeNextAction(next, ctx = {}) {
     const text = mcpText((next.message ?? next.description ?? '').trim());
     if (next.type === 'done' || next.type === 'none')
         return `Next: nothing left to do${text ? ` — ${text}` : '.'}`;
+    // Round 23 (pilot 22, headless-agent-pr): everything left waits for a deploy or the owner.
+    if (next.type === 'done_for_now')
+        return `Next: done for this change — ${text || 'the rest waits for a deploy or the owner.'}`;
     const op = next.operation_id ?? undefined;
     // Prefer the API's own mapping (next_action.mcp_tool); `call_api` means "no dedicated tool".
     const named = next.mcp_tool && next.mcp_tool !== 'call_api' ? next.mcp_tool : undefined;
@@ -330,14 +337,17 @@ export function fitJson(data, max = MAX_JSON_CHARS) {
         page: `Output too large (${compact.length} characters): narrow the request (a smaller limit, or one item at a time).`,
     };
 }
+/** The "Next:" line of a result whose API object names no next step. */
+export const FALLBACK_NEXT = 'Next: nothing more is needed for this result; get_compliance_plan names the site\'s next step.';
+export const FALLBACK_NEXT_ERROR = 'Next: fix what the error names (see the hint above, if any) and call the tool again.';
 export function renderOutput(out) {
     const lines = [mcpText(out.headline.trim())];
     for (const n of out.notes ?? [])
         if (n)
             lines.push(`- ${mcpText(n)}`);
     const next = describeNextAction(out.next === undefined ? nextActionOf(out.data) : out.next, { data: out.data });
-    if (next)
-        lines.push(next);
+    // Round 23 (pilot 22 item 27, agent-discovery: a result with no "Next:" line): every result names what comes next.
+    lines.push(next ?? (out.isError ? FALLBACK_NEXT_ERROR : FALLBACK_NEXT));
     if (out.data !== undefined) {
         const fitted = fitJson(forMcp(out.data));
         if (fitted.page)
@@ -397,7 +407,7 @@ function missingNext(message) {
     return { type: 'find_id', message: 'Call get_compliance_plan for the current task ids (each task carries its last_verification id).', operation_id: 'retrieveCompliancePlan' };
 }
 const ERROR_HINTS = {
-    insufficient_scope: 'This connection lacks that permission (a read-only connection or a restricted key). Ask the human to reconnect Checkbox with write access (or change the key\'s permissions in the Checkbox dashboard → Developers); never ask them to paste a key. Read-only tools still work.',
+    insufficient_scope: 'This connection lacks that permission (a read-only connection or a restricted key). Ask the human to reconnect Checkbox and choose Full access on the approval page: Codex: `codex mcp logout checkbox`, then `codex mcp login checkbox`; Claude Code: `/mcp` → checkbox → Clear authentication → Authenticate; claude.ai / Claude Desktop: Settings → Connectors → Checkbox → Disconnect, then Connect. For an API key, change its permissions in the Checkbox dashboard → Agent & API. Never ask them to paste a key. Read-only tools still work.',
     insufficient_role: 'The key acts as a viewer; writes need a member or admin key.',
     api_key_missing: 'No Checkbox API key is configured: call setup_checkbox (one browser approval by the human) to get one.',
     api_key_invalid: 'The configured Checkbox API key is unknown, revoked or expired: reconnect with setup_checkbox (one browser approval by the human), or ask the human to fix the key in the Checkbox dashboard → Developers. Never ask them to paste a key into the chat.',

package/dist/key-file.d.ts

@@ -0,0 +1,21 @@
+export interface KeysToSave {
+    secret_key: string;
+    publishable_key?: string | null;
+    live_secret_key?: string | null;
+    live_publishable_key?: string | null;
+}
+export type SavedKeys = {
+    ok: true;
+    file: string;
+    gitignored: boolean;
+    note?: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const ENV_FILE = ".env.local";
+export declare const FALLBACK_FILE = ".checkbox/keys.env";
+/** Writes the issued keys to the project's git-ignored env file. Never throws. */
+export declare function saveKeysToProject(root: string, keys: KeysToSave): SavedKeys;
+/** The CHECKBOX_SECRET_KEY saved by an earlier device login in this folder (.env.local, then .checkbox/keys.env). */
+export declare function readSavedKey(root: string): string | undefined;

package/dist/key-file.js

@@ -0,0 +1,118 @@
+// Round 25 (pilot 24 item 12, security-reviewer): the stdio device login returned the full ck_test_ secret key in the
+// tool result, so it landed in the LLM transcript (and in whatever logs the client keeps). The local stdio server now
+// writes the issued keys to a git-ignored file in the project itself and returns only a hint ("ck_test_…ab12" and the
+// file name). The next start of `checkbox-mcp` in the same folder reads the key back from that file.
+//
+// Where: .env.local in the project folder (what `checkbox init` writes, and what most frameworks load), unless git
+// tracks .env.local (a secret written there would go into the next commit even with .gitignore): then
+// .checkbox/keys.env, in a folder whose own .gitignore ignores everything.
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const ENV_FILE = '.env.local';
+export const FALLBACK_FILE = '.checkbox/keys.env';
+function read(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function gitTracked(root, file) {
+    try {
+        execFileSync('git', ['ls-files', '--error-unmatch', '--', file], { cwd: root, stdio: 'ignore', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function gitIgnores(root, file) {
+    try {
+        execFileSync('git', ['check-ignore', '-q', '--', file], { cwd: root, stdio: 'ignore', timeout: 5000 });
+        return true;
+    }
+    catch (err) {
+        // Exit 1: not ignored. Anything else (no git, not a repository): unknown.
+        return err.status === 1 ? false : null;
+    }
+}
+function upsertLines(existing, entries, header) {
+    let text = existing ?? '';
+    const missing = [];
+    for (const [k, v] of entries) {
+        const re = new RegExp(`^${k}=.*$`, 'm');
+        if (re.test(text))
+            text = text.replace(re, `${k}=${v}`);
+        else
+            missing.push([k, v]);
+    }
+    if (missing.length) {
+        const block = [header, ...missing.map(([k, v]) => `${k}=${v}`)];
+        text = `${text}${text && !text.endsWith('\n') ? '\n' : ''}${text ? '\n' : ''}${block.join('\n')}\n`;
+    }
+    return text;
+}
+/** Makes sure .gitignore covers .env.local (only in a git project, or when a .gitignore already exists). */
+function ensureIgnored(root, file) {
+    const ignored = gitIgnores(root, file);
+    if (ignored === true)
+        return true;
+    const path = join(root, '.gitignore');
+    const existing = read(path);
+    if (existing !== null) {
+        const lines = existing.split(/\r?\n/).map((l) => l.trim());
+        if (lines.some((l) => l === file || l === `/${file}` || l === '.env*' || l === '.env*.local' || l === '*.local' || l === '.env.local*'))
+            return true;
+    }
+    if (existing === null && !existsSync(join(root, '.git')))
+        return false;
+    writeFileSync(path, `${existing ?? ''}${existing && !existing.endsWith('\n') ? '\n' : ''}# Checkbox keys (checkbox-mcp)\n${file}\n`);
+    return true;
+}
+/** Writes the issued keys to the project's git-ignored env file. Never throws. */
+export function saveKeysToProject(root, keys) {
+    const entries = [['CHECKBOX_SECRET_KEY', keys.secret_key]];
+    if (keys.publishable_key)
+        entries.push(['CHECKBOX_PUBLISHABLE_KEY', keys.publishable_key]);
+    if (keys.live_secret_key)
+        entries.push(['CHECKBOX_LIVE_SECRET_KEY', keys.live_secret_key]);
+    if (keys.live_publishable_key)
+        entries.push(['CHECKBOX_LIVE_PUBLISHABLE_KEY', keys.live_publishable_key]);
+    const header = '# Checkbox (subscription compliance), written by checkbox-mcp. Secret: never commit this file.';
+    try {
+        if (!gitTracked(root, ENV_FILE)) {
+            const path = join(root, ENV_FILE);
+            writeFileSync(path, upsertLines(read(path), entries, header), { mode: 0o600 });
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch {
+                // best effort (some file systems ignore modes)
+            }
+            const gitignored = ensureIgnored(root, ENV_FILE);
+            return { ok: true, file: ENV_FILE, gitignored };
+        }
+        const dir = join(root, '.checkbox');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (read(join(dir, '.gitignore')) === null)
+            writeFileSync(join(dir, '.gitignore'), '# Checkbox local secrets: never committed\n*\n');
+        const path = join(root, FALLBACK_FILE);
+        writeFileSync(path, upsertLines(read(path), entries, header), { mode: 0o600 });
+        return { ok: true, file: FALLBACK_FILE, gitignored: true, note: `${ENV_FILE} is tracked by git, so the key was not written there.` };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** The CHECKBOX_SECRET_KEY saved by an earlier device login in this folder (.env.local, then .checkbox/keys.env). */
+export function readSavedKey(root) {
+    for (const file of [ENV_FILE, FALLBACK_FILE]) {
+        const text = read(join(root, file));
+        const m = text ? /^CHECKBOX_SECRET_KEY=["']?([A-Za-z0-9_]+)["']?\s*$/m.exec(text) : null;
+        if (m?.[1])
+            return m[1];
+    }
+    return undefined;
+}

package/dist/resources.js

@@ -48,10 +48,11 @@ what to change. Free. Every feature. No credit card. Fair-use limits.
 1. **setup_checkbox** — connected through the Checkbox connector (OAuth: claude.ai, Claude Desktop, Claude Code, Cursor)
    the human already approved: it registers the site and runs the first checks at once, no key involved. Without any
    credential (device login) it returns ONE link for the human ("Open … and click Approve"); call it again with the
-   device_code to receive test-mode keys. With an API key it starts a setup session. Pass what you know:
+   device_code (the local stdio server saves the key to the project's git-ignored .env.local itself and shows only a
+   hint; prefer OAuth wherever the client supports it). With an API key it starts a setup session. Pass what you know:
    site_url, checkout_url, terms_url / refund_url / cancellation_url, billing_platform, plans, project.layout_file.
    (The \`checkbox init\` CLI, \`npx @checkbox-site/cli init\`, does the same and patches the layout file.)
-2. Follow the setup **next_action** (install the snippet in the root layout, store a Stripe TEST key for test runs,
+2. Follow the setup **next_action** (install the snippet in the root layout, store the one Stripe TEST restricted key yourself with store_stripe_test_key,
    register checkout params). After each change: **update_setup**, then **get_setup_status** with verify=true.
 3. **get_compliance_plan** — ordered tasks: requirement + citation, where (file / selector / Stripe object), the exact
    change (diff template, copy, or Stripe params) and how to verify.
@@ -90,7 +91,8 @@ Every tool result ends with "Next: …" naming the tool to call. Errors carry a
   \`Authorization: Bearer <key>\`. Agents without a browser: \`${opts.mcpUrl}?login=device\` offers setup_checkbox's
   device login.
 - Local (stdio): the \`checkbox-mcp\` binary (packages/mcp) with CHECKBOX_API_KEY set; without a key it starts with
-  setup_checkbox only and switches to the issued key after the human approves.
+  setup_checkbox only and switches to the issued key after the human approves (it saves the key to the project's
+  git-ignored .env.local itself; the key never appears in the conversation).
 - REST: ${opts.apiBase}/v1 — OpenAPI at ${opts.apiBase}/v1/openapi.json.
 
 Automated compliance checks, not legal advice.

package/dist/server.d.ts

@@ -2,10 +2,10 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { CheckboxApi } from './api.ts';
 import type { KeyContext } from './permissions.ts';
-import { type IssuedKeys, type ToolDef } from './tools.ts';
+import { type IssuedKeys, type ToolContext, type ToolDef } from './tools.ts';
 export declare const SERVER_NAME = "checkbox";
 /** Kept equal to packages/mcp/package.json "version" (@checkbox-site/mcp); mcp.test.ts checks it. */
-export declare const SERVER_VERSION = "0.2.0";
+export declare const SERVER_VERSION = "0.2.1";
 export declare const DEFAULT_MCP_URL = "https://app.checkbox.site/mcp";
 /** The coverage phrase used across Checkbox (the API docs tests check the count against the rules catalog). */
 export declare const COVERAGE_PHRASE = "federal law, 27 states, DC and New York City";
@@ -22,6 +22,8 @@ export interface CheckboxMcpOptions {
         api: CheckboxApi;
         key: KeyContext;
     }>;
+    /** stdio: writes device-login keys to a git-ignored file in the project, so the tool result carries only a hint. */
+    saveKeys?: ToolContext['saveKeys'];
     /** Called for every tool call (metrics / logs). Never receives arguments (they may hold page HTML or keys). */
     onToolCall?: (event: {
         tool: string;

package/dist/server.js

@@ -9,7 +9,7 @@ import { likelyMisspelling, unknownArgumentsMessage, unknownKeysParams } from ".
 import { outdatedNotice } from "./version-check.js";
 export const SERVER_NAME = 'checkbox';
 /** Kept equal to packages/mcp/package.json "version" (@checkbox-site/mcp); mcp.test.ts checks it. */
-export const SERVER_VERSION = '0.2.0';
+export const SERVER_VERSION = '0.2.1';
 export const DEFAULT_MCP_URL = 'https://app.checkbox.site/mcp';
 /** The coverage phrase used across Checkbox (the API docs tests check the count against the rules catalog). */
 export const COVERAGE_PHRASE = 'federal law, 27 states, DC and New York City';
@@ -114,6 +114,7 @@ export function createCheckboxMcpServer(opts) {
             serverVersion: SERVER_VERSION,
             ...(opts.devicePoll ? { devicePoll: opts.devicePoll } : {}),
             ...(opts.apiForKey ? { apiForKey: opts.apiForKey } : {}),
+            ...(opts.saveKeys ? { saveKeys: opts.saveKeys } : {}),
             ...(client?.name ? { clientName: client.name } : {}),
             ...(opts.adoptKeys
                 ? {

package/dist/stdio.d.ts

@@ -6,6 +6,8 @@ export interface StdioOptions {
     fetch?: typeof fetch;
     /** Diagnostics go to stderr (stdout is the protocol). */
     log?: (line: string) => void;
+    /** The project folder the device login saves its keys in (default: the process's working folder). */
+    cwd?: string;
 }
 export interface ResolvedConfig {
     apiKey?: string;

package/dist/stdio.js

@@ -1,11 +1,13 @@
 // Local stdio MCP server (`checkbox-mcp`) for clients without remote MCP support, or for teams that prefer a local
-// process. Reads CHECKBOX_API_KEY (or CHECKBOX_SECRET_KEY, which `checkbox init` writes to .env.local) and calls
+// process. Reads CHECKBOX_API_KEY (or CHECKBOX_SECRET_KEY, from the environment or the project's .env.local, which
+// `checkbox init` and this server's device login write) and calls
 // the API over HTTPS — through @checkbox-site/node when it provides a client, else with the built-in fetch client.
 // Without a key it starts with setup_checkbox only and switches to the issued key once the human approves.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CheckboxApiError, createHttpApi, DEFAULT_API_BASE, fromSdkClient } from "./api.js";
 import { keyContextFromPrefix } from "./permissions.js";
 import { createCheckboxMcpServer, DEFAULT_MCP_URL, SERVER_VERSION } from "./server.js";
+import { readSavedKey, saveKeysToProject } from "./key-file.js";
 export function resolveConfig(env, argv) {
     const flag = (name) => {
         const i = argv.indexOf(name);
@@ -75,6 +77,13 @@ export async function runStdio(opts = {}) {
         return;
     }
     const cfg = resolveConfig(env, argv);
+    const cwd = opts.cwd ?? process.cwd();
+    // Round 25 (pilot 24 item 12): a key an earlier device login saved in this folder (never shown in the transcript).
+    if (!cfg.apiKey) {
+        const saved = readSavedKey(cwd);
+        if (saved)
+            cfg.apiKey = saved;
+    }
     const api = await buildApi(cfg, opts.fetch);
     let key;
     try {
@@ -93,6 +102,7 @@ export async function runStdio(opts = {}) {
             const nextApi = await buildApi({ apiKey: keys.secret_key, apiBase: cfg.apiBase }, opts.fetch);
             return { api: nextApi, key: await describeKey(nextApi, keys.secret_key, cfg.readOnly) };
         },
+        saveKeys: async (keys) => saveKeysToProject(cwd, keys),
     });
     await mcp.server.connect(new StdioServerTransport());
     log(`checkbox-mcp ${SERVER_VERSION}: ${key.authenticated ? `${key.mode} mode, ${mcp.visibleTools().length} tools` : 'no API key — setup_checkbox only'} (${cfg.apiBase})`);

package/dist/tools.d.ts

@@ -28,6 +28,19 @@ export interface ToolContext {
     };
     /** An API client for a key issued during this call (remote: the rest of setup_checkbox runs with it). */
     apiForKey?: (secretKey: string) => CheckboxApi;
+    /**
+     * stdio (round 25, pilot 24 item 12): writes the issued keys to a git-ignored file in the project, so the result
+     * carries only a hint and the secret key never enters the LLM transcript.
+     */
+    saveKeys?: (keys: IssuedKeys) => Promise<{
+        ok: true;
+        file: string;
+        gitignored: boolean;
+        note?: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
 }
 export interface ToolDef {
     name: string;

package/dist/tools.js

@@ -105,12 +105,12 @@ const setupFactsShape = {
     privacy_url: z.string().max(2048).nullable().optional().describe('Privacy policy URL.'),
     refund_url: z.string().max(2048).nullable().optional().describe('Refund policy URL.'),
     cancellation_url: z.string().max(2048).nullable().optional().describe('Cancellation policy URL, if separate from the Terms.'),
-    support_email: z.string().max(320).optional().describe('Support address subscribers can write to.'),
+    support_email: z.string().max(320).optional().describe('Support address for subscribers.'),
     merchant_name: z.string().max(100).optional().describe('The brand subscribers know (names the seller in generated disclosures), e.g. from the <title> or package.json (also accepted as "brand"). Default: the host name, which the plan then asks you to replace.'),
     billing_platform: z
-        .enum(['stripe', 'shopify', 'recharge', 'chargebee', 'recurly', 'paddle', 'woocommerce', 'custom'])
+        .enum(['stripe', 'shopify', 'recharge', 'chargebee', 'recurly', 'paddle', 'lemon_squeezy', 'woocommerce', 'custom'])
         .optional()
-        .describe('Billing platform the code uses.'),
+        .describe('Billing platform.'),
     plans: z
         .array(strictObject({
         name: z.string().max(200).optional(),
@@ -406,7 +406,7 @@ export function sitePlansNote(plans) {
     if (!Array.isArray(plans))
         return null;
     if (!plans.length)
-        return 'Plans: none known yet. Pass plans[] (name, price, interval, trial, Stripe price id) with update_setup, or ask the human to connect Stripe.';
+        return 'Plans: none known yet. Pass plans[] ({ name, amount, currency, interval, trial_days, price_id }) with update_setup, or ask the human to connect Stripe.';
     const lines = plans.slice(0, 6).map((p) => {
         const every = (p.interval_count ?? 1) > 1 ? `every ${p.interval_count} ${p.interval}s` : `/${p.interval ?? '?'}`;
         const trial = p.trial_days ? `, ${p.trial_days}-day trial` : ', no trial';
@@ -515,7 +515,7 @@ const setupCheckbox = {
         'Connected through the Checkbox connector (OAuth: claude.ai, Claude Desktop, Claude Code /mcp, Cursor, VS Code): the human already approved in the browser; there is NO key to ask for, paste or save. Call it with site_url (and what else you know): it registers the site and runs the first checks in the same call.',
         'Pass everything you already know from the codebase: site_url, checkout_url, terms/privacy/refund/cancellation URLs, billing_platform, plans, project.layout_file. Checkbox fetches and checks the Terms itself.',
         '',
-        'Only for clients without OAuth (no API key configured on this server): it returns a link for the HUMAN to open and click Approve (free, no card). Show them the link in one line, then call setup_checkbox again with the returned device_code — it waits up to ~50 s; call again while it says pending. On approval it returns test-mode API keys (shown once): save CHECKBOX_SECRET_KEY to .env.local (git-ignored), never commit it, and never ask the human to paste a key.',
+        'Only for clients without OAuth (no API key configured on this server): it returns a link for the HUMAN to open and click Approve (free, no card). Show them the link in one line, then call setup_checkbox again with the returned device_code — it waits up to ~50 s; call again while it says pending. On approval the stdio server saves the key to the git-ignored .env.local, showing a hint; the remote one returns it once: save it to .env.local, never commit it or ask for a pasted key.',
         '',
         'After this: follow next_action (usually verify the domain and install the snippet, then get_setup_status with verify=true), then get_compliance_plan.',
     ].join('\n'),
@@ -542,16 +542,28 @@ const setupCheckbox = {
                 };
             }
             const notes = [];
+            const saved = ctx.saveKeys ? await ctx.saveKeys(res).catch((err) => ({ ok: false, error: err instanceof Error ? err.message : String(err) })) : null;
             if (ctx.adoptKeys) {
                 await ctx.adoptKeys(res);
                 notes.push('This MCP server now uses the new test-mode key for the rest of the session (more tools are now available).');
-                notes.push('Save CHECKBOX_SECRET_KEY to .env.local (and set CHECKBOX_API_KEY in the MCP server config) so future sessions keep working.');
+                if (saved?.ok) {
+                    notes.push(`The secret key was saved to ${saved.file} in this project${saved.gitignored ? ' (git-ignored)' : ' (add it to .gitignore: this folder is not a git repository)'} and is not shown here: never print, copy or commit it. ${saved.note ?? ''}This server reads it from there on its next start.`.replace(/ +/g, ' '));
+                }
+                else if (saved) {
+                    notes.push(`The key could not be saved in this project (${saved.error.slice(0, 160)}), and it is not shown here. This server uses it until it stops; for a lasting key, the human creates one in the Checkbox dashboard (Agent & API) and sets CHECKBOX_API_KEY in the MCP server config.`);
+                }
+                else {
+                    notes.push('Save CHECKBOX_SECRET_KEY to .env.local (and set CHECKBOX_API_KEY in the MCP server config) so future sessions keep working.');
+                }
             }
             else {
                 notes.push('This remote MCP connection is stateless and keeps no key: save CHECKBOX_SECRET_KEY to .env.local and pass it on the connection (Authorization: Bearer) for the next calls:');
                 notes.push(`claude mcp add --transport http checkbox ${ctx.mcpUrl} --header "Authorization: Bearer $CHECKBOX_SECRET_KEY" (Cursor / VS Code: add the same header to the server config). Until then, the plan below is all you need; the HTTP API works with the key right away.`);
             }
-            notes.push('The secret key is shown only this once. Never commit it; the publishable key (pk_) is safe in browser code (e.g. NEXT_PUBLIC_CHECKBOX_PUBLISHABLE_KEY).');
+            if (!saved)
+                notes.push('The secret key is shown only this once. Never commit it; the publishable key (pk_) is safe in browser code (e.g. NEXT_PUBLIC_CHECKBOX_PUBLISHABLE_KEY).');
+            else
+                notes.push('The publishable key (pk_) is safe in browser code (e.g. NEXT_PUBLIC_CHECKBOX_PUBLISHABLE_KEY).');
             // Round 16 (pilot 15, sveltekit / change-guard): two public keys in one response, unexplained.
             notes.push("Two public keys: the snippet tag's data-key is the site's snippet key (install.snippet_key; use the script_tag exactly as given); publishable_key is the account key for Checkbox Elements and consent receipts only.");
             // In the same call, with the new key: apply the facts given (they are not lost between the two calls), run the
@@ -600,10 +612,11 @@ const setupCheckbox = {
                 notes,
                 ...(next ? { next } : {}),
                 data: {
-                    ...res,
+                    ...(saved ? withoutSecrets(res) : res),
                     site,
                     ...(next ? { next_action: next } : {}),
-                    env: { CHECKBOX_SECRET_KEY: res.secret_key, ...(res.publishable_key ? { CHECKBOX_PUBLISHABLE_KEY: res.publishable_key } : {}) },
+                    ...(saved?.ok ? { key_file: saved.file } : {}),
+                    env: { CHECKBOX_SECRET_KEY: saved ? `${hintOf(res.secret_key)} (${saved.ok ? `saved in ${saved.file}` : 'not shown'})` : res.secret_key, ...(res.publishable_key ? { CHECKBOX_PUBLISHABLE_KEY: res.publishable_key } : {}) },
                     public_keys: labelledPublicKeys(snippetKey ?? res.install?.snippet_key, res.publishable_key),
                     ...(firstCheck ? { first_check: firstCheck } : {}),
                     ...(inputWarnings.length ? { warnings: inputWarnings } : {}),
@@ -659,6 +672,17 @@ const setupCheckbox = {
         };
     },
 };
+/** "ck_test_…ab12": recognisable, never usable. */
+function hintOf(key) {
+    if (!key)
+        return null;
+    const m = /^([a-z]{2}_(?:live|test)_)/.exec(key);
+    return `${m?.[1] ?? key.slice(0, 3)}…${key.slice(-4)}`;
+}
+/** The device token without its secret keys (hints only): what the stdio server returns once it saved them. */
+function withoutSecrets(res) {
+    return { ...res, secret_key: hintOf(res.secret_key), ...(res.live_secret_key ? { live_secret_key: hintOf(res.live_secret_key) } : {}) };
+}
 /**
  * Round 20 (pilot 19 item 16, sveltekit / change-guard: a pk_ site key and a pk_test_ key side by side, unlabelled): each
  * public key says what it is for.
@@ -1040,7 +1064,7 @@ const getVerification = {
 // ---------------------------------------------------------------------------------------------------------------------
 /** createTestRun body from the tool's arguments (top-level shortcuts merged into `stripe`). Exported for tests. */
 export function startTestRunBody(args) {
-    const body = pick(args, ['mode', 'type', 'advance_time', 'cancel', 'email_wait_seconds', 'region', 'stripe', 'generic']);
+    const body = pick(args, ['mode', 'type', 'advance_time', 'cancel', 'email_wait_seconds', 'region', 'plan', 'stripe', 'generic']);
     const shortcuts = pick(args, ['checkout_url', 'test_account', 'checkout_steps', 'cancel_url', 'cancel_steps']);
     if (Object.keys(shortcuts).length && body.type !== 'generic') {
         body.stripe = { ...shortcuts, ...(body.stripe ?? {}) };
@@ -1049,12 +1073,40 @@ export function startTestRunBody(args) {
     }
     return body;
 }
+/**
+ * Round 22 (founder decision 2): the agent stores the site's ONE Stripe TEST-mode restricted key itself
+ * (createTestCredential). Live keys and sk_test_ secret keys are refused by the API with what to do instead.
+ */
+const storeStripeTestKey = {
+    name: 'store_stripe_test_key',
+    title: 'Store the Stripe TEST restricted key (rk_test_)',
+    description: 'Stores the site\'s ONE Stripe key in TEST mode: a restricted key (rk_test_…) from the project\'s env. Checked with Stripe; on a test-mode site it also connects Stripe (checks, fixes after the human approves, test runs). The human sees it on the dashboard and can revoke it. Live and sk_test_ keys are refused (the error says what to do). Never ask the human to paste a key into the chat.',
+    input: {
+        site: siteId.optional(),
+        secret_key: z.string().min(10).max(255).describe('rk_test_… key. Stored encrypted; never returned.'),
+        confirm_account_mismatch: z.boolean().optional().describe('Human said yes'),
+        type: z.enum(['stripe_test', 'stripe']).optional().describe('Optional: "stripe_test" (the REST body\'s type; "stripe" is accepted too). Always stored as a Stripe TEST key.'),
+    },
+    scopes: ['test_runs:write'],
+    annotations: { ...write(true, true), title: 'Store Stripe test key' },
+    async run(args, { api }) {
+        const site = await resolveSite(api, args.site);
+        const cred = await api.request('POST', `/v1/sites/${enc(site)}/test_credentials`, {
+            body: { type: 'stripe_test', secret_key: String(args.secret_key ?? ''), ...(args.confirm_account_mismatch === true ? { confirm_account_mismatch: true } : {}) },
+        });
+        return {
+            headline: `Stripe test key ${cred.key_hint} stored for ${site} (checked with Stripe). The human sees it on the dashboard and can revoke it.`,
+            data: cred,
+            next: cred.next_action ?? { type: 'continue_setup', message: 'Call get_setup_status for the next step (start_test_run once a checkout config is registered).', operation_id: 'retrieveSetupSession' },
+        };
+    },
+};
 const startTestRun = {
     name: 'start_test_run',
     title: 'Run a synthetic test subscription (test mode)',
     description: [
         'Observes the WHOLE subscription lifecycle, not just the checkout: in the billing platform\'s TEST mode Checkbox subscribes a test customer (card 4242…) whose email is a Checkbox inbox, waits for your acknowledgment email, fast-forwards a Stripe test clock through every legal notice window before trial end and renewal (collecting reminder emails), then cancels online and waits for the cancellation confirmation. Nothing is charged.',
-        'Needs a Stripe TEST key stored for the site — the human adds it in the Checkbox dashboard (the site\'s Proof page); never ask them to paste it into the chat. If missing, the error\'s next_action says so. For non-Stripe sites use type "generic".',
+        'Needs a Stripe TEST-mode restricted key (rk_test_…) stored for the site: store it yourself with store_stripe_test_key (one key for checks, fixes and test runs; live keys stay with the human in the dashboard). Never ask the human to paste a key into the chat. If missing, the error\'s next_action says so. For non-Stripe sites use type "generic".',
         'Usually 2-4 minutes: poll get_test_run (its next_action says when). Each step reports observations, check results and agent-readable fixes; apply them and run again.',
         'mode "real_checkout" is the PROOF run: the shopper buys through the merchant\'s own checkout on its test deployment (stripe.checkout_url or stripe.payment_link), so the merchant\'s webhook handlers and email code fire; give stripe.test_account + stripe.cancel_url when customers cancel in the app. A step is "passed" only with evidence; "warning" means needs review.',
     ].join('\n'),
@@ -1066,6 +1118,7 @@ const startTestRun = {
         cancel: z.boolean().optional().describe('Cancel online at the end (default true).'),
         email_wait_seconds: z.number().int().min(15).max(900).optional().describe('How long to wait for each email (default 120).'),
         region: z.string().max(10).optional().describe('State the synthetic shopper visits from, e.g. "US-CA".'),
+        plan: z.string().max(200).optional().describe('Plan to run: a registered checkout config name or a price_… its line_items use.'),
         stripe: z
             .object({
             checkout_config: z.string().max(100).optional().describe('Registered checkout config (scc_…) to mirror; default the newest, else the latest live Checkout Session; "none" skips registered configs.'),
@@ -1153,9 +1206,11 @@ const checkDisclosure = {
     input: {
         text: z.string().min(1).max(5000).describe('The disclosure shown next to the purchase button, exactly as rendered.'),
         ...planTermsShape,
-        interval: intervalStr,
+        interval: intervalStr.optional().describe('Billing interval: day, week, month or year (optional with site).'),
         button_text: z.string().max(200).optional().describe('Purchase button label, e.g. "Start free trial".'),
         order_summary: z.string().max(1000).optional().describe('Other text next to the button (order summary), if any.'),
+        site: z.string().max(100).optional().describe('site_… whose plans judge it (as verify_task)'),
+        plan: z.string().max(200).optional().describe('With site: plan name or price_…'),
         placement: strictObject({
             above_button: z.boolean().optional(),
             same_page_as_payment: z.boolean().optional(),
@@ -1642,7 +1697,8 @@ const getSiteStatus = {
         const ro = unverifiedScanNote(site.unverified_scan);
         const notes = [
             ...(todo.length ? [`To do (${todo.length}, from the compliance plan, in order):`, ...todo.map((t, i) => `${i + 1}. ${t.id} ${todoLine(t)}`)] : []),
-            ...(evaluated && label ? pendingLive.slice(0, 6).map((p) => `LIVE CHECK PENDING ${p.check_id}: ${p.what} — ${p.completes}`) : []),
+            // Round 25 (pilot 24 item 22: "4 live checks pending" listed 3): every pending live check the label counts.
+            ...(evaluated && label ? pendingLive.map((p) => `LIVE CHECK PENDING ${p.check_id}: ${p.what} — ${p.completes}`) : []),
             ...(ro ? [ro] : []),
             ...shopifyLines(site.shopify, site.id),
         ];
@@ -1970,7 +2026,8 @@ const getCompliantDisclosure = {
         return {
             headline: `Suggested disclosure generated (${r.replacement.verified ? 'passes the checks, verified by the rules engine' : 'not fully verified by the rules engine'}).`,
             notes: [
-                `Disclosure: ${r.replacement.disclosure_text}`,
+                // Round 23 (pilot 22 item 30): the short line first when the engine passes it; the full text as the fuller version.
+                ...(r.replacement.short_disclosure_text ? [`Disclosure: ${r.replacement.short_disclosure_text}`, `Fuller version (also passes): ${r.replacement.disclosure_text}`] : [`Disclosure: ${r.replacement.disclosure_text}`]),
                 `Consent label: ${r.replacement.consent_label}`,
                 ...(r.replacement.placeholders?.length ? [`Fill these placeholders: ${r.replacement.placeholders.join(', ')}.`] : []),
                 'Place html directly above the purchase button; never pre-check the box. For consent records as evidence, pass site to get the Elements snippet instead.',
@@ -2176,7 +2233,7 @@ const callApi = {
     description: [
         'For a next_action whose operation has no dedicated tool (e.g. createStripeCheckoutConfig, updateTask, updateNoticeSettings, listConsents). Calls the Checkbox /v1 API with this server\'s connection; paths and bodies are in https://app.checkbox.site/v1/openapi.json.',
         'Examples: {"method":"GET","path":"/v1/account"} ; {"method":"POST","path":"/v1/sites/site_123/domain_verification/check"}.',
-        'Never send API keys or Stripe keys through it: keys are added by the human in the Checkbox dashboard, never pasted into the chat.',
+        'Never send API keys or Stripe keys through it, except a Stripe TEST restricted key via store_stripe_test_key (not call_api). Live keys are added by the human in the Checkbox dashboard, never pasted into the chat.',
         'GET is read-only. POST/DELETE change data: only do what the user or a next_action asked for. DELETE archives or removes objects — confirm with the user first.',
     ].join('\n'),
     input: {
@@ -2207,7 +2264,7 @@ const callApi = {
  * brand are read as merchant_name; any other unknown field is listed back as ignored.
  */
 export const SETUP_FIELD_ALIASES = Object.freeze({ brand: 'merchant_name', brand_name: 'merchant_name', business_name: 'merchant_name', company_name: 'merchant_name', platform: 'billing_platform' });
-const BILLING_PLATFORMS = new Set(['stripe', 'shopify', 'recharge', 'chargebee', 'recurly', 'paddle', 'woocommerce', 'custom']);
+const BILLING_PLATFORMS = new Set(['stripe', 'shopify', 'recharge', 'chargebee', 'recurly', 'paddle', 'lemon_squeezy', 'woocommerce', 'custom']);
 export function normalizeSetupArgs(raw, known) {
     const args = {};
     const aliased = [];
@@ -2276,6 +2333,7 @@ export const TOOLS = [
     answerTask,
     verifySite,
     getVerification,
+    storeStripeTestKey,
     startTestRun,
     getTestRun,
     checkDisclosure,
@@ -2317,6 +2375,7 @@ export const TOOL_OPERATIONS = {
     answer_task: ['answerTask'],
     verify_site: ['verifySite'],
     get_verification: ['retrieveVerification'],
+    store_stripe_test_key: ['createTestCredential'],
     start_test_run: ['createTestRun'],
     get_test_run: ['listTestRuns', 'retrieveTestRun'],
     check_disclosure: ['checkDisclosure'],

package/package.json

@@ -1,15 +1,23 @@
 {
   "name": "@checkbox-site/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Checkbox MCP server: subscription-law compliance tools for AI agents (remote at https://app.checkbox.site/mcp, or local stdio).",
   "keywords": [
     "subscription",
+    "subscription-compliance",
     "auto-renewal",
     "automatic-renewal",
     "compliance",
     "rosca",
     "click-to-cancel",
     "california-arl",
+    "auto-renewal-law",
+    "auto-renewal-compliance",
+    "subscription-cancellation",
+    "renewal-reminder",
+    "stripe-subscriptions",
+    "ftc",
+    "negative-option",
     "stripe",
     "stripe-checkout",
     "checkout",
@@ -64,7 +72,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@checkbox-site/node": "^0.2.0",
+    "@checkbox-site/node": "^0.2.1",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "zod": "^4.6.7"
   }