@contenthero/mcp 0.4.8 → 0.4.10

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
@@ -171,19 +215,106 @@ const LINK_MIME = {
     video: 'video/mp4',
     audio: 'audio/mpeg',
 };
-function attachmentsFor(gen) {
+/**
+ * ⛔⛔⛔ **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];
-    return urls.map((uri, i) => ({
-        kind: 'link',
-        uri,
-        mimeType,
-        // Named per output so a batch reads as four distinct things rather than four copies of one name.
-        name: `${gen.outputId}${urls.length > 1 ? `-${i + 1}` : ''}.${ext}`,
-    }));
+    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:
@@ -232,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 {
@@ -255,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));
@@ -299,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;
@@ -366,6 +714,7 @@ 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. 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.',
@@ -415,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, attachmentsFor(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
@@ -423,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.',
@@ -470,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, attachmentsFor(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
@@ -478,12 +828,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_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. 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.',
@@ -571,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, attachmentsFor(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
@@ -579,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);
         }
     });
@@ -688,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.',
@@ -715,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, attachmentsFor(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
@@ -723,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.',
@@ -776,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, attachmentsFor(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
@@ -784,7 +1137,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);
         }
     });
@@ -1538,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) {
@@ -1778,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.",
@@ -1816,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);