@typeroll/mcp-server 0.45.42 → 0.45.44

package/dist/server.js

@@ -16,6 +16,8 @@ import { contentTypeTools } from './tools/content-types.js';
 import { pageTemplateTools } from './tools/page-templates.js';
 import { mediaTools } from './tools/media.js';
 import { redirectTools } from './tools/redirects.js';
+import { styleTools } from './tools/styles.js';
+import { reusableBlockTools } from './tools/reusable-blocks.js';
 import { migrationTools } from './tools/migration.js';
 import { formTools } from './tools/forms.js';
 import { searchTools } from './tools/search.js';
@@ -113,7 +115,17 @@ The full playbook ships with this server — use it:
 5. Pages default to block mode. Build with add_block/update_block; make layouts
    responsive per breakpoint with set_block_responsive (grid columns, icon-box
    layout, … take { mobile, tablet, laptop, desktop, wide } values).
-6. No site yet? With an org-scoped key, create_site bootstraps one.
+6. Appearance lives in named styles: list_styles before styling, reuse a
+   style through a block's style_id, and create_style for any look that could
+   recur. Use one-off block values only for something clearly unique, never
+   classed raw HTML. Text must meet WCAG AA contrast. A heading's small label
+   is its eyebrow field. For what styles cannot express, use page or site
+   custom_css on s-<style> or block custom_class selectors, not [data-block].
+7. Reuse: content that must stay identical on many pages is a global block
+   (make_block_global; core/global_block references it). A section people
+   start from and then adapt is a block template (list_block_templates,
+   insert_block_template copies it). Never duplicate shared content by hand.
+8. No site yet? With an org-scoped key, create_site bootstraps one.
 
 If anything here conflicts with what a tool returns, trust the tool. Every
 tool's own description carries its specifics.
@@ -142,6 +154,8 @@ export function buildServer(options) {
         ...pageTemplateTools,
         ...mediaTools,
         ...redirectTools,
+        ...styleTools,
+        ...reusableBlockTools,
         ...migrationTools,
         ...formTools,
         ...settingsTools,

package/dist/tools/content-types.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ok, withErrorBoundary, versionParam } from './helpers.js';
+import { ok, withErrorBoundary, versionParam, writeAuthority } from './helpers.js';
 const schema = z.array(z.object({ name: z.string(), label: z.string(), type: z.enum(['text', 'textarea', 'richtext', 'image', 'file', 'color', 'select', 'multiselect', 'boolean', 'number', 'url', 'email', 'date', 'datetime', 'list', 'list_simple', 'array', 'object', 'page_ref', 'page_ref_list']) }).passthrough());
 const fields = {
     label_singular: z.string().optional(), label_plural: z.string().optional(), fields: schema.optional(),
@@ -14,7 +14,7 @@ const fields = {
 export const contentTypeTools = [
     { name: 'page_completeness', description: 'Report missing, unverified and stale fields for Pages of one content type, with per-field counts and worst-first Page IDs. Read-only; agent-writable fields only by default.', inputSchema: { content_type: z.string(), limit: z.number().int().min(1).max(200).optional(), stale_after_days: z.number().min(0).optional(), agent_writable_only: z.boolean().optional(), version: versionParam },
         handler: withErrorBoundary(async (args, { client, siteId }) => { const { content_type, ...query } = args; return ok(await client.get(siteId, `content-types/${encodeURIComponent(content_type)}/completeness`, query)); }) },
-    { name: 'change_page_content_type', description: 'Change a saved Page to another content type. Preserves its identity, block body, status and existing URL. Save or discard its working copy first. If supplied, fields replaces the complete custom fields object; omitted fields are kept and must be valid for the new type. Snapshots a revision before changing.', inputSchema: { page_id: z.string(), content_type: z.string(), fields: z.record(z.unknown()).optional(), version: versionParam },
+    { name: 'change_page_content_type', description: 'Change a saved Page to another content type. Preserves its identity, block body, status and existing URL. Save or discard its working copy first. If supplied, fields replaces the complete custom fields object; omitted fields are kept and must be valid for the new type. Snapshots a revision before changing.', inputSchema: { page_id: z.string(), content_type: z.string(), fields: z.record(z.unknown()).optional(), ...writeAuthority, version: versionParam },
         handler: withErrorBoundary(async (args, { client, siteId }) => { const { page_id, version, ...body } = args; return ok(await client.post(siteId, `pages/${encodeURIComponent(page_id)}/content-type`, body, { version })); }) },
     { name: 'list_content_types', description: 'List the field schemas, URL patterns, sorting, allowed templates and default templates for Pages. All content is a Page; use list_pages with content_type to filter.', inputSchema: { version: versionParam },
         handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, 'content-types', { version: args.version }))) },

package/dist/tools/forms.js

@@ -1,4 +1,5 @@
-// Forms — agents can create/update/delete forms, and read submissions.
+// Forms — agents can create/update/delete forms, manage their email
+// notifications and webhooks, and read submissions, like the portal.
 // The customer-facing submit endpoint is HMAC-signed and lives at
 // /api/forms/submit. Agents place forms by reference: core/form in block mode,
 // or <x-form id="…" /> in HTML mode. Preview/build expands either reference
@@ -33,6 +34,16 @@ const targetSchema = z.object({
     context_params: z.array(z.string()).max(8).optional().describe('Explicit URL query keys forwarded to the app hydration endpoint; reserved security keys are rejected.'),
     installation_id: z.string(), path: z.string(), hydrate: z.boolean().optional(), session_param: z.string().optional(),
 }).optional().describe('Admin-only: bind to a declared POST route of an enabled app installation. Read its authenticated guide first.');
+// Actions run after a successful submission: email notifications, signed
+// webhooks and app-provided action types. Same validation as the portal's
+// 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.'),
+    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.';
 export const formTools = [
     {
         name: 'list_forms',
@@ -44,7 +55,7 @@ export const formTools = [
     },
     {
         name: 'read_form',
-        description: 'Read one form by id, including fields/steps, submit_text, and success_message. 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.',
+        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.',
         inputSchema: { form_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `forms/${encodeURIComponent(args.form_id)}`);
@@ -62,6 +73,7 @@ export const formTools = [
             submit_text: z.string().optional(),
             success_message: z.string().optional().describe('Shown after the final step. May contain basic HTML (links, emphasis); it is sanitized.'),
             success_redirect_url: z.string().optional().describe('After the final step, send the visitor to this absolute http(s) URL or root-relative path (for example a booking or thank-you page) instead of showing success_message. Pass an empty string to clear.'),
+            actions: z.array(actionSchema).optional().describe(actionsDescription),
             target: targetSchema,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -74,7 +86,7 @@ export const formTools = [
     },
     {
         name: 'update_form',
-        description: 'Patch a form. Provide only what you want to change. Passing `steps` replaces the whole step list; passing `fields` (sugar for simple forms) replaces the whole step list with ONE static step built from them. The existing form_id is immutable.',
+        description: 'Patch a form. Provide only what you want to change. Passing `steps` replaces the whole step list; passing `fields` (sugar for simple forms) replaces the whole step list with ONE static step built from them. Passing `actions` replaces the email notifications and webhooks (admin). The existing form_id is immutable.',
         inputSchema: {
             form_id: z.string(),
             patch: z.object({
@@ -84,6 +96,7 @@ export const formTools = [
                 submit_text: z.string().optional(),
                 success_message: z.string().optional().describe('Shown after the final step. May contain basic HTML (links, emphasis); it is sanitized.'),
                 success_redirect_url: z.string().optional().describe('After the final step, send the visitor to this absolute http(s) URL or root-relative path (for example a booking or thank-you page) instead of showing success_message. Pass an empty string to clear.'),
+                actions: z.array(actionSchema).optional().describe(actionsDescription),
                 target: targetSchema,
             }),
         },

package/dist/tools/helpers.js

@@ -53,6 +53,13 @@ export function withErrorBoundary(handler) {
     };
 }
 /** Shared zod fragment for the optional `version` parameter. */
+/**
+ * MCP writes Page field values with the same authority as an editor in the
+ * portal. Only a value the listed business set itself needs a stated reason.
+ */
+export const writeAuthority = {
+    override_reason: z.string().max(500).optional().describe('Why a value the listed business set itself (through its edit link) is being replaced. Required only for those values, as in the portal; the write otherwise returns 409 naming the field.'),
+};
 export const versionParam = z
     .string()
     .optional()

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({
@@ -89,7 +87,7 @@ export const pageBlockTools = [
     },
     {
         name: 'update_block',
-        description: 'Update a block\'s data fields (shallow merge), style overrides, or responsive settings. Works on pages, partials, and page templates — use `target` to address non-page containers. Does not modify children or slots; use move/add/remove for structural changes.',
+        description: 'Update a block\'s data fields (shallow merge), style overrides, or responsive settings. Works on pages, partials, and page templates — use `target` to address non-page containers. Does not modify children or slots; use move/add/remove for structural changes. For appearance, prefer a named style (`data.style_id`, see list_styles) over custom_class or custom_css. From render version 2, custom_class lands on the heading or button link element itself instead of the block wrapper.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
@@ -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,16 +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);
-        }),
-    },
 ];

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;
 }
@@ -107,7 +110,8 @@ export const pageTools = [
             sort_order: z.number().finite().optional().describe('Manual Page order; lower numbers come first in ascending lists. Content types and listings choose how to sort.'),
             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).'),
+            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),

package/dist/tools/partials.js

@@ -89,11 +89,12 @@ export const partialTools = [
     },
     {
         name: 'create_free_block',
-        description: 'Create a new free (reusable) global block. Use a kebab-case id and embed it on pages with <x-include name="block-id" />.',
+        description: 'Create a new global block: one shared source that every page using it shows, so an edit updates them all. Pass `blocks` for a block global block, referenced from block pages with a `core/global_block` block (data: { global_block_id }); or `html_content` for HTML pages, embedded with <x-include name="block-id" />. To turn an existing page block into a global block, use make_block_global. For a starter that is copied and then edited per page, use save_block_template instead.',
         inputSchema: {
             id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/),
             name: z.string().optional(),
-            html_content: z.string(),
+            blocks: z.array(z.record(z.unknown())).optional().describe('Block tree for a block global block.'),
+            html_content: z.string().optional().describe('HTML for <x-include> in HTML pages. Send blocks or html_content.'),
             status: z.enum(['draft', 'published']).optional(),
             version: versionParam,
         },

package/dist/tools/preview.js

@@ -26,6 +26,12 @@ export const previewTools = [
                 .boolean()
                 .optional()
                 .describe('Render unsaved drafts (working copies) too — yours AND the editor\'s. Off by default (saved content only). Signed into the token, so a draft link needs its own mint. Use this for your own iteration loop; use a plain link when the user wants to see exactly what a deploy would ship.'),
+            render_version: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Render with this platform render version instead of the site\'s own, to preview an upgrade before applying it (read_site_settings returns render.version, render.latest and what each upgrade changes). Signed into the token. Compare against a plain link to see exactly what would change; apply with update_site_settings render_version.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/reusable-blocks.js

@@ -0,0 +1,98 @@
+// Reusable blocks: global blocks (one shared source, referenced) and block
+// templates (saved starters, copied in). Global blocks themselves are
+// partials; see partials.ts for list/read/update/delete.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const reusableBlockTools = [
+    {
+        name: 'make_block_global',
+        description: 'Turn a block on a page (with everything inside it) into a global block and put a reference in its place. Other pages then add the same block with add_block type "core/global_block" data { global_block_id }. Editing the global block (update_partial / update_block with target { kind: "partial", id }) changes every page that uses it. Use for content that must stay identical everywhere, such as a shared call to action. Writes the page draft.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            name: z.string().optional().describe('Name editors see; defaults to the block name.'),
+            global_block_id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/).optional().describe('Id for the new global block; derived from the name when omitted.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { page_id, version, ...body } = args;
+            return ok(await client.post(siteId, `pages/${encodeURIComponent(page_id)}/blocks/make-global`, body, v(version)));
+        }),
+    },
+    {
+        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.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string().describe('The id of the core/global_block reference block.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { page_id, version, ...body } = args;
+            return ok(await client.post(siteId, `pages/${encodeURIComponent(page_id)}/blocks/detach`, body, v(version)));
+        }),
+    },
+    {
+        name: 'list_block_templates',
+        description: 'List the site\'s block templates: saved section starters (name, description, block count). Inserting one copies its blocks into a page, where they are then edited independently. Check here before building a common section from scratch.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'block-templates'))),
+    },
+    {
+        name: 'read_block_template',
+        description: 'Read one block template, including its block tree.',
+        inputSchema: { template_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, `block-templates/${encodeURIComponent(args.template_id)}`))),
+    },
+    {
+        name: 'save_block_template',
+        description: 'Save a block template: a section starter that editors and agents insert as an independent copy. Pass `from: { page_id, block_id }` to save a block from a page (its draft), or `blocks`. Prefer templates that use named styles (style_id) over one-off values, so copies stay consistent. Templates belong to the site, not a branch.',
+        inputSchema: {
+            name: z.string(),
+            description: z.string().optional().describe('When to use it.'),
+            id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/).optional(),
+            from: z.object({ page_id: z.string(), block_id: z.string() }).optional(),
+            blocks: z.array(z.record(z.unknown())).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'block-templates', args))),
+    },
+    {
+        name: 'update_block_template',
+        description: 'Rename a block template, change its description, or replace its blocks. Pages that already inserted it do not change.',
+        inputSchema: {
+            template_id: z.string(),
+            name: z.string().optional(),
+            description: z.string().optional(),
+            blocks: z.array(z.record(z.unknown())).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { template_id, ...body } = args;
+            return ok(await client.patch(siteId, `block-templates/${encodeURIComponent(template_id)}`, body));
+        }),
+    },
+    {
+        name: 'delete_block_template',
+        description: 'Delete a block template. Pages that already inserted it keep their copies.',
+        inputSchema: { template_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.del(siteId, `block-templates/${encodeURIComponent(args.template_id)}`))),
+    },
+    {
+        name: 'insert_block_template',
+        description: 'Insert a copy of a block template into a page (new block ids), at the top level or inside parent_id (slot_index for column slots), at `position` (default: end). Returns added_ids. Writes the page draft.',
+        inputSchema: {
+            page_id: z.string(),
+            template_id: z.string(),
+            parent_id: z.string().optional().nullable(),
+            slot_index: z.number().int().min(0).optional(),
+            position: z.number().int().min(0).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { page_id, version, ...body } = args;
+            return ok(await client.post(siteId, `pages/${encodeURIComponent(page_id)}/blocks/insert-template`, body, v(version)));
+        }),
+    },
+];

package/dist/tools/settings.js

@@ -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. 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, 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).",
         inputSchema: {
             version: versionParam,
         },
@@ -53,7 +53,8 @@ export const settingsTools = [
             // Scriptable surfaces. Trusted because the caller has an API key.
             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.'),
+            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.'),
+            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(),
             contact: z

package/dist/tools/styles.js

@@ -0,0 +1,108 @@
+// Style library tools. A site's look is a library of NAMED styles
+// (SiteSettings.styles): element roles (body, h1–h6, link) style every
+// matching element, and every other style is chosen per block through the
+// block's `style_id` field. Reuse beats one-off values.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+const COLOR_HELP = 'A palette token (primary, secondary, accent, background, surface, text, text_light), a derived readable text colour for a palette background (on_primary, on_secondary, on_accent), or a hex/rgb/hsl colour. Prefer tokens so a palette change flows through.';
+const length = z.string().describe('CSS length: px, rem, em, %, vw, ch, or clamp()/min()/max()');
+const color = z.string().describe(COLOR_HELP);
+const propsSchema = z.object({
+    font: z.enum(['heading', 'body', 'mono', 'inherit']).optional(),
+    size: length.optional(),
+    weight: z.number().int().min(100).max(900).optional(),
+    line_height: z.string().optional().describe('Unitless number such as "1.5", or a length'),
+    letter_spacing: z.string().optional().describe('e.g. "0.08em" or "normal"'),
+    transform: z.enum(['none', 'uppercase', 'lowercase', 'capitalize']).optional(),
+    italic: z.boolean().optional(),
+    color: color.optional(),
+    background: color.optional(),
+    align: z.enum(['left', 'center', 'right', 'start', 'end', 'justify']).optional(),
+    decoration: z.enum(['none', 'underline']).optional(),
+    space_before: length.optional(),
+    space_after: length.optional(),
+    padding: z.string().optional().describe('One to four CSS lengths'),
+    max_width: length.optional(),
+    radius: length.optional(),
+    border: z.object({
+        width: length.optional(),
+        style: z.enum(['solid', 'dashed', 'dotted', 'none']).optional(),
+        color: color.optional(),
+        sides: z.enum(['all', 'top', 'right', 'bottom', 'left', 'block', 'inline']).optional(),
+    }).optional(),
+}).describe('Style properties. Mobile-first: `base` applies everywhere, `at.<breakpoint>` from that width up.');
+const atSchema = z.object({
+    tablet: propsSchema.optional(),
+    laptop: propsSchema.optional(),
+    desktop: propsSchema.optional(),
+    wide: propsSchema.optional(),
+}).describe('Overrides from each site breakpoint upward (tablet, laptop, desktop, wide).');
+const styleFields = {
+    name: z.string().describe('Author-facing name, in the site\'s language, e.g. "Överrubrik" or "Hero title".'),
+    role: z.enum(['body', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'link', 'lead', 'eyebrow', 'small', 'quote', 'button', 'button_secondary', 'section']).optional()
+        .describe('Standard role. body/h1–h6/link style every matching element on the site; the others mark the standard style for that purpose. One style per role.'),
+    targets: z.array(z.enum(['text', 'heading', 'list', 'button', 'container'])).optional()
+        .describe('Block kinds that can select this style via style_id (text = core/prose, heading = core/heading and core/rich_heading, list, button, container = core/section and core/container).'),
+    description: z.string().optional().describe('When to use it; shown to editors and agents.'),
+    base: propsSchema.optional(),
+    at: atSchema.optional(),
+    hover: z.object({ color: color.optional(), background: color.optional(), decoration: z.enum(['none', 'underline']).optional() }).optional(),
+    css: z.string().optional().describe('Advanced CSS scoped to the style: bare declarations, or rules where `&` is the style selector (e.g. "&::before { content: \'—\' }"). Prefer structured properties.'),
+};
+export const styleTools = [
+    {
+        name: 'list_styles',
+        description: 'List the site\'s named style library: element roles (body, h1–h6, link) that style every matching element, and the styles blocks select with `style_id`. Also returns missing_standard_roles and contrast/library problems. READ THIS BEFORE STYLING ANY PAGE: reuse an existing style for a recurring look (eyebrows, leads, card titles, buttons, section spacing) instead of per-block values, raw HTML classes or page CSS.',
+        inputSchema: { version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, 'styles', v(args.version)))),
+    },
+    {
+        name: 'create_style',
+        description: 'Create a named style. Do this whenever a look could recur — an eyebrow, a lead paragraph, a card title, a quote, a button variant, a section rhythm — then apply it with the block\'s `style_id` field. Only a clearly unique one-off may use block settings instead. Set values for phones in `base` and grow them in `at.tablet`/`at.desktop`. Text must meet WCAG AA contrast (4.5:1, 3:1 for ≥24px or bold ≥18.7px) against its background; a failing style is refused. Never light grey on white.',
+        inputSchema: {
+            id: z.string().regex(/^[a-z][a-z0-9-]{0,47}$/).describe('Stable slug; the CSS class becomes s-<id>. Cannot change later.'),
+            ...styleFields,
+            name: styleFields.name,
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...style } = args;
+            return ok(await client.post(siteId, 'styles', { targets: [], base: {}, ...style }, v(version)));
+        }),
+    },
+    {
+        name: 'update_style',
+        description: 'Update a style. `base`, `hover` and each breakpoint in `at` merge property by property (pass null to remove one); name, targets, description and css replace. Every page using the style changes at once — tell the user which pages that affects when it matters.',
+        inputSchema: {
+            style_id: z.string(),
+            name: styleFields.name.optional(),
+            role: styleFields.role,
+            targets: styleFields.targets,
+            description: styleFields.description,
+            base: z.record(z.unknown()).optional().describe('Property patch for base; null removes a property.'),
+            at: z.record(z.unknown()).optional().describe('Per-breakpoint property patches; null removes a breakpoint or property.'),
+            hover: z.record(z.unknown()).optional(),
+            css: z.string().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, style_id, ...patch } = args;
+            return ok(await client.patch(siteId, `styles/${encodeURIComponent(style_id)}`, patch, v(version)));
+        }),
+    },
+    {
+        name: 'delete_style',
+        description: 'Delete a style. Blocks that still reference it fall back to their default look; reassign them first.',
+        inputSchema: { style_id: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.del(siteId, `styles/${encodeURIComponent(args.style_id)}`, v(args.version)))),
+    },
+    {
+        name: 'apply_standard_styles',
+        description: 'Add the standard styles the site is missing (body, H1–H6, link, lead, eyebrow, small text, quote, primary/secondary button, section), with considered sizes and spacing for phones, tablets and desktops. The natural first step when building a new site, before pages: then adjust them to the brand (fonts, colours, scale) with update_style. New sites already have them. overwrite:true resets the standard roles to the defaults and changes the site\'s look — ask first.',
+        inputSchema: { overwrite: z.boolean().optional(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'styles/standard', { overwrite: args.overwrite === true }, v(args.version)))),
+    },
+];

package/dist/tools/working-copy.js

@@ -13,7 +13,7 @@
 // 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 +42,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 +110,11 @@ 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);
         }),
     },

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.42",
+  "version": "0.45.44",
   "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

@@ -33,6 +33,7 @@ instructions. Read the relevant recipe when the task calls for it.
 | `tr-new-site.md`       | "create a new site", "bootstrap a site for…"        | Settings → header/footer partials → homepage → inner pages → deploy. Full setup recipe. |
 | `tr-brand.md`          | "create a brand", "choose colors", "design the look"| Palette recipes by mood, typography pairings, CSS variable setup, preview. |
 | `tr-redesign-branch.md`| "redesign", "modernize", anything site-wide-design   | Branch-isolated work with preview links, merge when approved. |
+| `tr-upgrade-rendering.md` | "upgrade rendering", render version behind latest | Screenshot-compares every page at the current and target render version, reports differences, upgrades with approval. |
 | `tr-content-write.md`  | "write a page about…", "draft copy for…"            | Discovery first (settings + sample pages), then drafts in the site's voice, previews, iterates. |
 | `tr-images.md`         | "make an image / hero / illustration", media uploads | Generates locally → signed upload URL → metadata patch → embed. |
 

package/skills/tr-brand.md

@@ -159,6 +159,16 @@ replace_partial partial_id="header" html_content="<updated HTML>"
 
 Same for footer.
 
+## Step 5b — Express the typography as styles
+
+Colours and fonts are only half the brand. Put the type scale, weights,
+spacing and recurring treatments into the site's named styles (`list_styles`,
+`update_style`, `create_style`): body text and H1–H6 apply everywhere; the
+eyebrow, lead, quote, buttons and section rhythm are chosen per block with
+`style_id`. Set phone values in `base` and grow them in `at.tablet` and
+`at.desktop`. Prefer this to custom CSS: editors can see and change styles,
+and every page follows.
+
 ## Step 6 — Custom CSS for advanced tokens (optional)
 
 If the brand needs things beyond the 7 base tokens — e.g. a gradient,

package/skills/tr-content-write.md

@@ -37,6 +37,23 @@ Read the actual HTML of an existing page. Note:
 - Length conventions (do existing pages run 200 words or 2000?)
 - Whether internal links use absolute or relative URLs
 
+`list_styles` too: use the site's named styles (`style_id` on heading, text,
+list, button and section blocks) for eyebrows, leads, quotes and buttons. If a
+treatment you need could recur and no style fits, create one rather than
+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">`). 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
+block (`core/global_block`) for content that must stay identical on every
+page, such as a shared call to action; don't paste copies of it.
+
 ### 2. Ask for the brief
 
 If the user hasn't told you, ask: