@typeroll/mcp-server 0.45.109 → 0.45.111

package/dist/rest-reference.js

@@ -0,0 +1,200 @@
+// Every MCP tool is a thin wrapper around the REST API. This module runs each
+// tool against a recording HTTP client to find the REST calls behind it, so
+// the published REST reference is derived from the tools themselves and cannot
+// drift from them. Placeholder arguments name each input, for example
+// `{page_id}`, and appear as such in the recorded paths.
+import { z } from 'zod';
+import { TyperollClient } from './client.js';
+import { ALL_TOOLS, effectFor } from './server.js';
+/** Tools that read bundled documentation and never call the API. */
+export const LOCAL_TOOLS = new Set(['read_guide', 'list_skills', 'read_skill']);
+const BASE = 'https://portal.invalid';
+/** Valid example input for tools that validate more than placeholders satisfy. */
+const EXAMPLE_ARGS = {
+    add_recipe_schema: { page_id: '{page_id}', name: 'Pancakes', ingredients: ['Flour'], instructions: ['Mix'] },
+    add_event_schema: { page_id: '{page_id}', name: 'Launch', start_date: '2026-06-12T19:00:00+02:00' },
+    import_gsc_performance: { property: 'https://example.com/' },
+    update_migration_urls: { ids: ['{id}'], patch: { excluded: true } },
+    revoke_preview_link: { preview_url: `${'https://portal.invalid'}/preview/{siteId}/?t={token}` },
+};
+const SITE = '{siteId}';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function placeholder(name, schema) {
+    const def = schema?.def ?? schema?._zod?.def;
+    switch (def?.type) {
+        case 'optional':
+        case 'default':
+        case 'nullable':
+        case 'readonly':
+        case 'catch':
+        case 'prefault':
+        case 'nonoptional':
+            return placeholder(name, def.innerType);
+        case 'pipe': return placeholder(name, def.in);
+        case 'lazy': return placeholder(name, def.getter());
+        case 'string':
+            if (schema.format === 'url' || /url$/i.test(name))
+                return `https://example.com/${name}.png`;
+            if (schema.format === 'email' || /email$/i.test(name))
+                return `${name}@example.com`;
+            return `{${name}}`;
+        case 'number':
+        case 'int':
+        case 'bigint': return 1;
+        case 'boolean': return true;
+        case 'enum': return Object.values(def.entries)[0];
+        case 'literal': return def.values[0];
+        case 'union': return placeholder(name, def.options[0]);
+        case 'array': return [placeholder(name.replace(/s$/, ''), def.element)];
+        case 'object': return Object.fromEntries(Object.entries(def.shape).map(([key, value]) => [key, placeholder(key, value)]));
+        case 'record': return {};
+        default: return `{${name}}`;
+    }
+}
+function parameters(tool) {
+    if (!tool.inputSchema)
+        return [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = z.toJSONSchema(z.object(tool.inputSchema), { unrepresentable: 'any', io: 'input' });
+    const required = new Set(json.required ?? []);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const typeOf = (value) => value?.enum ? value.enum.map((item) => JSON.stringify(item)).join(' | ')
+        : value?.anyOf ? value.anyOf.map(typeOf).join(' | ')
+            : value?.type === 'array' ? `${typeOf(value.items)}[]`
+                : Array.isArray(value?.type) ? value.type.join(' | ') : value?.type ?? 'any';
+    return Object.entries(json.properties ?? {}).map(([name, value]) => ({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        name, type: typeOf(value), required: required.has(name), description: String(value?.description ?? ''),
+    }));
+}
+async function record(tool) {
+    const calls = [];
+    const fetchImpl = (async (input, init) => {
+        const url = new URL(String(input instanceof Request ? input.url : input));
+        // Only API calls are recorded; nothing leaves the process.
+        if (url.origin !== BASE)
+            return new Response('Not available while generating the reference', { status: 503 });
+        let body = [];
+        if (typeof init?.body === 'string') {
+            try {
+                const parsed = JSON.parse(init.body);
+                body = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? Object.keys(parsed) : [];
+            }
+            catch {
+                body = [];
+            }
+        }
+        calls.push({
+            method: (init?.method ?? 'GET').toUpperCase(),
+            path: decodeURIComponent(url.pathname),
+            query: [...new Set([...url.searchParams.keys()])],
+            body,
+        });
+        return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+    });
+    const client = new TyperollClient({ baseUrl: BASE, apiKey: 'typeroll_live_reference', fetchImpl });
+    const args = EXAMPLE_ARGS[tool.name] ?? Object.fromEntries(Object.entries(tool.inputSchema ?? {}).map(([name, schema]) => [name, placeholder(name, schema)]));
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = fetchImpl;
+    let timer;
+    try {
+        // A handler that polls stops being observed after its first calls.
+        await Promise.race([
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            tool.handler(args, { client, siteId: SITE }),
+            new Promise(resolve => { timer = setTimeout(resolve, 1000); }),
+        ]);
+    }
+    catch {
+        // A handler may reject the empty recorded response after its call; the call is what matters.
+    }
+    finally {
+        clearTimeout(timer);
+        globalThis.fetch = realFetch;
+    }
+    return calls;
+}
+export async function restReference() {
+    const entries = [];
+    for (const tool of ALL_TOOLS) {
+        if (LOCAL_TOOLS.has(tool.name))
+            continue;
+        const calls = await record(tool);
+        entries.push({
+            tool: tool.name, effect: effectFor(tool.name), description: tool.description,
+            site: calls.some(call => call.path.startsWith(`/api/v1/sites/${SITE}/`)), parameters: parameters(tool), calls,
+        });
+    }
+    return entries;
+}
+const AREA_NAMES = {
+    '': 'Site', access: 'Access', organizations: 'Organizations', sites: 'Sites', publishing: 'Organization publishing',
+    organization: 'Organization', developer: 'Developer Extensions',
+};
+function area(entry) {
+    const path = entry.calls[0]?.path ?? '';
+    const rest = entry.site ? path.slice(`/api/v1/sites/${SITE}/`.length) : path.replace(/^\/api\/(v1\/)?/, '');
+    const segment = rest.split('/')[0] ?? '';
+    const generic = segment.replace(/[-_]/g, ' ').replace(/^./, letter => letter.toUpperCase());
+    const name = entry.site ? (segment ? generic : 'Details') : AREA_NAMES[segment] ?? generic;
+    return entry.site ? `Site: ${name}` : name;
+}
+function where(parameter, call) {
+    if (call.path.includes(`{${parameter.name}}`))
+        return 'path';
+    if (call.query.includes(parameter.name))
+        return 'query';
+    if (call.body.includes(parameter.name))
+        return 'body';
+    return call.method === 'GET' || call.method === 'DELETE' ? 'query' : 'body';
+}
+/** Markdown text outside code spans must not open HTML tags. */
+const prose = (text) => text.split('`').map((part, index) => index % 2 ? part : part.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')).join('`');
+const cell = (text) => prose(text).replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim();
+/** The published reference: one section per REST call behind each MCP tool. */
+export function renderRestReference(entries) {
+    const groups = new Map();
+    for (const entry of entries) {
+        const key = area(entry);
+        groups.set(key, [...groups.get(key) ?? [], entry]);
+    }
+    const lines = [
+        '---',
+        'title: REST API reference',
+        'description: Every operation the MCP server offers, as the REST call behind it. Generated from the MCP tools, so both always match.',
+        '---',
+        '',
+        '<!-- Generated by `npm run gen:rest -w packages/mcp-server` from the MCP tool definitions. Do not edit by hand. -->',
+        '',
+        'Every MCP tool is a thin wrapper around one or more of these REST calls, so',
+        'anything an AI agent can do through MCP, a script can do through the API. This',
+        'page is generated from the tools and checked in CI, so it always matches them.',
+        'For authentication, organizations and examples, see',
+        '[Use the REST API](../../guides/rest-api/).',
+        '',
+        '- Base address: `https://app.typeroll.com` on Cloud, or your own portal host.',
+        '- `{siteId}` and other names in braces are path parameters.',
+        '- Send JSON bodies with `Content-Type: application/json`.',
+        '- **Permission** is the least role or key permission the call needs: `read`, `write` or `admin`.',
+        '- The MCP tool name is shown for each call, so agent instructions and scripts can use the same names.',
+        '',
+    ];
+    for (const name of [...groups.keys()].sort((a, b) => a.localeCompare(b))) {
+        lines.push(`## ${name}`, '');
+        for (const entry of groups.get(name)) {
+            lines.push(`### \`${entry.tool}\``, '');
+            for (const call of entry.calls) {
+                lines.push(`\`${call.method} ${call.path}\``, '');
+            }
+            lines.push(`Permission: \`${entry.effect}\``, '', prose(entry.description.trim()), '');
+            if (entry.parameters.length) {
+                lines.push('| Parameter | In | Type | Required | Description |', '| --- | --- | --- | --- | --- |');
+                for (const parameter of entry.parameters) {
+                    lines.push(`| \`${parameter.name}\` | ${where(parameter, entry.calls[0])} | ${cell(parameter.type)} | ${parameter.required ? 'yes' : 'no'} | ${cell(parameter.description)} |`);
+                }
+                lines.push('');
+            }
+        }
+    }
+    return lines.join('\n');
+}

package/dist/server.js

@@ -45,6 +45,40 @@ import { compactTools, COMPACT_INSTRUCTIONS } from './compact-tools.js';
 /** What permission a tool needs to run. Maps onto the share model: a
  *  read-shared site can `read`-list but cannot mutate. Mode `write` is the
  *  default — applied to anything that isn't trivially side-effect-free. */
+/** Every MCP tool, in registration order. The REST reference is generated from it. */
+export const ALL_TOOLS = [
+    ...skillTools,
+    ...siteTools,
+    ...pageTools,
+    ...structuredDataTools,
+    ...ownerReviewTools,
+    ...partialTools,
+    ...blockTypeTools,
+    ...pageBlockTools,
+    ...workingCopyTools,
+    ...contentTypeTools,
+    ...pageTemplateTools,
+    ...mediaTools,
+    ...redirectTools,
+    ...styleTools,
+    ...reusableBlockTools,
+    ...migrationTools,
+    ...formTools,
+    ...emailTools,
+    ...settingsTools,
+    ...appTools,
+    ...extensionTools,
+    ...developerExtensionTools,
+    ...searchTools,
+    ...bulkTools,
+    ...readinessTools,
+    ...versionTools,
+    ...deployTools,
+    ...previewTools,
+    ...domainTools,
+    ...workflowTools,
+    ...accessTools,
+];
 const PERM_RANK = { read: 0, write: 1, admin: 2 };
 /**
  * Classify a tool by name into the minimum permission needed. We keep this
@@ -55,7 +89,7 @@ const PERM_RANK = { read: 0, write: 1, admin: 2 };
  * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*` / `check_*` / `find_*`; everything else
  * mutates.
  */
-function effectFor(name) {
+export function effectFor(name) {
     if (name === 'page_completeness' || name === 'resolve_page_url')
         return 'read';
     if (name === 'guide_publishing_domain_change'
@@ -107,6 +141,8 @@ function effectFor(name) {
         || name === 'prepare_organization_media_storage'
         || name === 'save_organization_media_access'
         || name === 'set_email_settings'
+        || name === 'set_form_spam_protection'
+        || name === 'delete_form_spam_protection'
         || name === 'delete_email_settings'
         || name === 'send_test_email'
         || name === 'retry_form_intake_notification'
@@ -207,39 +243,7 @@ export function buildServer(options) {
         capabilities: { tools: {} },
         instructions: (options.selection ? 'First ask which site to work on. List sites, confirm its organization/name with the user, then call select_site. Carry the returned site_context on every site call. Never search across sites or silently switch sites or versions. Select a new context to switch. Organization administration requires an explicit organization_id and the user’s permission. ' : '') + (options.toolMode === 'compact' ? COMPACT_INSTRUCTIONS : SERVER_INSTRUCTIONS),
     });
-    const allTools = [
-        ...skillTools,
-        ...siteTools,
-        ...pageTools,
-        ...structuredDataTools,
-        ...ownerReviewTools,
-        ...partialTools,
-        ...blockTypeTools,
-        ...pageBlockTools,
-        ...workingCopyTools,
-        ...contentTypeTools,
-        ...pageTemplateTools,
-        ...mediaTools,
-        ...redirectTools,
-        ...styleTools,
-        ...reusableBlockTools,
-        ...migrationTools,
-        ...formTools,
-        ...emailTools,
-        ...settingsTools,
-        ...appTools,
-        ...extensionTools,
-        ...developerExtensionTools,
-        ...searchTools,
-        ...bulkTools,
-        ...readinessTools,
-        ...versionTools,
-        ...deployTools,
-        ...previewTools,
-        ...domainTools,
-        ...workflowTools,
-        ...accessTools,
-    ];
+    const allTools = ALL_TOOLS;
     // SDK's registerTool has deeply-nested generics we can't unify across a
     // heterogeneous tool list at compile time — same shrug as stdio's index.ts.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/tools/deploy.js

@@ -42,7 +42,7 @@ export const deployTools = [
     },
     {
         name: 'get_deploy_status',
-        description: "Status of a single deploy job. Optional top-level build_progress reports the exact task status, attempt, step and completed/total files; not an overall percentage or ETA. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.targets and job.production, when present, record where the publication was admitted to publish and whether that included a live domain. job.status is one of queued | running | succeeded | failed. On a failed build, job.error names the failed step and the cause the step printed, job.failure.code is the reported code (e.g. media_build_process_exit_1) and job.failure.diagnostic holds { cause, lines } (the last 40 lines that step printed, credentials removed). On the Cloudflare build engine job.failure.provider_log also holds { step, build_id, summary, lines } from the provider's build log (last 60 lines). Read them before retrying; retrying does not fix a cause that is in the content or the build engine. job.warnings, when present, lists non-blocking findings of a deploy that still ran, for example a media file left out of the publication because it could not be published safely (an SVG that could not be sanitized); report them to the user. Polling cadence: ~5s for queued/running. job.render_report, when present, reports actual HTML mode (full/partial), rendered, reused, total and removed route counts plus a fallback reason. From Core 0.2.17, custom blocks and consumed image metadata are tracked per route; older caches require one full build. It does not measure media or provider startup savings. job.coordinator, when present, reports the last completed CMS phase and duration_ms for that attempt; external build waiting is excluded. Keep observing the same job across checkpoints; do not trigger duplicate deploys. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
+        description: "Status of a single deploy job. Optional top-level build_progress reports the exact task status, attempt, step and completed/total files; not an overall percentage or ETA. Media preparation runs in windows of about 12 minutes that each save their position, so attempt rises in a healthy build: media_continuations counts those planned windows, retries counts failed runs started again, and deadline is when the build stops for good. Do not cancel while completed still rises. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.targets and job.production, when present, record where the publication was admitted to publish and whether that included a live domain. job.status is one of queued | running | succeeded | failed. On a failed build, job.error names the failed step and the cause the step printed, job.failure.code is the reported code (e.g. media_build_process_exit_1) and job.failure.diagnostic holds { cause, lines } (the last 40 lines that step printed, credentials removed). On the Cloudflare build engine job.failure.provider_log also holds { step, build_id, summary, lines } from the provider's build log (last 60 lines). Read them before retrying; retrying does not fix a cause that is in the content or the build engine. job.warnings, when present, lists non-blocking findings of a deploy that still ran, for example a media file left out of the publication because it could not be published safely (an SVG that could not be sanitized); report them to the user. Polling cadence: ~5s for queued/running. job.render_report, when present, reports actual HTML mode (full/partial), rendered, reused, total and removed route counts plus a fallback reason. From Core 0.2.17, custom blocks and consumed image metadata are tracked per route; older caches require one full build. It does not measure media or provider startup savings. job.coordinator, when present, reports the last completed CMS phase and duration_ms for that attempt; external build waiting is excluded. Keep observing the same job across checkpoints; do not trigger duplicate deploys. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
         inputSchema: { job_id: z.string(), include_provider: z.boolean().optional().describe('Also read the exact Git commit and Cloudflare build stages for a customer Git publication. Does not return build secrets.') },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `deploys/${encodeURIComponent(args.job_id)}`);

package/dist/tools/domain.js

@@ -234,7 +234,7 @@ export const domainTools = [
         name: 'set_publishing_domains',
         description: 'Save future website, redirect and media hosts before preparing a deployment. Normal trigger_deploy continues updating the current or temporary address, even while future hosts await validation. Shortly before changing DNS, explicitly call prepare_publishing_domain_change to publish the last published snapshot again with these hosts. That explicit publication replaces main before DNS changes. Later normal publications retain its new origins and refresh the DNS approval receipt; no second build is needed to switch DNS. Requires the current revision from read_publishing_domains. This does not publish content or change traffic DNS. Choose external DNS when your agent manages Cloudflare independently. redirect_hosts (for example www.example.com when example.com is the website host) answer 301 to the website host, keeping path and query, through a Single Redirect rule in the host\'s Cloudflare zone; they are switched and verified with the website. The response includes host_checks: resolve its blockers before preparing.',
         inputSchema: {
-            revision: z.string(), website_host: z.string().nullable(), media_host: z.string().nullable(),
+            revision: z.string(), website_host: z.string().nullable(), media_host: z.string().nullable().describe('Optional site media host, such as media.<site domain>, so image addresses do not show the organization media domain. Its domain must be in the organization\'s connected Cloudflare account. Null uses the organization\'s shared media host.'),
             confirm_rebuild: z.boolean().optional().describe('Legacy input; Core 0.2.116+ does not require confirmation to save inert future addresses.'),
             media_path_prefix: z.string().optional().describe('Empty on a separate media host; /media when using the website host.'),
             redirect_hosts: z.array(z.string()).max(4).optional().describe('Hostnames that redirect permanently to website_host, such as www.example.com. Omit or send [] for none.'),

package/dist/tools/forms.js

@@ -63,6 +63,27 @@ export const formTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'get_form_spam_protection',
+        description: "Read the site's Cloudflare Turnstile setup for forms: provider, public site_key, secret_key masked as { set: true }, and enforced_forms (forms whose published pages have sent a verified Turnstile answer and now require one). provider is null when Turnstile is off. Admin permission required.",
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'integrations/form-spam-protection'))),
+    },
+    {
+        name: 'set_form_spam_protection',
+        description: "Turn on Cloudflare Turnstile for every form on the site, against bots that fill in forms in a real browser. First create a Turnstile widget in the site owner's Cloudflare dashboard (Turnstile → Add widget, mode Managed, with the site's website hostnames), then pass its site key and secret key. The secret is checked with Cloudflare, encrypted and never returned; omit secret_key to keep the stored one for the same site_key. Publish the site afterwards: forms render the widget only after publishing. Each form keeps accepting submissions without Turnstile until its republished pages send the first verified answer, then requires it. Forms that post to an app or Extension are not covered. Admin permission required.",
+        inputSchema: {
+            site_key: z.string().min(10).describe('The Turnstile widget\'s site key (public).'),
+            secret_key: z.string().min(10).optional().describe('The Turnstile widget\'s secret key. Required for a new site_key.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.put(siteId, 'integrations/form-spam-protection', {
+            provider: 'turnstile', site_key: args.site_key, ...(args.secret_key !== undefined ? { secret_key: args.secret_key } : {}),
+        }))),
+    },
+    {
+        name: 'delete_form_spam_protection',
+        description: "Turn off Turnstile for the site's forms and delete the stored secret. Submissions are accepted without Turnstile at once; republish to remove the widget from pages. Admin permission required.",
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.del(siteId, 'integrations/form-spam-protection'))),
+    },
     {
         name: 'get_form_capabilities',
         description: 'List the action types a form can run after a submission (core "email" and "webhook" plus types provided by installed apps) and the prefill sources, each with its config field schema — the same choices as the portal\'s Forms editor. Read this before writing `actions` with create_form/update_form. Admin permission required.',

package/dist/tools/media.js

@@ -44,7 +44,7 @@ export const mediaTools = [
     },
     {
         name: 'get_media_preparation',
-        description: 'Read background image preparation progress, including the build_job_id of a running preparation job on the organization build engine. unreadable_media lists library images whose stored file does not decode; preparation skips them, so upload a working copy. Originals and prepared draft variants remain private. Requires site access.',
+        description: 'Read background image preparation progress, including the build_job_id of a running preparation job on the organization build engine. unreadable_media lists library images whose stored file does not decode; preparation skips them, so upload a working copy. A round stopped by a passing condition (engine update, runner not started, step time limit, interrupted transfer) never ends the job: it starts again after 5 minutes, doubling up to an hour, shown as retry { attempt, next_at } with error_code. When the job fails, error names the cause, with error_code and failed_build_task. Originals and prepared draft variants remain private. Requires site access.',
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'media/preparation'))),
     },

package/dist/version.js

@@ -8,4 +8,4 @@
 //
 // Keep it in lockstep with package.json: tests/version.test.ts asserts
 // VERSION === package.json.version, so a bump that forgets this line fails CI.
-export const VERSION = '0.45.109';
+export const VERSION = '0.45.111';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@typeroll/mcp-server",
   "mcpName": "io.github.Typeroll/typeroll",
-  "version": "0.45.109",
+  "version": "0.45.111",
   "description": "Typeroll CMS MCP server \u2013 connect AI agents to the REST API to manage content and publish static websites.",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,8 @@
     "workspace-templates"
   ],
   "scripts": {
-    "gen": "node scripts/embed-content.mjs",
+    "gen": "node scripts/embed-content.mjs && npm run gen:rest",
+    "gen:rest": "UPDATE_REST_REFERENCE=1 vitest run tests/rest-reference.test.ts",
     "prebuild": "node scripts/embed-content.mjs --clean",
     "build": "tsc -p .",
     "typecheck": "tsc --noEmit",

package/skills/tr-forms.md

@@ -213,6 +213,11 @@ across pages. Other hidden fields always send their `default`.
 ## Pitfalls
 
 - Do not hand-write a form, token, honeypot, or submit script.
+- Spam from bots that use a real browser gets past the token, honeypot and rate
+  limits. Turn on Cloudflare Turnstile with `set_form_spam_protection` (a widget
+  from the site owner's Cloudflare dashboard), then publish the site. A site
+  admin can do the same in the portal under Forms → Spam protection; never ask
+  them to paste a secret key into the chat if they prefer that route.
 - Do not put a raw `<script>` in page HTML; the sanitizer removes it.
 - Do not drop existing actions by accident: `actions` replaces the list.
 - Do not send every submitted field to a webhook by default; choose the