@timelesscms-com/mcp-server 0.1.0

package/dist/tools/block-types.js

@@ -0,0 +1,42 @@
+// Block-type tools. Surface is wired in now so the future block editor
+// drops in without breaking integrations.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const blockTypeTools = [
+    {
+        name: 'list_block_types',
+        description: 'List registered block types with their schemas. Most sites have none today; this fills in when the block editor ships.',
+        inputSchema: { version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'block-types', v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_block_type',
+        description: 'Read one block type\'s schema.',
+        inputSchema: {
+            type_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `block-types/${encodeURIComponent(args.type_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'find_pages_using_block_type',
+        description: 'Pages whose block tree contains this block type. Empty for HTML-mode sites (the default today); fills in once block-mode pages exist.',
+        inputSchema: {
+            type_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `block-types/${encodeURIComponent(args.type_id)}/usage`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/bulk.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const bulkTools = [
+    {
+        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. Writes go through the normal pipeline (SEO transforms + revision snapshots).',
+        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.'),
+            page_ids: z.array(z.string()).optional().describe('Restrict to these page ids. Omit to apply to every matching page.'),
+            dry_run: z.boolean().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'bulk-replace', body, v(version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/collections.js

@@ -0,0 +1,197 @@
+// Collections + items (blog, team, events, products, custom).
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const collectionTools = [
+    {
+        name: 'create_collection',
+        description: 'Create a new content collection with a field schema and (optionally) per-item URLs. Pass `route_template` (e.g. "/restaurants/{slug}") to give each published item its own URL — omit to default to "/{name}/{slug}", set to "" to disable per-item URLs entirely.',
+        inputSchema: {
+            name: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
+            label_singular: z.string().min(1),
+            label_plural: z.string().min(1),
+            icon: z.string().optional(),
+            fields: z
+                .array(z.object({
+                name: z.string(),
+                label: z.string(),
+                type: z.string(),
+                required: z.boolean().optional(),
+                default: z.unknown().optional(),
+                options: z.array(z.string()).optional(),
+            }).passthrough())
+                .min(1),
+            slug_field: z.string().optional(),
+            sort_field: z.string().optional(),
+            sort_dir: z.enum(['asc', 'desc']).optional(),
+            route_template: z.string().optional(),
+            item_template_html: z.string().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'collections', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        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.',
+        inputSchema: {
+            name: z.string(),
+            patch: z
+                .object({
+                label_singular: z.string().optional(),
+                label_plural: z.string().optional(),
+                icon: z.string().optional(),
+                fields: z.array(z.record(z.unknown())).optional(),
+                slug_field: z.string().optional(),
+                sort_field: z.string().optional(),
+                sort_dir: z.enum(['asc', 'desc']).optional(),
+                route_template: z.string().optional(),
+                item_template_html: z.string().optional(),
+            })
+                .passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `collections/${encodeURIComponent(args.name)}`, 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.',
+        inputSchema: {
+            name: z.string(),
+            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) });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_collections',
+        description: 'List content collections on the site (name, label, icon, field schemas).',
+        inputSchema: { version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'collections', v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_collection',
+        description: 'Fetch one collection\'s schema (label, fields, icon).',
+        inputSchema: { name: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `collections/${encodeURIComponent(args.name)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_collection_items',
+        description: 'List items in a collection with status filter + cursor pagination (cap 200 per page). Defaults to summary mode (richtext/textarea fields replaced with a byte-count hint) so a 200-item directory listing stays compact; pass include_richtext: true if you actually need full bodies.',
+        inputSchema: {
+            collection: z.string(),
+            status: z.enum(['draft', 'published', 'all']).optional(),
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+            include_richtext: z.boolean().optional().describe('Include full richtext/textarea field values inline. Default false.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, version, include_richtext, ...query } = args;
+            const res = await client.get(siteId, `collections/${encodeURIComponent(collection)}/items`, { ...query, ...(include_richtext ? {} : { summary: 'true' }), ...v(version) });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'batch_read_collection_items',
+        description: 'Read up to 200 collection items in one call. Returns per-id found/not-found.',
+        inputSchema: {
+            collection: z.string(),
+            item_ids: z.array(z.string()).min(1).max(200),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `collections/${encodeURIComponent(args.collection)}/items/batch-read`, { item_ids: args.item_ids }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_collection_item',
+        description: 'Fetch a single item with all fields.',
+        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));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_collection_item',
+        description: 'Create an item. Fields outside the collection schema are silently dropped — call list_collections first if you\'re unsure what fields exist.',
+        inputSchema: {
+            collection: z.string(),
+            fields: z.record(z.unknown()),
+            status: z.enum(['draft', 'published']).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, version, ...body } = args;
+            const res = await client.post(siteId, `collections/${encodeURIComponent(collection)}/items`, body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_collection_item',
+        description: 'Update a collection item. Fields outside the schema are dropped.',
+        inputSchema: {
+            collection: z.string(),
+            item_id: z.string(),
+            fields: z.record(z.unknown()).optional(),
+            status: z.enum(['draft', 'published']).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, item_id, version, ...body } = args;
+            const res = await client.patch(siteId, `collections/${encodeURIComponent(collection)}/items/${encodeURIComponent(item_id)}`, body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'regenerate_collection_listing',
+        description: 'Refresh a hand-managed listing of collection items on a page. The agent inserts a marker pair `<!-- tcms:listing:{collection} -->` ... `<!-- /tcms:listing:{collection} -->` into a page body once; from then on this tool fills the section between the markers with the current published items, sorted by the collection\'s sort_field. Pass `item_template` to customize per-item HTML — {{field}} substitutes HTML-escaped, {{{field}}} raw, {{url}} resolves through the collection\'s route_template. Defaults to a basic <ul> of links.',
+        inputSchema: {
+            collection: z.string(),
+            page_id: z.string(),
+            item_template: z.string().optional()
+                .describe('Per-item HTML template. Default: <li><a href="{{url}}">{{title}}</a></li>'),
+            wrap_open: z.string().optional().describe('Override the opening wrap element. Default: <ul class="tcms-listing">'),
+            wrap_close: z.string().optional().describe('Override the closing wrap element. Default: </ul>'),
+            empty_html: z.string().optional().describe('Rendered when no items exist.'),
+            sort_field: z.string().optional().describe('Override the collection\'s default sort_field.'),
+            sort_dir: z.enum(['asc', 'desc']).optional(),
+            status_filter: z.enum(['published', 'all']).optional().describe('Default: published.'),
+            limit: z.number().int().min(1).max(500).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, version, ...body } = args;
+            const res = await client.post(siteId, `collections/${encodeURIComponent(collection)}/regenerate-listing`, body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_collection_item',
+        description: 'Delete a collection item.',
+        inputSchema: { collection: z.string(), item_id: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `collections/${encodeURIComponent(args.collection)}/items/${encodeURIComponent(args.item_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/deploy.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const deployTools = [
+    {
+        name: 'trigger_deploy',
+        description: 'Enqueue a deploy of the currently active version. Returns a job_id immediately; poll get_deploy_status until the status leaves queued/running.',
+        inputSchema: {
+            environment: z.enum(['production', 'staging']).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'deploy', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_deploys',
+        description: 'Recent deploy jobs, newest first (capped at 50).',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'deploys');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'get_deploy_status',
+        description: 'Status of a single deploy job (queued | running | succeeded | failed).',
+        inputSchema: { job_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `deploys/${encodeURIComponent(args.job_id)}`);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/forms.js

@@ -0,0 +1,98 @@
+// Forms — agents can create/update/delete forms, and read submissions.
+// The customer-facing submit endpoint is HMAC-signed and lives at
+// /api/forms/submit; the in-portal chat's `get_form_embed` tool produces
+// the snippet customers paste into their pages. This file is the
+// management surface.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+const fieldSchema = z.object({
+    name: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
+    type: z.enum([
+        'text', 'email', 'tel', 'url', 'number', 'textarea',
+        'select', 'checkbox', 'radio', 'hidden', 'gdpr_consent',
+    ]),
+    label: z.string(),
+    required: z.boolean().optional(),
+    placeholder: z.string().optional(),
+    options: z.array(z.string()).optional().describe('Required for type "select" and "radio".'),
+    default: z.unknown().optional(),
+});
+export const formTools = [
+    {
+        name: 'list_forms',
+        description: 'List every form defined on the site with its full field schema.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'forms');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_form',
+        description: 'Read one form by id, including fields, submit_text, and success_message.',
+        inputSchema: { form_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `forms/${encodeURIComponent(args.form_id)}`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_form',
+        description: 'Create a form. Each field has { name, type, label, required?, placeholder?, options? }. Allowed types: text, email, tel, url, number, textarea, select, checkbox, radio, hidden, gdpr_consent. The form can then be embedded on any page — use get_form_embed (in-portal chat) or render the form yourself by reading the schema.',
+        inputSchema: {
+            id: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
+            name: z.string().min(1),
+            fields: z.array(fieldSchema).min(1),
+            submit_text: z.string().optional(),
+            success_message: z.string().optional(),
+            actions: z.array(z.object({ type: z.string(), config: z.record(z.unknown()) })).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'forms', args);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_form',
+        description: 'Patch a form. Provide only the fields you want to change. Passing `fields` replaces the entire field list (so reorder + rename + drop happens in one call). The existing form_id is immutable.',
+        inputSchema: {
+            form_id: z.string(),
+            patch: z.object({
+                name: z.string().optional(),
+                fields: z.array(fieldSchema).optional(),
+                submit_text: z.string().optional(),
+                success_message: z.string().optional(),
+                actions: z.array(z.object({ type: z.string(), config: z.record(z.unknown()) })).optional(),
+            }),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `forms/${encodeURIComponent(args.form_id)}`, args.patch);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_form',
+        description: 'Delete a form. Existing submissions are preserved by default — pass delete_submissions: true to also drop them.',
+        inputSchema: {
+            form_id: z.string(),
+            delete_submissions: z.boolean().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `forms/${encodeURIComponent(args.form_id)}`, args.delete_submissions ? { delete_submissions: 'true' } : undefined);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_form_submissions',
+        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Use this to help a customer triage inbound contact / lead submissions.',
+        inputSchema: {
+            form_id: z.string(),
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { form_id, ...query } = args;
+            const res = await client.get(siteId, `forms/${encodeURIComponent(form_id)}/submissions`, query);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/helpers.js

@@ -0,0 +1,59 @@
+// Shared helpers for tool handlers.
+import { z } from 'zod';
+import { ApiError } from '../client.js';
+/** Format an arbitrary result as MCP tool output. Pretty-print JSON because
+ *  Claude renders code blocks well and we want the model to see structured
+ *  shapes, not blobby unfolded strings. */
+export function ok(data) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: typeof data === 'string' ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+/** Turn an API error into a structured tool error. Preserves the status
+ *  code so the agent can decide between "retry" and "give up". */
+export function fail(err) {
+    if (err instanceof ApiError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: err.message,
+                        status: err.status,
+                        body: err.body,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            { type: 'text', text: `Unexpected error: ${err instanceof Error ? err.message : String(err)}` },
+        ],
+        isError: true,
+    };
+}
+/** Convenience to wrap a handler so all API errors become structured tool
+ *  errors instead of throwing — Claude Code displays the result more
+ *  usefully when isError is set. */
+export function withErrorBoundary(handler) {
+    return async (args, deps) => {
+        try {
+            return await handler(args, deps);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    };
+}
+/** Shared zod fragment for the optional `version` parameter. */
+export const versionParam = z
+    .string()
+    .optional()
+    .describe('Branch id to target. Omit for main.');

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 TimelessCMS 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 TimelessCMS 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);
+        }),
+    },
+];