@typeroll/mcp-server 0.7.4

package/skills/tr-images.md

@@ -0,0 +1,152 @@
+---
+name: tr-images
+description: Use when the user asks for an image, hero, illustration, or logo to be created and embedded in a Typeroll page. Covers the two-step signed-URL upload flow so the agent doesn't try to POST bytes through the CMS API (it can't).
+---
+
+# Add images to a Typeroll site
+
+The Typeroll API does NOT accept image bytes directly. Uploads go
+through a signed PUT URL straight to Cloudflare R2, and the API only
+sees the metadata. Two-step flow:
+
+## Recipe
+
+### 1. Get an image
+
+Options, in order of preference:
+
+a. **Reuse an existing one.** `list_media` returns CDN URLs for every
+   image already on this site. Search the list before generating
+   anything — saves bandwidth and keeps the visual catalog tight.
+
+b. **Generate locally.** The user's Claude Code installation has
+   access to whatever image-gen tools they've configured (DALL-E,
+   Midjourney, Stable Diffusion, Replicate, etc.). Generate and save
+   to a tempfile.
+
+c. **Source from the web** with appropriate licensing (the user is
+   responsible for clearing rights). Save locally before upload.
+
+### 2. Mint a signed upload URL
+
+```
+create_upload_url filename="hero-services.png"
+                  content_type="image/png"
+                  size=<bytes>
+                  alt_text="Office worker reviewing documents at a desk"
+```
+
+Returns:
+
+```json
+{
+  "upload_url": "https://...r2.cloudflarestorage.com/.../signed-...",
+  "cdn_url": "https://cdn.example.com/orgs/.../images/...png",
+  "key": "orgs/.../images/...png",
+  "media_id": "abc123",
+  "expires_in": 300
+}
+```
+
+The signed URL is valid for 5 minutes. The media doc is already
+registered — even before the upload completes — so it'll show in
+`list_media` immediately.
+
+### 3. PUT the bytes
+
+Outside the MCP, hit the signed URL directly:
+
+```
+PUT <upload_url>
+Content-Type: <same content_type as in step 2>
+Body: <file bytes>
+```
+
+In a shell:
+
+```bash
+curl -X PUT "<upload_url>" \
+  -H "Content-Type: image/png" \
+  --data-binary @hero-services.png
+```
+
+Or from JS (Claude Code can run a one-line script):
+
+```js
+await fetch(uploadUrl, {
+  method: 'PUT',
+  headers: { 'Content-Type': contentType },
+  body: await fs.readFile(path),
+});
+```
+
+A 200 OK from R2 means the image is now live at `cdn_url`.
+
+### 4. Patch metadata (alt text, etc.)
+
+You set `alt_text` at create time, but if you generate the image first
+and only THEN realize what to caption it as, patch later:
+
+```
+update_media media_id=<id> alt_text="..." filename="hero-services-v2.png"
+```
+
+### 4b. Fill missing alt-text on existing media
+
+When a customer has uploaded a bunch of images without alt-text (very
+common after a WP migration), don't make it up — use vision:
+
+```
+list_media                                 → find items with empty alt_text
+suggest_alt_text_context media_id=<id>     → returns { image_url, suggested_prompt,
+                                              language, used_on_pages, current_alt_text }
+# Pass image_url + the returned suggested_prompt to YOUR OWN vision
+# capability (you can fetch the URL and pass bytes to vision).
+update_media media_id=<id> alt_text="<what vision returned>"
+```
+
+The prompt is tuned for SEO-grade output: short (5-15 words), no "image
+of / picture of" filler, written in the site's content language,
+decorative images return empty string. Run it sequentially on a
+list_media batch and you can fix alt-text gaps across a whole site
+without burning your context on prompt design. The platform does NOT
+run vision on your behalf — your model does, your usage.
+
+### 5. Embed in a page
+
+`read_page` the target, insert `<img>` in the right spot:
+
+```html
+<img src="<cdn_url>"
+     alt="<alt_text>"
+     style="width: 100%; height: auto; display: block; margin: 2rem 0;" />
+```
+
+Then `update_page` with the new HTML. Or, if you're generating a hero
+for a brand-new page, include the `<img>` directly in `create_page`'s
+`html_content`.
+
+## Pitfalls
+
+- **Always set `alt_text`.** Empty alt is bad for SEO + accessibility.
+  Default to a one-sentence description of what's in the image.
+- **`<script>` etc. in SVGs.** The page sanitizer drops `<script>`
+  inside SVG, so an icon set that includes script-based animations
+  won't render correctly. Use static SVG or a JPG/PNG export.
+- **CSS background-image references aren't dedup'd.** If you set the
+  same image as a CSS background on multiple pages, the alt-text +
+  metadata are page-irrelevant. The sanitizer allows
+  `background-image: url(...)` in inline styles, but think about
+  whether an `<img>` is actually better.
+- **Source URL leakage.** If you generated the image from a prompt
+  that contains internal info, don't bake that prompt into the
+  filename. Use a descriptive but generic filename.
+
+## Format choice
+
+- **PNG** for logos, icons with hard edges, anything with text.
+- **JPG** for photos. Smaller file, better for big hero images.
+- **WebP** if the target audience runs modern browsers (95%+ in 2026).
+- **SVG** for icons + simple illustrations. Vector scales perfectly.
+- **PDF** is supported by `create_upload_url` for document downloads;
+  link with `<a href>`, not `<img>`.

package/skills/tr-migrate-wp.md

@@ -0,0 +1,151 @@
+---
+name: tr-migrate-wp
+description: Use when the user asks to migrate a WordPress site to Typeroll, mentions wp-json, or names a WP source URL. Walks the WP REST API, rebuilds pages in the target site's design, transfers media, sets redirects, leaves everything as drafts for human review.
+---
+
+# Migrate from WordPress to Typeroll
+
+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 (consultant /
+agency) reviews each step in their terminal.
+
+## Preconditions
+
+- `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY`.
+- The source WP site has `/wp-json` reachable (Google for "wordpress
+  REST API disabled" if not — common for hardened hosts).
+- The Typeroll target site exists. New, blank sites with the
+  starter design work best. If the target already has content, you
+  must NOT clobber it — always `list_pages` first and only write to
+  slugs that don't already exist.
+
+## Recipe
+
+### 1. Probe and inventory
+
+```
+fetch <wp-url>/wp-json                           # confirm REST is on
+fetch <wp-url>/wp-sitemap.xml or /sitemap.xml    # URL inventory
+```
+
+Build a list of every URL you intend to migrate. WP custom post types
+need their REST endpoint (e.g. `/wp-json/wp/v2/news?per_page=100`),
+walking `X-WP-TotalPages` to paginate.
+
+### 2. Learn the target's design
+
+```
+get_site
+read_site_settings                               # colors, fonts, voice cues
+list_partials                                    # header / footer / shared
+read_partial partial_id="header"                 # nav structure
+list_pages limit=5
+batch_read_pages page_ids=[<2-3 representative ids>]   # see actual conventions
+```
+
+Don't skip this. Imposing a stranger's design on a customer's site is
+the biggest avoidable mistake.
+
+### 3. Migrate one page at a time, draft status
+
+For each source URL:
+
+a. Fetch from WP. Prefer the helper plugin's authenticated endpoint
+   (`/wp-json/typeroll/v1/...`) if available — it bypasses
+   `show_in_rest=false` and returns ACF + builder fields. Otherwise
+   fall back to `/wp-json/wp/v2/<post-type>?slug=<slug>`.
+
+b. Clean the HTML. Strip Elementor / Gutenberg / Breakdance class
+   soup. Drop empty `<div>` and `<span>` wrappers. Keep semantic tags,
+   tables, iframes from known hosts (YouTube / Vimeo / Calendly).
+
+c. Migrate referenced images:
+   - For each `<img src>` and CSS `background-image: url()`:
+     1. Download the source image locally.
+     2. `create_upload_url filename=... content_type=...` → returns
+        `{ upload_url, cdn_url, media_id }`.
+     3. PUT the bytes to `upload_url` (curl or fetch with the same
+        content type).
+     4. Replace the `src` with `cdn_url` in the rewritten HTML.
+   - Use `update_media media_id=... alt_text="..."` to set a real alt
+     text (existing WP `alt` attribute or `aria-label`; fall back to
+     filename only as a last resort).
+
+d. Reconstruct in the target's design. The cleaned HTML is rarely
+   ready to ship — typical fixes: replace WP `wp-block-*` classes
+   with the target's CSS variables; turn Elementor sections into
+   plain `<section>` with the target's spacing; fix headings so the
+   page has exactly one `<h1>`. If you're confident, batch these
+   through `bulk_replace_text` with `dry_run: true` first.
+
+e. Write the page as a draft:
+
+   ```
+   create_page title="..." slug="<preserved-from-wp>"
+               html_content="<reconstructed>"
+               status="draft" kind="article" author="..."
+               seo_title="..." seo_description="..."
+   ```
+
+   **Preserve the source URL.** WP post URLs like
+   `/2024/01/foo-bar/` go in as `slug: "2024/01/foo-bar"`. The
+   slug supports slashes; encode the WP permalink structure verbatim
+   when the customer wants existing links to keep working.
+
+### 4. Redirects
+
+After migration, every URL the agent didn't preserve verbatim needs a
+redirect:
+
+```
+create_redirect from_path="/old-services" to_path="/services"
+```
+
+Walk the inventory; for each URL: did it become a page with the same
+path? If yes, no redirect. If renamed, `create_redirect`. If
+intentionally dropped, mark it excluded in your notes (the customer
+should sign off on every dropped URL).
+
+### 5. Preview + review with the user
+
+```
+get_preview_link page_id=<id>                    # one URL the user can click
+```
+
+Open in the user's browser. The preview navigates the whole site from
+one mint. Iterate on feedback: pages, header, footer.
+
+### 6. Ship
+
+When the user signs off:
+
+```
+# Bulk-publish drafts that look right
+batch_update_pages updates=[{page_id, patch:{status:"published"}}, ...]
+
+# Deploy
+trigger_deploy
+get_deploy_status job_id=<id>    # poll
+```
+
+## Pitfalls
+
+- **Don't publish during migration.** Always import as `draft`. Even
+  if the agent is confident, the customer needs the chance to spot-check.
+- **WP slugs sometimes drift.** A post saved with slug `foo-bar` may
+  have been served at `/2024/01/foo-bar/` due to the permalink
+  structure. The full URL is what users see in Google; preserve that,
+  not the bare slug.
+- **Image bandwidth.** R2 upload is metered. Use `find_pages_matching`
+  contains="<old-domain>" on already-imported content to spot images
+  that weren't transferred.
+- **WP-specific JSON-LD** (Yoast, Rank Math) is usually wrong after a
+  redesign because it references old URLs. Strip it; let Typeroll
+  emit fresh Article/Page schemas via `kind: 'article'` + `author`.
+
+## When the source isn't WordPress
+
+The same shape applies for any source — Squarespace export, custom
+CMS, scraped HTML, CSV. Replace step 1's "WP REST" probe with whatever
+discovery the source supports, and the rest of the recipe is unchanged.

package/skills/tr-redesign-branch.md

@@ -0,0 +1,149 @@
+---
+name: tr-redesign-branch
+description: Use when the user asks to redesign, modernize, or restructure a Typeroll site (or a section of it). Forces branch-isolated work so the live site stays untouched until the redesign is approved.
+---
+
+# Redesign a site without breaking the live one
+
+Site-wide changes are exactly where copy-on-write branches earn their
+keep. This skill enforces the discipline: every redesign happens on a
+branch, preview-checked end-to-end, merged only after user sign-off.
+
+## Recipe
+
+### 1. Discover (always)
+
+```
+get_site
+read_site_settings
+read_partial partial_id="header"
+read_partial partial_id="footer"
+list_pages limit=20
+batch_read_pages page_ids=[<top 3-5 pages>]   # see actual conventions
+list_partials                                  # what free blocks exist
+list_collections                               # any data we need to consider
+```
+
+Write the user a short read-back: *"This is a 12-page agency site
+using CSS variables, primary color #1e40af, Inter heading + Source
+Sans body. Existing pages are content-dense, single-column. Main nav
+has 5 items including a CTA. I'd suggest..."*
+
+Confirm direction before touching anything.
+
+### 2. Create a branch
+
+```
+create_branch name="<descriptive name>"
+```
+
+Save the response's `id` — pass it as `version=<id>` on every
+subsequent call. Branches default `robots_blocked: true` so a
+half-finished redesign won't be indexed.
+
+### 3. Iterate on the branch
+
+For each redesign step:
+
+a. Make the change with `?version=<branch-id>`. Updates here don't
+   touch main:
+
+   ```
+   update_partial partial_id="header" patch={...} version="<branch>"
+   update_page page_id=home patch={...} version="<branch>"
+   ```
+
+b. Preview after every meaningful change:
+
+   ```
+   get_preview_link page_id=home version="<branch>"
+   ```
+
+   Send the URL to the user. The preview navigates the whole branch
+   from one mint.
+
+c. Iterate on feedback. Common rounds: headline tightening, color
+   tweaks, swapping hero images.
+
+### 4. Site-wide changes through partials, not pages
+
+If the redesign touches every page (e.g. new global header, new
+footer, new CTA bar) — edit a partial, not 23 pages. Before editing a
+shared block, check the blast radius:
+
+```
+find_pages_using_block partial_id="header" version="<branch>"
+```
+
+This returns every page that would show the change. Communicate that
+to the user before the save.
+
+### 5. Bulk content cleanups via dry-run first
+
+If the redesign requires content rewrites (e.g. "remove every mention
+of the old company name"), use the bulk tool with dry-run:
+
+```
+search_pages contains="OldCo" version="<branch>"
+bulk_replace_text pattern="OldCo" replacement="NewCo" dry_run=true version="<branch>"
+# Show the user the sample_diffs
+bulk_replace_text pattern="OldCo" replacement="NewCo" dry_run=false version="<branch>"
+```
+
+### 6. Approval round
+
+Send the user a final preview link:
+
+```
+get_preview_link page_id=home version="<branch>" ttl_seconds=86400
+```
+
+The 24h TTL gives them time to share with stakeholders. Wait for an
+explicit "looks good, ship it."
+
+### 7. Merge + deploy
+
+```
+merge_branch version_id="<branch>"        # branch's diffs land on main
+trigger_deploy
+get_deploy_status job_id=<id>             # poll until succeeded
+```
+
+Optionally, after a successful deploy:
+
+```
+delete_branch version_id="<branch>"       # tidy up
+```
+
+(You can also leave the branch around as a record of the redesign;
+disk cost is tiny.)
+
+## Pitfalls
+
+- **Forgetting `version=` on writes.** Every call you make on the
+  branch must include `version=<branch-id>`. A missing one writes
+  straight to main — silent and bad.
+- **Skipping discovery.** "Modernize" without first reading the site
+  produces a confidently-out-of-place result. Always sample existing
+  pages.
+- **Editing the in-portal preview URL by mistake.** That's the user's
+  own preview, not yours. `get_preview_link` returns a signed
+  external URL — always use that for sharing.
+- **Auto-merge.** Don't `merge_branch` without explicit user sign-off.
+  Once merged, the only undo is another branch + reverse edits.
+- **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.
+
+## When to NOT use a branch
+
+Tiny edits — "fix the typo on the About page" — don't need a branch.
+The in-portal chat handles those directly on main. This skill is for
+work where:
+
+- The user might want to walk away mid-redesign and come back later
+- Multiple changes need to ship together
+- The site is high-traffic and "broken for an hour" is unacceptable
+- Stakeholder review across multiple pages is expected
+
+If none of those apply, edit main directly and move on.