@typeroll/mcp-server 0.31.0 → 0.32.0

package/AGENTS.md

@@ -656,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)"
 
 ```
@@ -827,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` |