@typeroll/mcp-server 0.29.0 → 0.32.0

package/AGENTS.md

@@ -197,6 +197,42 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
     one `html` field rendered verbatim (then sanitized like HTML-mode
     content). Use it for the genuinely unique thing no block covers.
     Prefer real blocks when one fits.
+  - **Structured records at scale** (template_capabilities_version ≥ 0.31.0).
+    Four things landed together for directory-shaped sites:
+    - `collection_completeness` — **start an enrichment pass here**, not by
+      paging every item. Returns per-field gap counts plus the N worst
+      records (missing fields, never-verified fields, fields whose last write
+      is older than the staleness window), computed at read time. Fields no
+      API key may write are excluded by default: a gap you can't close is
+      noise.
+    - **Per-field write authority.** A collection field can declare
+      `writable_by` (`portal | owner | agent | app | import`). A write you're
+      not permitted, or one that would overwrite a higher-precedence writer
+      (a human correction, the listed business's own edit), comes back as
+      **409 with the losing field names** — never a silent no-op. Treat that
+      as "already handled" and record it; retrying will lose again.
+    - **Item references.** `item_ref` / `item_ref_list` fields point at items
+      in another collection (`ref_collection`). The reverse direction is
+      computed at render time — don't try to maintain backlinks yourself.
+      Render them with a `core/repeater` whose `source_type` is `related`
+      (a ref field on the current item) or `backlinks` (who points at it).
+    - **Taxonomy pages.** `CollectionDef.facets` generates one page per
+      distinct field value. ⚠️ This turns record count into ROUTE count, and
+      route count is what the build timeout measures. `min_items` (default 2)
+      keeps thin-content pages out, and combination pages must be listed
+      explicitly in `facet_combinations` — never assume a cartesian product.
+  - **`core/embed`** (template_capabilities_version ≥ 0.30.0) is
+    `core/html` plus behaviour: an `html` field and a `js` field. Reach
+    for it when a one-off placement needs JavaScript. **A `<script>` tag
+    written into `core/html` — or into any page/block markup — is stripped
+    by the sanitizer no matter which credential wrote it**, so this field
+    is the supported route, not a workaround. The code runs in an IIFE
+    with `el` bound to the block's root element and ships in the page's
+    block bundle, outside the sanitized body. Through an API key it's
+    accepted under your key's authority (audit-logged, notice in the
+    response). Scope guide: one placement → `core/embed`; a reusable
+    widget → `create_block_type` with `script`; a site-wide tag →
+    `settings.scripts_head` / `scripts_body_end`.
   - **Forms 2.0** (template_capabilities_version ≥ 0.18.0): forms can
     carry `steps[]` — each step is a Block[] tree mixing `form/*` field
     blocks (text/email/phone/number, textarea, select/radio_group/
@@ -239,6 +275,20 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
 - **Deploys.** Customers see live changes only after a deploy. Preview
   always sees drafts. `trigger_deploy` enqueues; `get_deploy_status`
   reports `queued → running → succeeded | failed`.
+  `trigger_deploy dry_run=true` builds without publishing — use it to prove
+  a structural change compiles (new collection, schema edit, template
+  rewrite) without touching the live site.
+  A finished job carries `cost`: total, cpu/memory/request split,
+  `duration_s`, per-phase timings, and output size. Estimates from a rate
+  card, not billing records, and gross of free tier — quote them as "roughly"
+  if a customer asks, and reach for `cost.phases` when the question is *why*
+  a build got slow.
+
+- **Is the site live?** There is no site-level status field —
+  `Site.status` was removed in 0.30.0 because it was set once at creation and
+  never advanced, so it reported live sites as "planning". Read
+  `get_site → urls.production` instead: non-null means the domain is verified
+  and serving. For "has anything shipped", use `list_deploys`.
 
 - **Site URLs.** `get_site` returns a `urls` object with:
     - `production` — the customer's real domain (or null)
@@ -606,6 +656,116 @@ Redirect hygiene is automatic in both directions (since 0.16.1):
   are removed (reported as `removed_redirects`). Manually created redirects
   are kept — delete them yourself via `delete_redirect` if they're obsolete.
 
+### "Before you start an import"
+
+```
+get_migration_readiness
+```
+
+Call this before moving any content. Every check it runs fails SILENTLY
+otherwise — the import succeeds, previews render, the customer signs off, and
+something is quietly wrong:
+
+- **media storage** (blocker) — without it every `<img>` keeps its original
+  URL, so the new site is still served images by the old host. Nothing looks
+  broken until that hosting is cancelled, at which point every image on every
+  page breaks at once.
+- **hosting adapter** (blocker) — without credentials, deploys return a job id
+  and publish nothing, while reporting success.
+- verification origin, AI reconstruction, form notification email, and whether
+  the target actually has a design to rebuild INTO (warnings).
+
+`ready: false` means STOP and report the blockers, each of which carries a
+`fix`. Don't start "and fix it after": the content work would have to be
+redone. The in-portal migration workflow enforces the same gate as its first
+step (`skip_preflight: true` overrides it, and logs that it did).
+
+### "Don't lose URLs in a migration"
+
+Two different questions, and you need both answers:
+
+```
+list_migration_urls status="unhandled"     # what the DATA says is uncovered
+verify_migration_urls                      # what the SERVER actually answers
+```
+
+`list_migration_urls` classifies every inventory URL against the site's
+current pages + redirects. It's recomputed on read, so creating a redirect
+flips the entry on your next call — no bookkeeping of your own.
+
+`verify_migration_urls` requests each URL against the deployed site (its
+fallback subdomain by default, because the real domain still points at the
+old host pre-cutover) and reports `ok` / `ok_redirect` / `missing` /
+`broken_redirect` / `error`. This is the one that catches a redirect
+pointing at an unpublished page, a typo'd `path`, and redirect loops — all
+of which read as "handled" in the coverage report and as a 404 to Googlebot.
+**Deploy first**: it tests saved, deployed content, not your drafts.
+
+Every unhandled URL gets exactly one of three outcomes — there is no fourth:
+
+- it moved → `create_redirect`
+- it's gone on purpose → `update_migration_url url_id=… excluded=true` (with
+  a note saying who signed off)
+- it should exist → migrate it
+
+Populate the inventory yourself when the in-portal WordPress migration
+didn't: `add_migration_urls` takes up to 2000 entries from a sitemap walk, a
+GSC export (pass `gsc_clicks` so the report prioritises itself), or a crawl.
+Pass `source_origin` whenever more than one old domain is in play — it
+rejects foreign-origin URLs, which is what stops one market's `/kontakt`
+from reading as another market's coverage.
+
+For a whole family of sites, read the `tr-migrate-multisite` skill.
+
+### "Retire a family of old URLs in one rule"
+
+```
+create_redirect from_path="/category/*" to_path="/blogg/:splat"
+create_redirect from_path="/blog/:slug" to_path="/artiklar/:slug"
+```
+
+A trailing `*` captures everything under a prefix (including the prefix
+itself) and `:splat` replays it; `:name` matches exactly one segment and is
+replayed by name. This is the right tool after a WordPress migration, where
+the dead URLs come in shapes — `/category/`, `/tag/`, `/author/`, `/2019/` —
+and the inventory only knows the subset it happened to find.
+
+Constraints, all enforced at write time rather than discovered in production:
+
+- **Trailing `*` only.** Cloudflare silently drops a mid-path splat, so the
+  rule would save fine and do nothing.
+- **`:splat` requires a `*`**, and `:name` in the target must be declared in
+  `from_path`.
+- **Query strings can't be matched** — `_redirects` keys on the path. A
+  WordPress `/?p=123` URL has to be handled at the source.
+- **A rule that would hide a live page is refused**, naming the pages.
+  Redirects are applied BEFORE static files, so `/blogg/*` makes every real
+  article under `/blogg/` unreachable. Narrow the prefix.
+
+Rules are emitted most-specific-first, so `/blogg/recept/*` and `/blogg/*`
+can coexist — the narrower one fires. `list_migration_urls` counts
+pattern-covered URLs as `redirected`, so the coverage report reflects what
+production will do.
+
+### "Link language versions together (hreflang)"
+
+One Typeroll site owns one domain, so `example.se` / `example.de` /
+`example.co.uk` are three sites. Nothing can derive which page corresponds
+to which — declare it per page:
+
+```
+update_page page_id=om-oss patch={ alternates: [
+  { hreflang: "de",        href: "https://example.de/ueber-uns" },
+  { hreflang: "x-default", href: "https://example.com/about-us" }
+]}
+```
+
+The renderer injects this page's own self-reference, so list only the OTHER
+variants. Clusters must be **reciprocal** — write all sides, `batch_update_pages`
+is the sane way. Use absolute URLs on the FINAL domains (never the
+`*.typeroll` fallback). Invalid tags/hrefs are rejected at write time with
+the reason rather than silently dropped at render.
+
 ### "Change the site's fallback URL (slug)"
 
 ```
@@ -777,7 +937,8 @@ preview.
 | **Block types** | `list_block_types`, `read_block_type`, `find_pages_using_block_type`, `export_block_types`, `import_block_types` |
 | **Collections** | `create_collection`, `update_collection_schema`, `delete_collection`, `list_collections`, `read_collection`, `list_collection_items` (richtext hidden by default), `read_collection_item`, `batch_read_collection_items`, `create_collection_item`, `update_collection_item`, `delete_collection_item`, `regenerate_collection_listing` |
 | **Media** | `list_media`, `read_media`, `create_upload_url`, `upload_media_from_url`, `upload_media_inline`, `update_media`, `delete_media`, `finalize_media`, `finalize_all_media`, `generate_image_variants`, `suggest_alt_text_context` |
-| **Redirects** | `list_redirects`, `create_redirect`, `delete_redirect` |
+| **Redirects** | `list_redirects`, `create_redirect`, `delete_redirect`. `from_path` may be a PATTERN: a trailing `*` (with `:splat` in the target) or `:name` for one segment — one rule retires a whole family of dead URLs (`/category/*` → `/blogg/:splat`). Mid-path splats and query strings are refused, as is any rule that would hide a live page. |
+| **Migration inventory** | `get_migration_readiness` (preflight — CALL FIRST on any import), `list_migration_urls`, `add_migration_urls`, `update_migration_url`, `delete_migration_url`, `verify_migration_urls`. The legacy site's URL list with LIVE coverage status (`migrated` / `redirected` / `excluded` / `unhandled`, recomputed on every read from current pages + redirects). `verify_migration_urls` is the pre-cutover check that REQUESTS every URL against the deployed site — see "Don't lose URLs in a migration" below. |
 | **Forms** | `list_forms`, `read_form`, `create_form`, `update_form`, `delete_form`, `list_form_submissions`, `delete_form_submission` (removes one submission — e.g. cleaning up a test entry; `delete_form` with `delete_submissions` is the bulk path). **Steps (form/* block trees) are the ONLY stored model** (0.29.0+, `forms_steps_only` capability): pass `steps` for funnels, or `fields` for simple forms — the server converts a flat field list to a single static step (read_form shows the resulting steps). **Placing a form: prefer a `core/form` block with `data.form_id`** — it renders every form with validation + signed token handled. The raw `<form method="POST">` embed with hidden `_token` + honeypot `_hp` (from read/create's `submit_token`/`submit_url`) is the HTML-mode fallback, single-step forms only; no client JS (the sanitizer strips inline `<script>`) |
 | **Settings** | `update_site_settings` (whitelist) |
 | **Search + bulk** | `search_pages`, `bulk_replace_text` |

package/README.md

@@ -152,7 +152,9 @@ the full reference + concrete operation recipes.
 - **Bulk** — `bulk_replace_text` with dry-run.
 - **Branches** — create, read, delete, merge. Branch deploys get their
   own URL at `{branch}.{project}.pages.dev`.
-- **Deploy** — trigger, list, get status.
+- **Deploy** — trigger (with `dry_run` to build without publishing), list, get
+  status. A finished job reports `cost`: what the build consumed in server
+  time, broken down per phase. Estimates from a rate card, not billing records.
 - **Preview** — `get_preview_link` (signed URL for browser navigation;
   supports `page_id`, `slug`, or `collection_name + item_id`; pass
   `include_working_copy: true` to also render unsaved drafts).
@@ -189,9 +191,12 @@ The MCP server is purely an ergonomics layer on top of that.
 - **HTML sanitization** happens at save time on the server — `<script>`,
   event handlers, and `javascript:` URLs are stripped from page/partial
   content (including `core/html` block output). The scriptable surfaces
-  (`scripts_*`, `custom_css`, block-type `script`) are deliberate
-  exceptions: the first are writable with an API key, and block-type
-  scripts additionally require the site's per-site opt-in.
+  are deliberate exceptions, and all of them are writable with an API key
+  under the key holder's own authority: `scripts_*` and `custom_css` on
+  the site settings, `script` on a block type, and the `js` field of a
+  `core/embed` block instance. Those writes are audit-logged and the
+  response carries a notice naming the stored JS. Only the in-portal chat
+  assistant is additionally gated, on a per-site opt-in.
 - Keys can be **revoked** at any time from the portal. Revocation takes
   effect on the next request (no in-flight requests get cancelled, but
   the next one returns 401).