@typeroll/mcp-server 0.11.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.
 

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/package.json

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