@typeroll/mcp-server 0.7.4

package/AGENTS.md

@@ -0,0 +1,448 @@
+# AGENTS.md — Working on a Typeroll site
+
+You are connected to a Typeroll site through `@typeroll/mcp-server`.
+This file is your briefing: what the system is, what conventions matter,
+what tools to reach for first.
+
+If anything below conflicts with what you observe in the tools, trust the
+tools — the platform may have moved since this was written.
+
+## What this is
+
+Typeroll is a static-site CMS: content lives in a database, the user
+edits it through an in-app editor, and a deploy step compiles everything
+to a fast static site hosted on Cloudflare Pages. The in-app chat handles
+single-page or single-block edits by the editor audience. You — through
+this MCP — handle the work that doesn't fit there: site-wide redesigns,
+bulk content updates, structural migrations, directory imports.
+
+The MCP server is a thin wrapper around the public REST API. Each tool
+maps to one HTTP endpoint; the actual logic runs in the customer's portal
+(SaaS or self-hosted).
+
+## The data model in 90 seconds
+
+- **Pages.** Title, slug, status (`draft | review | unlisted | published`),
+  body content + SEO fields. Two body shapes selectable per page via
+  `content_mode`:
+  - `blocks` (DEFAULT for new pages) — `blocks: Block[]` tree of typed
+    blocks (heading, prose, section, columns, image, button, plus any
+    user/third-party block types installed on the site). Use the
+    block-mutation tools (`add_block`, `update_block`, `move_block`,
+    `remove_block`) for structural changes.
+  - `html` — body lives in `html_content` as a single HTML string.
+    Useful when you have hand-written markup to drop in directly.
+
+  Slug can contain slashes, so `2024/01/foo-bar` is a valid slug →
+  `/2024/01/foo-bar` URL. Encode hierarchy in the slug; the renderer
+  doesn't use `parent` for routing.
+
+- **Partials = global blocks.** Three kinds:
+  - `header` — auto-injected at the top of every page.
+  - `footer` — auto-injected at the bottom of every page.
+  - `free` — reusable HTML you drop into a page with
+    `<x-include name="block-id" />`. Free blocks are how you avoid
+    duplicating HTML across HTML-mode pages.
+
+  Partials themselves also support `content_mode='blocks'` — pass a
+  `blocks: Block[]` tree to `update_partial` and the renderer composes
+  it the same way as a page. Useful for header/footer authored with
+  block types.
+
+- **Collections.** Repeatable content types (blog, team, events,
+  products, restaurants for a directory site, etc.). Each has a schema
+  (`fields[]`) and optional **per-item routing** via `route_template`
+  (e.g. `/restaurants/{slug}`). When set, every published item gets its
+  own static URL rendered through `item_template_html`. Set
+  `route_template=""` to opt out and keep the collection listing-only.
+
+- **Settings.** Site name, tagline, logo, favicon, colors, fonts,
+  contact info, social links, SEO suffix, plus `scripts_head`,
+  `scripts_body_end`, `custom_css` (writable via the API — your bearer
+  token authorises shipping arbitrary CSS/JS to the live site, just
+  like editing a partial's HTML does).
+
+- **Page templates.** A `PageTemplate` is a Block[] tree that wraps a
+  page's body. The template contains exactly one block of type
+  `template_content_slot` — at render time that block gets replaced by
+  the page's own `blocks`. Set `Page.template = "<template-id>"` to
+  apply a template to a page.
+
+- **Block types.** A site has three sources of block types:
+  - **Core** (origin: 'core', ids like `core/section`) — shipped in
+    the platform, always available.
+  - **User** (origin: 'user') — created in the portal's block-types UI.
+  - **Third-party** (origin: 'third_party') — imported from .tcblocks
+    packages via `import_block_types`.
+
+  `list_block_types` returns ALL of them in one list, with each entry's
+  full schema (field names, types, defaults). Always call this FIRST
+  before working with blocks — never hardcode block ids or field names,
+  the available set is per-site.
+
+- **Redirects.** `from_path → to_path` with status code 301 / 302.
+  Auto-created when you change a page's slug.
+
+- **Versions / branches.** Copy-on-write. The "main" version is the
+  live one. Create a branch (`create_branch`) for multi-step work;
+  everything you write through `?version=<branch-id>` lives on the
+  branch until you `merge_branch` it back to main. Branches default
+  `robots_blocked: true` so a half-finished redesign can't be indexed,
+  and deploys land at a stable `{branch}.{project}.pages.dev` URL.
+
+- **Deploys.** Customers see live changes only after a deploy. Preview
+  always sees drafts. `trigger_deploy` enqueues; `get_deploy_status`
+  reports `queued → running → succeeded | failed`.
+
+- **Site URLs.** `get_site` returns a `urls` object with:
+    - `production` — the customer's real domain (or null)
+    - `fallback` — the auto `{slug}.typeroll.app`-style preview URL
+    - `preview_base` — the portal preview origin (for token URLs)
+  Use these in answers to "what's the URL?" — never invent.
+
+## Discovering this site
+
+Don't hardcode assumptions about what's here. Every fact about the site
+goes through the MCP:
+
+1. `get_site` — confirm the key works; learn the site name + URLs.
+2. `read_site_settings` — colors, fonts, contact info, SEO suffix,
+   content language (used by `suggest_alt_text_context`).
+3. `list_pages` — what pages exist, paginated.
+4. `list_partials` — what shared blocks already exist. **Defaults to
+   summary mode** (no html_content, just bytes count) — pass
+   `include_content: true` if you actually need the bodies inline.
+5. `list_collections` — what content types exist + their schemas +
+   `route_template` (so you know if items have URLs).
+6. `list_block_types` — every block type usable on this site: core
+   (always available, ids like `core/section`), custom (origin: 'user'),
+   and third-party (origin: 'third_party'). Each entry includes the
+   full schema so you know what `data.X` fields each block accepts.
+7. `list_page_templates` — PageTemplate docs that wrap pages.
+
+You usually want at least #1 + #2 + a sampling from #3 before
+proposing any design change, so you mirror the conventions in use.
+
+## Common operations
+
+### "Replace this string across the whole site"
+
+```
+search_pages contains="299 kr"             → matches + excerpts
+bulk_replace_text dry_run=true ...          → sample_diffs
+# show the user, get confirmation
+bulk_replace_text dry_run=false ...         → write
+trigger_deploy                              → ship
+get_deploy_status job_id=…                  → poll until succeeded
+```
+
+Writes go through the normal save pipeline (SEO transform + revision
+snapshot) so changes are reversible from the in-app History tab.
+
+### "Audit / understand the site"
+
+```
+list_pages limit=200                              → inventory
+batch_read_pages page_ids=[…]                     → bulk-load bodies
+list_partials                                     → shared blocks (summary)
+find_pages_using_block partial_id=<id>            → blast radius per block
+list_collections                                  → content types + routing
+list_collection_items collection=<name>           → items (richtext hidden)
+```
+
+`find_pages_using_block` for the header or footer returns the full
+page list (they're auto-injected on every page).
+
+### "Redesign the home page"
+
+```
+get_site + read_site_settings
+read_partial partial_id="header"
+list_pages → batch_read_pages a few existing pages    # learn conventions
+# Propose redesign locally; ask user to confirm.
+create_branch name="Home redesign"                    # ID is, say, "home-redesign"
+update_page page_id=home patch={ html_content: "…" } version=home-redesign
+get_preview_link page_id=home version=home-redesign   # signed clickable URL
+# Iterate. When approved:
+merge_branch version_id=home-redesign
+trigger_deploy
+```
+
+The branch also has its own permanent deploy URL at
+`https://home-redesign.<project>.pages.dev` after `trigger_deploy
+version=home-redesign` — useful for "share with stakeholders without
+showing them my preview token". `read_version version_id=home-redesign`
+returns it as `deploy_url`.
+
+### "Build a reusable block"
+
+If you see the same HTML on 3+ pages, propose a free block instead of
+duplicating it:
+
+```
+create_free_block id="newsletter-cta" html_content="<form>…</form>"
+# Then on each page where it should appear (HTML-mode pages):
+update_page page_id=… patch={ html_content: "<…><x-include name=\"newsletter-cta\" />" }
+```
+
+Edits to the block update every page that includes it. Use
+`find_pages_using_block` before changing it.
+
+### "Build a page using blocks (the default for new pages)"
+
+New pages default to `content_mode='blocks'` with a seeded heading +
+prose block. Discover-then-build:
+
+```
+list_block_types
+# → [{ id: "core/section", category: "layout", container: true, schema: [{ name: "width", type: "select", options: ["narrow","normal","wide","full"] }, …] },
+#    { id: "core/columns", container: "slots", slot_count: 2, slot_labels: ["Left","Right"], schema: [...] },
+#    { id: "hero_bold", origin: "user", schema: [...] },   ← any custom blocks on this site
+#    …]
+
+get_page_blocks page_id=home
+# → { content_mode: 'blocks', blocks: [...] }
+
+add_block page_id=home block={ type: 'core/section', data: { width: 'wide' } }
+# → { added_id: 'blk_xyz', blocks: [...] }
+add_block page_id=home parent_id="blk_xyz" block={
+  type: 'core/heading', data: { text: 'Pricing', level: 'h2' }
+}
+add_block page_id=home parent_id="blk_xyz" block={
+  type: 'core/prose', data: { html: '<p>…</p>' }
+}
+```
+
+For an unfamiliar custom block, `read_block_type id="..."` gives the
+full field list (types, defaults, required) so you don't ship invalid
+`data`.
+
+Updating, moving, removing blocks: `update_block`, `move_block`,
+`remove_block` (all by `block_id`).
+
+### "Switch a page between blocks and HTML"
+
+Use `set_page_mode` — it snapshots a revision before flipping, so the
+previous state is restorable:
+
+```
+# Convert an HTML-mode page to blocks with auto-heuristic conversion:
+set_page_mode page_id=about to=blocks convert=true
+
+# Or just switch the mode without converting (empty blocks):
+set_page_mode page_id=about to=blocks
+
+# Switch back to HTML (drops the block tree; revision retains it):
+set_page_mode page_id=about to=html
+```
+
+The heuristic converter recognises `<h1-4>` → heading, `<img>` → image,
+`<a.btn>` → button, `grid-cols-2` → two-column, `<section>` / hero divs
+→ section. Anything it can't classify becomes a `core/prose` block,
+which preserves the raw HTML losslessly. Run with `convert_page_to_blocks
+dry_run=true` first if you want to inspect the proposal before
+committing.
+
+### "Build a directory site / import structured data"
+
+```
+create_collection
+  name="restaurants"
+  label_singular="Restaurant" label_plural="Restaurants"
+  fields=[ ...title, slug, address, phone, cuisine, body... ]
+  route_template="/restaurants/{slug}"
+  item_template_html="<article><h1>{{title}}</h1>… {{{body}}}</article>"
+
+# For each row in your source data:
+create_collection_item collection="restaurants" fields={…} status="published"
+
+# Each published item now lives at /restaurants/{slug}, included in
+# sitemap.xml. Preview a specific one:
+get_preview_link collection_name="restaurants" item_id="<id>"
+
+# Optional listing page:
+list_collection_items collection="restaurants" limit=200
+update_page page_id=restaurants patch={ html_content: "<hand-written listing>" }
+```
+
+### "Migrate a content type (e.g. WP custom post type)"
+
+```
+list_collections                                     # what exists today?
+read_collection name=blog                            # what fields are writable?
+batch_read_collection_items …                        # load items (richtext hidden)
+# Transform locally; then:
+update_collection_item …  (or)  create_collection_item …
+```
+
+Fields outside the schema are silently dropped — call `read_collection`
+first if you're unsure what's writable.
+
+### "Add images to a page"
+
+```
+# Image lives on a URL somewhere (Unsplash, customer's existing CDN):
+upload_media_from_url source_url="https://..." alt_text="Hero photo of …"
+  → returns { media_id, cdn_url, … }
+
+# OR image lives in your memory (image-gen output):
+upload_media_inline filename="hero.png" content_type="image/png"
+                    data_base64="iVBORw0KGgo…"
+  → returns the same shape
+
+# OPTIONAL but recommended: produce srcset variants for responsive <img>:
+generate_image_variants media_id=<id>
+  → returns webp + avif variants at 320/640/1024/1920 widths
+    (skips upscales; sub-5s per image)
+
+# Then embed in a page:
+read_page page_id=...
+# Build <picture> or <img srcset="..."> using variants[*].cdn_url
+update_page page_id=... patch={ html_content: "<...><img src='{cdn_url}' .../>" }
+```
+
+### "Fill missing alt-text across the media library"
+
+```
+list_media                                 → find items where alt_text is empty
+suggest_alt_text_context media_id=<id>     → returns image_url + tuned prompt
+                                             + language + nearest-heading context
+# Pass image_url + the returned suggested_prompt to YOUR OWN vision
+# capability. The platform does NOT run vision for you.
+update_media media_id=<id> alt_text="<what vision returned>"
+```
+
+The prompt is tuned for SEO-grade output: 5-15 words, written in
+`settings.language`, skips "image of" filler, decorative images return
+empty string.
+
+### "Change a page's URL safely"
+
+```
+update_page page_id=about patch={ slug: "om-oss" }
+  → response includes:
+     auto_redirects: [{ from_path: "/about", to_path: "/om-oss",
+                        status_code: 301 }]
+     sanitization_warnings: []
+```
+
+The 301 fires automatically — you don't have to remember.
+
+### "Change the site's fallback URL (slug)"
+
+```
+update_site slug="acme"
+  → response includes:
+     urls.fallback: "https://acme.sites.typeroll.com"
+     dns_note: "New fallback URL … attached to CF Pages. SSL provisioning
+                takes 1–10 minutes after DNS propagates. …"
+```
+
+The slug change triggers DNS + CF Pages reprovisioning behind the scenes.
+**Always check the response for `dns_note` vs `dns_warning`:**
+
+- `dns_note` present → the new fallback URL was wired up; warn the user it
+  may take 1–10 min for SSL to provision before the URL serves.
+- `dns_warning` present → the slug was saved but DNS / CF attach failed.
+  The `urls.fallback` field is still returned (it's just `{slug}.{base}`
+  string formatting) but the URL will NOT resolve until the issue is
+  fixed. Surface the warning verbatim to the user — don't tell them the
+  URL is ready.
+- Neither present → self-hosted portal without CF/SITES_BASE_DOMAIN
+  configured; URL behaviour is up to the operator.
+
+The old fallback URL keeps working (bookmarks + SEO survive). Customer
+can manually deprovision the old one via the portal.
+
+## Safety boundaries
+
+- **HTML is sanitized at save.** No `<script>`, no `onclick`, no
+  `javascript:` URLs in page or partial bodies. `<style>` blocks DO
+  survive — multi-page sites need authored CSS for `@media` queries,
+  `:hover`, theming, etc. Inside `<style>` we strip a small list of
+  legacy code-execution constructs (`expression()`, `behavior:url`,
+  `@import`, `url(javascript:)`) but leave normal CSS alone.
+- **Write responses include `sanitization_warnings: []` (strings) and
+  `sanitization_details: []`** (structured records `{ kind, label,
+  count, bytes? }`). Use the structured form to programmatically retry
+  with a fixed input.
+- **scripts_head, scripts_body_end, custom_css** are now writable via
+  `update_site_settings` and readable via `read_site_settings`. Same
+  trust model as user-authored block-type JS: an API caller with a valid
+  bearer token takes responsibility for what they ship. The chat AI
+  inside the portal continues to NOT expose these fields, so a
+  conversation-driven assistant can't smuggle scripts in.
+- **The API key is site-scoped.** Cross-site reach is impossible — a
+  key on the wrong site returns 401, indistinguishable from "bad token".
+- **Audit log.** Every state-changing call (POST / PATCH / PUT /
+  DELETE) is logged. Reads aren't. The customer sees "Acme agency key
+  wrote to /pages/home at 14:32" in the portal.
+- **Rate limits.** 600 reads/min, 60 writes/min per key. On 429 the
+  response carries `Retry-After`.
+
+## Preview-driven workflow
+
+After any non-trivial change, call `get_preview_link` and ask the user
+(or your own browser tool) to confirm the result before moving on. One
+HTTP call vs. shipping a broken redesign — always worth it.
+
+Preview shows DB state (drafts included). Live (`get_site → urls.production`)
+shows the most recent deploy. Branch deploys live at
+`get_version → deploy_url` (`{branch}.{project}.pages.dev`).
+
+## Branches
+
+For multi-step work, create a branch:
+
+```
+create_branch name="Pricing refresh"
+```
+
+The response includes `id` — pass that as `version=<id>` on every
+subsequent call. The branch is independent of main; writes don't affect
+the live site until you `merge_branch`.
+
+Branches default `robots_blocked: true`. Deploys to a branch land at a
+stable, share-able URL (`{branch}.{project}.pages.dev`); use that for
+stakeholder review.
+
+## When in doubt
+
+- **Read before you write.** A `read_page` round-trip is cheap and
+  stops you overwriting unrelated changes.
+- **Dry-run bulk operations.** `bulk_replace_text` accepts `dry_run:
+  true` and returns 3 sample diffs. Show them to the user before the
+  real run.
+- **Watch the sanitization_warnings array.** If it's non-empty, the
+  stored HTML differs from what you sent. Read it back to confirm.
+- **One small confirmation > one large undo.** The audit log makes it
+  obvious who did what, but a clean revert across many pages is still
+  more work than asking "ok to proceed?" first.
+- **Match the site's design.** Read a partial or two before designing
+  new components. CSS variables (`var(--color-primary)`) are common
+  but not universal — mirror what's already in use.
+
+## Reference: tool families
+
+| Family       | Tools |
+|---|---|
+| **Discovery** | `get_site`, `update_site`, `list_versions`, `read_site_settings` |
+| **Pages — reads** | `list_pages`, `read_page`, `batch_read_pages` |
+| **Pages — writes** | `create_page`, `update_page`, `replace_page`, `batch_update_pages`, `delete_page`, `clone_page` |
+| **Pages — blocks** | `get_page_blocks`, `add_block`, `update_block`, `move_block`, `remove_block`, `set_page_mode`, `convert_page_to_blocks` |
+| **Pages — meta** | `get_page_preview` |
+| **Global blocks (partials)** | `list_partials` (summary by default), `read_partial`, `create_free_block`, `update_partial`, `replace_partial`, `delete_partial`, `find_pages_using_block`, `list_blocks_with_usage` |
+| **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`, `generate_image_variants`, `suggest_alt_text_context` |
+| **Redirects** | `list_redirects`, `create_redirect`, `delete_redirect` |
+| **Forms** | `list_forms`, `read_form`, `create_form`, `update_form`, `delete_form`, `list_form_submissions` |
+| **Settings** | `update_site_settings` (whitelist) |
+| **Search + bulk** | `search_pages`, `bulk_replace_text` |
+| **Branches** | `create_branch`, `read_version`, `delete_branch`, `merge_branch` |
+| **Deploy** | `trigger_deploy`, `list_deploys`, `get_deploy_status` |
+| **Preview** | `get_preview_link`, `get_page_preview` |
+
+Every tool's input is validated server-side; the MCP server only does
+auth + shape. If a tool returns `isError: true`, the body carries
+`{ error, status, body }` from the underlying HTTP response.

package/README.md

@@ -0,0 +1,135 @@
+# @typeroll/mcp-server
+
+Model Context Protocol server for the [Typeroll](https://typeroll.com)
+public API. Lets Claude Code (or any MCP-compatible client) manage a
+Typeroll site through the same tool surface a human agency would use:
+read and write pages, partials, collections, media, redirects, versions;
+trigger deploys; mint preview links.
+
+The server is a **thin transport adapter** — every tool wraps one HTTP
+endpoint of the Typeroll REST API. Auth happens at the API layer with
+a site-scoped key; the MCP just carries the bearer through.
+
+## Quick start
+
+1. **Create an API key** in your Typeroll portal at
+   `/app/sites/{siteId}/settings/api-keys`. The key is shown once at
+   creation — copy it somewhere safe.
+
+2. **Add the server to Claude Code.** Drop this into `~/.claude.json`
+   (or your local `.claude/config.json`):
+
+   ```json
+   {
+     "mcpServers": {
+       "typeroll": {
+         "command": "npx",
+         "args": ["-y", "@typeroll/mcp-server"],
+         "env": {
+           "TYPEROLL_API_URL": "https://app.typeroll.com",
+           "TYPEROLL_API_KEY": "typeroll_live_REPLACE_WITH_YOUR_KEY"
+         }
+       }
+     }
+   }
+   ```
+
+   For a self-hosted portal, point `TYPEROLL_API_URL` at it (e.g.
+   `https://cms.example.com`).
+
+3. **Tell the agent what kind of work you want.** A good first message:
+
+   > "Connect to Typeroll and tell me what you find — site name,
+   > number of pages, what global blocks exist, what collections are
+   > defined. Then I'll give you a task."
+
+   Claude will call `get_site`, `list_pages`, `list_partials`,
+   `list_collections` in sequence and report back.
+
+## Environment variables
+
+| Var             | Required | Description |
+|-----------------|----------|-------------|
+| `TYPEROLL_API_URL`  | yes      | Base URL of your Typeroll portal. |
+| `TYPEROLL_API_KEY`  | yes      | A `typeroll_live_…` bearer token from the API keys page. |
+| `TYPEROLL_SITE_ID`  | no       | Pin the server to a specific site. Defaults to autodetect (calls `GET /v1/sites` — per-site keys return exactly one). |
+
+## What the agent should read first
+
+The package ships [AGENTS.md](./AGENTS.md), a self-contained briefing
+that explains Typeroll conventions, common operations, and the safety
+boundaries an agent needs to respect. Point Claude at it (or include it
+in your project's `CLAUDE.md` / `AGENTS.md`) so it knows when to use
+which tool.
+
+## Tool surface
+
+Around 50 tools across these families. See [AGENTS.md](./AGENTS.md) for
+the full reference + concrete operation recipes.
+
+- **Discovery** — `get_site`, `update_site` (name/slug/domain), `list_versions`,
+  `read_site_settings`, `update_site_settings`.
+- **Pages** — list, read, batch-read, create, update (PATCH), replace
+  (PUT), batch-update, delete, clone, get-blocks, get-preview.
+- **Global blocks (partials)** — list (summary mode by default), read,
+  create free block, update, replace, delete, find-pages-using-block.
+- **Block types** — list, read, find-pages-using-block-type. Surface
+  for the future block editor.
+- **Collections + items** — create/update/delete the collection schema
+  itself (incl. `route_template` for per-item URLs); list/read/batch-
+  read/create/update/delete items.
+- **Media** — list, read, signed upload URLs, `upload_media_from_url`,
+  `upload_media_inline`, patch metadata, delete, `generate_image_variants`
+  (build-time srcset pipeline), `suggest_alt_text_context` (returns a
+  tuned prompt for your own vision model).
+- **Redirects** — list, create, delete. Plus automatic 301 on slug change.
+- **Forms** — list, read, create, update, delete, list submissions.
+- **Settings** — read + patch (scripts and custom CSS not exposed).
+- **Search** — `search_pages` with substring or regex.
+- **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.
+- **Preview** — `get_preview_link` (signed URL for browser navigation;
+  supports `page_id`, `slug`, or `collection_name + item_id`).
+
+## Direct REST API access
+
+If you don't want the MCP wrapper, the same surface is reachable directly
+with curl:
+
+```bash
+curl -H "Authorization: Bearer typeroll_live_..." \
+  https://app.typeroll.com/api/v1/sites/<siteId>/pages
+```
+
+The MCP server is purely an ergonomics layer on top of that.
+
+## Security model
+
+- API keys are **site-scoped**. A key cannot read or write another site
+  in the same organization — server-side authoritative.
+- All write calls (`POST`, `PUT`, `PATCH`, `DELETE`) are **audit-logged**
+  with the key prefix, IP, method, path, and status. Reads are not
+  logged (cost vs. value).
+- **Rate limits**: 600 reads/min, 60 writes/min per key. 429 responses
+  carry `Retry-After` headers.
+- **HTML sanitization** happens at save time on the server — `<script>`,
+  event handlers, and `javascript:` URLs are stripped. The customer's
+  `scripts_*` and `custom_css` settings are read-stripped and write-dropped
+  by the API.
+- 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).
+
+## More
+
+- Full end-to-end production setup recipe with troubleshooting:
+  [docs/claude-code-mcp-setup.md](../../docs/claude-code-mcp-setup.md)
+- Agent operations briefing: [AGENTS.md](./AGENTS.md)
+- Boilerplate skills (migration, content, images, directory, redesign):
+  [skills/](./skills/)
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/client.js

@@ -0,0 +1,103 @@
+// Thin fetch client for the Typeroll REST API. The MCP server is just a
+// transport adapter — every tool delegates to one of these methods.
+//
+// Surface kept deliberately tiny so it's easy to reason about: get/post/
+// patch/put/del + a path helper. Errors come back as a structured
+// ApiError with the status and the parsed body so the caller can shape
+// useful tool-result messages.
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message ?? `API request failed (${status})`);
+        this.status = status;
+        this.body = body;
+        this.name = 'ApiError';
+    }
+}
+export class TyperollClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(config) {
+        if (!config.baseUrl)
+            throw new Error('baseUrl is required');
+        if (!config.apiKey)
+            throw new Error('apiKey is required');
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.apiKey = config.apiKey;
+        this.fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    }
+    /** Build the full URL for a path (relative to /api/v1/sites/{siteId}/...) */
+    url(siteId, path, query) {
+        const cleanPath = path.replace(/^\/+/, '');
+        const url = new URL(`${this.baseUrl}/api/v1/sites/${encodeURIComponent(siteId)}/${cleanPath}`);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        return url.toString();
+    }
+    /** Top-level URL (no siteId prefix) — used by GET /v1/sites only. */
+    rootUrl(path, query) {
+        const cleanPath = path.replace(/^\/+/, '');
+        const url = new URL(`${this.baseUrl}/api/v1/${cleanPath}`);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        return url.toString();
+    }
+    async request(method, url, body) {
+        const headers = {
+            authorization: `Bearer ${this.apiKey}`,
+            accept: 'application/json',
+        };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        const res = await this.fetchImpl(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        let parsed = undefined;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok) {
+            const message = parsed?.error ?? `HTTP ${res.status}`;
+            throw new ApiError(res.status, parsed, message);
+        }
+        return parsed;
+    }
+    // ── Site-scoped helpers ────────────────────────────────────────────────
+    get(siteId, path, query) {
+        return this.request('GET', this.url(siteId, path, query));
+    }
+    post(siteId, path, body, query) {
+        return this.request('POST', this.url(siteId, path, query), body);
+    }
+    patch(siteId, path, body, query) {
+        return this.request('PATCH', this.url(siteId, path, query), body);
+    }
+    put(siteId, path, body, query) {
+        return this.request('PUT', this.url(siteId, path, query), body);
+    }
+    del(siteId, path, query) {
+        return this.request('DELETE', this.url(siteId, path, query));
+    }
+    // ── Root helpers ───────────────────────────────────────────────────────
+    rootGet(path) {
+        return this.request('GET', this.rootUrl(path));
+    }
+}