@typeroll/mcp-server 0.42.2 → 0.43.0

package/dist/tools/collections.js

@@ -13,7 +13,7 @@ function existingCollectionArg(args) {
 export const collectionTools = [
     {
         name: 'create_collection',
-        description: 'Create a new content collection with a field schema and (optionally) per-item URLs. Pass `route_template` (e.g. "/restaurants/{slug}") to give each published item its own URL — omit to default to "/{name}/{slug}", set to "" to disable per-item URLs entirely.',
+        description: 'Create a new content collection with a field schema and (optionally) per-item URLs. Pass `route_template` (e.g. "/restaurants/{slug}") to give each published item its own URL — omit to default to "/{name}/{slug}", set to "" to disable per-item URLs entirely. Pass template_kind for a polished native item template, or item_template_blocks for a custom block tree.',
         inputSchema: {
             name: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
             label_singular: z.string().min(1),
@@ -34,6 +34,11 @@ export const collectionTools = [
             sort_dir: z.enum(['asc', 'desc']).optional(),
             route_template: z.string().optional(),
             item_template_html: z.string().optional(),
+            template_kind: z
+                .enum(['blog', 'article', 'checklist', 'team', 'events', 'products', 'custom'])
+                .optional()
+                .describe('Native starter for item pages. article includes breadcrumbs + body outline; checklist includes optional PDF CTA + explicit previous/next fields.'),
+            item_template_blocks: z.array(z.any()).optional().describe('Explicit item-template block tree. Overrides template_kind.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/migration.js

@@ -32,15 +32,32 @@ export const migrationTools = [
     },
     {
         name: 'get_migration_readiness',
-        description: "Preflight for an import: is this site actually ready to receive a migration? CALL THIS FIRST, before moving any content. Every check exists because its failure is INVISIBLE afterwards — the pages import, the previews render, the customer signs off, and something is quietly wrong. The blockers: media storage (without it every <img> keeps its original URL, so the shiny new site is still served images by the old host, and the day that hosting is cancelled every image breaks at once) and the hosting adapter (without credentials, deploys return a job id and publish nothing while reporting success). Warnings cover the pre-cutover verification URL, AI reconstruction, form notification email and whether the target has a design to rebuild INTO. Returns { ready, blockers[], warnings[], checks[] } — each with a `fix`. If `ready` is false, stop and report the blockers to the user rather than starting the import; the content work would have to be redone.",
+        description: "Preflight for an import: is this site actually ready to receive a migration? CALL THIS FIRST, before moving any content. Every check exists because its failure is INVISIBLE afterwards — the pages import, the previews render, the customer signs off, and something is quietly wrong. Pass proposed compositions to also inventory their block, field, and native-feature dependencies before implementation. A generic custom block, raw-HTML fallback, per-instance CSS workaround, missing block type, or missing declared field returns waiting_for_native_support and makes ready=false. Do not implement those workarounds; report the gap and wait for Core support. Business-specific custom blocks are allowed only when explicitly listed. Infrastructure warnings cover the pre-cutover verification URL, AI reconstruction, form notification email and whether the target has a design to rebuild INTO.",
         inputSchema: {
             source_url: z
                 .string()
                 .optional()
                 .describe('The site you are migrating FROM, e.g. "https://oldsite.com". When given, the source is probed too: unreachable or bot-blocked (403/429) is a BLOCKER because an import from a host that refuses our requests produces empty pages, and whether /wp-json answers is reported as a warning (without it the importer must scrape HTML and loses ACF/custom fields).'),
+            compositions: z
+                .array(z.object({
+                id: z.string().optional(),
+                name: z.string().min(1),
+                fields: z.array(z.object({ name: z.string().min(1), type: z.string().optional() })).optional(),
+                blocks: z.array(z.any()),
+                business_specific_block_types: z.array(z.string()).optional(),
+            }))
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('Proposed block compositions to review before build. Include fields when you want missing schema bindings detected. Explicitly list only genuinely business-specific custom block types.'),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.get(siteId, 'migration-preflight', args.source_url ? { source_url: args.source_url } : undefined);
+            const res = args.compositions
+                ? await client.post(siteId, 'migration-preflight', {
+                    ...(args.source_url ? { source_url: args.source_url } : {}),
+                    compositions: args.compositions,
+                })
+                : await client.get(siteId, 'migration-preflight', args.source_url ? { source_url: args.source_url } : undefined);
             return ok(res);
         }),
     },

package/dist/tools/pages.js

@@ -107,14 +107,13 @@ export const pageTools = [
     },
     {
         name: 'update_page',
-        description: 'Shallow-merge update on a page (only the fields you pass change). BUFFER MODEL: content fields land in the page\'s unsaved DRAFT (working copy) — invisible to deploys and default previews until saved; `status`/`date_published` apply immediately. Pass save:true to commit in the same call, or commit_working_copy later after the user approves. Returns the draft view of the page. For "replace this page entirely", use replace_page. To switch content_mode safely, prefer `set_page_mode`.',
+        description: 'Shallow-merge update on a page (only the fields you pass change). BUFFER MODEL: content fields land in the page\'s unsaved DRAFT (working copy) — invisible to deploys and default previews until saved; `status`/`date_published` apply immediately. Pass save:true to commit in the same call, or commit_working_copy later after the user approves. Returns the draft view of the page. For "replace this page entirely", use replace_page. This tool does not accept content_mode; switch modes with `set_page_mode`.',
         inputSchema: {
             page_id: z.string(),
             patch: z
                 .object({
                 title: z.string().optional(),
                 slug: z.string().optional(),
-                content_mode: z.enum(['blocks', 'html']).optional().describe('Changing this raw skips revision snapshotting — for safe switches use set_page_mode.'),
                 html_content: z.string().optional(),
                 blocks: z.array(z.any()).optional().describe('Block tree, only used when content_mode="blocks".'),
                 status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),
@@ -177,7 +176,7 @@ export const pageTools = [
     },
     {
         name: 'batch_update_pages',
-        description: 'Apply per-page patches in one call (up to 200 entries). Each entry is { page_id, patch, save? }; failures are reported per-row, the rest still apply. BUFFER MODEL: content patches land in each page\'s unsaved draft; per-entry save:true (or the top-level save flag) commits — typical for a user-approved sweep.',
+        description: 'Apply per-page patches in one call (up to 200 entries). Each entry is { page_id, patch, save? }; failures are reported per-row, the rest still apply. BUFFER MODEL: content patches land in each page\'s unsaved draft; per-entry save:true (or the top-level save flag) commits — typical for a user-approved sweep. content_mode is rejected per-row; switch each page with set_page_mode.',
         inputSchema: {
             updates: z
                 .array(z.object({

package/dist/tools/partials.js

@@ -22,7 +22,7 @@ export const partialTools = [
     },
     {
         name: 'read_partial',
-        description: 'Fetch one global block including its full HTML content.',
+        description: 'Fetch one global block including its content_mode and the active HTML or block tree.',
         inputSchema: {
             partial_id: z.string(),
             version: versionParam,
@@ -34,13 +34,14 @@ export const partialTools = [
     },
     {
         name: 'update_partial',
-        description: 'Shallow-merge update on a global block. Use partial_id "header" or "footer" for the auto-injected layout blocks, or a kebab-case id for a free block. HTML is sanitized server-side. BUFFER MODEL: content lands in the partial\'s unsaved DRAFT (status applies immediately); pass save:true to commit in the same call, or commit_working_copy later.',
+        description: 'Shallow-merge update on a global block. Use partial_id "header" or "footer" for the auto-injected layout blocks, or a kebab-case id for a free block. HTML is sanitized server-side. This tool does not accept content_mode; switch it with set_partial_mode. BUFFER MODEL: content lands in the partial\'s unsaved DRAFT (status applies immediately); pass save:true to commit in the same call, or commit_working_copy later.',
         inputSchema: {
             partial_id: z.string(),
             patch: z
                 .object({
                 name: z.string().optional(),
                 html_content: z.string().optional(),
+                blocks: z.array(z.any()).optional().describe('Block tree to stage before switching the partial to blocks mode.'),
                 status: z.enum(['draft', 'published']).optional(),
                 kind: z.enum(['header', 'footer', 'free']).optional(),
             })
@@ -53,6 +54,20 @@ export const partialTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'set_partial_mode',
+        description: 'Switch a header, footer, or free partial between HTML and native blocks through the revision-safe mode endpoint. To author a native partial deterministically: update_partial with blocks + save:true, then set_partial_mode to="blocks", then read_partial and verify the returned mode/tree. Set convert:true only for heuristic HTML-to-block conversion.',
+        inputSchema: {
+            partial_id: z.string(),
+            to: z.enum(['blocks', 'html']),
+            convert: z.boolean().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `partials/${encodeURIComponent(args.partial_id)}/mode`, { to: args.to, convert: args.convert ?? false }, v(args.version));
+            return ok(res);
+        }),
+    },
     {
         name: 'replace_partial',
         description: 'Full replace of a global block (PUT). Pass html_content (and optionally name/status) directly — no wrapper object needed. ' +

package/dist/tools/settings.js

@@ -74,6 +74,14 @@ export const settingsTools = [
                 .passthrough()
                 .optional(),
             social: z.record(z.string()).optional(),
+            cookie_consent: z.object({
+                enabled: z.boolean().optional(),
+                text: z.string().optional().describe('Localized consent copy. May include a privacy-policy link.'),
+                privacy_policy_url: z.string().optional(),
+                scripts_necessary: z.string().optional().describe('Trusted script markup that runs before consent.'),
+                scripts_optional: z.string().optional().describe('Trusted script markup activated only after full consent.'),
+                reload_after_consent: z.boolean().optional(),
+            }).optional().describe('Native consent banner configuration. Partial updates preserve omitted fields. Script fields execute in visitor browsers and are accepted under the API key authority.'),
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const { version, ...body } = args;

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.42.2",
+  "version": "0.43.0",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {

package/skills/tr-blog.md

@@ -13,7 +13,11 @@ description: Use when the user wants to set up a blog, news section, podcast fee
 > `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
 
 
-A blog in Typeroll is a **collection with `item_template_html` + `route_template`**. Every published item materialises as its own static page at build time — there is **no need to call `create_page` per article**. The detail design lives once in `item_template_html`; the listing lives once in a page with a `<!-- typeroll:listing -->` marker that `regenerate_collection_listing` refreshes.
+A blog in Typeroll is a **collection with `item_template_blocks` +
+`route_template`**. Every published item materialises as its own static page at
+build time — there is **no need to call `create_page` per article**. Start with
+the native `article` preset; the listing is a block-mode page with
+`core/collection_list` and updates at build time.
 
 If you find yourself about to create 20 pages for 20 articles, stop — you're using the old pattern. The recipe below is the right one.
 
@@ -25,7 +29,7 @@ If you find yourself about to create 20 pages for 20 articles, stop — you're u
 
 ## Recipe
 
-### 1. Create the collection with detail template baked in
+### 1. Create the collection with a native item composition
 
 ```
 create_collection {
@@ -34,27 +38,25 @@ create_collection {
   "label_plural": "Artiklar",
   "icon": "📝",
   "slug_field": "slug",
-  "sort_field": "date",
+  "sort_field": "published_at",
   "sort_dir": "desc",
   "route_template": "/blog/{slug}",
-  "item_template_html": "<article class=\"post\">\n  <header class=\"post__header\">\n    <time>{{date}}</time>\n    <h1>{{title}}</h1>\n    {{#author}}<p class=\"byline\">av {{author}}</p>{{/author}}\n  </header>\n  {{#image}}<img class=\"post__hero\" src=\"{{image}}\" alt=\"{{title}}\" />{{/image}}\n  <div class=\"post__body\">{{{body}}}</div>\n</article>\n<style>\n.post{max-width:42rem;margin:3rem auto;padding:0 1rem}\n.post__header time{color:var(--color-text-light);font-size:0.85rem}\n.post__header h1{font-family:var(--font-heading);font-size:2.25rem;margin:0.25rem 0}\n.byline{color:var(--color-text-light);font-size:0.9rem}\n.post__hero{width:100%;aspect-ratio:16/9;object-fit:cover;border-radius:0.5rem;margin:2rem 0}\n.post__body{font-size:1.05rem;line-height:1.7}\n.post__body h2{font-family:var(--font-heading);margin-top:2rem}\n.post__body p{margin-bottom:1.25rem}\n</style>",
+  "template_kind": "article",
   "fields": [
     {"name": "title",   "type": "text",     "label": "Rubrik",    "required": true},
     {"name": "slug",    "type": "text",     "label": "URL-slug",  "required": true},
-    {"name": "date",    "type": "date",     "label": "Datum",     "required": true},
+    {"name": "published_at", "type": "date", "label": "Datum", "required": true},
     {"name": "author",  "type": "text",     "label": "Författare"},
     {"name": "excerpt", "type": "textarea", "label": "Ingress"},
     {"name": "body",    "type": "richtext", "label": "Brödtext"},
-    {"name": "image",   "type": "image",    "label": "Omslagsbild"}
+    {"name": "featured_image", "type": "image", "label": "Omslagsbild"}
   ]
 }
 ```
 
-**About `item_template_html`:**
-- `{{field}}` HTML-escapes the value (use for plain text).
-- `{{{field}}}` leaves it raw (use for `body` and any richtext).
-- `{{#field}}...{{/field}}` is a conditional — render the block only if the field is truthy. Useful for optional images, authors, etc.
-- **No loops, no nested conditionals.** If you need either, pre-render the HTML in a field on the item itself (see tr-collection-template for patterns).
+The preset writes an ordinary, editable `item_template_blocks` tree with
+breadcrumbs, title/date, body, and a server-rendered outline. Localize labels
+or change field mappings in the collection template editor.
 
 **Field name rule:** ASCII only, lowercase, `[a-z][a-z0-9_-]*`. `ä→a`, `ö→o`, `å→a` for the `name`; the `label` can be anything.
 
@@ -64,84 +66,46 @@ create_collection {
 create_collection_item collection="blog" status="published" fields={
   "title":   "Vår designfilosofi",
   "slug":    "var-designfilosofi",
-  "date":    "2025-05-15",
+  "published_at": "2025-05-15",
   "author":  "Anna Lindström",
   "excerpt": "Vi tror på enkelhet med syfte — varje beslut ska kunna motiveras.",
   "body":    "<p>Lång brödtext här...</p><h2>En underrubrik</h2><p>Mer text...</p>",
-  "image":   "https://cdn.typeroll.com/..."
+  "featured_image": "https://cdn.typeroll.com/..."
 }
 ```
 
-If `image` is a URL from elsewhere, upload it first via `upload_media_from_url` and use the returned CDN URL.
+If `featured_image` is a URL from elsewhere, upload it first via `upload_media_from_url` and use the returned CDN URL.
 
 Each published item with this collection's `route_template` automatically becomes `/blog/{slug}` at deploy time — you do **not** need to call `create_page`.
 
-### 3. Build the listing page (once)
-
-Create a single page that hosts the listing. The HTML between the `typeroll:listing` markers gets regenerated whenever the collection changes:
-
-```
-create_page title="Artiklar" slug="blog" status="published" content_mode="html"
-  html_content="<section class=\"blog-listing\">
-  <div class=\"container\">
-    <h1 class=\"section-title\">Artiklar</h1>
-    <!-- typeroll:listing:blog -->
-    <!-- /typeroll:listing:blog -->
-  </div>
-</section>
-<style>
-.blog-listing{padding:4rem 0}
-.blog-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:2rem;margin-top:2rem}
-.blog-card{border:1px solid var(--color-surface);border-radius:0.5rem;overflow:hidden}
-.blog-card a{text-decoration:none;display:block;color:var(--color-text)}
-.blog-card img{width:100%;aspect-ratio:16/9;object-fit:cover}
-.blog-card__body{padding:1.5rem}
-.blog-card__date{font-size:0.8rem;color:var(--color-text-light);display:block;margin-bottom:0.5rem}
-.blog-card__title{font-family:var(--font-heading);font-size:1.25rem;margin-bottom:0.5rem}
-.blog-card__excerpt{color:var(--color-text-light);font-size:0.9rem;margin-bottom:1rem}
-.blog-card__cta{color:var(--color-accent);font-size:0.85rem;font-weight:600}
-</style>"
-```
-
-### 4. Populate the listing (and re-run after every change)
+### 3. Build the native listing page once
 
 ```
-regenerate_collection_listing
-  collection="blog"
-  page_id="blog"
-  item_template="<article class=\"blog-card\">
-    <a href=\"{{url}}\">
-      {{#image}}<img src=\"{{image}}\" alt=\"{{title}}\">{{/image}}
-      <div class=\"blog-card__body\">
-        <time class=\"blog-card__date\">{{date}}</time>
-        <h2 class=\"blog-card__title\">{{title}}</h2>
-        <p class=\"blog-card__excerpt\">{{excerpt}}</p>
-        <span class=\"blog-card__cta\">Läs mer →</span>
-      </div>
-    </a>
-  </article>"
-  wrap_open="<div class=\"blog-grid\">"
-  wrap_close="</div>"
+create_page title="Artiklar" slug="blog" status="published" content_mode="blocks" blocks=[
+  {"id":"articles-heading","type":"core/heading","data":{"text":"Artiklar","level":"h1","size":"auto","align":"left"}},
+  {"id":"articles-list","type":"core/collection_list","data":{"collection":"blog","sort_by":"published_at","sort_order":"desc","item_block":"core/post_card","layout":"grid","cols":3,"gap":"md"}}
+]
 ```
 
-`{{url}}` resolves through the collection's `route_template`. Only the content between the markers is replaced; everything else on the page stays put. Re-run this whenever items are added, edited, or unpublished.
+The list resolves from current collection data on every preview/build. No
+generated HTML marker or regeneration call is needed.
 
-### 5. Update the header partial to link to the listing
+### 4. Update the header partial to link to the listing
 
 ```
 read_partial partial_id="header"
 replace_partial partial_id="header" html_content="<updated with /blog link>"
 ```
 
-### 6. Preview a single article
+### 5. Preview a single article
 
 ```
 get_preview_link collection_name="blog" item_id="<id>"
 ```
 
-The returned URL renders the item through `item_template_html` exactly as it'll appear in production.
+The returned URL renders the native item block tree from current database content.
 
-### 7. Deploy
+### 6. Deploy
 
 ```
 trigger_deploy
@@ -154,20 +118,22 @@ The build produces one HTML file per published article at `/blog/<slug>` plus th
 
 ```
 create_collection_item collection="blog" status="published" fields={ ... }
-regenerate_collection_listing collection="blog" page_id="blog" item_template="..." wrap_open="..." wrap_close="..."
 trigger_deploy
 ```
 
-Three calls. No per-article `create_page`. No HTML diffing by hand.
+Two calls. No per-article `create_page`, listing regeneration, or HTML diffing.
 
 ## Pitfalls
 
-- **Don't fall back to "one page per article".** That was the pre-`item_template_html` pattern. It's strictly worse now: design changes mean editing N pages, you lose `{{url}}` resolution in listings, sitemap doesn't include items, previews can't surface a per-item URL — and the API will reject your attempt anyway. `create_page` rejects slugs containing slashes ("Invalid slug … slugs must not contain slashes"), so `slug: "blog/foo"` doesn't even get through. The collection's `route_template` is the only path to nested URLs.
-- **Slugs must be unique within the collection.** `regenerate_collection_listing` will silently drop items where `slug` is missing; the listing count will be lower than the item count.
+- **Don't fall back to "one page per article".** Collection item routes keep
+  design, sitemap, preview, and nested URL handling centralized. `create_page`
+  rejects slashes in `slug`; use the collection's `route_template`.
+- **Slugs must be unique within the collection.** An item whose route tokens
+  are missing cannot receive a static detail URL.
 - **Don't use non-ASCII field names.** `datum` not `Datum`; `forfattare` not `författare` in the `name`. The `label` is free-form.
-- **Listing goes stale if you forget step 4.** Every item change needs `regenerate_collection_listing`. Add it to your mental checklist after every `create/update_collection_item`.
-- **`{{#field}}...{{/field}}` only checks truthiness.** Empty string and the field being absent both count as falsy. If you need "render this block when `published_at` is later than today", do it in the data step — set a flag field.
-- **Template too clever.** Mustache substitution has no loops or arithmetic. For an article with chapter timestamps, multiple authors, a guest with nested links — pre-render the HTML into a single field at `create_collection_item` time. See `tr-collection-template` for concrete patterns.
+- **Template too clever.** First compose current native blocks and run the
+  composition preflight. Use custom/HTML-backed behavior only when it is
+  genuinely business-specific, not to repair a generic Core gap.
 
 ## When you want a page that ISN'T a collection item
 

package/skills/tr-collection-template.md

@@ -7,9 +7,46 @@ description: Use when building a rich per-item detail page for a Typeroll collec
 
 Prefer `item_template_blocks` when the design fits the block system. It can
 include `template/item_navigation`, whose previous/next URLs and titles are
-derived from the collection's `sort_field` and `sort_dir`; do not precompute
-four navigation fields per item. Use the HTML patterns below when the detail
-page genuinely needs richer loops or markup than the block schema provides.
+derived from the collection's `sort_field` and `sort_dir`. When imported
+navigation deliberately differs, bind its explicit URL/title fields instead.
+The native `article` and `checklist` `template_kind` presets already compose
+breadcrumbs, selected rich text, server-rendered outlines, optional PDF, and
+navigation. Start there.
+
+For an archive page, place `core/collection_list` and map its card contract
+through `item_overrides` instead of pre-rendering cards:
+
+```json
+{
+  "type": "core/collection_list",
+  "data": {
+    "collection": "checklists",
+    "layout": "grid",
+    "cols": { "mobile": 1, "tablet": 2, "desktop": 3 },
+    "item_overrides": {
+      "title_field": "title",
+      "excerpt_field": "excerpt",
+      "image_field": "image",
+      "image_alt_field": "image_alt",
+      "href_field": "url",
+      "heading_level": "h2",
+      "download_url_field": "pdf_url",
+      "download_label": "Download PDF"
+    }
+  }
+}
+```
+
+`core/post_card` omits its image when the mapped image field is empty and
+keeps the title and download as separate links. A missing PDF similarly emits
+no download action. Use `item_overrides.show_image: false` when the archive
+design has no media at all.
+
+Before using the HTML patterns below, submit the proposed composition through
+`get_migration_readiness compositions=[…]`. If it reports a generic platform
+gap, wait for native support rather than shipping a generic replacement block,
+raw page HTML, or tenant CSS. The patterns below are for genuinely
+business-specific structured behavior.
 
 `item_template_html` uses lightweight Mustache substitution: