@typeroll/mcp-server 0.45.45 → 0.45.47

package/dist/compact-tools.js

@@ -22,7 +22,7 @@ export function compactTools(catalog) {
         }),
         ...['read', 'write', 'admin'].map(effect => ({
             name: `call_${effect}_tool`, effect,
-            description: effect === 'read' ? 'Call a discovered read-only tool with its exact arguments. Does not accept write/admin tools.' : `Call a discovered ${effect} tool. May ${effect === 'admin' ? 'change app or email configuration, send a test email or activate releases' : 'save, delete, publish or otherwise change state'}. Inspect describe_tool first and follow the user’s authorization.`,
+            description: effect === 'read' ? 'Call a discovered read-only tool with its exact arguments. Does not accept write/admin tools.' : `Call a discovered ${effect} tool. May ${effect === 'admin' ? 'change app, email or block type configuration, send a test email or activate releases' : 'save, delete, publish or otherwise change state'}. Inspect describe_tool first and follow the user’s authorization.`,
             schema: { name: z.string().max(100), arguments: z.record(z.unknown()).default({}) },
             invoke: async (args) => {
                 const tool = byName.get(String(args.name));

package/dist/server.js

@@ -50,7 +50,7 @@ const PERM_RANK = { read: 0, write: 1, admin: 2 };
  * gate then checks `effect <= sitePermission`.
  *
  * Naming convention is followed by the tool modules: read paths are
- * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*` / `check_*`; everything else
+ * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*` / `check_*` / `find_*`; everything else
  * mutates.
  */
 function effectFor(name) {
@@ -101,8 +101,17 @@ function effectFor(name) {
         || name === 'set_email_settings'
         || name === 'delete_email_settings'
         || name === 'send_test_email'
-        || name === 'set_incoming_email_forwarding')
+        || name === 'set_incoming_email_forwarding'
+        // Block type authoring is site administration (the portal and the v1
+        // routes require admin); placing and editing blocks on pages stays write.
+        || name === 'create_block_type'
+        || name === 'update_block_type'
+        || name === 'delete_block_type'
+        || name === 'import_block_types')
         return 'admin';
+    // Compute an answer and write nothing, like the preview_* tools.
+    if (name === 'validate_block_type' || name.startsWith('find_'))
+        return 'read';
     if (name === 'diff_version')
         return 'read';
     if (name.startsWith('list_') ||

package/dist/tools/block-types.js

@@ -1,16 +1,18 @@
-// Block-type tools. Surface is wired in now so the future block editor
-// drops in without breaking integrations.
+// Block-type tools: discovery, authoring (validate, preview, create, update,
+// delete), usage, starters and .tcblocks packages. Every write goes through
+// the portal's one block type write path (shared validator, version chain,
+// rename migration), and authoring needs admin permission on the Site.
 import { z } from 'zod';
 import { ok, withErrorBoundary, versionParam } from './helpers.js';
 function v(version) {
     return version ? { version } : undefined;
 }
-// The per-block markup. These three fields dominate the payload size (a few
-// dozen blocks of template HTML + scoped CSS can exceed an agent's token
-// budget and get truncated), and an agent enumerating the library rarely
-// needs them — read_block_type fetches them for one block on demand. So
-// list_block_types omits them by default and returns a lightweight summary.
-const HEAVY_BLOCK_TYPE_FIELDS = ['template', 'styles', 'script'];
+// The per-block markup. These fields dominate the payload size (a few dozen
+// blocks of template HTML + scoped CSS can exceed an agent's token budget and
+// get truncated), and an agent enumerating the library rarely needs them —
+// read_block_type fetches them for one block on demand. So list_block_types
+// omits them by default and returns a lightweight summary.
+const HEAVY_BLOCK_TYPE_FIELDS = ['template', 'styles', 'styles_compiled', 'script', 'composition'];
 /** Strip the heavy markup fields from each block type in a `block-types`
  *  response, preserving the field `schema` and all light metadata. Defensive:
  *  if the shape isn't the expected `{ block_types: [...] }`, pass it through. */
@@ -25,18 +27,47 @@ function summariseBlockTypes(res) {
         if (!bt || typeof bt !== 'object')
             return bt;
         const copy = { ...bt };
+        if (Array.isArray(copy.composition) && copy.composition.length)
+            copy.composed = true;
         for (const field of HEAVY_BLOCK_TYPE_FIELDS)
             delete copy[field];
         return copy;
     });
     return { ...envelope, block_types: slim };
 }
+const AUTHORING_GUIDE = 'Two kinds of site block type. COMPOSED (preferred): `composition` is a tree of existing blocks ({ id, type, data, children? } — core/heading, core/text, core/prose, core/image, core/icon, core/button, core/container, core/grid, core/repeater …) and `schema` declares the props people edit when they place the block. Inner blocks read props through exact bindings as the WHOLE value: a heading\'s text "{{props.title}}"; a core/repeater with items "{{props.items}}" (an array prop) renders its children once per item, where "{{item.title}}" reads the item and "{{item.link.href}}" a link sub-value. Everything the inner blocks do (named styles, responsive settings, images, safe links, render versions) carries over. ' +
+    '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. ' +
+    '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 ADMIN permission on the Site; editors (write) place block types on pages and edit their fields.';
+const definitionShape = {
+    label: z.string().optional().describe('Display label in the block picker.'),
+    description: z.string().optional().describe('When to use this block type; shown to editors and agents (≤ 500 chars).'),
+    icon: z.string().optional().describe('Lucide icon name shown in the block picker.'),
+    category: z.enum(['layout', 'content', 'media', 'custom']).optional(),
+    container: z.union([
+        z.literal(true), z.literal(false),
+        z.enum(['slots', 'repeater', 'conditional']),
+    ]).optional().describe('Template types only. true renders {{children}}, slots fixed named slots, repeater loops over items, conditional show-if. A composed type is never a container; put a container block inside its composition.'),
+    slot_count: z.number().optional().describe('Required when container="slots". 1-8.'),
+    slot_labels: z.array(z.string()).optional(),
+    item_compatible: z.boolean().optional().describe('Mark true if this block is designed to render as a repeater item (no outer padding).'),
+    expand_to: z.object({
+        target: z.string(),
+        defaults: z.record(z.unknown()),
+    }).optional().describe('Alias mechanism — render as another block type with these defaults merged under authored data.'),
+    schema: z.array(z.unknown()).optional().describe('FieldDefinition[]: { name, type, label, help?, required?, default?, options? (select), fields? (array/object), item_label?, min_items?, max_items? }. Replaces the whole schema on update.'),
+    composition: z.array(z.unknown()).optional().describe('Block[] a composed type is built from. Bind data to props with "{{props.name}}" and, inside a core/repeater over an array prop, to items with "{{item.name}}" — always as the whole value.'),
+    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."),
+};
 export const blockTypeTools = [
     {
         name: 'export_block_types',
-        description: 'Pack custom block types into a .tcblocks zip (base64). When `ids` is omitted, every user-created block type is bundled. Useful for moving blocks between sites or backing them up — the returned zip is a portable package the import tool reads back.',
+        description: 'Pack site block types into a .tcblocks zip (base64). When `ids` is omitted, every block type the Site has (made in the portal, by an agent, or imported) is bundled. The package keeps every property — composition, template, styles and CSS scope, script, field help and list settings — so it moves between any Sites, in any Organization or Typeroll instance. import_block_types reads it back.',
         inputSchema: {
-            ids: z.array(z.string()).optional().describe('Specific block-type ids to include. Omit to export every user-created block.'),
+            ids: z.array(z.string()).optional().describe('Specific block-type ids to include. Omit to export every site block type.'),
             name: z.string().optional().describe('Package name (default: {site}-blocks).'),
             version: z.string().optional().describe('Package version written into the manifest (default: 1.0.0). This is the package semver, not a Site version — use version_branch for that.'),
             version_branch: versionParam,
@@ -60,26 +91,29 @@ export const blockTypeTools = [
     },
     {
         name: 'import_block_types',
-        description: 'Install block types from a .tcblocks package. Provide the zip as base64. Re-importing the same package overwrites existing blocks with the same id (package_name/block_name). Each imported BlockType may include arbitrary CSS and JS — the caller is responsible for trusting the source. Returns counts of created vs updated docs.',
+        description: 'Install block types from a .tcblocks package (zip as base64). Needs ADMIN permission on the Site. Each definition is checked by the same validator as create_block_type; a definition with errors is reported as failed and not written. On a name conflict `on_conflict` decides: skip (default) keeps the Site\'s type, rename imports it under a free name (references inside the package follow), replace overwrites it. Returns `results` per type (created, renamed, replaced, skipped, failed with problems) and counts. Imported types may carry CSS and JS — only import packages you trust.',
         inputSchema: {
             zip_base64: z.string().describe('Base64-encoded .tcblocks zip.'),
+            on_conflict: z.enum(['skip', 'rename', 'replace']).optional().describe('What to do when the Site already has a block type with the same name. Default skip.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const v = args.version ? { version: args.version } : undefined;
-            const res = await client.post(siteId, 'blocks/import', { zip_base64: args.zip_base64 }, v);
+            const res = await client.post(siteId, 'blocks/import', {
+                zip_base64: args.zip_base64,
+                ...(args.on_conflict ? { on_conflict: args.on_conflict } : {}),
+            }, v(args.version));
             return ok(res);
         }),
     },
     {
         name: 'list_block_types',
-        description: 'Discover every block type usable on this site. Returns ALL of them in one list: core blocks (id like "core/section", always available), custom blocks (origin: "user", created in the portal), and third-party blocks (origin: "third_party", imported from .tcblocks packages). Call this FIRST when starting block-mode work — never hardcode block ids; the available set is per-site. By default this is a LIGHTWEIGHT SUMMARY: each entry has id, label, category, icon, container/slot info, origin, and the full field schema (name/type/label/required/options/default) — everything you need to pick a block and call add_block — but NOT the render-time markup. The per-block template HTML, scoped styles, and script are omitted so the list stays within token budget no matter how large the library grows; fetch them for a single block with read_block_type, or pass full:true to inline them for every block (can be very large).',
+        description: 'Discover every block type usable on this site. Returns ALL of them in one list: core blocks (id like "core/section", always available), site block types (origin "user" from the portal, "ai" from an agent) and third-party blocks (origin "third_party", imported from .tcblocks packages). Call this FIRST when starting block-mode work — never hardcode block ids; the available set is per-site. By default this is a LIGHTWEIGHT SUMMARY: id, label, description, category, icon, container/slot info, origin, `composed: true` for composed types, and the full field schema — everything you need to pick a block and call add_block — but NOT the template, composition, styles or script. Fetch those for one block with read_block_type, or pass full:true to inline them for every block (can be very large).',
         inputSchema: {
-            include_core: z.boolean().optional().describe('Default true. Set false to get only custom + third-party (rarely needed).'),
+            include_core: z.boolean().optional().describe('Default true. Set false to get only the site\'s own and third-party types.'),
             full: z
                 .boolean()
                 .optional()
-                .describe("Default false. When true, include each block type's template HTML, styles CSS, and script inline — the full doc. Large; prefer read_block_type for one block's markup."),
+                .describe("Default false. When true, include each block type's template, composition, styles and script inline — the full doc. Large; prefer read_block_type for one block."),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -94,7 +128,7 @@ export const blockTypeTools = [
     },
     {
         name: 'read_block_type',
-        description: "Full schema for one block type. Returns the BlockType doc with template, styles, optional script, and the field-definitions array. Use this when list_block_types' summary isn't enough — e.g. before add_block on a custom block whose data fields you haven't seen.",
+        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.",
         inputSchema: {
             type_id: z.string(),
             version: versionParam,
@@ -106,7 +140,7 @@ export const blockTypeTools = [
     },
     {
         name: 'find_pages_using_block_type',
-        description: 'Pages whose block tree contains this block type. Empty for HTML-mode sites (the default today); fills in once block-mode pages exist.',
+        description: 'Everything that uses a block type, on every surface: `pages` (saved block pages and drafts — `sources` says which), `templates` (page templates), `partials` (header, footer, global blocks), `block_templates`, and `block_types` (other site block types built from it). Repeaters that render the type as their item_block count, and a use through another block type names it in `via`. `total` sums the lists; delete_block_type is refused while it is above zero. Call it before changing or removing fields of a type in use.',
         inputSchema: {
             type_id: z.string(),
             version: versionParam,
@@ -116,36 +150,62 @@ export const blockTypeTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'list_block_type_starters',
+        description: 'Built-in starting points for a new block type: complete composed definitions (icon list, feature cards, numbered steps) with fields, composition and scoped CSS. Adapt one (rename it, change fields) and pass it to create_block_type — it is the quickest way to a valid composed type.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'block-types/starters');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'validate_block_type',
+        description: `Check a block type definition without saving it, with the exact validator create_block_type and update_block_type use. Pass the whole definition, or with type_id a patch to that stored type (renames are checked too). Returns { ok, problems, merged }: every error and warning with a JSON-pointer path (e.g. /schema/0/fields/2/name, /composition/0/children/1/data/text) and a line for markup and CSS, and the definition as it would be stored. Writes nothing. ${AUTHORING_GUIDE}`,
+        inputSchema: {
+            definition: z.record(z.unknown()).describe('The block type definition (as for create_block_type), or a patch when type_id is set.'),
+            type_id: z.string().optional().describe('Validate `definition` as a patch to this stored block type.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = {};
+            if (args.type_id)
+                query.type_id = args.type_id;
+            if (args.version)
+                query.version = args.version;
+            const res = await client.post(siteId, 'block-types/validate', args.definition, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'preview_block_type',
+        description: 'Render a block type definition that need not be saved, through the same preview renderer as the portal (the Site\'s render version, theme CSS, named styles, custom CSS, the other site block types, and the sanitizer). Without `data` the block shows sample values derived from its fields. Returns { ok, html, css, document, data, problems }: `html` is the block\'s markup as a page carries it, `css` the scoped block CSS that ships, `document` a standalone HTML page. A definition with errors is not rendered (ok:false, problems listed). Block scripts never run in a preview. Writes nothing.',
+        inputSchema: {
+            definition: z.record(z.unknown()).optional().describe('The block type definition, or a patch when type_id is set. Omit with type_id to preview the stored type.'),
+            type_id: z.string().optional().describe('Preview `definition` as a patch to this stored block type.'),
+            data: z.record(z.unknown()).optional().describe('Field values for the previewed block. Omit for sample data.'),
+            render_version: z.number().int().optional().describe('Render with this platform render version instead of the Site\'s own.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'block-types/preview', { ...body, definition: body.definition ?? {} }, v(version));
+            return ok(res);
+        }),
+    },
     // ─── BlockType authoring — CREATE / UPDATE / DELETE ──────────────────
-    // `script` runs with full DOM access in every visitor's browser. Through
-    // an API key it is ACCEPTED under the key holder's authority (same trust
-    // level as scripts_head) — the write is audit-logged and the response
-    // carries a notice naming the stored JS. Only the in-portal chat AI
-    // remains gated on Site.ai_scripts_enabled. Origin is stamped 'ai' so
-    // audit + UI distinguish agent-authored types.
+    // Admin permission on the Site, as in the portal. `script` runs with full
+    // DOM access in every visitor's browser. Through an API key it is ACCEPTED
+    // under the key holder's authority (same trust level as scripts_head) and
+    // the write is audit-logged. Only the in-portal chat never writes it.
+    // Origin is stamped 'ai' so audit + UI distinguish agent-authored types.
     {
         name: 'create_block_type',
-        description: "Create a new custom block type usable on this site. Origin is stamped 'ai' automatically. The block ships immediately to every page editor + the renderer's registry. Custom JS via `script` is accepted under your API key's authority (audit-logged; the response carries a notice) — review before deploy. This is the supported way to ship per-page JS: `<script>` written into page or block MARKUP is stripped by the renderer's sanitizer no matter which credential wrote it, so package the behaviour as a block type instead. Site-wide tags belong in settings.scripts_head / scripts_body_end. Returns the created BlockType. Responsive fields: mark a schema field `responsive: true` and expose it as style=\"--{field}:{{field}}\" on the outermost element so it can vary per breakpoint. If the value is directly usable CSS, read var(--{field}); if it's a token that maps to CSS (e.g. layout 'icon-left' → flex-direction:row) add a `responsive_css` map on the field ({ 'icon-left': '--dir: row;' }), otherwise per-breakpoint overrides won't take effect.",
+        description: `Create a block type for this Site when no core block (or block template) fits a recurring shape. Origin is stamped 'ai'; id = name. The type is available to every page editor immediately and reaches the live site with the next deploy. ${AUTHORING_GUIDE} Returns { block_type, warnings }; 409 when the name exists. A block type is the supported way to ship per-block JS (\`script\`): <script> written into page or block markup is always stripped by the sanitizer. Site-wide tags belong in settings.scripts_head / scripts_body_end.`,
         inputSchema: {
-            name: z.string().describe('Machine name (lowercase kebab/underscore, 1-64 chars). Becomes the id.'),
-            label: z.string().optional().describe('Display label (defaults to name).'),
-            icon: z.string().optional().describe('Lucide icon name shown in the block picker.'),
-            category: z.enum(['layout', 'content', 'media', 'custom']).optional(),
-            container: z.union([
-                z.literal(true), z.literal(false),
-                z.enum(['slots', 'repeater', 'conditional']),
-            ]).optional().describe('Container kind. Use slots for fixed named slots, repeater for looping over items, conditional for show-if blocks.'),
-            slot_count: z.number().optional().describe('Required when container="slots". 1-8.'),
-            slot_labels: z.array(z.string()).optional(),
-            item_compatible: z.boolean().optional().describe('Mark true if this block is designed to render as a repeater item (no outer padding, kernel layout).'),
-            expand_to: z.object({
-                target: z.string(),
-                defaults: z.record(z.unknown()),
-            }).optional().describe('Alias mechanism — render as another block type with these defaults merged under authored data.'),
-            schema: z.array(z.unknown()).optional().describe('FieldDefinition[]. Each field has name, type, label, optional required/default/options/responsive.'),
-            template: z.string().optional().describe('HTML with {{field}}, {{{field}}}, {{=tag}}, {{children}}, {{slot:NAME}} substitutions.'),
-            styles: z.string().optional().describe('Block-scoped CSS. Selectors should start with [data-block="<name>"].'),
-            script: z.string().optional().describe("Client-side JS shipped with the block (runs on the published site). Accepted under your API key's authority — the write is audit-logged and the response carries a notice naming the stored JS. It runs on the published site's own origin, which shares nothing with the Typeroll portal."),
+            name: z.string().describe('Machine name (lowercase letters, digits, "-" and "_", 1-64 chars). Becomes the id.'),
+            ...definitionShape,
+            label: z.string().describe('Display label in the block picker.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -160,24 +220,12 @@ export const blockTypeTools = [
     },
     {
         name: 'update_block_type',
-        description: "Update fields of an existing custom block type. Core blocks (id starts with 'core/') are read-only — they're managed in platform code. Schema/template/styles replace wholesale (no deep merge); other fields shallow-merge. The `script` field follows the same policy as create_block_type — accepted under your key's authority, audit-logged, notice in the response.",
+        description: "Change a site block type (core/* types are read-only). Needs ADMIN 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.",
         inputSchema: {
-            type_id: z.string().describe('Block type id (custom or third_party). Cannot be a core/* block.'),
-            label: z.string().optional(),
-            icon: z.string().optional(),
-            category: z.enum(['layout', 'content', 'media', 'custom']).optional(),
-            container: z.union([
-                z.literal(true), z.literal(false),
-                z.enum(['slots', 'repeater', 'conditional']),
-            ]).optional(),
-            slot_count: z.number().optional(),
-            slot_labels: z.array(z.string()).optional(),
-            item_compatible: z.boolean().optional(),
-            expand_to: z.object({ target: z.string(), defaults: z.record(z.unknown()) }).optional(),
-            schema: z.array(z.unknown()).optional(),
-            template: z.string().optional(),
-            styles: z.string().optional(),
-            script: z.string().optional().describe("Accepted under your API key's authority; audit-logged, and the response carries a notice naming the stored JS."),
+            type_id: z.string().describe('Block type id (a site type). Cannot be a core/* block.'),
+            ...definitionShape,
+            renames: z.record(z.string()).optional().describe('Old field path → new field name, e.g. { "title": "heading", "items.label": "text" }. Send together with the new schema.'),
+            confirm_data_loss: z.boolean().optional().describe('Drop the data of removed or retyped fields that hold data. Only after the user agreed; the 409 lists what would be lost.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -188,7 +236,7 @@ export const blockTypeTools = [
     },
     {
         name: 'delete_block_type',
-        description: "Remove a custom block type. Core blocks (core/*) cannot be deleted. **Warning**: pages currently using this block type will render '<!-- unknown block type -->' comments instead. Call find_pages_using_block_type FIRST to see the blast radius; the AI should prompt the user before deleting if usage > 0.",
+        description: "Remove a site block type. Needs ADMIN permission; core blocks (core/*) cannot be deleted. Refused with 409 while anything uses the type — pages and drafts, page templates, header, footer, global blocks, block templates, other block types or repeaters — and the refusal lists the uses (as find_pages_using_block_type does). Remove those uses first and confirm with the user.",
         inputSchema: {
             type_id: z.string(),
             version: versionParam,

package/dist/tools/domain.js

@@ -30,13 +30,13 @@ export const domainTools = [
     },
     {
         name: 'read_organization_publishing_connections', noSite: true,
-        description: 'Read the Organization\'s GitHub and Cloudflare publishing connections: status, revision (needed to change or disconnect), account identity, media_ready, media migration, and connect_urls. Requires an organization API key; never returns credentials. GitHub sign-in/App installation and Cloudflare OAuth need a person in a browser: give the user the matching connect_urls link (an organization owner or admin completes it), then read again.',
+        description: 'Read the Organization\'s GitHub and Cloudflare publishing connections: status, revision (needed to change or disconnect), account identity, media_ready, media migration, github_setup (app_configured, encryption_available) and connect_urls. Requires an organization API key; never returns credentials. GitHub sign-in/App installation and Cloudflare OAuth need a person in a browser: give the user the matching connect_urls link (an organization owner or admin completes it), then read again. When GitHub is not connected, call diagnose_organization_github_connection to learn why and who must act.',
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('publishing/connections'))),
     },
     {
         name: 'disconnect_organization_publishing_provider', noSite: true,
-        description: 'Disconnect the Organization\'s GitHub or Cloudflare publishing connection at the revision from read_organization_publishing_connections. Erases stored credentials; does not delete repositories, buckets, media, DNS or published sites, but publishing through that provider stops until reconnected. Requires an organization API key and the user\'s explicit go-ahead.',
+        description: 'Disconnect the Organization\'s GitHub or Cloudflare publishing connection at the revision from read_organization_publishing_connections. Erases stored credentials; does not delete repositories, buckets, media, DNS or published sites, but publishing through that provider stops until reconnected. After a GitHub disconnect, an owner or admin may connect a different GitHub account in the browser only after confirming which account it replaces; existing repositories are not moved. Requires an organization API key and the user\'s explicit go-ahead.',
         inputSchema: { provider: z.enum(['github', 'cloudflare']), revision: z.string(), hosting_group_id: z.string().optional().describe('Omit for the organization (Default) connection.') },
         handler: withErrorBoundary(async ({ provider, ...body }, { client }) => ok(await client.rootDelete(`publishing/connections/${provider}`, body))),
     },
@@ -63,10 +63,16 @@ export const domainTools = [
     },
     {
         name: 'check_organization_github_permissions', noSite: true,
-        description: 'Check live GitHub build permissions without disconnecting or reconnecting. Requires an organization API key. Distinguishes an update the organization owner can approve from permissions Typeroll has not requested yet. Returns the existing installation approval URL only when actionable; does not enable a build engine.',
+        description: 'Check live GitHub build permissions (Actions and Workflows) of an already connected GitHub account without disconnecting or reconnecting. Requires an organization API key. Distinguishes an update the organization owner can approve from permissions Typeroll has not requested yet. Returns the existing installation approval URL only when actionable; does not enable a build engine. For a GitHub connection that is missing or failing, use diagnose_organization_github_connection.',
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('publishing/github-permissions'))),
     },
+    {
+        name: 'diagnose_organization_github_connection', noSite: true,
+        description: 'Explain why the Organization\'s GitHub publishing connection is or is not working and who must do what next. Returns the Organization\'s state: diagnosis.outcome (connected, needs_attention, choose, action_required, waiting_on_owner, sign_in_required, retryable_error or unavailable), blockers, and the saved installation once connected. A person\'s unfinished attempt and their GitHub accounts stay in their own browser session. Each blocker has a code, who must act (you = the person connecting, github_owner, publisher = operator of this Typeroll installation, typeroll_admin), a message and one action: a github.com or documentation link, or a browser step (sign_in, install, retry, confirm_account_change) completed at connect_url. Read only, except recheck: true re-checks a connected installation (suspension, repository access, permissions) with the App\'s own authority. An API key cannot sign in to GitHub; relay the message and link to the user. Requires an organization API key; never returns credentials.',
+        inputSchema: { recheck: z.boolean().optional().describe('Re-check the connected installation with the publisher App before answering.') },
+        handler: withErrorBoundary(async ({ recheck }, { client }) => ok(await client.rootGet(`publishing/github-diagnosis${recheck ? '?recheck=true' : ''}`))),
+    },
     {
         name: 'setup_organization_build_engine', noSite: true,
         description: 'Prepare or update the organization Cloudflare or GitHub build engine and start its isolated execution and artifact-transfer check. Use the selected provider’s engine revision. Setup does not change the organization’s default provider. Requires an organization API key and current revision. Keeps site repositories, branches and Hosting Groups separate. Read the engine status until verification finishes.',

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

package/package.json

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

package/skills/README.md

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

package/skills/tr-custom-blocks.md

@@ -0,0 +1,104 @@
+---
+name: tr-custom-blocks
+description: Use when a Typeroll site needs a block the core library does not have (an icon list, cards, steps, a team strip), so the user wants a reusable block type with its own fields.
+---
+
+# Build a site block type
+
+A site block type is reusable: editors place it and fill in its fields, and
+every instance updates when the type changes. Build one when the same section
+shape recurs, or when editors should fill in fields rather than arrange
+blocks. For a one-off section use plain blocks; for a section copied and then
+adapted per page use a block template; for content that must be identical
+everywhere use a global block.
+
+Creating, changing and deleting block types needs admin permission. A changed
+block type reaches the live site with the next deploy.
+
+## 1. Look before you build
+
+```
+list_block_types                 # core and site types: maybe it exists
+list_block_type_starters         # icon_list, feature_cards, steps
+list_styles                      # the site's named styles to use inside
+```
+
+Prefer a starter or a core block with the right settings over a new type.
+
+## 2. Compose it from existing blocks
+
+Composed is the default. Declare the editable fields in `schema` and build the
+markup from core blocks in `composition`:
+
+- An inner block field set to exactly `"{{props.name}}"` takes the block's
+  field value. Bindings keep their type (lists, links, booleans).
+- For a repeating group, add a `core/repeater` with
+  `items: "{{props.items}}"`, `source_type: "static"` and no `item_block`. Its
+  children render once per item and read the item with `"{{item.title}}"`.
+- Make a whole item a link with a `core/container`
+  `{ tag: "a", href: "{{item.link.href}}", new_tab: "{{item.link.new_tab}}" }`.
+  Items without a link render as a plain container.
+- Use `core/text` for values from text fields (always escaped), `core/heading`
+  for headings, `core/icon`, `core/image`, `core/button`.
+- Give inner blocks named styles (`style_id`) instead of CSS where you can.
+
+Field types: `text`, `textarea`, `richtext`, `image`, `icon` (`{name}_svg`),
+`link` (`{ page_id }` or `{ url }` plus `new_tab`; resolves to `href`, `target`,
+`rel` and follows page renames), `select` with `options`, `boolean`, `number`,
+`array` (`fields`, `item_label`, `min_items`, `max_items`), `object`.
+
+## 3. Check and preview before saving
+
+```
+validate_block_type definition={…}        # problems with paths, e.g. /schema/0/fields/1/name
+preview_block_type definition={…}         # html + css with sample data, as published
+```
+
+Fix every error. Read warnings: a binding inside other text
+(`"Call {{props.phone}}"`) is shown as typed; only whole-value bindings resolve.
+
+## 4. CSS
+
+`styles` apply only inside the block: selectors are prefixed automatically,
+`:scope` is the block element, and `html`, `body` and `:root` are refused. Use
+`var(--color-primary)` and the site's spacing, not fixed colours, and keep text
+at WCAG AA contrast.
+
+## 5. Create, place, deploy
+
+```
+create_block_type name="icon_list" label="Icon list" category="content" schema=[…] composition=[…] styles="…"
+add_block page_id=<id> block={ type: "icon_list", data: { items: [ … ] } }
+get_preview_link page_id=<id>
+```
+
+Show the preview to the user. Deploy only when they approve.
+
+## Template block types (advanced)
+
+When the markup cannot be built from blocks, use `template` instead of
+`composition`: `{{field}}` (escaped), `{{{richtext_field}}}`, `{{#field}}…{{/field}}`,
+`{{^field}}…{{/field}}` (empty), `{{#each items}}…{{/each}}` with `{{@index}}`,
+`{{@number}}`, `{{@first}}`, `{{@last}}`, and `{{#link field class="x"}}…{{/link}}`.
+A type has a composition or a template, never both.
+
+## Changing a type in use
+
+- Rename a field with `renames: { "old": "new" }` (`"items.old": "new"` inside a
+  group): Typeroll moves the data everywhere the type is used.
+- Removing or retyping a field that holds data is refused with the list of
+  usages unless you send `confirm_data_loss: true`. Ask the user first.
+- `find_pages_using_block_type` before deleting; a type in use cannot be
+  deleted.
+
+## Pitfalls
+
+- Pasting HTML into a `core/html` block inside a composition: editors cannot
+  edit it and it skips the site's styles. Compose from real blocks.
+- Binding a text field into `core/prose`: the value becomes HTML. Use `core/text`.
+- Nesting links: an icon or button with its own link inside a linked container.
+- Linked containers on a site below render version 4: every icon sits in a
+  link of its own, so the icon list starter nests links, and an item without
+  an address is still a link. The write warns; upgrade the site's rendering
+  (`tr-upgrade-rendering`) first.
+- Writing `script` without the user's explicit request.