@typeroll/mcp-server 0.7.12 → 0.9.0

package/AGENTS.md

@@ -287,22 +287,22 @@ 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='…' /></...>" }
 ```
 
 ### "Fill missing alt-text across the media library"
@@ -438,7 +438,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,6 +84,8 @@ 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).'),
@@ -115,9 +117,21 @@ 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.'),
                 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/package.json

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