@chrischall/gemini-mcp 1.1.0 → 1.2.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.2.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.2.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.2.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

@@ -89,8 +89,9 @@ progress), two guards make re-issuing safe and unnecessary:
 
 ## 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.2.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(
@@ -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") {
@@ -34675,7 +34678,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 +34715,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 +34734,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 +34767,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 +34808,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 +34826,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 +34860,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) {
@@ -34874,7 +34886,7 @@ function registerFileTools(server, client2) {
       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 +34925,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,
@@ -34980,14 +34994,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`;
+}

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/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;
-}

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 ' +
@@ -77,7 +78,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,18 +123,21 @@ 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);
@@ -182,13 +186,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';
-    }
-}

package/dist/tools/interact.js

@@ -20,7 +20,7 @@ const NEW_REFERENCES_ONLY = 'NEW reference images only (e.g. a style or target p
 /**
  * On a chained call, split `images` into genuinely new references vs paths
  * this server itself generated (which the interaction already contains).
- * Unresolvable paths are kept so `gatherImageInputs` surfaces its usual error.
+ * Unresolvable paths are kept so `resolveImageInputs` surfaces its usual error.
  */
 function splitReattachedOutputs(images, writtenOutputs) {
     const kept = [];

package/dist/tools/music.js

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

package/dist/tools/shared.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { textResult, McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveVideoPath, videoMimeType } from '../images.js';
 import { IMAGE_URL_MAX_BYTES } from '../fetch-image.js';
+import { wholeMb } from '../bytes.js';
 import { createDiskSink } from '../storage/media.js';
 /**
  * Fallback sink for call sites that pass no explicit one (every pre-existing
@@ -64,7 +65,7 @@ export function imagesUrlSchema(label = 'Reference images') {
         .optional()
         .describe(`${label} as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. ` +
         'Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. ' +
-        `Max ${Math.round(IMAGE_URL_MAX_BYTES / (1024 * 1024))}MB each; must be a directly-linked image (Content-Type image/*).`);
+        `Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each; must be a directly-linked image (Content-Type image/*).`);
 }
 /**
  * Reference images already in the Gemini Files API. The cheapest form there is:

package/dist/tools/video.js

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

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '1.1.0'; // x-release-please-version
+export const VERSION = '1.2.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "mcpName": "io.github.chrischall/gemini-mcp",
   "description": "Gemini image-generation MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "1.1.0",
+  "version": "1.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       },

package/skills/gemini-mcp/SKILL.md

@@ -97,6 +97,9 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 
 ### Reference images — four ways in, one that costs context
 
+These apply to **every** tool that takes a reference image: the four image tools, plus
+`gemini_video_generate` (reference stills) and `gemini_music_generate`.
+
 | Parameter | Where the bytes travel | Context cost |
 |---|---|---|
 | `images_url` (`master_images_url`) | the **server** downloads the https URL | none |
@@ -142,8 +145,8 @@ curl -X POST https://<connector>/upload \
 ### Video & Music (preview — funded account)
 | Tool | Description |
 |------|-------------|
-| `gemini_video_generate(prompt, aspect_ratio?, task?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, model?, filename?, output_dir?, timeout_ms?, idempotency_key?, async?)` | Generate a short video via the Gemini omni model: `text_to_video` (default), `image_to_video` / `reference_to_video` (supply reference image[s]), or `edit` (with `previous_interaction_id` / `continue_last`). `aspect_ratio` is `16:9` or `9:16`. Written to disk as **MP4**. Runs long — use `async: true` + `gemini_get_result`, or raise `timeout_ms`. |
-| `gemini_music_generate(prompt, model?, audio_format?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, filename?, output_dir?, inline?, timeout_ms?, idempotency_key?, async?)` | Generate music from a prompt (mood/genre/instruments/structure/lyrics) via a Lyria model: `lyria-3-clip-preview` (~30s, default) or `lyria-3-pro-preview` (longer, WAV-capable). `audio_format` `mp3` (default) or `wav` (**Pro-only**). Written to disk as MP3/WAV, or returned inline. |
+| `gemini_video_generate(prompt, aspect_ratio?, task?, images_url?, images_file_uris?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, model?, filename?, output_dir?, timeout_ms?, idempotency_key?, async?)` | Generate a short video via the Gemini omni model: `text_to_video` (default), `image_to_video` / `reference_to_video` (supply reference image[s]), or `edit` (with `previous_interaction_id` / `continue_last`). `aspect_ratio` is `16:9` or `9:16`. Written to disk as **MP4**. Runs long — use `async: true` + `gemini_get_result`, or raise `timeout_ms`. |
+| `gemini_music_generate(prompt, model?, audio_format?, images_url?, images_file_uris?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, filename?, output_dir?, inline?, timeout_ms?, idempotency_key?, async?)` | Generate music from a prompt (mood/genre/instruments/structure/lyrics) via a Lyria model: `lyria-3-clip-preview` (~30s, default) or `lyria-3-pro-preview` (longer, WAV-capable). `audio_format` `mp3` (default) or `wav` (**Pro-only**). Written to disk as MP3/WAV, or returned inline. |
 
 ### Async / idempotency (any generation tool)
 | Tool | Description |