@chrischall/gemini-mcp 1.2.0 → 1.4.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.2.0"
+    "version": "1.4.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.2.0",
+      "version": "1.4.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gemini-mcp",
   "displayName": "Gemini Images",
-  "version": "1.2.0",
+  "version": "1.4.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

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

package/dist/bundle.js

@@ -32783,6 +32783,15 @@ var init_clipboard = __esm({
   }
 });
 
+// src/media-url.ts
+var MEDIA_URL_TTL_MS;
+var init_media_url = __esm({
+  "src/media-url.ts"() {
+    "use strict";
+    MEDIA_URL_TTL_MS = 48 * 60 * 60 * 1e3;
+  }
+});
+
 // src/index.ts
 init_dist();
 
@@ -32796,7 +32805,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.2.0";
+var VERSION = "1.4.0";
 
 // src/tools/models.ts
 init_dist();
@@ -33214,13 +33223,21 @@ function createDiskSink() {
       const { writeMedia: writeMedia2, resolveOutputDir: resolveOutputDir2 } = await Promise.resolve().then(() => (init_images(), images_exports));
       const dir = resolveOutputDir2(opts.output_dir);
       const refs = [];
-      for (const it of items) refs.push(await writeMedia2(dir, it.base, it.base64, it.mimeType));
+      for (const it of items) refs.push({ ref: await writeMedia2(dir, it.base, it.base64, it.mimeType) });
       return refs;
     },
     note: () => void 0
   };
 }
 
+// src/media-endpoint.ts
+init_media_url();
+function downloadFilename(key) {
+  const last = key.split("/").pop() || "media";
+  const stripped = last.replace(/^[0-9a-f]{6,12}-/i, "");
+  return stripped || last;
+}
+
 // src/tools/shared.ts
 var DEFAULT_SINK = createDiskSink();
 var ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:4", "4:1", "1:8", "8:1"];
@@ -33346,14 +33363,32 @@ async function emitMedia(named, kind, opts, meta3, onWritten) {
     return { content: blocks };
   }
   const sink = opts.sink ?? DEFAULT_SINK;
-  const refs = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
+  const persisted = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
     output_dir: opts.output_dir
   });
+  const refs = persisted.map((p) => p.ref);
   if (sink.persistsFiles) await onWritten?.(refs);
   const note = opts.inline && kind === "video" ? { inline_unsupported: "video has no MCP inline content type \u2014 written to disk instead" } : {};
   const storageNote = sink.note();
+  const unavailable = persisted.some((p) => p.unavailable) ? {
+    media_url_unavailable: "The media was stored but no public URL could be generated for it, so the values above are bare object keys, not links. This is a connector misconfiguration: set MEDIA_PUBLIC_BASE_URL, or use inline: true to receive the bytes directly."
+  } : {};
+  const detailed = persisted.filter((p) => p.key !== void 0);
+  const media = detailed.length === persisted.length && detailed.length > 0 ? {
+    media: persisted.map((p) => ({
+      url: p.ref,
+      ...p.key ? { r2_key: p.key } : {},
+      ...p.expiresAt ? { expires_at: p.expiresAt } : {},
+      // 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, ...meta3 });
+  return textResult({ [`${kind}s`]: refs, ...media, ...unavailable, ...note, ...storage, ...meta3 });
 }
 async function emit(named, opts, meta3, onWritten) {
   return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), "image", opts, meta3, onWritten);
@@ -33384,6 +33419,47 @@ function isExpired(entry, now) {
 function fingerprintRequest(toolName, parts) {
   return createHash("sha256").update(`${toolName}\0${JSON.stringify(parts)}`).digest("hex");
 }
+async function refreshMedia(result, sink) {
+  const first = result.content?.[0];
+  if (!sink?.resign || !first || first.type !== "text") return result;
+  let body;
+  try {
+    body = JSON.parse(first.text);
+  } catch {
+    return result;
+  }
+  const entries = Array.isArray(body.media) ? body.media : [];
+  if (!entries.some((e) => typeof e.r2_key === "string")) return result;
+  const refreshed = await Promise.all(entries.map(async (e) => {
+    if (typeof e.r2_key !== "string") return void 0;
+    try {
+      return await sink.resign(e.r2_key);
+    } catch {
+      return void 0;
+    }
+  }));
+  if (refreshed.every((r) => r === void 0)) return result;
+  const mediaKeyName = ["images", "videos", "audios"].find((k) => Array.isArray(body[k]));
+  const refs = [];
+  refreshed.forEach((fresh, i) => {
+    if (!fresh) {
+      refs.push(String(entries[i]?.url ?? ""));
+      return;
+    }
+    const { expires_at: _stale, ...rest } = entries[i];
+    entries[i] = {
+      ...rest,
+      url: fresh.ref,
+      ...fresh.expiresAt ? { expires_at: fresh.expiresAt } : {},
+      curl_hint: `curl -sS -o ${downloadFilename(fresh.key ?? "media")} "${fresh.ref}"`
+    };
+    refs.push(fresh.ref);
+  });
+  body.media = entries;
+  if (mediaKeyName) body[mediaKeyName] = refs;
+  body.media_urls_refreshed = true;
+  return { ...result, content: [{ ...first, text: JSON.stringify(body, null, 2) }, ...(result.content ?? []).slice(1)] };
+}
 function annotateReused(result, jobId) {
   const content = result.content ?? [];
   const first = content[0];
@@ -33411,6 +33487,12 @@ function jobHandle(jobId, status) {
   });
 }
 var JobRegistry = class {
+  /**
+   * Lets a replayed result have its media URLs re-minted. Set by the session
+   * that owns this registry; absent on stdio, where refs are file paths that
+   * never expire.
+   */
+  resigner;
   jobs = /* @__PURE__ */ new Map();
   byKey = /* @__PURE__ */ new Map();
   // idempotencyKey -> jobId
@@ -33470,7 +33552,7 @@ var JobRegistry = class {
     }
     if (hit) {
       if (async) return jobHandle(hit.jobId, hit.status);
-      return annotateReused(await hit.promise, hit.jobId);
+      return annotateReused(await refreshMedia(await hit.promise, this.resigner), hit.jobId);
     }
     const jobId = randomUUID();
     this.evict(now);
@@ -33598,31 +33680,43 @@ function registerGenerateTools(server, client2) {
         const named = [];
         let capturedText;
         let capturedGrounding;
+        const failed = [];
+        let firstError;
         await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : "image"} (${model})`, async () => {
           for (let i = 0; i < count; i++) {
-            const result = await client2.generate({
-              prompt: args.prompt,
-              images: refInputs.length > 0 ? refInputs : void 0,
-              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 {
+              const result = await client2.generate({
+                prompt: args.prompt,
+                images: refInputs.length > 0 ? refInputs : void 0,
+                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 meta3 = buildMeta(model, seed, args);
         if (capturedText) meta3.text = capturedText;
         if (capturedGrounding) meta3.grounding = capturedGrounding;
         if (report) meta3.image_inputs = report;
+        if (failed.length) {
+          meta3.failed_images = failed;
+          meta3.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 \u2014 each failure message is in failed_images.`;
+        }
         if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
         meta3.hint = REFINE_HINT;
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, count, persistsFiles: client2.mediaSink?.persistsFiles });
@@ -33756,6 +33850,7 @@ function registerSetTools(server, client2) {
           client2
         );
         const masterRefInputs = [...masterOnly.inputs, ...carried.inputs];
+        const failed = [];
         const report = carried.report || masterOnly.report ? { ...masterOnly.report, ...carried.report } : void 0;
         const named = [];
         const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
@@ -33769,18 +33864,33 @@ function registerSetTools(server, client2) {
           named.push({ image: master, base: `${slug}-master` });
           const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
           const mode = args.reference_mode ?? "master";
+          const sceneName = (i) => `${slug}-${String(i + 1).padStart(2, "0")}`;
+          const record2 = (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 client2.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 client2.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
+                named.push({ image: img, base: sceneName(i) });
+                ref = img;
+              } catch (err) {
+                record2(err, i);
+              }
             }
           } else {
-            const scenes = await Promise.all(
+            const settled = await Promise.allSettled(
               scenePrompts.map((p, i) => client2.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")}` }));
+            settled.forEach((outcome, i) => {
+              if (outcome.status === "fulfilled") named.push({ image: outcome.value, base: sceneName(i) });
+              else record2(outcome.reason, i);
+            });
           }
           return result;
         });
@@ -33789,6 +33899,10 @@ function registerSetTools(server, client2) {
         if (masterText) meta3.text = masterText;
         if (masterResult.grounding) meta3.grounding = masterResult.grounding;
         if (report) meta3.image_inputs = report;
+        if (failed.length) {
+          meta3.failed_scenes = failed;
+          meta3.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 \u2014 each failure message is in failed_scenes.`;
+        }
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client2.mediaSink?.persistsFiles });
         if (risk) meta3.timeout_risk = risk;
         return emit(named, { ...args, sink: client2.mediaSink }, meta3);
@@ -33958,6 +34072,7 @@ var GeminiClient = class {
   session = new SessionState();
   constructor(opts = {}) {
     this.mediaSink = opts.mediaSink ?? createDiskSink();
+    this.session.jobs.resigner = this.mediaSink;
     this.explicitApiKey = opts.apiKey?.trim() || void 0;
     this.fetchImpl = opts.fetchImpl ?? fetch;
     this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -34027,6 +34142,22 @@ var GeminiClient = class {
   async fetchRemoteImage(url2, opts = {}) {
     return fetchRemoteImage(url2, { ...opts, fetchImpl: this.fetchImpl, timeoutMs: resolveTimeoutMs(opts.timeoutMs) });
   }
+  /**
+   * Read back media this connector generated, straight out of its own store.
+   *
+   * The alternative — fetching our own `/media` URL — needs a signature the
+   * caller cannot mint and returns 403, which is the loop this exists to close.
+   */
+  async readStoredMedia(key) {
+    const stored = await this.mediaSink.read?.(key.trim());
+    if (!stored) {
+      throw new McpToolError(
+        `No stored media for r2_key "${key}" \u2014 objects are removed on a retention schedule, so an old key may be gone. Re-run the generation, or upload the bytes with \`url\` / \`data_base64\`.`,
+        { hint: "Use the exact media[].r2_key from a generation result." }
+      );
+    }
+    return stored;
+  }
   /** The default model after env override (no per-call arg). */
   defaultModel() {
     return resolveModel(void 0, readEnvVar("GEMINI_IMAGE_MODEL"));
@@ -34508,7 +34639,7 @@ function splitReattachedOutputs(images, writtenOutputs) {
 }
 function registerInteractTools(server, client2) {
   const onDiskRuntime = client2.mediaSink?.persistsFiles ?? true;
-  const recoveryDescription = onDiskRuntime ? "If a call times out on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction \u2014 check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). " : "This connector has no filesystem: there is no output dir and no `<image>.json` sidecar, so a lost response cannot be recovered from disk and a 404 on a chained call cannot be re-anchored automatically. Capture the returned `interaction_id` from every result, and use `async: true` + gemini_get_result for long generations. ";
+  const recoveryDescription = onDiskRuntime ? "If a call times out on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction \u2014 check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). " : "On this connector each result returns an image URL you can open or share directly (see `media[].url`) \u2014 show it to the user rather than assuming they can see the image. There is no filesystem, so no output dir and no `<image>.json` sidecar: a lost response cannot be recovered from disk and a 404 on a chained call cannot be re-anchored automatically. Capture the returned `interaction_id` from every result, and use `async: true` + gemini_get_result for long generations. ";
   server.registerTool(
     "gemini_interact",
     {
@@ -34882,13 +35013,16 @@ function registerFileTools(server, client2) {
   server.registerTool(
     "gemini_upload_file",
     {
-      description: "Upload an image (or video/audio) to the Gemini Files API ONCE and get back a reusable `files/<id>` reference. Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever enter the conversation, and it can be reused across many generations until it expires (~48h). Provide exactly one of `url` (the server downloads it), `data_base64`" + (onDisk ? ", or `path` (a local file)." : ".") + (onDisk ? "" : " This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header and a Content-Type of image/*, which avoids base64 entirely."),
+      description: "Upload a file \u2014 an image, reference photo, picture, screenshot, video or audio clip \u2014 to the Gemini Files API ONCE, and get back a reusable `file_uri` (`files/<id>`) to attach to later image, video or music generations. Keywords: upload, upload file, upload image, upload photo, attach, reference image, reference photo, file_uri, files api, image reference, reuse across calls. Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever enter the conversation, and it can be reused across many generations until it expires (~48h). Provide exactly one of `url` (the server downloads it), `data_base64`" + (onDisk ? ", or `path` (a local file)." : ", 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 and a Content-Type of image/*, which avoids base64 entirely."),
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         url: external_exports.string().url().optional().describe(
           `Public https URL the SERVER downloads and uploads (image/video/audio, up to ${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)."),
+        r2_key: external_exports.string().min(1).optional().describe(
+          onDisk ? "Unavailable on this server (media is written to local disk) \u2014 pass the file path via `path` instead." : "An `r2_key` from a previous generation result (media[].r2_key) \u2014 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 \u2014 that would be the connector fetching itself and needs a signature."
+        ),
         path: external_exports.string().min(1).optional().describe(
           onDisk ? "Path to a local file (absolute, or resolved against $GEMINI_INPUT_DIR). Confirm-gated like every other local-file input." : "Unavailable on this hosted connector (no filesystem) \u2014 use `url`, `data_base64`, or POST /upload."
         ),
@@ -34898,10 +35032,10 @@ function registerFileTools(server, client2) {
       }
     },
     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 source, not ${sources.length} (${sources.join(", ")}).`
+          sources.length === 0 ? "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) {
@@ -34930,6 +35064,19 @@ function registerFileTools(server, client2) {
             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 \u2014 this server writes media to local disk, so pass the generated file via `path` instead."
+            );
+          }
+          const stored = await client2.readStoredMedia(args.r2_key);
+          return client2.uploadBytes(
+            stored.bytes,
+            args.mime_type ?? stored.mimeType,
+            args.display_name ?? downloadFilename(args.r2_key)
+          );
+        }
         if (args.data_base64) {
           const { decodeImageInput: decodeImageInput2 } = await Promise.resolve().then(() => (init_images(), images_exports));
           const decoded = decodeImageInput2(args.data_base64);
@@ -34952,7 +35099,7 @@ function registerFileTools(server, client2) {
   server.registerTool(
     "gemini_list_files",
     {
-      description: "List the files currently uploaded to the Gemini Files API under this API key, with their `files/<id>` references, MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.",
+      description: "List files, images and photos currently uploaded to the Gemini Files API under this API key, with their reusable `file_uri` (`files/<id>`) references, MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
         page_size: external_exports.number().int().positive().max(100).optional().describe("Maximum files to return (1-100, default 100)")
@@ -34976,10 +35123,44 @@ function registerFileTools(server, client2) {
       });
     }
   );
+  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 \u2014 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: external_exports.string().min(1).describe("The `media[].r2_key` from an earlier generation result")
+        }
+      },
+      async (args) => {
+        const sink = client2.mediaSink;
+        if (!sink?.resign) {
+          throw new McpToolError("This server does not serve media URLs \u2014 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) {
+          throw new McpToolError(
+            `No stored media for r2_key "${args.r2_key}" \u2014 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 \u2014 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 will then fail with a generic 404, so delete only references you are finished with.",
+      description: "Delete an uploaded file, image or photo (by file_uri) from the Gemini Files API before its ~48h expiry. Any tool call still referencing it will then fail with a generic 404, so delete only references you are finished with.",
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
         file_uri: external_exports.string().min(1).describe("The `files/<id>` reference (or full uri) to delete"),

package/dist/client.js

@@ -155,6 +155,9 @@ export class GeminiClient {
     session = new SessionState();
     constructor(opts = {}) {
         this.mediaSink = opts.mediaSink ?? createDiskSink();
+        // A replayed idempotent result must not hand back an expired media URL, so
+        // the job registry needs a way to re-sign from the stable r2_key.
+        this.session.jobs.resigner = this.mediaSink;
         this.explicitApiKey = opts.apiKey?.trim() || undefined;
         this.fetchImpl = opts.fetchImpl ?? fetch;
         this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -227,6 +230,21 @@ export class GeminiClient {
         // one unbounded network operation in the server.
         return fetchRemoteImage(url, { ...opts, fetchImpl: this.fetchImpl, timeoutMs: resolveTimeoutMs(opts.timeoutMs) });
     }
+    /**
+     * Read back media this connector generated, straight out of its own store.
+     *
+     * The alternative — fetching our own `/media` URL — needs a signature the
+     * caller cannot mint and returns 403, which is the loop this exists to close.
+     */
+    async readStoredMedia(key) {
+        const stored = await this.mediaSink.read?.(key.trim());
+        if (!stored) {
+            // Remediation goes in the MESSAGE: MCP serialization drops hints.
+            throw new McpToolError(`No stored media for r2_key "${key}" — objects are removed on a retention schedule, so an old key may be gone. ` +
+                'Re-run the generation, or upload the bytes with `url` / `data_base64`.', { hint: 'Use the exact media[].r2_key from a generation result.' });
+        }
+        return stored;
+    }
     /** The default model after env override (no per-call arg). */
     defaultModel() {
         return resolveModel(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));

package/dist/connector-origin.js

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