@checkbox-site/mcp 0.2.3 → 0.2.5

package/dist/resources.js

@@ -62,6 +62,9 @@ what to change. Free. Every feature. No credit card. Fair-use limits.
 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 checks pass (plan status value \`compliant\`, label "Checks pass"), then **complete_setup** (emails the human a summary).
+8. A setup in Stripe test mode is not live yet: the plan and complete_setup carry **go_live** (the steps left before
+   real customers, with who takes each: verify the domain, the live Stripe key — a person only —, the live checkout,
+   promoting the site). Tell the human "set up in test mode; N steps before real customers", never just "done".
 
 Every tool result ends with "Next: …" naming the tool to call. Errors carry a stable \`code\` and often a next_action.
 

package/dist/server.d.ts

@@ -5,7 +5,7 @@ import type { KeyContext } from './permissions.ts';
 import { type IssuedKeys, type ToolContext, type ToolDef } from './tools.ts';
 export declare const SERVER_NAME = "checkbox";
 /** Kept equal to packages/mcp/package.json "version" (@checkbox-site/mcp); mcp.test.ts checks it. */
-export declare const SERVER_VERSION = "0.2.3";
+export declare const SERVER_VERSION = "0.2.5";
 export declare const DEFAULT_MCP_URL = "https://app.checkbox.site/mcp";
 /** The coverage phrase used across Checkbox (the API docs tests check the count against the rules catalog). */
 export declare const COVERAGE_PHRASE = "federal law, 27 states, DC and New York City";

package/dist/server.js

@@ -9,7 +9,7 @@ import { likelyMisspelling, unknownArgumentsMessage, unknownKeysParams } from ".
 import { outdatedNotice } from "./version-check.js";
 export const SERVER_NAME = 'checkbox';
 /** Kept equal to packages/mcp/package.json "version" (@checkbox-site/mcp); mcp.test.ts checks it. */
-export const SERVER_VERSION = '0.2.3';
+export const SERVER_VERSION = '0.2.5';
 export const DEFAULT_MCP_URL = 'https://app.checkbox.site/mcp';
 /** The coverage phrase used across Checkbox (the API docs tests check the count against the rules catalog). */
 export const COVERAGE_PHRASE = 'federal law, 27 states, DC and New York City';

package/dist/tools.d.ts

@@ -153,6 +153,17 @@ export declare function summaryEmailLine(status: string | null | undefined, d: {
     to?: string | null;
     error?: string | null;
 } | null | undefined): string;
+export interface GoLiveLite {
+    summary: string;
+    steps: Array<{
+        key: string;
+        who: 'person' | 'agent';
+        text: string;
+        url?: string;
+    }>;
+}
+/** Round 32 (pilot 31 item 1): the go-live list as notes: what to tell the owner, then each step with who takes it. Pure. */
+export declare function goLiveNotes(g: GoLiveLite | null | undefined): string[];
 export declare function planStatusWords(status: string, label?: string | null): string;
 interface PlanLite {
     status: string;
@@ -237,6 +248,18 @@ interface SiteShopifyLite {
 }
 /** The site's Shopify connection in one line, naming the tool (or the human step) that comes next. */
 export declare function shopifyLines(sh: SiteShopifyLite | null | undefined, site: string): string[];
+/**
+ * Round 32 (pilot 31, codex: get_finding on a not_applicable / resolved finding said "apply_fix … verify_site"). Next
+ * follows the finding's status: nothing to fix for a finding that passes, does not apply or is resolved. Pure, exported
+ * for tests.
+ */
+export declare function findingNext(finding: {
+    status: string;
+    state?: string;
+    compliance?: {
+        status?: string;
+    } | null;
+}, fromFix: NextAction | null): NextAction;
 /**
  * Agent audit round 2: list_law_updates with limit 3 printed 62 KB (one catalog update carried 195 requirement changes,
  * each with its full summary). Each update keeps its first changes in short form, with the total.

package/dist/tools.js

@@ -646,6 +646,8 @@ const setupCheckbox = {
                 headline: `Ask the human to open ${auth.verification_uri_complete} and click Approve (code ${auth.user_code}). It expires in ${Math.round(auth.expires_in / 60)} minutes.`,
                 notes: [
                     'Tell the human exactly one line, e.g. "Open <link> and click Approve to connect Checkbox (free, no card)." Do not ask them to copy keys.',
+                    // Round 32 (pilot 31 item 13): the Stripe key box and the restricted key in the same message (one approval).
+                    `${args.billing_platform === 'stripe' ? 'In the same message' : 'If the site sells through Stripe, in the same message'}, ask them to tick “Let your agent store a Stripe test-mode key” on that page and, if the project has no rk_test_ key yet, to create a restricted key in Stripe Test mode (https://dashboard.stripe.com/test/apikeys → Create restricted key, with the permissions the approval page lists) and put it in the project's env file (never in the chat): one approval then covers the key and the test subscription.`,
                     `Then call setup_checkbox again with device_code "${auth.device_code}" AND the same facts (site_url, checkout_url, merchant_name, plans, policy URLs): after the approval Checkbox applies them and runs the first checks in that call. Keep the device_code private; it is not shown to the human.`,
                 ],
                 next: { type: 'wait_for_approval', message: `Call setup_checkbox with device_code "${auth.device_code}" to wait for the approval.`, operation_id: 'createDeviceToken' },
@@ -729,7 +731,7 @@ const getSetupStatus = {
             const pl = sitePlansNote(res.setup_session?.site_plans);
             if (pl)
                 notes.push(pl);
-            return { headline: `Re-checked setup session ${id}.`, ...(notes.length ? { notes } : {}), data: withoutLegacyScore(res), next: nextActionOf(res) ?? nextActionOf(res.session) };
+            return { headline: `Re-checked setup session ${id}.`, ...(notes.length ? { notes } : {}), data: withoutLegacyScore(res), next: nextActionOf(res) ?? nextActionOf(res.setup_session) ?? nextActionOf(res.session) };
         }
         const session = await api.request('GET', `/v1/setup_sessions/${enc(id)}`);
         const open = (session.steps ?? []).filter((s) => s.status && !['done', 'skipped', 'not_applicable'].includes(s.status));
@@ -738,7 +740,7 @@ const getSetupStatus = {
         return {
             headline: `Setup session ${session.id}: ${session.status}; ${open.length} checklist step(s) open.`,
             // The policies step says what an unverified preview read (or that the pages wait for domain verification).
-            notes: [...open.slice(0, 8).map((s) => `${s.status}: ${s.title ?? s.key}${s.key === 'policies' && s.summary ? ` (${s.summary.slice(0, 240)})` : ''}`), ...(ro ? [ro] : []), ...(plansLine ? [plansLine] : [])],
+            notes: [...open.slice(0, 8).map((s) => `${s.status}: ${s.title ?? s.key}${s.key === 'policies' && s.summary ? ` (${s.summary.slice(0, 240)})` : ''}`), ...(ro ? [ro] : []), ...(plansLine ? [plansLine] : []), ...(session.next_action?.type === 'done' ? goLiveNotes(session.go_live) : [])],
             data: withoutLegacyScore(session),
         };
     },
@@ -792,19 +794,27 @@ export function summaryEmailLine(status, d) {
         return 'not sent: this deployment has no email delivery';
     return 'not sent';
 }
+/** Round 32 (pilot 31 item 1): the go-live list as notes: what to tell the owner, then each step with who takes it. Pure. */
+export function goLiveNotes(g) {
+    if (!g?.steps?.length)
+        return [];
+    return [g.summary, ...g.steps.map((s, i) => `Go live ${i + 1} (${s.who === 'person' ? 'owner' : 'you, the agent'}): ${s.text}${s.url ? ` ${s.url}` : ''}`)];
+}
 const completeSetup = {
     name: 'complete_setup',
     title: 'Finish setup and email the human a summary',
-    description: 'Call once the setup checklist next_action is "done" (or nothing else can be done without the human). Marks the setup finished and emails the person who approved it "<agent> set up Checkbox for <domain>" with what was created, what is still open and a review link. Idempotent: the email is sent once. Monitoring keeps running. Then work through get_compliance_plan.',
+    description: 'Call once the setup checklist next_action is "done" (or nothing else can be done without the human). Marks the setup finished and emails the person who approved it "<agent> set up Checkbox for <domain>" with what was created, what is still open, the go-live steps and a review link. Idempotent: the email is sent once. Monitoring keeps running. In test mode it returns go_live: tell the human go_live.summary ("set up in test mode; N steps before real customers"), never just "done".',
     input: { setup_session: z.string().max(100).optional().describe('Setup session id (setup_…). Default: the newest one.') },
     scopes: ['setup_sessions:write'],
     annotations: { ...write(true), title: 'Complete setup' },
     async run(args, { api }) {
         const id = await resolveSetupSession(api, args.setup_session);
         const session = await api.request('POST', `/v1/setup_sessions/${enc(id)}/complete`, { body: {} });
+        // Round 32 (pilot 31 item 1): a test-mode setup is "set up in test mode; N steps before real customers", never "done".
+        const live = goLiveNotes(session.go_live);
         return {
-            headline: `Setup ${session.id} completed; summary email: ${summaryEmailLine(session.owner_email, session.owner_email_detail)}.`,
-            notes: session.review_url ? [`Human review page: ${session.review_url}`] : [],
+            headline: `Setup ${session.id} completed${session.go_live ? ` in Stripe test mode (${session.go_live.steps.length} step${session.go_live.steps.length === 1 ? '' : 's'} left before real customers)` : ''}; summary email: ${summaryEmailLine(session.owner_email, session.owner_email_detail)}.`,
+            notes: [...live, ...(session.review_url ? [`Human review page: ${session.review_url}`] : [])],
             data: withoutLegacyScore(session),
         };
     },
@@ -912,6 +922,7 @@ const getCompliancePlan = {
                 ...(optional.length ? [`Optional suggestions (${plan.protection_level ?? 'balanced'} protection; never block the checks from passing): ${optional.map((t) => t.title).join('; ')}`] : []),
                 ...(plan.optional_improvements ? ['Optional (never blocking, not part of compliance): conversion suggestions for this site with `suggest_improvements`.'] : []),
                 'Each task below is a summary; call get_task with its id for the full change (diff, copy or params) before applying it.',
+                ...goLiveNotes(plan.go_live),
                 ...(plan.status === 'compliant' ? await reviewHint(api, site, 'plan_compliant') : []),
             ],
             // Normal-round pilot (sveltekit): the full plan (53K characters) was cut mid-JSON by the client. The plan here is a
@@ -941,7 +952,7 @@ export function precheckLines(pre, max = 12) {
     const checks = pre?.checks ?? [];
     if (!checks.length)
         return [];
-    const order = { fail: 0, needs_review: 1, missing_data: 1, pass: 2, not_applicable: 3 };
+    const order = { fail: 0, needs_review: 1, missing_data: 1, pass: 2, informational: 2, not_applicable: 3 };
     const sorted = [...checks].sort((a, b) => (order[a.status] ?? 1) - (order[b.status] ?? 1));
     const lines = sorted.slice(0, max).map((c) => `${c.check_id}: ${c.status}${c.reason ? ` — ${untrusted(c.reason, 180)}` : ''}${c.fix ? ` Fix: ${untrusted(c.fix, 200)}` : ''}`);
     return [`Pre-check (${pre?.verdict ?? 'n/a'}), per check:`, ...lines, ...(checks.length > max ? [`and ${checks.length - max} more (data.precheck.checks)`] : [])];
@@ -955,7 +966,7 @@ const verifyTask = {
         '- page tasks: html = the rendered page HTML (before or after deploy; ≤ ~900 KB). Without it Checkbox fetches the live page.',
         '- Stripe tasks: stripe_checkout_session = exactly the object your code now passes to stripe.checkout.sessions.create.',
         '- email tasks: email = { subject, text and/or html } of the new template.',
-        'Result: verification status passed / failed (with a diff of expected vs observed) / pending (waiting for the confirming scan). Waits up to `wait` seconds. Then follow next_action (usually get_compliance_plan). A verification with checks still needs_review is reported as failed with next_action type needs_review: it is not done.',
+        'Result: verification status passed / failed (with a diff of expected vs observed) / pending (waiting for the confirming scan). Waits up to `wait` seconds. Then follow next_action (usually get_compliance_plan). A verification with checks still needs_review is reported as failed with next_action type needs_review: it is not done. "informational" checks are notes on Stripe\'s own layout: nothing to change.',
     ].join('\n'),
     input: {
         task: z.string().max(100).describe('Task id (task_…).'),
@@ -1115,7 +1126,7 @@ const startTestRun = {
     name: 'start_test_run',
     title: 'Run a synthetic test subscription (test mode)',
     description: [
-        'Observes the WHOLE subscription lifecycle, not just the checkout: in the billing platform\'s TEST mode Checkbox subscribes a test customer (card 4242…) whose email is a Checkbox inbox, waits for your acknowledgment email, fast-forwards a Stripe test clock through every legal notice window before trial end and renewal (collecting reminder emails), then cancels online and waits for the cancellation confirmation. Nothing is charged.',
+        'Observes the WHOLE subscription lifecycle in the billing platform\'s TEST mode: subscribes a test customer (card 4242…) with a Checkbox inbox email, waits for the acknowledgment, fast-forwards a Stripe test clock through each notice window before trial end and renewal (collecting reminders), then cancels online and waits for the confirmation. Nothing is charged.',
         'Needs a Stripe TEST-mode restricted key (rk_test_…) stored for the site: store it yourself with store_stripe_test_key (one key for checks, fixes and test runs; live keys stay with the human in the dashboard). Never ask the human to paste a key into the chat. If missing, the error\'s next_action says so. For non-Stripe sites use type "generic".',
         'Usually 1-2 minutes (real_checkout: a few): poll get_test_run (its next_action says when, and minutes_left estimates the rest). Each step reports observations, check results and agent-readable fixes; apply them and run again.',
         'mode "real_checkout" is the PROOF run: the shopper buys through the merchant\'s own checkout on its test deployment (stripe.checkout_url or stripe.payment_link), so the merchant\'s webhook handlers and email code fire; give stripe.test_account + stripe.cancel_url when customers cancel in the app. A step is "passed" only with evidence; "warning" means needs review.',
@@ -1315,7 +1326,9 @@ const checkEmail = {
     annotations: { ...ro, title: 'Check email' },
     async run(args, { api }) {
         const r = await api.request('POST', '/v1/checks/email', { body: { ...args, kind: checkKind(args.kind) } });
-        const notes = checkNotes(r, 8, r.template?.verified ? { by: 'template (subject + text or html; add your greeting and sign-off around it if you like)', except: r.template.remaining_checks ?? [] } : undefined);
+        // Round 32 (pilot 31): a template with values left to fill ({{support_contact}}, {{cancel_url}}) passes once they are filled.
+        const toFill = r.template?.placeholders ?? [];
+        const notes = checkNotes(r, 8, r.template?.verified ? { by: `template (subject + text or html; add your greeting and sign-off around it if you like${toFill.length ? `; replace ${toFill.join(', ')} with your real value${toFill.length === 1 ? '' : 's'} first, or pass them in terms` : ''})`, except: r.template.remaining_checks ?? [] } : undefined);
         notes.unshift(r.required_by?.length ? `Legally required for this plan by: ${citationList(r.required_by, r.requirements)}.` : 'Not legally required for this plan (still good practice).');
         return { headline: verdictHeadline(`Email (${String(args.kind)}${r.plan ? `, plan ${untrusted(r.plan, 60)}` : ''})`, r), notes, data: slimCheckResult(r) };
     },
@@ -1457,7 +1470,7 @@ const suggestImprovements = {
     name: 'suggest_improvements',
     title: 'Suggest conversion improvements that keep the checks passing',
     description: [
-        'OPTIONAL, after compliance: concrete ways to make the checkout page, Stripe Checkout, lifecycle emails and the cancellation flow convert or retain better WITHOUT breaking automatic-renewal laws. Deterministic library; every after-example was run through Checkbox\'s own checks for the merchant\'s states before it is offered.',
+        'OPTIONAL, after the checks pass: concrete ways to make the checkout, Stripe Checkout, lifecycle emails and cancellation flow convert or retain better WITHOUT breaking automatic-renewal laws. Every after-example passed Checkbox\'s own checks for the merchant\'s states.',
         'Each suggestion gives apply.where + apply.content (the exact copy, Stripe JSON patch or flow change to make), apply.instructions, preconditions that must be true (never apply one whose precondition is false), and guardrails with catalog requirement ids (e.g. California / Colorado click-to-cancel next to any save offer, Minnesota ask-first). Never invent figures or add urgency, pre-checked boxes or obstacles.',
         'With a site id (or one site in this mode): suggestions from what Checkbox observed. Or send the copy you are writing: terms + any of disclosure, page_html, stripe_checkout_session_params, emails, cancellation_flow (as in the check_* tools).',
         'Surfaces whose compliance checks fail are held: fix them first (get_compliance_plan). Suggestions never block and never count toward compliance. After applying one, re-run the check named in verification.operation_id on the real copy.',
@@ -1812,10 +1825,23 @@ const getFinding = {
             headline: `${finding.severity.toUpperCase()} ${finding.id} [${finding.compliance?.label ?? finding.status}] ${finding.check_id}: ${finding.title}`,
             notes: [complianceBullet(finding.check_id, finding.compliance, finding.status, finding.title)].filter((x) => !!x),
             data: { finding, fix },
-            next: nextActionOf(fix) ?? { type: 'apply_fix', message: 'Apply fix (or the matching task from get_compliance_plan), then call verify_site.', operation_id: 'verifySite' },
+            next: findingNext(finding, nextActionOf(fix)),
         };
     },
 };
+/**
+ * Round 32 (pilot 31, codex: get_finding on a not_applicable / resolved finding said "apply_fix … verify_site"). Next
+ * follows the finding's status: nothing to fix for a finding that passes, does not apply or is resolved. Pure, exported
+ * for tests.
+ */
+export function findingNext(finding, fromFix) {
+    const settled = finding.status === 'pass' || finding.status === 'not_applicable' || finding.state === 'resolved' || finding.compliance?.status === 'compliant' || finding.compliance?.status === 'not_applicable' || finding.compliance?.status === 'verified_live';
+    if (settled) {
+        const why = finding.state === 'resolved' ? 'resolved' : finding.status === 'not_applicable' || finding.compliance?.status === 'not_applicable' ? 'not applicable to this site' : 'passing';
+        return { type: 'continue', message: `Nothing to fix: this finding is ${why}. Continue with get_compliance_plan for what is left.`, operation_id: 'retrieveCompliancePlan' };
+    }
+    return fromFix ?? { type: 'apply_fix', message: 'Apply fix (or the matching task from get_compliance_plan), then call verify_site.', operation_id: 'verifySite' };
+}
 const publishShopifyTerms = {
     name: 'publish_shopify_terms',
     title: 'Publish renewal terms to the Shopify app block (write)',

package/package.json

@@ -1,18 +1,26 @@
 {
   "name": "@checkbox-site/mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Checkbox MCP server: auto-renewal law and subscription compliance checks for AI agents (FTC ROSCA, California ARL, New York and other states) on Stripe Checkout params, pricing pages, disclosures and emails. Remote at https://app.checkbox.site/mcp, or local stdio.",
   "keywords": [
+    "checkbox",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "ai-agent",
+    "stripe",
+    "stripe-checkout",
     "subscription",
     "subscription-compliance",
-    "subscription compliance",
     "auto-renewal",
-    "auto renewal",
-    "autorenewal",
     "automatic-renewal",
     "compliance",
     "rosca",
     "click-to-cancel",
+    "ci",
+    "subscription compliance",
+    "auto renewal",
+    "autorenewal",
     "california-arl",
     "auto-renewal-law",
     "auto-renewal-compliance",
@@ -21,14 +29,8 @@
     "stripe-subscriptions",
     "ftc",
     "negative-option",
-    "stripe",
-    "stripe-checkout",
     "checkout",
-    "cancellation",
-    "mcp",
-    "model-context-protocol",
-    "mcp-server",
-    "ai-agent"
+    "cancellation"
   ],
   "mcpName": "site.checkbox/checkbox",
   "license": "MIT",
@@ -75,7 +77,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@checkbox-site/node": "^0.2.3",
+    "@checkbox-site/node": "^0.2.5",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "zod": "^4.6.7"
   }