@chrischall/gemini-mcp 1.1.0 → 1.3.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
-    "version": "1.1.0"
+    "version": "1.3.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Gemini Images",
       "source": "./",
       "description": "Generate and edit images with Google Gemini image models (Nano Banana / Nano Banana Pro) via natural language prompts",
-      "version": "1.1.0",
+      "version": "1.3.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gemini-mcp",
   "displayName": "Gemini Images",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -87,10 +87,71 @@ progress), two guards make re-issuing safe and unnecessary:
 | `gemini_list_files` | List the files currently uploaded under this API key, with MIME types and expiry times |
 | `gemini_delete_file` | Delete an uploaded file before its ~48h expiry (confirm-gated) |
 
+## Seeing your images (hosted connector)
+
+On the hosted connector there is no filesystem, so a generated image has to come back as
+something you can *open*. It does: **every result includes a URL**, with no configuration.
+
+```jsonc
+{
+  "images": ["https://connector.example.com/media/gen/2026-07-29/ab12cd34-a-cat.png?exp=…&sig=…"],
+  "media":  [{ "url": "https://…", "r2_key": "gen/2026-07-29/ab12cd34-a-cat.png",
+               "expires_at": "2026-07-31T12:00:00.000Z" }]
+}
+```
+
+Those links need no auth header — the signature is in the URL — so they work in a browser, in
+`curl`, and in a chat message. They expire (48h by default) and the objects behind them are
+swept on a retention schedule.
+
+**Why this matters:** MCP's inline image content blocks (`inline: true`) are visible to the
+*assistant* but many chat clients never render them to the user, and the assistant cannot
+extract bytes back out of its own context to save them elsewhere. A generation could bill
+successfully and be invisible. A URL is the portable answer; `inline` remains available, but
+it is no longer the only way to receive media.
+
+### Three ways to serve the bytes
+
+| | setup | URL shape |
+|---|---|---|
+| **Worker route** (default) | none — works out of the box | `https://<worker-host>/media/<key>?exp=&sig=` |
+| **r2.dev public bucket** | enable public access on the bucket, set `MEDIA_PUBLIC_BASE_URL` | `https://pub-….r2.dev/<key>` |
+| **Custom domain** (best) | attach a domain to the bucket in Cloudflare, set `MEDIA_PUBLIC_BASE_URL` | `https://media.example.com/<key>` |
+
+The built-in Worker route is the zero-config path: the connector streams the object out of R2
+itself. The other two are worth setting up if you want plain, non-expiring URLs or want media
+traffic served by R2 rather than by the Worker — r2.dev is easiest but rate-limited and fine
+for personal use; a custom domain is the best of the three.
+
+**Auth on `/media` is a signed, expiring URL rather than an unlisted key.** Random keys would
+be simpler, but they never expire and never revoke: anything that ever logged or forwarded the
+link keeps working forever. A signature scopes access to one object with a deadline, and
+rotating `MEDIA_URL_SECRET` invalidates every outstanding link at once. The tradeoff is that
+links are long and cannot be shortened by hand.
+
+### For assistants relaying a result
+
+Show the user the URL. If your sandbox has network egress to the connector host, fetching it
+and attaching the bytes as a file gives the nicest result; otherwise present the link itself.
+Whether a given client renders `![](url)` markdown inline varies by client — a bare URL is the
+safe form, and a markdown link is a reasonable enhancement where you know it renders.
+
+### Retention
+
+| Variable | Default | Effect |
+|---|---|---|
+| `MEDIA_TTL_DAYS` | `7` | Objects older than this are deleted by a daily cron (both the current `gen/` prefix and the legacy `media/` one) |
+| `MEDIA_URL_SECRET` | generated | HMAC key for `/media` links; rotate to revoke all outstanding URLs |
+| `MEDIA_PUBLIC_BASE_URL` | unset | Serve from R2 directly instead of the Worker route |
+
+Signed-URL lifetime is clamped to `MEDIA_TTL_DAYS`, so a link never outlives the object it
+points at.
+
 ## Sending reference images without burning context
 
-Every image tool (`gemini_image_generate`, `gemini_image_edit`, `gemini_image_set`,
-`gemini_interact`) takes reference images four ways. Only one of them costs model context:
+Every tool that takes a reference image — `gemini_image_generate`, `gemini_image_edit`,
+`gemini_image_set`, `gemini_interact`, plus `gemini_video_generate` (reference stills) and
+`gemini_music_generate` — accepts them four ways. Only one of them costs model context:
 
 | Parameter | Where the bytes travel | Context cost |
 |---|---|---|

package/dist/bundle.js

@@ -32548,73 +32548,11 @@ var init_dist = __esm({
   }
 });
 
-// src/clipboard.ts
-var clipboard_exports = {};
-__export(clipboard_exports, {
-  readClipboardImage: () => readClipboardImage
-});
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { readFile, unlink } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join as join2 } from "node:path";
-async function readClipboardImage(run = defaultRun) {
-  if (process.platform !== "darwin") {
-    throw new McpToolError("from_clipboard is only supported on macOS", {
-      hint: "Save the image to a file and pass it via `images` instead."
-    });
-  }
-  const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-  const png = join2(tmpdir(), `gemini-clip-${id}.png`);
-  const jpg = join2(tmpdir(), `gemini-clip-${id}.jpg`);
-  try {
-    try {
-      await run("osascript", [
-        "-e",
-        `set f to (open for access POSIX file "${png}" with write permission)`,
-        "-e",
-        "write (the clipboard as \xABclass PNGf\xBB) to f",
-        "-e",
-        "close access f"
-      ]);
-    } catch {
-      throw new McpToolError("No image found on the clipboard", {
-        hint: "Copy an image (\u2318C) first, or pass `images`/`images_base64`."
-      });
-    }
-    try {
-      await run("sips", ["-Z", "2048", "-s", "format", "jpeg", png, "--out", jpg]);
-    } catch {
-      throw new McpToolError("Failed to convert the clipboard image", {
-        hint: "The clipboard may contain a non-standard image format."
-      });
-    }
-    const buf = await readFile(jpg);
-    return { base64: buf.toString("base64"), mimeType: "image/jpeg" };
-  } finally {
-    await unlink(png).catch(() => void 0);
-    await unlink(jpg).catch(() => void 0);
-  }
-}
-var execFileAsync, defaultRun;
-var init_clipboard = __esm({
-  "src/clipboard.ts"() {
-    "use strict";
-    init_dist();
-    execFileAsync = promisify(execFile);
-    defaultRun = async (cmd, args) => {
-      await execFileAsync(cmd, args);
-    };
-  }
-});
-
 // src/images.ts
 var images_exports = {};
 __export(images_exports, {
   baseName: () => baseName,
   decodeImageInput: () => decodeImageInput,
-  gatherImageInputs: () => gatherImageInputs,
-  loadImageInputs: () => loadImageInputs,
   mediaExt: () => mediaExt,
   previewImageInput: () => previewImageInput,
   previewVideoInput: () => previewVideoInput,
@@ -32629,9 +32567,9 @@ __export(images_exports, {
   writeMedia: () => writeMedia,
   writeSidecar: () => writeSidecar
 });
-import { mkdir, readFile as readFile2, writeFile, access, stat, open } from "node:fs/promises";
+import { mkdir, readFile, writeFile, access, stat, open } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { join as join3, resolve, isAbsolute } from "node:path";
+import { join as join2, resolve, isAbsolute } from "node:path";
 function slugify2(text, max = 40) {
   const s = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, max).replace(/-+$/g, "");
   return s || "image";
@@ -32645,10 +32583,10 @@ async function exists(p) {
   }
 }
 async function uniquePath(dir, base, ext) {
-  let candidate = join3(dir, `${base}.${ext}`);
+  let candidate = join2(dir, `${base}.${ext}`);
   let n = 2;
   while (await exists(candidate)) {
-    candidate = join3(dir, `${base}-${n}.${ext}`);
+    candidate = join2(dir, `${base}-${n}.${ext}`);
     n++;
   }
   return candidate;
@@ -32694,7 +32632,7 @@ function resolveInputPath(p, kind) {
   if (isAbsolute(p) && existsSync(p)) return p;
   const inputDir = readEnvVar("GEMINI_INPUT_DIR");
   if (inputDir) {
-    const candidate = join3(inputDir, p);
+    const candidate = join2(inputDir, p);
     if (existsSync(candidate)) return resolve(candidate);
   }
   const cwd = resolve(p);
@@ -32740,7 +32678,7 @@ async function previewVideoInput(path) {
 }
 async function readImageAsInline(path) {
   const resolved = resolveImagePath(path);
-  const buf = await readFile2(resolved);
+  const buf = await readFile(resolved);
   const mimeType = sniffMimeBytes(buf);
   return { base64: buf.toString("base64"), mimeType };
 }
@@ -32757,16 +32695,6 @@ function decodeImageInput(input) {
   const buf = Buffer.from(trimmed, "base64");
   return { base64: trimmed, mimeType: sniffMimeBytes(buf) };
 }
-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];
-}
-async function gatherImageInputs(opts) {
-  const clipboardImages = opts.from_clipboard ? [await (await Promise.resolve().then(() => (init_clipboard(), clipboard_exports))).readClipboardImage()] : [];
-  const fileImages = await loadImageInputs(opts.images, opts.images_base64);
-  return [...clipboardImages, ...fileImages];
-}
 function baseName(name) {
   const stripped = name.replace(/\.(png|jpe?g|webp|mp4|mov|webm|mp3|wav|ogg)$/i, "");
   const safe = stripped.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
@@ -32795,6 +32723,66 @@ var init_images = __esm({
   }
 });
 
+// src/clipboard.ts
+var clipboard_exports = {};
+__export(clipboard_exports, {
+  readClipboardImage: () => readClipboardImage
+});
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile as readFile2, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as join3 } from "node:path";
+async function readClipboardImage(run = defaultRun) {
+  if (process.platform !== "darwin") {
+    throw new McpToolError("from_clipboard is only supported on macOS", {
+      hint: "Save the image to a file and pass it via `images` instead."
+    });
+  }
+  const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const png = join3(tmpdir(), `gemini-clip-${id}.png`);
+  const jpg = join3(tmpdir(), `gemini-clip-${id}.jpg`);
+  try {
+    try {
+      await run("osascript", [
+        "-e",
+        `set f to (open for access POSIX file "${png}" with write permission)`,
+        "-e",
+        "write (the clipboard as \xABclass PNGf\xBB) to f",
+        "-e",
+        "close access f"
+      ]);
+    } catch {
+      throw new McpToolError("No image found on the clipboard", {
+        hint: "Copy an image (\u2318C) first, or pass `images`/`images_base64`."
+      });
+    }
+    try {
+      await run("sips", ["-Z", "2048", "-s", "format", "jpeg", png, "--out", jpg]);
+    } catch {
+      throw new McpToolError("Failed to convert the clipboard image", {
+        hint: "The clipboard may contain a non-standard image format."
+      });
+    }
+    const buf = await readFile2(jpg);
+    return { base64: buf.toString("base64"), mimeType: "image/jpeg" };
+  } finally {
+    await unlink(png).catch(() => void 0);
+    await unlink(jpg).catch(() => void 0);
+  }
+}
+var execFileAsync, defaultRun;
+var init_clipboard = __esm({
+  "src/clipboard.ts"() {
+    "use strict";
+    init_dist();
+    execFileAsync = promisify(execFile);
+    defaultRun = async (cmd, args) => {
+      await execFileAsync(cmd, args);
+    };
+  }
+});
+
 // src/index.ts
 init_dist();
 
@@ -32808,7 +32796,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.1.0";
+var VERSION = "1.3.0";
 
 // src/tools/models.ts
 init_dist();
@@ -32853,6 +32841,30 @@ init_dist();
 
 // src/fetch-image.ts
 init_dist();
+
+// src/bytes.ts
+function base64ToBytes(base643) {
+  const binary = atob(base643);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function bytesToBase64(bytes) {
+  const CHUNK = 32768;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary);
+}
+function wholeMb(bytes) {
+  return Math.round(bytes / (1024 * 1024));
+}
+function formatMb(bytes) {
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// src/fetch-image.ts
 var IMAGE_URL_MAX_BYTES = 15 * 1024 * 1024;
 var IMAGE_INLINE_MAX_BYTES = 6 * 1024 * 1024;
 var MAX_REDIRECTS = 5;
@@ -32955,6 +32967,14 @@ function assertPublicHttpsUrl(raw, requested) {
   }
   return url2;
 }
+function fileNameFromUrl(url2, fallback) {
+  try {
+    const name = new URL(url2).pathname.split("/").filter(Boolean).pop();
+    return name ? decodeURIComponent(name).slice(0, 120) : fallback;
+  } catch {
+    return fallback;
+  }
+}
 function describeUrl(current, requested) {
   return current === requested ? current : `${current} (redirected from ${requested})`;
 }
@@ -33008,9 +33028,8 @@ function fetchFailure(err, current, requested, timeoutMs) {
   );
 }
 function tooBig(url2, requested, size, max, partial2 = false) {
-  const mb2 = (n) => `${(n / (1024 * 1024)).toFixed(1)} MB`;
   return new McpToolError(
-    `Image at ${describeUrl(url2, requested)} is ${partial2 ? "over" : ""} ${mb2(size)}, above the ${mb2(max)} limit for images_url.`,
+    `Image at ${describeUrl(url2, requested)} is ${partial2 ? "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." }
   );
 }
@@ -33143,7 +33162,7 @@ async function resolveLocalPath(path, client2, onDisk, report) {
   const inline = await readImageAsInline2(resolved);
   if (references < 2) return inline;
   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 client2.uploadBytes(bytes, inline.mimeType, displayName);
     client2.session.uploadCache.set(key, {
@@ -33167,29 +33186,13 @@ async function resolveUrl(url2, client2, 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(url2);
+  const displayName = fileNameFromUrl(url2, "image");
   const uploaded = await client2.uploadBytes(fetched.bytes, fetched.mimeType, displayName);
   entry.file_uri = uploaded.name;
   return { uri: uploaded.uri, mimeType: uploaded.mimeType };
 }
-function fileNameFromUrl(url2) {
-  try {
-    const name = new URL(url2).pathname.split("/").filter(Boolean).pop();
-    return name ? decodeURIComponent(name).slice(0, 120) : "image";
-  } catch {
-    return "image";
-  }
-}
-function encodeBase64(bytes) {
-  let binary = "";
-  const CHUNK = 32768;
-  for (let i = 0; i < bytes.length; i += CHUNK) {
-    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
-  }
-  return btoa(binary);
-}
 function requireImageInput(args) {
   if (hasImageInput(args)) return;
   throw new McpToolError(
@@ -33211,7 +33214,7 @@ function createDiskSink() {
       const { writeMedia: writeMedia2, resolveOutputDir: resolveOutputDir2 } = await Promise.resolve().then(() => (init_images(), images_exports));
       const dir = resolveOutputDir2(opts.output_dir);
       const refs = [];
-      for (const it of items) refs.push(await writeMedia2(dir, it.base, it.base64, it.mimeType));
+      for (const it of items) refs.push({ ref: await writeMedia2(dir, it.base, it.base64, it.mimeType) });
       return refs;
     },
     note: () => void 0
@@ -33234,7 +33237,7 @@ var asyncSchema = external_exports.boolean().optional().describe(
 );
 function imagesUrlSchema(label = "Reference images") {
   return external_exports.array(external_exports.string().url()).optional().describe(
-    `${label} as public https URLs \u2014 the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max ${Math.round(IMAGE_URL_MAX_BYTES / (1024 * 1024))}MB each; must be a directly-linked image (Content-Type image/*).`
+    `${label} as public https URLs \u2014 the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each; must be a directly-linked image (Content-Type image/*).`
   );
 }
 function imagesFileUrisSchema(label = "Reference images") {
@@ -33343,14 +33346,26 @@ async function emitMedia(named, kind, opts, meta3, onWritten) {
     return { content: blocks };
   }
   const sink = opts.sink ?? DEFAULT_SINK;
-  const refs = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
+  const persisted = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
     output_dir: opts.output_dir
   });
+  const refs = persisted.map((p) => p.ref);
   if (sink.persistsFiles) await onWritten?.(refs);
   const note = opts.inline && kind === "video" ? { inline_unsupported: "video has no MCP inline content type \u2014 written to disk instead" } : {};
   const storageNote = sink.note();
+  const unavailable = persisted.some((p) => p.unavailable) ? {
+    media_url_unavailable: "The media was stored but no public URL could be generated for it, so the values above are bare object keys, not links. This is a connector misconfiguration: set MEDIA_PUBLIC_BASE_URL, or use inline: true to receive the bytes directly."
+  } : {};
+  const detailed = persisted.filter((p) => p.key !== void 0);
+  const media = detailed.length === persisted.length && detailed.length > 0 ? {
+    media: persisted.map((p) => ({
+      url: p.ref,
+      ...p.key ? { r2_key: p.key } : {},
+      ...p.expiresAt ? { expires_at: p.expiresAt } : {}
+    }))
+  } : {};
   const storage = sink.persistsFiles ? {} : { storage: sink.kind, storage_note: storageNote };
-  return textResult({ [`${kind}s`]: refs, ...note, ...storage, ...meta3 });
+  return textResult({ [`${kind}s`]: refs, ...media, ...unavailable, ...note, ...storage, ...meta3 });
 }
 async function emit(named, opts, meta3, onWritten) {
   return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), "image", opts, meta3, onWritten);
@@ -34505,7 +34520,7 @@ function splitReattachedOutputs(images, writtenOutputs) {
 }
 function registerInteractTools(server, client2) {
   const onDiskRuntime = client2.mediaSink?.persistsFiles ?? true;
-  const recoveryDescription = onDiskRuntime ? "If a call times out on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction \u2014 check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). " : "This connector has no filesystem: there is no output dir and no `<image>.json` sidecar, so a lost response cannot be recovered from disk and a 404 on a chained call cannot be re-anchored automatically. Capture the returned `interaction_id` from every result, and use `async: true` + gemini_get_result for long generations. ";
+  const recoveryDescription = onDiskRuntime ? "If a call times out on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction \u2014 check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). " : "On this connector each result returns an image URL you can open or share directly (see `media[].url`) \u2014 show it to the user rather than assuming they can see the image. There is no filesystem, so no output dir and no `<image>.json` sidecar: a lost response cannot be recovered from disk and a 404 on a chained call cannot be re-anchored automatically. Capture the returned `interaction_id` from every result, and use `async: true` + gemini_get_result for long generations. ";
   server.registerTool(
     "gemini_interact",
     {
@@ -34675,7 +34690,9 @@ function registerVideoTools(server, client2) {
         aspect_ratio: external_exports.enum(VIDEO_ASPECT_RATIOS).optional().describe("Output aspect ratio (omni: 16:9 or 9:16)"),
         task: external_exports.enum(VIDEO_TASKS).optional().describe("text_to_video (default), image_to_video / reference_to_video (need image input), or edit (needs previous_interaction_id)"),
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Reference image path(s) for image_to_video / reference_to_video"),
-        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs"),
+        images_url: imagesUrlSchema("Reference stills"),
+        images_file_uris: imagesFileUrisSchema("Reference stills"),
+        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation"),
         from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS clipboard as a reference"),
         filename: external_exports.string().optional().describe("Base filename for the output video (extension stripped; default: slugified prompt)"),
         output_dir: external_exports.string().optional().describe("Directory to write the video to (default: $GEMINI_OUTPUT_DIR or cwd)"),
@@ -34710,10 +34727,12 @@ function registerVideoTools(server, client2) {
         images: args.images,
         images_base64: args.images_base64,
         from_clipboard: args.from_clipboard,
+        images_url: args.images_url,
+        images_file_uris: args.images_file_uris,
         previous_interaction_id: previousInteractionId
       });
       return client2.session.jobs.dispatch({ toolName: "gemini_video_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
-        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const { inputs, report } = await resolveImageInputs(args, client2);
         const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client2.generateVideo({
           input: args.prompt,
           images: inputs.length ? inputs : void 0,
@@ -34727,6 +34746,7 @@ function registerVideoTools(server, client2) {
         const meta3 = { model, interaction_id: r.id };
         if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
         if (r.text) meta3.text = r.text;
+        if (report) meta3.image_inputs = report;
         meta3.hint = `To edit this video, call gemini_video_generate again with task: "edit" and previous_interaction_id: "${r.id}" (or continue_last: true).`;
         const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
         const named = r.videos.map((media, i) => ({
@@ -34759,7 +34779,9 @@ function registerMusicTools(server, client2) {
         model: external_exports.enum(MUSIC_MODELS).optional().describe(`Lyria model (default: ${DEFAULT_MUSIC_MODEL}). Pro is longer-form and supports WAV.`),
         audio_format: external_exports.enum(AUDIO_FORMATS).optional().describe("Output format (default mp3). wav is lyria-3-pro-preview-only."),
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Optional reference image path(s) to condition the music"),
-        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs"),
+        images_url: imagesUrlSchema("Reference images"),
+        images_file_uris: imagesFileUrisSchema("Reference images"),
+        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation"),
         from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS clipboard as a reference"),
         filename: external_exports.string().optional().describe("Base filename for the output audio (extension stripped; default: slugified prompt)"),
         output_dir: external_exports.string().optional().describe("Directory to write audio to (default: $GEMINI_OUTPUT_DIR or cwd)"),
@@ -34798,10 +34820,12 @@ function registerMusicTools(server, client2) {
         images: args.images,
         images_base64: args.images_base64,
         from_clipboard: args.from_clipboard,
+        images_url: args.images_url,
+        images_file_uris: args.images_file_uris,
         previous_interaction_id: previousInteractionId
       });
       return client2.session.jobs.dispatch({ toolName: "gemini_music_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
-        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const { inputs, report } = await resolveImageInputs(args, client2);
         const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client2.generateMusic({
           input: args.prompt,
           images: inputs.length ? inputs : void 0,
@@ -34814,6 +34838,7 @@ function registerMusicTools(server, client2) {
         const meta3 = { model, interaction_id: r.id };
         if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
         if (r.text) meta3.text = r.text;
+        if (report) meta3.image_inputs = report;
         meta3.hint = `To continue this track, call gemini_music_generate again with previous_interaction_id: "${r.id}" (or continue_last: true).`;
         const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
         const named = r.audios.map((media, i) => ({
@@ -34847,7 +34872,6 @@ init_zod();
 init_dist();
 var UPLOAD_URL_MAX_BYTES_DISK = 100 * 1024 * 1024;
 var UPLOAD_URL_MAX_BYTES_HOSTED = 25 * 1024 * 1024;
-var mb = (bytes) => Math.round(bytes / (1024 * 1024));
 var UPLOAD_ACCEPT = ["image/", "video/", "audio/"];
 var 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.";
 function uploadResult(file2) {
@@ -34870,11 +34894,11 @@ function registerFileTools(server, client2) {
   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."),
+      description: "Upload a file \u2014 an image, reference photo, picture, screenshot, video or audio clip \u2014 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`" + (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: external_exports.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.")
+          `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: external_exports.string().min(1).optional().describe("Raw base64 or a data: URI. Last resort \u2014 this is the one form that costs model context (~14k tokens for a modest JPEG)."),
         path: external_exports.string().min(1).optional().describe(
@@ -34913,19 +34937,21 @@ function registerFileTools(server, client2) {
           return client2.uploadBytes(
             fetched.bytes,
             args.mime_type ?? fetched.mimeType,
-            args.display_name ?? nameFromUrl(args.url)
+            // '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: decodeImageInput2 } = await Promise.resolve().then(() => (init_images(), images_exports));
           const decoded = decodeImageInput2(args.data_base64);
-          const bytes2 = Uint8Array.from(atob(decoded.base64), (c) => c.charCodeAt(0));
+          const bytes2 = base64ToBytes(decoded.base64);
           return client2.uploadBytes(bytes2, args.mime_type ?? decoded.mimeType, args.display_name ?? "upload");
         }
         const { readImageAsInline: readImageAsInline2, resolveImagePath: resolveImagePath2 } = await Promise.resolve().then(() => (init_images(), images_exports));
         const resolved = resolveImagePath2(args.path);
         const inline = await readImageAsInline2(resolved);
-        const bytes = Uint8Array.from(atob(inline.base64), (c) => c.charCodeAt(0));
+        const bytes = base64ToBytes(inline.base64);
         return client2.uploadBytes(
           bytes,
           args.mime_type ?? inline.mimeType,
@@ -34938,7 +34964,7 @@ function registerFileTools(server, client2) {
   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.",
+      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: {
         page_size: external_exports.number().int().positive().max(100).optional().describe("Maximum files to return (1-100, default 100)")
@@ -34965,7 +34991,7 @@ function registerFileTools(server, client2) {
   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.",
+      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: {
         file_uri: external_exports.string().min(1).describe("The `files/<id>` reference (or full uri) to delete"),
@@ -34980,14 +35006,6 @@ function registerFileTools(server, client2) {
     }
   );
 }
-function nameFromUrl(url2) {
-  try {
-    const name = new URL(url2).pathname.split("/").filter(Boolean).pop();
-    return name ? decodeURIComponent(name).slice(0, 120) : "upload";
-  } catch {
-    return "upload";
-  }
-}
 
 // src/index.ts
 await loadStdioDotenv();

package/dist/bytes.js

@@ -0,0 +1,46 @@
+/**
+ * base64 ↔ bytes, and byte-size formatting.
+ *
+ * These conversions had grown four near-identical copies — an inline
+ * `Uint8Array.from(atob(x), c => c.charCodeAt(0))` in `inputs.ts` and twice in
+ * `tools/files.ts`, plus a private `decodeBase64` in `storage/media.ts` — and
+ * a fifth (`encodeBase64`) that was subtly different because it is the only one
+ * that has to chunk. One place, so the chunking rule can't be forgotten in copy
+ * number six.
+ *
+ * `atob`/`btoa` rather than `Buffer`: this module is on the Worker's import
+ * graph, and they are the primitive both runtimes share. Module scope stays
+ * side-effect-free for the same reason (see the note in client.ts).
+ */
+/** Decode base64 into raw bytes. */
+export function base64ToBytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/**
+ * Encode raw bytes as base64.
+ *
+ * Chunked because `String.fromCharCode(...bytes)` spreads one argument per
+ * byte and blows the engine's argument limit somewhere around 100–125k — i.e.
+ * it works fine on every small test fixture and throws on the first real
+ * photo, which is the worst possible place to learn about it.
+ */
+export function bytesToBase64(bytes) {
+    const CHUNK = 0x8000;
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+/** Whole megabytes, for limits stated in tool descriptions (`25MB`). */
+export function wholeMb(bytes) {
+    return Math.round(bytes / (1024 * 1024));
+}
+/** One-decimal megabytes, for error messages about an actual size (`15.4 MB`). */
+export function formatMb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}