@chrischall/gemini-mcp 1.0.3 → 1.1.0

package/dist/inputs.js

@@ -0,0 +1,186 @@
+import { McpToolError } from '@chrischall/mcp-utils';
+import { IMAGE_INLINE_MAX_BYTES } from './fetch-image.js';
+/** True when this call carries at least one image input of any kind. */
+export function hasImageInput(args) {
+    return Boolean(args.images?.length ||
+        args.images_base64?.length ||
+        args.images_url?.length ||
+        args.images_file_uris?.length ||
+        args.from_clipboard);
+}
+/** Conservative TTL when the API doesn't tell us: documented retention is ~48h. */
+const ASSUMED_TTL_MS = 47 * 60 * 60 * 1000;
+function expiresAtMs(expirationTime, now) {
+    if (expirationTime) {
+        const t = Date.parse(expirationTime);
+        if (Number.isFinite(t))
+            return t;
+    }
+    return now + ASSUMED_TTL_MS;
+}
+/**
+ * Resolve every image input a tool was given into {@link ImageInput}s.
+ *
+ * Order is stable and matches the pre-`images_url` behaviour so existing calls
+ * produce byte-identical requests: clipboard, then paths, then base64, then
+ * fetched URLs, then Files API references.
+ *
+ * A URL repeated within one call is fetched ONCE. That is what lets
+ * `gemini_image_set` hand the same reference to the master and all N scene
+ * generations without paying for N downloads (or N uploads).
+ */
+export async function resolveImageInputs(args, client) {
+    const report = {};
+    const inputs = [];
+    const onDisk = client.mediaSink?.persistsFiles ?? true;
+    // 1. clipboard (macOS, stdio only). Imported dynamically so `child_process`
+    // stays off the default path — and off the Worker's module graph entirely.
+    if (args.from_clipboard) {
+        inputs.push(await (await import('./clipboard.js')).readClipboardImage());
+    }
+    // 2. local paths — inline, unless this session has seen the same file before.
+    for (const path of args.images ?? []) {
+        inputs.push(await resolveLocalPath(path, client, onDisk, report));
+    }
+    // 3. raw base64 / data URIs
+    if (args.images_base64?.length) {
+        const { decodeImageInput } = await import('./images.js');
+        for (const b64 of args.images_base64)
+            inputs.push(decodeImageInput(b64));
+    }
+    // 4. https URLs, fetched by the server. Deduped within the call.
+    const fetched = new Map();
+    for (const url of args.images_url ?? []) {
+        const hit = fetched.get(url);
+        if (hit) {
+            inputs.push(hit);
+            continue;
+        }
+        const resolved = await resolveUrl(url, client, report);
+        fetched.set(url, resolved);
+        inputs.push(resolved);
+    }
+    // 5. Files API references — no bytes move at all.
+    const seenUris = new Map();
+    for (const ref of args.images_file_uris ?? []) {
+        const hit = seenUris.get(ref);
+        if (hit) {
+            inputs.push(hit);
+            continue;
+        }
+        const file = await client.getFile(ref);
+        const input = { uri: file.uri, mimeType: file.mimeType };
+        seenUris.set(ref, input);
+        (report.file_uris ??= []).push(file.name);
+        inputs.push(input);
+    }
+    return { inputs, report: Object.keys(report).length > 0 ? report : undefined };
+}
+/**
+ * One local path → an inline input, or a Files API reference once this session
+ * has referenced the same bytes more than once.
+ *
+ * Identity is path + mtime + size, so editing the file in place produces a new
+ * key rather than silently reusing an upload of the old content.
+ */
+async function resolveLocalPath(path, client, onDisk, report) {
+    const { readImageAsInline, resolveImagePath } = await import('./images.js');
+    // A runtime with no filesystem never gets here — `assertLocalInputsAvailable`
+    // rejects `images` before any of this — but if it somehow did, reading the
+    // file is what would fail, so keep the pre-existing error path.
+    if (!onDisk)
+        return readImageAsInline(path);
+    const { stat } = await import('node:fs/promises');
+    const resolved = resolveImagePath(path);
+    let key;
+    try {
+        const { mtimeMs, size } = await stat(resolved);
+        // NUL separator, written as the \u0000 ESCAPE and never a literal NUL
+        // byte: a literal one makes git classify this whole file as binary and
+        // stop diffing it (same trap as fingerprintRequest in jobs.ts). It cannot
+        // occur in a path, so no crafted name can straddle a field boundary.
+        key = `path\u0000${resolved}\u0000${mtimeMs}\u0000${size}`;
+    }
+    catch {
+        // Unstattable but resolvable is odd; fall back to plain inline rather than
+        // failing a call that would otherwise have worked.
+        return readImageAsInline(path);
+    }
+    const cached = client.session.cachedUpload(key);
+    if (cached)
+        return { uri: cached.uri, mimeType: cached.mimeType };
+    const references = client.session.countReference(key);
+    const inline = await readImageAsInline(resolved);
+    if (references < 2)
+        return inline;
+    // Second sighting: pay one upload now so every later reference is free.
+    // Best-effort — an upload failure must not fail a call that inline handles
+    // perfectly well.
+    try {
+        const bytes = Uint8Array.from(atob(inline.base64), (c) => c.charCodeAt(0));
+        const displayName = resolved.split(/[\\/]/).pop() || 'image';
+        const uploaded = await client.uploadBytes(bytes, inline.mimeType, displayName);
+        client.session.uploadCache.set(key, {
+            name: uploaded.name,
+            uri: uploaded.uri,
+            mimeType: uploaded.mimeType,
+            expiresAtMs: expiresAtMs(uploaded.expirationTime, Date.now()),
+        });
+        (report.auto_uploaded ??= []).push({ path: resolved, file_uri: uploaded.name, expires: uploaded.expirationTime });
+        return { uri: uploaded.uri, mimeType: uploaded.mimeType };
+    }
+    catch {
+        return inline;
+    }
+}
+/** One https URL → inline bytes, or a Files API reference when it's large. */
+async function resolveUrl(url, client, report) {
+    const fetched = await client.fetchRemoteImage(url);
+    const entry = {
+        url,
+        mime_type: fetched.mimeType,
+        bytes: fetched.size,
+    };
+    (report.fetched_urls ??= []).push(entry);
+    if (fetched.size <= IMAGE_INLINE_MAX_BYTES) {
+        return { base64: encodeBase64(fetched.bytes), mimeType: fetched.mimeType };
+    }
+    const displayName = fileNameFromUrl(url);
+    const uploaded = await client.uploadBytes(fetched.bytes, fetched.mimeType, displayName);
+    entry.file_uri = uploaded.name;
+    return { uri: uploaded.uri, mimeType: uploaded.mimeType };
+}
+/** Last path segment of a URL, for the Files API display name. */
+function fileNameFromUrl(url) {
+    try {
+        const name = new URL(url).pathname.split('/').filter(Boolean).pop();
+        return name ? decodeURIComponent(name).slice(0, 120) : 'image';
+    }
+    catch {
+        return 'image';
+    }
+}
+/**
+ * bytes → base64 without `Buffer`. `btoa` is the primitive both runtimes share
+ * (see `storage/media.ts`, which decodes the same way); chunked because
+ * `String.fromCharCode(...huge)` blows the argument limit.
+ */
+function encodeBase64(bytes) {
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+/**
+ * Guard for tools that REQUIRE at least one reference image
+ * (`gemini_image_edit`). Names every accepted param, in the order a caller
+ * should prefer them — the context-free ones first.
+ */
+export function requireImageInput(args) {
+    if (hasImageInput(args))
+        return;
+    throw new McpToolError('Provide at least one input image via `images_url` (an https URL the server fetches), `images_file_uris` ' +
+        '(from gemini_upload_file), `images` (a local path), `images_base64`, or `from_clipboard`.');
+}

package/dist/session.js

@@ -44,6 +44,43 @@ export class SessionState {
      * model against the requested edit.
      */
     writtenOutputs = new Set();
+    /**
+     * Files API uploads this session can reuse, keyed by an opaque identity
+     * string (for a local path: absolute path + mtime + size, so an edited file
+     * is a different key rather than a stale hit).
+     *
+     * Backs the stdio "referenced twice → upload once" optimization: the second
+     * time a session sends the same picture, the bytes are replaced by a
+     * `files/…` reference that costs nothing to repeat. Session-scoped, like
+     * everything else here — a uri is minted by ONE user's API key and is only
+     * readable with that key, so sharing this map across the connector's tenants
+     * would hand out references another user cannot use and this user did not
+     * create.
+     */
+    uploadCache = new Map();
+    /**
+     * How many times each identity has been referenced this session. The
+     * threshold for auto-uploading is "more than once", so the count has to
+     * outlive the call that first saw it.
+     */
+    referenceCounts = new Map();
+    /** Record a reference and return the running total (1 on first sight). */
+    countReference(key) {
+        const next = (this.referenceCounts.get(key) ?? 0) + 1;
+        this.referenceCounts.set(key, next);
+        return next;
+    }
+    /** A cached upload, or `undefined` if absent or past its Files API TTL. */
+    cachedUpload(key, now = Date.now()) {
+        const hit = this.uploadCache.get(key);
+        if (!hit)
+            return undefined;
+        if (hit.expiresAtMs <= now) {
+            this.uploadCache.delete(key);
+            return undefined;
+        }
+        return hit;
+    }
     /** Forget everything. Tests use this; nothing in `src/` calls it. */
     reset() {
         this.jobs.reset();
@@ -51,5 +88,7 @@ export class SessionState {
         this.lastMusicInteractionId = undefined;
         this.lastVideoInteractionId = undefined;
         this.writtenOutputs.clear();
+        this.uploadCache.clear();
+        this.referenceCounts.clear();
     }
 }

package/dist/tools/files.js

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { withProgressHeartbeat } from './shared.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;
+const mb = (bytes) => Math.round(bytes / (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 ${mb(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, args.display_name ?? nameFromUrl(args.url));
+            }
+            if (args.data_base64) {
+                const { decodeImageInput } = await import('../images.js');
+                const decoded = decodeImageInput(args.data_base64);
+                const bytes = Uint8Array.from(atob(decoded.base64), (c) => c.charCodeAt(0));
+                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 = Uint8Array.from(atob(inline.base64), (c) => c.charCodeAt(0));
+            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 });
+    });
+}
+/** Last path segment of a URL, for the Files API display name. */
+function nameFromUrl(url) {
+    try {
+        const name = new URL(url).pathname.split('/').filter(Boolean).pop();
+        return name ? decodeURIComponent(name).slice(0, 120) : 'upload';
+    }
+    catch {
+        return 'upload';
+    }
+}

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
@@ -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 });