@checkbox-site/mcp 0.1.1 → 0.2.1

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 {
@@ -35,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',
@@ -34,6 +35,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',
@@ -74,6 +76,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
@@ -88,23 +95,125 @@ 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) {
+    // 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.
+        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}` : '.'}`;
+    // 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;
-    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}`);
@@ -144,6 +253,44 @@ function withItems(data, path, items) {
         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
@@ -169,6 +316,14 @@ export function fitJson(data, max = MAX_JSON_CHARS) {
             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).` };
@@ -182,16 +337,19 @@ 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 = [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);
-    if (next)
-        lines.push(next);
+            lines.push(`- ${mcpText(n)}`);
+    const next = describeNextAction(out.next === undefined ? nextActionOf(out.data) : out.next, { data: out.data });
+    // 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(out.data);
+        const fitted = fitJson(forMcp(out.data));
         if (fitted.page)
             lines.push(`- ${fitted.page}`);
         lines.push('', '```json', fitted.json, '```');
@@ -212,27 +370,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 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: 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/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;
+}