@checkbox-site/mcp 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# Checkbox MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- mcp-name: site.checkbox/checkbox -->
+
+Subscription-law compliance for AI coding agents. Connect Claude, Cursor, VS Code or any MCP client to Checkbox and
+your agent can set up a project with one human click, check checkout code before it ships, work the compliance plan to
+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.
+
+## Connect
+
+**Remote (recommended)** — Streamable HTTP at `https://app.checkbox.site/mcp`, nothing to install, no API key to copy:
+the server implements MCP OAuth, so your client opens a Checkbox sign-in and you click **Approve** once.
+
+- claude.ai / Claude Desktop: Settings → Connectors → **Add custom connector** → `https://app.checkbox.site/mcp` →
+  Connect → Approve.
+- Claude Code: `claude mcp add --transport http checkbox https://app.checkbox.site/mcp`, then `/mcp` → Authenticate.
+- Cursor (`.cursor/mcp.json`): `{ "mcpServers": { "checkbox": { "url": "https://app.checkbox.site/mcp" } } }`, then
+  Connect.
+
+API keys still work everywhere (CI, headless agents): add `--header "Authorization: Bearer $CHECKBOX_SECRET_KEY"`
+(Claude Code) or `"headers": { "Authorization": "Bearer ${env:CHECKBOX_SECRET_KEY}" }` (Cursor). Agents without a
+browser: `https://app.checkbox.site/mcp?login=device` offers `setup_checkbox`, which returns an approval link and then
+test-mode keys.
+
+**Local (stdio)** — for clients without remote MCP support:
+
+```json
+{
+  "mcpServers": {
+    "checkbox": {
+      "command": "npx",
+      "args": ["-y", "@checkbox-site/mcp"],
+      "env": { "CHECKBOX_API_KEY": "ck_test_..." }
+    }
+  }
+}
+```
+
+Package: `@checkbox-site/mcp` on npm (Node 20+; binary `checkbox-mcp`). Options:
+`--read-only`, `--api-key`, `--api-base`; environment `CHECKBOX_API_KEY` (falls back to `CHECKBOX_SECRET_KEY`),
+`CHECKBOX_API_BASE`, `CHECKBOX_MCP_READ_ONLY=true`.
+
+## Tools
+
+Start with `setup_checkbox`; then `get_compliance_plan` → apply a task → `verify_task`, until the plan is 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.
+
+Every tool is a thin call to the public API (`https://app.checkbox.site/v1`), so keys, scopes, test/live mode and rate
+limits are the API's. Write tools say so and carry `readOnlyHint: false`. Results are written for models and end with
+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.
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,66 @@
+/** API version the MCP tools are written against (sent as Checkbox-Version). */
+export declare const API_VERSION = "2026-10-30";
+export declare const DEFAULT_API_BASE = "https://app.checkbox.site";
+export type HttpMethod = 'GET' | 'POST' | 'DELETE';
+export interface ApiRequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** POST only; a fresh key is generated when omitted, so a transport retry never applies a call twice. */
+    idempotencyKey?: string;
+    /** Send without the API key (public routes: device login). */
+    anonymous?: boolean;
+}
+/** `next_action` as the API returns it (errors, setup sessions, plans, tasks, checks). */
+export interface NextAction {
+    type: string;
+    message?: string;
+    description?: string;
+    operation_id?: string | null;
+    command?: string | null;
+    endpoint?: string | null;
+    url?: string | null;
+    task?: string | null;
+}
+/** A non-2xx /v1 response (the error envelope) or a network failure (status 0). */
+export declare class CheckboxApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code: string;
+    readonly param?: string | undefined;
+    readonly requestId?: string | undefined;
+    readonly nextAction?: NextAction | undefined;
+    readonly docUrl?: string | undefined;
+    constructor(message: string, status: number, type: string, code: string, param?: string | undefined, requestId?: string | undefined, nextAction?: NextAction | undefined, docUrl?: string | undefined);
+}
+export interface CheckboxApi {
+    /** Calls `method path` (path starts with /v1/). Resolves with the parsed JSON body; rejects with CheckboxApiError. */
+    request<T = unknown>(method: HttpMethod, path: string, opts?: ApiRequestOptions): Promise<T>;
+    /** Whether an API key is configured (false: only the device-login setup tools work). */
+    readonly hasKey: boolean;
+    /** Base URL of the API (for links in tool output). */
+    readonly apiBase: string;
+}
+/** 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;
+/** Turns a /v1 response (status + parsed body) into a value or a CheckboxApiError. */
+export declare function interpretResponse<T>(status: number, json: unknown, requestId?: string, rawText?: string): T;
+export interface HttpApiOptions {
+    apiKey?: string;
+    apiBase?: string;
+    userAgent?: string;
+    fetch?: typeof fetch;
+    /** Retries on network errors, 429 and 5xx (default 2). POSTs are safe to retry: they carry an Idempotency-Key. */
+    maxRetries?: number;
+    timeoutMs?: number;
+}
+/** /v1 over HTTPS with fetch. Used by the stdio server when no SDK client is supplied. */
+export declare function createHttpApi(opts: HttpApiOptions): CheckboxApi;
+/**
+ * Adapts a Node SDK client (@checkbox-site/node) to CheckboxApi. Any client with a Stripe-style
+ * `rawRequest(method, path, params?, options?)` or a `request(method, path, { query, body, idempotencyKey })` works;
+ * errors with `status`/`code`/`type` fields are mapped to CheckboxApiError.
+ */
+export declare function fromSdkClient(client: unknown, info: {
+    hasKey: boolean;
+    apiBase: string;
+}): CheckboxApi | null;

package/dist/api.js

@@ -0,0 +1,146 @@
+// The one thing the MCP tools need from the outside world: a way to call the Checkbox /v1 API.
+//
+// - The remote server (apps/api, https://app.checkbox.site/mcp) implements it in-process with Fastify's inject, so a
+//   tool call goes through exactly the same /v1 auth, scopes, test/live mode, idempotency and rate limits as an HTTP
+//   call with the same key.
+// - The local stdio server (`checkbox-mcp`) implements it over HTTPS (createHttpApi, or an @checkbox-site/node client
+//   through fromSdkClient).
+import { randomUUID } from 'node:crypto';
+/** 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';
+/** A non-2xx /v1 response (the error envelope) or a network failure (status 0). */
+export class CheckboxApiError extends Error {
+    status;
+    type;
+    code;
+    param;
+    requestId;
+    nextAction;
+    docUrl;
+    constructor(message, status, type, code, param, requestId, nextAction, docUrl) {
+        super(message);
+        this.status = status;
+        this.type = type;
+        this.code = code;
+        this.param = param;
+        this.requestId = requestId;
+        this.nextAction = nextAction;
+        this.docUrl = docUrl;
+        this.name = 'CheckboxApiError';
+    }
+}
+/** Builds the query string for a request (`expand` arrays are not needed by the tools). */
+export function withQuery(path, query) {
+    const entries = Object.entries(query ?? {}).filter(([, v]) => v !== undefined && v !== '');
+    if (!entries.length)
+        return path;
+    const qs = new URLSearchParams(entries.map(([k, v]) => [k, String(v)]));
+    return `${path}${path.includes('?') ? '&' : '?'}${qs.toString()}`;
+}
+/** Turns a /v1 response (status + parsed body) into a value or a CheckboxApiError. */
+export function interpretResponse(status, json, requestId, rawText) {
+    if (status >= 200 && status < 300)
+        return json;
+    const e = json?.error;
+    if (e && typeof e === 'object') {
+        return throwError(new CheckboxApiError(typeof e.message === 'string' ? e.message : `HTTP ${status}`, status, typeof e.type === 'string' ? e.type : 'api_error', typeof e.code === 'string' ? e.code : 'unknown_error', typeof e.param === 'string' ? e.param : undefined, typeof e.request_id === 'string' ? e.request_id : requestId, e.next_action && typeof e.next_action === 'object' ? e.next_action : undefined, typeof e.doc_url === 'string' ? e.doc_url : undefined));
+    }
+    return throwError(new CheckboxApiError(`HTTP ${status}: ${(rawText ?? '').slice(0, 200) || 'empty response'}`, status, 'api_error', 'unexpected_response', undefined, requestId));
+}
+function throwError(err) {
+    throw err;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** /v1 over HTTPS with fetch. Used by the stdio server when no SDK client is supplied. */
+export function createHttpApi(opts) {
+    const f = opts.fetch ?? fetch;
+    const base = (opts.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, '');
+    const maxRetries = opts.maxRetries ?? 2;
+    return {
+        hasKey: Boolean(opts.apiKey),
+        apiBase: base,
+        async request(method, path, ro = {}) {
+            const url = base + withQuery(path.startsWith('/') ? path : `/${path}`, ro.query);
+            const headers = {
+                accept: 'application/json',
+                'checkbox-version': API_VERSION,
+                'user-agent': opts.userAgent ?? 'checkbox-mcp',
+            };
+            if (opts.apiKey && !ro.anonymous)
+                headers.authorization = `Bearer ${opts.apiKey}`;
+            if (ro.body !== undefined)
+                headers['content-type'] = 'application/json';
+            if (method === 'POST')
+                headers['idempotency-key'] = ro.idempotencyKey ?? `mcp_${randomUUID()}`;
+            for (let attempt = 0;; attempt++) {
+                let res;
+                try {
+                    res = await f(url, {
+                        method,
+                        headers,
+                        ...(ro.body !== undefined ? { body: JSON.stringify(ro.body) } : {}),
+                        signal: AbortSignal.timeout(opts.timeoutMs ?? 90_000),
+                    });
+                }
+                catch (err) {
+                    if (attempt < maxRetries) {
+                        await sleep(300 * 2 ** attempt);
+                        continue;
+                    }
+                    throw new CheckboxApiError(`Could not reach ${base}: ${err instanceof Error ? err.message : String(err)}`, 0, 'api_connection_error', 'network_error');
+                }
+                if ((res.status === 429 || res.status >= 500) && attempt < maxRetries) {
+                    const retryAfter = Number(res.headers.get('retry-after'));
+                    await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 10) * 1000 : 500 * 2 ** attempt);
+                    continue;
+                }
+                const text = await res.text();
+                let json;
+                try {
+                    json = text ? JSON.parse(text) : undefined;
+                }
+                catch {
+                    json = undefined;
+                }
+                return interpretResponse(res.status, json, res.headers.get('request-id') ?? undefined, text);
+            }
+        },
+    };
+}
+/**
+ * Adapts a Node SDK client (@checkbox-site/node) to CheckboxApi. Any client with a Stripe-style
+ * `rawRequest(method, path, params?, options?)` or a `request(method, path, { query, body, idempotencyKey })` works;
+ * errors with `status`/`code`/`type` fields are mapped to CheckboxApiError.
+ */
+export function fromSdkClient(client, info) {
+    const c = client;
+    const call = c?.request
+        ? (m, p, o) => c.request(m, p, { query: o.query, body: o.body, idempotencyKey: o.idempotencyKey ?? (m === 'POST' ? `mcp_${randomUUID()}` : undefined) })
+        : c?.rawRequest
+            ? (m, p, o) => c.rawRequest(m, withQuery(p, o.query), o.body, { idempotencyKey: o.idempotencyKey ?? (m === 'POST' ? `mcp_${randomUUID()}` : undefined) })
+            : null;
+    if (!call)
+        return null;
+    return {
+        ...info,
+        async request(method, path, ro = {}) {
+            try {
+                return (await call(method, path, ro));
+            }
+            catch (err) {
+                throw toCheckboxApiError(err);
+            }
+        },
+    };
+}
+function toCheckboxApiError(err) {
+    if (err instanceof CheckboxApiError)
+        return err;
+    const e = (err ?? {});
+    const raw = (e.raw ?? e.error ?? {});
+    const pick = (k) => (typeof e[k] === 'string' ? e[k] : typeof raw[k] === 'string' ? raw[k] : undefined);
+    const status = typeof e.status === 'number' ? e.status : typeof e.statusCode === 'number' ? e.statusCode : 0;
+    const next = (e.nextAction ?? e.next_action ?? raw.next_action);
+    return new CheckboxApiError(err instanceof Error ? err.message : pick('message') ?? 'Request failed', status, pick('type') ?? (status ? 'api_error' : 'api_connection_error'), pick('code') ?? (status ? 'unknown_error' : 'network_error'), pick('param'), pick('requestId') ?? pick('request_id'), next && typeof next === 'object' ? next : undefined, pick('docUrl') ?? pick('doc_url'));
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The `checkbox-mcp` executable (package.json "bin").
+import { runStdio } from "./stdio.js";
+runStdio().catch((err) => {
+    process.stderr.write(`checkbox-mcp: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/format.d.ts

@@ -0,0 +1,40 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type NextAction } from './api.ts';
+/** API operationId → the MCP tool that performs it. Operations without a tool are reached with call_api. */
+export declare const OPERATION_TOOLS: Record<string, string>;
+/** The MCP tool that performs an operation: its dedicated tool, else `call_api`. */
+export declare function mcpToolFor(operationId: string | null | undefined): string | null;
+/**
+ * Quotes text Checkbox did not write (page HTML, email bodies, policy text, merchant-supplied strings) for the text part
+ * of a tool result: JSON-encoded on one line, truncated, inside explicit <untrusted_text> delimiters, so a model never
+ * 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;
+/** One line telling the model what to call next, in MCP terms. */
+export declare function describeNextAction(next: NextAction | null | undefined): string | null;
+/** Pulls the top-level next_action off an API object. */
+export declare function nextActionOf(obj: unknown): NextAction | null;
+export interface ToolOutput {
+    /** One or two sentences: what happened / where things stand. */
+    headline: string;
+    /** Extra lines (bullets) between the headline and the JSON. */
+    notes?: string[];
+    /** The API object (or a composite). Printed as JSON. */
+    data?: unknown;
+    /** Overrides data.next_action for the "Next:" line. */
+    next?: NextAction | null;
+    /** 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

@@ -0,0 +1,238 @@
+import { CheckboxApiError } from "./api.js";
+/** API operationId → the MCP tool that performs it. Operations without a tool are reached with call_api. */
+export const OPERATION_TOOLS = {
+    createDeviceAuthorization: 'setup_checkbox',
+    createDeviceToken: 'setup_checkbox',
+    createSetupSession: 'setup_checkbox',
+    retrieveSetupSession: 'get_setup_status',
+    listSetupSessions: 'get_setup_status',
+    verifySetupSession: 'get_setup_status',
+    updateSetupSession: 'update_setup',
+    completeSetupSession: 'complete_setup',
+    retrieveCompliancePlan: 'get_compliance_plan',
+    retrieveTask: 'get_task',
+    verifyTask: 'verify_task',
+    answerTask: 'answer_task',
+    verifySite: 'verify_site',
+    retrieveVerification: 'get_verification',
+    createTestRun: 'start_test_run',
+    retrieveTestRun: 'get_test_run',
+    listTestRuns: 'get_test_run',
+    checkDisclosure: 'check_disclosure',
+    checkStripeCheckoutSession: 'check_stripe_checkout_session',
+    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',
+    retrieveSite: 'get_site_status',
+    retrieveLatestEvaluation: 'get_site_status',
+    createEvaluation: 'verify_site',
+    listFindings: 'list_findings',
+    retrieveFinding: 'get_finding',
+    retrieveFindingFix: 'get_finding',
+    createScan: 'run_scan',
+    retrieveScan: 'get_scan',
+    listLawUpdates: 'list_law_updates',
+    createFeedback: 'send_feedback',
+    createDisclosure: 'get_elements_snippet',
+    retrieveReceipt: 'get_receipt',
+    verifyReceipt: 'get_receipt',
+    listReceipts: 'list_receipts',
+    listDueNotices: 'list_due_notices',
+    markNoticeSent: 'mark_notice_sent',
+    markNoticeMissed: 'mark_notice_sent',
+    listNoticeTemplates: 'get_notice_templates',
+    checkNoticeTemplate: 'get_notice_templates',
+};
+/** The MCP tool that performs an operation: its dedicated tool, else `call_api`. */
+export function mcpToolFor(operationId) {
+    if (!operationId)
+        return null;
+    return OPERATION_TOOLS[operationId] ?? 'call_api';
+}
+/** Arguments for the generic call_api tool when an operation has no dedicated tool. */
+const OPERATION_ENDPOINTS = {
+    createTestCredential: 'POST /v1/sites/{site}/test_credentials',
+    connectBillingPlatform: 'POST /v1/sites/{site}/integrations',
+    createStripeCheckoutConfig: 'POST /v1/sites/{site}/stripe_checkout_configs',
+    createDomainVerification: 'POST /v1/sites/{site}/domain_verification',
+    checkDomainVerification: 'POST /v1/sites/{site}/domain_verification/check',
+    retrieveDomainVerification: 'GET /v1/sites/{site}/domain_verification',
+    updateTask: 'POST /v1/tasks/{task}',
+    updateFinding: 'POST /v1/findings/{finding}',
+    listConsents: 'GET /v1/consents',
+    updateNoticeSettings: 'POST /v1/sites/{site}/notice_settings',
+    retrieveNoticeSettings: 'GET /v1/sites/{site}/notice_settings',
+    createWebhookEndpoint: 'POST /v1/webhook_endpoints',
+    createCertificate: 'POST /v1/sites/{site}/certificates',
+    retrieveAccount: 'GET /v1/account',
+    checkStripePaymentLink: 'POST /v1/checks/stripe_payment_link',
+    listSiteFixes: 'GET /v1/sites/{site}/fixes',
+    listVerifications: 'GET /v1/sites/{site}/verifications',
+    cancelTestRun: 'POST /v1/test_runs/{test_run}/cancel',
+};
+/**
+ * Quotes text Checkbox did not write (page HTML, email bodies, policy text, merchant-supplied strings) for the text part
+ * of a tool result: JSON-encoded on one line, truncated, inside explicit <untrusted_text> delimiters, so a model never
+ * reads it as an instruction next to the "Next:" line. Full values stay in the fenced JSON.
+ */
+export function untrusted(value, max = 80) {
+    let s = String(value ?? '').replace(/\s+/g, ' ').trim();
+    if (s.length > max)
+        s = `${s.slice(0, max)}…`;
+    // No markup that could close the delimiter or open a fake one.
+    s = s.replace(/</g, '‹').replace(/>/g, '›');
+    return `<untrusted_text>${JSON.stringify(s)}</untrusted_text>`;
+}
+/** One line telling the model what to call next, in MCP terms. */
+export function describeNextAction(next) {
+    if (!next || typeof next !== 'object' || !next.type)
+        return null;
+    const text = (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;
+    const parts = [`Next (${next.type}): ${text || 'see next_action.'}`];
+    if (tool)
+        parts.push(`→ MCP tool \`${tool}\`${next.task ? ` (task: ${next.task})` : ''}.`);
+    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).`);
+    }
+    if (next.command)
+        parts.push(`CLI equivalent: \`${next.command}\`.`);
+    if (next.url && !tool)
+        parts.push(`Docs: ${next.url}`);
+    return parts.join(' ');
+}
+/** Pulls the top-level next_action off an API object. */
+export function nextActionOf(obj) {
+    const n = obj?.next_action;
+    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;
+}
+/**
+ * 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;
+        }
+        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()];
+    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);
+    if (out.data !== undefined) {
+        const fitted = fitJson(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 } : {}) };
+}
+/** An API error as a tool result: stable code, message, param and the API's own next_action. */
+export function renderError(err) {
+    if (err instanceof CheckboxApiError) {
+        const data = { type: err.type, code: err.code, message: err.message };
+        if (err.param)
+            data.param = err.param;
+        if (err.status)
+            data.http_status = err.status;
+        if (err.requestId)
+            data.request_id = err.requestId;
+        if (err.docUrl)
+            data.doc_url = err.docUrl;
+        if (err.nextAction)
+            data.next_action = err.nextAction;
+        const hint = 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,
+            isError: true,
+        });
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return renderOutput({ headline: `Tool failed: ${message}`, isError: true });
+}
+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_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.',
+    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.',
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { API_VERSION, CheckboxApiError, DEFAULT_API_BASE, createHttpApi, fromSdkClient, interpretResponse, withQuery, type ApiRequestOptions, type CheckboxApi, type HttpMethod, type NextAction, } from './api.ts';
+export { OPERATION_TOOLS, describeNextAction, renderError, renderOutput, type ToolOutput } from './format.ts';
+export { NO_KEY, keyAllows, keyContextFromPrefix, type KeyContext, type KeyRole, type ToolScope } from './permissions.ts';
+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 { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+// @checkbox-site/mcp — the Checkbox MCP server (tools, resources, prompts) shared by the remote endpoint
+// (https://app.checkbox.site/mcp, apps/api/src/mcp) and the local stdio binary (dist/bin.js).
+export { API_VERSION, CheckboxApiError, DEFAULT_API_BASE, createHttpApi, fromSdkClient, interpretResponse, withQuery, } from "./api.js";
+export { OPERATION_TOOLS, describeNextAction, renderError, renderOutput } from "./format.js";
+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";
+// Re-exported so hosts use the same SDK copy as the server.
+export { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

package/dist/permissions.d.ts

@@ -0,0 +1,30 @@
+export type Access = 'read' | 'write';
+/** `<resource>:<access>` as in the /v1 restricted-key scopes (apps/api/src/v1/scopes.ts). */
+export type ToolScope = `${string}:${Access}`;
+export type KeyRole = 'admin' | 'member' | 'viewer';
+/** What is known about the key the server acts with. */
+export interface KeyContext {
+    /** No key at all: only the setup (device login) tool and the docs work. */
+    authenticated: boolean;
+    /** test / live, or unknown (stdio before the first call). */
+    mode: 'test' | 'live' | 'unknown';
+    kind?: 'secret' | 'restricted';
+    role?: KeyRole;
+    /** Restricted keys only: `{ resource: 'read' | 'write' }`. */
+    scopes?: Record<string, string> | null;
+    /** Hide every write tool regardless of the key (`?read_only=true`, `--read-only`). */
+    readOnly?: boolean;
+    /**
+     * How the remote connection authenticated: an API key in the Authorization header, or an OAuth access token from
+     * the one-click connector flow (claude.ai / Claude Desktop / Claude Code / Cursor). With OAuth there is no key to
+     * copy or save: setup_checkbox registers the site and runs the first checks straight away.
+     */
+    auth?: 'api_key' | 'oauth';
+    /** OAuth only: the connected app's name as approved by the human (e.g. "Claude"). */
+    appName?: string;
+}
+export declare const NO_KEY: KeyContext;
+/** Whether the key may use one scope (write implies read; viewer keys are read-only). */
+export declare function keyAllows(key: KeyContext, scope: ToolScope): boolean;
+/** Infers the mode and kind from the key prefix (the server confirms with retrieveAccount when it can). */
+export declare function keyContextFromPrefix(apiKey: string | undefined, readOnly?: boolean): KeyContext;