@typeroll/mcp-server 0.45.44 → 0.45.46

package/dist/tools/extensions.js

@@ -66,4 +66,135 @@ export const extensionTools = [
             }
         }),
     },
+    {
+        name: 'install_extension',
+        description: 'Install an Extension release on this site, as the portal\'s install action does. Pass the Extension id and a published release (developer organizations may also install their own draft or review releases on their own sites). granted_scopes must be a subset of the manifest\'s requested permissions — grant only what the user approved. config must satisfy manifest.config_schema; secret values are encrypted and never returned. Does not deploy: trigger_deploy afterwards to publish provisioned components. Admin permission required.',
+        inputSchema: {
+            extension_id: z.string().min(1),
+            version: z.string().min(1).describe('Release version to install.'),
+            granted_scopes: z.array(z.string()).optional().describe('Approved scopes; defaults to none.'),
+            config: z.record(z.unknown()).optional(),
+            developer_org_id: z.string().optional().describe('Organization that publishes the Extension. Defaults to the key\'s own organization.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.post(siteId, 'extensions', args));
+        }),
+    },
+    {
+        name: 'set_extension_installation_status',
+        description: 'Enable or disable an installed Extension on this site. Disabling removes its components from the public snapshot and editor until re-enabled; page instances are kept. Changes apply immediately to previews; deploy to publish. Admin permission required.',
+        inputSchema: {
+            installation_id: z.string().min(1),
+            status: z.enum(['enabled', 'disabled']),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.patch(siteId, `extensions/${encodeURIComponent(args.installation_id)}`, { status: args.status }));
+        }),
+    },
+    {
+        name: 'uninstall_extension',
+        description: 'Uninstall an Extension from this site: revokes the installation and all its server credentials and removes its block definitions. Existing page blocks remain as unavailable placeholders. Not reversible except by installing again (a new installation id). Get explicit user approval. Admin permission required.',
+        inputSchema: { installation_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.del(siteId, `extensions/${encodeURIComponent(args.installation_id)}`));
+        }),
+    },
+    {
+        name: 'pair_extension_issuer',
+        description: 'Pair this Typeroll instance\'s token issuer with the Extension provider (manifest auth.pairing_url), the portal\'s "secure connection" action. Contacts the provider. Returns the trusted issuer record. Admin permission required.',
+        inputSchema: { installation_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.post(siteId, `extensions/${encodeURIComponent(args.installation_id)}/pair`));
+        }),
+    },
+    {
+        name: 'read_extension_diagnostics',
+        description: 'Read an installation\'s diagnostics: status, health, release resolution, credential metadata (no secrets), the latest audit events and lifecycle event deliveries, and declared URL context inputs. Admin permission required.',
+        inputSchema: { installation_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.get(siteId, `extensions/${encodeURIComponent(args.installation_id)}/diagnostics`));
+        }),
+    },
+    {
+        name: 'launch_extension_admin_page',
+        description: 'Issue a single-use, short-lived launch grant for one of the Extension\'s admin pages (manifest admin.pages), as opening the page in the portal does. Returns { launch_url, method, form, expires_at }: a browser tool must POST the `form` fields to launch_url before expires_at. The provider sees the caller as api-key:{prefix}. Treat the code as a credential. For approved native pages prefer call_extension_admin. The page\'s minimum_permission applies.',
+        inputSchema: {
+            installation_id: z.string().min(1),
+            page_id: z.string().min(1).describe('Admin page id from the installation manifest.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.post(siteId, `extensions/${encodeURIComponent(args.installation_id)}/launch`, { page_id: args.page_id }));
+        }),
+    },
+];
+const ext = (id) => `extensions/${encodeURIComponent(id)}`;
+/** Extension developer tools — the `typeroll extension` CLI's API. They act on
+ *  the key's own organization, not on a site, and need an
+ *  organization-scoped key (a site key gets 403). */
+export const developerExtensionTools = [
+    {
+        name: 'list_developer_extensions', noSite: true,
+        description: 'List Extensions registered by your organization (developer side). Requires an organization API key.',
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.developer('GET', 'extensions'))),
+    },
+    {
+        name: 'read_developer_extension', noSite: true,
+        description: 'Read one of your organization\'s Extensions with all saved releases and their status (draft, review, published, deprecated, revoked). Requires an organization API key.',
+        inputSchema: { extension_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('GET', ext(args.extension_id)))),
+    },
+    {
+        name: 'update_developer_extension', noSite: true,
+        description: 'Update an Extension\'s name, status (active/suspended), distribution (only while every release is a draft), trusted origins or private allow-lists. Requires an organization API key.',
+        inputSchema: {
+            extension_id: z.string().min(1),
+            name: z.string().optional(),
+            status: z.enum(['active', 'suspended']).optional(),
+            distribution: z.enum(['private', 'unlisted', 'public']).optional(),
+            trusted_origins: z.array(z.string()).optional(),
+            allowed_org_ids: z.array(z.string()).optional(),
+            allowed_site_ids: z.array(z.string()).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client }) => {
+            const { extension_id, ...patch } = args;
+            return ok(await client.developer('PATCH', ext(extension_id), patch));
+        }),
+    },
+    {
+        name: 'save_extension_version', noSite: true,
+        description: 'Save (create or replace) a draft release from a full Extension manifest. Published releases are immutable; bump manifest.version instead. Validate locally with `typeroll extension validate` first. Requires an organization API key.',
+        inputSchema: {
+            extension_id: z.string().min(1),
+            manifest: z.record(z.unknown()).describe('Complete manifest; its id must equal extension_id.'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('POST', `${ext(args.extension_id)}/versions`, { manifest: args.manifest }))),
+    },
+    {
+        name: 'publish_extension_version', noSite: true,
+        description: 'Publish a saved release after verifying its asset digests. Private releases become installable for allowed organizations and sites; public releases enter review before catalog discovery. Installations follow compatible published releases automatically, so get user approval. Requires an organization API key.',
+        inputSchema: { extension_id: z.string().min(1), version: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('POST', `${ext(args.extension_id)}/versions/${encodeURIComponent(args.version)}/publish`))),
+    },
+    {
+        name: 'set_extension_version_lifecycle', noSite: true,
+        description: 'Deprecate or revoke a release. Revoking stops installations from resolving to it. Requires an organization API key.',
+        inputSchema: {
+            extension_id: z.string().min(1),
+            version: z.string().min(1),
+            status: z.enum(['deprecated', 'revoked']),
+            reason: z.string().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client }) => {
+            const { extension_id, version, ...body } = args;
+            return ok(await client.developer('PATCH', `${ext(extension_id)}/versions/${encodeURIComponent(version)}`, body));
+        }),
+    },
+    {
+        name: 'list_developer_extension_installations', noSite: true,
+        description: 'List operational metadata (status, versions, health; never config) for your Extension\'s installations on one customer site. Requires an organization API key and the customer\'s organization and site ids.',
+        inputSchema: { extension_id: z.string().min(1), owner_org_id: z.string().min(1), site_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('GET', `${ext(args.extension_id)}/installations`, undefined, {
+            owner_org_id: args.owner_org_id, site_id: args.site_id,
+        }))),
+    },
 ];

package/dist/tools/forms.js

@@ -39,11 +39,11 @@ const targetSchema = z.object({
 // Forms editor; admin permission required, as in the portal.
 const actionSchema = z.object({
     id: z.string().optional().describe('Keep an existing action\'s id to update it in place (webhooks keep their stored secret).'),
-    type: z.string().describe('"email", "webhook", or an action type provided by an installed app.'),
+    type: z.string().describe('"email", "webhook", or an action type provided by an installed app (see get_form_capabilities).'),
     config: z.record(z.string(), z.unknown()).describe('email: { to, subject, body, cc?, bcc?, reply_to?, include_all?, format?: "html"|"text" } — to/subject/body may use {{field}} placeholders, e.g. to: "{{email}}" for a confirmation to the visitor. ' +
         'webhook: { url (https), fields: ["name","email"] (only these values are sent), secret (signing secret; send "••••••••" to keep the stored one) }.'),
 });
-const actionsDescription = 'The complete list of actions after a submission (replaces the current list): email notifications, webhooks, app actions. Read the form first and send back the actions you keep. Requires admin permission, like the portal.';
+const actionsDescription = 'The complete list of actions after a submission (replaces the current list): email notifications, webhooks, app actions (get_form_capabilities lists the types and their config). Read the form first and send back the actions you keep. Emails send through the provider set with set_email_settings. Requires admin permission, like the portal.';
 export const formTools = [
     {
         name: 'list_forms',
@@ -53,6 +53,11 @@ export const formTools = [
             return ok(res);
         }),
     },
+    {
+        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.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'form-capabilities'))),
+    },
     {
         name: 'read_form',
         description: 'Read one form by id, including fields/steps, submit_text, success_message and, for admins, its actions (email notifications and webhooks; secrets masked). Place it with a `core/form` block using data.form_id on a block-mode page, or `<x-form id="…" />` in HTML mode. Both references are expanded server-side with validation, signed token, initial state, and the shared runtime.',
@@ -119,7 +124,7 @@ export const formTools = [
     },
     {
         name: 'list_form_submissions',
-        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Use this to help a customer triage inbound contact / lead submissions.',
+        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Admins also see each submission\'s webhook delivery status. Use this to help a customer triage inbound contact / lead submissions; read_form_submission reads one.',
         inputSchema: {
             form_id: z.string(),
             limit: z.number().int().min(1).max(200).optional(),
@@ -131,6 +136,18 @@ export const formTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'read_form_submission',
+        description: 'Read one submission of a form by id (from list_form_submissions): the submitted values, status (partial or complete), step and timestamps. Admins also see its webhook delivery status, as in the portal.',
+        inputSchema: {
+            form_id: z.string(),
+            submission_id: z.string(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `forms/${encodeURIComponent(args.form_id)}/submissions/${encodeURIComponent(args.submission_id)}`);
+            return ok(res);
+        }),
+    },
     {
         name: 'delete_form_submission',
         description: 'Delete a single submission from a form\'s inbox. Use this to remove individual entries (test submissions, spam) without touching the rest — delete_form with delete_submissions is the only way to bulk-delete. Get submission ids from list_form_submissions.',

package/dist/tools/media.js

@@ -18,6 +18,12 @@ export const mediaTools = [
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'media/import'))),
     },
+    {
+        name: 'get_media_upload_status',
+        description: 'Pre-flight for uploads: whether media uploads can go through for this site right now (organization storage connected, or platform storage configured), with the reason and a settings_url when they cannot. Same check as the banner in the portal media library. Requires site read access.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'media/upload-status'))),
+    },
     {
         name: 'read_private_media_url',
         description: 'Get a 60-second read URL for a private media original. Use it for authorized image inspection; never store it in page content or generated source. Use the stable media URL or ID in content.',
@@ -229,6 +235,12 @@ export const mediaTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'purge_site_media',
+        description: 'Permanently delete every media object and record of an ARCHIVED site (archive_site first; an active site returns 409). Irreversible — the step before retiring a site for good, same as the portal action. Requires an admin key of the organization that owns the site; shared access is refused. Returns counts; HTTP 207 with `failed` lists objects that could not be removed (their records are kept) — call again to retry exactly those. Confirm with the user before calling.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.post(siteId, 'media/purge'))),
+    },
     {
         name: 'delete_media',
         description: 'Delete a media item\'s metadata. (R2 object cleanup is a separate ops task.)',

package/dist/tools/pages.js

@@ -287,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,6 +9,8 @@
 //                                              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.
@@ -118,4 +120,64 @@ export const workingCopyTools = [
             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.44';
+export const VERSION = '0.45.46';

package/package.json

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

package/skills/README.md

@@ -43,6 +43,7 @@ instructions. Read the relevant recipe when the task calls for it.
 |---|---|---|
 | `tr-blog.md` | "add a blog", "set up news" | Articles are Pages of a content type, sharing a native template and Page listing. |
 | `tr-forms.md`             | "contact form", "add a form", "booking form"           | Form definition → embed HTML with signed token → inline JS feedback → deploy. |
+| `tr-custom-blocks.md` | "make a block for…", "icon list", a section shape the core blocks lack | Starter or composition from core blocks with fields and bindings → validate → preview → create → place. |
 | `tr-page-template.md` | Reusable Page templates: audio players, chapter lists, guest cards, image galleries — anything needing loops/nested data | Compose native blocks around `template_content_slot`; bind Page metadata, structured fields and references. |
 | `tr-seo.md`               | "SEO", "meta descriptions", "structured data"          | Audit → fix titles/descriptions → OG images → JSON-LD → robots.txt → deploy. |