@typeroll/mcp-server 0.7.12 → 0.10.0

package/AGENTS.md

@@ -287,24 +287,50 @@ first if you're unsure what's writable.
 ```
 # 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, … }
+  → returns { media_id, cdn_url, finalize: {…}, finalize_error: null }
 
 # 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)
+# Both tools auto-finalize after PUT: immutable Cache-Control on the
+# original PLUS AVIF/WebP variants at 320/640/1024/1920. No manual
+# generate_image_variants call needed. The site-template renderer reads
+# the variants array off the Media doc and emits <picture> automatically
+# — you can keep the <img src="{cdn_url}"> markup simple.
 
 # 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}' .../>" }
+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"
 
 ```
@@ -438,7 +464,7 @@ stakeholder review.
 | **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` |
+| **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` |
 | **Settings** | `update_site_settings` (whitelist) |

package/README.md

@@ -105,9 +105,14 @@ the full reference + concrete operation recipes.
   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).
+  `upload_media_inline` (both auto-finalize after PUT — see below),
+  patch metadata, delete, `finalize_media` (per-item: applies immutable
+  Cache-Control + generates AVIF/WebP srcset variants — call after
+  `create_upload_url`'s raw PUT path), `finalize_all_media` (bulk
+  backfill for legacy libraries), `generate_image_variants` (the
+  variant half of finalize, kept for surgical reruns),
+  `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).

package/dist/server.js

@@ -24,6 +24,7 @@ import { blockTypeTools } from './tools/block-types.js';
 import { pageBlockTools } from './tools/page-blocks.js';
 import { settingsTools } from './tools/settings.js';
 import { siteTools } from './tools/sites.js';
+import { domainTools } from './tools/domain.js';
 import { fail } from './tools/helpers.js';
 const PERM_RANK = { read: 0, write: 1, admin: 2 };
 /**
@@ -73,6 +74,7 @@ export function buildServer(options) {
         ...versionTools,
         ...deployTools,
         ...previewTools,
+        ...domainTools,
     ];
     // SDK's registerTool has deeply-nested generics we can't unify across a
     // heterogeneous tool list at compile time — same shrug as stdio's index.ts.

package/dist/tools/collections.js

@@ -52,6 +52,14 @@ export const collectionTools = [
                 sort_dir: z.enum(['asc', 'desc']).optional(),
                 route_template: z.string().optional(),
                 item_template_html: z.string().optional(),
+                schema_type: z
+                    .string()
+                    .optional()
+                    .describe('Free-form Schema.org type for auto JSON-LD on every item route ("BlogPosting", "PodcastEpisode", "Product", "Event", "Recipe", "Course", …). Pair with schema_field_map when item field names differ from the schema property names.'),
+                schema_field_map: z
+                    .record(z.string())
+                    .optional()
+                    .describe('Override the default field→schema-property mapping. Example: { "audio_url": "contentUrl", "show_notes": "description" }. Values use camelCase (Schema.org convention).'),
             })
                 .passthrough(),
             version: versionParam,

package/dist/tools/domain.js

@@ -0,0 +1,98 @@
+// Custom-domain lifecycle tools. Wrap the four /api/v1/sites/{id}/domain/*
+// routes so an agent can read, attach, poll, activate, or remove a
+// custom domain through MCP. Admin-only on the server side; site-scoped
+// keys are implicitly admin, org-scoped keys forward the share's
+// permission.
+//
+// State machine recap (see docs/domain-lifecycle-plan.md):
+//
+//   no domain   ──add_domain──▶  pending
+//   pending     ──poll_domain──▶ pending | verified | failed
+//   verified    ──activate_domain──▶ live
+//   any state   ──remove_domain──▶ no domain
+//
+// `production_url` on the site response (list_sites / read_site) only
+// reflects the custom domain when status === 'live'. Until then,
+// agents should send users to the fallback URL.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const domainTools = [
+    {
+        name: 'read_domain',
+        description: "Read the current state of the site's custom domain. Returns " +
+            '`{ hostname, status, dns_target, verified_at, failure_reason }` ' +
+            "or `null` when no domain is attached. Status is one of 'pending' " +
+            "(DNS not yet verified), 'verified' (DNS + cert OK, awaiting customer " +
+            "activation), 'live' (production URL is now the custom domain), " +
+            "'failed' (Cloudflare returned an error — see failure_reason).",
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'domain');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'add_domain',
+        description: "Attach a custom domain to this site. The site MUST NOT already have " +
+            "a domain set — remove the existing one first. Returns the new state, " +
+            "including the CNAME target the customer must point DNS at. Status " +
+            "starts as 'pending'; once DNS is correct + cert is issued, " +
+            "`poll_domain` will flip it to 'verified', then `activate_domain` " +
+            "makes it production.",
+        inputSchema: {
+            hostname: z
+                .string()
+                .describe('Hostname to attach, e.g. "www.example.com". Leading https:// and trailing slashes are stripped.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'domain', { hostname: args.hostname });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'poll_domain',
+        description: "Ask Cloudflare for the current state of the attached domain and " +
+            "update the site doc accordingly. Idempotent — call after DNS " +
+            "changes propagate. Returns the new state; status may have advanced " +
+            "from 'pending' to 'verified' or 'failed'.",
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.post(siteId, 'domain/poll');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'activate_domain',
+        description: "Make the verified domain the production URL. Precondition: status " +
+            "must be 'verified' (or already 'live' — idempotent). After this " +
+            "call, the site's `production_url` switches from the fallback URL " +
+            "to https://<hostname>. " +
+            "By default also enqueues a production deploy so the canonical URL, " +
+            "sitemap, and JSON-LD update to reflect the new hostname — the " +
+            "response includes `deploy.job_id` you can poll. Pass " +
+            "`auto_deploy: false` to skip the deploy (the canonical stays at " +
+            "the previous URL until the customer deploys manually).",
+        inputSchema: {
+            auto_deploy: z
+                .boolean()
+                .optional()
+                .describe('Default true. Enqueue a production deploy after activation so canonical URLs update.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'domain/activate', args);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'remove_domain',
+        description: "Detach the custom domain from this site. Removes it from Cloudflare " +
+            "Pages and clears the site doc. The fallback subdomain remains. " +
+            "Use this when the customer wants to start over with a different " +
+            "hostname or move the site to a different domain provider.",
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.del(siteId, 'domain');
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/media.js

@@ -59,7 +59,7 @@ export const mediaTools = [
     },
     {
         name: 'create_upload_url',
-        description: 'Mint a 5-min signed PUT URL for direct-to-R2 upload. After the upload completes, the CDN url is what you reference in <img src="…">. The media doc is pre-created so a follow-up update_media can attach alt_text.',
+        description: 'Mint a 5-min signed PUT URL for direct-to-R2 upload. After the upload completes, the CDN url is what you reference in <img src="…">. REQUIRED follow-up: call `finalize_media` after the PUT succeeds — without it the original ships with no Cache-Control (Lighthouse will flag it) and no responsive variants get generated. The response carries `finalize_url` as a reminder. Prefer `upload_media_from_url` or `upload_media_inline` if you have the bytes in hand — they do the PUT + finalize for you in one call.',
         inputSchema: {
             filename: z.string().min(1),
             content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf"'),
@@ -108,12 +108,27 @@ export const mediaTools = [
             if (!putRes.ok) {
                 throw new Error(`R2 upload failed: ${putRes.status} ${putRes.statusText}`);
             }
+            // 4. Auto-finalize: set immutable Cache-Control on the original and
+            //    generate AVIF/WebP responsive variants. Best-effort — if it
+            //    fails (variant pipeline 500, missing env var on the server),
+            //    the upload itself still succeeded so we return ok with a
+            //    `finalize_error` flag instead of throwing.
+            let finalizeResult = null;
+            let finalizeError = null;
+            try {
+                finalizeResult = await client.post(siteId, `media/${encodeURIComponent(mint.media_id)}/finalize`);
+            }
+            catch (e) {
+                finalizeError = e instanceof Error ? e.message : String(e);
+            }
             return ok({
                 media_id: mint.media_id,
                 cdn_url: mint.cdn_url,
                 filename,
                 content_type: contentType,
                 size_bytes: buf.byteLength,
+                finalize: finalizeResult,
+                finalize_error: finalizeError,
             });
         }),
     },
@@ -149,12 +164,24 @@ export const mediaTools = [
             if (!putRes.ok) {
                 throw new Error(`R2 upload failed: ${putRes.status} ${putRes.statusText}`);
             }
+            // Auto-finalize (cache headers + AVIF/WebP variants). See
+            // upload_media_from_url for the same pattern + rationale.
+            let finalizeResult = null;
+            let finalizeError = null;
+            try {
+                finalizeResult = await client.post(siteId, `media/${encodeURIComponent(mint.media_id)}/finalize`);
+            }
+            catch (e) {
+                finalizeError = e instanceof Error ? e.message : String(e);
+            }
             return ok({
                 media_id: mint.media_id,
                 cdn_url: mint.cdn_url,
                 filename: args.filename,
                 content_type: args.content_type,
                 size_bytes: buf.byteLength,
+                finalize: finalizeResult,
+                finalize_error: finalizeError,
             });
         }),
     },
@@ -174,13 +201,31 @@ export const mediaTools = [
     },
     {
         name: 'generate_image_variants',
-        description: 'Run the build-time srcset pipeline for one image: produces webp + avif variants at 320 / 640 / 1024 / 1920 (skipping upscales), uploads them to R2 alongside the original, and patches the media doc with a variants[] array. Synchronous; takes ~1-5s per image. Skips PDFs and non-image media without erroring. Loop this over list_media to rebuild an existing library; call once per image right after upload to keep new media current.',
+        description: 'Run the build-time srcset pipeline for one image: produces webp + avif variants at 320 / 640 / 1024 / 1920 (skipping upscales), uploads them to R2 alongside the original, and patches the media doc with a variants[] array. Synchronous; takes ~1-5s per image. Skips PDFs and non-image media without erroring. NOTE: prefer `finalize_media` for new uploads — it does this PLUS sets immutable Cache-Control on the original. Use this tool only for surgical variant reruns.',
         inputSchema: { media_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.post(siteId, `media/${encodeURIComponent(args.media_id)}/generate-variants`);
             return ok(res);
         }),
     },
+    {
+        name: 'finalize_media',
+        description: 'Post-upload finalize for a single image: (1) applies immutable Cache-Control (public, max-age=31536000) to the R2 original via in-place CopyObject so the CDN caches it for a year, and (2) generates AVIF/WebP responsive variants if not already present. Call this immediately after a successful upload (the presigned PUT does NOT set cache headers — without finalize, Cloudflare defaults to ~4h and every visit re-fetches the original). Idempotent: safe to call twice. Skips variant work when variants already exist on the doc.',
+        inputSchema: { media_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `media/${encodeURIComponent(args.media_id)}/finalize`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'finalize_all_media',
+        description: 'Backfill version of finalize_media: walks the entire media library, applies cache headers + variant generation to every item missing them. Use this once on legacy sites to fix Lighthouse "cache lifetimes" + "image delivery" warnings in one go. Synchronous, can take minutes on large libraries (~1-5s per image needing variants, ~50ms for cache-only). Idempotent.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.post(siteId, 'media/finalize-all');
+            return ok(res);
+        }),
+    },
     {
         name: 'suggest_alt_text_context',
         description: 'Get everything you need to generate good alt-text for a media item: the image URL, a tuned SEO/accessibility prompt, the site\'s content language, and the list of pages where the image is used (with the nearest heading per use site). YOU run the actual vision call with your own model — this endpoint does NOT generate text. After you decide on alt-text, save it with update_media.',

package/dist/tools/pages.js

@@ -84,10 +84,13 @@ export const pageTools = [
             status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),
             seo_title: z.string().optional(),
             seo_description: z.string().optional(),
+            seo_image_alt: z.string().optional(),
+            schema_type: z.string().optional().describe('Free-form Schema.org type ("Service", "Course", "Product", …) for auto JSON-LD.'),
             kind: z.enum(['page', 'article']).optional(),
             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 }) => {
@@ -115,9 +118,22 @@ export const pageTools = [
                 seo_title: z.string().optional(),
                 seo_description: z.string().optional(),
                 og_image: z.string().optional(),
+                seo_image_alt: z.string().optional().describe('Alt text for og:image/twitter:image. Falls back to first <img alt> on the page when unset.'),
                 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
+                    .object({
+                    price: z.union([z.number(), z.string()]).optional(),
+                    price_currency: z.string().optional().describe('ISO 4217 (SEK, EUR, USD).'),
+                    duration: z.string().optional(),
+                    description: z.string().optional(),
+                    url: z.string().optional(),
+                })
+                    .optional(),
                 template: z.string().optional(),
             })
                 .passthrough(),

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.7.12",
+  "version": "0.10.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": {