@typeroll/mcp-server 0.45.43 → 0.45.45

package/dist/tools/page-blocks.js

@@ -1,10 +1,8 @@
-// Page-block mutation tools. Five primitives (get/add/update/move/remove)
-// plus a one-shot HTML→blocks converter. All target the active version
-// (override with `version`).
+// Page-block mutation tools: get/add/update/move/remove and friends. All
+// target the active version (override with `version`).
 //
-// The AI agent uses these to author block-mode pages directly. For
-// HTML-mode pages, `convert_page_to_blocks` returns a preview only.
-// It never writes. A person accepts that preview in the page editor.
+// The AI agent uses these to author block-mode pages directly. Typeroll does
+// not convert HTML into blocks; block pages are built with blocks.
 import { z } from 'zod';
 import { ok, withErrorBoundary, versionParam } from './helpers.js';
 const blockSchema = z.object({
@@ -193,7 +191,7 @@ export const pageBlockTools = [
     },
     {
         name: 'set_page_mode',
-        description: 'Safely switch a page\'s content_mode between "blocks" and "html". Always snapshots a revision before the flip so the previous state is restorable. HTML → blocks does not convert or rewrite the body. Blocks → HTML drops the block tree (the revision retains it). Prefer this over `update_page patch={content_mode}` because that bypasses snapshotting. Automatic HTML-to-blocks conversion is preview-only; a person accepts it in the page editor.',
+        description: 'Safely switch a page\'s content_mode between "blocks" and "html". Always snapshots a revision before the flip so the previous state is restorable. HTML → blocks does not convert or rewrite the body. Blocks → HTML drops the block tree (the revision retains it). Prefer this over `update_page patch={content_mode}` because that bypasses snapshotting. Typeroll does not convert HTML into blocks: after switching to blocks, build the content with blocks.',
         inputSchema: {
             page_id: z.string(),
             to: z.enum(['blocks', 'html']).describe('Target mode.'),
@@ -204,30 +202,4 @@ export const pageBlockTools = [
             return ok(res);
         }),
     },
-    {
-        name: 'convert_page_to_blocks',
-        description: 'Preview a heuristic conversion of a page\'s html_content into a block tree. Always returns the proposal, including unconverted text, classes and markup, and does not write. A person accepts the preview in the page editor. This tool cannot change content_mode or replace the body.',
-        inputSchema: {
-            page_id: z.string(),
-            version: versionParam,
-        },
-        handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert`, { dry_run: true }, v(args.version));
-            return ok(res);
-        }),
-    },
-    {
-        name: 'convert_prose_block',
-        description: 'Turn one text block (core/prose) into separate blocks: headings (a classed label above a heading becomes its eyebrow), paragraphs, lists, images and buttons. Use it when a text block holds headings, classed HTML or media that should be editable and styled with named styles. Call without `accept` to preview (nothing is written); review `converted`, `notes` and `unconverted`, then call again with `accept` set to the preview\'s `fingerprint`. Writes the page draft (working copy) like other block edits. Pages only.',
-        inputSchema: {
-            page_id: z.string(),
-            block_id: z.string(),
-            accept: z.string().optional().describe('The fingerprint from a preview of this same block. Omit to preview.'),
-            version: versionParam,
-        },
-        handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert-prose`, { block_id: args.block_id, ...(args.accept ? { accept: args.accept } : {}) }, v(args.version));
-            return ok(res);
-        }),
-    },
 ];

package/dist/tools/pages.js

@@ -1,7 +1,10 @@
 // Pages tools. Read + write + batch + blocks-view + preview.
 import { z } from 'zod';
-import { ok, withErrorBoundary, versionParam } from './helpers.js';
+import { ok, withErrorBoundary, versionParam, writeAuthority } from './helpers.js';
 const answerSources = z.record(z.object({ source_url: z.string().url().optional(), import_run_id: z.string().max(200).optional() }).strict()).optional().describe('Evidence per schema leaf path. Actor and timestamp are always assigned by the server; unchanged answers are not confirmed.');
+function authorityBody(args) {
+    return args.override_reason ? { override_reason: args.override_reason } : {};
+}
 function v(version) {
     return version ? { version } : undefined;
 }
@@ -108,6 +111,7 @@ export const pageTools = [
             template: z.string().nullable().optional().describe('Allowed Page template ID; null uses the content type default.'),
             image_sizes_default: z.string().optional().describe('Per-page default `sizes` for responsive images (e.g. "(max-width: 640px) 360px, 560px"). Overrides the site setting; a per-<img> `sizes` attr still wins. Set when this page\'s images render narrower than the generic default so the browser stops over-fetching.'),
             custom_css: z.string().optional().describe('Per-page CSS, injected into <head> as a <style> AFTER the site-level custom_css (so it overrides site styling). This is the RIGHT home for page-specific styling — page metadata, not content. Put a page\'s <style> here instead of stuffing it into a core/html block (which is opaque and un-editable in the visual editor). Syntax errors refuse the write; target s-<style> classes or block custom_class rather than [data-block]/.block-* platform markup.'),
+            ...writeAuthority,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -168,11 +172,12 @@ export const pageTools = [
             })
                 .passthrough(),
             answer_sources: answerSources,
+            ...writeAuthority,
             save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call — use for pre-approved or batch changes. Without it, changes stay in the unsaved draft until commit_working_copy.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.patch, ...(args.answer_sources ? { answer_sources: args.answer_sources } : {}), ...(args.save ? { save: true } : {}) }, v(args.version));
+            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.patch, ...(args.answer_sources ? { answer_sources: args.answer_sources } : {}), ...authorityBody(args), ...(args.save ? { save: true } : {}) }, v(args.version));
             return ok(res);
         }),
     },
@@ -183,11 +188,12 @@ export const pageTools = [
             page_id: z.string(),
             page: z.object({ title: z.string().min(1) }).passthrough(),
             answer_sources: answerSources,
+            ...writeAuthority,
             save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call — use for pre-approved or batch changes. Without it, changes stay in the unsaved draft until commit_working_copy.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.page, ...(args.answer_sources ? { answer_sources: args.answer_sources } : {}), ...(args.save ? { save: true } : {}) }, v(args.version));
+            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.page, ...(args.answer_sources ? { answer_sources: args.answer_sources } : {}), ...authorityBody(args), ...(args.save ? { save: true } : {}) }, v(args.version));
             return ok(res);
         }),
     },
@@ -201,6 +207,7 @@ export const pageTools = [
                 patch: z.record(z.unknown()),
                 save: z.boolean().optional(),
                 answer_sources: answerSources,
+                ...writeAuthority,
             }))
                 .min(1)
                 .max(200),
@@ -280,7 +287,7 @@ export const pageTools = [
     // the block-tree mutation tools (add/update/move/remove/convert).
     {
         name: 'get_page_preview',
-        description: "Get the WHOLE page rendered as one self-contained HTML document — header partial + block-rendered body + footer partial, with the site's settings CSS variables, global styles, and the tree-shaken block-CSS bundle all inlined, exactly as deployed. This is the single artifact for UNDERSTANDING what a page looks like and how its CSS actually cascades (get_page_blocks gives the editable block tree; this gives the rendered result). Returns { rendered_html, internal_links[] }. Pass annotate:true to tag every element with data-block-id + data-block-type so you can map the rendered HTML back to the block to edit. For a clickable preview URL use get_preview_link instead.",
+        description: "Get the WHOLE page rendered as one self-contained HTML document — header partial + block-rendered body + footer partial, with the site's settings CSS variables, global styles, the tree-shaken block-CSS bundle, block JavaScript, the Extension runtime and the cookie-consent banner all included, exactly as the portal Preview shows it. This is the single artifact for UNDERSTANDING what a page looks like and how its CSS actually cascades (get_page_blocks gives the editable block tree; this gives the rendered result). Returns { rendered_html, internal_links[] }. Pass annotate:true to tag every element with data-block-id + data-block-type so you can map the rendered HTML back to the block to edit. For a clickable preview URL use get_preview_link instead.",
         inputSchema: {
             page_id: z.string(),
             annotate: z

package/dist/tools/partials.js

@@ -118,7 +118,7 @@ export const partialTools = [
     },
     {
         name: 'find_pages_using_block',
-        description: 'Pages that embed a given block via <x-include name="…">. For partial_id "header" or "footer" returns the full page list (they are auto-injected on every page). Use this to know the blast radius before editing a shared block.',
+        description: 'What references a global block, saved or in a draft: `pages` (core/global_block or <x-include name="…">), `templates` (page templates) and `global_blocks` (header, footer and other global blocks that nest it; a header or footer means every page). For partial_id "header" or "footer" returns the full page list (they are auto-injected on every page). Use this to know the blast radius before editing a shared block.',
         inputSchema: {
             partial_id: z.string(),
             version: versionParam,

package/dist/tools/reusable-blocks.js

@@ -24,7 +24,7 @@ export const reusableBlockTools = [
     },
     {
         name: 'detach_global_block',
-        description: 'Replace a core/global_block reference on a page with an editable copy of the global block\'s blocks. Later edits to the global block no longer reach this page. Writes the page draft.',
+        description: 'Replace a core/global_block reference on a page with an editable copy of the global block\'s blocks. Copies the global block\'s unsaved draft on this version when it has one (what the editors show), otherwise the saved global block; `copied_from` says which. Later edits to the global block no longer reach this page. Writes the page draft.',
         inputSchema: {
             page_id: z.string(),
             block_id: z.string().describe('The id of the core/global_block reference block.'),

package/dist/tools/settings.js

@@ -1,10 +1,10 @@
-// Settings tools. scripts_head, scripts_body_end, and custom_css ARE
-// writable via the public API (as of mcp-server 0.4.x) — the v1 route
-// accepts them and they round-trip through read_site_settings. Same
-// trust model as user-authored block-type JS: a bearer-token caller
-// takes responsibility for what they ship. The portal chat AI still
-// doesn't expose these fields, so conversation-driven assistants can't
-// smuggle scripts in.
+// Settings tools. update_site_settings accepts every field the portal
+// Settings form does — including scripts_head, scripts_body_end,
+// custom_css, cookie-consent scripts, default_og_image, twitter_handle,
+// organization (JSON-LD) and staging_url — with the same admin permission
+// the portal requires. A bearer-token caller takes responsibility for what
+// it ships, exactly as a site admin in the portal does. (The in-portal chat
+// assistant has its own, narrower settings tool; that is unrelated to MCP.)
 import { z } from 'zod';
 import { ok, withErrorBoundary, versionParam } from './helpers.js';
 function v(version) {
@@ -13,7 +13,7 @@ function v(version) {
 export const settingsTools = [
     {
         name: 'read_site_settings',
-        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, language, robots_txt, image_sizes_default, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
+        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, default_og_image, twitter_handle, organization (JSON-LD), language, robots_txt, image_sizes_default, cookie_consent, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, `urls` (including `urls.staging`, the site's staging_url) and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
         inputSchema: {
             version: versionParam,
         },
@@ -24,12 +24,14 @@ export const settingsTools = [
     },
     {
         name: 'update_site_settings',
-        description: 'Patch site settings, including responsive breakpoints for block layouts and visibility. Only the fields you pass change. ' +
+        description: 'Patch site settings, including responsive breakpoints for block layouts and visibility. Accepts everything the portal Settings form does. Requires admin permission on the site, as in the portal. Only the fields you pass change. ' +
             'Pass fields at the TOP LEVEL of the object — do NOT wrap in a "settings" key. ' +
             'Example: {"site_name": "Acme", "colors": {"primary": "#ff0"}} not {"settings": {...}}. ' +
             'Nested objects (colors, fonts, contact, social) are shallow-merged into the existing value. ' +
             'Unknown top-level keys return a 400 error listing the valid fields. ' +
-            'scripts_head / scripts_body_end / custom_css ARE writable here — useful for a global stylesheet across all pages. ' +
+            'scripts_head / scripts_body_end / custom_css and cookie_consent scripts ARE writable here — useful for a global stylesheet or analytics tag across all pages. ' +
+            'Social sharing and structured data: default_og_image, twitter_handle, organization ({name, logo, same_as[]}, replaced as a whole; null clears). ' +
+            'staging_url is stored on the Site (not per version), so it applies whichever `version` you pass. ' +
             'Pass `version` to scope the write to a branch (copy-on-write) instead of main — the right way to brand/recolor a site inside a redesign branch (colors, fonts, logo, custom_css) without touching the live settings. Omit it to write main.',
         inputSchema: {
             version: versionParam,
@@ -54,6 +56,14 @@ export const settingsTools = [
             scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page. Use for analytics, fonts, third-party CSS links.'),
             scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page. Use for chat widgets, deferred analytics.'),
             custom_css: z.string().optional().describe('Global CSS in a <style> in <head>, after block CSS and before the page\'s own custom CSS and the template base stylesheet (reset + global). Base rules for :root tokens (spacing, radius, container widths), body font and line-height load after it, so override those with a more specific selector (for example html:root or body.page) rather than a bare :root/body rule. Preview uses the same order. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element. Prefer named styles (create_style) for anything a style can express. Syntax errors (unbalanced braces, unclosed comments or strings, expression()/javascript:) refuse the write; selectors on platform markup ([data-block], .block-*) come back as warnings because they can change between render versions — target s-<style> classes or block custom_class instead.'),
+            default_og_image: z.string().optional().describe('Site-wide fallback og:image URL for pages without their own social image. Empty string clears.'),
+            twitter_handle: z.string().optional().describe('Twitter/X handle for twitter:site, with or without the leading @ (stored without it). Empty string clears.'),
+            organization: z.object({
+                name: z.string().optional(),
+                logo: z.string().optional().describe('Absolute logo URL for the Organization JSON-LD.'),
+                same_as: z.array(z.string()).max(50).optional().describe('Profile URLs (LinkedIn, X, Facebook, …) emitted as sameAs.'),
+            }).strict().nullable().optional().describe('Organization schema.org JSON-LD emitted on every page. Replaces the stored value as a whole; null (or all-empty) clears it.'),
+            staging_url: z.string().nullable().optional().describe('URL of a staging environment for this site, reported as urls.staging. Stored on the Site, not per version. Trailing slashes are dropped; empty string or null clears.'),
             render_version: z.number().int().min(1).optional().describe('Platform render version. Platform output changes ship as new versions so existing sites never change look on their own. Upgrade only after previewing (get_preview_link render_version) and with the user\'s approval; the tr-upgrade-rendering skill compares every page. Lowering it returns to an earlier version.'),
             colors: z.record(z.string()).optional(),
             fonts: z.record(z.unknown()).optional(),

package/dist/tools/sites.js

@@ -1,4 +1,6 @@
-// Sites tools — discovery + Site-level identity edits.
+// Sites tools — discovery, Site-level identity edits and the site lifecycle
+// (archive / restore). Each maps to a v1 route with the same permission
+// check as the corresponding portal action.
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 export const siteTools = [
@@ -30,7 +32,7 @@ export const siteTools = [
     },
     {
         name: 'get_site',
-        description: 'Read this site\'s metadata (id, name, slug, domain, active version) + a urls object covering the production / fallback / preview_base URLs. Useful as a first call to confirm the key is wired up and to learn what URLs the site is reachable at.',
+        description: 'Read this site\'s metadata (id, name, slug, domain, language, ai_scripts_enabled, lifecycle {status: active|archived}, active version) + a urls object covering the production / fallback / preview_base / staging URLs. Useful as a first call to confirm the key is wired up and to learn what URLs the site is reachable at.',
         handler: withErrorBoundary(async (_args, { client, siteId }) => {
             const res = await client.get(siteId, '');
             return ok(res);
@@ -65,16 +67,36 @@ export const siteTools = [
     },
     {
         name: 'update_site',
-        description: 'Edit Site-level identity fields: name (display), slug (drives the {slug}.typeroll-fallback subdomain — kebab-case, 3-48 chars, unique across the org), domain (the customer\'s real hostname; pass "" to clear). For colors / fonts / contact info / tagline use update_site_settings instead.',
+        description: 'Edit Site-level fields: name (display), slug (drives the {slug}.typeroll-fallback subdomain — kebab-case, 3-48 chars, unique across the org), domain (the customer\'s real hostname; pass "" to clear), language, and ai_scripts_enabled (the portal\'s "Allow AI to write block scripts" toggle; requires admin permission, as in the portal). For colors / fonts / contact info / tagline / staging_url use update_site_settings instead.',
         inputSchema: {
             name: z.string().min(1).optional(),
             slug: z.string().optional().describe('Kebab-case identifier, 3-48 chars [a-z0-9-]. Empty string clears.'),
             domain: z.string().optional().describe('Bare hostname e.g. "example.com". Empty string clears.'),
             language: z.string().optional().describe('Default content language as a BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> and the default for alt-text generation. Empty string clears.'),
+            ai_scripts_enabled: z.boolean().optional().describe('"Allow AI to write block scripts": lets the in-portal chat assistant author block JavaScript for this site. API keys and MCP are not gated by it — they can always write block `script` and core/embed `js`. Requires admin permission.'),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.patch(siteId, '', args);
             return ok(res);
         }),
     },
+    {
+        name: 'archive_site',
+        description: 'Archive (retire) this site, the same action as Settings → Archive site in the portal. An archived site stays readable but refuses every write and publish until restored; the last published output keeps serving. Refused with 409 while a custom domain is still live or verified — move or remove the domain first. Requires an admin key of the organization that OWNS the site (a site-scoped key or the owner organization\'s org key); a key that reaches the site through a share is refused. Idempotent. Confirm with the user before calling.',
+        inputSchema: {
+            reason: z.string().max(500).optional().describe('Why the site is retired; shown in the portal.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'lifecycle', { action: 'archive', ...(args.reason ? { reason: args.reason } : {}) });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'restore_site',
+        description: 'Restore an archived site so it accepts writes and publishing again, the same action as Restore in the portal. Same permission as archive_site (owner-organization admin). Idempotent: restoring an active site succeeds without change.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.post(siteId, 'lifecycle', { action: 'restore' });
+            return ok(res);
+        }),
+    },
 ];

package/dist/tools/versions.js

@@ -12,7 +12,7 @@ export const versionTools = [
     },
     {
         name: 'create_branch',
-        description: "Create a copy-on-write branch from main (or the version passed in `base`) — the RECOMMENDED first step for any larger or experimental change (redesigns, multi-page edits, trying a new design direction). Work lands on the branch, never on the live main version, until you merge_branch it. New branches default to robots_blocked:true (a half-finished design can't be indexed) and get their own stable deploy address for stakeholder review: after the branch's first trigger_deploy, read it from deploy_url in list_versions or read_version (the publishing setup decides the host: under a Hosting Group it is a v-… host under that group's site address base, otherwise the address the host reported; never construct it yourself). Pass the returned id as ?version= on every subsequent read/write. When in doubt, branch — it's cheap and keeps the live site safe. The tr-redesign-branch skill (read_skill) walks the full flow.",
+        description: "Create a copy-on-write branch from main (or the version passed in `base`) — the RECOMMENDED first step for any larger or experimental change (redesigns, multi-page edits, trying a new design direction). Work lands on the branch, never on the live main version, until you merge_branch it. New branches default to robots_blocked:true (a half-finished design can't be indexed) and get their own stable deploy address for stakeholder review: after the branch's first trigger_deploy, read it from deploy_url in list_versions or read_version (the publishing setup decides the host: under a Hosting Group it is a v-… host under that group's site address base, otherwise the address the host reported; never construct it yourself). Pass the returned id as ?version= on every subsequent read/write. When in doubt, branch — it's cheap and keeps the live site safe. The tr-redesign-branch skill (read_skill) walks the full flow. Admin permission on the site is required, as in the portal.",
         inputSchema: {
             name: z.string().min(1),
             base: z.string().optional().describe('Source version id; defaults to main.'),
@@ -33,16 +33,34 @@ export const versionTools = [
     },
     {
         name: 'delete_branch',
-        description: 'Discard a branch (main cannot be deleted).',
+        description: 'Discard a branch with its overrides, tombstones and revision history (main cannot be deleted). Admin permission required.',
         inputSchema: { version_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.del(siteId, `versions/${encodeURIComponent(args.version_id)}`);
             return ok(res);
         }),
     },
+    {
+        name: 'diff_version',
+        description: 'Read-only: what a branch changes relative to main, per collection (pages, partials, redirects, contentTypes, pageTemplates, blockTypes): ids it adds, modifies and deletes, plus whether it overrides site settings and totalChanges. This is exactly what merge_branch would land on main and what reset_version would discard. Use it to summarise a branch for review before asking for merge approval.',
+        inputSchema: { version_id: z.string().describe('Branch id (main has nothing to diff).') },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `versions/${encodeURIComponent(args.version_id)}/diff`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'reset_version',
+        description: 'Discard EVERY change on a branch (all overrides and deletions), so it reads straight through to main again. The branch itself, its deploy address and its revision history are kept. Destructive for the branch\'s work: run diff_version first and get explicit user approval. Returns { cleared } — the diff that was discarded. Admin permission required. Main cannot be reset.',
+        inputSchema: { version_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `versions/${encodeURIComponent(args.version_id)}/reset`);
+            return ok(res);
+        }),
+    },
     {
         name: 'merge_branch',
-        description: 'Promote a branch\'s overrides + tombstones onto main. The branch is left in place so you can keep iterating; delete_branch removes it when you\'re done.',
+        description: 'Promote a branch\'s overrides + tombstones onto main (diff_version shows exactly what will land). The branch is left in place so you can keep iterating; delete_branch removes it when you\'re done. Admin permission required.',
         inputSchema: { version_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.post(siteId, `versions/${encodeURIComponent(args.version_id)}/merge`);

package/dist/tools/workflows.js

@@ -0,0 +1,61 @@
+// Workflow tools — the portal's server-side workflows (WordPress migration,
+// AI site planning, SEO / link / performance audits, content generation and
+// improvement, schema markup, URL parity, rebuild & deploy) and creating a
+// Site together with its first workflow.
+import { z } from 'zod';
+import { ok, versionParam, withErrorBoundary } from './helpers.js';
+const WORKFLOW_TYPES = [
+    'migration', 'site_planning', 'seo_audit', 'content_improvement', 'link_check',
+    'performance_audit', 'content_generation', 'schema_markup', 'url_parity', 'rebuild_deploy',
+];
+export const workflowTools = [
+    {
+        name: 'list_workflows',
+        description: 'List the workflow types this Site can run (label, description, steps, required_permission) and its most recent runs with status. Read only. Migration, site planning and URL parity pause for review; check get_workflow for paused_for_review.',
+        inputSchema: { limit: z.number().int().min(1).max(100).optional() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, 'workflows', args.limit ? { limit: args.limit } : undefined))),
+    },
+    {
+        name: 'start_workflow',
+        description: 'Start a server-side workflow on this Site; it runs in the background and returns workflow_id. Poll get_workflow. Config per type (same fields as the portal form): migration { wp_url, helper_api_key? } (needs verified organization import storage); site_planning { business_description }; content_generation { topic, tone?, audience? }; content_improvement { limit? }; url_parity { target_origin?, source_origin?, check_source?, statuses? }; rebuild_deploy { environment: staging | production }; seo_audit, link_check, performance_audit and schema_markup take none. Needs write permission; rebuild_deploy publishes and needs admin. Workflows that change content write to the given version (default main) — get the user\'s agreement first.',
+        inputSchema: {
+            type: z.enum(WORKFLOW_TYPES),
+            config: z.record(z.unknown()).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'workflows', { type: args.type, config: args.config }, args.version ? { version: args.version } : undefined))),
+    },
+    {
+        name: 'get_workflow',
+        description: 'Read one workflow run: status (pending | running | paused_for_review | completed | failed), current step, progress, log, review_message/review_data when paused, results and failure_reason. Credential config is masked.',
+        inputSchema: { workflow_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, `workflows/${encodeURIComponent(args.workflow_id)}`))),
+    },
+    {
+        name: 'approve_workflow',
+        description: 'Approve the review gate of a run that is paused_for_review; it resumes from the next step in the background. Show the user review_message and review_data from get_workflow and get their approval first — approval is theirs to give, not the tool\'s. Write permission; any other status returns 409.',
+        inputSchema: { workflow_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, `workflows/${encodeURIComponent(args.workflow_id)}/approve`))),
+    },
+    {
+        name: 'create_site_and_migrate',
+        noSite: true,
+        description: 'Create a new Site in the Organization and start a WordPress migration into it, like "Migrate from WordPress" on the portal\'s New site page. Requires an organization API key and verified organization import storage (409 import_storage_required otherwise — nothing is created). Returns site and workflow ids; poll get_workflow with that site_id. Run get_migration_readiness on the new Site if you need the preflight first.',
+        inputSchema: {
+            name: z.string().min(1).describe('Site display name; slugified into the Site id.'),
+            wp_url: z.string().url().describe('Public WordPress address, e.g. https://oldsite.example.'),
+            helper_api_key: z.string().optional().describe('Typeroll Helper plugin key from the WordPress admin, if installed. Stored for the run and never returned.'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('sites/create-and-migrate', args))),
+    },
+    {
+        name: 'create_site_and_plan',
+        noSite: true,
+        description: 'Create a new Site in the Organization and start AI site planning from a business description, like "Plan a new site with AI" on the New site page. Requires an organization API key. The plan pauses for review: read it with get_workflow and approve_workflow only after the user agrees.',
+        inputSchema: {
+            name: z.string().min(1),
+            business_description: z.string().min(1).describe('What the business does, for whom, and what sets it apart.'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('sites/create-and-plan', args))),
+    },
+];

package/dist/tools/working-copy.js

@@ -9,11 +9,13 @@
 //                                              Save button)
 //   discard_working_copy                   →  throw the draft away
 //   list/read/restore_page_revision        →  saved-state history (undo)
+//   preview_page_revision                  →  render a saved state
+//   list/read/restore_partial_revision     →  the same for partials
 //
 // The portal editor shows any agent-written draft as "Unsaved changes", so
 // the human can also Save or Discard it from the UI.
 import { z } from 'zod';
-import { ok, withErrorBoundary, versionParam } from './helpers.js';
+import { ok, withErrorBoundary, versionParam, writeAuthority } from './helpers.js';
 function v(version) {
     return version ? { version } : undefined;
 }
@@ -42,10 +44,11 @@ export const workingCopyTools = [
         description: 'SAVE a doc\'s unsaved draft: promote it onto the saved doc through the canonical write path (revision snapshot, SEO transform, redirect hygiene) and delete the draft. Identical to the Save button in the portal editor. Returns { committed, seo_warnings, auto_redirects, retired_redirects }. Never changes publish status. Deploys only ship saved content, so commit before trigger_deploy. Equivalent shortcut: save:true on the write tools.',
         inputSchema: {
             target: wcTargetSchema,
+            ...writeAuthority,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, wcPath(args.target), {}, v(args.version));
+            const res = await client.post(siteId, wcPath(args.target), { ...(args.override_reason ? { override_reason: args.override_reason } : {}) }, v(args.version));
             return ok(res);
         }),
     },
@@ -109,10 +112,71 @@ export const workingCopyTools = [
             page_id: z.string(),
             revision_id: z.string(),
             save: z.boolean().optional().describe('Save immediately (default false: leave it as an unsaved draft to preview).'),
+            ...writeAuthority,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/revisions/${encodeURIComponent(args.revision_id)}/restore`, { save: args.save === true }, v(args.version));
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/revisions/${encodeURIComponent(args.revision_id)}/restore`, { save: args.save === true, ...(args.override_reason ? { override_reason: args.override_reason } : {}) }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'preview_page_revision',
+        description: 'Render one saved page revision as the whole preview document (header, body, footer, site CSS and block scripts), exactly what the editor\'s History panel shows before a restore. Read-only. The revision\'s fields are laid over the current page; the current header, footer and settings give context. Returns { page_id, revision_id, slug, title, rendered_html, internal_links }. Pass annotate:true to tag block roots with data-block-id + data-block-type. Compare with get_page_preview before restore_page_revision.',
+        inputSchema: {
+            page_id: z.string(),
+            revision_id: z.string(),
+            annotate: z.boolean().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = { ...(v(args.version) ?? {}) };
+            if (args.annotate)
+                query.annotate = 'true';
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/revisions/${encodeURIComponent(args.revision_id)}/preview`, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_partial_revisions',
+        description: "Saved-state history of a partial (header, footer or global block) on this version, newest first. Every save snapshots the partial as it was BEFORE the save. Returns { revisions: [{ id, created_at, created_by, note, name, content_mode, date_updated }], total }. Use read_partial_revision for the full document and restore_partial_revision to undo.",
+        inputSchema: {
+            partial_id: z.string(),
+            limit: z.number().int().min(1).max(100).optional().describe('Newest N entries (default 50).'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = { ...(v(args.version) ?? {}) };
+            if (args.limit)
+                query.limit = String(args.limit);
+            const res = await client.get(siteId, `partials/${encodeURIComponent(args.partial_id)}/revisions`, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_partial_revision',
+        description: 'Read one partial revision with the full saved document (name, kind, html_content or blocks, status) — compare it with read_partial before restoring.',
+        inputSchema: {
+            partial_id: z.string(),
+            revision_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `partials/${encodeURIComponent(args.partial_id)}/revisions/${encodeURIComponent(args.revision_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'restore_partial_revision',
+        description: "Restore a partial revision's name and content (HTML or block tree) into the partial's DRAFT, replacing the current draft. Pass save:true to save it at once; the save snapshots the current partial first, so the restore is itself undoable. Status and kind are kept. A revision from the other content mode is refused (409) — switch mode first. Returns { restored_revision, saved, has_unsaved_changes, staged_fields, sanitization_warnings }.",
+        inputSchema: {
+            partial_id: z.string(),
+            revision_id: z.string(),
+            save: z.boolean().optional().describe('Save immediately (default false: leave it as an unsaved draft to preview).'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `partials/${encodeURIComponent(args.partial_id)}/revisions/${encodeURIComponent(args.revision_id)}/restore`, { save: args.save === true }, v(args.version));
             return ok(res);
         }),
     },

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.43';
+export const VERSION = '0.45.45';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.43",
+  "version": "0.45.45",
   "description": "Typeroll CMS MCP server – connect AI agents to the REST API to manage content and publish static websites.",
   "license": "MIT",
   "repository": {

package/skills/tr-content-write.md

@@ -45,9 +45,9 @@ setting one-off values; ask first when it changes the site's look.
 A small label above a heading is the heading block's `eyebrow`, and a line
 below it is its `subtitle` (render version 2), each with its own style field.
 Never write them as separate text blocks with classed HTML. In text blocks,
-style whole paragraphs with site text styles (`<p class="s-lead">`); a text
-block that needs other classes, images or headings with parts is better split
-with `convert_prose_block`.
+style whole paragraphs with site text styles (`<p class="s-lead">`). Content
+that needs headings with parts, images or buttons belongs in their own blocks,
+not in a text block's HTML.
 
 `list_block_templates` and `list_partials` too. Start a common section from a
 block template (`insert_block_template`, then edit the copy). Use a global

package/skills/tr-forms.md

@@ -6,8 +6,8 @@ description: Use when the user wants to add a contact form, newsletter signup, b
 # Add a form to a Typeroll site
 
 Typeroll forms are server-backed. The platform renders the form shell, accepts
-signed submissions, validates declared fields, stores submissions, and can run
-admin-configured email or webhook actions.
+signed submissions, validates declared fields, stores submissions, and runs
+email and webhook actions configured in the portal or through MCP/API.
 
 ## Choose the placement
 
@@ -97,9 +97,34 @@ actions in the form editor:
   `X-Typeroll-Signature`, sends an idempotency key, retries transient failures,
   and stores delivery status.
 
-Actions are deliberately excluded from MCP/API-key writes and reads because
-they can exfiltrate submitted data. Direct the user to the portal form editor
-to configure them.
+Agents manage the same actions with `read_form` (actions with secrets masked)
+and `update_form patch={ actions: [...] }`, with admin permission as in the
+portal. `actions` replaces the whole list: read the form, change what you need
+and send the list back. Examples:
+
+```
+update_form form_id=contact patch={ actions: [
+  { type: "email", config: { to: "hello@example.com", subject: "New lead: {{name}}",
+    body: "<p>{{message}}</p>", include_all: true, reply_to: "{{email}}" } },
+  { type: "email", config: { to: "{{email}}", subject: "Thanks, {{name}}",
+    body: "<p>We will get back to you within a day.</p>" } }
+] }
+```
+
+A webhook needs `url` (https), an explicit `fields` allowlist and a signing
+`secret`; send the masked value back to keep a stored secret.
+`get_form_capabilities` lists every action type the site offers, including
+types from installed apps, with the config fields each one takes.
+
+Email actions send through the site's email provider. Check it with
+`get_email_settings`; if `email` is null, connect one with `set_email_settings`
+(for example `type: "postmark"`, `from`, `config: { server_token }`) and confirm
+with `send_test_email`. Without a provider, submissions are stored but nobody is
+notified. These tools need admin permission, like Settings → Email & notifications.
+
+`list_form_submissions` reads what visitors sent, `read_form_submission` reads
+one entry (admins also see webhook delivery status) and `delete_form_submission`
+removes one.
 
 ## Verify
 
@@ -107,8 +132,11 @@ to configure them.
 2. Preview the page and confirm the authoring reference has expanded to a form
    with `data-tr-form-el`, a signed token, and the platform runtime.
 3. Submit a test entry and confirm it appears in Forms → Submissions.
-4. If a webhook is configured, confirm its delivery status and the receiving
-   system's idempotency key before deploying.
+4. If a webhook is configured, confirm its delivery status
+   (`read_form_submission`) and the receiving system's idempotency key before
+   deploying.
+5. If an email action is configured, confirm `get_email_settings` shows a
+   provider and the test message arrived.
 
 ## Common patterns
 
@@ -143,7 +171,7 @@ Booking request:
 
 - Do not hand-write a form, token, honeypot, or submit script.
 - Do not put a raw `<script>` in page HTML; the sanitizer removes it.
-- Do not expose action configuration through agent surfaces.
+- Do not drop existing actions by accident: `actions` replaces the list.
 - Do not send every submitted field to a webhook by default; choose the
   smallest allowlist the external register needs.
 - `submit_token` is stable until the platform rotates its form-signing secret;

package/skills/tr-import-url.md

@@ -61,8 +61,8 @@ small label directly above a heading is an eyebrow style, not a heading of its
 own: put it in the heading block's `eyebrow` field (and a line under the
 heading in `subtitle`). Never carry classed raw HTML into text blocks to keep a
 look: the editor cannot edit it, and the next render version may not keep it.
-A text block that already holds such markup can be split with
-`convert_prose_block` (preview, then `accept`).
+Build such sections with heading, text, image and button blocks; Typeroll does
+not convert HTML into blocks.
 
 ### 2. Measure the source and protect existing target work