@checkbox-site/mcp 0.1.0 → 0.2.0

package/README.md

@@ -7,7 +7,7 @@ your agent can set up a project with one human click, check checkout code before
 done and run synthetic test subscriptions — against ROSCA, California's Automatic Renewal Law, New York GBL § 527-a
 and the other state automatic-renewal laws.
 
-Docs: https://checkbox.site/docs/mcp · Agent index: https://checkbox.site/llms.txt · Free to start.
+Docs: https://checkbox.site/docs/mcp · Agent index: https://checkbox.site/llms.txt · Free. Every feature. No credit card. Fair-use limits.
 
 ## Connect
 
@@ -45,7 +45,7 @@ Package: `@checkbox-site/mcp` on npm (Node 20+; binary `checkbox-mcp`). Options:
 
 ## Tools
 
-Start with `setup_checkbox`; then `get_compliance_plan` → apply a task → `verify_task`, until the plan is compliant.
+Start with `setup_checkbox`; then `get_compliance_plan` → apply a task → `verify_task`, until the checks pass (plan status `compliant`).
 Preflight tools (`check_disclosure`, `check_stripe_checkout_session`, `check_email`, `check_page_html`,
 `get_notice_schedule`) work on code before it is deployed. The full list, with the API operation behind each tool, is
 at https://checkbox.site/docs/mcp#tools.
@@ -56,7 +56,7 @@ the next tool to call.
 
 ## Not legal advice
 
-Checkbox output is an automated assessment against a legal catalog pending attorney review; it is not legal advice.
+Rules drafted from the statute text and updated as new statutes come into effect. Automated checks, not legal advice. Every rule cites its source, so you or your lawyer can check it.
 
 ## License
 

package/dist/api.d.ts

@@ -20,6 +20,8 @@ export interface NextAction {
     endpoint?: string | null;
     url?: string | null;
     task?: string | null;
+    /** The MCP tool the API maps operation_id to (`call_api` when there is none). */
+    mcp_tool?: string | null;
 }
 /** A non-2xx /v1 response (the error envelope) or a network failure (status 0). */
 export declare class CheckboxApiError extends Error {
@@ -39,6 +41,11 @@ export interface CheckboxApi {
     readonly hasKey: boolean;
     /** Base URL of the API (for links in tool output). */
     readonly apiBase: string;
+    /**
+     * Round 21 (pilot 20 item 5): the oldest MCP server version the API said it expects (response header
+     * checkbox-mcp-minimum-version), once a response carried it. Absent on in-process clients (same version as the API).
+     */
+    minimumMcpVersion?(): string | undefined;
 }
 /** Builds the query string for a request (`expand` arrays are not needed by the tools). */
 export declare function withQuery(path: string, query?: ApiRequestOptions['query']): string;

package/dist/api.js

@@ -6,6 +6,7 @@
 // - The local stdio server (`checkbox-mcp`) implements it over HTTPS (createHttpApi, or an @checkbox-site/node client
 //   through fromSdkClient).
 import { randomUUID } from 'node:crypto';
+import { MinimumVersionTracker } from "./version-check.js";
 /** API version the MCP tools are written against (sent as Checkbox-Version). */
 export const API_VERSION = '2026-10-30';
 export const DEFAULT_API_BASE = 'https://app.checkbox.site';
@@ -57,9 +58,11 @@ export function createHttpApi(opts) {
     const f = opts.fetch ?? fetch;
     const base = (opts.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, '');
     const maxRetries = opts.maxRetries ?? 2;
+    const versions = new MinimumVersionTracker();
     return {
         hasKey: Boolean(opts.apiKey),
         apiBase: base,
+        minimumMcpVersion: () => versions.minimum,
         async request(method, path, ro = {}) {
             const url = base + withQuery(path.startsWith('/') ? path : `/${path}`, ro.query);
             const headers = {
@@ -95,6 +98,7 @@ export function createHttpApi(opts) {
                     await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 10) * 1000 : 500 * 2 ** attempt);
                     continue;
                 }
+                versions.observe(res.headers);
                 const text = await res.text();
                 let json;
                 try {
@@ -122,13 +126,19 @@ export function fromSdkClient(client, info) {
             : null;
     if (!call)
         return null;
+    const versions = new MinimumVersionTracker();
     return {
         ...info,
+        minimumMcpVersion: () => versions.minimum,
         async request(method, path, ro = {}) {
             try {
-                return (await call(method, path, ro));
+                const out = await call(method, path, ro);
+                // The Node SDK puts the response headers on a non-enumerable `lastResponse`.
+                versions.observe(out?.lastResponse?.headers);
+                return out;
             }
             catch (err) {
+                versions.observe(err?.headers);
                 throw toCheckboxApiError(err);
             }
         },

package/dist/format.d.ts

@@ -10,8 +10,30 @@ export declare function mcpToolFor(operationId: string | null | undefined): stri
  * reads it as an instruction next to the "Next:" line. Full values stay in the fenced JSON.
  */
 export declare function untrusted(value: unknown, max?: number): string;
+/**
+ * Whether the `checkbox` CLI (@checkbox-site/cli) is on npm. While this is false, MCP output never shows `command`
+ * fields or a "CLI equivalent". It is published.
+ */
+export declare const CLI_PUBLISHED = true;
+/** Docs for `checkbox ci` / the GitHub Action (checkbox.json + .github/workflows/checkbox.yml). */
+export declare const CI_DOCS_URL = "https://checkbox.site/docs/guides/ci";
+/**
+ * After a check passes, one line offering to keep it passing in CI. The Action runs the published CLI, so this stays
+ * off until CLI_PUBLISHED is true (`published` is for tests).
+ */
+export declare function ciHint(passing: boolean, published?: boolean): string | null;
+/**
+ * Audit P2: text the API writes for SDK users names operations (verifyTask, updateSite, …) and REST paths. Over MCP
+ * those become the tool to call: a dedicated tool name, else `call_api` with the endpoint. CLI hints are dropped while
+ * the CLI is unpublished.
+ */
+export declare function mcpText(text: string): string;
+/** Rewrites agent-facing strings in an API object for MCP (mcpText), and drops `command` while the CLI is unpublished. */
+export declare function forMcp(value: unknown, depth?: number): unknown;
 /** One line telling the model what to call next, in MCP terms. */
-export declare function describeNextAction(next: NextAction | null | undefined): string | null;
+export declare function describeNextAction(next: NextAction | null | undefined, ctx?: {
+    data?: unknown;
+}): string | null;
 /** Pulls the top-level next_action off an API object. */
 export declare function nextActionOf(obj: unknown): NextAction | null;
 export interface ToolOutput {
@@ -26,6 +48,15 @@ export interface ToolOutput {
     /** Mark the result as an error the model should act on (still a normal result). */
     isError?: boolean;
 }
+/**
+ * Round-3 pilot (nextjs, sveltekit): output was cut at 60 KB in the middle of the JSON, which agents then failed to
+ * parse. Output is always valid JSON: an oversized list is paged (the first items that fit, plus `_page` naming the
+ * ids of the rest to fetch one by one), never cut mid-value.
+ */
+export declare function fitJson(data: unknown, max?: number): {
+    json: string;
+    page?: string;
+};
 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

@@ -23,6 +23,8 @@ export const OPERATION_TOOLS = {
     checkEmail: 'check_email',
     checkPage: 'check_page_html',
     checkNoticeSchedule: 'get_notice_schedule',
+    listSiteSuggestions: 'suggest_improvements',
+    suggestImprovements: 'suggest_improvements',
     listSites: 'list_sites',
     createSite: 'create_site',
     updateSite: 'update_site',
@@ -32,6 +34,7 @@ export const OPERATION_TOOLS = {
     listFindings: 'list_findings',
     retrieveFinding: 'get_finding',
     retrieveFindingFix: 'get_finding',
+    publishShopifyTerms: 'publish_shopify_terms',
     createScan: 'run_scan',
     retrieveScan: 'get_scan',
     listLawUpdates: 'list_law_updates',
@@ -72,6 +75,11 @@ const OPERATION_ENDPOINTS = {
     listSiteFixes: 'GET /v1/sites/{site}/fixes',
     listVerifications: 'GET /v1/sites/{site}/verifications',
     cancelTestRun: 'POST /v1/test_runs/{test_run}/cancel',
+    createReceiptToken: 'POST /v1/receipt_tokens',
+    createReceipt: 'POST /v1/receipts',
+    retrieveReceiptSettings: 'GET /v1/receipt_settings',
+    updateReceiptSettings: 'POST /v1/receipt_settings',
+    retrieveDueNotice: 'GET /v1/notices/{notice}',
 };
 /**
  * Quotes text Checkbox did not write (page HTML, email bodies, policy text, merchant-supplied strings) for the text part
@@ -86,23 +94,119 @@ export function untrusted(value, max = 80) {
     s = s.replace(/</g, '‹').replace(/>/g, '›');
     return `<untrusted_text>${JSON.stringify(s)}</untrusted_text>`;
 }
+/**
+ * Whether the `checkbox` CLI (@checkbox-site/cli) is on npm. While this is false, MCP output never shows `command`
+ * fields or a "CLI equivalent". It is published.
+ */
+export const CLI_PUBLISHED = true;
+/** Docs for `checkbox ci` / the GitHub Action (checkbox.json + .github/workflows/checkbox.yml). */
+export const CI_DOCS_URL = 'https://checkbox.site/docs/guides/ci';
+/**
+ * After a check passes, one line offering to keep it passing in CI. The Action runs the published CLI, so this stays
+ * off until CLI_PUBLISHED is true (`published` is for tests).
+ */
+export function ciHint(passing, published = CLI_PUBLISHED) {
+    if (!published || !passing)
+        return null;
+    return `Optional, ask the human once: keep these checks passing on every pull request. With a yes, write checkbox.json listing the files you just checked (Stripe params via "source" or "module", disclosure / email template files, the plans) and .github/workflows/checkbox.yml (uses: checkbox-site/checkbox@v1; offline, no key), then run \`npx @checkbox-site/cli ci\` to confirm. \`npx @checkbox-site/cli ci init --yes\` drafts both. ${CI_DOCS_URL}`;
+}
+/** REST paths of the preflight checks → their MCP tools (for text written for API users). */
+const CHECK_PATH_TOOLS = {
+    disclosure: 'check_disclosure',
+    stripe_checkout_session: 'check_stripe_checkout_session',
+    stripe_payment_link: 'call_api (POST /v1/checks/stripe_payment_link)',
+    email: 'check_email',
+    page: 'check_page_html',
+    notice_schedule: 'get_notice_schedule',
+};
+/** CLI commands → the MCP tool that does the same (for text that still names a command). */
+const CLI_TOOLS = { plan: 'get_compliance_plan', fix: 'get_task', answer: 'answer_task', verify: 'verify_site', init: 'get_setup_status', check: 'check_disclosure' };
+const OP_RE = new RegExp(`\\b(${[...Object.keys(OPERATION_TOOLS), ...Object.keys(OPERATION_ENDPOINTS)].sort((a, b) => b.length - a.length).join('|')})\\b`, 'g');
+/**
+ * Audit P2: text the API writes for SDK users names operations (verifyTask, updateSite, …) and REST paths. Over MCP
+ * those become the tool to call: a dedicated tool name, else `call_api` with the endpoint. CLI hints are dropped while
+ * 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]);
+    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.
+        if (op === 'verifySetupSession')
+            return 'get_setup_status (verify=true)';
+        const tool = OPERATION_TOOLS[op];
+        if (tool)
+            return tool;
+        const endpoint = OPERATION_ENDPOINTS[op];
+        return endpoint ? `call_api (${endpoint})` : op;
+    });
+    // Agent audit round 2: "call_api (POST /v1/sites/{site}/notice_settings) (POST /v1/sites/site_…/notice_settings)":
+    // an operation followed by its own concrete endpoint is said once, with the concrete path.
+    s = s.replace(/call_api \(((?:GET|POST|DELETE) )[^()]*\) \(\1([^()]+)\)/g, (_m, verb, path) => `call_api (${verb}${path})`);
+    if (!CLI_PUBLISHED) {
+        s = s
+            .replace(/\s*\((?:or )?(?:run )?`(?:npx [^`]*)?checkbox [^`]*`[^)]*\)/g, '')
+            .replace(/,? or (?:run )?`checkbox [^`]*`/g, '')
+            .replace(/ \(`checkbox [^`]*` (?:writes|does) [^)]*\)/g, '')
+            .replace(/(?:run )?`checkbox ([a-z-]+)[^`]*`/g, (_m, cmd) => `\`${CLI_TOOLS[cmd] ?? 'get_compliance_plan'}\``);
+    }
+    return s;
+}
+const TEXT_KEYS = new Set(['message', 'description', 'summary', 'fix', 'note', 'how', 'detail', 'headline']);
+/** Round 21 (pilot 20 item 16): lists of agent-facing sentences the API writes with operation names (REST words). */
+const TEXT_LIST_KEYS = new Set(['plan_terms_conflicts', 'notes', 'steps']);
+/** Rewrites agent-facing strings in an API object for MCP (mcpText), and drops `command` while the CLI is unpublished. */
+export function forMcp(value, depth = 0) {
+    if (depth > 12 || value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => forMcp(v, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (k === 'command' && !CLI_PUBLISHED && (v === null || typeof v === 'string'))
+            continue;
+        out[k] =
+            typeof v === 'string' && TEXT_KEYS.has(k)
+                ? mcpText(v)
+                : Array.isArray(v) && TEXT_LIST_KEYS.has(k)
+                    ? v.map((x) => (typeof x === 'string' ? mcpText(x) : forMcp(x, depth + 1)))
+                    : forMcp(v, depth + 1);
+    }
+    return out;
+}
+/** The argument hint for the tool a next step names (the right id for that tool). */
+function argHint(tool, next, ctx) {
+    const d = (ctx.data ?? {});
+    if (tool === 'get_verification')
+        return d.object === 'verification' && typeof d.id === 'string' ? ` (verification: ${d.id})` : '';
+    if (tool === 'get_setup_status' && next.operation_id === 'verifySetupSession')
+        return ' (verify: true)';
+    const task = next.task ?? /\/v1\/tasks\/(task_[A-Za-z0-9]+)/.exec(next.endpoint ?? '')?.[1];
+    return task && ['get_task', 'verify_task', 'answer_task'].includes(tool) ? ` (task: ${task})` : '';
+}
 /** One line telling the model what to call next, in MCP terms. */
-export function describeNextAction(next) {
+export function describeNextAction(next, ctx = {}) {
     if (!next || typeof next !== 'object' || !next.type)
         return null;
-    const text = (next.message ?? next.description ?? '').trim();
+    const text = mcpText((next.message ?? next.description ?? '').trim());
     if (next.type === 'done' || next.type === 'none')
         return `Next: nothing left to do${text ? ` — ${text}` : '.'}`;
     const op = next.operation_id ?? undefined;
-    const tool = op ? OPERATION_TOOLS[op] : 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;
+    const tool = named ?? (op ? OPERATION_TOOLS[op] : undefined);
     const parts = [`Next (${next.type}): ${text || 'see next_action.'}`];
     if (tool)
-        parts.push(`→ MCP tool \`${tool}\`${next.task ? ` (task: ${next.task})` : ''}.`);
+        parts.push(`→ MCP tool \`${tool}\`${argHint(tool, next, ctx)}.`);
     else if (op) {
-        const endpoint = next.endpoint ?? OPERATION_ENDPOINTS[op];
-        parts.push(endpoint ? `→ MCP tool \`call_api\` with ${endpoint} (operation ${op}).` : `→ operation ${op} (use \`call_api\`; paths in /v1/openapi.json).`);
+        let endpoint = next.endpoint ?? OPERATION_ENDPOINTS[op];
+        const site = ctx.data ?? {};
+        const siteId = typeof site.site === 'string' && site.site.startsWith('site_') ? site.site : typeof site.id === 'string' && site.id.startsWith('site_') ? site.id : undefined;
+        if (endpoint && siteId)
+            endpoint = endpoint.replace('{site}', siteId);
+        parts.push(endpoint ? `→ MCP tool \`call_api\` with ${endpoint}.` : `→ MCP tool \`call_api\` (operation ${op}; paths in /v1/openapi.json).`);
     }
-    if (next.command)
+    if (next.command && CLI_PUBLISHED)
         parts.push(`CLI equivalent: \`${next.command}\`.`);
     if (next.url && !tool)
         parts.push(`Docs: ${next.url}`);
@@ -114,20 +218,131 @@ export function nextActionOf(obj) {
     return n && typeof n === 'object' ? n : null;
 }
 const MAX_JSON_CHARS = 60_000;
+/** The largest array in `data` (top level, or one level down), with its path. */
+function largestArray(data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    let best = null;
+    const consider = (path, v) => {
+        if (!Array.isArray(v) || v.length < 2)
+            return;
+        const size = JSON.stringify(v).length;
+        if (!best || size > best.size)
+            best = { path, items: v, size };
+    };
+    for (const [k, v] of Object.entries(data)) {
+        consider([k], v);
+        if (v && typeof v === 'object' && !Array.isArray(v))
+            for (const [k2, v2] of Object.entries(v))
+                consider([k, k2], v2);
+    }
+    return best;
+}
+function withItems(data, path, items) {
+    const root = { ...data };
+    if (path.length === 1)
+        root[path[0]] = items;
+    else
+        root[path[0]] = { ...root[path[0]], [path[1]]: items };
+    return root;
+}
+/** A list this short is never paged down to fewer items: its items' nested lists are shortened instead. */
+const SMALL_LIST = 5;
+/**
+ * Every item of `arr` kept; in each item, its largest nested list (top level or one level down) is cut to the first `k`
+ * entries, with `_truncated` saying how many it had. `k` is the largest that fits. Null when even k = 0 does not fit.
+ */
+function fitNestedLists(data, arr, max) {
+    const nested = arr.items.map((item) => (item && typeof item === 'object' && !Array.isArray(item) ? largestArray(item) : null));
+    const longest = Math.max(0, ...nested.map((n) => n?.items.length ?? 0));
+    if (!longest)
+        return null;
+    const render = (k) => {
+        const items = arr.items.map((item, i) => {
+            const n = nested[i];
+            if (!n || n.items.length <= k)
+                return item;
+            const cut = withItems(item, n.path, n.items.slice(0, k));
+            return { ...cut, _truncated: { list: n.path.join('.'), returned: k, total: n.items.length } };
+        });
+        return JSON.stringify(withItems(data, arr.path, items), null, 2);
+    };
+    if (render(0).length > max)
+        return null;
+    let lo = 0;
+    let hi = longest;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (render(mid).length <= max)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    const lists = [...new Set(nested.filter((n) => !!n && n.items.length > lo).map((n) => n.path.join('.')))];
+    return {
+        json: render(lo),
+        page: `Output shortened: all ${arr.items.length} items of "${arr.path.join('.')}" shown, each with at most ${lo} entries of its "${lists.join('", "')}" list (see _truncated in each item). The JSON is complete and valid; retrieve one item by id to see more of it, or narrow the request.`,
+    };
+}
+/**
+ * Round-3 pilot (nextjs, sveltekit): output was cut at 60 KB in the middle of the JSON, which agents then failed to
+ * parse. Output is always valid JSON: an oversized list is paged (the first items that fit, plus `_page` naming the
+ * ids of the rest to fetch one by one), never cut mid-value.
+ */
+export function fitJson(data, max = MAX_JSON_CHARS) {
+    const pretty = JSON.stringify(data, null, 2);
+    if (pretty.length <= max)
+        return { json: pretty };
+    const arr = largestArray(data);
+    if (arr) {
+        let lo = 0;
+        let hi = arr.items.length;
+        const render = (n) => {
+            const rest = arr.items.slice(n);
+            const ids = rest.map((x) => (x && typeof x === 'object' ? x.id : undefined)).filter((x) => typeof x === 'string');
+            return JSON.stringify(withItems({ ...data, _page: { list: arr.path.join('.'), returned: n, total: arr.items.length, remaining_ids: ids.slice(0, 200) } }, arr.path, arr.items.slice(0, n)), null, 2);
+        };
+        while (lo < hi) {
+            const mid = Math.ceil((lo + hi) / 2);
+            if (render(mid).length <= max)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        // MCP connector test: list_law_updates (limit 3) printed "0 of 2 items shown": each law update carried hundreds of
+        // changed requirements, so not even one item fitted. When paging would drop items of a short list (or all of them),
+        // every item is shown instead, with its own longest nested list cut to what fits.
+        if (lo < arr.items.length && (lo === 0 || arr.items.length <= SMALL_LIST)) {
+            const inner = fitNestedLists(data, arr, max);
+            if (inner)
+                return inner;
+        }
+        const json = render(lo);
+        if (json.length <= max) {
+            return { json, page: `Output paged: ${lo} of ${arr.items.length} items of "${arr.path.join('.')}" shown. The JSON is complete and valid; fetch the others by id (_page.remaining_ids), e.g. get_task for plan tasks, or narrow the request (a smaller limit).` };
+        }
+    }
+    const compact = JSON.stringify(data);
+    if (compact.length <= max)
+        return { json: compact, page: 'Output printed compactly (no indentation) to fit.' };
+    return {
+        json: JSON.stringify({ _truncated: true, size: compact.length, keys: data && typeof data === 'object' ? Object.keys(data) : [] }, null, 2),
+        page: `Output too large (${compact.length} characters): narrow the request (a smaller limit, or one item at a time).`,
+    };
+}
 export function renderOutput(out) {
-    const lines = [out.headline.trim()];
+    const lines = [mcpText(out.headline.trim())];
     for (const n of out.notes ?? [])
         if (n)
-            lines.push(`- ${n}`);
-    const next = describeNextAction(out.next === undefined ? nextActionOf(out.data) : out.next);
+            lines.push(`- ${mcpText(n)}`);
+    const next = describeNextAction(out.next === undefined ? nextActionOf(out.data) : out.next, { data: out.data });
     if (next)
         lines.push(next);
     if (out.data !== undefined) {
-        let json = JSON.stringify(out.data, null, 2);
-        if (json.length > MAX_JSON_CHARS) {
-            json = `${json.slice(0, MAX_JSON_CHARS)}\n… (truncated ${json.length - MAX_JSON_CHARS} characters; narrow the request, e.g. a smaller limit or one task at a time)`;
-        }
-        lines.push('', '```json', json, '```');
+        const fitted = fitJson(forMcp(out.data));
+        if (fitted.page)
+            lines.push(`- ${fitted.page}`);
+        lines.push('', '```json', fitted.json, '```');
     }
     return { content: [{ type: 'text', text: lines.join('\n') }], ...(out.isError ? { isError: true } : {}) };
 }
@@ -145,27 +360,53 @@ export function renderError(err) {
             data.doc_url = err.docUrl;
         if (err.nextAction)
             data.next_action = err.nextAction;
-        const hint = ERROR_HINTS[err.code];
+        const hint = err.code === 'resource_missing' ? missingHint(err.message) : ERROR_HINTS[err.code];
         return renderOutput({
             headline: `Checkbox API error ${err.code}${err.param ? ` (param: ${err.param})` : ''}: ${err.message}`,
             notes: hint ? [hint] : [],
             data: { error: data },
-            next: err.nextAction ?? null,
+            next: err.nextAction ?? (err.code === 'resource_missing' ? missingNext(err.message) : null),
             isError: true,
         });
     }
     const message = err instanceof Error ? err.message : String(err);
     return renderOutput({ headline: `Tool failed: ${message}`, isError: true });
 }
+/** Audit P2: where to find a valid id of the kind that was missing (by its prefix in the message). */
+function missingKind(message) {
+    if (/\btask_/.test(message))
+        return 'task';
+    if (/\bver(?:ification)?_/.test(message))
+        return 'verification';
+    if (/\bfinding_/.test(message))
+        return 'finding';
+    if (/\bsite_/.test(message))
+        return 'site';
+    return 'other';
+}
+function missingHint(message) {
+    const where = { task: 'get_compliance_plan lists the current task ids', verification: 'get_task shows a task\'s last_verification id', finding: 'list_findings lists finding ids', site: 'list_sites lists site ids', other: 'get_compliance_plan and list_sites list the current ids' }[missingKind(message)];
+    return `The id does not exist in this mode (test keys only see test-mode objects): ${where}.`;
+}
+function missingNext(message) {
+    const k = missingKind(message);
+    if (k === 'site')
+        return { type: 'find_id', message: 'Call list_sites for the site ids in this mode.', operation_id: 'listSites' };
+    if (k === 'finding')
+        return { type: 'find_id', message: 'Call list_findings for the finding ids.', operation_id: 'listFindings' };
+    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: 'The API key this MCP server uses is a restricted key without that permission. Ask the human for a key with the permission (Dashboard → Developers → API keys) or use a read-only tool.',
+    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_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: call setup_checkbox to get a new one, or ask the human for a valid key.',
+    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.',
     account_not_activated: 'Live mode is locked until a site domain is verified. Use a test key (ck_test_…) for setup and checks, or verify the domain first.',
     parameter_invalid: 'Fix the named parameter and call the tool again.',
     parameter_missing: 'Add the named parameter and call the tool again.',
     parameter_unknown: 'Remove the named parameter and call the tool again.',
-    resource_missing: 'The id does not exist in this mode (test keys only see test-mode objects). Use list_sites / list_findings to find valid ids.',
     rate_limit_exceeded: 'Wait the number of seconds in the message, then retry.',
+    shopify_not_connected: 'Only the merchant can connect the store: tell them the step in next_action (install the Checkbox app in the Shopify admin, then "Connect to Checkbox"). Do not retry until they say it is done.',
+    terms_incomplete: 'Checkbox never guesses prices or cancellation terms: send the missing plan facts (next_action), then call the tool again.',
+    platform_error: 'The merchant\'s platform refused the change; nothing was applied. Retry in a few minutes.',
 };

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { NO_KEY, keyAllows, keyContextFromPrefix, type KeyContext, type KeyRole,
 export { CATALOG_URI, QUICKSTART_URI, makeMyCheckoutCompliantPrompt, quickstartMarkdown, renderCatalog, type CoverageDoc } from './resources.ts';
 export { DEFAULT_MCP_URL, SERVER_INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, createCheckboxMcpServer, type CheckboxMcp, type CheckboxMcpOptions } from './server.ts';
 export { TOOLS, TOOL_OPERATIONS, ToolError, toolVisible, type IssuedKeys, type ToolContext, type ToolDef } from './tools.ts';
+export { closestArgument, unknownArgumentsMessage } from './unknown-args.ts';
 export { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

package/dist/index.js

@@ -6,5 +6,6 @@ export { NO_KEY, keyAllows, keyContextFromPrefix } from "./permissions.js";
 export { CATALOG_URI, QUICKSTART_URI, makeMyCheckoutCompliantPrompt, quickstartMarkdown, renderCatalog } from "./resources.js";
 export { DEFAULT_MCP_URL, SERVER_INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, createCheckboxMcpServer } from "./server.js";
 export { TOOLS, TOOL_OPERATIONS, ToolError, toolVisible } from "./tools.js";
+export { closestArgument, unknownArgumentsMessage } from "./unknown-args.js";
 // Re-exported so hosts use the same SDK copy as the server.
 export { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

package/dist/permissions.js

@@ -23,8 +23,8 @@ export function keyAllows(key, scope) {
 export function keyContextFromPrefix(apiKey, readOnly = false) {
     if (!apiKey)
         return { ...NO_KEY, readOnly };
-    const mode = /^(ck|rk)_test_/.test(apiKey) ? 'test' : /^(ck|rk|sk)_live_/.test(apiKey) ? 'live' : 'unknown';
-    const kind = apiKey.startsWith('rk_') ? 'restricted' : 'secret';
+    const mode = /^(ckr|ck|rk)_test_/.test(apiKey) ? 'test' : /^(ckr|ck|rk|sk)_live_/.test(apiKey) ? 'live' : 'unknown';
+    const kind = (apiKey.startsWith('rk_') || apiKey.startsWith('ckr_')) ? 'restricted' : 'secret';
     // Restricted keys with unknown scopes: list everything and let the API answer insufficient_scope.
     return { authenticated: true, mode, kind: kind === 'restricted' ? undefined : kind, readOnly };
 }

package/dist/resources.js

@@ -38,9 +38,10 @@ export async function loadCatalog(api) {
 export function quickstartMarkdown(opts) {
     return `# Checkbox for AI agents — quickstart
 
-Checkbox makes a subscription business compliant with automatic-renewal laws (FTC ROSCA, California ARL, New York and
-~26 other states) and keeps it compliant: it watches the checkout, the acknowledgment / reminder emails and the
-cancellation flow, stores signed evidence, and tells you — the agent — exactly what to change. Free to start, no card.
+Checkbox checks a subscription business against automatic-renewal laws (federal law, 27 states, DC and New York City:
+FTC ROSCA, California ARL, New York and the other state laws) and keeps checking it: it watches the checkout, the
+acknowledgment / reminder emails and the cancellation flow, stores signed evidence, and tells you — the agent — exactly
+what to change. Free. Every feature. No credit card. Fair-use limits.
 
 ## The loop (agent-to-agent)
 
@@ -49,7 +50,7 @@ cancellation flow, stores signed evidence, and tells you — the agent — exact
    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:
    site_url, checkout_url, terms_url / refund_url / cancellation_url, billing_platform, plans, project.layout_file.
-   (The \`checkbox init\` CLI does the same and patches the layout file; it is pre-release and not on npm yet.)
+   (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,
    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
@@ -59,7 +60,7 @@ cancellation flow, stores signed evidence, and tells you — the agent — exact
 5. Tasks with status **manual** hold a question for the HUMAN: ask them, then **answer_task**. Never answer for them.
 6. **start_test_run** — a synthetic subscription in Stripe test mode (card 4242, Checkbox inbox, test clock through
    trial end and renewal, online cancellation) observes every lifecycle check; **get_test_run** for results.
-7. Repeat 3-4 until the plan status is **compliant**, then **complete_setup** (emails the human a summary).
+7. Repeat 3-4 until the checks pass (plan status value \`compliant\`, label "Checks pass"), then **complete_setup** (emails the human a summary).
 
 Every tool result ends with "Next: …" naming the tool to call. Errors carry a stable \`code\` and often a next_action.
 
@@ -67,10 +68,10 @@ Every tool result ends with "Next: …" naming the tool to call. Errors carry a
 
 - **check_disclosure** — disclosure text next to the pay button → verdicts + engine-verified replacement.
 - **check_stripe_checkout_session** — the params you pass to stripe.checkout.sessions.create → corrected_params.
-- **check_email** — a lifecycle email → verdicts + compliant template.
+- **check_email** — a lifecycle email → verdicts + a template that passes the checks.
 - **check_page_html** — the rendered checkout page HTML → verdicts.
 - **get_notice_schedule** — when each required notice must be sent for a plan.
-- **get_compliant_disclosure** / **get_elements_snippet** — locked compliant wording, or the drop-in
+- **get_compliant_disclosure** / **get_elements_snippet** — locked wording that passes the checks, or the drop-in
   \`<checkbox-disclosure>\` element that also records consent as evidence.
 
 ## Keys and modes
@@ -98,15 +99,15 @@ Automated compliance checks, not legal advice.
 /** The make_my_checkout_compliant prompt: inspect the code → preflight → patch → verify. */
 export function makeMyCheckoutCompliantPrompt(args) {
     const target = args.site_url ? ` for ${args.site_url}` : '';
-    return `Make this project's subscription checkout compliant with automatic-renewal laws${target}, using the Checkbox MCP tools. Work autonomously; only stop to ask me (the human) when a tool says a human must decide or approve.
+    return `Make this project's subscription checkout pass the automatic-renewal checks${target}, using the Checkbox MCP tools. Work autonomously; only stop to ask me (the human) when a tool says a human must decide or approve.
 
 1. Inspect the code first. Find: the framework${args.framework ? ` (expected: ${args.framework})` : ''}, the root layout file, where the subscribe / pay button is rendered, where subscriptions are created (stripe.checkout.sessions.create, payment links, or ${args.billing_platform ?? 'the billing platform'} calls), the plans and prices (amount, interval, trial), the Terms / refund / cancellation policy pages, and which emails are sent to subscribers (acknowledgment, trial / renewal reminders, cancellation confirmation).
 2. Preflight before changing anything:
    - check_stripe_checkout_session with the exact params the code passes to Stripe (plus merchant terms when it uses a Price id);
    - check_disclosure with the text next to the pay button (or check_page_html with the rendered checkout HTML);
    - check_email for each subscriber email template, and get_notice_schedule for when reminders must go out.
-3. Patch the code with the returned fixes: corrected_params for Stripe, the replacement disclosure + an unchecked, required consent checkbox directly above the pay button (or get_elements_snippet for the drop-in Checkbox Elements component), compliant email templates and send timing, and an online cancellation path. Keep the existing code style; do not invent prices or terms — use the real ones from the code.
+3. Patch the code with the returned fixes: corrected_params for Stripe, the replacement disclosure + an unchecked, required consent checkbox directly above the pay button (or get_elements_snippet for the drop-in Checkbox Elements component), email templates that pass the checks and send timing, and an online cancellation path. Keep the existing code style; do not invent prices or terms — use the real ones from the code.
 4. Re-run the same checks on the patched code until they pass (styling items may stay needs_review until a rendered scan).
-5. If Checkbox is not set up for this project yet, call setup_checkbox (one approval link for me), then get_compliance_plan and work the tasks: apply → verify_task → next, until the plan is compliant. Ask me any "manual" task questions verbatim; never answer them yourself.
+5. If Checkbox is not set up for this project yet, call setup_checkbox (one approval link for me), then get_compliance_plan and work the tasks: apply → verify_task → next, until the checks pass (plan status compliant). Ask me any "manual" task questions verbatim; never answer them yourself.
 6. Finish with a short summary: what changed (files), which laws/citations each change satisfies, and anything still open.`;
 }