@typeroll/mcp-server 0.9.0 → 0.11.0

package/AGENTS.md

@@ -305,6 +305,32 @@ read_page page_id=...
 update_page page_id=... patch={ html_content: "<...><img src='{cdn_url}' alt='…' /></...>" }
 ```
 
+### "Stop an image over-fetching a too-large variant"
+
+When an image renders much narrower than the viewport (a container-constrained
+hero, a sidebar thumbnail), the default `<picture sizes>` of
+`(max-width: 768px) 100vw, 800px` makes the browser pull a wider srcset variant
+than it needs — Lighthouse flags it as wasted bytes. Three levers, narrowest
+wins:
+
+```
+# 1. Per-image: put a real `sizes` on the <img>. Survives the transform verbatim.
+update_page page_id=... patch={ html_content:
+  "<img src='{cdn_url}' alt='…' sizes='(max-width: 640px) 360px, 560px' />" }
+
+# 2. Per-page default (applies to every image on the page that has no own sizes):
+update_page page_id=... patch={ image_sizes_default: "(max-width: 640px) 360px, 560px" }
+
+# 3. Site-wide default (fallback under the page default):
+update_site_settings image_sizes_default="(max-width: 640px) 360px, 560px"
+```
+
+Precedence: per-image `sizes` > page `image_sizes_default` >
+site `image_sizes_default` > the generic built-in. To opt a single image out of
+the platform's auto-`<picture>` entirely, hand-write your own `<picture>` with
+custom `<source media=…>` — the transform leaves an existing `<picture>`
+untouched (it no longer re-wraps the inner `<img>`).
+
 ### "Fill missing alt-text across the media library"
 
 ```
@@ -440,7 +466,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/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/dist/tools/pages.js

@@ -90,6 +90,7 @@ export const pageTools = [
             author: z.string().optional(),
             language: z.string().optional().describe('BCP-47 tag overriding the site default (e.g. "en" on an otherwise Swedish site).'),
             template: z.string().optional().describe('Page template id (PageTemplate). Wraps the body in the template tree at render time.'),
+            image_sizes_default: z.string().optional().describe('Per-page default `sizes` for responsive images (e.g. "(max-width: 640px) 360px, 560px"). Overrides the site setting; a per-<img> `sizes` attr still wins. Set when this page\'s images render narrower than the generic default so the browser stops over-fetching.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -121,6 +122,7 @@ export const pageTools = [
                 canonical_url: z.string().optional(),
                 noindex: z.boolean().optional(),
                 lastmod_override: z.string().optional().describe('Override the sitemap <lastmod>. Empty string suppresses lastmod for this page entirely.'),
+                image_sizes_default: z.string().optional().describe('Per-page default `sizes` for responsive images (e.g. "(max-width: 640px) 360px, 560px"). Overrides the site setting; a per-<img> `sizes` attr still wins. Set when this page\'s images render narrower than the generic default so the browser stops over-fetching the larger variant.'),
                 json_ld: z.string().optional(),
                 schema_type: z.string().optional().describe('Free-form Schema.org type ("Service", "Course", "Product", …) used for auto JSON-LD emission. Use service.* for Service-specific fields.'),
                 service: z

package/dist/tools/settings.js

@@ -10,7 +10,7 @@ import { ok, withErrorBoundary } from './helpers.js';
 export const settingsTools = [
     {
         name: 'read_site_settings',
-        description: "Read every site setting: name, tagline, logo, favicon, colors, fonts, contact info, social links, default SEO suffix, language, robots_txt, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css.",
+        description: "Read every site setting: name, tagline, logo, favicon, colors, fonts, contact info, social links, default SEO suffix, language, robots_txt, image_sizes_default, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css.",
         handler: withErrorBoundary(async (_args, { client, siteId }) => {
             const res = await client.get(siteId, 'settings');
             return ok(res);
@@ -32,6 +32,7 @@ export const settingsTools = [
             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(),
+            image_sizes_default: z.string().optional().describe('Site-wide default `sizes` attribute for responsive-image <picture> output, e.g. "(max-width: 640px) 360px, 560px". Tells the browser how wide images actually render so it stops over-fetching the larger srcset variant. A page can override via its own image_sizes_default; a per-<img> `sizes` attribute wins over both. Leave unset for the generic "(max-width: 768px) 100vw, 800px".'),
             // Scriptable surfaces. Trusted because the caller has an API key.
             scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page. Use for analytics, fonts, third-party CSS links.'),
             scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page. Use for chat widgets, deferred analytics.'),

package/package.json

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