@typeroll/mcp-server 0.38.0 → 0.41.0

package/dist/extension-cli.js

@@ -67,6 +67,19 @@ function executionOrigins(manifest) {
             urls.push(value);
     return [...new Set(urls.map((value) => new URL(value).origin))];
 }
+export function extensionMetadataUpdate(manifest, registered, manifestOrigins) {
+    const trusted = Array.isArray(registered.trusted_origins)
+        ? registered.trusted_origins.map(String)
+        : [];
+    const update = {
+        name: manifest.name,
+        trusted_origins: [...new Set([...trusted, ...manifestOrigins])],
+    };
+    if (registered.distribution !== manifest.distribution) {
+        update.distribution = manifest.distribution;
+    }
+    return update;
+}
 async function api(path, init = {}, allowed = []) {
     const baseUrl = process.env.TYPEROLL_API_URL?.trim().replace(/\/$/, '');
     const apiKey = process.env.TYPEROLL_API_KEY?.trim();
@@ -126,14 +139,9 @@ export async function runExtensionCli(args) {
             }
             else {
                 const registered = current.data.extension;
-                const trusted = Array.isArray(registered?.trusted_origins) ? registered.trusted_origins.map(String) : [];
                 await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`, {
                     method: 'PATCH',
-                    body: JSON.stringify({
-                        name: manifest.name,
-                        distribution: manifest.distribution,
-                        trusted_origins: [...new Set([...trusted, ...executionOrigins(manifest)])],
-                    }),
+                    body: JSON.stringify(extensionMetadataUpdate(manifest, registered, executionOrigins(manifest))),
                 });
             }
             const pushed = await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}/versions`, {

package/dist/server.js

@@ -29,6 +29,7 @@ import { siteTools } from './tools/sites.js';
 import { domainTools } from './tools/domain.js';
 import { funnelAttributionTools } from './tools/funnel-attribution.js';
 import { appTools } from './tools/apps.js';
+import { extensionTools } from './tools/extensions.js';
 import { skillTools } from './tools/skills.js';
 import { fail } from './tools/helpers.js';
 import { VERSION } from './version.js';
@@ -38,14 +39,17 @@ const PERM_RANK = { read: 0, write: 1, admin: 2 };
  * conservative — anything that mutates is `write`. The MCP route's per-call
  * gate then checks `effect <= sitePermission`.
  *
- * Naming convention is followed by all 16 tool files: read paths are
- * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*`; everything else
+ * Naming convention is followed by the tool modules: read paths are
+ * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*` / `check_*`; everything else
  * mutates.
  */
 function effectFor(name) {
     if (name === 'list_apps'
         || name === 'read_app'
         || name === 'update_app'
+        || name === 'list_extension_installations'
+        || name === 'read_extension_installation'
+        || name === 'update_extension_installation_config'
         || name === 'read_funnel_attribution'
         || name === 'update_funnel_attribution')
         return 'admin';
@@ -54,7 +58,8 @@ function effectFor(name) {
         name.startsWith('get_') ||
         name.startsWith('batch_read_') ||
         name.startsWith('preview_') ||
-        name.startsWith('search_')) {
+        name.startsWith('search_') ||
+        name.startsWith('check_')) {
         return 'read';
     }
     return 'write';
@@ -80,8 +85,11 @@ playbook ships with this server — use it:
    list_skills FIRST, then read_skill <name> for the step-by-step recipe
    (tr-new-site, tr-migrate-wp, tr-brand, tr-blog, tr-responsive, …). These are
    the canonical how-to; don't improvise what a skill already covers.
-2. Discover before you write: get_site, read_site_settings, list_pages,
-   list_block_types. Never hardcode block ids or field names — they're per-site.
+2. Discover before you write: get_site, get_site_capabilities,
+   read_site_settings, list_pages, list_block_types. Never hardcode block ids
+   or field names — they're per-site. For installed Extension config, call
+   list_extension_installations then read_extension_installation before an
+   update.
 3. THE BUFFER MODEL: every content write (pages, blocks, partials,
    collection items) lands in an unsaved per-doc DRAFT — deploys and plain
    previews see saved content only. Iterate freely, view your drafts with
@@ -125,6 +133,7 @@ export function buildServer(options) {
         ...formTools,
         ...settingsTools,
         ...appTools,
+        ...extensionTools,
         ...funnelAttributionTools,
         ...searchTools,
         ...bulkTools,

package/dist/tools/bulk.js

@@ -4,14 +4,26 @@ function v(version) {
     return version ? { version } : undefined;
 }
 export const bulkTools = [
+    {
+        name: 'check_internal_links',
+        description: 'Check internal hrefs against the versioned database before deploy. Covers published pages, partials, collection templates/items, page templates, generated collection/facet routes, media URLs and redirect chains. Returns every broken source/href pair without requesting the live site.',
+        inputSchema: { version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.get(siteId, 'internal-links', v(args.version)));
+        }),
+    },
     {
         name: 'bulk_replace_text',
-        description: 'Replace a literal substring or regex across pages in one call. ALWAYS run with dry_run=true first and show the sample_diffs to the user before running the real call. BUFFER MODEL: replacements land in each page\'s unsaved DRAFT; after the user approves the diffs, run with save:true to commit each touched page (revision snapshots + SEO transforms included). Response: { dry_run, updated, saved, total_matches, pages_with_matches, sample_diffs_shown, additional_pages_with_matches, sample_diffs[], skipped (deprecated) }.',
+        description: 'Replace a literal substring or regex across pages, collection-item schema fields, and partials. ALWAYS run with dry_run=true first and show sample_diffs before the real call. Defaults to scope=pages for backwards compatibility. BUFFER MODEL: replacements land in unsaved DRAFTS; save=true commits each touched resource through the canonical save path.',
         inputSchema: {
             pattern: z.string().min(1).describe('Literal substring (default) or JS regex source if regex=true.'),
             replacement: z.string(),
             regex: z.boolean().optional().describe('Treat pattern as a regex source. Always case-insensitive + global.'),
+            scope: z.enum(['pages', 'collection_items', 'partials', 'all']).optional().describe('Resource family to scan. Defaults to pages.'),
             page_ids: z.array(z.string()).optional().describe('Restrict to these page ids. Omit to apply to every matching page.'),
+            collection: z.string().optional().describe('Restrict collection-item replacement to this collection.'),
+            item_ids: z.array(z.string()).optional().describe('Restrict to item ids. Requires collection.'),
+            partial_ids: z.array(z.string()).optional().describe('Restrict to partial ids.'),
             dry_run: z.boolean().optional(),
             save: z.boolean().optional().describe('Commit every touched page\'s draft in the same call — the usual choice after the user approved the dry-run diffs.'),
             version: versionParam,

package/dist/tools/collections.js

@@ -4,6 +4,12 @@ import { ok, withErrorBoundary, versionParam } from './helpers.js';
 function v(version) {
     return version ? { version } : undefined;
 }
+function existingCollectionArg(args) {
+    const value = args.collection ?? args.name;
+    if (!value)
+        throw new Error('collection is required');
+    return value;
+}
 export const collectionTools = [
     {
         name: 'create_collection',
@@ -38,9 +44,10 @@ export const collectionTools = [
     },
     {
         name: 'update_collection_schema',
-        description: 'PATCH a collection\'s schema or routing. Pass only the fields you want to change. Renaming a field would orphan existing item data — adding new fields is safe, removing fields is silently allowed but item docs keep the dropped data.',
+        description: 'PATCH a collection\'s schema or routing. `collection` is required (`name` remains a deprecated compatibility alias). Pass only the fields you want to change. Renaming a field would orphan existing item data — adding new fields is safe, removing fields is silently allowed but item docs keep the dropped data.',
         inputSchema: {
-            name: z.string(),
+            collection: z.string().optional().describe('Collection machine name. Preferred argument name.'),
+            name: z.string().optional().describe('Deprecated alias for collection.'),
             patch: z
                 .object({
                 label_singular: z.string().optional(),
@@ -65,20 +72,23 @@ export const collectionTools = [
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.patch(siteId, `collections/${encodeURIComponent(args.name)}`, args.patch, v(args.version));
+            const collection = existingCollectionArg(args);
+            const res = await client.patch(siteId, `collections/${encodeURIComponent(collection)}`, { patch: args.patch }, v(args.version));
             return ok(res);
         }),
     },
     {
         name: 'delete_collection',
-        description: 'Delete a collection AND every item in it. Destructive; requires `confirm: true`. Get-the-user-to-confirm workflow recommended.',
+        description: 'Delete a collection AND every item in it. `collection` is required (`name` remains a deprecated compatibility alias). Destructive; requires `confirm: true`. Get-the-user-to-confirm workflow recommended.',
         inputSchema: {
-            name: z.string(),
+            collection: z.string().optional().describe('Collection machine name. Preferred argument name.'),
+            name: z.string().optional().describe('Deprecated alias for collection.'),
             confirm: z.literal(true).describe('Must be true to actually delete.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.del(siteId, `collections/${encodeURIComponent(args.name)}`, { confirm: 'true', ...v(args.version) });
+            const collection = existingCollectionArg(args);
+            const res = await client.del(siteId, `collections/${encodeURIComponent(collection)}`, { confirm: 'true', ...v(args.version) });
             return ok(res);
         }),
     },
@@ -93,10 +103,15 @@ export const collectionTools = [
     },
     {
         name: 'read_collection',
-        description: 'Fetch one collection\'s schema (label, fields, icon).',
-        inputSchema: { name: z.string(), version: versionParam },
+        description: 'Fetch one collection\'s schema (label, fields, icon). `collection` is required; `name` remains a deprecated compatibility alias.',
+        inputSchema: {
+            collection: z.string().optional().describe('Collection machine name. Preferred argument name.'),
+            name: z.string().optional().describe('Deprecated alias for collection.'),
+            version: versionParam,
+        },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.get(siteId, `collections/${encodeURIComponent(args.name)}`, v(args.version));
+            const collection = existingCollectionArg(args);
+            const res = await client.get(siteId, `collections/${encodeURIComponent(collection)}`, v(args.version));
             return ok(res);
         }),
     },
@@ -148,7 +163,7 @@ export const collectionTools = [
     },
     {
         name: 'read_collection_item',
-        description: 'Fetch a single item with all fields.',
+        description: 'Fetch a single item with all fields. item_id may be the internal id or the value of the collection\'s slug_field.',
         inputSchema: { collection: z.string(), item_id: z.string(), version: versionParam },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `collections/${encodeURIComponent(args.collection)}/items/${encodeURIComponent(args.item_id)}`, v(args.version));
@@ -172,7 +187,7 @@ export const collectionTools = [
     },
     {
         name: 'update_collection_item',
-        description: 'Update a collection item. Fields outside the schema are dropped. BUFFER MODEL: field values land in the item\'s unsaved DRAFT (status applies immediately); pass save:true to commit in the same call, or commit_working_copy later. Scheduled publishing (0.29.0+): pass publish_at/unpublish_at INSIDE `fields` — ISO datetime at which the platform flips status (+ deploys the site); null clears; applies immediately like status.',
+        description: 'Update a collection item by internal id or slug_field value. Fields outside the schema are dropped. BUFFER MODEL: field values land in the item\'s unsaved DRAFT (status applies immediately); pass save:true to commit in the same call, or commit_working_copy later. Scheduled publishing (0.29.0+): pass publish_at/unpublish_at INSIDE `fields` — ISO datetime at which the platform flips status (+ deploys the site); null clears; applies immediately like status.',
         inputSchema: {
             collection: z.string(),
             item_id: z.string(),

package/dist/tools/extensions.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const extensionTools = [
+    {
+        name: 'list_extension_installations',
+        description: 'List the site\'s installed Extensions, including installation ids, manifests, config schemas, and masked current config. Read this before updating installation config. Admin permission required.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            return ok(await client.get(siteId, 'extensions'));
+        }),
+    },
+    {
+        name: 'read_extension_installation',
+        description: 'Read one Extension installation, its manifest config schema, and its masked current config. Secret values are never returned. Admin permission required.',
+        inputSchema: {
+            installation_id: z.string().min(1).describe('Installation id returned by list_extension_installations.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.get(siteId, `extensions/${encodeURIComponent(args.installation_id)}`));
+        }),
+    },
+    {
+        name: 'update_extension_installation_config',
+        description: 'Update schema-defined config for an installed Extension. Call read_extension_installation first and send only keys declared by manifest.config_schema. Omitted fields preserve their current values, including masked secrets. This can update public content such as consent text, policy-link text, and policy URLs. The response returns redeploy_required:true; call trigger_deploy separately after the change has been reviewed. Admin permission required.',
+        inputSchema: {
+            installation_id: z.string().min(1).describe('Installation id returned by list_extension_installations.'),
+            config: z.record(z.unknown()).describe('Config keys and values declared by the installation manifest config schema.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.patch(siteId, `extensions/${encodeURIComponent(args.installation_id)}`, { config: args.config }));
+        }),
+    },
+];

package/dist/tools/media.js

@@ -1,6 +1,7 @@
 // Media tools (list + signed upload URL + metadata patch).
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
+const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
 // Best-effort content-type inference from the URL extension. The server's
 // upload-URL endpoint requires content_type, so we have to pick *something*
 // before the actual fetch — and a bad guess gets corrected by the HEAD
@@ -35,6 +36,65 @@ function filenameFromUrl(url, fallback) {
     catch { /* fall through */ }
     return `import-${Date.now()}`;
 }
+async function readSourceBytes(response) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > MAX_UPLOAD_BYTES) {
+        throw new Error(`Source file too large (max ${MAX_UPLOAD_BYTES} bytes)`);
+    }
+    if (!response.body)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > MAX_UPLOAD_BYTES) {
+            await reader.cancel();
+            throw new Error(`Source file too large (max ${MAX_UPLOAD_BYTES} bytes)`);
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+async function uploadFromUrl(args, deps) {
+    const filename = filenameFromUrl(args.source_url, args.filename);
+    const sourceRes = await fetch(args.source_url);
+    if (!sourceRes.ok)
+        throw new Error(`Failed to fetch source URL: ${sourceRes.status} ${sourceRes.statusText}`);
+    const buf = await readSourceBytes(sourceRes);
+    const sourceCt = sourceRes.headers.get('content-type')?.split(';')[0]?.trim();
+    const contentType = args.content_type ?? sourceCt ?? inferContentType(filename);
+    const mint = await deps.client.post(deps.siteId, 'media/upload-url', {
+        filename, content_type: contentType, size: buf.byteLength, alt_text: args.alt_text,
+    });
+    const putRes = await fetch(mint.upload_url, {
+        method: 'PUT', headers: { 'Content-Type': contentType }, body: buf,
+    });
+    if (!putRes.ok)
+        throw new Error(`R2 upload failed: ${putRes.status} ${putRes.statusText}`);
+    let finalizeResult = null;
+    let finalizeError = null;
+    try {
+        finalizeResult = await deps.client.post(deps.siteId, `media/${encodeURIComponent(mint.media_id)}/finalize`);
+    }
+    catch (error) {
+        finalizeError = error instanceof Error ? error.message : String(error);
+    }
+    return {
+        media_id: mint.media_id, cdn_url: mint.cdn_url, filename,
+        content_type: contentType, size_bytes: buf.byteLength,
+        finalize: finalizeResult, finalize_error: finalizeError,
+    };
+}
 export const mediaTools = [
     {
         name: 'list_media',
@@ -80,55 +140,44 @@ export const mediaTools = [
             content_type: z.string().optional().describe('Override the inferred content type (e.g. when source_url has no extension).'),
             alt_text: z.string().optional(),
         },
-        handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const filename = filenameFromUrl(args.source_url, args.filename);
-            // 1. Fetch the source bytes on the agent's machine.
-            const sourceRes = await fetch(args.source_url);
-            if (!sourceRes.ok) {
-                throw new Error(`Failed to fetch source URL: ${sourceRes.status} ${sourceRes.statusText}`);
-            }
-            const buf = new Uint8Array(await sourceRes.arrayBuffer());
-            // Prefer the source's content-type header; fall back to extension
-            // inference; let the caller override the whole thing.
-            const sourceCt = sourceRes.headers.get('content-type')?.split(';')[0]?.trim();
-            const contentType = args.content_type ?? sourceCt ?? inferContentType(filename);
-            // 2. Mint a signed PUT URL through the Typeroll API.
-            const mint = await client.post(siteId, 'media/upload-url', {
-                filename,
-                content_type: contentType,
-                size: buf.byteLength,
-                alt_text: args.alt_text,
-            });
-            // 3. PUT the bytes straight to R2.
-            const putRes = await fetch(mint.upload_url, {
-                method: 'PUT',
-                headers: { 'Content-Type': contentType },
-                body: buf,
+        handler: withErrorBoundary(async (args, deps) => ok(await uploadFromUrl({
+            source_url: String(args.source_url),
+            filename: args.filename,
+            content_type: args.content_type,
+            alt_text: args.alt_text,
+        }, deps))),
+    },
+    {
+        name: 'upload_media_batch_from_urls',
+        description: 'Upload 1–50 public images/PDFs (max 25 MiB each) in one MCP call. Uses the same integrity-safe download → signed PUT → finalize pipeline as upload_media_from_url, with four concurrent workers. Returns one result per source URL; individual failures do not abort the batch.',
+        inputSchema: {
+            items: z.array(z.object({
+                source_url: z.string().url(),
+                filename: z.string().optional(),
+                content_type: z.string().optional(),
+                alt_text: z.string().optional(),
+            })).min(1).max(50),
+        },
+        handler: withErrorBoundary(async (args, deps) => {
+            const results = new Array(args.items.length);
+            let cursor = 0;
+            const workers = Array.from({ length: Math.min(4, args.items.length) }, async () => {
+                while (cursor < args.items.length) {
+                    const index = cursor++;
+                    const item = args.items[index];
+                    try {
+                        results[index] = { source_url: item.source_url, ok: true, ...(await uploadFromUrl(item, deps)) };
+                    }
+                    catch (error) {
+                        results[index] = { source_url: item.source_url, ok: false, error: error instanceof Error ? error.message : String(error) };
+                    }
+                }
             });
-            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);
-            }
+            await Promise.all(workers);
             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,
+                results,
+                succeeded: results.filter((result) => result.ok === true).length,
+                failed: results.filter((result) => result.ok === false).length,
             });
         }),
     },

package/dist/tools/migration.js

@@ -2,6 +2,33 @@ import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 const STATUS = z.enum(['migrated', 'redirected', 'excluded', 'unhandled']);
 export const migrationTools = [
+    {
+        name: 'import_sitemap',
+        description: 'Import an explicit sitemap URL into the migration URL inventory. Sitemap indexes are followed recursively; URLs outside source_origin are rejected and reported.',
+        inputSchema: {
+            url: z.string().url().describe('Absolute URL of a sitemap or sitemap index.'),
+            source_origin: z.string().url().optional().describe('Expected legacy-site origin. Defaults to the sitemap origin.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.post(siteId, 'migration-urls/import-sitemap', args));
+        }),
+    },
+    {
+        name: 'import_gsc_performance',
+        description: 'Import URL metrics from Google Search Console. Use property for a direct server-side Search Console API query, or csv for the manual export fallback. URL fragments are stripped, duplicate metrics are summed, and previously unknown URLs enter the inventory as unhandled.',
+        inputSchema: {
+            property: z.string().optional().describe('Search Console property, e.g. https://example.com/ or sc-domain:example.com.'),
+            months: z.number().int().min(1).max(16).optional(),
+            csv: z.string().optional().describe('Raw Search Console Pages CSV export.'),
+            source_origin: z.string().url().optional().describe('Legacy-site origin. Required for bare CSV paths or sc-domain properties.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            if ((typeof args.property === 'string') === (typeof args.csv === 'string')) {
+                throw new Error('Provide exactly one of property or csv.');
+            }
+            return ok(await client.post(siteId, 'migration-urls/import-gsc', args));
+        }),
+    },
     {
         name: 'get_migration_readiness',
         description: "Preflight for an import: is this site actually ready to receive a migration? CALL THIS FIRST, before moving any content. Every check exists because its failure is INVISIBLE afterwards — the pages import, the previews render, the customer signs off, and something is quietly wrong. The blockers: media storage (without it every <img> keeps its original URL, so the shiny new site is still served images by the old host, and the day that hosting is cancelled every image breaks at once) and the hosting adapter (without credentials, deploys return a job id and publish nothing while reporting success). Warnings cover the pre-cutover verification URL, AI reconstruction, form notification email and whether the target has a design to rebuild INTO. Returns { ready, blockers[], warnings[], checks[] } — each with a `fix`. If `ready` is false, stop and report the blockers to the user rather than starting the import; the content work would have to be redone.",
@@ -75,6 +102,27 @@ export const migrationTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'update_migration_urls',
+        description: 'Apply one shared patch to many inventory entries in a single API request. Select either `ids` (up to 2000) or `where: { source }`, never both. This is the migration-scale path for decisions such as “every wordpress-redirect-guess URL is an intentional 404”; it avoids hundreds of rate-limited PATCH calls. Returns matched/updated/unchanged counts, unknown ids, and the refreshed coverage summary.',
+        inputSchema: {
+            ids: z.array(z.string()).min(1).max(2000).optional(),
+            where: z.object({ source: z.string().min(1) }).optional(),
+            patch: z.object({
+                excluded: z.boolean().optional(),
+                notes: z.string().optional(),
+                gsc_clicks: z.number().nonnegative().optional(),
+                gsc_impressions: z.number().nonnegative().optional(),
+            }).refine((value) => Object.keys(value).length > 0, 'patch must include at least one writable field'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            if ((args.ids ? 1 : 0) + (args.where ? 1 : 0) !== 1) {
+                throw new Error('Provide exactly one selector: ids or where');
+            }
+            const res = await client.patch(siteId, 'migration-urls', args);
+            return ok(res);
+        }),
+    },
     {
         name: 'delete_migration_url',
         description: 'Remove an entry from the inventory entirely. Use for junk the crawl picked up (session URLs, faceted duplicates). To record a deliberate 404 instead, prefer update_migration_url with excluded: true — that keeps the decision visible in the coverage report.',
@@ -86,7 +134,7 @@ export const migrationTools = [
     },
     {
         name: 'verify_migration_urls',
-        description: "Pre-cutover parity check: actually REQUEST every inventory URL against the new site and report what it answers. list_migration_urls tells you what the data says; this tells you what the server does — a redirect pointing at an unpublished page, a typo'd path, or a redirect loop all read as \"handled\" in coverage and as a 404 to Googlebot. Runs against the site's fallback subdomain by default, which is the right target while the real domain still points at the old host. Verdicts: `ok` (200 at the same path), `ok_redirect` (redirects to a 200), `missing` (404/410 — the gap), `broken_redirect` (loop or chain ending badly), `error` (5xx/timeout, inconclusive). Also stamps verified/last_checked on the redirect rules it exercised. Deploy before running this — it tests the DEPLOYED site, not your drafts.",
+        description: "Pre-cutover parity check: actually REQUEST every inventory URL against the new site and report what it answers. list_migration_urls tells you what the data says; this tells you what the server does — a redirect pointing at an unpublished page, a typo'd path, or a redirect loop all read as \"handled\" in coverage and as a 404 to Googlebot. Runs against the site's fallback subdomain by default. The response is compact by default: the full summary plus only `missing`, `broken_redirect`, and `error` rows; successful rows are counted but omitted. Pass `verdicts` for an exact result filter or `include_successes: true` for every row. Canonical trailing-slash normalization counts as `ok`, not `ok_redirect`. Also stamps verified/last_checked on redirect rules it exercised. Deploy before running this — it tests the DEPLOYED site, not your drafts.",
         inputSchema: {
             target_origin: z
                 .string()
@@ -101,6 +149,14 @@ export const migrationTools = [
                 .array(STATUS)
                 .optional()
                 .describe('Only check entries with these coverage statuses. Default: all — "migrated" is exactly the claim this check exists to falsify.'),
+            verdicts: z
+                .array(z.enum(['ok', 'ok_redirect', 'missing', 'broken_redirect', 'error', 'excluded']))
+                .optional()
+                .describe('Only return rows with these verdicts. The summary still covers every checked URL.'),
+            include_successes: z
+                .boolean()
+                .optional()
+                .describe('Return all rows when verdicts is omitted. Default false: successful/excluded rows are summarized but omitted.'),
             limit: z.number().int().positive().max(500).optional().describe('Max URLs per run (default 150). `truncated: true` in the response means there are more.'),
             concurrency: z.number().int().positive().max(12).optional(),
         },

package/dist/tools/pages.js

@@ -83,6 +83,7 @@ export const pageTools = [
             blocks: z.array(z.any()).optional().describe('Block tree — only used when content_mode="blocks". Omit to get the default heading+prose seed.'),
             status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),
             seo_title: z.string().optional(),
+            append_seo_suffix: z.boolean().optional().describe('Set false to omit the site default SEO suffix on this page.'),
             seo_description: z.string().optional(),
             seo_image_alt: z.string().optional(),
             alternates: z
@@ -123,6 +124,7 @@ export const pageTools = [
                 author: z.string().optional(),
                 language: z.string().optional(),
                 seo_title: z.string().optional(),
+                append_seo_suffix: z.boolean().optional().describe('Set false to use seo_title/page title verbatim without the site suffix.'),
                 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.'),
@@ -224,6 +226,7 @@ export const pageTools = [
                 html_content: srcMode === 'html' ? src.html_content : '',
                 blocks: srcMode === 'blocks' ? (src.blocks ?? []) : undefined,
                 seo_title: src.seo_title,
+                append_seo_suffix: src.append_seo_suffix,
                 seo_description: src.seo_description,
                 og_image: src.og_image,
                 canonical_url: undefined, // intentionally NOT copied — point of canonical is to differ

package/dist/tools/settings.js

@@ -13,7 +13,7 @@ function v(version) {
 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, default meta description, language, robots_txt, image_sizes_default, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css. Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
+        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, language, robots_txt, image_sizes_default, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css. Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
         inputSchema: {
             version: versionParam,
         },
@@ -38,6 +38,9 @@ export const settingsTools = [
             logo: z.string().optional(),
             favicon: z.string().optional(),
             apple_touch_icon: z.string().optional().describe('URL to a 180x180 PNG for iOS/Android home-screen bookmarks. Emitted as <link rel="apple-touch-icon">.'),
+            icon_192: z.string().optional().describe('URL to a 192x192 PNG app icon. Emitted with sizes="192x192".'),
+            trailing_slash: z.enum(['always', 'never', 'ignore']).optional().describe('Canonical URL style. `always` is the default; `never` emits extensionless URLs without a final slash; `ignore` preserves authored paths.'),
+            iframe_allowed_hosts: z.array(z.string()).max(50).optional().describe('Additional exact HTTPS iframe hostnames allowed on this site, e.g. ["player.example.com"]. No wildcards, schemes, ports or paths.'),
             default_seo_suffix: z.string().optional(),
             default_meta_description: z.string().optional().describe('Site-wide fallback <meta name="description">. Used when a page has no seo_description of its own; falls back further to the tagline when unset.'),
             language: z.string().optional().describe('BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> on the rendered site.'),

package/dist/version.js

@@ -8,4 +8,4 @@
 //
 // Keep it in lockstep with package.json: tests/version.test.ts asserts
 // VERSION === package.json.version, so a bump that forgets this line fails CI.
-export const VERSION = '0.38.0';
+export const VERSION = '0.41.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.38.0",
+  "version": "0.41.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": {
@@ -20,6 +20,7 @@
     ".": "./dist/index.js",
     "./server": "./src/server.ts",
     "./client": "./src/client.ts",
+    "./version": "./src/version.ts",
     "./tools/helpers": "./src/tools/helpers.ts"
   },
   "files": [

package/skills/tr-brand.md

@@ -126,12 +126,12 @@ partial just to keep it off live; that's no longer necessary.
 
 ### Site icons — always propose them, never leave them empty
 
-Every site gets a favicon + apple touch icon as part of brand setup:
+Every site gets a favicon + apple touch icon + 192px app icon as part of brand setup:
 
 1. **Brand assets exist** (favicon-*.png, app icon, symbol): upload the
    right sizes via `upload_media_inline` (favicon: 32–64px PNG or SVG;
-   apple touch icon: 180×180 PNG) and set BOTH in one call:
-   `update_site_settings { "favicon": "<url>", "apple_touch_icon": "<url>" }`.
+   apple touch icon: 180×180 PNG; app icon: 192×192 PNG) and set all three in one call:
+   `update_site_settings { "favicon": "<url>", "apple_touch_icon": "<url>", "icon_192": "<url>" }`.
 2. **No icon assets:** derive a proposal instead of skipping — crop the
    logo's symbol to a square and resize locally (`sips -z 180 180 in.png
    --out icon-180.png` on macOS, or ImageMagick), or generate a simple

package/skills/tr-collection-template.md

@@ -5,6 +5,12 @@ description: Use when building a rich per-item detail page for a Typeroll collec
 
 # Rich detail templates for collections
 
+Prefer `item_template_blocks` when the design fits the block system. It can
+include `template/item_navigation`, whose previous/next URLs and titles are
+derived from the collection's `sort_field` and `sort_dir`; do not precompute
+four navigation fields per item. Use the HTML patterns below when the detail
+page genuinely needs richer loops or markup than the block schema provides.
+
 `item_template_html` uses lightweight Mustache substitution:
 
 - `{{field}}` — HTML-escaped value

package/skills/tr-images.md

@@ -9,6 +9,13 @@ The Typeroll API does NOT accept image bytes directly. Uploads go
 through a signed PUT URL straight to Cloudflare R2, and the API only
 sees the metadata. Two-step flow:
 
+For public source URLs, prefer `upload_media_from_url`; for 2–50 files use
+`upload_media_batch_from_urls` (max 25 MiB per file). Both download, upload,
+and finalize each asset automatically. Batch results preserve input order and
+report failures per item, so retry only the failed entries. Use the manual
+signed-URL flow below for local files or when you need direct control over the
+PUT.
+
 ## Recipe
 
 ### 1. Get an image

package/skills/tr-migrate-wp.md

@@ -177,7 +177,12 @@ Rules:
 Then verify against reality before anything is cut over:
 
 ```
-verify_migration_urls        # after trigger_deploy
+import_sitemap url="https://old.example.com/sitemap.xml"
+# Optional: direct Search Console query (platform service account must have property access)
+import_gsc_performance property="https://old.example.com/" months=6
+# Or paste a Search Console Pages CSV via csv="..." and source_origin.
+check_internal_links         # database preflight before deploy
+verify_migration_urls        # after trigger_deploy; compact exceptions by default
 ```
 
 ### 5. Preview + review with the user