@typeroll/mcp-server 0.14.0 → 0.15.2

package/AGENTS.md

@@ -84,7 +84,28 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   before working with blocks — never hardcode block ids or field names,
   the available set is per-site.
 
-  Three specifics worth knowing:
+  Block-library specifics worth knowing (template_capabilities_version
+  0.15.0):
+  - **`core/media_card`** — image + text side by side (image left/right,
+    width third/two-fifths/half, heading + richtext + button, optional
+    card background/radius; stacks image-on-top below 720px). Use it for
+    the classic "photo next to copy" layout instead of hand-building
+    section+grid+html.
+  - **`core/hero` and `core/cta` render their buttons server-side** via
+    `primary_label`/`primary_url` + `secondary_label`/`secondary_url`.
+    (The old `buttons` array relied on client hydration that never
+    existed — if you see `data-buttons` in stored content it renders
+    nothing; rebuild with the explicit fields.)
+  - **`core/image` gets responsive `<picture>` automatically at build
+    time** — the deploy pipeline's SEO transform converts CDN `<img>`
+    into `<picture>` with AVIF/WebP srcset variants. You do NOT need
+    `core/html` for responsive images; just point `src` at an uploaded
+    media URL (run `generate_image_variants` first) and optionally set
+    `radius`. Note: the in-portal preview shows the plain `<img>` — the
+    `<picture>` upgrade appears on the deployed site.
+  - **`core/icon` / `core/icon_box` icons do not render yet** — they
+    emit `data-icon` placeholders awaiting an icon pipeline. Prefer
+    numbered markers, emoji, or CSS shapes until that ships.
   - **`core/section` is natively full-bleed on block pages** (since
     template_capabilities_version 0.14.0): the section's background runs
     edge-to-edge and meets the header with zero gap; content inside is
@@ -236,6 +257,28 @@ add_block page_id=home parent_id="blk_xyz" block={
 }
 ```
 
+Slot containers (`container: "slots"` — `core/columns`, `core/tabs`)
+hold their children in per-slot lists, not in `children`. Two ways to
+populate them (both require template_capabilities_version ≥ 0.15.2):
+
+```
+# Inline — pass the whole subtree in one call:
+add_block page_id=home block={
+  type: 'core/columns', data: { ratio: '1-1' },
+  slots: [
+    [{ type: 'core/prose', data: { html: '<p>Left column</p>' } }],
+    [{ type: 'core/image', data: { src: '…' } }],
+  ]
+}
+
+# Incrementally — slot_index picks the slot (0-based, defaults to 0):
+add_block page_id=home block={ type: 'core/columns', data: {} }
+# → { added_id: 'blk_cols' } — slots are auto-initialised to the type's arity
+add_block page_id=home parent_id="blk_cols" slot_index=1 block={
+  type: 'core/prose', data: { html: '<p>Right column</p>' }
+}
+```
+
 For an unfamiliar custom block, `read_block_type id="..."` gives the
 full field list (types, defaults, required) so you don't ship invalid
 `data`.

package/dist/tools/page-blocks.js

@@ -67,7 +67,7 @@ export const pageBlockTools = [
     },
     {
         name: 'add_block',
-        description: 'Insert a block into a container (page, partial, or page template). With no parent_id, inserts at the top level of the container. Otherwise inserts as a child (or into the named slot for slot-containers). Position defaults to "end". For slot containers, slot_index picks the slot. 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). 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.',
         inputSchema: {
             target: targetSchema.optional(),
             page_id: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.14.0",
+  "version": "0.15.2",
   "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-new-site.md

@@ -10,13 +10,17 @@ the portal UI or API) but has no design, no header/footer, and no pages.
 The goal is to go from blank to a working 4-page site with correct brand
 identity in a single session.
 
+**Pages are built in block mode** — the platform default. Blocks give
+structured, per-field editing, native full-bleed sections, responsive
+breakpoints, and templates. HTML mode is the secondary path for
+hand-crafted one-offs and migrated content (section at the end).
+
 ## Preconditions
 
 - `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY`.
 - The site exists (confirm with `get_site`).
 - You have the customer brief: company name, industry, 2–3 key brand colors,
-  tone of voice (formal / friendly / minimal / vibrant), and a list of
-  initial pages.
+  tone of voice, and a list of initial pages.
 
 ## Recipe
 
@@ -24,9 +28,11 @@ identity in a single session.
 
 ```
 get_site
+get_site_capabilities   # template_capabilities_version — what this deployment supports
 read_site_settings      # see what (if anything) is already configured
 list_pages              # don't overwrite pages that already exist
 list_partials           # check if header/footer already have content
+list_block_types        # the per-site block palette — NEVER assume, always list
 ```
 
 ### 2. Brand + settings
@@ -47,203 +53,189 @@ One `update_site_settings` call with every field you know:
     "text":       "#1a1a2e",
     "text_light": "#6b7280"
   },
-  "fonts": {
-    "heading": "Playfair Display",
-    "body":    "Inter",
-    "size_base": 16
-  },
-  "contact": {
-    "email": "hej@acme.se",
-    "phone": "+46 8 123 456",
-    "address": "Drottninggatan 1, 111 51 Stockholm"
-  },
-  "social": {
-    "instagram": "https://instagram.com/acme",
-    "linkedin":  "https://linkedin.com/company/acme"
-  }
+  "fonts": { "heading": "Playfair Display", "body": "Inter", "size_base": 16 },
+  "contact": { "email": "hej@acme.se", "phone": "+46 8 123 456" },
+  "social": { "instagram": "https://instagram.com/acme" }
 }
 ```
 
-Read it back: `read_site_settings` — confirm `updated_fields` includes
-everything you intended.
+Read it back with `read_site_settings`. Google Fonts names are
+case-sensitive display names ("Plus Jakarta Sans", not "plus jakarta").
 
-Google Fonts names: use the full display name as it appears on
-fonts.google.com, e.g. "Cormorant Garamond", "DM Sans", "Plus Jakarta Sans".
+**Site icons are part of brand setup** — upload favicon (32–64px) and a
+180×180 apple touch icon, set `favicon` + `apple_touch_icon`. No icon
+assets? Derive a proposal (see `tr-brand`). Also set `settings.logo` to
+the uploaded brand mark — it feeds OG/schema even if the header uses a
+different lockup.
 
-### 3. Header partial
+### 3. Header + footer partials
 
-Replace the header with a real nav. Keep it simple:
+Partials are usually simplest in HTML mode (one nav, a few links — no
+per-field editing needed). Keep them lean; literal site name (no template
+engine in partials):
 
 ```html
 <header class="site-header">
   <div class="header-inner">
-    <a class="header-logo" href="/">Acme Studio</a>
+    <a class="header-logo" href="/"><img src="LOGO_MEDIA_URL" alt="Acme Studio" height="40" /></a>
     <nav class="header-nav">
       <a href="/om-oss">Om oss</a>
-      <a href="/tjanster">Tjänster</a>
       <a href="/kontakt">Kontakt</a>
     </nav>
   </div>
 </header>
 <style>
-.site-header{background:var(--color-primary);padding:1rem 2rem}
+.site-header{background:var(--color-background);padding:1rem 2rem}
 .header-inner{max-width:1080px;margin:0 auto;display:flex;align-items:center;justify-content:space-between}
-.header-logo{color:#fff;text-decoration:none;font-family:var(--font-heading);font-size:1.25rem;font-weight:700}
 .header-nav{display:flex;gap:2rem}
-.header-nav a{color:rgba(255,255,255,0.85);text-decoration:none;font-size:0.9rem;letter-spacing:0.05em;text-transform:uppercase}
-.header-nav a:hover{color:#fff}
-</style>
-```
-
-Use `replace_partial partial_id="header" html_content="..."`.
-
-### 4. Footer partial
-
-```html
-<footer class="site-footer">
-  <div class="footer-inner">
-    <p class="footer-brand">Acme Studio</p>
-    <p class="footer-tagline">Tagline here</p>
-    <div class="footer-links">
-      <a href="/om-oss">Om oss</a>
-      <a href="/kontakt">Kontakt</a>
-    </div>
-    <p class="footer-copy">© 2025 Acme Studio. Alla rättigheter förbehållna.</p>
-  </div>
-</footer>
-<style>
-.site-footer{background:var(--color-secondary);color:rgba(255,255,255,0.7);padding:3rem 2rem;margin-top:4rem}
-.footer-inner{max-width:1080px;margin:0 auto;text-align:center;display:grid;gap:1rem}
-.footer-brand{font-family:var(--font-heading);font-size:1.5rem;color:#fff;font-weight:700}
-.footer-links{display:flex;justify-content:center;gap:2rem}
-.footer-links a{color:rgba(255,255,255,0.7);text-decoration:none}
-.footer-links a:hover{color:#fff}
-.footer-copy{font-size:0.8rem;opacity:0.5}
+.header-nav a{color:var(--color-text);text-decoration:none}
 </style>
 ```
 
-Use `replace_partial partial_id="footer" html_content="..."`.
-
-### 5. Homepage
-
-```
-create_page title="Start" slug="" content_mode="html"
-            html_content="<article class=\"home-page\">...full hero + intro HTML...</article>"
-            status="published"
-```
-
-`slug=""` creates the homepage under `page_id: "home"`. If it already exists, use `update_page page_id="home" patch={html_content: "..."}`.
-
-**Always wrap the body in a page-scope `<article class="...-page">`.** The renderer's `.page-content` layout shell sets default max-width and padding; without a scope class, any selectors you write live in the same tree as the renderer defaults and you'll wonder why your `.hero h1` doesn't get the size you set. With `.home-page .hero h1` you're at specificity 0,2,1 and trivially win. Use `<article class="home-page">` for the homepage and `<article class="static-page">` (or page-specific names like `<article class="about-page">`) for inner pages.
-
-A minimal homepage structure:
-- Hero: **full-bleed** section (negative-margin escape) with `<h1>`, tagline, one CTA button
-- Intro: 2–3 sentences about what the company does
-- Services/features grid: 3 cards max
-- CTA band: "Kontakta oss" or similar
-
-Full-bleed hero recipe (matches the section conventions from `tr-brand`'s Step 4b):
-
-```css
-.home-page .home-hero {
-  position: relative;
-  margin-left: calc(50% - 50vw);
-  margin-right: calc(50% - 50vw);
-  margin-top: -32px;          /* cancels .page-content top padding */
-  width: 100vw;
-  padding: 80px 0 64px;
-  background: var(--gradient-soft), #fff;
-}
-```
-
-**Caveat:** never combine with `overflow-x: clip` on the page wrapper — the clip cancels the bleed.
-
-### 6. Inner pages
-
-Create each page (always with a page-scope class):
-
-```
-create_page title="Om oss" slug="om-oss" content_mode="html"
-            html_content="<article class=\"static-page\">...</article>"
-            status="published"
-```
-
-Standard set: Om oss, Tjänster, Kontakt. Add more if the brief says so.
-
-### 6b. If the legacy site is still live, scrape canonical content
-
-When a page (privacy policy, terms, about) exists on the still-live previous site, use `WebFetch` to pull the canonical text directly rather than rewriting from memory or relying on placeholder copy.
-
-Pattern:
-
-```
-WebFetch url="https://www.olddomain.example/integritetspolicy"
-         prompt="Return full content as markdown, preserve Swedish characters,
-                 preserve hierarchy, don't summarize"
-```
+`replace_partial partial_id="header" html_content="..."` — same pattern
+for the footer. Design notes: **no border-bottom on the header if the
+first page section should meet it seamlessly** — let background color
+changes do the separating. Anchor links in nav (`/#section`) are fine.
 
-Then convert markdown → HTML for `html_content`. This keeps legal text exact and stops "polished" rewrites from drifting from the canonical version.
+### 4. Homepage — block tree
 
-### 7. Preview + iterate
+`create_page` with the whole tree in one call. Omit block `id`s — the
+platform assigns them (`blk_…`); you read them back for later
+`update_block` calls.
 
 ```
-get_preview_link        # get a signed URL for the whole site
-get_page_preview page_id="home"   # get rendered HTML to spot-check
+create_page title="Start" slug="" status="draft" content_mode="blocks" blocks=[...]
 ```
 
-Share the preview link with the user. Iterate on feedback.
+A proven landing-page skeleton (every top-level block is a `core/section`
+— sections are **natively full-bleed**: the background runs edge-to-edge,
+content is constrained by the section's own inner container via the
+`width` field. NEVER use 100vw negative-margin hacks):
 
-### 8. Deploy
+```json
+[
+  { "type": "core/section", "data": { "background": "#ffffff", "padding_y": "lg" }, "children": [
+    { "type": "core/media_card", "data": {
+        "image": "MEDIA_URL", "image_alt": "…", "image_side": "right",
+        "heading": "Huvudrubriken", "heading_level": "h2",
+        "text": "<p>Ingress …</p>",
+        "button_label": "Kontakta oss", "button_url": "/#kontakt"
+    } }
+  ] },
+  { "type": "core/section", "data": { "padding_y": "lg" }, "children": [
+    { "type": "core/heading", "data": { "text": "Så funkar det", "level": "h2", "align": "center" } },
+    { "type": "core/grid", "data": { "cols": 3, "gap": "lg" }, "children": [
+      { "type": "core/step_card", "data": { "number": "1", "title": "…", "text": "<p>…</p>" } },
+      { "type": "core/step_card", "data": { "number": "2", "title": "…", "text": "<p>…</p>" } },
+      { "type": "core/step_card", "data": { "number": "3", "title": "…", "text": "<p>…</p>" } }
+    ] }
+  ] },
+  { "type": "core/cta", "data": {
+      "heading": "Redo att börja?",
+      "primary_label": "Kontakta oss", "primary_url": "/kontakt"
+  } }
+]
+```
+
+Block-palette guidance (verify against `list_block_types` — the source of
+truth):
+
+- **Hero:** `core/media_card` inside a white section (image beside copy),
+  or `core/hero` (eyebrow/heading/subheading + `primary_*`/`secondary_*`
+  buttons — rendered server-side; `layout: split-right` puts the image
+  beside the text). For a plain text hero: section + heading + prose +
+  button.
+- **`core/heading`** decouples `level` (h1–h6, semantics) from `size`
+  (visual) — exactly one `level: h1` per page.
+- **Images:** `core/image` with an uploaded media URL. The build pipeline
+  automatically emits responsive `<picture>` with AVIF/WebP variants
+  (run `generate_image_variants` after upload) — the in-portal preview
+  shows a plain `<img>`, the deployed site gets the upgrade. Use the
+  `radius` field for rounded corners.
+- **Repeaters/listings:** `core/collection_list`, `gallery`,
+  `feature_grid` etc. — alias blocks over `core/repeater`. Use these for
+  collection-driven content instead of hand-writing listing markup.
+- **Forms:** `create_form`, then a `core/html` block carrying the plain
+  `<form method="POST" action={submit_url}>` embed with the hidden
+  `_token` — see `tr-forms`.
+- **`core/html`** is the escape hatch for the genuinely unique thing —
+  not a default. If you reach for it more than once or twice per page,
+  note why (that's block-library feedback).
+
+Slot containers (`core/columns`, `core/tabs`): populate them either by
+passing the whole tree inline (`block={ type: 'core/columns', slots:
+[[…],[…]] }`) or incrementally with `add_block parent_id=<columns-id>
+slot_index=0|1`. Requires template_capabilities_version ≥ 0.15.2 — on
+older sites use `core/grid` (children flow into columns) instead.
+
+Known limitations (honest list — don't fight them):
+
+- **`core/icon` / `core/icon_box` icons don't render yet** (pending icon
+  pipeline). Use `step_card` numbers, emoji, or CSS markers.
+
+Theming: block primitives render neutral. Brand color/typography comes
+from settings (step 2). For page-specific polish (e.g. a colored card
+treatment), a single `core/html` block with a small `<style>` scoped to
+`[data-bid]`/section selectors is acceptable — keep it minimal and note
+it in your log.
+
+### 5. Inner pages
+
+Same pattern: `create_page` with `content_mode: "blocks"` and a section
+tree. Standard set: Om oss, Tjänster, Kontakt — or what the brief says.
+Default new pages to `status: "draft"`; publish after review.
+
+### 5b. If the legacy site is still live, scrape canonical content
+
+For pages with canonical text (privacy policy, terms, about), `WebFetch`
+the live page and carry the text verbatim — don't rewrite legal copy
+from memory. Convert to prose blocks (or one `core/html` for complex
+legacy markup).
+
+### 6. Preview + iterate
+
+```
+get_preview_link                  # signed URL for browser review
+get_page_preview page_id="home"   # rendered HTML for structural checks
+```
+
+Share the preview link. Iterate on feedback with `update_block` /
+`add_block` / `move_block` — that's the point of block mode: surgical
+edits, not full-page rewrites.
+
+### 7. Deploy
 
 When the user approves:
 ```
 trigger_deploy
-get_deploy_status job_id=<id>    # poll until status=succeeded
+get_deploy_status job_id=<id>
 ```
 
-## Design conventions
-
-- **One `<h1>` per page.** SEO and screen reader requirement.
-- **CSS variables for colors.** Always use `var(--color-primary)` etc. in
-  partial `<style>` blocks — never hardcode hex values.
-- **Responsive layout.** Use `max-width` on containers, `display:flex`
-  or `display:grid` for layouts, and `clamp()` for fluid type.
-- **Scoped styles.** Put `<style>` at the bottom of partial HTML.
-  Styles apply to the whole page; prefix class names with the partial ID
-  to avoid collisions (`site-header__*`, `site-footer__*`).
-- **Page-scope class on every page body.** Wrap `html_content` in
-  `<article class="my-page">` and prefix all your page-specific rules
-  with `.my-page`. The renderer's `.page-content` layout shell sets
-  width + padding at normal specificity, so a scope class keeps your
-  rules cleanly above the defaults and the next agent can refactor a
-  single page without bleed-through.
-- **Inherit `tr-brand`'s Step 4b section/layout defaults.** Full-bleed
-  sections via negative-margin escape, one signal per section boundary
-  (bg shift OR divider, not both), cards drop bg on `.section.alt`,
-  gradient-clipped headings use `line-height: 1.1+` to keep descenders
-  inside the box. See the brand skill for the full list — don't
-  re-derive.
-- **Don't simplify data during import.** When porting content from an
-  existing site, preserve full fidelity at the data layer. Don't
-  ASCII-fold slugs into display labels (`affärsutveckling` ≠
-  `affarsutveckling`), don't truncate descriptions, don't drop
-  metadata fields you "won't use yet". Carry titles verbatim from
-  source; derive slug-from-title only for the URL, not the label.
-- **Minimal JS.** The platform doesn't bundle JS. If you need interactions,
-  write a small `<script>` inside the partial or page; keep it under 50
-  lines. Avoid external CDN dependencies in page bodies.
+## Secondary path: HTML mode
+
+For migrated legacy pages or a hand-crafted one-off, `content_mode:
+"html"` still works. Rules that apply there (and only there):
+
+- Wrap the body in a page-scope `<article class="my-page">` and prefix
+  selectors with it — the `.page-content` shell sets width/padding at
+  normal specificity.
+- HTML-mode bodies are container-constrained; full-bleed requires the
+  negative-margin escape (`margin-left: calc(50% - 50vw); width: 100vw`)
+  — never combine with `overflow-x: clip` on a wrapper.
+- `set_page_mode` flips a page between modes;
+  `convert_page_to_blocks` does a heuristic HTML→blocks conversion.
 
 ## Pitfalls
 
-- **Don't create pages that already exist.** Run `list_pages` first;
-  if the slug is taken, use `update_page` instead of `create_page`.
-- **Don't hardcode text from settings into partials.** If `site_name`
-  is "Acme", the header partial should have literal "Acme" in it —
-  there's no template engine. When the name changes the user updates
-  the partial.
-- **Google Fonts names are case-sensitive.** "Playfair Display" works;
-  "playfair display" or "Playfair-Display" do not.
-- **Empty `custom_css` field.** If you set `custom_css: ""` it's
-  stored as an empty string, not removed. Use it only when you have
-  global styles that span both partials and pages (e.g. utility classes,
-  `@keyframes`, `:root` overrides for things not in `colors`/`fonts`).
+- **Don't create pages that already exist** — `list_pages` first; use
+  `update_page` if the slug is taken.
+- **`update_page` takes a `patch` object**, not flat fields.
+- **Don't hardcode block field names from memory** — schemas are
+  per-site (`list_block_types`/`read_block_type`).
+- **One `level: h1` per page** (core/heading) — SEO + screen readers.
+- **Don't simplify data during import** — preserve Swedish characters in
+  labels (`affärsutveckling`, not the ASCII-folded slug), keep titles
+  verbatim; slugs are derived for URLs only.
+- **Minimal JS.** Inline `<script>` in page content is stripped by the
+  sanitizer. Interactivity ships via block-type `script` (requires the
+  site's AI-scripts opt-in) or the human-managed `scripts_body_end`.