@chrischall/gemini-mcp 1.2.0 → 1.4.0

package/dist/tools/files.js

@@ -3,6 +3,7 @@ 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 { downloadFilename } from '../media-endpoint.js';
 import { previewUnlessConfirmed, previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 /**
  * First-class Gemini Files API access.
@@ -63,11 +64,16 @@ export function registerFileTools(server, client) {
     const onDisk = client.mediaSink?.persistsFiles ?? true;
     const urlMaxBytes = onDisk ? UPLOAD_URL_MAX_BYTES_DISK : UPLOAD_URL_MAX_BYTES_HOSTED;
     server.registerTool('gemini_upload_file', {
-        description: 'Upload an image (or video/audio) to the Gemini Files API ONCE and get back a reusable `files/<id>` reference. ' +
+        description: 'Upload a file — an image, reference photo, picture, screenshot, video or audio clip — to the Gemini Files API ' +
+            'ONCE, and get back a reusable `file_uri` (`files/<id>`) to attach to later image, video or music generations. ' +
+            'Keywords: upload, upload file, upload image, upload photo, attach, reference image, reference photo, ' +
+            'file_uri, files api, image reference, reuse across calls. ' +
             'Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever ' +
             'enter the conversation, and it can be reused across many generations until it expires (~48h). ' +
             'Provide exactly one of `url` (the server downloads it), `data_base64`' +
-            (onDisk ? ', or `path` (a local file).' : '.') +
+            (onDisk
+                ? ', or `path` (a local file).'
+                : ', or `r2_key` (re-upload media this connector generated, from media[].r2_key in an earlier result).') +
             (onDisk
                 ? ''
                 : ' This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header ' +
@@ -86,6 +92,16 @@ export function registerFileTools(server, client) {
                 .min(1)
                 .optional()
                 .describe('Raw base64 or a data: URI. Last resort — this is the one form that costs model context (~14k tokens for a modest JPEG).'),
+            r2_key: z
+                .string()
+                .min(1)
+                .optional()
+                .describe(onDisk
+                ? 'Unavailable on this server (media is written to local disk) — pass the file path via `path` instead.'
+                : 'An `r2_key` from a previous generation result (media[].r2_key) — re-uploads media THIS connector generated, ' +
+                    'so a generated image can become a reference image in one cheap call. The server reads its own bucket directly: ' +
+                    'no HTTP request, no signed URL, and no expiry to worry about. Do NOT pass a /media URL as `url` for this — ' +
+                    'that would be the connector fetching itself and needs a signature.'),
             path: z
                 .string()
                 .min(1)
@@ -102,10 +118,10 @@ export function registerFileTools(server, client) {
             confirm: schemaConfirm,
         },
     }, async (args, extra) => {
-        const sources = [args.url && 'url', args.data_base64 && 'data_base64', args.path && 'path'].filter(Boolean);
+        const sources = [args.url && 'url', args.data_base64 && 'data_base64', args.r2_key && 'r2_key', args.path && 'path'].filter(Boolean);
         if (sources.length !== 1) {
             throw new McpToolError(sources.length === 0
-                ? 'Provide exactly one of `url`, `data_base64`' + (onDisk ? ' or `path`.' : '.')
+                ? 'Provide exactly one of `url`, `data_base64`' + (onDisk ? ' or `path`.' : ' or `r2_key`.')
                 : `Provide exactly one source, not ${sources.length} (${sources.join(', ')}).`);
         }
         if (args.path) {
@@ -128,6 +144,17 @@ export function registerFileTools(server, client) {
                 // this tool takes video and audio too, so 'image' would be a lie.
                 args.display_name ?? fileNameFromUrl(args.url, 'upload'));
             }
+            if (args.r2_key) {
+                if (onDisk) {
+                    throw new McpToolError('`r2_key` is only available on the hosted connector — this server writes media to local disk, ' +
+                        'so pass the generated file via `path` instead.');
+                }
+                // Reading our own bucket rather than fetching our own /media URL. A
+                // self-fetch would need a signature the caller cannot mint, which is
+                // exactly the 403 loop this parameter exists to remove.
+                const stored = await client.readStoredMedia(args.r2_key);
+                return client.uploadBytes(stored.bytes, args.mime_type ?? stored.mimeType, args.display_name ?? downloadFilename(args.r2_key));
+            }
             if (args.data_base64) {
                 const { decodeImageInput } = await import('../images.js');
                 const decoded = decodeImageInput(args.data_base64);
@@ -143,7 +170,7 @@ export function registerFileTools(server, client) {
         return uploadResult(uploaded);
     });
     server.registerTool('gemini_list_files', {
-        description: 'List the files currently uploaded to the Gemini Files API under this API key, with their `files/<id>` references, ' +
+        description: 'List files, images and photos currently uploaded to the Gemini Files API under this API key, with their reusable `file_uri` (`files/<id>`) references, ' +
             'MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.',
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: {
@@ -168,8 +195,42 @@ export function registerFileTools(server, client) {
                 : 'No files uploaded (or all have expired — retention is ~48h). Upload one with gemini_upload_file.',
         });
     });
+    // Hosted connector only. On a disk-backed server the result carries a path
+    // that never expires, so a "refresh my link" tool would only ever error —
+    // don't advertise it there (mirrors the Worker not registering video).
+    if (!onDisk) {
+        server.registerTool('gemini_sign_media', {
+            description: 'Mint a FRESH signed URL for media this connector generated, from its `r2_key`. ' +
+                'Signed media links expire well before the object behind them is cleaned up, so an expired link is not a dead ' +
+                'end — re-sign it instead of re-generating (and re-paying for) the image. Keywords: expired link, refresh url, ' +
+                're-sign, media url, download again.',
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            inputSchema: {
+                r2_key: z.string().min(1).describe('The `media[].r2_key` from an earlier generation result'),
+            },
+        }, async (args) => {
+            const sink = client.mediaSink;
+            if (!sink?.resign) {
+                throw new McpToolError('This server does not serve media URLs — generated files are written to disk and the path in the result is already usable.', {
+                    hint: 'gemini_sign_media applies to the hosted connector only.',
+                });
+            }
+            const fresh = await sink.resign(args.r2_key.trim());
+            if (!fresh) {
+                // Remediation goes in the MESSAGE: MCP serialization drops hints.
+                throw new McpToolError(`No stored media for r2_key "${args.r2_key}" — it has probably passed its retention window. Re-run the generation to get a new one.`, { hint: 'Objects are swept on a retention schedule (MEDIA_TTL_DAYS, default 7 days).' });
+            }
+            return textResult({
+                url: fresh.ref,
+                r2_key: fresh.key,
+                ...(fresh.expiresAt ? { expires_at: fresh.expiresAt } : {}),
+                curl_hint: `curl -sS -o ${downloadFilename(fresh.key ?? 'media')} "${fresh.ref}"`,
+                hint: 'In a Claude chat client, download this URL into your sandbox and present it as an output file — inline image blocks and markdown embeds do not render for the end user.',
+            });
+        });
+    }
     server.registerTool('gemini_delete_file', {
-        description: 'Delete an uploaded file from the Gemini Files API before its ~48h expiry. Any tool call still referencing it ' +
+        description: 'Delete an uploaded file, image or photo (by file_uri) from the Gemini Files API before its ~48h expiry. Any tool call still referencing it ' +
             'will then fail with a generic 404, so delete only references you are finished with.',
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: {

package/dist/tools/generate.js

@@ -66,31 +66,46 @@ export function registerGenerateTools(server, client) {
             // For count>1, surface the FIRST call's grounding (each call grounds
             // independently; one representative set of sources beats concatenating N).
             let capturedGrounding;
+            // count>1 is N billed generations in one tools/call, and any one can
+            // fail (a safety filter, a transient 5xx). Failures are collected per
+            // image so one bad draw cannot lose the ones that succeeded — same
+            // contract as gemini_image_set's failed_scenes. Zero successes still
+            // throws: an empty success is worse than an error.
+            const failed = [];
+            let firstError;
             await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : 'image'} (${model})`, async () => {
                 for (let i = 0; i < count; i++) {
-                    // Distinct seed per image (seed+0 for the single-image case == echoed seed)
-                    // so count>1 yields N *different* images, not N duplicates.
-                    const result = await client.generate({
-                        prompt: args.prompt,
-                        images: refInputs.length > 0 ? refInputs : undefined,
-                        model: args.model,
-                        aspectRatio: args.aspect_ratio,
-                        imageSize: args.image_size,
-                        seed: seed + i,
-                        thinkingLevel: args.thinking_level,
-                        googleSearch: args.google_search,
-                        videoUrl: video.videoUrl,
-                        videoMimeType: video.videoMimeType,
-                        timeoutMs: args.timeout_ms,
-                    });
-                    const { images: [img], text } = result;
-                    if (text && !capturedText)
-                        capturedText = text;
-                    if (result.grounding && !capturedGrounding)
-                        capturedGrounding = result.grounding;
-                    named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, '0')}` });
+                    try {
+                        // Distinct seed per image (seed+0 for the single-image case == echoed seed)
+                        // so count>1 yields N *different* images, not N duplicates.
+                        const result = await client.generate({
+                            prompt: args.prompt,
+                            images: refInputs.length > 0 ? refInputs : undefined,
+                            model: args.model,
+                            aspectRatio: args.aspect_ratio,
+                            imageSize: args.image_size,
+                            seed: seed + i,
+                            thinkingLevel: args.thinking_level,
+                            googleSearch: args.google_search,
+                            videoUrl: video.videoUrl,
+                            videoMimeType: video.videoMimeType,
+                            timeoutMs: args.timeout_ms,
+                        });
+                        const { images: [img], text } = result;
+                        if (text && !capturedText)
+                            capturedText = text;
+                        if (result.grounding && !capturedGrounding)
+                            capturedGrounding = result.grounding;
+                        named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, '0')}` });
+                    }
+                    catch (err) {
+                        firstError ??= err;
+                        failed.push({ image: i + 1, error: err instanceof Error ? err.message : String(err) });
+                    }
                 }
             });
+            if (named.length === 0)
+                throw firstError;
             const meta = buildMeta(model, seed, args);
             if (capturedText)
                 meta.text = capturedText;
@@ -98,6 +113,12 @@ export function registerGenerateTools(server, client) {
                 meta.grounding = capturedGrounding;
             if (report)
                 meta.image_inputs = report;
+            if (failed.length) {
+                meta.failed_images = failed;
+                meta.partial =
+                    `${failed.length} of ${count} image(s) failed; the ${named.length} that succeeded are returned above. ` +
+                        'Re-run with count set to the shortfall rather than the whole batch — each failure message is in failed_images.';
+            }
             if (video.videoFileMeta)
                 meta.video_file = video.videoFileMeta;
             meta.hint = REFINE_HINT;

package/dist/tools/interact.js

@@ -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/set.js

@@ -61,6 +61,8 @@ export function registerSetTools(server, client) {
             const carried = await resolveImageInputs({ images_url: args.master_images_url, images_file_uris: args.master_images_file_uris }, client);
             const masterOnly = await resolveImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard }, client);
             const masterRefInputs = [...masterOnly.inputs, ...carried.inputs];
+            /** Scenes that failed, so one bad scene cannot lose the whole batch. */
+            const failed = [];
             const report = carried.report || masterOnly.report
                 ? { ...masterOnly.report, ...carried.report }
                 : undefined;
@@ -79,17 +81,44 @@ export function registerSetTools(server, client) {
                 // 2. scene prompts (explicit, or N repeats of master_prompt for variations)
                 const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
                 const mode = args.reference_mode ?? 'master';
+                // A set is N+1 billed generations in one tools/call, and any one of
+                // them can fail — a safety filter on a single scene, a transient 5xx.
+                // `Promise.all` rejected the whole batch on the first failure, losing
+                // the master and every scene that HAD succeeded, and surfaced as an
+                // opaque "Error occurred during tool execution" with no indication of
+                // which scene or why. Failures are collected per scene instead.
+                const sceneName = (i) => `${slug}-${String(i + 1).padStart(2, '0')}`;
+                const record = (err, i) => {
+                    failed.push({
+                        scene: i + 1,
+                        prompt: scenePrompts[i],
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                };
                 if (mode === 'chain') {
                     let ref = master;
                     for (let i = 0; i < scenePrompts.length; i++) {
-                        const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
-                        named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` });
-                        ref = img;
+                        try {
+                            const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
+                            named.push({ image: img, base: sceneName(i) });
+                            // Chain mode anchors each scene on the previous OUTPUT, so a
+                            // failure must not advance the reference — the next scene
+                            // continues from the last image that actually exists.
+                            ref = img;
+                        }
+                        catch (err) {
+                            record(err, i);
+                        }
                     }
                 }
                 else {
-                    const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
-                    scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` }));
+                    const settled = await Promise.allSettled(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
+                    settled.forEach((outcome, i) => {
+                        if (outcome.status === 'fulfilled')
+                            named.push({ image: outcome.value, base: sceneName(i) });
+                        else
+                            record(outcome.reason, i);
+                    });
                 }
                 return result;
             });
@@ -101,6 +130,13 @@ export function registerSetTools(server, client) {
                 meta.grounding = masterResult.grounding;
             if (report)
                 meta.image_inputs = report;
+            if (failed.length) {
+                meta.failed_scenes = failed;
+                meta.partial =
+                    `${failed.length} of ${failed.length + named.length - 1} scene(s) failed; the master and the ` +
+                        `${named.length - 1} scene(s) that succeeded are returned above. Re-run just the failed prompts rather than the whole set — ` +
+                        'each failure message is in failed_scenes.';
+            }
             // A set is master + N scenes in one tools/call — the most timeout-prone
             // tool. Effective image count drives the risk hint.
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client.mediaSink?.persistsFiles });

package/dist/tools/shared.js

@@ -4,6 +4,7 @@ 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';
+import { downloadFilename } from '../media-endpoint.js';
 /**
  * Fallback sink for call sites that pass no explicit one (every pre-existing
  * test, and any caller constructed before the sink seam existed). The stdio
@@ -265,9 +266,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.
@@ -279,8 +281,37 @@ 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 } : {}),
+                // A ready-to-run command, not a description of one. Models copy an
+                // exact string far more reliably than they compose one — and in a
+                // chat client this download-then-attach flow is the ONLY way the end
+                // user actually sees the image (inline MCP blocks and markdown embeds
+                // both render for the model and not for them).
+                ...(p.key ? { curl_hint: `curl -sS -o ${downloadFilename(p.key)} "${p.ref}"` } : {}),
+            })),
+        }
+        : {};
     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/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.2.0",
+  "version": "1.4.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.2.0",
+  "version": "1.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.2.0",
+      "version": "1.4.0",
       "transport": {
         "type": "stdio"
       },