@chrischall/gemini-mcp 1.1.0 → 1.3.0

package/dist/connector-origin.js

@@ -0,0 +1,34 @@
+/**
+ * Tell an MCP session which hostname it was reached on.
+ *
+ * This is the single load-bearing link in the zero-config media-URL path: the
+ * origin captured here becomes `https://<host>/media/…` for every generated
+ * image. If it goes missing, generations silently stop coming back with
+ * openable links — the exact failure the media work exists to end — so it lives
+ * in its own module, free of any Cloudflare import, purely so it can be tested.
+ * (`src/worker.ts` pulls in `agents` and cannot load under Node at all.)
+ *
+ * Deriving the origin per request rather than configuring it is what makes a
+ * fork, a `*.workers.dev` preview and the custom domain all mint correct links
+ * with nothing to set. It rides on `ctx.props` — the object the OAuth provider
+ * has already populated with the decrypted grant — rather than a module-level
+ * variable, because one isolate serves many authenticated sessions (session.ts).
+ */
+/** Property name the session reads back off its props. */
+export const CONNECTOR_ORIGIN_PROP = 'connectorOrigin';
+/**
+ * Wrap a handler so `ctx.props.connectorOrigin` is set before it runs.
+ *
+ * Existing props are preserved — they carry the user's API key, and dropping
+ * them would break authentication rather than merely lose a URL.
+ */
+export function withConnectorOrigin(inner) {
+    return {
+        fetch(request, env, ctx) {
+            const carrier = (ctx ?? {});
+            const existing = (typeof carrier.props === 'object' && carrier.props !== null ? carrier.props : {});
+            carrier.props = { ...existing, [CONNECTOR_ORIGIN_PROP]: new URL(request.url).origin };
+            return inner.fetch(request, env, ctx);
+        },
+    };
+}

package/dist/fetch-image.js

@@ -1,4 +1,5 @@
 import { McpToolError } from '@chrischall/mcp-utils';
+import { formatMb } from './bytes.js';
 /**
  * Server-side fetching of `images_url` references.
  *
@@ -207,6 +208,28 @@ function assertPublicHttpsUrl(raw, requested) {
     }
     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})`;
@@ -265,8 +288,7 @@ function fetchFailure(err, current, requested, timeoutMs) {
     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) {
-    const mb = (n) => `${(n / (1024 * 1024)).toFixed(1)} MB`;
-    return new McpToolError(`Image at ${describeUrl(url, requested)} is ${partial ? 'over' : ''} ${mb(size)}, above the ${mb(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.' });
+    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

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/inputs.js

@@ -1,5 +1,6 @@
 import { McpToolError } from '@chrischall/mcp-utils';
-import { IMAGE_INLINE_MAX_BYTES } from './fetch-image.js';
+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 ||
@@ -117,7 +118,7 @@ async function resolveLocalPath(path, client, onDisk, report) {
     // 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 bytes = base64ToBytes(inline.base64);
         const displayName = resolved.split(/[\\/]/).pop() || 'image';
         const uploaded = await client.uploadBytes(bytes, inline.mimeType, displayName);
         client.session.uploadCache.set(key, {
@@ -143,36 +144,14 @@ async function resolveUrl(url, client, report) {
     };
     (report.fetched_urls ??= []).push(entry);
     if (fetched.size <= IMAGE_INLINE_MAX_BYTES) {
-        return { base64: encodeBase64(fetched.bytes), mimeType: fetched.mimeType };
+        return { base64: bytesToBase64(fetched.bytes), mimeType: fetched.mimeType };
     }
-    const displayName = fileNameFromUrl(url);
+    // '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 };
 }
-/** 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

package/dist/media-cleanup.js

@@ -0,0 +1,75 @@
+/**
+ * Retention for generated media.
+ *
+ * Every hosted generation writes an object to R2 and nothing ever removed it,
+ * so the bucket grew without bound — and the signed links pointing into it are
+ * only useful for a couple of days anyway. A scheduled sweep keeps the two in
+ * step: objects live `MEDIA_TTL_DAYS` (default 7), and a signed URL's lifetime
+ * is clamped to that, so a link never outlives the object behind it.
+ *
+ * R2 lifecycle rules would be the cheaper mechanism, but they are configured on
+ * the bucket rather than in `wrangler.jsonc`, so a fresh deploy of this repo
+ * would silently have no retention at all. A cron in the Worker ships with the
+ * code.
+ */
+const DEFAULT_MAX_OBJECTS = 5_000;
+/**
+ * `gen/` is where media is written now; `media/` is where it was written before
+ * the rename that made URLs read `/media/gen/…` instead of `/media/media/…`.
+ * Both are swept — retention that ignores the existing backlog is not retention.
+ */
+const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/'];
+/** R2 accepts bulk deletes in batches; 1000 is the documented ceiling. */
+const DELETE_BATCH = 1_000;
+/** Days → ms, defaulting to 7 for anything missing or nonsensical. */
+export function retentionMsFromDays(days) {
+    const n = Number(days);
+    return (Number.isFinite(n) && n > 0 ? n : 7) * 24 * 60 * 60 * 1000;
+}
+/**
+ * Delete generated media older than `retentionMs`. Returns counts rather than
+ * logging them, so the caller decides what to do with the numbers and the sweep
+ * itself stays testable.
+ */
+export async function cleanupExpiredMedia(bucket, retentionMs, opts = {}) {
+    const now = opts.now?.() ?? Date.now();
+    const cutoff = now - retentionMs;
+    const maxObjects = opts.maxObjects ?? DEFAULT_MAX_OBJECTS;
+    const prefixes = opts.prefixes ?? LEGACY_AND_CURRENT_PREFIXES;
+    let scanned = 0;
+    let deleted = 0;
+    let truncated = false;
+    const doomed = [];
+    const flush = async (all) => {
+        while (doomed.length >= (all ? 1 : DELETE_BATCH)) {
+            const batch = doomed.splice(0, DELETE_BATCH);
+            await bucket.delete(batch);
+            deleted += batch.length;
+        }
+    };
+    for (const prefix of prefixes) {
+        let cursor;
+        for (;;) {
+            if (scanned >= maxObjects) {
+                truncated = true;
+                break;
+            }
+            const page = await bucket.list({ prefix, cursor, limit: Math.min(1000, maxObjects - scanned) });
+            for (const object of page.objects) {
+                scanned++;
+                if (object.uploaded.getTime() < cutoff)
+                    doomed.push(object.key);
+            }
+            await flush(false);
+            if (!page.truncated)
+                break;
+            if (scanned >= maxObjects) {
+                truncated = true;
+                break;
+            }
+            cursor = page.cursor;
+        }
+    }
+    await flush(true);
+    return { scanned, deleted, truncated };
+}

package/dist/media-endpoint.js

@@ -0,0 +1,72 @@
+import { loadSigningKey, verifyMediaSignature } from './media-url.js';
+function problem(status, message) {
+    return new Response(`${message}\n`, {
+        status,
+        headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' },
+    });
+}
+/**
+ * Build the `/media` handler. `basePath` is stripped from the pathname to get
+ * the R2 key, so the key keeps its own prefix and the two never drift.
+ */
+export function createMediaHandler(env, basePath = '/media/') {
+    return async function handleMedia(request) {
+        if (request.method !== 'GET' && request.method !== 'HEAD') {
+            return problem(405, `Method ${request.method} not allowed; media links are GET-only.`);
+        }
+        const url = new URL(request.url);
+        if (!url.pathname.startsWith(basePath))
+            return problem(404, 'Not found');
+        // decodeURIComponent per segment, mirroring how the URL was built. A key
+        // cannot contain `..` (the sink sanitises every segment), and R2 has no
+        // path traversal to exploit anyway — a key is an opaque string, not a path.
+        const key = url.pathname
+            .slice(basePath.length)
+            .split('/')
+            .map((segment) => {
+            try {
+                return decodeURIComponent(segment);
+            }
+            catch {
+                return segment;
+            }
+        })
+            .join('/');
+        if (!key)
+            return problem(404, 'Not found');
+        const now = env.now?.() ?? Date.now();
+        // Read-only: verification must never CREATE a signing secret. A stale KV
+        // read here would otherwise clobber the secret every outstanding link was
+        // signed with (see loadSigningKey). No secret ⇒ nothing was legitimately
+        // signed ⇒ refuse, without touching storage or the bucket.
+        const signingKey = await loadSigningKey(env.secret, env.store);
+        const check = signingKey
+            ? await verifyMediaSignature(signingKey, key, url.searchParams.get('exp'), url.searchParams.get('sig'), now)
+            : { ok: false, reason: 'invalid' };
+        if (!check.ok) {
+            if (check.reason === 'expired') {
+                return problem(410, 'This media link has expired. Generated media is retained for a limited time — re-run the generation to get a fresh link.');
+            }
+            return problem(403, 'Invalid or missing media signature. Media links must be used exactly as returned by the tool, including the exp and sig parameters.');
+        }
+        const object = await env.bucket.get(key);
+        if (!object) {
+            return problem(404, 'That media object no longer exists — it may have been cleaned up. Re-run the generation to get a fresh one.');
+        }
+        const headers = new Headers({
+            'content-type': object.httpMetadata?.contentType ?? 'application/octet-stream',
+            // The URL is signed and expiring, so it is safe to cache for its lifetime;
+            // `private` keeps shared caches from serving it to anyone else.
+            'cache-control': 'private, max-age=3600',
+            'content-disposition': `inline; filename="${key.split('/').pop() ?? 'media'}"`,
+            // The bytes are model output being handed to a browser — never let a
+            // sniffed content type turn an image response into something executable.
+            'x-content-type-options': 'nosniff',
+        });
+        if (object.size !== undefined)
+            headers.set('content-length', String(object.size));
+        if (request.method === 'HEAD')
+            return new Response(null, { status: 200, headers });
+        return new Response(object.body, { status: 200, headers });
+    };
+}

package/dist/media-url.js

@@ -0,0 +1,135 @@
+/**
+ * Signed URLs for generated media on the hosted connector.
+ *
+ * The problem these exist to solve: a chat client shows the user whatever the
+ * assistant *says*, and MCP inline image blocks are not that. On claude.ai and
+ * the mobile app the bytes arrive in the model's context and are never rendered
+ * — so a generation that billed successfully is invisible. A URL is the only
+ * portable answer: a human can tap it and an agent can curl it.
+ *
+ * That means the media route cannot sit behind the connector's OAuth, because
+ * a browser opening a link carries no bearer token. The signature IS the
+ * authorization: a URL is valid for one key until it expires, and nothing else
+ * in the bucket is reachable without one.
+ *
+ * Kept free of any Cloudflare import so the whole thing is testable under Node:
+ * WebCrypto is the only primitive used, and it exists on both runtimes.
+ */
+/** How long a freshly minted media URL stays valid. Matches Files API retention. */
+export const MEDIA_URL_TTL_MS = 48 * 60 * 60 * 1000;
+/** KV key holding the lazily-generated signing secret (zero-config path). */
+export const SIGNING_SECRET_KV_KEY = 'media:url-signing-secret';
+function base64UrlEncode(bytes) {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let binary = '';
+    for (let i = 0; i < view.length; i++)
+        binary += String.fromCharCode(view[i]);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlDecode(text) {
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+/** Import raw secret material as an HMAC key. */
+async function importKey(material) {
+    return crypto.subtle.importKey('raw', new TextEncoder().encode(material), { name: 'HMAC', hash: 'SHA-256' }, false, [
+        'sign',
+        'verify',
+    ]);
+}
+/**
+ * The HMAC key for **signing**, creating one if this deployment has never
+ * signed anything.
+ *
+ * `MEDIA_URL_SECRET` wins when an operator sets one. Otherwise a random 32-byte
+ * secret is generated once and persisted in KV — which is what makes the whole
+ * feature work with **zero configuration**, the entire point of this change.
+ *
+ * Creating is confined to this function, and this function is called only when
+ * minting a URL. {@link loadSigningKey} is what the verify path uses. That
+ * split is load-bearing, not stylistic — see the warning there.
+ *
+ * Deliberately NOT cached in a module-level variable: `src/` holds no
+ * module-scope mutable state (see session.ts), and a KV read per sign is cheap
+ * next to an image generation. There is a narrow first-use race — two isolates
+ * generating simultaneously — so the value is re-read after writing and the
+ * stored one wins, collapsing the window to URLs minted in that same instant.
+ */
+export async function resolveSigningKey(secret, store) {
+    let material = secret?.trim();
+    if (!material) {
+        material = (await store.get(SIGNING_SECRET_KV_KEY)) ?? undefined;
+        if (!material) {
+            const generated = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
+            await store.put(SIGNING_SECRET_KV_KEY, generated);
+            // Re-read so a concurrent generator's value wins consistently for both.
+            material = (await store.get(SIGNING_SECRET_KV_KEY)) ?? generated;
+        }
+    }
+    return importKey(material);
+}
+/**
+ * The HMAC key for **verifying**. Read-only: returns `undefined` when no secret
+ * is stored, and never creates one.
+ *
+ * This is not a stylistic split. KV is eventually consistent — a `put` on one
+ * isolate is not immediately visible to another — so the verify path can and
+ * will see a miss for a secret that exists. If verification created-on-miss
+ * (as it did originally), that transient miss would mint a NEW secret and
+ * overwrite the one every outstanding link was signed with, permanently 403ing
+ * media that had been signed perfectly correctly. A self-inflicted denial of
+ * service, triggered by ordinary traffic, and irreversible once the old secret
+ * is gone.
+ *
+ * No secret stored ⇒ nothing was ever legitimately signed ⇒ refuse.
+ */
+export async function loadSigningKey(secret, store) {
+    const material = secret?.trim() || (await store.get(SIGNING_SECRET_KV_KEY));
+    return material ? importKey(material) : undefined;
+}
+/** The bytes covered by a signature: the object key and the expiry, nothing else. */
+function payload(key, expiresAtMs) {
+    return new TextEncoder().encode(`${key}\n${expiresAtMs}`);
+}
+/** Sign one object key for use until `expiresAtMs`. */
+export async function signMediaKey(signingKey, key, expiresAtMs) {
+    return base64UrlEncode(await crypto.subtle.sign('HMAC', signingKey, payload(key, expiresAtMs)));
+}
+/**
+ * Check a `?exp=&sig=` pair against an object key.
+ *
+ * Verification goes through `crypto.subtle.verify` rather than a string
+ * comparison, so it is constant-time — a `===` on the signature would leak the
+ * expected value one byte at a time to anyone willing to time it.
+ */
+export async function verifyMediaSignature(signingKey, key, exp, sig, nowMs) {
+    if (!exp || !sig)
+        return { ok: false, reason: 'missing' };
+    const expiresAtMs = Number(exp);
+    if (!Number.isFinite(expiresAtMs))
+        return { ok: false, reason: 'invalid' };
+    let valid;
+    try {
+        valid = await crypto.subtle.verify('HMAC', signingKey, base64UrlDecode(sig), payload(key, expiresAtMs));
+    }
+    catch {
+        return { ok: false, reason: 'invalid' };
+    }
+    // Signature first, then expiry: an expired-but-authentic link deserves a
+    // different message from a forged one, and saying "expired" about a forgery
+    // would confirm the attacker got the signature right.
+    if (!valid)
+        return { ok: false, reason: 'invalid' };
+    if (nowMs > expiresAtMs)
+        return { ok: false, reason: 'expired' };
+    return { ok: true };
+}
+/** `<base>/<key>?exp=…&sig=…` — the URL handed back to the caller. */
+export function buildMediaUrl(baseUrl, key, expiresAtMs, signature) {
+    const path = key.split('/').map(encodeURIComponent).join('/');
+    return `${baseUrl.replace(/\/+$/, '')}/${path}?exp=${expiresAtMs}&sig=${signature}`;
+}

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).
@@ -29,13 +30,15 @@ export function createDiskSink() {
             // Sequential on purpose: uniquePath checks the filesystem, so writing two
             // colliding names concurrently would race onto the same path.
             for (const it of items)
-                refs.push(await writeMedia(dir, it.base, it.base64, it.mimeType));
+                refs.push({ ref: await writeMedia(dir, it.base, it.base64, it.mimeType) });
             return refs;
         },
         note: () => undefined,
     };
 }
-const KEY_PREFIX_DEFAULT = 'media';
+// `gen`, not `media`: the objects are served at `/media/<key>`, and a `media`
+// prefix would make every URL read `/media/media/…`.
+const KEY_PREFIX_DEFAULT = 'gen';
 /** Object-key-safe name: no slashes, no dot-segments, never empty. */
 function safeKeySegment(base) {
     const cleaned = base
@@ -56,7 +59,9 @@ export function createR2Sink(bucket, opts) {
     const prefix = opts.prefix ?? KEY_PREFIX_DEFAULT;
     const now = opts.now ?? (() => new Date());
     const randomId = opts.randomId ?? (() => crypto.randomUUID().slice(0, 8));
-    const base = opts.publicBaseUrl?.replace(/\/+$/, '');
+    const publicBase = opts.publicBaseUrl?.replace(/\/+$/, '');
+    const signedBase = opts.signedBaseUrl?.replace(/\/+$/, '');
+    const ttlMs = opts.urlTtlMs ?? 0;
     return {
         kind: 'r2',
         persistsFiles: false,
@@ -66,32 +71,38 @@ export function createR2Sink(bucket, opts) {
             // module graph.
             const { mediaExt } = await import('../images.js');
             const day = now().toISOString().slice(0, 10);
+            const expiresAtMs = now().getTime() + ttlMs;
             const refs = [];
             for (const it of items) {
                 const key = `${prefix}/${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;
-                const bytes = decodeBase64(it.base64);
-                await bucket.put(key, bytes, { httpMetadata: { contentType: it.mimeType } });
-                refs.push(base ? `${base}/${key}` : `r2://${opts.bucketName ?? 'media'}/${key}`);
+                await bucket.put(key, base64ToBytes(it.base64), { httpMetadata: { contentType: it.mimeType } });
+                refs.push(await describe(key, expiresAtMs));
             }
             return refs;
         },
-        note: () => base
-            ? 'Generated media was uploaded to R2; the values above are public URLs, not local file paths. ' +
+        note: () => publicBase
+            ? 'Generated media was uploaded to R2 and the values above are public URLs (not local file paths) — open or download them directly. ' +
                 '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.'
-            : 'Generated media was uploaded to R2, which is not publicly served: the values above are object refs (r2://bucket/key), NOT fetchable URLs. ' +
-                'Set MEDIA_PUBLIC_BASE_URL on the Worker to get URLs, or pass inline: true to receive the bytes directly. ' +
-                '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.',
+            : signedBase
+                ? 'Generated media is served by this connector at the signed URLs above — open them in a browser or fetch them with curl; no auth header is needed, the signature is in the link. ' +
+                    'They expire (see media[].expires_at), and the objects behind them are cleaned up on a retention schedule. ' +
+                    '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.'
+                : 'Generated media was stored, but this connector has no public media URL configured and no signing route available, so the values above are bare object keys rather than fetchable links. ' +
+                    'Set MEDIA_PUBLIC_BASE_URL on the Worker, or pass inline: true to receive the bytes directly.',
     };
-}
-/**
- * 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;
+    /** One stored object → the ref the caller sees, plus its key and expiry. */
+    async function describe(key, expiresAtMs) {
+        // A bucket served directly (r2.dev or a custom domain) needs no signature.
+        if (publicBase)
+            return { ref: `${publicBase}/${key}`, key };
+        if (signedBase && opts.sign) {
+            const { buildMediaUrl } = await import('../media-url.js');
+            const signature = await opts.sign(key, expiresAtMs);
+            return { ref: buildMediaUrl(signedBase, key, expiresAtMs, signature), key, expiresAt: new Date(expiresAtMs).toISOString() };
+        }
+        // Neither configured. Unreachable in the Worker (which always passes its
+        // own origin), so this is a misconfiguration rather than a mode — say so
+        // explicitly rather than returning something that looks like a filename.
+        return { ref: key, key, unavailable: true };
+    }
 }

package/dist/tools/files.js

@@ -1,6 +1,8 @@
 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.
@@ -38,7 +40,6 @@ import { previewUnlessConfirmed, previewLocalInputsUnlessConfirmed, schemaConfir
  */
 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 ' +
@@ -62,7 +63,10 @@ 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. ' +
+        description: 'Upload a file — an image, reference photo, picture, screenshot, video or audio clip — to the Gemini Files API ' +
+            'ONCE, and get back a reusable `file_uri` (`files/<id>`) to attach to later image, video or music generations. ' +
+            'Keywords: upload, upload file, upload image, upload photo, attach, reference image, reference photo, ' +
+            'file_uri, files api, image reference, reuse across calls. ' +
             '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`' +
@@ -77,7 +81,7 @@ export function registerFileTools(server, client) {
                 .string()
                 .url()
                 .optional()
-                .describe(`Public https URL the SERVER downloads and uploads (image/video/audio, up to ${mb(urlMaxBytes)}MB). ` +
+                .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
@@ -122,24 +126,27 @@ export function registerFileTools(server, client) {
         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));
+                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 = Uint8Array.from(atob(decoded.base64), (c) => c.charCodeAt(0));
+                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 = Uint8Array.from(atob(inline.base64), (c) => c.charCodeAt(0));
+            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, ' +
+        description: 'List files, images and photos currently uploaded to the Gemini Files API under this API key, with their reusable `file_uri` (`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: {
@@ -165,7 +172,7 @@ export function registerFileTools(server, client) {
         });
     });
     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 ' +
+        description: 'Delete an uploaded file, image or photo (by file_uri) 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: {
@@ -182,13 +189,3 @@ export function registerFileTools(server, client) {
         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';
-    }
-}