@chrischall/gemini-mcp 1.0.4 → 1.2.0

package/dist/fetch-image.js

@@ -0,0 +1,361 @@
+import { McpToolError } from '@chrischall/mcp-utils';
+import { formatMb } from './bytes.js';
+/**
+ * Server-side fetching of `images_url` references.
+ *
+ * The point of this module is that image BYTES never travel through the model's
+ * context window. A caller hands over an `https://` URL — a few dozen tokens —
+ * and the *server* pulls the bytes down and turns them into an `inline_data`
+ * part or a Files API upload. The alternative, `images_base64`, costs roughly
+ * 14k tokens for a modest JPEG and is silently corrupted whenever a host
+ * truncates the read that produced it.
+ *
+ * Fetching a caller-supplied URL from inside the server is an SSRF primitive,
+ * and on the stdio build the server runs on the user's own machine, next to
+ * their LAN. So this is deliberately narrow:
+ *
+ *  - **https only.** `http:`, `file:`, `data:`, `gopher:` and friends are out.
+ *  - **No private/loopback/link-local destinations** — including the cloud
+ *    metadata address, the classic escalation target.
+ *  - **Redirects are followed MANUALLY**, revalidating every hop. `redirect:
+ *    'follow'` would let a public URL bounce to `http://169.254.169.254/` with
+ *    no further check, which makes the origin check theatre.
+ *  - **A hard byte cap enforced while streaming**, not from `Content-Length` —
+ *    a hostile or merely wrong server can under-report or omit it.
+ *
+ * Module scope stays side-effect-free: `src/worker.ts` reaches this file
+ * through the tool registrars, so anything executed here would run during
+ * Cloudflare isolate startup.
+ */
+/** Hard ceiling on a fetched image. Above this the URL is rejected outright. */
+export const IMAGE_URL_MAX_BYTES = 15 * 1024 * 1024;
+/**
+ * Above this an image is uploaded to the Files API and referenced by uri
+ * instead of inlined. `generateContent` caps a whole request at ~20 MB, so a
+ * couple of large inline references would fail the request itself — and a
+ * by-reference part costs nothing to repeat across calls.
+ */
+export const IMAGE_INLINE_MAX_BYTES = 6 * 1024 * 1024;
+/** Redirect hops followed before giving up. */
+const MAX_REDIRECTS = 5;
+/**
+ * Per-hop abort budget. Matches the client's default upstream timeout so a URL
+ * fetch is bounded like every other network call this server makes; callers
+ * override it with the same `timeout_ms` resolution (see `resolveTimeoutMs`).
+ */
+const DEFAULT_FETCH_TIMEOUT_MS = 60_000;
+/** Parse an IPv4 literal into its four octets, or `undefined` if it isn't one. */
+function ipv4Octets(host) {
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return undefined;
+    const octets = parts.map((p) => (/^\d{1,3}$/.test(p) ? Number(p) : NaN));
+    return octets.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? octets : undefined;
+}
+/** True for addresses that are not on the public internet. */
+function isPrivateIpv4([a, b]) {
+    if (a === 0 || a === 127)
+        return true; // this-host / loopback
+    if (a === 10)
+        return true; // RFC1918
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // RFC1918
+    if (a === 192 && b === 168)
+        return true; // RFC1918
+    if (a === 169 && b === 254)
+        return true; // link-local — includes 169.254.169.254
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // CGNAT
+    if (a === 192 && b === 0)
+        return true; // IETF protocol assignments
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // benchmarking
+    if (a >= 224)
+        return true; // multicast + reserved
+    return false;
+}
+/**
+ * Expand an IPv6 literal into its eight 16-bit groups, or `undefined` if it
+ * isn't one. Handles `::` compression and a trailing dotted-quad
+ * (`::ffff:127.0.0.1`) — the latter never comes out of `new URL`, which
+ * re-serializes it as hex, but a redirect `Location` is parsed before
+ * normalization and a human writes it that way.
+ */
+function ipv6Groups(host) {
+    if (!host.includes(':'))
+        return undefined;
+    let text = host;
+    const tail = [];
+    // A trailing dotted-quad occupies the last two groups.
+    const dotted = /:((?:\d{1,3}\.){3}\d{1,3})$/.exec(text);
+    if (dotted) {
+        const octets = ipv4Octets(dotted[1]);
+        if (!octets)
+            return undefined;
+        tail.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
+        text = text.slice(0, dotted.index);
+    }
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const parse = (part) => {
+        if (part === '')
+            return [];
+        const out = [];
+        for (const piece of part.split(':')) {
+            if (!/^[0-9a-f]{1,4}$/.test(piece))
+                return undefined;
+            out.push(parseInt(piece, 16));
+        }
+        return out;
+    };
+    const head = parse(halves[0]);
+    const rest = halves.length === 2 ? parse(halves[1]) : [];
+    if (!head || !rest)
+        return undefined;
+    const explicit = [...head, ...rest, ...tail];
+    if (halves.length === 2) {
+        if (explicit.length > 7)
+            return undefined;
+        return [...head, ...Array(8 - explicit.length).fill(0), ...rest, ...tail];
+    }
+    return explicit.length === 8 ? explicit : undefined;
+}
+/**
+ * The /96 prefixes that carry an IPv4 address in their final 32 bits, as the
+ * first six groups. A literal matching any of them is judged on the v4 address
+ * it embeds, not on the prefix.
+ *
+ * `::ffff:0:0/96` is the one that matters operationally — stacks really do
+ * resolve `[::ffff:7f00:1]` to loopback, and `new URL` normalizes
+ * `[::ffff:127.0.0.1]` into exactly that hex spelling, which is how a guard
+ * that pattern-matched the dotted form came to never fire.
+ *
+ * The rest are defense in depth: `::/96` is deprecated IPv4-compatible,
+ * `::ffff:0:0:0/96` is deprecated SIIT (RFC 2765), and `64:ff9b::/96` is the
+ * NAT64 well-known prefix (RFC 6052), which needs a translator on the network
+ * to route at all — and whose §3.1 already forbids embedding non-global v4.
+ * They are listed anyway because a function that understands one v4-carrying
+ * prefix and not its siblings is precisely the shape the original bypass had.
+ */
+const V4_BEARING_PREFIXES = [
+    [0, 0, 0, 0, 0, 0xffff], // ::ffff:0:0/96   — IPv4-mapped
+    [0, 0, 0, 0, 0, 0], //      ::/96           — IPv4-compatible (deprecated)
+    [0, 0, 0, 0, 0xffff, 0], // ::ffff:0:0:0/96 — IPv4-translated (deprecated SIIT)
+    [0x64, 0xff9b, 0, 0, 0, 0], // 64:ff9b::/96 — NAT64 well-known (RFC 6052)
+];
+/**
+ * True for IPv6 addresses that are not on the public internet.
+ *
+ * Anything carrying an IPv4 address (see {@link V4_BEARING_PREFIXES}) is
+ * decided by running that address through the same {@link isPrivateIpv4} table
+ * as a bare v4 literal — so the two guards can never disagree about whether
+ * 10.0.0.5 is private.
+ */
+function isPrivateIpv6(groups) {
+    if (groups.every((g) => g === 0))
+        return true; // ::
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return true; // ::1
+    if ((groups[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local
+    if ((groups[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique-local
+    if (V4_BEARING_PREFIXES.some((prefix) => prefix.every((g, i) => groups[i] === g))) {
+        return isPrivateIpv4([groups[6] >> 8, groups[6] & 0xff, groups[7] >> 8, groups[7] & 0xff]);
+    }
+    return false;
+}
+/**
+ * Reject a URL that isn't a plain public https endpoint. Hostname-based, so it
+ * cannot catch a public name that RESOLVES to a private address (DNS rebinding)
+ * — closing that needs resolve-then-pin, which neither Node's nor workerd's
+ * fetch exposes. It does close the direct-literal and redirect-to-metadata
+ * cases, which is what a prompt-injected URL actually reaches for.
+ */
+function assertPublicHttpsUrl(raw, requested) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new McpToolError(`Not a valid URL: ${raw}`, {
+            hint: 'images_url entries must be absolute https:// URLs.',
+        });
+    }
+    if (url.protocol !== 'https:') {
+        throw new McpToolError(`Refusing to fetch ${describeUrl(raw, requested)}: only https:// URLs are fetched (got "${url.protocol}").`, {
+            hint: 'Use an https:// URL, or send the bytes with images_base64 / gemini_upload_file.',
+        });
+    }
+    // `new URL` always brackets an IPv6 hostname, which is the reliable signal
+    // that this is a literal and not a name.
+    const rawHost = url.hostname.toLowerCase();
+    const isIpv6Literal = rawHost.startsWith('[') && rawHost.endsWith(']');
+    const host = isIpv6Literal ? rawHost.slice(1, -1) : rawHost;
+    const v4 = isIpv6Literal ? undefined : ipv4Octets(host);
+    const v6 = isIpv6Literal ? ipv6Groups(host) : undefined;
+    const blocked = isIpv6Literal
+        // Fail CLOSED on an IPv6 literal we cannot parse: a guard that allows what
+        // it does not understand is the wrong default for this control.
+        ? (v6 === undefined || isPrivateIpv6(v6))
+        : host === 'localhost' ||
+            host.endsWith('.localhost') ||
+            host.endsWith('.local') ||
+            (v4 ? isPrivateIpv4(v4) : false);
+    if (blocked) {
+        throw new McpToolError(`Refusing to fetch ${describeUrl(raw, requested)}: "${url.hostname}" is a private, loopback or link-local address, not a public host.`, { hint: 'images_url is fetched by the server, so it must point at a publicly reachable https:// image.' });
+    }
+    return url;
+}
+/**
+ * Last path segment of a URL, for the Files API display name. Cosmetic — the
+ * API keys on the resource name it returns, not on this — so an unparseable
+ * URL degrades to `fallback` rather than failing the upload.
+ *
+ * `fallback` is REQUIRED, deliberately. This function was created by merging
+ * two byte-identical copies that differed only in their default (`'image'` in
+ * `inputs.ts`, `'upload'` in `tools/files.ts`), and taking one of those
+ * defaults silently changed the other caller's behaviour — `gemini_upload_file`
+ * started naming a fallback upload "image" even for an mp4, and disagreed with
+ * the other two branches of its own handler. With no default, merging callers
+ * that disagree stops being something you can do by accident.
+ */
+export function fileNameFromUrl(url, fallback) {
+    try {
+        const name = new URL(url).pathname.split('/').filter(Boolean).pop();
+        return name ? decodeURIComponent(name).slice(0, 120) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** "<url>" — or "<url> (redirected from <requested>)" when they differ. */
+function describeUrl(current, requested) {
+    return current === requested ? current : `${current} (redirected from ${requested})`;
+}
+/** Read a response body, aborting as soon as it exceeds `maxBytes`. */
+async function readCapped(res, maxBytes, url, requested) {
+    const declared = Number(res.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        throw tooBig(url, requested, declared, maxBytes);
+    }
+    const reader = res.body?.getReader();
+    if (!reader) {
+        // No streaming body (some mocked/edge responses) — fall back to buffering,
+        // then apply the same cap. Correct, just less eager.
+        const buf = new Uint8Array(await res.arrayBuffer());
+        if (buf.byteLength > maxBytes)
+            throw tooBig(url, requested, buf.byteLength, maxBytes);
+        return buf;
+    }
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => { });
+                throw tooBig(url, requested, total, maxBytes, true);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+    }
+    return out;
+}
+/** A transport-level failure, told apart from a plain unreachable host. */
+function fetchFailure(err, current, requested, timeoutMs) {
+    const name = err?.name;
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return new McpToolError(`Fetching ${describeUrl(current, requested)} timed out after ${timeoutMs}ms.`, {
+            hint: 'The server accepted the connection but did not finish sending the image. Try a different URL, or raise timeout_ms.',
+        });
+    }
+    return new McpToolError(`Could not fetch ${describeUrl(current, requested)}: ${err instanceof Error ? err.message : String(err)}`, { hint: 'Check the URL is reachable from the server and serves the image without authentication.' });
+}
+function tooBig(url, requested, size, max, partial = false) {
+    return new McpToolError(`Image at ${describeUrl(url, requested)} is ${partial ? 'over' : ''} ${formatMb(size)}, above the ${formatMb(max)} limit for images_url.`, { hint: 'Resize or re-encode the image, or upload it yourself with gemini_upload_file and pass the returned file_uri.' });
+}
+/**
+ * Fetch one image URL server-side, validating protocol, destination, response
+ * status, content type and size. Every failure names the offending URL in the
+ * MESSAGE — MCP error serialization drops `hint`, and "one of your URLs failed"
+ * is useless when a call carried four of them.
+ */
+export async function fetchRemoteImage(requestedUrl, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const maxBytes = opts.maxBytes ?? IMAGE_URL_MAX_BYTES;
+    const accept = opts.accept ?? ['image/'];
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    let current = requestedUrl;
+    for (let hop = 0;; hop++) {
+        const url = assertPublicHttpsUrl(current, requestedUrl);
+        // One budget per hop, applied to the body read as well: aborting the signal
+        // errors the response stream, so a trickling server cannot outlast it.
+        const signal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+        let res;
+        try {
+            // Manual redirects: every hop goes back through assertPublicHttpsUrl, so
+            // a public URL cannot bounce the fetch onto the metadata service.
+            res = await doFetch(url.toString(), {
+                redirect: 'manual',
+                headers: { accept: accept.map((p) => `${p.replace(/\/$/, '')}/*`).join(', ') },
+                ...(signal ? { signal } : {}),
+            });
+        }
+        catch (err) {
+            throw fetchFailure(err, current, requestedUrl, timeoutMs);
+        }
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get('location');
+            if (!location) {
+                throw new McpToolError(`Fetching ${describeUrl(current, requestedUrl)} returned HTTP ${res.status} with no Location header.`);
+            }
+            if (hop >= MAX_REDIRECTS) {
+                throw new McpToolError(`Fetching ${requestedUrl} exceeded ${MAX_REDIRECTS} redirects (last hop: ${location}).`);
+            }
+            current = new URL(location, url).toString();
+            continue;
+        }
+        if (!res.ok) {
+            throw new McpToolError(`Fetching ${describeUrl(current, requestedUrl)} returned HTTP ${res.status} ${res.statusText || ''}`.trim(), {
+                hint: 'The URL must be publicly readable — a login page or signed-URL expiry shows up here as 401/403/404.',
+            });
+        }
+        const contentType = (res.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+        if (!accept.some((prefix) => contentType.startsWith(prefix))) {
+            const expected = accept.map((p) => `${p.replace(/\/$/, '')}/*`).join(' or ');
+            throw new McpToolError(`${describeUrl(current, requestedUrl)} is not ${accept.length === 1 && accept[0] === 'image/' ? 'an image' : 'usable media'}: ` +
+                `the server returned Content-Type "${contentType || '(none)'}", expected ${expected}.`, { hint: 'Link directly to the media file, not to the page that displays it.' });
+        }
+        let bytes;
+        try {
+            bytes = await readCapped(res, maxBytes, current, requestedUrl);
+        }
+        catch (err) {
+            // The cap is its own actionable error; anything else here is a transport
+            // failure mid-body, most usefully reported as one (including the timeout).
+            if (err instanceof McpToolError)
+                throw err;
+            throw fetchFailure(err, current, requestedUrl, timeoutMs);
+        }
+        if (bytes.byteLength === 0) {
+            throw new McpToolError(`${describeUrl(current, requestedUrl)} returned an empty body.`);
+        }
+        return { bytes, mimeType: contentType, size: bytes.byteLength, finalUrl: current, requestedUrl };
+    }
+}

package/dist/images.js

@@ -215,25 +215,6 @@ export function decodeImageInput(input) {
     const buf = Buffer.from(trimmed, 'base64');
     return { base64: trimmed, mimeType: sniffMimeBytes(buf) };
 }
-/** Load images from file paths (via readImageAsInline) and raw base64 strings (via decodeImageInput), paths first. */
-export async function loadImageInputs(paths = [], base64s = []) {
-    const fromPaths = await Promise.all(paths.map((p) => readImageAsInline(p)));
-    const fromBase64s = base64s.map((b) => decodeImageInput(b));
-    return [...fromPaths, ...fromBase64s];
-}
-/**
- * Aggregate image inputs from all sources: clipboard (macOS only), file paths, and base64 strings.
- * Clipboard image is prepended if `from_clipboard` is true.
- */
-export async function gatherImageInputs(opts) {
-    // Only load the clipboard module when actually requested (keeps the child_process
-    // path off the default code path).
-    const clipboardImages = opts.from_clipboard
-        ? [await (await import('./clipboard.js')).readClipboardImage()]
-        : [];
-    const fileImages = await loadImageInputs(opts.images, opts.images_base64);
-    return [...clipboardImages, ...fileImages];
-}
 /** Caller-supplied filename → safe base name (no extension). */
 export function baseName(name) {
     // Strip a known media extension (image / video / audio) so writeMedia doesn't

package/dist/index.js

@@ -9,6 +9,7 @@ import { registerInteractTools } from './tools/interact.js';
 import { registerVideoTools } from './tools/video.js';
 import { registerMusicTools } from './tools/music.js';
 import { registerJobTools } from './tools/jobs.js';
+import { registerFileTools } from './tools/files.js';
 import { client } from './client.js';
 // Load `.env` here rather than in client.ts, which the Cloudflare Worker
 // imports: `import.meta.url` + async I/O at module scope crashes the isolate at
@@ -30,6 +31,6 @@ await runMcp({
     name: 'gemini-mcp',
     version: VERSION,
     banner: '[gemini-mcp] This project was developed and is maintained by AI (Claude). Use at your own discretion.',
-    tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerVideoTools, registerMusicTools, registerJobTools],
+    tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerVideoTools, registerMusicTools, registerJobTools, registerFileTools],
     deps: client,
 });

package/dist/inputs.js

@@ -0,0 +1,165 @@
+import { McpToolError } from '@chrischall/mcp-utils';
+import { IMAGE_INLINE_MAX_BYTES, fileNameFromUrl } from './fetch-image.js';
+import { base64ToBytes, bytesToBase64 } from './bytes.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 = base64ToBytes(inline.base64);
+        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: bytesToBase64(fetched.bytes), mimeType: fetched.mimeType };
+    }
+    // 'image' here: this path is `images_url`, which only ever carries images.
+    const displayName = fileNameFromUrl(url, 'image');
+    const uploaded = await client.uploadBytes(fetched.bytes, fetched.mimeType, displayName);
+    entry.file_uri = uploaded.name;
+    return { uri: uploaded.uri, mimeType: uploaded.mimeType };
+}
+/**
+ * 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/storage/media.js

@@ -11,6 +11,7 @@
  * is a thin wrapper over the pre-existing `resolveOutputDir` + `writeMedia`
  * behaviour and must stay byte-for-byte equivalent to it.
  */
+import { base64ToBytes } from '../bytes.js';
 /**
  * The stdio sink: `resolveOutputDir(output_dir)` → `writeMedia` per item, in
  * order (so `uniquePath`'s `name`/`name-2`/`name-3` sequencing is preserved).
@@ -69,7 +70,7 @@ export function createR2Sink(bucket, opts) {
             const refs = [];
             for (const it of items) {
                 const key = `${prefix}/${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;
-                const bytes = decodeBase64(it.base64);
+                const bytes = base64ToBytes(it.base64);
                 await bucket.put(key, bytes, { httpMetadata: { contentType: it.mimeType } });
                 refs.push(base ? `${base}/${key}` : `r2://${opts.bucketName ?? 'media'}/${key}`);
             }
@@ -83,15 +84,3 @@ export function createR2Sink(bucket, opts) {
                 'This hosted connector has no filesystem, so `output_dir` is ignored and no <image>.json sidecar is written — capture interaction_id from this result to chain further turns.',
     };
 }
-/**
- * base64 → bytes without `Buffer`. `Buffer` exists in a Worker under
- * `nodejs_compat`, but `atob` is the platform primitive on both runtimes and
- * keeps this module free of any Node dependency.
- */
-function decodeBase64(b64) {
-    const binary = atob(b64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return bytes;
-}