@typeroll/mcp-server 0.11.0 → 0.13.0

package/AGENTS.md

@@ -84,6 +84,18 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   before working with blocks — never hardcode block ids or field names,
   the available set is per-site.
 
+  Two specifics worth knowing:
+  - **`core/html`** is the raw-HTML escape hatch for block-mode pages —
+    one `html` field rendered verbatim (then sanitized like HTML-mode
+    content). Use it for the genuinely unique thing no block covers: a
+    form embed with its signed `_token`, a third-party widget's markup,
+    a hand-crafted one-off. Prefer real blocks when one fits.
+  - **`script` on custom block types** (create/update_block_type) is
+    honoured only when the site has "Allow AI to write block scripts"
+    enabled — a human-set portal setting. When it's off your script is
+    stripped and the response carries a warning; relay it to the user
+    instead of retrying.
+
 - **Redirects.** `from_path → to_path` with status code 301 / 302.
   Auto-created when you change a page's slug.
 

package/README.md

@@ -96,11 +96,20 @@ 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.
+  (PUT), batch-update, delete, clone, get-preview, `set_page_mode`
+  (flip between blocks/html), `convert_page_to_blocks`.
+- **Blocks (instances)** — `get_page_blocks`, `add_block`,
+  `update_block`, `move_block`, `remove_block`, `duplicate_block`,
+  `set_block_responsive`. All take a `target` (page, partial, page
+  template, or collection item-template), so one tool family edits
+  every block container.
 - **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.
+- **Block types** — list, read, create, update, delete,
+  find-pages-using-block-type, plus `.tcblocks` export/import. Custom
+  client-side JS (`script`) is honoured only when the site has enabled
+  "Allow AI to write block scripts" (a human-set portal setting) —
+  otherwise it's stripped with a warning.
 - **Collections + items** — create/update/delete the collection schema
   itself (incl. `route_template` for per-item URLs); list/read/batch-
   read/create/update/delete items.
@@ -115,7 +124,13 @@ the full reference + concrete operation recipes.
   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).
+  Read/create responses include `submit_token` + `submit_url` — a plain
+  `<form method="POST">` with a hidden `_token` input is a fully working
+  no-JS embed (the endpoint answers form posts with an HTML
+  confirmation page).
+- **Settings** — read + patch, including `scripts_head` /
+  `scripts_body_end` / `custom_css` (trusted because the caller holds an
+  API key; the in-portal chat AI does NOT get these).
 - **Search** — `search_pages` with substring or regex.
 - **Bulk** — `bulk_replace_text` with dry-run.
 - **Branches** — create, read, delete, merge. Branch deploys get their
@@ -138,17 +153,21 @@ 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.
+- API keys are **site-scoped or org-scoped** (see "Key scopes" above) —
+  enforced server-side. A site-scoped key cannot touch any other site;
+  an org-scoped key reaches the org's own sites plus sites explicitly
+  shared into the org, with the share's permission level applied.
 - 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.
+  event handlers, and `javascript:` URLs are stripped from page/partial
+  content (including `core/html` block output). The scriptable surfaces
+  (`scripts_*`, `custom_css`, block-type `script`) are deliberate
+  exceptions: the first are writable with an API key, and block-type
+  scripts additionally require the site's per-site opt-in.
 - 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).
@@ -158,7 +177,8 @@ The MCP server is purely an ergonomics layer on top of that.
 - 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):
+- Boilerplate skills (site building, brand, forms, SEO, blog,
+  collections, migration, image generation, redesign, …):
   [skills/](./skills/)
 
 ## License

package/dist/index.js

@@ -15,22 +15,9 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { TyperollClient } from './client.js';
 import { runInstallSkillsCli } from './install-skills.js';
+import { resolveSiteId } from './resolve-site-id.js';
 import { buildServer } from './server.js';
 const VERSION = '0.7.12';
-async function resolveSiteId(client) {
-    const fromEnv = process.env.TYPEROLL_SITE_ID?.trim();
-    if (fromEnv)
-        return fromEnv;
-    const res = await client.rootGet('sites');
-    if (!res.sites || res.sites.length === 0) {
-        throw new Error('No sites returned for this API key. Check the key is valid.');
-    }
-    if (res.sites.length > 1) {
-        throw new Error(`This key authorises ${res.sites.length} sites; set TYPEROLL_SITE_ID to pick one. ` +
-            'Org-scoped keys span multiple sites — stdio currently binds to one at a time.');
-    }
-    return res.sites[0].id;
-}
 function bail(message) {
     console.error(`typeroll-mcp: ${message}`);
     process.exit(1);

package/dist/resolve-site-id.js

@@ -0,0 +1,29 @@
+// Discover which site a stdio invocation binds to.
+//
+// TYPEROLL_SITE_ID wins when set. Otherwise we ask GET /v1/sites: a
+// site-scoped key returns exactly one entry; an org-scoped key can return
+// many, in which case TYPEROLL_SITE_ID is required so this stdio invocation
+// maps onto one specific site.
+export async function resolveSiteId(client) {
+    const fromEnv = process.env.TYPEROLL_SITE_ID?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const res = await client.rootGet('sites');
+    if (!res.sites || res.sites.length === 0) {
+        throw new Error('No sites returned for this API key. Check the key is valid.');
+    }
+    if (res.sites.length > 1) {
+        throw new Error(`This key authorises ${res.sites.length} sites; set TYPEROLL_SITE_ID to pick one. ` +
+            'Org-scoped keys span multiple sites — stdio currently binds to one at a time.');
+    }
+    // Defense in depth: portals before the /v1/sites org-key fix returned a
+    // single placeholder entry with an empty id for org-scoped keys. Binding
+    // to "" would make every subsequent call fail incomprehensibly — reject
+    // it with an actionable message instead.
+    const id = res.sites[0].id?.trim();
+    if (!id) {
+        throw new Error('The portal returned a site with an empty id (org-scoped key against an older portal). ' +
+            'Set TYPEROLL_SITE_ID to pick a site explicitly, or upgrade the portal.');
+    }
+    return id;
+}

package/dist/tools/block-types.js

@@ -84,15 +84,15 @@ export const blockTypeTools = [
         }),
     },
     // ─── BlockType authoring — CREATE / UPDATE / DELETE ──────────────────
-    // The chat AI surface intentionally omits the `script` field on these
-    // three tools. Scripts run with full DOM access in every visitor's
-    // browser; AI-authored blocks must not carry custom JS. A human can
-    // add a script later via the portal UI (consent gate) or via the
-    // cookie-auth API directly. Origin is stamped 'ai' so audit + UI
-    // distinguish these from human-authored types.
+    // `script` runs with full DOM access in every visitor's browser, so
+    // agent-authored scripts are gated server-side on a per-site human
+    // opt-in (Site.ai_scripts_enabled, set in the portal's settings UI).
+    // The tools expose the field; when the site hasn't opted in, the API
+    // strips it and returns a warning. Origin is stamped 'ai' so audit +
+    // UI distinguish these from human-authored types.
     {
         name: 'create_block_type',
-        description: "Create a new custom block type usable on this site. Origin is stamped 'ai' automatically. The block ships immediately to every page editor + the renderer's registry. **Custom JS is NOT exposed here** — if a script is genuinely needed, a human must add it later via the portal UI. Returns the created BlockType.",
+        description: "Create a new custom block type usable on this site. Origin is stamped 'ai' automatically. The block ships immediately to every page editor + the renderer's registry. Custom JS via `script` requires the site's \"Allow AI to write block scripts\" setting (human-set in the portal) — when it's off, the field is ignored and the response carries a warning. Returns the created BlockType.",
         inputSchema: {
             name: z.string().describe('Machine name (lowercase kebab/underscore, 1-64 chars). Becomes the id.'),
             label: z.string().optional().describe('Display label (defaults to name).'),
@@ -112,6 +112,7 @@ export const blockTypeTools = [
             schema: z.array(z.unknown()).optional().describe('FieldDefinition[]. Each field has name, type, label, optional required/default/options/responsive.'),
             template: z.string().optional().describe('HTML with {{field}}, {{{field}}}, {{=tag}}, {{children}}, {{slot:NAME}} substitutions.'),
             styles: z.string().optional().describe('Block-scoped CSS. Selectors should start with [data-block="<name>"].'),
+            script: z.string().optional().describe('Client-side JS shipped with the block (runs on the published site). Only honoured when the site has enabled AI block scripts; otherwise stripped with a warning in the response.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -126,7 +127,7 @@ export const blockTypeTools = [
     },
     {
         name: 'update_block_type',
-        description: "Update fields of an existing custom block type. Core blocks (id starts with 'core/') are read-only — they're managed in platform code. Schema/template/styles replace wholesale (no deep merge); other fields shallow-merge. **Custom JS is NOT exposed here** — to add or change a script, edit via portal UI.",
+        description: "Update fields of an existing custom block type. Core blocks (id starts with 'core/') are read-only — they're managed in platform code. Schema/template/styles replace wholesale (no deep merge); other fields shallow-merge. The `script` field follows the same site-setting gate as create_block_type.",
         inputSchema: {
             type_id: z.string().describe('Block type id (custom or third_party). Cannot be a core/* block.'),
             label: z.string().optional(),
@@ -143,6 +144,7 @@ export const blockTypeTools = [
             schema: z.array(z.unknown()).optional(),
             template: z.string().optional(),
             styles: z.string().optional(),
+            script: z.string().optional().describe('Only honoured when the site has enabled AI block scripts; otherwise stripped with a warning.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {

package/dist/tools/settings.js

@@ -29,6 +29,7 @@ export const settingsTools = [
             tagline: z.string().optional(),
             logo: z.string().optional(),
             favicon: z.string().optional(),
+            apple_touch_icon: z.string().optional().describe('URL to a 180x180 PNG for iOS/Android home-screen bookmarks. Emitted as <link rel="apple-touch-icon">.'),
             default_seo_suffix: z.string().optional(),
             language: z.string().optional().describe('BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> on the rendered site.'),
             robots_txt: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {

package/skills/tr-brand.md

@@ -108,6 +108,24 @@ update_site_settings {
 
 Read back to confirm: `read_site_settings`.
 
+### Site icons — always propose them, never leave them empty
+
+Every site gets a favicon + apple touch icon as part of brand setup:
+
+1. **Brand assets exist** (favicon-*.png, app icon, symbol): upload the
+   right sizes via `upload_media_inline` (favicon: 32–64px PNG or SVG;
+   apple touch icon: 180×180 PNG) and set BOTH in one call:
+   `update_site_settings { "favicon": "<url>", "apple_touch_icon": "<url>" }`.
+2. **No icon assets:** derive a proposal instead of skipping — crop the
+   logo's symbol to a square and resize locally (`sips -z 180 180 in.png
+   --out icon-180.png` on macOS, or ImageMagick), or generate a simple
+   icon candidate with the imagegen lab (see `tr-imagegen`; respect the
+   style profile, no text). Upload, set, and tell the user it's a
+   proposal they can swap.
+
+A site shipping with the browser's default globe icon is a build gap —
+treat icons like the logo: part of done.
+
 ## Step 5 — Update partials to use the new palette
 
 Partials that hardcoded hex colors need updating. Fetch the header:

package/skills/tr-imagegen.md

@@ -0,0 +1,154 @@
+---
+name: tr-imagegen
+description: Use when the user wants to generate images for a Typeroll site with AI models (Gemini, OpenAI, Higgsfield) — hero images, illustrations, section backgrounds, og-images. Triggers on "generera bilder", "generate images", "skapa en hero-bild", "AI-bilder", "bildgenerering", or when a brief calls for imagery that doesn't exist in assets/. Covers the local lab loop (generate → review → pick) and uploading winners to the Typeroll media library.
+---
+
+# Generate images for a Typeroll site (local lab → media library)
+
+Image generation runs **locally** in the site workdir — provider API keys
+live in the folder's `.env`, candidates land in `images/lab/`, and only
+the picked winners are uploaded to the Typeroll media library via the
+regular media tools (see `tr-images` for the upload/variants half).
+
+Why local: you can look at the candidates (Read the files), iterate on
+prompts cheaply, and never ship a key or a reject anywhere.
+
+## Folder convention
+
+```
+<site>/
+├── .env                  # provider keys — GITIGNORED, never committed
+├── prompts/
+│   └── image-style.md    # the site's image style profile (see below)
+└── images/
+    └── lab/              # generated candidates — gitignored, disposable
+```
+
+`.env` keys (only the ones the user has — check before assuming):
+
+```
+GEMINI_API_KEY=...
+OPENAI_API_KEY=...
+```
+
+(Higgsfield needs no key here — it connects as an MCP server, see below.)
+
+Load them per-command (`source .env` doesn't persist between Bash calls):
+
+```bash
+export $(grep -v '^#' .env | xargs)   # prepend to each generation command
+```
+
+## The style profile — prompts/image-style.md
+
+Every site gets ONE style profile that you **prepend to every image
+prompt**. This is what keeps 20 images generated across 5 sessions
+looking like one site. Derive it from `assets/brand.md` + the brief if
+it doesn't exist yet, and confirm it with the user before generating at
+scale. Keep it short (5–10 lines): art direction, palette, mood,
+photography vs illustration, what to avoid.
+
+Example shape:
+
+```markdown
+# Bildstil — <Sajtnamn>
+Varm, folklig illustration med mjuka rundade former. Platt 2D med
+subtila skuggor — ingen 3D, ingen fotorealism. Palett: kobolt #1F4FB8,
+sol #FFC83D, grädde #FFF8EC; accenter sparsamt. Människor: enkla,
+inkluderande, glada — inga karikatyrer. Undvik: stockfoto-känsla, text
+i bilden, logotyper, watermarks.
+```
+
+## Generate candidates
+
+Name candidates descriptively: `images/lab/<motiv>-<modell>-<n>.png`.
+Generate 3–6 candidates per slot (mix models when several keys exist),
+then **Read the files to actually look at them** before showing the
+user your shortlist.
+
+### Gemini (gemini-2.5-flash-image)
+
+```bash
+curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent" \
+  -H "x-goog-api-key: $GEMINI_API_KEY" -H 'Content-Type: application/json' \
+  -d '{
+    "contents": [{"parts": [{"text": "<STYLE PROFILE>\n\n<MOTIF PROMPT>"}]}],
+    "generationConfig": {"imageConfig": {"aspectRatio": "16:9"}}
+  }' | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' \
+  | base64 -d > images/lab/hero-gemini-1.png
+```
+
+Aspect ratios: `1:1`, `16:9`, `4:3`, `3:4`, `9:16`. Gemini also does
+image *editing* — pass an existing image as an `inlineData` part plus an
+instruction to restyle/extend it (useful for "same illustration but
+winter").
+
+### OpenAI (gpt-image-1)
+
+```bash
+curl -s https://api.openai.com/v1/images/generations \
+  -H "Authorization: Bearer $OPENAI_API_KEY" -H 'Content-Type: application/json' \
+  -d '{
+    "model": "gpt-image-1",
+    "prompt": "<STYLE PROFILE>\n\n<MOTIF PROMPT>",
+    "size": "1536x1024",
+    "quality": "high"
+  }' | jq -r '.data[0].b64_json' | base64 -d > images/lab/hero-openai-1.png
+```
+
+Sizes: `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait).
+
+### Higgsfield (MCP server — no API key)
+
+Higgsfield exposes its models through a hosted MCP server at
+`https://mcp.higgsfield.ai/mcp` (OAuth-protected — first connect opens a
+browser login; no secret lands in any file). Add it next to the
+typeroll server in the site folder's `.mcp.json`:
+
+```json
+"higgsfield": { "type": "http", "url": "https://mcp.higgsfield.ai/mcp" }
+```
+
+Then use its tools directly — list what's available rather than
+assuming tool names. Save/download outputs into `images/lab/` with the
+same naming convention, and prepend the style profile to prompts here
+too. **Headless caveat:** OAuth-protected MCP servers need an existing
+login session on the machine — connect once interactively before
+relying on it in a headless run. (The same URL works as a custom
+connector in Claude Desktop, for editors who don't use Claude Code.)
+
+## Review → pick → upload
+
+1. **Look at every candidate** (Read the image files) and write one line
+   per candidate in `build-log.md` (keep/reject + why).
+2. Show the user the shortlist (file paths) and let them pick — unless
+   they've delegated the pick to you.
+3. Upload winners with the regular media tools (see `tr-images`):
+   - small files → `upload_media_inline` (base64);
+   - larger → `create_upload_url` + HTTP PUT + `finalize_media`.
+   Give real `alt` text and a descriptive filename at upload time.
+4. `generate_image_variants` for responsive sizes when the image is
+   placed full-width.
+5. Place via `update_block` (`core/image`, hero fields, …) or page HTML.
+6. `images/lab/` is disposable — leave rejects there; never upload them.
+
+## Pitfalls
+
+- **Never put text in generated images** (headlines, buttons) — text is
+  HTML's job; generated text renders as gibberish in non-English. And
+  models sneak text onto surfaces where it "feels natural" — jerseys,
+  signs, banners, packages — even when the prompt doesn't ask for any.
+  Forbid it explicitly in the prompt ("plain unmarked clothing, no
+  text, no letters, no numbers anywhere in the image") and make the
+  same rule part of every site's style profile.
+- **Don't commit `.env` or `images/lab/`** — both are gitignored by the
+  kit convention; keep it that way.
+- **Cost discipline:** generation costs real money per image. Batch
+  thoughtfully (3–6 per slot, not 20), and reuse via Gemini's
+  edit-an-image mode instead of regenerating from scratch.
+- **Licensing/provenance:** AI-generated imagery is fine for site
+  decoration, but never generate fake "photos" of real people, products
+  the customer doesn't sell, or anything presented as documentary fact.
+- **The style profile is the contract.** If the user rejects a batch on
+  style grounds, fix `prompts/image-style.md` first, then regenerate —
+  don't just tweak one prompt.