@typeroll/mcp-server 0.45.60 → 0.45.62

package/dist/server.js

@@ -165,8 +165,11 @@ The full playbook ships with this server — use it:
    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].
+   is its eyebrow field. A block's sub-elements (links, a hero's heading or
+   buttons) are parts (read_block_type): style them site-wide with a style's
+   parts or on one block with data.part_styles. 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,

package/dist/tools/block-types.js

@@ -39,6 +39,7 @@ const AUTHORING_GUIDE = 'Two kinds of site block type. COMPOSED (preferred): `co
     'TEMPLATE (advanced, when existing blocks cannot express the markup): `template` is HTML with {{field}} (escaped), {{{field}}} (raw: richtext fields and derived …_svg / …_html only), {{#field}}…{{/field}} (shown when set), {{^field}}…{{/field}} (shown when empty), {{#each items}}…{{/each}} (per array item; names resolve against the item first; {{@index}}, {{@number}}, {{@first}}, {{@last}}), {{#link field class="…"}}…{{/link}} (wraps the body in a safe <a href rel target> when the link resolves), plus {{children}} / {{slot:NAME}} for containers. ' +
     'Fields: text, textarea, richtext, image, icon (derived {name}_svg), select (options), boolean, number, url, link ({ page_id?, url?, new_tab? } — prefer page_id for a page on the Site, it survives slug changes; resolves to .href, .target, .rel), array (a repeating group: fields, item_label, min_items, max_items; nests 3 levels), object, style … each with name, type, label and optional help, required, default. ' +
     '`styles` is scoped to the block when written: every selector applies inside [data-block="<name>"], :scope is the block element itself, body/html/:root are refused; use the site\'s var(--color-*) and spacing tokens. The response returns `styles_compiled`, the CSS that ships. ' +
+    '`parts` names elements of the markup (a title, a button, links) so site styles can restyle them without CSS against the block: [{ name, label, selector, target }]. ' +
     'Unknown properties are errors. Every problem has a JSON-pointer `path` (and a `line` for markup/CSS); a 400 lists them all in `problems`, warnings come back in `warnings`. Call validate_block_type / preview_block_type first, and list_block_type_starters for complete examples. Needs WRITE permission on the Site; editors can author types as well as place them on pages.';
 const definitionShape = {
     label: z.string().optional().describe('Display label in the block picker.'),
@@ -61,6 +62,18 @@ const definitionShape = {
     template: z.string().optional().describe('Markup of a template type (instead of composition); see the section syntax above.'),
     styles: z.string().optional().describe('CSS scoped to the block. Write selectors for the block\'s own markup; :scope is the block element.'),
     script: z.string().optional().describe("Client-side JS shipped with the block (runs on the published site's own origin). Accepted under your API key's authority — the write is audit-logged. Prefer a composed type without script."),
+    parts: z.array(z.object({
+        name: z.string().describe('Stable name: a-z, 0-9 and _ (max 32), starting with a letter. Never rename a part in use: part_styles and styles refer to it.'),
+        label: z.string().describe('Shown in the editor, e.g. "Primary button".'),
+        selector: z.string().describe('The element(s), relative to the block root: tags, .classes, [attributes], structural pseudo-classes (:first-child, :nth-child()) and combinators, up to four comma-separated. No braces, at-rules, pseudo-elements or :hover/:focus (hover comes from the style).'),
+        target: z.enum(['text', 'heading', 'list', 'button', 'container', 'link', 'image']).describe('The kind of style that fits the part.'),
+        style_field: z.string().optional().describe('A `style` field of this type that already chooses the part\'s style per instance; part_styles then skips the part.'),
+        color: z.string().optional().describe('Colour token of the part\'s text in the block\'s CSS, for contrast checks (default text).'),
+        background: z.string().optional().describe('Colour token behind the part, for contrast checks (default the site background).'),
+        background_field: z.string().optional().describe('A `color` field of this type holding the background behind the part.'),
+        decorative: z.boolean().optional().describe('The part holds no text (an overlay, a layout row): no text contrast check.'),
+        min_render_version: z.number().int().optional(),
+    }).passthrough()).optional().describe('Named sub-elements (at most 16) that site styles can reach: site-wide through a style\'s `parts` ("<type id>.<part>"), on one block through its `part_styles` data, a field added automatically when a part has no style_field. Mainly for template types; a warning names a selector class the template never writes. Composed types\' inner blocks keep their own parts. Replaces the whole list on update.'),
 };
 export const blockTypeTools = [
     {
@@ -128,7 +141,7 @@ export const blockTypeTools = [
     },
     {
         name: 'read_block_type',
-        description: "Full definition of one block type: the field schema, and its composition (composed types) or template (template types), styles with `styles_compiled` (the scoped CSS that ships), and optional script. Use this when list_block_types' summary isn't enough — before add_block on an unfamiliar block, or before update_block_type.",
+        description: "Full definition of one block type: the field schema, its `parts` (named sub-elements such as core/rich_heading's links or core/hero's heading and buttons, each with a target; style one with a style's `parts` site-wide or the block's `data.part_styles`, or the part's own style_field), and its composition (composed types) or template (template types), styles with `styles_compiled` (the scoped CSS that ships), and optional script. Use this when list_block_types' summary isn't enough — before add_block on an unfamiliar block, or before update_block_type.",
         inputSchema: {
             type_id: z.string(),
             version: versionParam,
@@ -220,7 +233,7 @@ export const blockTypeTools = [
     },
     {
         name: 'update_block_type',
-        description: "Change a site block type (core/* types are read-only). Needs WRITE permission. schema, composition, template and styles replace wholesale when sent; other properties merge. Changing a type in use: to RENAME a field, send the new schema with `renames` ({ \"title\": \"heading\", \"items.label\": \"text\" } — dotted paths of the OLD names, new name of the field) and the data moves in every block that uses the type (saved pages and drafts, page templates, header/footer/global blocks, block templates, other block types, repeater items), after a revision of each changed page; a composed type's own {{props.…}}/{{item.…}} bindings follow unless you send a composition. Removing or retyping a field that holds data answers 409 with the affected uses until you resend with confirm_data_loss: true (ask the user first). Returns { block_type, warnings, impact: { usages, renamed, removed, retyped } }. The same validation as create_block_type applies.",
+        description: "Change a site block type (core/* types are read-only). Needs WRITE permission. schema, composition, template, styles and parts replace wholesale when sent; other properties merge. Changing a type in use: to RENAME a field, send the new schema with `renames` ({ \"title\": \"heading\", \"items.label\": \"text\" } — dotted paths of the OLD names, new name of the field) and the data moves in every block that uses the type (saved pages and drafts, page templates, header/footer/global blocks, block templates, other block types, repeater items), after a revision of each changed page; a composed type's own {{props.…}}/{{item.…}} bindings follow unless you send a composition. Removing or retyping a field that holds data answers 409 with the affected uses until you resend with confirm_data_loss: true (ask the user first). Returns { block_type, warnings, impact: { usages, renamed, removed, retyped } }. The same validation as create_block_type applies.",
         inputSchema: {
             type_id: z.string().describe('Block type id (a site type). Cannot be a core/* block.'),
             ...definitionShape,

package/dist/tools/page-blocks.js

@@ -31,6 +31,20 @@ const targetSchema = z.object({
 function v(version) {
     return version ? { version } : undefined;
 }
+/**
+ * Write tools answer compactly by default: the changed block, its parent id,
+ * slot index and position, has_unsaved_changes and any warnings, instead of
+ * the container's whole tree (tens of kB for an article). `response: "tree"`
+ * asks for the tree. Sent as a query parameter, which an older Core ignores
+ * and answers with the tree, where an unknown body key would be refused.
+ */
+const responseParam = z.enum(['summary', 'tree']).optional().describe('Answer shape. "summary" (default): the changed block, parent_id, slot_index, position, has_unsaved_changes and warnings. "tree": the whole block tree of the container.');
+function writeQuery(version, response) {
+    return { ...v(version), response: response ?? 'summary' };
+}
+/** Block parts: per-instance part styles in block data. */
+const PART_STYLES = ' `data.part_styles` ({ "<part>": "<style id>" }) gives named parts of the block a style on this block only, replacing a site-wide part style; read_block_type lists the type\'s `parts` and their targets (parts with a style_field, such as core/heading eyebrow → eyebrow_style_id, use that field instead). The map is replaced whole on update; null removes it. A part the block cannot style is 400 `unknown_field` at data.part_styles.<part> with suggestions; a value that is not a style id is `field_type_mismatch`; a style the site lacks (`unknown_style`) or of the wrong kind (`style_target_mismatch`) is refused with the styles that fit, as is text that fails both APCA and WCAG 2 AA on the part\'s background (`part_style_contrast`; an APCA-only miss is a warning).';
+const COMPACT_ANSWER = ' Answers with the changed block, `parent_id`, `slot_index`, `position` and `has_unsaved_changes` (the working copy differs from the saved content); pass `response: "tree"` for the whole tree, or call get_page_blocks.';
 /**
  * Resolve a (target | page_id) pair to a REST path prefix. Pages keep
  * routing through /pages/{id}/blocks for back-compat with older callers;
@@ -64,7 +78,7 @@ export const pageBlockTools = [
     },
     {
         name: 'add_block',
-        description: 'Insert a block into a container (page, partial, or page template). BUFFER MODEL: block mutations on pages/partials edit the unsaved DRAFT — commit_working_copy is the explicit save. With no parent_id, inserts at the top level of the container. Otherwise inserts as a child (or into a slot for slot-containers). Position defaults to "end". Slot containers (core/columns, core/tabs — container: "slots"): slot_index picks the slot (0-based; defaults to 0) and works even if the parent instance has no slots array yet; a freshly added slot container gets its slots initialised to the type\'s arity. You can also pass the whole subtree inline via block.slots: [[...],[...]]. Pass `target: { kind: "partial", id: "header" }` to drop a block into the header on every page, etc. `page_id` is the legacy shorthand.',
+        description: 'Insert a block into a container (page, partial, or page template). BUFFER MODEL: block mutations on pages/partials edit the unsaved DRAFT — commit_working_copy is the explicit save. With no parent_id, inserts at the top level of the container. Otherwise inserts as a child (or into a slot for slot-containers). Position defaults to "end". Slot containers (core/columns, core/tabs — container: "slots"): slot_index picks the slot (0-based; defaults to 0) and works even if the parent instance has no slots array yet; a freshly added slot container gets its slots initialised to the type\'s arity. You can also pass the whole subtree inline via block.slots: [[...],[...]]. Pass `target: { kind: "partial", id: "header" }` to drop a block into the header on every page, etc. `page_id` is the legacy shorthand. A `data` key that no field of the block\'s type declares (read_block_type) is rejected with 400 `unknown_field`, for the block and every child; nothing is written, and `unknown_fields[].suggestions` says where it belongs (e.g. `item_overrides.<key>` for an item-block field on a repeater or its aliases, or the closest field names).' + PART_STYLES + COMPACT_ANSWER + ' `added_id` is the new block\'s id.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
@@ -72,6 +86,7 @@ export const pageBlockTools = [
             parent_id: z.string().optional().nullable(),
             slot_index: z.number().int().min(0).optional(),
             position: z.number().int().min(0).optional(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -81,18 +96,18 @@ export const pageBlockTools = [
                 parent_id: args.parent_id,
                 slot_index: args.slot_index,
                 position: args.position,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },
     {
         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. 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.',
+        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. Send values in the field\'s type (numbers as numbers); a value the block will not render comes back in `warnings` (`field_type_mismatch`) with its path. A `null` value removes that key from data (the field renders its default); use it to clean up a key stored by mistake. A written key that no field of the block\'s type declares is rejected with 400 `unknown_field` and nothing is written; `unknown_fields[].suggestions` says where it belongs: on core/repeater and its aliases (core/testimonials, core/page_list, ...) a field of the item block goes in `item_overrides.<key>`, otherwise the closest field names.' + PART_STYLES + COMPACT_ANSWER,
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
             block_id: z.string(),
-            data: z.record(z.unknown()).optional(),
+            data: z.record(z.unknown()).optional().describe('Field values to merge into block.data. null removes the key.'),
             style_overrides: z.object({
                 spacing_before: z.string().optional(),
                 spacing_after: z.string().optional(),
@@ -100,6 +115,7 @@ export const pageBlockTools = [
                 custom_class: z.string().optional(),
                 html_id: z.string().optional(),
             }).optional(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -108,13 +124,13 @@ export const pageBlockTools = [
                 block_id: args.block_id,
                 data: args.data,
                 style_overrides: args.style_overrides,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },
     {
         name: 'move_block',
-        description: 'Reparent or reorder a block inside its container. target_parent_id=null moves to top level. For slot containers, target_slot_index picks the slot. Cycles (moving a block into its own descendant) are rejected. Works for pages, partials, and templates.',
+        description: 'Reparent or reorder a block inside its container. target_parent_id=null moves to top level. For slot containers, target_slot_index picks the slot. Cycles (moving a block into its own descendant) are rejected. Works for pages, partials, and templates.' + COMPACT_ANSWER + ' The location is where the block now sits.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
@@ -122,6 +138,7 @@ export const pageBlockTools = [
             target_parent_id: z.string().optional().nullable(),
             target_slot_index: z.number().int().min(0).optional(),
             target_position: z.number().int().min(0).optional(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -131,61 +148,61 @@ export const pageBlockTools = [
                 target_parent_id: args.target_parent_id,
                 target_slot_index: args.target_slot_index,
                 target_position: args.target_position,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },
     {
         name: 'remove_block',
-        description: 'Remove a block and everything inside it from its container. Works for pages, partials, and templates.',
+        description: 'Remove a block and everything inside it from its container. Works for pages, partials, and templates. Answers with `removed_id`, the `parent_id`, `slot_index` and `position` it was removed from and `has_unsaved_changes`; pass `response: "tree"` for the whole remaining tree.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
             block_id: z.string(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const path = pathFor(args.target, args.page_id);
-            const query = { block_id: args.block_id };
-            if (args.version)
-                query.version = args.version;
-            const res = await client.del(siteId, path, query);
+            const res = await client.del(siteId, path, { block_id: args.block_id, ...writeQuery(args.version, args.response) });
             return ok(res);
         }),
     },
     {
         name: 'duplicate_block',
-        description: 'Clone a block (subtree included) and insert the copy directly after the original within the same container. Returns the duplicate\'s new id. Useful for "add another card to this feature grid" — duplicate the existing one and then `update_block` on the new id to change its data. Works for pages, partials, and templates.',
+        description: 'Clone a block (subtree included) and insert the copy directly after the original within the same container. Returns the duplicate\'s new id. Useful for "add another card to this feature grid" — duplicate the existing one and then `update_block` on the new id to change its data. Works for pages, partials, and templates.' + COMPACT_ANSWER + ' `duplicate_id` is the copy\'s id; `block` is the copy.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
             block_id: z.string(),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const path = pathFor(args.target, args.page_id);
             const res = await client.post(siteId, `${path}/duplicate`, {
                 block_id: args.block_id,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },
     {
         name: 'set_block_responsive',
-        description: 'Set a per-breakpoint value on one responsive field of a block (in any container — page, partial, or template). The renderer reads { mobile, tablet, laptop, desktop, wide } objects on any field marked responsive in the BlockType schema (use read_block_type to see which). Mobile-first inheritance: missing breakpoints inherit upward. Pass a scalar value to clear responsive back to a single value. Example: setting `cols` on a feature_grid to { mobile: 1, tablet: 2, desktop: 3 } renders 1-col on phones, 2-col on tablets, 3-col on desktop+.',
+        description: 'Set a per-breakpoint value on one responsive field of a block (in any container — page, partial, or template). The renderer reads { mobile, tablet, laptop, desktop, wide } objects on any field marked responsive in the BlockType schema (use read_block_type to see which). Mobile-first inheritance: missing breakpoints inherit upward. Pass a scalar value to clear responsive back to a single value. Example: setting `cols` on a feature_grid to { mobile: 1, tablet: 2, desktop: 3 } renders 1-col on phones, 2-col on tablets, 3-col on desktop+. A field the block type does not declare is rejected with 400 `unknown_field`.' + COMPACT_ANSWER,
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),
             block_id: z.string(),
             field: z.string().describe('Field name (must be marked responsive in the BlockType schema).'),
             value: z.any().describe('Scalar (applies to all BPs) or { mobile?, tablet?, laptop?, desktop?, wide? }.'),
+            response: responseParam,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const path = pathFor(args.target, args.page_id);
             const res = await client.post(siteId, `${path}/responsive`, {
                 block_id: args.block_id, field: args.field, value: args.value,
-            }, v(args.version));
+            }, writeQuery(args.version, args.response));
             return ok(res);
         }),
     },

package/dist/tools/pages.js

@@ -75,6 +75,10 @@ export const pageTools = [
             'and seeds the tree with a heading + prose block so the editor is never blank. ' +
             'Pass html_content (or content_mode="html") to opt into raw-HTML mode instead. ' +
             'Slug is derived from the title when omitted. Default status is "draft". ' +
+            'Address conflicts: an explicit slug or path that another page already uses (drafts and unsaved drafts included) ' +
+            'fails with 409 { code: "slug_in_use" | "path_in_use", details: { page_id, path } } — edit that page or choose another slug; ' +
+            'the address is never changed silently. Only a title-derived slug is numbered (e.g. "tack" → "tack-2"), and the response then ' +
+            'carries warnings: [{ code: "slug_adjusted", requested, slug, path, conflicting_page_id }]. ' +
             'Homepage convention: pass slug="" (empty string) or omit slug and set title to "Home"; ' +
             'the server stores it under id "home" with slug "". ' +
             'Slug must be a single path segment (no slashes). For nested URLs like ' +
@@ -88,7 +92,7 @@ export const pageTools = [
             title: z.string().min(1),
             content_type: z.string().optional().describe('Content type ID; defaults to page.'),
             fields: z.record(z.unknown()).optional().describe('Custom field values defined by the content type.'),
-            slug: z.string().optional().describe('URL slug — single path segment, no slashes (e.g. "about", "kontakt"). Empty string "" = homepage. For nested URLs set the `path` field explicitly — `slug` stays a leaf id.'),
+            slug: z.string().optional().describe('URL slug — single path segment, no slashes (e.g. "about", "kontakt"). Empty string "" = homepage. For nested URLs set the `path` field explicitly — `slug` stays a leaf id. Already in use → 409 slug_in_use naming the existing page; omit it to derive one from the title (numbered with a slug_adjusted warning on conflict).'),
             path: z.string().optional().describe('Optional explicit URL path for nested pages (e.g. "/erbjudanden/sommar-2026"). When set, takes precedence over slug for routing. Must start with "/", lowercase a-z/0-9/-/_/ only, no "..", no "//", no trailing slash. Slug is still required as the leaf id but two pages CAN share a slug under different paths.'),
             content_mode: z.enum(['blocks', 'html']).optional().describe('Default "blocks". "blocks" stores a Block[] tree (the modern default — supports the full ~40-block library, page templates, and the responsive system). "html" stores raw markup in html_content (legacy path, still fully supported for imported content or hand-written HTML). Passing html_content without content_mode also opts into "html".'),
             html_content: z.string().optional().describe('Body HTML — only used when content_mode="html".'),
@@ -224,11 +228,11 @@ export const pageTools = [
     },
     {
         name: 'clone_page',
-        description: 'Duplicate an existing page under a new title + slug. Use this when you want a near-copy of an existing page as the starting point (e.g. duplicate "Privatflytt" → "Privatflytt Härnösand"). The new page is created as a draft regardless of the source\'s status. Returns the created page.',
+        description: 'Duplicate an existing page under a new title + slug. Use this when you want a near-copy of an existing page as the starting point (e.g. duplicate "Privatflytt" → "Privatflytt Härnösand"). The new page is created as a draft regardless of the source\'s status. Returns the created page. Same address rule as create_page: a slug you pass that is already in use fails with 409 slug_in_use (details: { page_id, path }); a slug derived from the title is numbered and reported in warnings (code slug_adjusted).',
         inputSchema: {
             source_page_id: z.string(),
             title: z.string().min(1).describe('Title for the new page.'),
-            slug: z.string().optional().describe('Slug for the new page. Omit to auto-derive from title.'),
+            slug: z.string().optional().describe('Slug for the new page. Omit to derive it from the title. A slug already in use is refused (409 slug_in_use), never changed.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -268,7 +272,7 @@ export const pageTools = [
                 image_sizes_default: src.image_sizes_default,
                 status: 'draft',
             };
-            if (args.slug)
+            if (args.slug !== undefined)
                 body.slug = args.slug;
             if (typeof src.path === 'string' && src.path) {
                 // Keep an explicit route's directory, never its old final segment.
@@ -282,7 +286,9 @@ export const pageTools = [
                 segments.pop();
                 body.path = '/' + [...segments, slug.replace(/^\/+|\/+$/g, '')].join('/');
             }
-            // 3. Create. The API auto-uniques generated routes; explicit conflicts return 409.
+            // 3. Create. An explicit slug or path that is taken fails with 409
+            //    (slug_in_use / path_in_use); a title-derived slug is numbered and
+            //    reported in `warnings`.
             const created = await client.post(siteId, 'pages', body, v(args.version));
             return ok(created);
         }),

package/dist/tools/reusable-blocks.js

@@ -49,7 +49,7 @@ export const reusableBlockTools = [
     },
     {
         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.',
+        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, part_styles) 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.'),

package/dist/tools/settings.js

@@ -76,8 +76,8 @@ export const settingsTools = [
             }).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(),
+            colors: z.record(z.string().nullable()).optional().describe('Palette: primary, secondary, accent, background, surface, text, text_light (shallow-merged). Optional on_primary, on_secondary, on_accent set the text colour on that theme colour (buttons, badges, tabs, call-to-action sections, styles using the on_* tokens) as a hex colour such as "#ffffff"; null returns to the automatic black or white (chosen by APCA from render version 8, by the WCAG 2 ratio before). A chosen on_* colour applies on every render version. The response lists `on_colors` with each one\'s APCA Lc and WCAG 2 ratio; a choice below APCA Lc 60 (button text, 16px/600) is kept and returned as a warning. Prefer the automatic choice unless the brand specifies a colour.'),
+            fonts: z.record(z.unknown()).optional().describe('heading, body (Google Fonts family or "system"), size_base (px) and smoothing: "auto" (browser default) or "antialiased" (thinner text on macOS, for light text on dark backgrounds); null clears smoothing. Unset smoothing is auto from render version 6.'),
             contact: z
                 .object({
                 email: z.string().optional(),

package/dist/tools/styles.js

@@ -1,13 +1,16 @@
 // 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.
+// block's `style_id` field. A style can also style a block PART (a named
+// sub-element such as core/rich_heading's links): site-wide through the
+// style's `parts`, on one block through its `part_styles` data. 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 COLOR_HELP = 'A palette token (primary, secondary, accent, background, surface, text, text_light), the text colour for a palette background (on_primary, on_secondary, on_accent: the site\'s colors.on_* when set, else black or white, whichever reads better), 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({
@@ -33,6 +36,9 @@ const propsSchema = z.object({
         color: color.optional(),
         sides: z.enum(['all', 'top', 'right', 'bottom', 'left', 'block', 'inline']).optional(),
     }).optional(),
+    opacity: z.number().min(0).max(1).optional().describe('0 (invisible) to 1 (opaque)'),
+    shadow: z.enum(['none', 'sm', 'md', 'lg']).optional().describe('Shadow preset; none removes a shadow the block draws'),
+    gap: z.string().optional().describe('Space between the children of a flex or grid element: one CSS length, or row and column'),
 }).describe('Style properties. Mobile-first: `base` applies everywhere, `at.<breakpoint>` from that width up.');
 const atSchema = z.object({
     tablet: propsSchema.optional(),
@@ -44,24 +50,26 @@ 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).'),
+    targets: z.array(z.enum(['text', 'heading', 'list', 'button', 'container', 'link', 'image'])).optional()
+        .describe('Kinds of element that can select this style: through a block\'s style_id (text = core/prose, heading = core/heading and core/rich_heading, list, button, container = core/section and core/container) and through a block part with that target (link and image exist for parts, e.g. core/rich_heading.link, core/hero.media).'),
     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.'),
+    parts: z.array(z.string()).optional()
+        .describe('Block parts this style applies to SITE-WIDE, on every instance, as "<block type>.<part>" (e.g. "core/rich_heading.link", "core/hero.primary_button"); read_block_type lists a block\'s `parts` with their targets. The style\'s targets must include each part\'s target; a part takes one site-wide style; not for element roles (body, h1–h6, link). Unknown parts are refused with the closest names. Precedence, lowest first: the block\'s own CSS and fields; this site-wide part style, replaced on one block by its `data.part_styles` choice; a style class on the element itself (a heading\'s eyebrow_style_id, a button\'s style_id).'),
 };
 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.',
+        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, contrast/library problems and readability warnings (both APCA Lc and WCAG 2 ratio). 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.',
+        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 contrast against its background is measured with APCA by use, size and weight (body text Lc 75; secondary/small text Lc 60; headings, eyebrows and buttons Lc 60 from 16px at weight 600+, Lc 45 from 24px bold or 36px; smaller or lighter non-body text Lc 75) and with the WCAG 2 ratio. Text that fails both is refused; text below its APCA level that meets WCAG 2 AA (4.5:1, 3:1 for ≥24px or bold ≥18.7px) is saved and returned in `warnings`. Never light grey on white. To restyle a sub-element of a block (rich-heading links, a hero\'s buttons or image), list it in `parts` (site-wide) or choose the style in that block\'s `data.part_styles`.',
         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,
@@ -75,7 +83,7 @@ export const styleTools = [
     },
     {
         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.',
+        description: 'Update a style. `base`, `hover` and each breakpoint in `at` merge property by property (pass null to remove one); name, targets, description, css and parts replace (parts: [] removes the style from every part). 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(),
@@ -86,6 +94,7 @@ export const styleTools = [
             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(),
+            parts: styleFields.parts,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -101,7 +110,7 @@ export const styleTools = [
     },
     {
         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.',
+        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. A standard style whose palette colour is unreadable on the background is added with the body text colour instead; `adjusted` lists those and `warnings` says what changed, with the measures — tell the user.',
         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/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.60';
+export const VERSION = '0.45.62';

package/package.json

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

package/skills/tr-brand.md

@@ -51,6 +51,14 @@ A Typeroll site uses 7 color tokens:
 | `text` | Body copy. | ≥4.5:1 contrast ratio on `background`. |
 | `text_light` | Secondary labels, captions, placeholders. | ≥3:1 on `background`. |
 
+Text on `primary`, `secondary` and `accent` (buttons, badges, tabs,
+call-to-action sections, the `on_*` style tokens) is black or white
+automatically, chosen by APCA from render version 8. When the brand
+specifies it, set `colors.on_primary`, `colors.on_secondary` or
+`colors.on_accent` (a hex colour; `null` returns to automatic). The response
+lists `on_colors` with each one's APCA Lc and WCAG 2 ratio: button text needs
+Lc 60, body text Lc 75. Do not compensate with custom CSS.
+
 **Palette recipes by mood:**
 
 *Nordic / minimal:*

package/skills/tr-custom-blocks.md

@@ -87,6 +87,13 @@ When the markup cannot be built from blocks, use `template` instead of
 `{{@number}}`, `{{@first}}`, `{{@last}}`, and `{{#link field class="x"}}…{{/link}}`.
 A type has a composition or a template, never both.
 
+Declare `parts` for the elements of the markup a site may want to restyle:
+`parts: [{ name: "title", label: "Title", selector: ".icon-list-title", target: "heading" }]`.
+Selectors are tags, classes, attributes and structural pseudo-classes, never
+`:hover` or `::before`. Styles then reach the part site-wide
+(`parts: ["icon_list.title"]` on the style) or on one block
+(`data.part_styles: { title: "card-title" }`, a field added automatically).
+
 ## Changing a type in use
 
 - Rename a field with `renames: { "old": "new" }` (`"items.old": "new"` inside a

package/skills/tr-migrate-wp.md

@@ -73,6 +73,9 @@ Then the ordinary preconditions:
   appearance unless a redesign is explicitly requested.
 - If the target already has content, you must NOT clobber it — always
   `list_pages` first and only write to slugs that don't already exist.
+  Pass the slug explicitly: `create_page` then refuses an address that is
+  already in use (409 `slug_in_use` naming the existing page) instead of
+  numbering it.
 
 ## Recipe
 

package/skills/tr-migration-evidence.md

@@ -62,6 +62,41 @@ behavior or other semantics unsupported by the chosen block: record the gap
 and use a supported composition or stop for native support.
 Do not apply a template to hundreds of Pages until its prototype passes.
 
+## Report platform gaps, do not patch them
+
+Matching the source sometimes needs something the platform does not offer.
+Never close that with site or page `custom_css`, raw HTML or a generic custom
+block: the next site hits the same gap and the workaround breaks on the next
+Core change. Record it and report it instead. Check these five causes first,
+because each has looked like a site problem:
+
+1. **A platform default no setting reaches.** Compare computed text rendering
+   and base styles on `body`, links and headings (`-webkit-font-smoothing`,
+   `line-height`, `text-decoration`) with the source. If the difference comes
+   from Typeroll's base CSS, check Site settings and the render versions first
+   (`read_site_settings` → `render.upgrades`).
+2. **A replaced control ignores the block's settings.** A capability can swap a
+   field for a provider element (address suggestions). Compare that control
+   with a plain field in the same block: border, radius, height, background,
+   text colour, font, placeholder, icon and colour scheme in light and dark mode.
+3. **A missing part.** The source has a part (icon, badge, second label) the
+   block has no field for. Check `read_block_type` for a field before
+   concluding it is missing.
+4. **A value that is stored and ignored.** Read every write response's
+   `warnings` (`field_type_mismatch`, `unknown_style_override`): a wrong type or
+   key is saved and never rendered. Measure the computed result, not the
+   read-back.
+5. **Preview differs from the published page.** A setting that shows in preview
+   but not in a fresh hosted build is a publication gap; report both URLs.
+
+Report each gap with: site ID, Organization, Core version and render version;
+source and target URL; viewport (actual `innerWidth`), browser and DPR; the
+block ID and type or the setting; source and target computed values; what is
+missing, ignored or wrong; the proposed setting or fix; and acceptance
+criteria a reviewer can measure. State that no workaround CSS is in place.
+Mark the affected recipe `waiting_for_native_support`, continue independent
+work, and verify against the source again after the release.
+
 ## Separate files, addresses and business behavior
 
 Inventory both file bytes and every discovered historical asset URL, including

package/skills/tr-new-site.md

@@ -140,7 +140,9 @@ Set the site's look as named styles before building any page:
    `apply_standard_styles`.
 2. Adjust them to the brand with `update_style`: the font, the type scale and
    spacing for `base` (phones) and `at.tablet`/`at.desktop`, and colours from
-   palette tokens. Keep text at WCAG AA contrast; failing styles are refused.
+   palette tokens. Keep text readable: contrast is checked with APCA and
+   WCAG 2; text that fails both is refused, and text below its APCA level
+   comes back as a warning.
 3. Add a named style for every look the design repeats: a card title, a price
    note, a highlighted section, a CTA button variant. Use the site's language
    for names.
@@ -148,6 +150,12 @@ Set the site's look as named styles before building any page:
 Pages then choose styles with each block's `style_id` field. A per-block
 font size, colour or class is only for something clearly unique.
 
+To change a sub-element a block styles itself (the underline on formatted
+heading links, a hero's heading or buttons), use its parts:
+`read_block_type` lists them. A style with `parts: ["core/rich_heading.link"]`
+applies to that part on every block; `data.part_styles` on one block replaces
+it there.
+
 ### 3. Header + footer partials
 
 **Start from the native preset — don't hand-roll navigation.** Read