@typeroll/mcp-server 0.10.0 → 0.12.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.
 
@@ -466,7 +478,7 @@ stakeholder review.
 | **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`, `finalize_media`, `finalize_all_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` |
+| **Forms** | `list_forms`, `read_form`, `create_form`, `update_form`, `delete_form`, `list_form_submissions`. read/create return `submit_token` + `submit_url` — embed as a plain `<form method="POST">` with a hidden `_token` input + empty honeypot `_hp`; no client JS (the sanitizer strips inline `<script>`; the endpoint answers form posts with an HTML confirmation page) |
 | **Settings** | `update_site_settings` (whitelist) |
 | **Search + bulk** | `search_pages`, `bulk_replace_text` |
 | **Branches** | `create_branch`, `read_version`, `delete_branch`, `merge_branch` |

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/forms.js

@@ -1,8 +1,10 @@
 // Forms — agents can create/update/delete forms, and read submissions.
 // The customer-facing submit endpoint is HMAC-signed and lives at
-// /api/forms/submit; the in-portal chat's `get_form_embed` tool produces
-// the snippet customers paste into their pages. This file is the
-// management surface.
+// /api/forms/submit. read_form/create_form return `submit_token` +
+// `submit_url`, which is everything an agent needs to embed a working
+// plain-POST form (no client JS — the page sanitizer strips inline
+// <script>, and the endpoint answers form-encoded posts with an HTML
+// confirmation page).
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 const fieldSchema = z.object({
@@ -28,7 +30,7 @@ export const formTools = [
     },
     {
         name: 'read_form',
-        description: 'Read one form by id, including fields, submit_text, and success_message.',
+        description: 'Read one form by id, including fields, submit_text, success_message — plus submit_token and submit_url for embedding: a plain <form method="POST" action={submit_url}> with a hidden _token input and an empty honeypot _hp is a fully working no-JS embed.',
         inputSchema: { form_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `forms/${encodeURIComponent(args.form_id)}`);
@@ -37,7 +39,7 @@ export const formTools = [
     },
     {
         name: 'create_form',
-        description: 'Create a form. Each field has { name, type, label, required?, placeholder?, options? }. Allowed types: text, email, tel, url, number, textarea, select, checkbox, radio, hidden, gdpr_consent. The form can then be embedded on any page — use get_form_embed (in-portal chat) or render the form yourself by reading the schema.',
+        description: 'Create a form. Each field has { name, type, label, required?, placeholder?, options? }. Allowed types: text, email, tel, url, number, textarea, select, checkbox, radio, hidden, gdpr_consent. The response includes submit_token + submit_url — embed with a plain <form method="POST" action={submit_url}>, a hidden _token input, and an empty honeypot _hp. Do NOT add inline <script> (the page sanitizer strips it); the endpoint answers plain form posts with an HTML confirmation page.',
         inputSchema: {
             id: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
             name: z.string().min(1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.10.0",
+  "version": "0.12.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-forms.md

@@ -31,11 +31,15 @@ create_form {
     {"name":"subject", "label":"Ämne",           "type":"select",
      "options":["Prisförfrågan","Samarbete","Övrigt"]}
   ],
-  "success_message": "Tack! Vi återkommer inom 24 timmar.",
-  "recipient_email": "hej@acme.se"
+  "success_message": "Tack! Vi återkommer inom 24 timmar."
 }
 ```
 
+There is no `recipient_email` field — submissions land in the portal's
+Submissions inbox (`/app/sites/{siteId}/forms/{formId}/submissions`).
+Email notification is a form *action* (not yet wired platform-side);
+tell the customer to check the inbox.
+
 **Field types:** `text`, `email`, `tel`, `url`, `number`, `textarea`,
 `select`, `radio`, `checkbox`.
 
@@ -46,22 +50,28 @@ create_form {
 
 ### 2. Get the signed embed token
 
-The form's submit button needs a signed token that proves it was
-generated by the platform. Fetch it:
+The submit endpoint only accepts requests carrying a platform-signed
+HMAC token. `create_form` returns it directly; you can also fetch it any
+time with:
 
 ```
 read_form form_id="kontakt"
 ```
 
-The response includes `submit_token` (a short-lived HMAC). Use this in
-the HTML.
-
-Actually, the embed HTML is best generated by reading the form and
-building it manually — the form's `id` is all you need for the action URL.
+The response includes `submit_token` (put it in the hidden `_token`
+input) and `submit_url` (use it as the form's `action`). The token is
+stable — it only stops working if the platform rotates its signing
+secret — so baking it into static page HTML is correct. If
+`submit_token` comes back `null`, the server has no signing secret
+configured (dev setups); the form cannot accept submissions until that's
+fixed — tell the user instead of embedding a broken form.
 
 ### 3. Embed the form on a page
 
-Typeroll forms submit to the platform's endpoint. The HTML:
+A plain HTML form POST is the default and needs **no JavaScript**: the
+endpoint answers a normal form-encoded POST with a small confirmation
+page (the form's `success_message` + a link back to the page the
+visitor came from). Validation errors get the same treatment. The HTML:
 
 ```html
 <section class="contact-section">
@@ -70,11 +80,10 @@ Typeroll forms submit to the platform's endpoint. The HTML:
     <p>Fyll i formuläret så återkommer vi inom 24 timmar.</p>
 
     <form class="contact-form"
-          action="https://app.typeroll.com/api/forms/submit"
+          action="SUBMIT_URL"
           method="POST">
-      <!-- Hidden fields — required by the platform -->
-      <input type="hidden" name="_form_id"  value="kontakt">
-      <input type="hidden" name="_site_id"  value="YOUR_SITE_ID">
+      <!-- The signed token is the only hidden field the platform needs;
+           it encodes org + site + form identity. -->
       <input type="hidden" name="_token"    value="SIGNED_TOKEN">
       <!-- Honeypot — must stay empty, bots fill it -->
       <input type="text"   name="_hp"       style="display:none" tabindex="-1" autocomplete="off">
@@ -129,32 +138,50 @@ Typeroll forms submit to the platform's endpoint. The HTML:
 ```
 
 **Replace:**
-- `YOUR_SITE_ID` → the site's actual id (from `get_site`)
-- `SIGNED_TOKEN` → fetch via `read_form form_id="kontakt"` → `submit_token`
+- `SUBMIT_URL` → `submit_url` from `read_form` / `create_form`
+- `SIGNED_TOKEN` → `submit_token` from the same response
+
+### 4. Inline feedback (optional — requires user action)
 
-### 4. Add success/error handling (optional JS)
+**The page sanitizer strips inline `<script>` from page and partial
+HTML**, so you cannot ship fetch-based submit handling yourself — a
+`<script>` you put in `html_content` is silently removed. The plain
+POST above is the reliable path; use it.
 
-To show inline feedback without a page reload:
+If the customer wants inline feedback without a page reload, the script
+must go into the site's `scripts_body_end` setting, which only a human
+can edit (Settings → Custom code — it's deliberately excluded from the
+AI tool surface). Hand them this snippet for that box; it intercepts the
+form and POSTs the JSON shape `{ token, data }`:
 
 ```html
 <script>
 (function(){
   const form = document.querySelector('.contact-form');
   if(!form) return;
-  form.addEventListener('submit', async(e) => {
+  form.addEventListener('submit', async (e) => {
     e.preventDefault();
     const btn = form.querySelector('[type=submit]');
     btn.disabled = true;
     btn.textContent = 'Skickar…';
+    // The endpoint's fetch contract is JSON: { token, data }.
+    const fd = new FormData(form);
+    const token = fd.get('_token');
+    const data = {};
+    fd.forEach((v, k) => { if (k !== '_token') data[k] = v; });
     try {
-      const res = await fetch(form.action, {method:'POST', body: new FormData(form)});
-      const data = await res.json();
-      if(data.ok) {
-        form.innerHTML = '<p class="form-success">Tack! Vi återkommer inom 24 timmar.</p>';
+      const res = await fetch(form.action, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token, data }),
+      });
+      const json = await res.json();
+      if (res.ok && json.success) {
+        form.innerHTML = '<p class="form-success">' + (json.message || 'Tack!') + '</p>';
       } else {
         btn.disabled = false;
         btn.textContent = 'Skicka meddelande';
-        alert('Något gick fel: ' + (data.error || 'okänt fel'));
+        alert('Något gick fel: ' + ((json.errors && json.errors.join(', ')) || json.error || 'okänt fel'));
       }
     } catch {
       btn.disabled = false;
@@ -226,18 +253,19 @@ portal at `/app/sites/{siteId}/forms/kontakt/submissions`.
 
 ## Pitfalls
 
-- **Tokens expire.** The `submit_token` in the form embed is short-lived
-  (24h by default). For forms on long-cached static pages, fetch a fresh
-  token via `read_form` and rebuild the page HTML, then redeploy.
-  Alternatively, fetch the token client-side via a small `<script>` that
-  calls the portal's token endpoint before submit.
-- **Field names must be ASCII.** `message` not `meddelande`... wait,
-  `meddelande` is ASCII. `foretag` not `företag`. Only Swedish/Nordic
-  special characters (å, ä, ö) cause problems.
+- **Tokens are stable, not expiring.** The `submit_token` stays valid
+  until the platform rotates its signing secret (rare, operator-driven).
+  Bake it into the static HTML; no refresh logic needed. If submissions
+  suddenly 403 after working, re-fetch via `read_form` and republish.
+- **Inline `<script>` does not survive.** The page sanitizer strips it
+  from `html_content` — never rely on client JS you embed yourself. The
+  plain form POST works without it (section 3).
+- **Field names must be lowercase ASCII** (`[a-z][a-z0-9_-]*`):
+  `foretag` not `företag`, `amne` not `ämne`. Labels can be anything.
 - **Don't use the same form_id on two different forms.** IDs must be
   unique per site — use descriptive names: `kontakt`, `boka`, `nyhetsbrev`.
 - **Honeypot must be invisible.** `_hp` field must have `display:none`.
   If it's visible and a real user fills it, their submission is rejected.
-- **Recipient email is display-only in phase 1.** The portal stores
-  submissions; email delivery to `recipient_email` depends on the platform's
-  email configuration. Confirm with the customer that they'll check the inbox.
+- **No email notifications yet.** Submissions are stored and visible in
+  the portal's Submissions inbox; the email action handler isn't wired
+  platform-side. Confirm with the customer that they'll check the inbox.

package/skills/tr-imagegen.md

@@ -0,0 +1,149 @@
+---
+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.
+- **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.