@typeroll/mcp-server 0.7.4

package/dist/tools/media.js

@@ -0,0 +1,202 @@
+// Media tools (list + signed upload URL + metadata patch).
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+// 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
+// response if the agent supplies an override.
+function inferContentType(urlOrFilename) {
+    const lower = urlOrFilename.toLowerCase().split('?')[0];
+    if (lower.endsWith('.jpg') || lower.endsWith('.jpeg'))
+        return 'image/jpeg';
+    if (lower.endsWith('.png'))
+        return 'image/png';
+    if (lower.endsWith('.webp'))
+        return 'image/webp';
+    if (lower.endsWith('.gif'))
+        return 'image/gif';
+    if (lower.endsWith('.avif'))
+        return 'image/avif';
+    if (lower.endsWith('.svg'))
+        return 'image/svg+xml';
+    if (lower.endsWith('.pdf'))
+        return 'application/pdf';
+    return 'application/octet-stream';
+}
+function filenameFromUrl(url, fallback) {
+    if (fallback)
+        return fallback;
+    try {
+        const u = new URL(url);
+        const last = u.pathname.split('/').filter(Boolean).pop();
+        if (last)
+            return decodeURIComponent(last);
+    }
+    catch { /* fall through */ }
+    return `import-${Date.now()}`;
+}
+export const mediaTools = [
+    {
+        name: 'list_media',
+        description: 'List uploaded media items (CDN URLs, alt text, mime). Newest first, cursor-paginated.',
+        inputSchema: {
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'media', { limit: args.limit, cursor: args.cursor });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_media',
+        description: 'Read one media item\'s metadata by id.',
+        inputSchema: { media_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `media/${encodeURIComponent(args.media_id)}`);
+            return ok(res);
+        }),
+    },
+    {
+        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.',
+        inputSchema: {
+            filename: z.string().min(1),
+            content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf"'),
+            size: z.number().int().nonnegative().optional(),
+            alt_text: z.string().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'media/upload-url', args);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'upload_media_from_url',
+        description: 'Fetch an image (or PDF) from any public URL and push it to the site\'s media library in one call. The bytes pass through the agent\'s machine — they do NOT go through the Typeroll API — so this works whenever your agent can `fetch()` the source. Returns { media_id, cdn_url, filename }.',
+        inputSchema: {
+            source_url: z.string().url().describe('Public URL to download the image from.'),
+            filename: z.string().optional().describe('Override the filename used on R2. Defaults to the last path segment of source_url.'),
+            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,
+            });
+            if (!putRes.ok) {
+                throw new Error(`R2 upload failed: ${putRes.status} ${putRes.statusText}`);
+            }
+            return ok({
+                media_id: mint.media_id,
+                cdn_url: mint.cdn_url,
+                filename,
+                content_type: contentType,
+                size_bytes: buf.byteLength,
+            });
+        }),
+    },
+    {
+        name: 'upload_media_inline',
+        description: 'Upload an image (or PDF) directly from base64-encoded bytes — useful when you generated the image with an image-gen tool and have it in memory. Same two-step signed-PUT flow as upload_media_from_url, no temp file needed. Returns { media_id, cdn_url, filename }.',
+        inputSchema: {
+            filename: z.string().min(1),
+            content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf"'),
+            data_base64: z.string().min(1).describe('The file bytes, base64-encoded (without a data: URL prefix).'),
+            alt_text: z.string().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            // Tolerate data: URL prefix in case the agent passed one through.
+            const raw = args.data_base64.startsWith('data:')
+                ? args.data_base64.slice(args.data_base64.indexOf(',') + 1)
+                : args.data_base64;
+            const buf = Uint8Array.from(Buffer.from(raw, 'base64'));
+            if (buf.byteLength === 0) {
+                throw new Error('data_base64 decoded to zero bytes — check the encoding.');
+            }
+            const mint = await client.post(siteId, 'media/upload-url', {
+                filename: args.filename,
+                content_type: args.content_type,
+                size: buf.byteLength,
+                alt_text: args.alt_text,
+            });
+            const putRes = await fetch(mint.upload_url, {
+                method: 'PUT',
+                headers: { 'Content-Type': args.content_type },
+                body: buf,
+            });
+            if (!putRes.ok) {
+                throw new Error(`R2 upload failed: ${putRes.status} ${putRes.statusText}`);
+            }
+            return ok({
+                media_id: mint.media_id,
+                cdn_url: mint.cdn_url,
+                filename: args.filename,
+                content_type: args.content_type,
+                size_bytes: buf.byteLength,
+            });
+        }),
+    },
+    {
+        name: 'update_media',
+        description: 'Patch a media item\'s alt_text or filename. Other fields are immutable.',
+        inputSchema: {
+            media_id: z.string(),
+            alt_text: z.string().optional(),
+            filename: z.string().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { media_id, ...body } = args;
+            const res = await client.patch(siteId, `media/${encodeURIComponent(media_id)}`, body);
+            return ok(res);
+        }),
+    },
+    {
+        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.',
+        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: '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.',
+        inputSchema: { media_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `media/${encodeURIComponent(args.media_id)}/alt-text-context`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_media',
+        description: 'Delete a media item\'s metadata. (R2 object cleanup is a separate ops task.)',
+        inputSchema: { media_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `media/${encodeURIComponent(args.media_id)}`);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/page-blocks.js

@@ -0,0 +1,155 @@
+// Page-block mutation tools. Five primitives (get/add/update/move/remove)
+// plus a one-shot HTML→blocks converter. All target the active version
+// (override with `version`).
+//
+// The AI agent uses these to author block-mode pages directly. For
+// HTML-mode pages, `convert_page_to_blocks` is the bridge — call with
+// `dry_run: true` first to preview, then `dry_run: false, switch_mode:
+// true` to commit.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+const blockSchema = z.object({
+    id: z.string().optional().describe('Stable id. Omit to let the server generate one.'),
+    type: z.string().describe('Block type id, e.g. "core/heading", "core/section", or a custom "user/banner".'),
+    data: z.record(z.unknown()).optional().describe('Field values matching the block-type schema.'),
+    children: z.array(z.any()).optional().describe('Nested blocks for container types.'),
+    slots: z.array(z.array(z.any())).optional().describe('Slot contents for slot-container types.'),
+    style_overrides: z.object({
+        spacing_before: z.string().optional(),
+        spacing_after: z.string().optional(),
+        custom_css: z.string().optional(),
+        custom_class: z.string().optional(),
+        html_id: z.string().optional(),
+    }).optional(),
+}).passthrough();
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const pageBlockTools = [
+    {
+        name: 'get_page_blocks',
+        description: 'Read a page\'s block tree. Returns content_mode (html or blocks) and the blocks array. Empty array for HTML-mode pages — those store body content in html_content instead. Use this before any block mutation so you know what you\'re modifying.',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'add_block',
+        description: 'Insert a block into a page. With no parent_id, inserts at top level. Otherwise inserts as a child (or into the named slot for slot-containers). Position defaults to "end". For slot containers, slot_index picks the slot; for regular containers it\'s ignored.',
+        inputSchema: {
+            page_id: z.string(),
+            block: blockSchema,
+            parent_id: z.string().optional().nullable(),
+            slot_index: z.number().int().min(0).optional(),
+            position: z.number().int().min(0).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+                block: args.block,
+                parent_id: args.parent_id,
+                slot_index: args.slot_index,
+                position: args.position,
+            }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_block',
+        description: 'Update a block\'s data fields (shallow merge), style overrides, or responsive settings. Does not modify children or slots — use move/add/remove for structural changes.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            data: z.record(z.unknown()).optional(),
+            style_overrides: z.object({
+                spacing_before: z.string().optional(),
+                spacing_after: z.string().optional(),
+                custom_css: z.string().optional(),
+                custom_class: z.string().optional(),
+                html_id: z.string().optional(),
+            }).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+                block_id: args.block_id,
+                data: args.data,
+                style_overrides: args.style_overrides,
+            }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'move_block',
+        description: 'Reparent or reorder a block. target_parent_id=null moves to top level. For slot containers, target_slot_index picks the slot. Cycles (moving a block into its own descendant) are rejected.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            target_parent_id: z.string().optional().nullable(),
+            target_slot_index: z.number().int().min(0).optional(),
+            target_position: z.number().int().min(0).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, {
+                block_id: args.block_id,
+                target_parent_id: args.target_parent_id,
+                target_slot_index: args.target_slot_index,
+                target_position: args.target_position,
+            }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'remove_block',
+        description: 'Remove a block and everything inside it from a page.',
+        inputSchema: {
+            page_id: z.string(),
+            block_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = { block_id: args.block_id };
+            if (args.version)
+                query.version = args.version;
+            const res = await client.del(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'set_page_mode',
+        description: 'Safely switch a page\'s content_mode between "blocks" and "html". Always snapshots a revision before the flip so the previous state is restorable. HTML → blocks with `convert: true` also runs the heuristic converter so the page starts with a populated tree. Blocks → HTML drops the block tree (the revision retains it). Prefer this over `update_page patch={content_mode}` because that bypasses snapshotting.',
+        inputSchema: {
+            page_id: z.string(),
+            to: z.enum(['blocks', 'html']).describe('Target mode.'),
+            convert: z.boolean().optional().describe('When going to blocks: run the htmlToBlocks heuristic on html_content. Ignored for blocks → html.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/mode`, { to: args.to, convert: args.convert ?? false }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'convert_page_to_blocks',
+        description: 'Heuristically convert a page\'s html_content into a block tree. By default runs as dry_run and returns the proposed blocks without writing. Pass dry_run: false to apply, and switch_mode: true to flip content_mode to "blocks" so the renderer uses the new tree. For a safer one-call switch with revision snapshot, use `set_page_mode` with `convert: true` instead.',
+        inputSchema: {
+            page_id: z.string(),
+            dry_run: z.boolean().optional().describe('Default true. When true, returns the proposed tree without writing.'),
+            switch_mode: z.boolean().optional().describe('When applying (dry_run=false), flip content_mode to "blocks". Default false.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert`, {
+                dry_run: args.dry_run ?? true,
+                switch_mode: args.switch_mode ?? false,
+            }, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/pages.js

@@ -0,0 +1,209 @@
+// Pages tools. Read + write + batch + blocks-view + preview.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const pageTools = [
+    {
+        name: 'list_pages',
+        description: 'List pages on the active site. Returns id, title, slug, status, and SEO summary. Supports filtering by status and forward-cursor pagination.',
+        inputSchema: {
+            status: z.enum(['draft', 'review', 'unlisted', 'published', 'all']).optional(),
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'pages', {
+                status: args.status,
+                limit: args.limit,
+                cursor: args.cursor,
+                ...v(args.version),
+            });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_page',
+        description: 'Fetch one page in full — title, slug, status, html_content, SEO fields.',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'batch_read_pages',
+        description: 'Read up to 200 pages in a single call. Use to bulk-load context before a redesign sweep.',
+        inputSchema: {
+            page_ids: z.array(z.string()).min(1).max(200),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'pages/batch-read', { page_ids: args.page_ids }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_page',
+        description: 'Create a new page. Defaults to blocks-mode (recommended) — the new page seeds with a heading + prose block built from the title. Pass content_mode="html" to opt out. Slug is derived from title when omitted; default status is "draft". Returns the created page.',
+        inputSchema: {
+            title: z.string().min(1),
+            slug: z.string().optional(),
+            content_mode: z.enum(['blocks', 'html']).optional().describe('Default "blocks". "html" stores body in html_content; "blocks" stores a Block[] tree.'),
+            html_content: z.string().optional().describe('Body HTML — only used when content_mode="html".'),
+            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(),
+            seo_description: z.string().optional(),
+            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.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'pages', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_page',
+        description: 'Shallow-merge update on a page (only the fields you pass change). Returns the updated page. For "replace this page entirely", use replace_page instead. To switch content_mode safely with a revision snapshot + optional auto-conversion, prefer `set_page_mode`.',
+        inputSchema: {
+            page_id: z.string(),
+            patch: z
+                .object({
+                title: z.string().optional(),
+                slug: z.string().optional(),
+                content_mode: z.enum(['blocks', 'html']).optional().describe('Changing this raw skips revision snapshotting — for safe switches use set_page_mode.'),
+                html_content: z.string().optional(),
+                blocks: z.array(z.any()).optional().describe('Block tree, only used when content_mode="blocks".'),
+                status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),
+                kind: z.enum(['page', 'article']).optional(),
+                author: z.string().optional(),
+                language: z.string().optional(),
+                seo_title: z.string().optional(),
+                seo_description: z.string().optional(),
+                og_image: z.string().optional(),
+                canonical_url: z.string().optional(),
+                noindex: z.boolean().optional(),
+                json_ld: z.string().optional(),
+                template: z.string().optional(),
+            })
+                .passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}`, args.patch, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'replace_page',
+        description: 'Full replace of a page\'s writable fields (PUT). Omitted fields are reset to undefined; use update_page if you want shallow merge.',
+        inputSchema: {
+            page_id: z.string(),
+            page: z.object({ title: z.string().min(1) }).passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}`, args.page, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'batch_update_pages',
+        description: 'Apply per-page patches in one call (up to 200 entries). Each entry is { page_id, patch }; failures are reported per-row, the rest still apply.',
+        inputSchema: {
+            updates: z
+                .array(z.object({
+                page_id: z.string(),
+                patch: z.record(z.unknown()),
+            }))
+                .min(1)
+                .max(200),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'pages/batch-write', args.updates, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'clone_page',
+        description: 'Duplicate an existing page under a new title + slug. Use this when you want a near-copy of an existing page as the starting point (e.g. duplicate "Privatflytt" → "Privatflytt Härnösand"). The new page is created as a draft regardless of the source\'s status. Returns the created page.',
+        inputSchema: {
+            source_page_id: z.string(),
+            title: z.string().min(1).describe('Title for the new page.'),
+            slug: z.string().optional().describe('Slug for the new page. Omit to auto-derive from title.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            // 1. Read the source — full body + SEO fields.
+            const sourceRes = await client.get(siteId, `pages/${encodeURIComponent(args.source_page_id)}`, v(args.version));
+            const src = sourceRes.page;
+            // 2. Build the new page body. Title + slug from args, everything else
+            //    copied — except the new page always starts as a draft so cloning
+            //    a published page doesn't accidentally publish a half-edited copy.
+            // Critical: preserve the source's content_mode exactly. Without
+            // this, create_page falls back to its blocks-default and seeds a
+            // fresh heading+prose tree, leaving the clone with TWO content
+            // sources (the copied html_content AND a default blocks[]). Bug
+            // surfaced in MCP-FEEDBACK-2.md from the Sundsvallsflytt demo build.
+            const srcMode = src.content_mode ?? 'html';
+            const body = {
+                title: args.title,
+                content_mode: srcMode,
+                html_content: srcMode === 'html' ? src.html_content : '',
+                blocks: srcMode === 'blocks' ? (src.blocks ?? []) : undefined,
+                seo_title: src.seo_title,
+                seo_description: src.seo_description,
+                og_image: src.og_image,
+                canonical_url: undefined, // intentionally NOT copied — point of canonical is to differ
+                noindex: src.noindex,
+                kind: src.kind,
+                author: src.author,
+                json_ld: undefined, // structured data is usually page-specific; force re-author
+                template: src.template,
+                status: 'draft',
+            };
+            if (args.slug)
+                body.slug = args.slug;
+            // 3. Create. The server auto-uniques the slug if it clashes.
+            const created = await client.post(siteId, 'pages', body, v(args.version));
+            return ok(created);
+        }),
+    },
+    {
+        name: 'delete_page',
+        description: 'Delete a page (tombstoned on branches, removed on main).',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `pages/${encodeURIComponent(args.page_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    // get_page_blocks lives in tools/page-blocks.ts alongside the rest of
+    // the block-tree mutation tools (add/update/move/remove/convert).
+    {
+        name: 'get_page_preview',
+        description: 'Get rendered HTML for one page (header-authed read). Returns { rendered_html, internal_links[] }. For a clickable preview URL use get_preview_link instead.',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/preview`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/partials.js

@@ -0,0 +1,108 @@
+// Partials (global blocks) tools.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const partialTools = [
+    {
+        name: 'list_partials',
+        description: 'List global blocks (header, footer, free blocks). Defaults to summary mode (no html_content, just metadata + byte count) to keep agent context lean — pass include_content: true if you actually want the bodies inline, otherwise call read_partial on the one you care about.',
+        inputSchema: {
+            include_content: z.boolean().optional().describe('Include full html_content in the response. Default false.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'partials', {
+                ...(args.include_content ? {} : { summary: 'true' }),
+                ...v(args.version),
+            });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_partial',
+        description: 'Fetch one global block including its full HTML content.',
+        inputSchema: {
+            partial_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `partials/${encodeURIComponent(args.partial_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_partial',
+        description: 'Shallow-merge update on a global block. Use partial_id "header" or "footer" for the auto-injected layout blocks, or a kebab-case id for a free block. HTML is sanitized server-side.',
+        inputSchema: {
+            partial_id: z.string(),
+            patch: z
+                .object({
+                name: z.string().optional(),
+                html_content: z.string().optional(),
+                status: z.enum(['draft', 'published']).optional(),
+                kind: z.enum(['header', 'footer', 'free']).optional(),
+            })
+                .passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `partials/${encodeURIComponent(args.partial_id)}`, args.patch, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'replace_partial',
+        description: 'Full replace of a global block (PUT). Use this when you want to set every field including auto-inferring kind from id.',
+        inputSchema: {
+            partial_id: z.string(),
+            partial: z.object({ html_content: z.string() }).passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.put(siteId, `partials/${encodeURIComponent(args.partial_id)}`, args.partial, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_free_block',
+        description: 'Create a new free (reusable) global block. Use a kebab-case id and embed it on pages with <x-include name="block-id" />.',
+        inputSchema: {
+            id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/),
+            name: z.string().optional(),
+            html_content: z.string(),
+            status: z.enum(['draft', 'published']).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'partials', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_partial',
+        description: 'Delete a free global block. header and footer cannot be deleted (they are layout blocks).',
+        inputSchema: {
+            partial_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `partials/${encodeURIComponent(args.partial_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'find_pages_using_block',
+        description: 'Pages that embed a given block via <x-include name="…">. For partial_id "header" or "footer" returns the full page list (they are auto-injected on every page). Use this to know the blast radius before editing a shared block.',
+        inputSchema: {
+            partial_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `partials/${encodeURIComponent(args.partial_id)}/usage`, v(args.version));
+            return ok(res);
+        }),
+    },
+];