@typeroll/mcp-server 0.45.44 → 0.45.46

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.

package/skills/tr-forms.md

@@ -112,8 +112,19 @@ update_form form_id=contact patch={ actions: [
 ```
 
 A webhook needs `url` (https), an explicit `fields` allowlist and a signing
-`secret`; send the masked value back to keep a stored secret. `list_form_submissions`
-reads what visitors sent.
+`secret`; send the masked value back to keep a stored secret.
+`get_form_capabilities` lists every action type the site offers, including
+types from installed apps, with the config fields each one takes.
+
+Email actions send through the site's email provider. Check it with
+`get_email_settings`; if `email` is null, connect one with `set_email_settings`
+(for example `type: "postmark"`, `from`, `config: { server_token }`) and confirm
+with `send_test_email`. Without a provider, submissions are stored but nobody is
+notified. These tools need admin permission, like Settings → Email & notifications.
+
+`list_form_submissions` reads what visitors sent, `read_form_submission` reads
+one entry (admins also see webhook delivery status) and `delete_form_submission`
+removes one.
 
 ## Verify
 
@@ -121,8 +132,11 @@ reads what visitors sent.
 2. Preview the page and confirm the authoring reference has expanded to a form
    with `data-tr-form-el`, a signed token, and the platform runtime.
 3. Submit a test entry and confirm it appears in Forms → Submissions.
-4. If a webhook is configured, confirm its delivery status and the receiving
-   system's idempotency key before deploying.
+4. If a webhook is configured, confirm its delivery status
+   (`read_form_submission`) and the receiving system's idempotency key before
+   deploying.
+5. If an email action is configured, confirm `get_email_settings` shows a
+   provider and the test message arrived.
 
 ## Common patterns
 

package/skills/tr-migrate-wp.md

@@ -19,9 +19,13 @@ Its shared evidence record is required for visual acceptance.
 > `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
 
 
-The platform's in-portal migration workflow is the "managed" path for
-customers who want one-click. This skill is the "power-user" path: you
-do it locally, mix data sources freely, and the user reviews each step in their terminal.
+The platform's migration workflow is the "managed" path for customers who
+want one-click. It runs on the server and is also available to you:
+`start_workflow type="migration" config={ wp_url }` on an existing site, or
+`create_site_and_migrate` (organization key) for a new one; poll `get_workflow`
+and approve its review gate only with the user's consent. This skill is the
+"power-user" path: you do it locally, mix data sources freely, and the user
+reviews each step in their terminal.
 
 ## Preconditions
 

package/skills/tr-new-site.md

@@ -32,7 +32,9 @@ wrapper. Load only the relevant guide section and recipe. Discover site apps wit
 read_app_documentation when needed; do not bundle private app guides locally.
 
 No Site yet? Use hosted MCP with an Organization key and create_site, or create it
-in the portal. Read back its ID before editing. Use one explicit Site/Version for
+in the portal. To start from an AI site plan instead of a blank Site, use
+create_site_and_plan, poll get_workflow and approve its structure review only
+with the user's consent. Read back its ID before editing. Use one explicit Site/Version for
 related operations. Larger changes to an existing site should use a branch.
 
 Before importing content or a media library, require get_import_readiness to pass.

package/skills/tr-redesign-branch.md

@@ -245,6 +245,15 @@ compiled output or merge. Wait for an explicit "looks good, ship it."
 
 ### 7. Merge + deploy
 
+Before asking for sign-off, summarise exactly what will land:
+
+```
+diff_version version_id="<branch>"        # added / modified / deleted per collection
+```
+
+Then, once approved (creating and merging branches need site admin
+permission):
+
 ```
 merge_branch version_id="<branch>"        # branch's diffs land on main
 trigger_deploy
@@ -274,7 +283,12 @@ disk cost is tiny.)
   the DB, reflects edits on reload); deploy only for the compiled static
   output or merge (steps 6–7).
 - **Auto-merge.** Don't `merge_branch` without explicit user sign-off.
-  Once merged, the only undo is another branch + reverse edits.
+  Once merged, the only undo is another branch + reverse edits (or
+  restoring individual saved states with `restore_page_revision` /
+  `restore_partial_revision` on main).
+- **Starting over.** To abandon a direction but keep the branch and its
+  address, `reset_version version_id="<branch>"` discards every change on it
+  (check `diff_version` and ask first); `delete_branch` removes it entirely.
 - **Header rewrites that drop the brand block.** Even when the
   redesign is dramatic, preserve the brand mark + the nav skeleton
   unless the user said to redo them.

package/skills/tr-seo.md

@@ -97,11 +97,25 @@ batch_update_pages updates=[
 OG image dimensions: 1200×630px ideal. The platform doesn't resize —
 use a correctly-sized source image.
 
+For pages without their own image, set a site-wide fallback and the X/Twitter
+handle (admin permission, as in the portal Settings form):
+
+```
+update_site_settings default_og_image="<cdn_url>" twitter_handle="@acmestudio"
+```
+
 ### 5. Add structured data (JSON-LD)
 
 Typeroll auto-generates Article and Page schema, but you can override or
 extend with custom JSON-LD per page. Example: LocalBusiness on the homepage.
 
+The site-wide Organization schema comes from settings — set it once instead of
+repeating it on every page (`null` clears it):
+
+```
+update_site_settings organization={"name":"Acme Studio","logo":"<cdn_url>","same_as":["https://www.linkedin.com/company/acme"]}
+```
+
 ```
 update_page page_id="home" patch={
   "json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"LocalBusiness\",\"name\":\"Acme Studio\",\"url\":\"https://acme.se\",\"telephone\":\"+46812345\",\"address\":{\"@type\":\"PostalAddress\",\"streetAddress\":\"Drottninggatan 1\",\"addressLocality\":\"Stockholm\",\"postalCode\":\"111 51\",\"addressCountry\":\"SE\"}}"