@chrischall/gemini-mcp 1.0.4 → 1.2.0

package/dist/tools/files.js

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { withProgressHeartbeat } from './shared.js';
+import { base64ToBytes, wholeMb } from '../bytes.js';
+import { fileNameFromUrl } from '../fetch-image.js';
+import { previewUnlessConfirmed, previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
+/**
+ * First-class Gemini Files API access.
+ *
+ * The problem these solve: on a hosted connector there is no filesystem, so the
+ * only way to hand over a picture used to be `images_base64` — and a base64
+ * JPEG is ~14k tokens of the model's context window per photo, corrupted
+ * outright whenever the file read that produced it was truncated. A Files API
+ * reference is a 20-character string that any number of later calls can reuse.
+ *
+ * Three ways in, none of which put bytes in the conversation:
+ *
+ *  - `gemini_upload_file` with `url` — the SERVER downloads it.
+ *  - `POST /upload` on the connector with the raw bytes as the request body —
+ *    the intended path for an agent with a shell (see README).
+ *  - `gemini_upload_file` with `path` — stdio only, reads the local file.
+ *
+ * `data_base64` exists as a deliberate last resort: it is the one form that
+ * *does* cost context, and it is documented as such.
+ *
+ * Uploads are retained ~48h. After that the uri stops resolving — which,
+ * unhelpfully, surfaces as the same generic 404 an unknown model id produces
+ * (see `ChainedRequest404Error` in client.ts), so the expiry is stated
+ * everywhere a uri is returned.
+ */
+/**
+ * A `url` upload is buffered whole before being forwarded (fetched bytes, then
+ * a Blob copy of them), so the cap has to be one the runtime can actually hold
+ * — an advertised limit that fails as an OOM is worse than a smaller honest
+ * one. A Cloudflare isolate gets 128MB total, hence the much lower hosted
+ * figure; Node has no comparable ceiling.
+ *
+ * `POST /upload` is unaffected: it streams, and is bounded only by the Files
+ * API's own 2 GB cap.
+ */
+const UPLOAD_URL_MAX_BYTES_DISK = 100 * 1024 * 1024;
+const UPLOAD_URL_MAX_BYTES_HOSTED = 25 * 1024 * 1024;
+/** What a `url` upload will accept: the media the Files API is useful for. */
+const UPLOAD_ACCEPT = ['image/', 'video/', 'audio/'];
+const RETENTION_NOTE = 'Gemini retains uploaded files for ~48h. Until then this reference can be reused across any number of calls ' +
+    '(images_file_uris on gemini_image_generate / _edit / _set / gemini_interact, or video_url) without re-sending the bytes.';
+/** Shape returned by every upload path. */
+function uploadResult(file) {
+    return textResult({
+        // The `files/<id>` form is what every tool parameter documents, so it leads.
+        file_uri: file.name,
+        // The absolute uri, for callers that would rather pass it through verbatim.
+        uri: file.uri,
+        name: file.name,
+        mime_type: file.mimeType,
+        ...(file.sizeBytes ? { size_bytes: Number(file.sizeBytes) } : {}),
+        ...(file.displayName ? { display_name: file.displayName } : {}),
+        expires: file.expirationTime ?? '~48h from upload',
+        hint: `Pass "${file.name}" in images_file_uris (or video_url for video) on any image tool. ${RETENTION_NOTE}`,
+    });
+}
+export function registerFileTools(server, client) {
+    const onDisk = client.mediaSink?.persistsFiles ?? true;
+    const urlMaxBytes = onDisk ? UPLOAD_URL_MAX_BYTES_DISK : UPLOAD_URL_MAX_BYTES_HOSTED;
+    server.registerTool('gemini_upload_file', {
+        description: 'Upload an image (or video/audio) to the Gemini Files API ONCE and get back a reusable `files/<id>` reference. ' +
+            'Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever ' +
+            'enter the conversation, and it can be reused across many generations until it expires (~48h). ' +
+            'Provide exactly one of `url` (the server downloads it), `data_base64`' +
+            (onDisk ? ', or `path` (a local file).' : '.') +
+            (onDisk
+                ? ''
+                : ' This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header ' +
+                    'and a Content-Type of image/*, which avoids base64 entirely.'),
+        annotations: { readOnlyHint: false, openWorldHint: true },
+        inputSchema: {
+            url: z
+                .string()
+                .url()
+                .optional()
+                .describe(`Public https URL the SERVER downloads and uploads (image/video/audio, up to ${wholeMb(urlMaxBytes)}MB). ` +
+                'No bytes pass through the conversation.' +
+                (onDisk ? '' : ' Larger files: POST the raw bytes to /upload, which streams instead of buffering.')),
+            data_base64: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Raw base64 or a data: URI. Last resort — this is the one form that costs model context (~14k tokens for a modest JPEG).'),
+            path: z
+                .string()
+                .min(1)
+                .optional()
+                .describe(onDisk
+                ? 'Path to a local file (absolute, or resolved against $GEMINI_INPUT_DIR). Confirm-gated like every other local-file input.'
+                : 'Unavailable on this hosted connector (no filesystem) — use `url`, `data_base64`, or POST /upload.'),
+            mime_type: z
+                .string()
+                .regex(/^[\w.+-]+\/[\w.+-]+$/, 'must be a MIME type like image/png')
+                .optional()
+                .describe('Override the detected MIME type (sniffed from the bytes / taken from the server response otherwise)'),
+            display_name: z.string().min(1).optional().describe('Human-readable name recorded against the upload'),
+            confirm: schemaConfirm,
+        },
+    }, async (args, extra) => {
+        const sources = [args.url && 'url', args.data_base64 && 'data_base64', args.path && 'path'].filter(Boolean);
+        if (sources.length !== 1) {
+            throw new McpToolError(sources.length === 0
+                ? 'Provide exactly one of `url`, `data_base64`' + (onDisk ? ' or `path`.' : '.')
+                : `Provide exactly one source, not ${sources.length} (${sources.join(', ')}).`);
+        }
+        if (args.path) {
+            if (!onDisk) {
+                throw new McpToolError('`path` is unavailable on the hosted connector: it runs on a Cloudflare Worker, which has no filesystem. ' +
+                    'Use `url` (the server downloads it), `data_base64`, or POST the raw bytes to /upload with the same Authorization header.', { hint: 'Use `url`, `data_base64`, or POST /upload.' });
+            }
+            // Same gate as every other local-file input: a prompt-injected `path`
+            // would otherwise ship an arbitrary local file to Google, and an
+            // uploaded file is readable by anyone holding the api key for ~48h.
+            const gate = await previewLocalInputsUnlessConfirmed(args.confirm, 'Upload a local file to the Gemini Files API', '/upload/v1beta/files', [args.path]);
+            if (gate)
+                return gate;
+        }
+        const uploaded = await withProgressHeartbeat(extra, 'Uploading to the Gemini Files API', async () => {
+            if (args.url) {
+                const fetched = await client.fetchRemoteImage(args.url, { maxBytes: urlMaxBytes, accept: UPLOAD_ACCEPT });
+                return client.uploadBytes(fetched.bytes, args.mime_type ?? fetched.mimeType, 
+                // 'upload', matching the data_base64 and path branches below —
+                // this tool takes video and audio too, so 'image' would be a lie.
+                args.display_name ?? fileNameFromUrl(args.url, 'upload'));
+            }
+            if (args.data_base64) {
+                const { decodeImageInput } = await import('../images.js');
+                const decoded = decodeImageInput(args.data_base64);
+                const bytes = base64ToBytes(decoded.base64);
+                return client.uploadBytes(bytes, args.mime_type ?? decoded.mimeType, args.display_name ?? 'upload');
+            }
+            const { readImageAsInline, resolveImagePath } = await import('../images.js');
+            const resolved = resolveImagePath(args.path);
+            const inline = await readImageAsInline(resolved);
+            const bytes = base64ToBytes(inline.base64);
+            return client.uploadBytes(bytes, args.mime_type ?? inline.mimeType, args.display_name ?? (resolved.split(/[\\/]/).pop() || 'upload'));
+        });
+        return uploadResult(uploaded);
+    });
+    server.registerTool('gemini_list_files', {
+        description: 'List the files currently uploaded to the Gemini Files API under this API key, with their `files/<id>` references, ' +
+            'MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.',
+        annotations: { readOnlyHint: true, openWorldHint: true },
+        inputSchema: {
+            page_size: z.number().int().positive().max(100).optional().describe('Maximum files to return (1-100, default 100)'),
+        },
+    }, async (args) => {
+        const files = await client.listFiles(args.page_size ?? 100);
+        return textResult({
+            count: files.length,
+            files: files.map((f) => ({
+                file_uri: f.name,
+                uri: f.uri,
+                mime_type: f.mimeType,
+                ...(f.displayName ? { display_name: f.displayName } : {}),
+                ...(f.sizeBytes ? { size_bytes: Number(f.sizeBytes) } : {}),
+                ...(f.state ? { state: f.state } : {}),
+                ...(f.createTime ? { created: f.createTime } : {}),
+                ...(f.expirationTime ? { expires: f.expirationTime } : {}),
+            })),
+            hint: files.length
+                ? `Pass any file_uri above in images_file_uris on an image tool. ${RETENTION_NOTE}`
+                : 'No files uploaded (or all have expired — retention is ~48h). Upload one with gemini_upload_file.',
+        });
+    });
+    server.registerTool('gemini_delete_file', {
+        description: 'Delete an uploaded file from the Gemini Files API before its ~48h expiry. Any tool call still referencing it ' +
+            'will then fail with a generic 404, so delete only references you are finished with.',
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        inputSchema: {
+            file_uri: z.string().min(1).describe('The `files/<id>` reference (or full uri) to delete'),
+            confirm: schemaConfirm,
+        },
+    }, async (args) => {
+        // Deleting is a remote mutation with no undo — confirm-gated per the
+        // fleet convention (unlike writing a generated image, which is local).
+        const gate = previewUnlessConfirmed(args.confirm, 'Delete an uploaded Gemini file', 'DELETE', `/v1beta/${args.file_uri}`);
+        if (gate)
+            return gate;
+        await client.deleteFile(args.file_uri);
+        return textResult({ deleted: args.file_uri });
+    });
+}

package/dist/tools/generate.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
-import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
+import { readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
-import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { slugify, baseName } from '../images.js';
+import { resolveImageInputs, requireImageInput } from '../inputs.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const GENERATE_ENDPOINT = '/v1beta/models/{model}:generateContent';
@@ -21,7 +22,9 @@ export function registerGenerateTools(server, client) {
             count: z.number().int().positive().max(8).optional().describe('Number of independent images (default 1)'),
             filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
             images: z.array(z.string().min(1)).optional().describe('Paths to reference input images (image-conditioned generation)'),
-            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs'),
+            images_url: imagesUrlSchema(),
+            images_file_uris: imagesFileUrisSchema(),
+            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
             video_url: z.string().url().optional().describe('Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
             video_path: videoPathSchema,
             confirm: schemaConfirm,
@@ -46,12 +49,15 @@ export function registerGenerateTools(server, client) {
             model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search, count,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
+            images_url: args.images_url, images_file_uris: args.images_file_uris,
             video_url: args.video_url, video_path: args.video_path,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_image_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const seed = pickSeed(args.seed);
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
-            const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            // Resolved ONCE, before the count loop: a URL is fetched (and a large
+            // one uploaded) a single time no matter how many images are generated.
+            const { inputs: refInputs, report } = await withProgressHeartbeat(extra, 'Resolving reference images', () => resolveImageInputs(args, client));
             // Upload ONCE (before the count loop) — every generate call references
             // the same files/… uri.
             const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args, client));
@@ -90,6 +96,8 @@ export function registerGenerateTools(server, client) {
                 meta.text = capturedText;
             if (capturedGrounding)
                 meta.grounding = capturedGrounding;
+            if (report)
+                meta.image_inputs = report;
             if (video.videoFileMeta)
                 meta.video_file = video.videoFileMeta;
             meta.hint = REFINE_HINT;
@@ -108,18 +116,16 @@ export function registerGenerateTools(server, client) {
         inputSchema: {
             prompt: z.string().min(1).describe('Instruction describing the edit or composition'),
             images: z.array(z.string().min(1)).optional().describe('Paths to input image file(s) (1 = edit, 2+ = compose)'),
-            images_base64: z.array(z.string().min(1)).optional().describe('Input images as base64 strings or data URIs'),
+            images_url: imagesUrlSchema('Input images'),
+            images_file_uris: imagesFileUrisSchema('Input images'),
+            images_base64: z.array(z.string().min(1)).optional().describe('Input images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
             filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
             confirm: schemaConfirm,
             ...sharedImageSchema,
         },
     }, async (args, extra) => {
         assertLocalInputsAvailable(client.mediaSink, args);
-        const hasPaths = (args.images?.length ?? 0) > 0;
-        const hasBase64 = (args.images_base64?.length ?? 0) > 0;
-        if (!hasPaths && !hasBase64 && !args.from_clipboard) {
-            throw new McpToolError('Provide at least one input image via `images`, `images_base64`, or `from_clipboard`.');
-        }
+        requireImageInput(args);
         // Confirm-gate local file inputs (see gemini_image_generate). base64 /
         // clipboard inputs are not local-path reads and pass through ungated.
         const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images);
@@ -130,11 +136,12 @@ export function registerGenerateTools(server, client) {
             model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
+            images_url: args.images_url, images_file_uris: args.images_file_uris,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_image_edit', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const seed = pickSeed(args.seed);
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
-            const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            const { inputs, report } = await withProgressHeartbeat(extra, 'Resolving input images', () => resolveImageInputs(args, client));
             const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client.generate({
                 prompt: args.prompt,
                 images: inputs,
@@ -152,6 +159,8 @@ export function registerGenerateTools(server, client) {
                 meta.text = text;
             if (result.grounding)
                 meta.grounding = result.grounding;
+            if (report)
+                meta.image_inputs = report;
             meta.hint = REFINE_HINT;
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: client.mediaSink?.persistsFiles });
             if (risk)

package/dist/tools/interact.js

@@ -2,9 +2,10 @@ import { z } from 'zod';
 import { McpToolError, ApiError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { ChainedRequest404Error } from '../client.js';
-import { slugify, baseName, gatherImageInputs, resolveImagePath, writeSidecar, resolveOutputDir, readImageAsInline } from '../images.js';
+import { slugify, baseName, resolveImagePath, writeSidecar, resolveOutputDir, readImageAsInline } from '../images.js';
+import { resolveImageInputs } from '../inputs.js';
 import { findInteractionImages, latestInteractionId } from '../sidecar.js';
-import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 // The last-interaction id and the written-outputs set used to live here, at
@@ -19,7 +20,7 @@ const NEW_REFERENCES_ONLY = 'NEW reference images only (e.g. a style or target p
 /**
  * On a chained call, split `images` into genuinely new references vs paths
  * this server itself generated (which the interaction already contains).
- * Unresolvable paths are kept so `gatherImageInputs` surfaces its usual error.
+ * Unresolvable paths are kept so `resolveImageInputs` surfaces its usual error.
  */
 function splitReattachedOutputs(images, writtenOutputs) {
     const kept = [];
@@ -73,10 +74,13 @@ export function registerInteractTools(server, client) {
                 .array(z.string().min(1))
                 .optional()
                 .describe(`Paths to reference input images. ${NEW_REFERENCES_ONLY}`),
+            images_url: imagesUrlSchema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
+            images_file_uris: imagesFileUrisSchema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
             images_base64: z
                 .array(z.string().min(1))
                 .optional()
-                .describe(`Reference images as base64 strings or data URIs. ${NEW_REFERENCES_ONLY}`),
+                .describe(`Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, ` +
+                `which keep image bytes out of the conversation. ${NEW_REFERENCES_ONLY}`),
             model: z
                 .string()
                 .optional()
@@ -171,10 +175,11 @@ export function registerInteractTools(server, client) {
             thinking_level: args.thinking_level, previous_interaction_id: previousInteractionId,
             google_search: args.google_search, search_types: args.search_types,
             images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
+            images_url: args.images_url, images_file_uris: args.images_file_uris,
             video_url: args.video_url, video_path: args.video_path,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_interact', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
-            const inputs = await gatherImageInputs({ images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            const { inputs, report } = await resolveImageInputs({ ...args, images }, client);
             const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args, client));
             const callOpts = {
                 input: args.input,
@@ -254,6 +259,8 @@ export function registerInteractTools(server, client) {
                 meta.text = r.text;
             if (r.grounding)
                 meta.grounding = r.grounding;
+            if (report)
+                meta.image_inputs = report;
             if (video.videoFileMeta)
                 meta.video_file = video.videoFileMeta;
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: onDisk });

package/dist/tools/music.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { McpToolError } from '@chrischall/mcp-utils';
-import { slugify, baseName, gatherImageInputs } from '../images.js';
+import { slugify, baseName } from '../images.js';
+import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_MUSIC_MODEL } from '../models.js';
-import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const MUSIC_MODELS = ['lyria-3-clip-preview', 'lyria-3-pro-preview'];
@@ -26,7 +27,9 @@ export function registerMusicTools(server, client) {
             model: z.enum(MUSIC_MODELS).optional().describe(`Lyria model (default: ${DEFAULT_MUSIC_MODEL}). Pro is longer-form and supports WAV.`),
             audio_format: z.enum(AUDIO_FORMATS).optional().describe('Output format (default mp3). wav is lyria-3-pro-preview-only.'),
             images: z.array(z.string().min(1)).optional().describe('Optional reference image path(s) to condition the music'),
-            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs'),
+            images_url: imagesUrlSchema('Reference images'),
+            images_file_uris: imagesFileUrisSchema('Reference images'),
+            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
             from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS clipboard as a reference'),
             filename: z.string().optional().describe('Base filename for the output audio (extension stripped; default: slugified prompt)'),
             output_dir: z.string().optional().describe('Directory to write audio to (default: $GEMINI_OUTPUT_DIR or cwd)'),
@@ -61,10 +64,11 @@ export function registerMusicTools(server, client) {
         const fingerprint = fingerprintRequest('gemini_music_generate', {
             model, prompt: args.prompt, audio_format: args.audio_format,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
+            images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
-            const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            const { inputs, report } = await resolveImageInputs(args, client);
             const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client.generateMusic({
                 input: args.prompt,
                 images: inputs.length ? inputs : undefined,
@@ -79,6 +83,8 @@ export function registerMusicTools(server, client) {
                 meta.previous_interaction_id = previousInteractionId;
             if (r.text)
                 meta.text = r.text;
+            if (report)
+                meta.image_inputs = report;
             meta.hint = `To continue this track, call gemini_music_generate again with previous_interaction_id: "${r.id}" (or continue_last: true).`;
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
             const named = r.audios.map((media, i) => ({

package/dist/tools/set.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
-import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { slugify, baseName } from '../images.js';
+import { resolveImageInputs } from '../inputs.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerSetTools(server, client) {
@@ -16,7 +17,9 @@ export function registerSetTools(server, client) {
             reference_mode: z.enum(['master', 'chain']).optional().describe('master: every image references the master (default). chain: each references the previous.'),
             basename: z.string().optional().describe('Base filename prefix for output images (default: slugified master_prompt)'),
             master_images: z.array(z.string().min(1)).optional().describe('Reference image paths passed to the master generation call'),
-            master_images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs for master generation'),
+            master_images_url: imagesUrlSchema('Reference images passed to the master AND to every scene call (fetched once)'),
+            master_images_file_uris: imagesFileUrisSchema('Reference images passed to the master AND to every scene call'),
+            master_images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs for master generation. Last resort: prefer master_images_url or master_images_file_uris, which keep image bytes out of the conversation'),
             confirm: schemaConfirm,
             ...sharedImageSchema,
         },
@@ -37,13 +40,30 @@ export function registerSetTools(server, client) {
             reference_mode: args.reference_mode, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search,
             master_images: args.master_images, master_images_base64: args.master_images_base64, from_clipboard: args.from_clipboard,
+            master_images_url: args.master_images_url, master_images_file_uris: args.master_images_file_uris,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_image_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const seed = pickSeed(args.seed);
             const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
             const slug = args.basename ? baseName(args.basename) : slugify(args.master_prompt);
-            // 1. master (optionally seeded from reference images)
-            const masterRefInputs = await gatherImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard });
+            // 1. master (optionally seeded from reference images).
+            //
+            // Two resolutions, because the two groups have different lifetimes:
+            //
+            //  - `carried` — URL and Files API references. Fetched/uploaded ONCE for
+            //    the whole set (a URL repeated across master + N scenes is one
+            //    download, and a `files/…` reference costs nothing to repeat), and
+            //    passed to EVERY scene call, where they do the most good: they are
+            //    what keeps the subject consistent scene to scene.
+            //  - `masterOnly` — path / base64 / clipboard references. Master-only,
+            //    exactly as before these parameters existed, so pre-existing calls
+            //    still build byte-identical requests.
+            const carried = await resolveImageInputs({ images_url: args.master_images_url, images_file_uris: args.master_images_file_uris }, client);
+            const masterOnly = await resolveImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard }, client);
+            const masterRefInputs = [...masterOnly.inputs, ...carried.inputs];
+            const report = carried.report || masterOnly.report
+                ? { ...masterOnly.report, ...carried.report }
+                : undefined;
             const named = [];
             const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
                 const result = await client.generate({
@@ -62,13 +82,13 @@ export function registerSetTools(server, client) {
                 if (mode === 'chain') {
                     let ref = master;
                     for (let i = 0; i < scenePrompts.length; i++) {
-                        const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref], seed: seed + i + 1, ...cfg });
+                        const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
                         named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` });
                         ref = img;
                     }
                 }
                 else {
-                    const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
+                    const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
                     scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` }));
                 }
                 return result;
@@ -79,6 +99,8 @@ export function registerSetTools(server, client) {
                 meta.text = masterText;
             if (masterResult.grounding)
                 meta.grounding = masterResult.grounding;
+            if (report)
+                meta.image_inputs = report;
             // A set is master + N scenes in one tools/call — the most timeout-prone
             // tool. Effective image count drives the risk hint.
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client.mediaSink?.persistsFiles });

package/dist/tools/shared.js

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { textResult, McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveVideoPath, videoMimeType } from '../images.js';
+import { IMAGE_URL_MAX_BYTES } from '../fetch-image.js';
+import { wholeMb } from '../bytes.js';
 import { createDiskSink } from '../storage/media.js';
 /**
  * Fallback sink for call sites that pass no explicit one (every pre-existing
@@ -52,6 +54,31 @@ export const asyncSchema = z
     .boolean()
     .optional()
     .describe('Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion).');
+/**
+ * Reference images the SERVER fetches, so the bytes never pass through the
+ * model's context window. Defined once and reused under both the `images_url`
+ * and `master_images_url` names.
+ */
+export function imagesUrlSchema(label = 'Reference images') {
+    return z
+        .array(z.string().url())
+        .optional()
+        .describe(`${label} as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. ` +
+        'Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. ' +
+        `Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each; must be a directly-linked image (Content-Type image/*).`);
+}
+/**
+ * Reference images already in the Gemini Files API. The cheapest form there is:
+ * a short string, reusable across calls until the file expires.
+ */
+export function imagesFileUrisSchema(label = 'Reference images') {
+    return z
+        .array(z.string().min(1))
+        .optional()
+        .describe(`${label} by Gemini Files API reference ("files/<id>", or the full uri) from gemini_upload_file or POST /upload. ` +
+        'Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. ' +
+        'Files are retained ~48h, after which the reference stops resolving.');
+}
 /**
  * The model/aspect/size/output fields every generation tool shares. Defined once
  * here so descriptions can't drift between `generate.ts` and `set.ts`. Spread
@@ -271,10 +298,15 @@ export async function emit(named, opts, meta, onWritten) {
  *  - `video_path` — the Files API upload streams the file off disk.
  *
  * Called at the top of every generation handler, BEFORE any billable upstream
- * call, so a caller gets a clear "use images_base64 / video_url instead"
- * instead of an obscure module-resolution or ENOENT crash. A no-op on the disk
- * sink, so the stdio behaviour (including its own "Image not found" errors) is
- * untouched.
+ * call, so a caller gets a clear alternative instead of an obscure
+ * module-resolution or ENOENT crash. A no-op on the disk sink, so the stdio
+ * behaviour (including its own "Image not found" errors) is untouched.
+ *
+ * The remediation deliberately does NOT lead with `images_base64` any more.
+ * Inlining a photo as a tool argument costs ~14k tokens of the model's context
+ * and silently corrupts whenever the read that produced it was truncated — so
+ * it is named last, after the three routes that move bytes without the model
+ * ever seeing them.
  */
 export function assertLocalInputsAvailable(sink, args) {
     if ((sink ?? DEFAULT_SINK).persistsFiles)
@@ -293,8 +325,14 @@ export function assertLocalInputsAvailable(sink, args) {
     // Remediation goes in the MESSAGE, not just `hint`: MCP error serialization
     // surfaces the message and drops the hint, so hint-only advice is invisible
     // exactly when it is needed.
-    const fix = 'Send image bytes as `images_base64` (raw base64 or a data: URI) instead of `images`/`master_images`/`from_clipboard`, ' +
-        'and reference video by `video_url` (a public YouTube URL, or a files/… uri uploaded elsewhere) instead of `video_path`.';
+    const fix = 'Reference images WITHOUT putting bytes in the conversation, in order of preference: ' +
+        '(1) `images_url` — public https URLs the server fetches itself; ' +
+        '(2) `images_file_uris` — upload once with `gemini_upload_file` (it takes a `url` or `data_base64`) and reuse the returned files/… uri; ' +
+        '(3) `POST /upload` on this connector with the raw bytes as the body ' +
+        "(`curl -X POST <connector-url>/upload -H 'Authorization: Bearer <token>' -H 'Content-Type: image/jpeg' --data-binary @photo.jpg`), " +
+        'then pass the returned file_uri. ' +
+        'As a last resort `images_base64` still works, but it costs ~14k tokens per photo and breaks on a truncated read. ' +
+        'Reference video by `video_url` (a public YouTube URL, or a files/… uri uploaded elsewhere) instead of `video_path`.';
     throw new McpToolError(`${unavailable.join(', ')} ${unavailable.length > 1 ? 'are' : 'is'} unavailable on the hosted connector: ` +
         `it runs on a Cloudflare Worker, which has no filesystem and no local clipboard. ${fix}`, { hint: fix });
 }

package/dist/tools/video.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { McpToolError } from '@chrischall/mcp-utils';
-import { slugify, baseName, gatherImageInputs } from '../images.js';
+import { slugify, baseName } from '../images.js';
+import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_VIDEO_MODEL } from '../models.js';
-import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 /** omni's own aspect-ratio enum — NOT the image tools' ASPECT_RATIOS. */
@@ -27,7 +28,9 @@ export function registerVideoTools(server, client) {
             aspect_ratio: z.enum(VIDEO_ASPECT_RATIOS).optional().describe('Output aspect ratio (omni: 16:9 or 9:16)'),
             task: z.enum(VIDEO_TASKS).optional().describe('text_to_video (default), image_to_video / reference_to_video (need image input), or edit (needs previous_interaction_id)'),
             images: z.array(z.string().min(1)).optional().describe('Reference image path(s) for image_to_video / reference_to_video'),
-            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs'),
+            images_url: imagesUrlSchema('Reference stills'),
+            images_file_uris: imagesFileUrisSchema('Reference stills'),
+            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
             from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS clipboard as a reference'),
             filename: z.string().optional().describe('Base filename for the output video (extension stripped; default: slugified prompt)'),
             output_dir: z.string().optional().describe('Directory to write the video to (default: $GEMINI_OUTPUT_DIR or cwd)'),
@@ -63,10 +66,11 @@ export function registerVideoTools(server, client) {
         const fingerprint = fingerprintRequest('gemini_video_generate', {
             model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, task: args.task,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
+            images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
-            const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            const { inputs, report } = await resolveImageInputs(args, client);
             const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client.generateVideo({
                 input: args.prompt,
                 images: inputs.length ? inputs : undefined,
@@ -82,6 +86,8 @@ export function registerVideoTools(server, client) {
                 meta.previous_interaction_id = previousInteractionId;
             if (r.text)
                 meta.text = r.text;
+            if (report)
+                meta.image_inputs = report;
             meta.hint = `To edit this video, call gemini_video_generate again with task: "edit" and previous_interaction_id: "${r.id}" (or continue_last: true).`;
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
             const named = r.videos.map((media, i) => ({