@chrischall/gemini-mcp 1.1.0 → 1.3.0

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 = [];
@@ -48,9 +48,11 @@ export function registerInteractTools(server, client) {
             '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. ';
+        : 'On this connector each result returns an image URL you can open or share directly (see `media[].url`) — 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', {
         description: 'Preferred tool for iterative or multi-step refinement of a single image — ' +
             "multi-turn generation/editing via Gemini's Interactions API. " +

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:
@@ -264,9 +265,10 @@ export async function emitMedia(named, kind, opts, meta, 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);
     // `onWritten` (sidecars, the written-outputs set) is meaningful only when the
     // refs are real files. On a sink with no filesystem there is nothing to sit
     // next to, so it is skipped rather than handed URLs it would misinterpret.
@@ -278,8 +280,31 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
     // key is the same (`images`/`videos`/`audios`), so without this a caller would
     // reasonably read a URL as a file path.
     const storageNote = sink.note();
+    // Per-item detail (`url` / `r2_key` / `expires_at`) alongside the flat list,
+    // so a caller can reason about retention without parsing a URL. Only emitted
+    // where there IS extra detail — the disk sink's absolute paths say it all,
+    // and adding a parallel array there would change a stable result shape.
+    // A stored-but-unaddressable object is a configuration failure, not a mode.
+    // Saying so in the result beats handing back a bare key that reads like a
+    // filename — the silent-unopenable-ref problem this change exists to end.
+    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 !== undefined);
+    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, ...meta });
+    return textResult({ [`${kind}s`]: refs, ...media, ...unavailable, ...note, ...storage, ...meta });
 }
 /**
  * Image convenience wrapper over {@link emitMedia} — preserves the original

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.3.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.1.0",
+  "version": "1.3.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.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.1.0",
+      "version": "1.3.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 |