@timelesscms-com/mcp-server 0.1.0

package/skills/tcms-content-write.md

@@ -0,0 +1,105 @@
+---
+name: tcms-content-write
+description: Use when the user asks to write, draft, or rewrite a page on a TimelessCMS site. Loads the site's design conventions before writing so the new content matches the existing voice and style.
+---
+
+# Write a page that fits the site
+
+The default failure mode for an AI writing a page is "good generic
+HTML in the wrong voice." This skill makes the discovery step
+non-optional.
+
+## Recipe
+
+### 1. Always discover first
+
+```
+get_site                          # site name (use it in copy)
+read_site_settings                # tagline, contact info, brand colors
+read_partial partial_id="header"  # what other pages exist in the nav
+list_pages limit=5
+batch_read_pages page_ids=[<2-3 representative pages>]
+```
+
+Read the actual HTML of an existing page. Note:
+- Heading structure (single `<h1>` per page? subtitle pattern?)
+- Whether the site uses CSS variables (`var(--color-primary)`) or
+  hardcoded values
+- Tone (sober, playful, technical, marketing-y)
+- Length conventions (do existing pages run 200 words or 2000?)
+- Whether internal links use absolute or relative URLs
+
+### 2. Ask for the brief
+
+If the user hasn't told you, ask:
+
+- **Topic + purpose**: what's the page for, who's it for?
+- **Key points**: must-include facts, calls to action
+- **Target length**: short landing vs. long-form
+- **Audience**: anything specific (existing customers, agencies,
+  developers)
+- **Reference page**: is there an existing page to match in tone or
+  structure?
+
+### 3. Draft
+
+Write in semantic HTML, matching the site's conventions you observed
+in step 1:
+
+- Use `<section>`, `<article>`, `<h1>`/`<h2>`, `<p>`, `<ul>` — avoid
+  div soup.
+- Match the existing site's class naming or CSS variable usage. Don't
+  introduce a new design system mid-page.
+- Insert images via `<img src="https://cdn..." alt="...">` — use
+  `list_media` to find existing images first; only generate new ones
+  if necessary (see `tcms-images` skill).
+- Default status: `draft`. Don't auto-publish unless the user said so.
+
+### 4. Create or update
+
+```
+# New page:
+create_page title="..." slug="..." html_content="<full body>"
+            status="draft" kind="page"
+            seo_title="..." seo_description="..."
+
+# Or update an existing one:
+update_page page_id=<id> patch={ html_content: "..." }
+```
+
+For an existing page, `read_page` first and preserve the existing
+structure — replace one section at a time rather than rewriting the
+whole body, unless the user explicitly asked for a full redo.
+
+### 5. Preview + iterate
+
+```
+get_preview_link page_id=<id>
+```
+
+Show the URL to the user. Iterate on feedback. Common rounds:
+shortening, adding a CTA, tweaking SEO description.
+
+### 6. Status change is the user's call
+
+Don't `update_page status:"published"` without an explicit "looks
+good, publish it" from the user. Same for `trigger_deploy`.
+
+## SEO conventions worth knowing
+
+- **`kind: "article"`** for blog posts and news. Switches to
+  `og:type=article` + emits Article JSON-LD. Set `author` too — empty
+  author = no Person schema = no author rich-result eligibility.
+- **SEO title** target 50-60 chars. Past 60 Google truncates.
+- **Meta description** target 150-160 chars. Don't write fluff to
+  fill it; Google rewrites descriptions when they go off-topic.
+- **OG image** per page matters for shareable content. For articles
+  especially.
+
+## Pitfalls
+
+- Reading 0 pages and just inventing a design is the most common
+  failure. Always sample at least one existing page first.
+- Skipping the brief and producing 1000 words of plausible filler when
+  the user wanted a 200-word landing. Ask up front.
+- Auto-publishing. Don't.

package/skills/tcms-directory.md

@@ -0,0 +1,214 @@
+---
+name: tcms-directory
+description: Use when the user wants to build a directory site or import a structured dataset (restaurants, products, events, agencies, etc.) where each item should have its own URL. Covers collection schema creation, per-item URLs via route_template, listing page, deploy.
+---
+
+# Build a directory site from external data
+
+TimelessCMS collections support per-item URLs: every published item
+in a collection with a `route_template` materialises as its own static
+page at build time. This is the right pattern when you have hundreds
+of similar entities (restaurants, products, listings, profiles).
+
+## Big-picture flow
+
+1. **Data source** → 2. **Collection schema** → 3. **Items** → 4. **Listing page**
+→ 5. **Preview** → 6. **Deploy**
+
+You drive everything from Claude Code locally — the scrape, the data
+shaping, the writes. The MCP just receives the final shape.
+
+## Recipe
+
+### 1. Get the data
+
+Whatever source the user has — scraped CSV, public API, vendor feed,
+manual research, another LLM's output. Normalise to a flat shape:
+one object per item with stable, kebab-case field names.
+
+```jsonc
+[
+  {
+    "title": "Joe's Pizza",
+    "slug": "joes-pizza",
+    "address": "123 Main St, Anytown",
+    "phone": "+1-555-0100",
+    "cuisine": "italian",
+    "rating": 4.5,
+    "image": "https://...",        // optional: a hosted image URL
+    "excerpt": "Family-run since 1987...",
+    "body": "<p>Long-form description with HTML.</p>"
+  }
+]
+```
+
+The `slug` field is what populates `route_template`. Make it
+kebab-case, unique within the dataset. If the source doesn't have one,
+derive from `title`: lowercase, replace non-alphanumeric with `-`,
+collapse consecutive dashes.
+
+### 2. Decide the URL structure with the user
+
+Common patterns:
+
+- `/restaurants/{slug}` (default — simple, predictable)
+- `/r/{slug}` (compact)
+- `/{cuisine}/{slug}` (categorised)
+- `/dir/{slug}` (short prefix to avoid collisions with page slugs)
+
+Pick one before creating the collection — changing `route_template`
+later renames every URL and requires redirect rules.
+
+### 3. Create the collection schema
+
+```
+create_collection
+  name="restaurants"
+  label_singular="Restaurant"
+  label_plural="Restaurants"
+  icon="🍕"
+  fields=[
+    {"name":"title","label":"Name","type":"text","required":true},
+    {"name":"slug","label":"Slug","type":"text","required":true},
+    {"name":"address","label":"Address","type":"text"},
+    {"name":"phone","label":"Phone","type":"text"},
+    {"name":"cuisine","label":"Cuisine","type":"text"},
+    {"name":"rating","label":"Rating","type":"number"},
+    {"name":"image","label":"Image URL","type":"text"},
+    {"name":"excerpt","label":"Excerpt","type":"textarea"},
+    {"name":"body","label":"Body","type":"richtext"}
+  ]
+  slug_field="slug"
+  sort_field="title"
+  sort_dir="asc"
+  route_template="/restaurants/{slug}"
+  item_template_html="<article class=\"directory-item\">
+    <header>
+      <h1>{{title}}</h1>
+      {{cuisine}} · ⭐ {{rating}}
+    </header>
+    <img src=\"{{image}}\" alt=\"{{title}}\" />
+    <address>{{address}} · <a href=\"tel:{{phone}}\">{{phone}}</a></address>
+    <section class=\"description\">{{{body}}}</section>
+  </article>"
+```
+
+The `item_template_html` is what renders for each item. `{{field}}`
+HTML-escapes; `{{{field}}}` leaves raw (use for richtext bodies that
+intentionally carry HTML).
+
+### 4. Bulk-import items
+
+Loop over your data array. For each item:
+
+```
+create_collection_item
+  collection="restaurants"
+  fields={ title:"Joe's Pizza", slug:"joes-pizza", ... }
+  status="published"
+```
+
+For larger datasets (1000+), batch outside the MCP — spawn 5 parallel
+`create_collection_item` calls at a time, watch the 60-writes/min rate
+limit (you'll hit it on big imports, the API returns 429 with
+`Retry-After`).
+
+Set `status: "draft"` for items the user still needs to review; only
+published items get static pages.
+
+### 5. Build a listing page
+
+Items have per-item URLs but not a default index. Create one with a
+marker pair that `regenerate_collection_listing` will keep up to date:
+
+```
+create_page
+  title="Restaurants"
+  slug="restaurants"
+  status="published"
+  html_content="<h1>All restaurants</h1>
+    <!-- tcms:listing:restaurants -->
+    <!-- /tcms:listing:restaurants -->
+  "
+```
+
+Then populate (and refresh whenever items change) with one call:
+
+```
+regenerate_collection_listing
+  collection="restaurants"
+  page_id="restaurants"
+  item_template="<article class=\"directory-card\">
+    <h2><a href=\"{{url}}\">{{title}}</a></h2>
+    <p>{{cuisine}} · ⭐ {{rating}}</p>
+    <p>{{address}}</p>
+  </article>"
+  wrap_open="<div class=\"directory-grid\">"
+  wrap_close="</div>"
+```
+
+`{{field}}` substitutes HTML-escaped, `{{{field}}}` raw (for richtext
+fields), `{{url}}` resolves through the collection's `route_template`.
+The tool replaces only what's between the marker pair — anything before
+or after the markers stays put.
+
+When the customer adds a new restaurant later, the agent re-runs the
+same `regenerate_collection_listing` call and the index updates. No
+diff-the-HTML-by-hand, no stale listings.
+
+(When the block editor lands, you'll be able to drop in a "collection
+listing" block instead of hand-writing this. For now, raw HTML.)
+
+### 6. Preview an item
+
+```
+get_preview_link collection_name="restaurants" item_id="<id>"
+```
+
+Returns a URL the user can open. Internal links inside the preview
+stay inside the preview surface, so navigating to another item works.
+
+### 7. Deploy
+
+```
+trigger_deploy
+get_deploy_status job_id=<id>
+```
+
+Each published item gets its own URL in the static build, with
+`sitemap.xml` automatically including them all.
+
+## Pitfalls
+
+- **Slugs must be unique within the collection** — duplicates cause
+  build failures (two pages claiming the same URL). De-dupe before
+  importing.
+- **Don't reuse `slug` across collections without thinking.**
+  `/restaurants/joes` and `/products/joes` are fine; just avoid
+  `/joes` for both (collection items vs. pages don't collide because
+  pages always win, but two collections sharing a `slug_field=slug`
+  with the same `route_template` is a foot-gun).
+- **Required fields.** `route_template="/restaurants/{slug}"` will
+  silently skip items where `slug` is missing. Check
+  `list_collection_items` after import — if you imported 500 and the
+  listing only shows 480, look at the dropped 20's source data.
+- **Template too clever.** Substitution is plain `{{field}}` — no
+  loops, no conditionals. If your design needs more, prefer flat
+  fields (`star_html`, `rating_label`) prebuilt in the data step.
+- **Field type changes drift data.** Adding a new field after import
+  is fine; renaming one orphans the old data on every item. Plan the
+  schema before import.
+
+## Mixing scraped + generated content
+
+The whole point of the local-agent model: you can blend sources.
+
+- Scrape addresses + phone from a yellow-pages site.
+- Generate excerpt + body from a local Claude pass over the raw
+  scraped HTML.
+- Generate hero images per item via `tcms-images`.
+- All three merged into one `create_collection_item` per record.
+
+Keep a local manifest (`./directory-state.json`) of what's been
+imported so a partial run is resumable. The MCP doesn't track that
+state — your local script does.

package/skills/tcms-images.md

@@ -0,0 +1,152 @@
+---
+name: tcms-images
+description: Use when the user asks for an image, hero, illustration, or logo to be created and embedded in a TimelessCMS 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 TimelessCMS site
+
+The TimelessCMS 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/tcms-migrate-wp.md

@@ -0,0 +1,151 @@
+---
+name: tcms-migrate-wp
+description: Use when the user asks to migrate a WordPress site to TimelessCMS, 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 TimelessCMS
+
+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
+
+- `@timelesscms-com/mcp-server` configured with a valid `TCMS_API_KEY`.
+- The source WP site has `/wp-json` reachable (Google for "wordpress
+  REST API disabled" if not — common for hardened hosts).
+- The TimelessCMS 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/timelesscms/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 TimelessCMS
+  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.