@typeroll/mcp-server 0.44.73 → 0.45.0

package/skills/tr-migrate-astro.md

@@ -1,297 +1,69 @@
 ---
 name: tr-migrate-astro
-description: Use when the user wants to migrate an Astro site — particularly an Astro Content Collections-backed site — to Typeroll. Walks `src/content/<collection>/*.md(x)`, lifts frontmatter into Typeroll collection schemas, converts markdown bodies into richtext fields, batch-imports items, then maps `src/pages/*` into Typeroll pages/partials. Triggers on "migrate an Astro site", "import from src/content", "convert content collections", or when the user names a local Astro repo as the source.
+description: Migrate an existing Astro site, including Astro Content Collections, to native Typeroll Pages and Content types while preserving routes, design and media.
 ---
 
-# Migrate an Astro site to Typeroll
-
-> **The buffer model (draft writes).** Every content write in this recipe
-> (pages, blocks, partials, collection items) lands in an unsaved per-doc
-> DRAFT — deploys and plain previews only see SAVED content. For recipe-style
-> build work, pass `save: true` on write calls (the work is pre-approved by
-> the task itself), or run `commit_working_copy` per doc before any
-> `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
-
-
-Astro's [Content Collections](https://docs.astro.build/en/guides/content-collections/) and Typeroll's `Collection` + `CollectionItem` map one-to-one. A collection in Astro is a directory of frontmatter-bearing files under `src/content/<name>/`; in Typeroll it's a schema + items doc set under `organizations/{org}/sites/{site}/collections/{name}/`. The Astro schema (`zod.object(...)` in `src/content/config.ts`) is your field list. The frontmatter values are field values. The markdown bodies are richtext fields.
-
-This skill walks the migration from a checked-out Astro repo on the user's machine to a target Typeroll site. You run it locally — the source repo is on disk, the MCP just receives the final shape.
-
-## Preconditions
-
-- The Astro repo is checked out locally and `npm install`d (so we can read `src/content/config.ts` to extract the schemas).
-- `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY` pointing at the target site (or org-scoped key + a `site_id` argument per call).
-- Target Typeroll site exists. **Empty starter site is best.** If non-empty, treat existing pages and collections as off-limits unless the user explicitly says otherwise.
-- The Astro design / theme is **not** being migrated — Typeroll has its own design layer. We migrate content; the user re-skins on the Typeroll side.
-
-## Recipe
-
-### 1. Map the source
-
-From the Astro repo root:
-
-```bash
-ls src/content/                  # which collections exist?
-cat src/content/config.ts        # collection schemas (zod)
-ls src/pages/                    # standalone pages
-ls public/                       # static assets and images
-```
-
-Build a working manifest:
-
-| Astro source | Typeroll target |
-|---|---|
-| `src/content/blog/*.md` | Collection `blog` with items |
-| `src/content/projects/*.mdx` | Collection `projects` with items |
-| `src/pages/about.astro` | Page with slug `about` |
-| `src/pages/services/[slug].astro` | If dynamic from a collection → that collection's `route_template`. If genuinely per-page → individual Typeroll pages. |
-| `public/og/*.png`, `public/images/*` | Upload to Typeroll media via `upload_media_from_url` (after staging them on a temporary public URL) or via local upload if the MCP supports it. |
-| `src/layouts/*.astro` | Header / footer / shared chunks → Typeroll partials. The rest of the layout is the site design, owned by the target site. |
-| `src/components/*.astro` | Either become partials (if reused across pages) or get inlined into the page that uses them. |
-
-### 2. Learn the target's design (don't skip)
-
-```
-get_site
-read_site_settings           # colours, fonts, voice
-list_partials
-read_partial partial_id="header"
-list_pages limit=5
-```
-
-Same rule as in `tr-migrate-wp`: you're moving content into the *target's* visual language, not preserving the source's. Note the existing fonts, colour vars, header structure.
-
-### 3. Translate one collection schema
-
-Pick the most representative collection first (usually `blog`). Read its zod schema:
-
-```ts
-// src/content/config.ts
-const blog = defineCollection({
-  type: 'content',
-  schema: z.object({
-    title: z.string(),
-    description: z.string(),
-    pubDate: z.coerce.date(),
-    updatedDate: z.coerce.date().optional(),
-    heroImage: z.string().optional(),
-    author: z.string().default('Editorial'),
-    tags: z.array(z.string()).default([]),
-    draft: z.boolean().default(false),
-  }),
-});
-```
-
-Map zod types to Typeroll field types:
-
-| Astro zod | Typeroll field type |
-|---|---|
-| `z.string()` | `text` (or `textarea` if it's a description/excerpt — judge by typical length) |
-| `z.string().long()` / a description field | `textarea` |
-| `z.coerce.date()` / `z.date()` | `date` |
-| `z.number()` | `number` |
-| `z.boolean()` | `boolean` |
-| `z.string()` with image path / `image()` helper | `image` |
-| `z.array(z.string())` | `text` (comma-joined) or `tags` if you have a tags field type |
-| `z.enum([...])` | `text` with a comment about the allowed values; the model writes the listing logic |
-| `z.object({...})` (nested) | Flatten into prefixed fields, or pre-render into a `*_html` field (see `tr-collection-template`) |
-| Markdown body | `body: richtext` (the markdown content of the file, converted to HTML — see §4) |
-
-Create the collection with the design template baked in (this is the new pattern — read `tr-blog` if you haven't yet):
-
-```
-create_collection {
-  "name": "blog",
-  "label_singular": "Article",
-  "label_plural": "Articles",
-  "slug_field": "slug",
-  "sort_field": "date",
-  "sort_dir": "desc",
-  "route_template": "/blog/{slug}",
-  "fields": [
-    {"name":"title",       "type":"text",     "required":true},
-    {"name":"slug",        "type":"text",     "required":true},
-    {"name":"description", "type":"textarea"},
-    {"name":"date",        "type":"date",     "required":true},
-    {"name":"updated_date","type":"date"},
-    {"name":"hero_image",  "type":"image"},
-    {"name":"author",      "type":"text"},
-    {"name":"tags",        "type":"text"},
-    {"name":"body",        "type":"richtext"}
-  ],
-  "item_template_html": "<article class=\"post\">...</article>"
-}
-```
-
-Field-name rules: ASCII, lowercase, `[a-z][a-z0-9_-]*`. The Astro source `pubDate` → Typeroll `date`. `updatedDate` → `updated_date` (snake_case is fine; camelCase isn't).
-
-### 4. Convert markdown bodies → richtext
-
-Astro stores the markdown body as the file content after the `---` frontmatter fence. Typeroll's `body: richtext` wants HTML. Pick one of:
-
-**Option A — use Astro's own markdown renderer (preferred when the repo already builds):**
-
-```js
-import { unified } from 'unified';
-import remarkParse from 'remark-parse';
-import remarkRehype from 'remark-rehype';
-import rehypeStringify from 'rehype-stringify';
-
-const md2html = async (md) => {
-  const file = await unified()
-    .use(remarkParse)
-    .use(remarkRehype, { allowDangerousHtml: true })
-    .use(rehypeStringify, { allowDangerousHtml: true })
-    .process(md);
-  return String(file);
-};
-```
-
-Run this on the body of every collection file. Image references inside the markdown (`![alt](./hero.png)`) need their `src` rewritten to the uploaded Typeroll CDN URLs after step 6.
-
-**Option B — convert ad-hoc:** `marked`, `markdown-it`, or any other parser. Just stay consistent across files so the HTML output looks uniform.
-
-Typeroll's sanitiser will strip `<script>` and event handlers from the output regardless. If the markdown carried embedded raw HTML you want to keep (iframes for video, etc.), check the sanitiser config in `packages/site-template/src/lib/sanitize.ts` for the whitelist.
-
-### 5. Resolve and upload images
-
-For every image referenced by an item (`heroImage`, images inside the markdown body):
-
-1. Stage the local file at a temporary public URL (or use a local-upload MCP tool if one is configured).
-2. `upload_media_from_url url=<staged-url> alt=<from frontmatter or filename>` — record the returned CDN URL.
-3. Substitute the CDN URL into both the `hero_image` field value AND the markdown-converted HTML body (regex replace `src=` references).
-
-Keep a local map (`./astro-migration-state.json`):
-
-```json
-{
-  "media": {
-    "./hero.png": "https://cdn.typeroll.com/<orgId>/<siteId>/abc123.png"
-  }
-}
-```
-
-So a partial run is resumable and you don't re-upload the same image twice.
-
-### 6. Batch-import items
-
-For each file in `src/content/<collection>/`:
-
-```js
-import fs from 'node:fs';
-import path from 'node:path';
-import matter from 'gray-matter';
-
-const files = fs.readdirSync('src/content/blog').filter(f => /\.mdx?$/.test(f));
-for (const file of files) {
-  const raw = fs.readFileSync(`src/content/blog/${file}`, 'utf8');
-  const { data, content } = matter(raw);
-  const slug = file.replace(/\.mdx?$/, '');
-  const body = await md2html(content);
-
-  // create_collection_item via the MCP
-  await mcp.callTool('create_collection_item', {
-    collection: 'blog',
-    status: data.draft ? 'draft' : 'published',
-    fields: {
-      title:        data.title,
-      slug,
-      description:  data.description,
-      date:         data.pubDate ? new Date(data.pubDate).toISOString().slice(0, 10) : null,
-      updated_date: data.updatedDate ? new Date(data.updatedDate).toISOString().slice(0, 10) : null,
-      hero_image:   mediaMap[data.heroImage] || data.heroImage,
-      author:       data.author,
-      tags:         (data.tags || []).join(', '),
-      body,
-    },
-  });
-}
-```
-
-Rate-limit awareness: spawn at most 5 parallel `create_collection_item` calls; the API caps at ~60 writes/minute and responds with 429 + `Retry-After` if exceeded.
-
-Set `status: 'draft'` (or honour Astro's `draft: true` frontmatter) for items the user should review before publishing. Only published items get static pages.
-
-### 7. Build the listing page
-
-```
-create_page title="Blog" slug="blog" status="published" content_mode="html"
-  html_content="<section><h1>Blog</h1>
-  <!-- typeroll:listing:blog -->
-  <!-- /typeroll:listing:blog -->
-</section>"
-
-regenerate_collection_listing
-  collection="blog"
-  page_id="blog"
-  item_template="<article class=\"blog-card\"><a href=\"{{url}}\"><h2>{{title}}</h2><p>{{description}}</p><time>{{date}}</time></a></article>"
-  wrap_open="<div class=\"blog-grid\">"
-  wrap_close="</div>"
-```
-
-See `tr-blog` for full styling and post-import update flow.
-
-### 8. Translate standalone pages
-
-For each non-dynamic `.astro` page under `src/pages/`:
-
-```
-read_partial partial_id="header"          # learn target's nav style
-# Re-skin the page content using target site's CSS variables and partials.
-create_page title="About" slug="about" status="draft" content_mode="html"
-  html_content="..."
-```
-
-Default to **draft** — the user reviews each page before publishing.
-
-For dynamic Astro pages (`[slug].astro` that consume a collection), you're already done: the matching Typeroll collection's `route_template` produces the same URLs at build time.
-
-### 9. Add redirects for URL changes
-
-If Astro's slugs differed from what you derived for Typeroll (e.g. Astro had `/posts/my-article` but you want `/blog/my-article`), bulk-add redirects:
-
-```
-add_redirect from="/posts/my-article" to="/blog/my-article" status=301
-```
-
-Or build a redirect map from the `astro-migration-state.json` and apply it in one pass.
-
-### 10. Deploy
-
-```
-trigger_deploy
-get_deploy_status job_id=<id>
-```
-
-Browse the resulting site, compare against the Astro source, surface anything that drifted.
-
-## Astro-specific gotchas
-
-- **`.mdx` files with custom components.** Components inside MDX (`<MyCustom prop="..." />`) will not render in Typeroll because the component definitions don't migrate. Two options: (1) replace each component with its rendered HTML output (run the Astro build, scrape the rendered HTML, use that as `body`); (2) if the component is a reusable visual element used across many items, factor it into a Typeroll partial and replace MDX usages with `<x-include name="..." />` calls. See `tr-page-template` for the partial-include pattern.
-- **`src/content/config.ts` typed `image()` helper.** Astro resolves `image()` fields at build time to optimised assets. After migration the Typeroll `hero_image` field carries the original source URL — re-upload via step 5 to get it onto the Typeroll CDN.
-- **`getCollection` filters at runtime.** If `src/pages/blog/index.astro` does `getCollection('blog', ({ data }) => !data.draft)`, Typeroll handles this via `status` on the item. Don't translate the filter — set `status: 'draft'` on items where `data.draft === true`.
-- **Per-tag pages (`/blog/tag/[tag].astro`).** Typeroll doesn't auto-generate these. Either (a) drop tag pages and use a client-side filter in the blog listing JS, (b) generate them by enumerating unique tags and calling `create_page` per tag with a server-side-pre-filtered listing. (a) is preferable for ≤dozens of tags.
-- **`rehype-pretty-code` / shiki / fenced code with syntax highlighting.** The HTML output of these contains inline styles that the Typeroll sanitiser preserves. The colours match the Astro site's theme at import time; redoing the target design later means re-running the highlighter against the same markdown source. Keep a copy of the raw markdown if you might.
-- **`og:image` per page from `astro-og-image` style plugins.** Typeroll has its own SEO surface (`seo_title`, `seo_description`, `seo_og_image`). Set them explicitly on each page during step 8.
-- **i18n via `src/content/<lang>/<collection>/`.** Typeroll's site-level `default_language` + per-page `language` field cover this (capabilities: `supports_language_per_page: true`). Map each language directory to per-item `language: 'sv-SE' | 'en-US' | …` instead of separate collections.
-
-## Mixing imported + new content
-
-Half-migrate, leave drafts, let the user inspect, iterate. You can:
-
-- Import only collections, skip standalone pages, let the user rebuild those from scratch.
-- Import everything as `status: 'draft'`, treat publishing as a per-item human review pass.
-- Mix sources: pull article bodies from Astro markdown, use Claude to generate fresh excerpts/SEO metadata before writing the item.
-
-Keep the local `astro-migration-state.json` honest — it's the only way to make a partial run resumable when the API rate-limits or a markdown parser trips on an edge case file.
-
-## Storage prerequisite
-
-Before reading or importing source content, call `get_import_readiness` (Core
-0.1.95 / MCP 0.44.68 or later). If `ready` is false, stop the import and show the
-returned message and Publishing settings link. The organization must connect
-and verify its own storage first. Do not fall back to draft storage, hotlink
-source images, or use ordinary page-write tools to bypass the import gate.
-Use `upload_media_from_url` for referenced source images; the customer’s
-Cloudflare transfer Worker copies and verifies them directly in R2, independently
-of the GitHub/Cloudflare build-provider choice.
+# Migrate an Astro site
+
+Astro Content Collections are source data. In Typeroll, each source record
+becomes a Page, and each source schema becomes a Content type. Static Astro
+pages use that same Page model. Shared Astro layouts become Page templates,
+partials or reusable block types; no separate item storage is created.
+
+## Inventory before writing
+
+Read the source repository's routing, content loaders, schema, frontmatter,
+layouts, components, styling and public assets. New Astro projects can define
+loaders in `src/content.config.ts`; older projects may use
+`src/content/config.ts` and files under `src/content/`. Follow what the actual
+project uses, including generated route logic and trailing-slash policy.
+
+Discover the target with `get_site`, `get_site_capabilities`, `list_pages`,
+`list_content_types`, `list_page_templates` and `list_block_types`. Existing target
+content remains out of scope unless the user authorized replacing it. Create a
+site version for the migration and pass it consistently on all versioned calls.
+Call `get_migration_readiness` before import; connect verified customer storage
+before transferring any source content or media.
+
+Record a URL inventory from the existing site and source routing. Use explicit
+Page paths to preserve nested routes or frontmatter-based permalinks. Do not
+assume that a filename alone determines the production URL.
+
+## Map the source
+
+- Common frontmatter such as title, slug, author, publication date and SEO maps
+  to top-level Page metadata.
+- Other schema fields become the Content type's custom fields and Page `fields`.
+  Preserve typed objects and arrays; use `page_ref`/`page_ref_list` for relations.
+- Markdown becomes native Page body blocks. First render Markdown to HTML using
+  the source project's parser, then review block conversion. MDX components
+  require explicit equivalents; never drop them as if they were plain Markdown.
+- A shared layout becomes a reusable Page template with `template_content_slot`.
+  Assign it as the type's default. Header/footer and reusable fragments can be
+  partials. Use native blocks before choosing a rare reviewed HTML/embed exception.
+- Browser scripts, integrations and server-rendered endpoints need separate
+  review. A static Page cannot inherit a private server runtime by copying its
+  source text. Configure the supported Forms/Extension runtime explicitly.
+
+Create templates with `create_page_template`, types with `create_content_type`,
+then one `create_page` per source record. Use returned Page IDs, not source IDs
+or slugs, for later updates and previews. For linked content, create the Pages
+first and resolve their reference fields in a second pass.
+
+Upload assets to connected storage and rewrite source-relative image references
+to returned media URLs. Use direct upload URLs for local bytes and the customer
+transfer flow for remote media; do not relay large base64 payloads through the
+model. Preserve alt text, captions, dimensions, links and image variants.
+
+## Listing and verification
+
+An archive is a Page with `core/page_list` filtered by `content_type`. Configure
+sorting and pagination from the block schema. It reads saved Pages at build
+time; do not generate a second listing representation or call a regeneration tool.
+
+Check representative long/short bodies, code, tables, images, captions, embedded
+components and related links at desktop and mobile widths. Compare the source
+and Typeroll preview, then a fresh authorized static build. Verify every inventory
+URL and redirect, canonical/hreflang, sitemap inclusion, noindex state and assets.
+Save working copies before publication. Keep the source host and DNS in place
+until the candidate passes checks and the user authorizes its cutover.

package/skills/tr-migrate-multisite.md

@@ -6,7 +6,7 @@ description: Use when migrating SEVERAL sites at once — a WordPress multisite
 # Migrate a multisite / multi-domain family to Typeroll
 
 > **The buffer model (draft writes).** Every content write in this recipe
-> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> (pages, blocks and partials) lands in an unsaved per-doc
 > DRAFT — deploys and plain previews only see SAVED content. For recipe-style
 > build work, pass `save: true` on write calls (the work is pre-approved by
 > the task itself), or run `commit_working_copy` per doc before any

package/skills/tr-migrate-wp.md

@@ -6,7 +6,7 @@ description: Use when the user asks to migrate a WordPress site to Typeroll, men
 # Migrate from WordPress to Typeroll
 
 > **The buffer model (draft writes).** Every content write in this recipe
-> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> (pages, blocks and partials) lands in an unsaved per-doc
 > DRAFT — deploys and plain previews only see SAVED content. For recipe-style
 > build work, pass `save: true` on write calls (the work is pre-approved by
 > the task itself), or run `commit_working_copy` per doc before any
@@ -27,7 +27,7 @@ get_migration_readiness source_url="https://oldsite.com"
 ```
 
 When the migration includes reusable page/item layouts, include each proposed
-block composition and its collection fields in this same call. A
+block composition and its content type fields in this same call. A
 `waiting_for_native_support` result means leave that template intact and do
 not replace the gap with generic custom blocks, raw HTML, or corrective site
 CSS. Independent content and SEO work may continue. Rerun the review after the

package/skills/tr-new-site.md

@@ -6,7 +6,7 @@ description: Use when the user wants to create a new Typeroll site from scratch,
 # Bootstrap a new Typeroll site
 
 > **The buffer model (draft writes).** Every content write in this recipe
-> (pages, blocks, partials, collection items) lands in an unsaved per-doc
+> (pages, blocks and partials) lands in an unsaved per-doc
 > DRAFT — deploys and plain previews only see SAVED content. For recipe-style
 > build work, pass `save: true` on write calls (the work is pre-approved by
 > the task itself), or run `commit_working_copy` per doc before any
@@ -55,11 +55,11 @@ Common requirements that are easy to misclassify:
 |---|---|
 | Full-bleed hero flush below the header | `core/section` + `core/hero`; block-mode sections already own the full width and have no page-shell padding |
 | Responsive icon/card grid | `core/grid` + `core/icon_box`, or `core/feature_grid`; set responsive fields with `set_block_responsive` |
-| Custom cards backed by a collection | `core/repeater` / `core/collection_list` with a site-authored `item_compatible` block type as `item_block` |
-| Grouped collection listing | `core/repeater` with `group_by`; array-valued fields place an item in every matching group |
+| Custom cards backed by Pages | `core/repeater` / `core/page_list` with a site-authored `item_compatible` block type as `item_block` |
+| Grouped Page listing | `core/repeater` with `group_by`; array-valued fields place an item in every matching group |
 | Breadcrumbs in a page template | `template/page_breadcrumbs`; page and item routes supply a server-rendered trail |
-| Generated heading index | `core/table_of_contents`; choose heading levels and set `source_field` for collection content |
-| Previous/next collection item links | `template/item_navigation`; defaults to collection order and can bind explicit neighbor fields |
+| Generated heading index | `core/table_of_contents`; choose heading levels and set `source_field` for Page content |
+| Previous/next Page links | `template/page_navigation`; defaults to content type sort order and can bind explicit neighbor fields |
 | Download CTA that disappears without a file | `template/show_if` around a context-bound `core/button`; a dedicated download block is only editor convenience |
 | Sticky/custom header and multi-column footer | Block-mode header/footer partials plus layout blocks, or one reusable custom block type |
 | Cookie notice | `settings.cookie_consent`, not a page block |
@@ -199,14 +199,14 @@ truth):
   (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`,
+- **Repeaters/listings:** `core/page_list`, `gallery`,
   `feature_grid` etc. — alias blocks over `core/repeater`. Use these for
-  collection-driven content instead of hand-writing listing markup. The base
+  Pages of a content type instead of hand-writing listing markup. The base
   repeater also supports `group_by`, group ordering/headings, multi-valued
   membership, filters, custom `item_block`, and `item_overrides`.
 - **Long-form navigation:** `core/table_of_contents` builds an anchor list
-  from page headings. Collection block templates use
-  `template/item_navigation` for deterministic previous/next links.
+  from page headings. Page templates use
+  `template/page_navigation` for deterministic previous/next links.
 - **Forms:** `create_form`, then place `core/form` with its `form_id`.
   HTML-mode pages use `<x-form id="…" />`; both paths render the same signed
   shell and runtime. See `tr-forms`.