@contenthero/mcp 0.4.7 → 0.4.9

package/dist/server.js

@@ -33,11 +33,28 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * ⚠️⚠️ **THE CONSTANTS ONLY, NOT THE `./server` HELPERS, AND THAT IS DELIBERATE.**
+ *
+ * `@modelcontextprotocol/ext-apps@2` targets the SPLIT packages (`@modelcontextprotocol/server`), while this
+ * server is built on the monolithic `@modelcontextprotocol/sdk@1.26`. Its `registerAppResource` therefore
+ * typechecks against a different `ResourceMetadata` than ours and rejects `description`.
+ *
+ * ⭐ The helper is convenience over a two-line contract: a resource whose mimeType is the app profile, and a
+ * tool result whose `_meta` names it. Registering through OUR `server.registerResource` keeps one server
+ * abstraction instead of two, and the STRINGS still come from the package, so the part that must match the
+ * spec has a single source. Migrating to the split SDK is its own piece of work, not a prerequisite for this.
+ */
+import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from '@modelcontextprotocol/ext-apps';
 import { z } from 'zod';
 import { GenerationTimeoutError, pendingOutputId, } from '@contenthero/sdk';
 import { getClient as defaultGetClient } from './client.js';
+/** This module's own directory, so the widget is read from the PACKAGE rather than from the cwd. */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+export { GENERATION_WIDGET_URI } from './widget-uri.js';
+import { GENERATION_WIDGET_URI } from './widget-uri.js';
 import { resolveModelEnums, BOARD_TYPES, BOARD_TYPE_GUIDANCE, IMAGE_MODEL_GUIDANCE, VIDEO_MODEL_GUIDANCE, AUDIO_MODEL_GUIDANCE, EDIT_AUDIO_MODEL_GUIDANCE, UPSCALE_MODEL_GUIDANCE, LIP_SYNC_MODEL_GUIDANCE, } from './models.js';
-import { audioResult, avatarListResult, avatarResult, avatarPendingResult, balanceResult, brandKitListResult, brandKitResult, brandKnowledgeListResult, brandKnowledgeDetailResult, brandKnowledgeSearchResult, brandKnowledgeItemResult, completedResult, connectedAccountListResult, connectedAccountResult, costResult, accountDetailResult, inspirationContentResult, mediaListResult, mediaSearchResult, folderListResult, folderContentsResult, mediaBatchResult, mediaUploadResult, importedMediaResult, uploadedMediaResult, tagListResult, tagResult, tagDeletedResult, modelListResult, modelResult, platformListResult, platformResult, elementListResult, elementResult, elementDeletedResult, errorResult, generationBatchResult, outlierListResult, enhanceClipsResult, pendingResult, stageListResult, stageResult, stageDeletedResult, spaceDeletedResult, spaceListResult, spaceResult, cardListResult, cardResult, postSummaryResult, publishResult, statusActionResult, editorOpsResult, text, projectDetailResult, liveContextResult, projectListResult, projectCreatedResult, projectDeletedResult, layerTypesResult, timelineTypesResult, editorTranscriptResult, exportJobResult, exportFormatsResult, trackedAccountListResult, transcriptResult, voiceListResult, voiceResult, } from './format.js';
+import { audioResult, avatarListResult, avatarResult, avatarPendingResult, balanceResult, brandKitListResult, brandKitResult, brandKnowledgeListResult, brandKnowledgeDetailResult, brandKnowledgeSearchResult, brandKnowledgeItemResult, completedResult, connectedAccountListResult, connectedAccountResult, costResult, accountDetailResult, inspirationContentResult, mediaListResult, mediaSearchResult, folderListResult, folderContentsResult, mediaBatchResult, mediaUploadResult, importedMediaResult, uploadedMediaResult, tagListResult, tagResult, tagDeletedResult, modelListResult, modelResult, platformListResult, platformResult, elementListResult, elementResult, elementDeletedResult, errorResult, generationBatchResult, outlierListResult, enhanceClipsResult, pendingResult, pollAfterSecondsFor, stageListResult, stageResult, stageDeletedResult, spaceDeletedResult, spaceListResult, spaceResult, cardListResult, cardResult, postSummaryResult, publishResult, statusActionResult, editorOpsResult, text, projectDetailResult, liveContextResult, projectListResult, projectCreatedResult, projectDeletedResult, layerTypesResult, timelineTypesResult, editorTranscriptResult, exportJobResult, exportFormatsResult, trackedAccountListResult, transcriptResult, voiceListResult, voiceResult, } from './format.js';
 /** Platforms a card or one of its posts may target. */
 const POST_PLATFORMS = [
     'youtube',
@@ -57,6 +74,33 @@ const POST_PLATFORMS = [
  * than tripping the client's timeout.
  */
 const SMART_WAIT_MS = 50_000;
+/**
+ * What a still-running generation can already say about the shape of its own result, read from the tool's
+ * own ARGUMENTS.
+ *
+ * ⚠️ **FROM `args`, NOT FROM THE BUILT REQUEST.** Every one of these sites builds its request inside a
+ * `try`, so the request is out of scope in the `catch` where a pending outputId surfaces. `args` is the
+ * handler's parameter and is always in scope, and it is also the more honest source: it is what the caller
+ * asked for, which is exactly what the placeholders should depict.
+ *
+ * ⚠️ Read defensively because the count is spelled `numImages` on some tools and `numGenerations` on
+ * others. A widened type here would be a third spelling; reading both is the whole reconciliation.
+ *
+ * ⛔ `auto` and `adaptive` are legal aspect inputs meaning "the model decides", so they are NOT ratios.
+ * Passing one through would have the widget lay placeholders out against a string it cannot parse. Null
+ * lets it fall back to its unshaped box, which is the honest state while nothing is known.
+ */
+function pendingShapeFrom(args, contentType) {
+    const a = (args ?? {});
+    const ar = a.aspectRatio;
+    const displayAspect = !ar || ar === 'auto' || ar === 'adaptive' || !ar.includes(':') ? null : ar;
+    return {
+        contentType,
+        modelId: a.modelId ?? '',
+        displayAspect,
+        expected: a.numImages ?? a.numGenerations ?? 1,
+    };
+}
 /**
  * Tool annotations drive how MCP clients group the surface. readOnlyHint=true
  * tools list under "Read-only"; the rest list under "Interactive". publish is
@@ -119,6 +163,159 @@ async function fetchSnapshotBase64(url) {
         return null;
     }
 }
+/**
+ * The asset itself, ready to attach to a finished generation.
+ *
+ * ## The rule, per medium
+ *
+ * ⭐⭐⭐ **BYTES FOR WHAT MCP CAN CARRY, A LINK FOR WHAT IT CANNOT.** Images and audio have first-class
+ * content blocks and modest sizes, so they are embedded: that is what makes them render in the chat, and it
+ * is also what makes them permanent, because bytes in a transcript cannot expire. Video has no block of its
+ * own and a ten-second 1080p clip would be megabytes of base64 in every future turn of the conversation, so
+ * it travels as a `resource_link` pointing at a capability url.
+ *
+ * ⛔ **FAILING TO FETCH IS NOT AN ERROR.** A generation that succeeded must never be reported as failed
+ * because we could not inline a preview of it. Every failure path returns no attachment and the text result
+ * stands on its own, which is exactly what the caller got before this existed.
+ *
+ * ⚠️ ONLY THE FIRST OUTPUT IS EMBEDDED WHEN THERE ARE MANY. A four-image batch as four base64 payloads is a
+ * large multiple of the same conversation cost, and the urls for the rest are already in the text. The cap
+ * is stated here rather than left implicit, because a silent truncation reads as "that is all there was".
+ */
+/**
+ * ⭐⭐⭐ **EVERY OUTPUT, AS A LINK, NOT THE FIRST ONE AS BYTES.**
+ *
+ * The first version embedded base64 for images and audio and capped at one attachment. Both halves were
+ * wrong, and they were wrong together:
+ *
+ *   - **The cap made a four-variation batch show one variation.** Generating four and seeing one is not a
+ *     smaller version of the feature, it is a broken one: the whole point of a batch is to compare them.
+ *   - **Base64 is charged to the user's context on every subsequent turn.** A four-image batch embedded as
+ *     bytes is a large multiple of the same cost, repeated for the rest of the conversation.
+ *
+ * ⭐ A `resource_link` costs a URL and renders in the host's UI, so ALL of them can come back. Verified
+ * against a working implementation: the Higgsfield MCP returns `resource_link` for its media and it renders.
+ *
+ * ## ⛔ THE THING THIS DELIBERATELY GIVES UP, AND WHERE IT WENT INSTEAD
+ *
+ * An `image` block feeds the MODEL's vision; a `resource_link` gives the HOST something to render for the
+ * human. Measured in this very session: when a link came back from another MCP, the model received text and
+ * could not see the picture.
+ *
+ * So the model can no longer critique a generation it just made from this result alone. That is the correct
+ * trade, because **`get_media` already exists to embed bytes for exactly that purpose** and an agent calls
+ * it when it actually needs to look. Deciding on every generation that the model probably wants to look was
+ * the wrong default: it spent the user's context to answer a question nobody asked.
+ *
+ * ⚠️ NO SSRF FETCH HAPPENS HERE ANY MORE. Nothing is downloaded, so the allowlist that guards
+ * `fetchSnapshotBase64` is not on this path; the url is handed to the host to fetch under its own rules.
+ */
+const LINK_MIME = {
+    image: 'image/png',
+    video: 'video/mp4',
+    audio: 'audio/mpeg',
+};
+/**
+ * ⛔⛔⛔ **A `resource_link` DOES NOT RENDER. MEASURED IN BOTH HOSTS, IN PRODUCTION, 2026-09-19.**
+ *
+ * This returned `kind: 'link'` for every output, including images, and the result was the feature not
+ * working at all:
+ *
+ *   - **ChatGPT** showed the output id and a "View the generated image" hyperlink. Clicking it opened the
+ *     asset in a NEW TAB, which is the opposite of inline.
+ *   - **Claude** showed NOTHING. No image, no link, no output id.
+ *
+ * ⚠️ **THE FORMATTER COULD ALWAYS DO THIS AND NOTHING EVER ASKED IT TO.** `completedResult` has handled a
+ * `kind: 'bytes'` attachment since it was written, and its own docblock claims images get first-class
+ * blocks. This function never produced one, so the branch had no caller. Same shape as the capability-url
+ * no-op: a path that exists, typechecks, passes tests, and is unreachable.
+ *
+ * ⭐ **AN `image` BLOCK IS THE ONLY THING A HOST ACTUALLY RENDERS**, and it feeds the model's vision as
+ * well, so the earlier reasoning that `get_media` covers the looking case was answering a different
+ * question than the one the user asked: they wanted to SEE it.
+ *
+ * ## Both, not either
+ *
+ * Images get a block AND a link. The block is the small `.preview.webp` sibling, so inline display costs a
+ * few hundred tokens rather than the megabytes a 2736x1536 original would. The link is the capability url:
+ * permanent, full resolution, and the thing to click when the preview is not enough.
+ *
+ * ⚠️ VIDEO STAYS LINK-ONLY. MCP has no video content block, and base64 video in a transcript is not a
+ * trade worth making. Audio likewise has no small derivative to send, so it stays a link too.
+ */
+/**
+ * ⛔⛔ **THERE IS NO HOST DETECTION HERE, AND THAT IS NOT AN OVERSIGHT.**
+ *
+ * The obvious optimization is to skip the bytes when the host will mount the widget, since the widget loads
+ * media from a URL and the blocks are only a fallback. I wrote it, and it could never work: MCP Apps
+ * declares its support under `capabilities.extensions["io.modelcontextprotocol/ui"]`, and
+ * **`@modelcontextprotocol/sdk@1.26` does not know the word `extensions`** (measured: zero occurrences in
+ * its types). The schema strips it, so `getClientCapabilities()` returns the same answer for a host that
+ * mounts widgets and one that cannot, and the check silently reduced to a constant.
+ *
+ * ⭐ A CHECK THAT ALWAYS ANSWERS THE SAME WAY IS WORSE THAN NO CHECK: it reads as a decision being made.
+ * Deleted, and the budget below is what keeps every result under the host's ceiling on its own.
+ *
+ * ⏭️ The split packages (`@modelcontextprotocol/server@2`) carry the field. Migrating to them is what
+ * unlocks this, and it is its own piece of work rather than a prerequisite for rendering.
+ */
+export async function attachmentsFor(gen) {
+    /**
+     * ⛔⛔⛔ **ONE BUDGET FOR THE WHOLE RESULT, BECAUSE THE HOST'S CEILING IS PER RESULT.**
+     *
+     * This was a PER-ITEM cap, which is the same defect one level up from the one it replaced. Four images at
+     * 600 KB each pass individually (822 KB encoded, under the budget) and total 3.3 MB, so the host rejects
+     * the call and the person pays for four generations they cannot reach. Today's assets are ~3.6 MB apiece
+     * and fail the per-item check anyway, so the batch case was safe BY ACCIDENT rather than by design.
+     *
+     * ⭐ Spending a single budget makes the envelope bounded no matter the count or the resolution: four 4K
+     * images, ten variations, a 60 second video. Whatever does not fit degrades to a link, and the widget
+     * renders it from a URL regardless, so nothing is lost but the fallback for hosts that cannot mount apps.
+     */
+    let budget = MAX_INLINE_BASE64_CHARS;
+    const urls = (gen.outputUrls ?? []).filter((u) => typeof u === 'string' && u.length > 0);
+    const mimeType = LINK_MIME[gen.contentType];
+    if (!mimeType)
+        return [];
+    const ext = mimeType.split('/')[1];
+    const out = [];
+    for (const [i, uri] of urls.entries()) {
+        /**
+         * ⭐ AUDIO HAS A FIRST-CLASS BLOCK TOO, and it plays inline exactly as an image draws. It is fetched the
+         * same best-effort way: a miss degrades this one output to a link rather than failing a generation the
+         * person already paid for.
+         *
+         * ⚠️ NO PREVIEW DERIVATIVE EXISTS FOR AUDIO, so this is the real file and the size cap is what stops a
+         * long track going into the transcript. A voiceover is small; an hour of music is not, and that one
+         * degrades to a link, which the widget renders anyway.
+         */
+        if (gen.contentType === 'audio') {
+            const bytes = await fetchAudioBytes(uri, budget);
+            if (bytes) {
+                budget -= bytes.data.length;
+                out.push({ kind: 'bytes', type: 'audio', data: bytes.data, mimeType: bytes.mimeType });
+            }
+        }
+        if (gen.contentType === 'image') {
+            // Best-effort: a miss (host not allowlisted, over the budget, network hiccup) degrades this one output
+            // to a link instead of failing a generation the user already paid for.
+            const bytes = await fetchMediaImageBase64(uri, budget);
+            if (bytes) {
+                budget -= bytes.data.length;
+                out.push({ kind: 'bytes', type: 'image', data: bytes.data, mimeType: bytes.mimeType });
+            }
+        }
+        /**
+         * ⛔ NO `resource_link` PER OUTPUT ANY MORE. It was a THIRD representation of a url the text list and the
+         * widget's `structuredContent` both already carry, and hosts render a run of them as `name: uri` with no
+         * separator, producing tokens that read as corrupted. The link added nothing the text did not, and cost
+         * a per-output block to say it.
+         */
+        void ext;
+        void mimeType;
+    }
+    return out;
+}
 /**
  * True when an image URL is safe to fetch into an image block. SSRF allowlist:
  * our storage hosts plus the finite set of generation-provider CDNs that our
@@ -134,6 +331,11 @@ function isAllowedImageHost(url) {
         if (u.username || u.password)
             return false;
         return (u.host === 'cloud.contenthero.ai' ||
+            // ⭐ THE MEDIA GATEWAY. Generated assets now address through it with a capability token rather than a
+            // presigned R2 url, so without this every inline attachment would be silently dropped by the SSRF
+            // allowlist and the agent would be back to a bare link.
+            u.host === 'media.contenthero.ai' ||
+            u.host === 'cdn.contenthero.ai' ||
             u.host.endsWith('.supabase.co') ||
             u.host.endsWith('.fal.media') ||
             u.host.endsWith('.cloudinary.com'));
@@ -161,17 +363,87 @@ function optimizedImageSibling(url) {
         return url;
     return query ? `${rewritten}?${query}` : rewritten;
 }
-async function fetchImageBytes(url) {
+/**
+ * ⛔⛔⛔ **A HOST ENFORCES A 1 MB CEILING ON A WHOLE TOOL RESULT, AND THIS IS SIZED AGAINST THAT.**
+ *
+ * Claude Desktop rejects an oversized result outright with "Tool result is too large. Maximum size is 1MB",
+ * which fails the CALL rather than degrading the picture. Measured 2026-09-19 on a real `generate_image`:
+ * the generation succeeded and was charged, and the person could not retrieve it.
+ *
+ * ⚠️ I SET THIS CAP WRONG TWICE BEFORE GETTING HERE. 1.5 MB was too low and would have silently degraded
+ * real outputs back to links; 8 MB was too high and broke the host. Both were reasoned from what the BYTES
+ * cost us. The number that actually governs belongs to the host, and it bounds the ENTIRE result: text,
+ * structured content, every block. So the budget is expressed in BASE64 LENGTH, which is what travels, and
+ * leaves room for everything else in the envelope.
+ *
+ * ⭐ Over budget, the item degrades to a link and the widget still renders it, because the widget loads from
+ * a url rather than from bytes.
+ *
+ * ⚠️ **DERIVED, NOT PICKED.** The ceiling is 1,000,000 bytes for the ENTIRE serialized result. Measured on a
+ * real one: text, `structuredContent` and the links together weigh about 2 KB. 900,000 base64 characters
+ * leaves roughly 100 KB of headroom, and admits a 657 KB source asset. A 613 KB PNG measured in production
+ * encodes to about 840 KB, so it fits with room to spare, where the 700,000 I first wrote would have thrown
+ * it away. That was the third time I set this number from reasoning instead of from a measurement.
+ */
+const MAX_INLINE_BASE64_CHARS = 900_000;
+/**
+ * The audio equivalent of `fetchImageBytes`, sharing its host allowlist, its size cap and its timeout.
+ *
+ * ⚠️ SEPARATE RATHER THAN A `kind` PARAMETER because the content-type CHECK is the difference, and a single
+ * function taking "which prefix do I accept" is the shape that eventually accepts the wrong one.
+ */
+async function fetchAudioBytes(url, budget) {
     if (!isAllowedImageHost(url))
         return null;
     try {
-        const res = await fetch(url);
+        const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
+        if (!res.ok)
+            return null;
+        const mimeType = res.headers.get('content-type') || 'audio/mpeg';
+        if (!mimeType.startsWith('audio/'))
+            return null;
+        // Base64 inflates by about a third, so the declared byte length is checked against the budget it will
+        // BECOME rather than against itself.
+        const declared = Number(res.headers.get('content-length') ?? '');
+        if (Number.isFinite(declared) && declared * 1.37 > budget)
+            return null;
+        const data = Buffer.from(await res.arrayBuffer()).toString('base64');
+        if (data.length > budget)
+            return null;
+        return { data, mimeType };
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchImageBytes(url, budget) {
+    if (!isAllowedImageHost(url))
+        return null;
+    try {
+        /**
+         * ⚠️⚠️ **A BARE `fetch` HAS NO TIMEOUT, AND THIS ONE IS ON THE PATH OF EVERY GENERATION RESULT.**
+         *
+         * One unresponsive asset would hang the whole tool call rather than degrading that item to a link, and
+         * the caller would see a dead generation they had already paid for. Found by `verify:inline` hanging on
+         * its first run after the status path started attaching.
+         *
+         * ⭐ Failing is CHEAP here and the fallback is good: no block, keep the link. Waiting is what is
+         * expensive, so the budget is deliberately short.
+         */
+        const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
         if (!res.ok)
             return null;
         const mimeType = res.headers.get('content-type') || 'image/jpeg';
         if (!mimeType.startsWith('image/'))
             return null;
+        // Checked BEFORE reading the body where the server declares it, and again after, because
+        // `content-length` is absent on a chunked response and a header is not a measurement.
+        const declared = Number(res.headers.get('content-length') ?? '');
+        if (Number.isFinite(declared) && declared * 1.37 > budget)
+            return null;
         const data = Buffer.from(await res.arrayBuffer()).toString('base64');
+        if (data.length > budget)
+            return null;
         return { data, mimeType };
     }
     catch {
@@ -184,15 +456,111 @@ async function fetchImageBytes(url) {
  * auto-upgrades as the optimization pipeline backfills derivatives, with no code
  * change here. Best-effort: any failure returns null and the item stays text-only.
  */
-async function fetchMediaImageBase64(url) {
+async function fetchMediaImageBase64(url, budget) {
     const optimized = optimizedImageSibling(url);
     if (optimized !== url) {
-        const hit = await fetchImageBytes(optimized);
+        const hit = await fetchImageBytes(optimized, budget);
         if (hit)
             return hit;
     }
-    return fetchImageBytes(url);
+    return fetchImageBytes(url, budget);
 }
+/**
+ * ⭐⭐⭐ **THE ONE PLACE THAT DECIDES HOW MUCH OF A RESULT MAY BE BYTES.**
+ *
+ * Two call sites needed this and each had its own answer, which is how the same defect appeared twice at
+ * different levels: `attachmentsFor` capped PER ITEM while the host's ceiling is per RESULT, and `get_media`
+ * fetched up to TEN images in parallel with no cap at all (10 x 840 KB is 8 MB against a 1 MB limit).
+ *
+ * ⛔ SEQUENTIAL, DELIBERATELY. The budget is shared state, so a parallel fetch cannot know what the others
+ * already spent and every one of them would pass a check the set as a whole fails. Most calls carry one to
+ * three items, so the latency is small and the alternative is a ceiling that holds only by luck.
+ *
+ * Returns one entry per input, `null` where the asset did not fit or could not be read, so callers keep
+ * positional alignment with what they asked for.
+ */
+async function inlineImagesWithinBudget(urls) {
+    let budget = MAX_INLINE_BASE64_CHARS;
+    const out = [];
+    for (const url of urls) {
+        if (!url) {
+            out.push(null);
+            continue;
+        }
+        const hit = await fetchMediaImageBase64(url, budget);
+        if (hit)
+            budget -= hit.data.length;
+        out.push(hit);
+    }
+    return out;
+}
+/**
+ * ⛔⛔⛔ **THE WIDGET IS DECLARED BY THE TOOL, NOT BY THE RESULT. I HAD IT ON THE RESULT.**
+ *
+ * A host reads `tool._meta` at `tools/list` time to learn that a tool renders a widget. Putting the binding
+ * only on the CallToolResult means the host never knows to mount anything, so the result arrives as plain
+ * blocks and the widget silently never appears. Measured in Claude Desktop 2026-09-19: four URLs as text,
+ * no viewer, no error anywhere.
+ *
+ * ⚠️ BOTH SPELLINGS, DELIBERATELY. `_meta.ui.resourceUri` is the current format and `ui/resourceUri` the
+ * legacy one, and the spec's own guidance is that hosts must accept either. Emitting both costs nothing and
+ * removes a whole class of "works in one client" from the table.
+ *
+ * ⭐ Spread into the tools whose results are MEDIA. Not onto all 87: a tool that returns a card or a folder
+ * has nothing for this widget to show, and claiming otherwise would put an empty frame under every call.
+ */
+const RENDERS_GENERATION = {
+    _meta: {
+        ui: { resourceUri: GENERATION_WIDGET_URI },
+        [RESOURCE_URI_META_KEY]: GENERATION_WIDGET_URI,
+    },
+};
+/**
+ * ⛔⛔⛔ **WITHOUT THIS THE FRAME LOADS NOTHING, AND THE SPEC SAYS SO PLAINLY:**
+ * "Empty or omitted → no network resources (secure default)."
+ *
+ * Measured in Claude Desktop 2026-09-19: the widget mounted, the chrome rendered, the variation strip and
+ * the buttons worked, and every image was a broken icon showing its own filename. The frame was doing
+ * exactly what it was told, which was to permit nothing.
+ *
+ * `resourceDomains` maps to `img-src`, `media-src`, `script-src`, `style-src` and `font-src`, so it is the
+ * one field that decides whether an `<img>` or a `<video>` in this widget can reach our storage.
+ *
+ * ⚠️ NO `connectDomains`. The widget never calls `fetch`: it points element sources at urls and lets the
+ * browser load them. Granting network access it does not use would widen the sandbox for nothing.
+ *
+ * ⚠️ These are the hosts that actually serve generated media, which is a SMALLER set than the server's SSRF
+ * allowlist. That list governs what the SERVER may fetch and inline; this governs what the FRAME may load.
+ * Two different questions, deliberately not one constant.
+ */
+const WIDGET_CSP = {
+    _meta: {
+        ui: {
+            csp: {
+                resourceDomains: [
+                    // Capability urls for generated assets: the token rides in the query string, so an element src
+                    // loads one directly with no header to set.
+                    'https://media.contenthero.ai',
+                    // Public-class objects (posters, gallery, stock).
+                    'https://cdn.contenthero.ai',
+                ],
+                /**
+                 * ⛔⛔ **A SEPARATE FIELD, AND OMITTING IT BLOCKS `fetch` ENTIRELY.**
+                 *
+                 * `resourceDomains` maps to `img-src`, `media-src` and friends, which is why the pictures render.
+                 * `connectDomains` maps to `connect-src`, and the spec's default for an omitted list is "no network
+                 * connections (secure default)". So the frame could DISPLAY our media and could not READ it, which
+                 * is exactly the shape needed to save a file: downloading means holding the bytes.
+                 *
+                 * ⚠️ Same origins, deliberately repeated rather than shared with a constant. They answer different
+                 * questions (may the frame paint this, may the frame read this) and a future answer to one is not
+                 * automatically the answer to the other.
+                 */
+                connectDomains: ['https://media.contenthero.ai', 'https://cdn.contenthero.ai'],
+            },
+        },
+    },
+};
 /** Drop undefined values so the request payload stays minimal. */
 function compact(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
@@ -228,6 +596,57 @@ export function registerTools(server, opts) {
      * shape per op type. Strictness here applies to the TOP-LEVEL argument object only, so those keep taking
      * varied op payloads while still rejecting an undeclared top-level parameter.
      */
+    /**
+     * ⭐⭐⭐ **THE GENERATION WIDGET: THE ONLY THING THAT PUTS A PLAYING VIDEO IN A CONVERSATION.**
+     *
+     * MCP's content blocks are `text | image | audio | resource | resource_link`. **There is no video block**,
+     * so no arrangement of them can render video, and a `resource_link` renders as a hyperlink in ChatGPT and
+     * as NOTHING in Claude. Measured in production 2026-09-19.
+     *
+     * MCP Apps is the mechanism that works. The server publishes an HTML resource under `ui://`, the host
+     * mounts it, and the widget reads the tool's `structuredContent`. It is an open standard with an official
+     * SDK (`@modelcontextprotocol/ext-apps`), verified against a working implementation before adoption.
+     *
+     * ⚠️ **THE HTML IS READ FROM THE PACKAGE, NOT FETCHED.** It ships inside the published tarball, so a local
+     * install renders the same thing the hosted server does. Fetching it from our app would make the widget
+     * depend on a deploy and break every offline or self-hosted install.
+     *
+     * ⛔ **REGISTERING THIS COSTS NOTHING FOR HOSTS THAT DO NOT SUPPORT IT.** A client that ignores `ui://`
+     * resources simply never reads it, and the image and audio BLOCKS remain the fallback. That is why the
+     * blocks stay rather than being replaced: two mechanisms, and the widget is the better one where it exists.
+     */
+    /**
+     * ⚠️⚠️ **REGISTERED UNCONDITIONALLY, AND READ LAZILY.**
+     *
+     * This used to read the bundle at startup and register the resource only if it was found. Two problems.
+     * A missing bundle produced a server that silently had no widget, which is the failure mode hardest to
+     * notice: every tool still worked and nothing rendered. And the resource then did not exist when running
+     * from `src/`, so the guard that checks tools point at a real resource could not run at all.
+     *
+     * ⭐ The resource is part of this server's contract. Advertising it always and throwing a NAMED error at
+     * read time turns "no widget, no reason" into one line that says exactly what is missing.
+     */
+    server.registerResource('generation', GENERATION_WIDGET_URI, {
+        description: 'Shows what a generation produced: every variation, playable and downloadable.',
+        mimeType: RESOURCE_MIME_TYPE,
+        ...WIDGET_CSP,
+    }, async () => {
+        const path = join(MODULE_DIR, 'widget', 'generation.html');
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch {
+            throw new Error(`The generation widget is missing at ${path}. It is built by \`npm run build\` ` +
+                '(`node widget/build.mjs`) and ships inside the package; a server running from source has not built it.');
+        }
+        // ⚠️ REPEATED ON THE READ RESULT, not just the listing. The spec reads csp from the `resources/read`
+        // content item and treats the `resources/list` entry as a FALLBACK, so a host that only consults the
+        // read path would otherwise see no policy and apply the secure default of blocking everything.
+        return {
+            contents: [{ uri: GENERATION_WIDGET_URI, mimeType: RESOURCE_MIME_TYPE, text, ...WIDGET_CSP }],
+        };
+    });
     const rawRegisterTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, cb) => {
         const shape = config.inputSchema;
@@ -295,9 +714,10 @@ export function registerTools(server, opts) {
     });
     // -- generate_image -------------------------------------------------------
     server.registerTool('generate_image', {
+        ...RENDERS_GENERATION,
         title: 'Generate Image',
         annotations: WRITE,
-        description: 'Generate one or more images from a text prompt (optionally image-to-image with reference images). Waits for the result and returns the image URLs. Optionally pass projectId to place the generated image onto that project in the same call, controlled by an optional placement: a VIDEO timeline places a clip on a track, a CANVAS design places a layer on a slide (defaulting to the slide the user is focused on). Omit projectId to save a standalone library output. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
+        description: 'Generate one or more images from a text prompt (optionally image-to-image with reference images). Waits for the result and returns the image URLs. Optionally pass projectId to place the generated image onto that project in the same call, controlled by an optional placement: a VIDEO timeline places a clip on a track, a CANVAS design places a layer on a slide (defaulting to the slide the user is focused on). Omit projectId to save a standalone library output. The result LINKS each output so the user sees it inline; to SEE it yourself (judge a face, check legibility, pick between variations) call get_media with the outputId. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
         inputSchema: {
             modelId: z.enum(models.image).describe(IMAGE_MODEL_GUIDANCE),
             prompt: z
@@ -344,7 +764,7 @@ export function registerTools(server, opts) {
             if (args.getCost)
                 return costResult(await client.estimateCost(request));
             const gen = await client.generateAndWait(request, { timeoutMs: SMART_WAIT_MS });
-            return completedResult(gen);
+            return completedResult(gen, await attachmentsFor(gen), [], client.baseUrl);
         }
         catch (err) {
             // A SUBMITTED generation is running and charged. Whether the wait timed out or a
@@ -352,12 +772,13 @@ export function registerTools(server, opts) {
             // dropping it invites a retry that generates and charges a second time.
             const pending = pendingOutputId(err);
             if (pending)
-                return pendingResult(pending);
+                return pendingResult(pending, pollAfterSecondsFor('image'), pendingShapeFrom(args, 'image'));
             return errorResult(err);
         }
     });
     // -- generate_board -------------------------------------------------------
     server.registerTool('generate_board', {
+        ...RENDERS_GENERATION,
         title: 'Generate Reference Board',
         annotations: WRITE,
         description: 'Generate a Reference Board: a dense multi-panel reference sheet (3:4, 4K) built from a source image and/or a written description, used to keep a subject on-model across later generations (feed the board back in as a referenceImage). Provide referenceImages and/or a prompt (at least one is required). Waits up to ~50s; boards render slowly (minutes), so it usually returns an outputId to poll with get_generation_status. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
@@ -399,7 +820,7 @@ export function registerTools(server, opts) {
             if (args.getCost)
                 return costResult(await client.estimateBoardCost(request));
             const gen = await client.generateBoardAndWait(request, { timeoutMs: SMART_WAIT_MS });
-            return completedResult(gen);
+            return completedResult(gen, await attachmentsFor(gen), [], client.baseUrl);
         }
         catch (err) {
             // A SUBMITTED generation is running and charged. Whether the wait timed out or a
@@ -407,15 +828,16 @@ export function registerTools(server, opts) {
             // dropping it invites a retry that generates and charges a second time.
             const pending = pendingOutputId(err);
             if (pending)
-                return pendingResult(pending);
+                return pendingResult(pending, pollAfterSecondsFor('image'), pendingShapeFrom(args, 'image'));
             return errorResult(err);
         }
     });
     // -- generate_video -------------------------------------------------------
     server.registerTool('generate_video', {
+        ...RENDERS_GENERATION,
         title: 'Generate Video',
         annotations: WRITE,
-        description: 'Generate a video from a text prompt (optionally from a start/end frame or reference images/videos/audio). Waits up to ~50s; if the render is still running it returns an outputId to poll with get_generation_status. Seedance 2.0 has two input modes selected by which references you pass: a startFrame (and optional endFrame) runs start/end-frame mode; referenceImages / referenceVideos / referenceAudio (without a startFrame) run references mode. Optionally pass projectId to place the generated video onto that project in the same call, controlled by an optional placement: a VIDEO timeline places a clip on a track, a CANVAS design places a layer on a slide (defaulting to the slide the user is focused on). Omit projectId to save a standalone library output. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
+        description: 'Generate a video from a text prompt (optionally from a start/end frame or reference images/videos/audio). Waits up to ~50s; if the render is still running it returns an outputId to poll with get_generation_status. Seedance 2.0 has two input modes selected by which references you pass: a startFrame (and optional endFrame) runs start/end-frame mode; referenceImages / referenceVideos / referenceAudio (without a startFrame) run references mode. Optionally pass projectId to place the generated video onto that project in the same call, controlled by an optional placement: a VIDEO timeline places a clip on a track, a CANVAS design places a layer on a slide (defaulting to the slide the user is focused on). Omit projectId to save a standalone library output. The result LINKS each output so the user sees it inline; to SEE it yourself (judge a face, check legibility, pick between variations) call get_media with the outputId. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
         inputSchema: {
             modelId: z.enum(models.video).describe(VIDEO_MODEL_GUIDANCE),
             prompt: z
@@ -500,7 +922,7 @@ export function registerTools(server, opts) {
             if (args.getCost)
                 return costResult(await client.estimateCost(request));
             const gen = await client.generateAndWait(request, { timeoutMs: SMART_WAIT_MS });
-            return completedResult(gen);
+            return completedResult(gen, await attachmentsFor(gen), [], client.baseUrl);
         }
         catch (err) {
             // A SUBMITTED generation is running and charged. Whether the wait timed out or a
@@ -508,7 +930,7 @@ export function registerTools(server, opts) {
             // dropping it invites a retry that generates and charges a second time.
             const pending = pendingOutputId(err);
             if (pending)
-                return pendingResult(pending);
+                return pendingResult(pending, pollAfterSecondsFor('video'), pendingShapeFrom(args, 'video'));
             return errorResult(err);
         }
     });
@@ -516,7 +938,7 @@ export function registerTools(server, opts) {
     server.registerTool('generate_audio', {
         title: 'Generate Audio',
         annotations: WRITE,
-        description: 'Generate audio with ElevenLabs: speech (TTS), music, or a sound effect. Returns the audio URL directly (synchronous, no polling). Optionally pass projectId to place the generated audio onto that editor project\'s timeline in the same call, controlled by an optional placement; omit projectId to save a standalone library output. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
+        description: 'Generate audio with ElevenLabs: speech (TTS), music, or a sound effect. Returns the audio URL directly (synchronous, no polling). Optionally pass projectId to place the generated audio onto that editor project\'s timeline in the same call, controlled by an optional placement; omit projectId to save a standalone library output. The result LINKS each output so the user sees it inline; to SEE it yourself (judge a face, check legibility, pick between variations) call get_media with the outputId. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
         inputSchema: {
             modelId: z.enum(models.audio).describe(AUDIO_MODEL_GUIDANCE),
             prompt: z.string().optional().describe('For music / sfx: what to generate.'),
@@ -617,6 +1039,7 @@ export function registerTools(server, opts) {
     });
     // -- upscale --------------------------------------------------------------
     server.registerTool('upscale', {
+        ...RENDERS_GENERATION,
         title: 'Upscale',
         annotations: WRITE,
         description: 'Upscale an existing image or video to a higher resolution. Provide the source media URL and a model-supported factor. Waits for the result; if the job is still running it returns an outputId to poll with get_generation_status. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
@@ -644,7 +1067,7 @@ export function registerTools(server, opts) {
             if (args.getCost)
                 return costResult(await client.estimateCost(request));
             const gen = await client.generateAndWait(request, { timeoutMs: SMART_WAIT_MS });
-            return completedResult(gen);
+            return completedResult(gen, await attachmentsFor(gen), [], client.baseUrl);
         }
         catch (err) {
             // A SUBMITTED generation is running and charged. Whether the wait timed out or a
@@ -652,12 +1075,13 @@ export function registerTools(server, opts) {
             // dropping it invites a retry that generates and charges a second time.
             const pending = pendingOutputId(err);
             if (pending)
-                return pendingResult(pending);
+                return pendingResult(pending, pollAfterSecondsFor('image'), pendingShapeFrom(args, 'image'));
             return errorResult(err);
         }
     });
     // -- generate_lip_sync ----------------------------------------------------
     server.registerTool('generate_lip_sync', {
+        ...RENDERS_GENERATION,
         title: 'Generate Lip Sync',
         annotations: WRITE,
         description: 'Animate a portrait image so the subject speaks. Provide imageUrl (the face) plus a voice source: either audioUrl (an existing speech clip) or script + voiceId (we synthesize the speech). Optional motionPrompt nudges expression/motion. Waits up to ~50s; if still rendering it returns an outputId to poll with get_generation_status. SPENDS CREDITS: pass getCost to preview the price first, which runs nothing and charges nothing.',
@@ -705,7 +1129,7 @@ export function registerTools(server, opts) {
             if (args.getCost)
                 return costResult(await client.estimateCost(request));
             const gen = await client.generateAndWait(request, { timeoutMs: SMART_WAIT_MS });
-            return completedResult(gen);
+            return completedResult(gen, await attachmentsFor(gen), [], client.baseUrl);
         }
         catch (err) {
             // A SUBMITTED generation is running and charged. Whether the wait timed out or a
@@ -713,13 +1137,20 @@ export function registerTools(server, opts) {
             // dropping it invites a retry that generates and charges a second time.
             const pending = pendingOutputId(err);
             if (pending)
-                return pendingResult(pending);
+                return pendingResult(pending, pollAfterSecondsFor('video'), pendingShapeFrom(args, 'video'));
             return errorResult(err);
         }
     });
     // -- transcribe -----------------------------------------------------------
     server.registerTool('transcribe', {
         title: 'Transcribe Audio',
+        /*
+          ⭐ ANNOTATED, NOT JUST ARGUED FOR. The comment below has said "NOT read-only" since this tool
+          shipped, and nobody ever wrote the annotation, so the tool went out carrying NEITHER hint. Claude
+          files an unannotated tool under "Other", which is how 2 of 88 ended up unclassified: a comment
+          describing an enforcement nobody built reads exactly like one that was built.
+        */
+        annotations: WRITE,
         // NOT read-only, despite only returning text. readOnlyHint is a host's signal that a
         // tool is safe to call without asking the user, and this one is metered per minute of
         // audio: annotated READ, an agent could transcribe a two-hour file repeatedly,
@@ -1460,7 +1891,9 @@ export function registerTools(server, opts) {
             // Image blocks are an MCP-layer concern: fetch the resolver-chosen still
             // (imageUrl) for each item that has one (images + video posters). audio /
             // transcript / posterless items stay text-only. See get-context §9.5.
-            const images = await Promise.all(result.items.map((it) => it.ok && it.imageUrl ? fetchMediaImageBase64(it.imageUrl) : Promise.resolve(null)));
+            // ⚠️ Ten items at 840 KB each is 8 MB against a 1 MB ceiling, and this used to fetch them all in
+            // parallel with no bound. One shared budget, spent in order.
+            const images = await inlineImagesWithinBudget(result.items.map((it) => (it.ok ? it.imageUrl : null)));
             return mediaBatchResult(result, images);
         }
         catch (err) {
@@ -1700,6 +2133,7 @@ export function registerTools(server, opts) {
     });
     // -- get_generation_status ------------------------------------------------
     server.registerTool('get_generation_status', {
+        ...RENDERS_GENERATION,
         title: 'Get Generation Status',
         annotations: READ,
         description: "Check one or more in-progress generations (outputIds from generate_image / generate_video / upscale / generate_lip_sync / generate_board) and get their final URLs. BY DEFAULT THIS BLOCKS until they finish, up to ~50s per call, because that is almost always what you want after starting a render; if one is still running it comes back with the current status and a poll_after_seconds hint, so call again. Pass wait:false for an instant snapshot with no blocking. Accepts 1-8 outputIds in one call.",
@@ -1738,7 +2172,12 @@ export function registerTools(server, opts) {
                     }
                 }
             }));
-            return generationBatchResult(gens);
+            // ⭐ Only the single-generation case is attached: a batch of ten would embed ten sets of bytes into
+            // one result. Polling ONE generation is the case a person is watching, and the one worth rendering.
+            const attachments = gens.length === 1 && gens[0]
+                ? { [gens[0].outputId]: await attachmentsFor(gens[0]) }
+                : {};
+            return generationBatchResult(gens, attachments, client.baseUrl);
         }
         catch (err) {
             return errorResult(err);
@@ -2496,19 +2935,44 @@ export function registerTools(server, opts) {
         inputSchema: {
             projectId: z.string().optional().describe('Scope to a specific project (editor/canvas). Omit for the user\'s most-recent-active surface anywhere. Required for render when no session is live.'),
             capture: z.boolean().optional().describe("Also return a screenshot of the user's live viewport (their SCREEN), captured at read time. Default false returns structured context only. Request it only when the task depends on seeing the live, as-shown state including unsaved UI. To see the composed OUTPUT rather than the screen, use render instead."),
-            render: z.boolean().optional().describe('Also return an inline render (image[s]) of your work, so you can visually verify edits. Ephemeral, stored nowhere, counts against no quota, works without a live tab. render=true alone renders the current focus point as a still. Use mode=filmstrip for several frames across a range. Use this to check your work, not export_project. To watch a RAW source clip use get_media with a video item; for a composed VIDEO of a range use create_preview.'),
-            mode: z.enum(['still', 'filmstrip']).optional().describe("Render tier (inferred from the params if omitted): 'still' = one composed editor frame / canvas slide; 'filmstrip' = several composed frames across an editor range (judge motion / flow / cut placement)."),
-            frame: z.number().int().min(0).optional().describe('still (editor): which timeline frame to render. Omit to render the current playhead frame.'),
-            slideId: z.string().optional().describe('still (canvas): the id of the slide to render. Omit to render the focused slide.'),
-            slideIndex: z.number().int().min(1).optional().describe('still (canvas): the 1-based slide index to render (alternative to slideId).'),
-            fromFrame: z.number().int().min(0).optional().describe('filmstrip: start timeline frame of the range. Omit to start at the beginning.'),
-            toFrame: z.number().int().min(0).optional().describe('filmstrip: end timeline frame of the range. Omit to run to the end.'),
-            count: z.number().int().min(1).optional().describe('filmstrip: how many frames to return. Omit for a proportional default.'),
-            width: z.number().int().min(48).max(1440).optional().describe('still: render at an explicit DISPLAY width in pixels, to judge legibility at the size the output will actually be seen (a course tile, a thumbnail, a feed card) rather than at full resolution, where small type always looks fine. Height follows the composition aspect ratio and is not settable. Clamped; the size produced is reported back on rendered.'),
+            render: z.boolean().optional().describe('Also render your work so you can visually verify edits. Ephemeral, stored nowhere, counts against no quota, works without a live tab. render=true alone renders the current focus point as one image; add count with fromFrame/toFrame for several across a range; mode=video returns a short playable clip of that range. Use this to check your work, not export_project, which produces a file the user KEEPS. To watch a RAW source clip instead of your composition, use get_media with a video item.'),
+            mode: z.enum(['image', 'video']).optional().describe("What MEDIUM to render (default 'image'). 'image' returns composed frames INLINE: one by default, or several across a range when you pass count with fromFrame/toFrame, to judge motion, flow and cut placement. 'video' returns the range actually playing, as a short low-res composed clip, for timing a cut or a beat that separate frames cannot show; it is a JOB, returning a renderId to poll with get_preview, because it has to be rendered."),
+            frame: z.number().int().min(0).optional().describe("mode='image' (editor): which single timeline frame to render. Omit to render the current playhead frame."),
+            slideId: z.string().optional().describe("mode='image' (canvas): the id of the slide to render. Omit to render the focused slide."),
+            slideIndex: z.number().int().min(1).optional().describe("mode='image' (canvas): the 1-based slide index to render (alternative to slideId)."),
+            fromFrame: z.number().int().min(0).optional().describe('Start timeline frame of the range, for several frames or a video. Omit to start at the beginning.'),
+            toFrame: z.number().int().min(0).optional().describe('End timeline frame of the range. Omit to run to the end.'),
+            count: z.number().int().min(1).optional().describe("mode='image': how many frames to return across the range. Omit for one frame at the focus point, or a proportional default when a range is given."),
+            width: z.number().int().min(48).max(1440).optional().describe("mode='image': render at an explicit DISPLAY width in pixels, to judge legibility at the size the output will actually be seen (a course tile, a thumbnail, a feed card) rather than at full resolution, where small type always looks fine. Height follows the composition aspect ratio and is not settable. Clamped; the size produced is reported back on rendered."),
         },
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
+            /*
+              ⭐⭐⭐ **`video` IS THE THIRD RUNG OF THIS LADDER, NOT A SEPARATE TOOL.** It used to be
+              `create_preview`, and the split was drawn on HOW the render is delivered (a job, not inline)
+              rather than on WHAT the caller is asking for. Both answers to "let me look at my own work,
+              ephemerally, without producing a deliverable" now live behind one question.
+    
+              ⛔ THE EVIDENCE THE OLD BOUNDARY WAS WRONG WAS IN THE DESCRIPTIONS. `get_context` ended with
+              "for a composed VIDEO of a range use create_preview" and `create_preview` ended with "to see a
+              single frame or a few frames use get_context render". Two tools each telling the agent when to
+              use the other is routing work the schema should be doing. The CLI had already reached this
+              conclusion: it exposes `context preview`, a sibling of `context`, while export lives under
+              `project`.
+    
+              ⚠️ THE TRANSPORT IS UNCHANGED. This is a facade over the same client call the old tool made, so
+              nothing moved server-side and the SDK needed no new field.
+            */
+            if (args.mode === 'video') {
+                const job = await client.createPreview({
+                    projectId: args.projectId ?? '',
+                    fromFrame: args.fromFrame,
+                    toFrame: args.toFrame,
+                });
+                return text(`Preview render started (frames ${job.fromFrame}-${job.toFrame}, ~${job.durationSeconds}s).\n` +
+                    `Poll get_preview with renderId="${job.renderId}" and bucketName="${job.bucketName}" until status is "done", then fetch the returned url.`);
+            }
             const result = await client.getContext({
                 projectId: args.projectId,
                 capture: args.capture,
@@ -2530,37 +2994,13 @@ export function registerTools(server, opts) {
             return errorResult(err);
         }
     });
-    server.registerTool('create_preview', {
-        title: 'Create Preview',
-        // NOT read-only. It does not charge the caller's credits (unlike transcribe), but it
-        // STARTS A RENDER JOB: it returns a renderId you then poll, which is state that did
-        // not exist before the call. readOnlyHint says a tool does not modify its
-        // environment, and dispatching a Lambda render does. get_preview, which only reads
-        // that job, stays READ.
-        description: "Create an async PREVIEW of your work (ephemeral, never stored, not a deliverable). Currently a short low-res COMPOSED VIDEO of an editor range, so you can assess motion, cuts, transitions, and pacing that a still cannot show. This is a JOB: it returns a renderId + bucketName; poll get_preview with those until it is done, then fetch the returned url. To see a single frame or a few frames instead (cheaper, instant), use get_context render. Requires the context:read scope.",
-        inputSchema: {
-            projectId: z.string().describe('The editor project to preview.'),
-            fromFrame: z.number().int().min(0).optional().describe('Start timeline frame of the range. Omit to start at the beginning.'),
-            toFrame: z.number().int().min(0).optional().describe('End timeline frame. Omit to run to the end (capped to a short preview length).'),
-        },
-    }, async (args, extra) => {
-        try {
-            const client = await getClient(extra);
-            const job = await client.createPreview({ projectId: args.projectId, fromFrame: args.fromFrame, toFrame: args.toFrame });
-            return text(`Preview render started (frames ${job.fromFrame}-${job.toFrame}, ~${job.durationSeconds}s).\n` +
-                `Poll get_preview with renderId="${job.renderId}" and bucketName="${job.bucketName}" until status is "done", then fetch the returned url.`);
-        }
-        catch (err) {
-            return errorResult(err);
-        }
-    });
     server.registerTool('get_preview', {
         title: 'Get Preview',
         annotations: READ,
-        description: 'Poll a preview started with create_preview. While rendering, returns the progress; when done, returns a short-lived url to the ephemeral preview output (plus the estimated cost). Requires the context:read scope.',
+        description: 'Poll a preview started by get_context with mode="video". While rendering, returns the progress; when done, returns a short-lived url to the ephemeral preview output (plus the estimated cost). Requires the context:read scope.',
         inputSchema: {
-            renderId: z.string().describe('The renderId returned by create_preview.'),
-            bucketName: z.string().describe('The bucketName returned by create_preview.'),
+            renderId: z.string().describe('The renderId returned by get_context with mode="video".'),
+            bucketName: z.string().describe('The bucketName returned by get_context with mode="video".'),
         },
     }, async (args, extra) => {
         try {