@checkbox-site/mcp 0.2.6 → 0.2.8

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.6";
+export declare const SERVER_VERSION = "0.2.8";
 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.6';
+export const SERVER_VERSION = '0.2.8';
 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.js

@@ -1220,14 +1220,24 @@ const startTestRun = {
         };
     },
 };
+const TEST_RUN_MAX_WAIT = 55;
+const TEST_RUN_DONE = new Set(['succeeded', 'incomplete', 'failed', 'canceled']);
 const getTestRun = {
     name: 'get_test_run',
     title: 'Get a test run (steps, observations, fixes)',
-    description: 'A synthetic test subscription with every step (checkout, acknowledgment email, reminders at each legal window, cancellation, confirmation): what was observed, check results, evidence ids and fixes. While running, next_action.type is "wait" and waiting_for says what it waits for (pass wait: 30 to get the answer as soon as the run moves on). When finished, apply the fixes (usually via get_compliance_plan) and start another run to verify. Without test_run, returns the newest run of the site.',
+    description: 'A synthetic test subscription with every step (checkout, acknowledgment email, reminders at each legal window, cancellation, confirmation): what was observed, check results, evidence ids and fixes. While running, next_action.type is "wait" and waiting_for says what it waits for: pass wait: 55 to get the answer as soon as the run finishes (one or two calls per run). When finished, apply the fixes (usually via get_compliance_plan) and start another run to verify. Without test_run, returns the newest run of the site.',
     input: {
         test_run: z.string().max(100).optional().describe('Test run id (run_…). Default: the newest run of the site.'),
         site: siteId.optional(),
-        wait: z.number().int().min(0).max(30).optional().describe('Long-poll: wait up to this many seconds for the run to move on before answering.'),
+        // Round 34 (pilot 33 item 22, core-codex: 25 polls with wait=30 for runs of 1-2 minutes, because each poll answered
+        // on every step): wait up to 55 s (under common 60 s client tool timeouts), answering when the run finishes.
+        wait: z
+            .number()
+            .int()
+            .min(0)
+            .transform((n) => Math.min(TEST_RUN_MAX_WAIT, n))
+            .optional()
+            .describe(`Seconds to wait for the run to finish before answering (0-${TEST_RUN_MAX_WAIT}; larger values wait ${TEST_RUN_MAX_WAIT}). Answers at once when it finishes.`),
     },
     scopes: ['test_runs:read'],
     annotations: { ...ro, title: 'Test run' },
@@ -1240,8 +1250,15 @@ const getTestRun = {
                 throw new ToolError(`Site ${site} has no test run yet.`, { type: 'start_test_run', message: 'Call start_test_run.', operation_id: 'createTestRun' });
             id = list.data[0].id;
         }
-        const wait = typeof args.wait === 'number' && args.wait > 0 ? Math.min(30, Math.floor(args.wait)) : undefined;
-        const run = await api.request('GET', `/v1/test_runs/${enc(id)}`, wait ? { query: { wait } } : undefined);
+        const wait = typeof args.wait === 'number' && args.wait > 0 ? Math.min(TEST_RUN_MAX_WAIT, Math.floor(args.wait)) : 0;
+        const deadline = Date.now() + wait * 1000;
+        // The API long-polls up to 30 s per call and answers on every step; keep asking until the run finishes or time is up.
+        let run = await api.request('GET', `/v1/test_runs/${enc(id)}`, wait ? { query: { wait: Math.min(30, wait) } } : undefined);
+        for (let left = Math.floor((deadline - Date.now()) / 1000); wait && !TEST_RUN_DONE.has(run.status) && left >= 1; left = Math.floor((deadline - Date.now()) / 1000)) {
+            run = await api.request('GET', `/v1/test_runs/${enc(id)}`, { query: { wait: Math.min(30, left) } });
+        }
+        const running = !TEST_RUN_DONE.has(run.status);
+        const next = running && run.next_action?.type === 'wait' ? { ...run.next_action, message: `${(run.next_action.message ?? '').replace(/\s*Call retrieveTestRun with \?wait=30[^.]*\.?/, '').trim()} Call get_test_run again with wait: ${TEST_RUN_MAX_WAIT}: it answers as soon as the run finishes.`.trim() } : undefined;
         const w = run.waiting_for;
         const progress = w ? [w.step && w.steps_total ? `step ${w.step} of ${w.steps_total}` : '', w.minutes_left ? `about ${w.minutes_left} min left` : ''].filter(Boolean).join(', ') : '';
         const waiting = w ? `Waiting for: ${w.what}${w.until ? ` (until ${new Date(w.until * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC at the latest)` : ''}${progress ? ` [${progress}]` : ''}` : null;
@@ -1249,6 +1266,7 @@ const getTestRun = {
             headline: `Test run ${run.id}: ${run.status_label ?? statusLine(run.status)}${run.phase && run.status !== 'succeeded' && run.status !== 'failed' ? ` (phase ${run.phase})` : ''}.`,
             notes: [...(waiting ? [waiting] : []), ...(run.steps ?? []).map((s) => `${s.status ?? '?'}: ${s.title ?? s.key}${s.code ? ` (${s.code})` : ''}`)].slice(0, 13),
             data: run,
+            ...(next ? { next } : {}),
         };
     },
 };
@@ -1260,8 +1278,8 @@ const checkDisclosure = {
     title: 'Check checkout disclosure text',
     description: [
         'Before shipping a checkout: checks the automatic-renewal disclosure shown next to the purchase button against every applicable law (ROSCA, CA, NY, …) and returns per-check verdicts with citations plus a REPLACEMENT verified by the rules engine (disclosure_text, consent_label, button_text, drop-in html and jsx).',
-        'Pass the text exactly as rendered plus the plan terms. Example: {"text":"Renews monthly at $19.99 until you cancel.","price":19.99,"interval":"month","trial_days":14,"cancel_url":"https://acme.example/account/cancel","merchant_name":"Acme","consent":{"checkbox":true,"prechecked":false}}.',
-        'If verdict is fail, put replacement.jsx (React) or .html above the button, then call again with the new text, consent and placement.bold: true (it is semibold). needs_review on styling means a rendered scan must confirm.',
+        'Pass the text exactly as rendered plus the plan terms. Example: {"text":"Renews monthly at $19.99 until you cancel.","price":19.99,"interval":"month","cancel_url":"https://acme.example/account/cancel","consent":{"checkbox":true,"prechecked":false}}.',
+        'If verdict is fail, put replacement.jsx (React) or .html above the button, then call again with the new text, consent and placement.bold: true. needs_review on styling means a rendered scan must confirm.',
     ].join('\n'),
     input: {
         text: z.string().min(1).max(5000).describe('The disclosure shown next to the purchase button, exactly as rendered.'),
@@ -1281,7 +1299,7 @@ const checkDisclosure = {
             body_font_size_px: z.number().min(4).max(96).optional(),
         }, 'placement')
             .optional()
-            .describe('Where and how the disclosure is shown (defaults: above the button, same page, 14px, high contrast).'),
+            .describe('Defaults: above the button, same page, 14px, high contrast.'),
         consent: strictObject({
             checkbox: z.boolean(),
             prechecked: z.boolean().optional(),
@@ -1289,7 +1307,8 @@ const checkDisclosure = {
             required: z.boolean().optional(),
         }, 'consent')
             .optional()
-            .describe('The consent checkbox, if the page has one. Omit when there is none.'),
+            .describe('The consent checkbox, if any.'),
+        checkout_type: z.enum(['own_page', 'stripe_checkout', 'payment_link']).optional().describe('Stripe-hosted: no box here'),
         jurisdictions: jurisdictions.optional(),
         as_of: asOf.optional(),
     },
@@ -1679,7 +1698,7 @@ const updateSite = {
     name: 'update_site',
     title: 'Update a site\'s settings (write)',
     description: [
-        'WRITE: updates a site — the fields plan tasks of change.type "config" ask for (their change.content is this tool\'s input): checkout_url, checkout_steps, test_account { login_url, email, password } (stored encrypted; the response echoes it without the password), name (the merchant name in generated legal copy), platform, jurisdictions, monitoring_interval_minutes, protection_level (minimum = legal floor only; balanced = + recommended suggestions, the default; maximum = + extras; only required items ever affect compliance).',
+        'WRITE: updates a site — the fields plan tasks of change.type "config" ask for (their change.content is this tool\'s input): checkout_url, checkout_steps, checkout_pages, test_account { login_url, email, password } (stored encrypted; the response echoes it without the password), name (the merchant name in generated legal copy), platform, jurisdictions, monitoring_interval_minutes, protection_level.',
         'The response is the site; check checkout.url / checkout.test_account to confirm. Then verify_task the task that asked for it.',
     ].join('\n'),
     input: {
@@ -1687,10 +1706,11 @@ const updateSite = {
         name: z.string().max(200).optional().describe('Merchant / brand name (used in generated disclosures).'),
         checkout_url: z.string().max(2048).optional().describe('Page with the Subscribe / Buy button.'),
         checkout_steps: z.array(z.record(z.string(), z.unknown())).max(20).optional().describe('Steps to reach the purchase button (clicks / fills), as in the API.'),
+        checkout_pages: z.array(z.record(z.string(), z.string())).max(4).optional().describe('[{url,plan}] per plan'),
         test_account: strictObject({
             login_url: z.string().max(2048),
             email: z.string().max(320),
-            password: z.string().max(200),
+            password: z.string().max(200).optional(),
             reactivate_url: z.string().max(2048).optional().describe('Test-only page that re-subscribes the test account.'),
         }, 'test_account')
             .optional()
@@ -1704,7 +1724,7 @@ const updateSite = {
     annotations: { ...write(false, true), title: 'Update site' },
     async run(args, { api }) {
         const site = await resolveSite(api, args.site);
-        const body = pick(args, ['name', 'checkout_url', 'checkout_steps', 'test_account', 'platform', 'jurisdictions', 'monitoring_interval_minutes', 'protection_level']);
+        const body = pick(args, ['name', 'checkout_url', 'checkout_steps', 'checkout_pages', 'test_account', 'platform', 'jurisdictions', 'monitoring_interval_minutes', 'protection_level']);
         if (!Object.keys(body).length)
             throw new ToolError('Pass at least one field to change (e.g. checkout_url, test_account, name).');
         const updated = await api.request('POST', `/v1/sites/${enc(site)}`, { body });
@@ -1832,9 +1852,13 @@ const listFindings = {
                 starting_after: args.starting_after,
             },
         });
+        // Round 34 (pilot 33 item 11, core-new-app: status=fail listed 0 while the plan said "2 fixes needed"): status is
+        // the engine's verdict; the fix count is the status label (a needs_review finding can need a fix).
+        const failNote = args.status === 'fail' && !list.data.length ? ' status=fail is the engine verdict only: a needs_review finding can still be counted as a fix (its label says "Needs a fix"). The fixes to make are the tasks of get_compliance_plan.' : '';
         return {
-            headline: `${list.data.length}${list.has_more ? '+' : ''} finding(s).`,
-            notes: list.data.map((f) => `${f.severity.toUpperCase()} ${f.id} [${f.compliance?.label ?? f.status}] ${f.check_id}: ${f.title}${f.requirements?.[0] ? ` [${f.requirements[0].citation}]` : ''}`),
+            headline: `${list.data.length}${list.has_more ? '+' : ''} finding(s).${failNote}`,
+            // Round 35 (pilot 34 item 7): each finding with what the plan says about it (the plan decides what is left to do).
+            notes: list.data.map((f) => `${f.severity.toUpperCase()} ${f.id} [${f.compliance?.label ?? f.status}] ${f.check_id}: ${f.title}${f.requirements?.[0] ? ` [${f.requirements[0].citation}]` : ''}${f.plan_task ? ` — plan: ${f.plan_task.label} (${f.plan_task.id})` : ''}`),
             data: list,
         };
     },
@@ -1858,7 +1882,7 @@ const getFinding = {
             ? await optional(api.request('GET', `/v1/findings/${enc(id)}/fix`, { query: pick(args, ['target', 'cancel_url', 'plan']) }))
             : { unavailable: 'This key has no fixes:read permission.' };
         return {
-            headline: `${finding.severity.toUpperCase()} ${finding.id} [${finding.compliance?.label ?? finding.status}] ${finding.check_id}: ${finding.title}`,
+            headline: `${finding.severity.toUpperCase()} ${finding.id} [${finding.compliance?.label ?? finding.status}] ${finding.check_id}: ${finding.title}${finding.plan_task ? ` — plan: ${finding.plan_task.label} (${finding.plan_task.id})` : ''}`,
             notes: [complianceBullet(finding.check_id, finding.compliance, finding.status, finding.title)].filter((x) => !!x),
             data: { finding, fix },
             next: findingNext(finding, nextActionOf(fix)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkbox-site/mcp",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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",
@@ -77,7 +77,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@checkbox-site/node": "^0.2.6",
+    "@checkbox-site/node": "^0.2.8",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "zod": "^4.6.7"
   }