@checkbox-site/mcp 0.1.0 → 0.2.0

package/dist/unknown-args.d.ts

@@ -0,0 +1,22 @@
+/** Levenshtein distance (small inputs: argument names). */
+export declare function editDistance(a: string, b: string): number;
+/** The known argument an unknown one most likely means, if any is close enough. */
+export declare function closestArgument(unknown: string, known: readonly string[]): string | undefined;
+/**
+ * Round 21 (pilot 20 item 5): an unknown argument that is an alias or a near spelling of a known one (stripe_params,
+ * emial), as opposed to a field this server does not know yet (plan_variant): those are forwarded to the API, which
+ * refuses what it does not know either. A name that only contains a known one is not a misspelling here.
+ */
+export declare function likelyMisspelling(unknown: string, known: readonly string[]): string | undefined;
+/** The error an agent reads for unknown arguments: each with a suggestion, then every argument the tool accepts. */
+export declare function unknownArgumentsMessage(tool: string, keys: readonly string[], known: readonly string[]): string;
+/**
+ * Pilot round 13: an unknown key inside a nested object (plans[].price_cents, merchant.name) is refused, naming the
+ * closest field. `hints` maps keys to a fuller suggestion for this object (e.g. price → amount in minor units).
+ */
+export declare function nestedUnknownMessage(where: string, keys: readonly string[], known: readonly string[], hints?: Readonly<Record<string, string>>): string;
+/**
+ * Object params that word the unknown-keys error on both zod majors: the monorepo builds against zod 3 (`errorMap`),
+ * the published server ships zod 4 (`error`). Other issues keep zod's own message.
+ */
+export declare function unknownKeysParams(message: (keys: string[]) => string): any;

package/dist/unknown-args.js

@@ -0,0 +1,119 @@
+// Round 12 (change-guard): MCP tools registered their input without .strict(), so zod dropped unknown arguments.
+// verify_task with `stripe_params` (a misspelled stripe_checkout_session) found no params, judged the Checkout Sessions
+// read from Stripe and read PASSED. Unknown arguments are now refused with the closest known name.
+/** Names agents use for an argument, mapped to the real one (checked before the edit distance). */
+const ALIASES = Object.freeze({
+    stripe_params: 'stripe_checkout_session',
+    checkout_params: 'stripe_checkout_session',
+    session_params: 'stripe_checkout_session',
+    checkout_session: 'stripe_checkout_session',
+    stripe_session: 'stripe_checkout_session',
+    session: 'stripe_checkout_session',
+    sessions: 'stripe_checkout_sessions',
+    task_id: 'task',
+    site_id: 'site',
+    plan_terms: 'terms',
+    merchant: 'terms',
+    terms: 'merchant',
+    body: 'text',
+    page_html: 'html',
+    price: 'price_id',
+    name: 'merchant_name',
+    brand: 'merchant_name',
+    price_cents: 'amount',
+    amount_cents: 'amount',
+    unit_amount: 'amount',
+    trial_period_days: 'trial_days',
+    billing_interval: 'interval',
+});
+/** Levenshtein distance (small inputs: argument names). */
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const up = prev[j];
+            prev[j] = Math.min(up + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = up;
+        }
+    }
+    return prev[b.length];
+}
+/** The known argument an unknown one most likely means, if any is close enough. */
+export function closestArgument(unknown, known) {
+    const k = unknown.toLowerCase();
+    const alias = ALIASES[k];
+    if (alias && known.includes(alias))
+        return alias;
+    let best;
+    for (const name of known) {
+        const d = editDistance(k, name.toLowerCase());
+        if (!best || d < best.d)
+            best = { name, d };
+    }
+    if (best && best.d <= Math.max(2, Math.floor(best.name.length / 3)))
+        return best.name;
+    // A prefix / containment match ("stripe" → stripe_checkout_session) when exactly one known name fits.
+    const contains = known.filter((n) => n.length >= 4 && (n.includes(k) || k.includes(n)));
+    return contains.length === 1 ? contains[0] : undefined;
+}
+/**
+ * Round 21 (pilot 20 item 5): an unknown argument that is an alias or a near spelling of a known one (stripe_params,
+ * emial), as opposed to a field this server does not know yet (plan_variant): those are forwarded to the API, which
+ * refuses what it does not know either. A name that only contains a known one is not a misspelling here.
+ */
+export function likelyMisspelling(unknown, known) {
+    const k = unknown.toLowerCase();
+    const alias = ALIASES[k];
+    if (alias && known.includes(alias))
+        return alias;
+    let best;
+    for (const name of known) {
+        const d = editDistance(k, name.toLowerCase());
+        if (!best || d < best.d)
+            best = { name, d };
+    }
+    return best && best.d <= Math.max(2, Math.floor(best.name.length / 3)) ? best.name : undefined;
+}
+/** The error an agent reads for unknown arguments: each with a suggestion, then every argument the tool accepts. */
+export function unknownArgumentsMessage(tool, keys, known) {
+    const parts = keys.map((key) => {
+        const hint = closestArgument(key, known);
+        return `unknown argument \`${key}\`${hint ? `; did you mean \`${hint}\`?` : ''}`;
+    });
+    return `${parts.join('. ')}. Nothing was checked. ${tool} accepts: ${known.join(', ')}.`;
+}
+/**
+ * Pilot round 13: an unknown key inside a nested object (plans[].price_cents, merchant.name) is refused, naming the
+ * closest field. `hints` maps keys to a fuller suggestion for this object (e.g. price → amount in minor units).
+ */
+export function nestedUnknownMessage(where, keys, known, hints = {}) {
+    const parts = keys.map((key) => {
+        const hint = hints[key.toLowerCase()] ?? closestArgument(key, known);
+        return `unknown field \`${where}.${key}\`${hint ? `; did you mean \`${where}.${hint}\`?` : ''}`;
+    });
+    return `${parts.join('. ')}. Nothing was changed. ${where} accepts: ${known.join(', ')}.`;
+}
+/**
+ * Object params that word the unknown-keys error on both zod majors: the monorepo builds against zod 3 (`errorMap`),
+ * the published server ships zod 4 (`error`). Other issues keep zod's own message.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function unknownKeysParams(message) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pick = (issue) => (issue?.code === 'unrecognized_keys' ? message(issue.keys) : undefined);
+    return {
+        // zod 3
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        errorMap: (issue, ctx) => {
+            const m = pick(issue);
+            return m !== undefined ? { message: m } : ctx ? { message: ctx.defaultError } : undefined;
+        },
+        // zod 4 (undefined falls through to the default message)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        error: (issue) => pick(issue),
+    };
+}

package/dist/version-check.d.ts

@@ -0,0 +1,22 @@
+/** Response header on every /v1 response: the oldest @checkbox-site/mcp the API is written for. */
+export declare const MCP_MIN_VERSION_HEADER = "checkbox-mcp-minimum-version";
+/**
+ * The oldest @checkbox-site/mcp the API is written for. Raise it (with SERVER_VERSION) when the API adds arguments or
+ * operations that next_action / task text tells agents to use.
+ */
+export declare const MCP_MINIMUM_VERSION = "0.2.0";
+/** How a person updates the local server (what the README's config runs). */
+export declare const MCP_UPDATE_COMMAND = "npx -y @checkbox-site/mcp@latest";
+/** Compares dotted versions (1.10.0 > 1.9.0; a pre-release suffix is ignored). Negative when a < b. */
+export declare function compareVersions(a: string, b: string): number;
+/** The words an agent reads when this server is older than the API expects; null when it is not (or unknown). */
+export declare function outdatedNotice(current: string, minimum: string | null | undefined): string | null;
+/** Remembers the newest minimum version the API sent (headers of any response). */
+export declare class MinimumVersionTracker {
+    #private;
+    get minimum(): string | undefined;
+    /** Reads the header from a fetch Headers object or a plain lower-case record. */
+    observe(headers: {
+        get(name: string): string | null;
+    } | Record<string, string | undefined> | undefined | null): void;
+}

package/dist/version-check.js

@@ -0,0 +1,50 @@
+// Round 21 (pilot 20 item 5: testers ran @checkbox-site/mcp 0.1.1 from npm against an API that named arguments and
+// operations 0.1.1 does not have, and nothing told them to update). Every /v1 response says which MCP server version
+// the API expects (MCP_MIN_VERSION_HEADER); a local server older than that tells the agent, with the update command.
+/** Response header on every /v1 response: the oldest @checkbox-site/mcp the API is written for. */
+export const MCP_MIN_VERSION_HEADER = 'checkbox-mcp-minimum-version';
+/**
+ * The oldest @checkbox-site/mcp the API is written for. Raise it (with SERVER_VERSION) when the API adds arguments or
+ * operations that next_action / task text tells agents to use.
+ */
+export const MCP_MINIMUM_VERSION = '0.2.0';
+/** How a person updates the local server (what the README's config runs). */
+export const MCP_UPDATE_COMMAND = 'npx -y @checkbox-site/mcp@latest';
+/** Compares dotted versions (1.10.0 > 1.9.0; a pre-release suffix is ignored). Negative when a < b. */
+export function compareVersions(a, b) {
+    const parts = (v) => v.trim().replace(/^v/i, '').split(/[-+]/)[0].split('.').map((x) => Number.parseInt(x, 10) || 0);
+    const pa = parts(a);
+    const pb = parts(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d)
+            return d;
+    }
+    return 0;
+}
+const VERSION_RE = /^v?\d+(?:\.\d+){0,3}(?:[-+][\w.]+)?$/;
+/** The words an agent reads when this server is older than the API expects; null when it is not (or unknown). */
+export function outdatedNotice(current, minimum) {
+    const min = (minimum ?? '').trim();
+    if (!min || !VERSION_RE.test(min) || !VERSION_RE.test(current) || compareVersions(current, min) >= 0)
+        return null;
+    return `Your Checkbox MCP server is ${current}; the Checkbox API expects ${min} or newer, so arguments and operations its next steps name may be missing here. Ask the human to update it: in the MCP client config run \`${MCP_UPDATE_COMMAND}\` (then restart the client), or connect the remote server https://app.checkbox.site/mcp instead. Until then, call_api reaches any operation.`;
+}
+/** Remembers the newest minimum version the API sent (headers of any response). */
+export class MinimumVersionTracker {
+    #minimum;
+    get minimum() {
+        return this.#minimum;
+    }
+    /** Reads the header from a fetch Headers object or a plain lower-case record. */
+    observe(headers) {
+        if (!headers)
+            return;
+        const raw = typeof headers.get === 'function' ? headers.get(MCP_MIN_VERSION_HEADER) : headers[MCP_MIN_VERSION_HEADER];
+        const v = (raw ?? '').trim();
+        if (!v || !VERSION_RE.test(v))
+            return;
+        if (!this.#minimum || compareVersions(v, this.#minimum) > 0)
+            this.#minimum = v;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkbox-site/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Checkbox MCP server: subscription-law compliance tools for AI agents (remote at https://app.checkbox.site/mcp, or local stdio).",
   "keywords": [
     "subscription",
@@ -64,7 +64,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@checkbox-site/node": "^0.1.0",
+    "@checkbox-site/node": "^0.2.0",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "zod": "^4.6.7"
   }