@chrischall/gemini-mcp 1.2.0 → 1.3.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/README.md

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

package/dist/bundle.js

@@ -32796,7 +32796,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.2.0";
+var VERSION = "1.3.0";
 
 // src/tools/models.ts
 init_dist();
@@ -33214,7 +33214,7 @@ function createDiskSink() {
       const { writeMedia: writeMedia2, resolveOutputDir: resolveOutputDir2 } = await Promise.resolve().then(() => (init_images(), images_exports));
       const dir = resolveOutputDir2(opts.output_dir);
       const refs = [];
-      for (const it of items) refs.push(await writeMedia2(dir, it.base, it.base64, it.mimeType));
+      for (const it of items) refs.push({ ref: await writeMedia2(dir, it.base, it.base64, it.mimeType) });
       return refs;
     },
     note: () => void 0
@@ -33346,14 +33346,26 @@ async function emitMedia(named, kind, opts, meta3, onWritten) {
     return { content: blocks };
   }
   const sink = opts.sink ?? DEFAULT_SINK;
-  const refs = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
+  const persisted = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
     output_dir: opts.output_dir
   });
+  const refs = persisted.map((p) => p.ref);
   if (sink.persistsFiles) await onWritten?.(refs);
   const note = opts.inline && kind === "video" ? { inline_unsupported: "video has no MCP inline content type \u2014 written to disk instead" } : {};
   const storageNote = sink.note();
+  const unavailable = persisted.some((p) => p.unavailable) ? {
+    media_url_unavailable: "The media was stored but no public URL could be generated for it, so the values above are bare object keys, not links. This is a connector misconfiguration: set MEDIA_PUBLIC_BASE_URL, or use inline: true to receive the bytes directly."
+  } : {};
+  const detailed = persisted.filter((p) => p.key !== void 0);
+  const media = detailed.length === persisted.length && detailed.length > 0 ? {
+    media: persisted.map((p) => ({
+      url: p.ref,
+      ...p.key ? { r2_key: p.key } : {},
+      ...p.expiresAt ? { expires_at: p.expiresAt } : {}
+    }))
+  } : {};
   const storage = sink.persistsFiles ? {} : { storage: sink.kind, storage_note: storageNote };
-  return textResult({ [`${kind}s`]: refs, ...note, ...storage, ...meta3 });
+  return textResult({ [`${kind}s`]: refs, ...media, ...unavailable, ...note, ...storage, ...meta3 });
 }
 async function emit(named, opts, meta3, onWritten) {
   return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), "image", opts, meta3, onWritten);
@@ -34508,7 +34520,7 @@ function splitReattachedOutputs(images, writtenOutputs) {
 }
 function registerInteractTools(server, client2) {
   const onDiskRuntime = client2.mediaSink?.persistsFiles ?? true;
-  const recoveryDescription = onDiskRuntime ? "If a call times out on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction \u2014 check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). " : "This connector has no filesystem: there is no output dir and no `<image>.json` sidecar, so a lost response cannot be recovered from disk and a 404 on a chained call cannot be re-anchored automatically. Capture the returned `interaction_id` from every result, and use `async: true` + gemini_get_result for long generations. ";
+  const recoveryDescription = onDiskRuntime ? "If a call times out on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction \u2014 check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). " : "On this connector each result returns an image URL you can open or share directly (see `media[].url`) \u2014 show it to the user rather than assuming they can see the image. There is no filesystem, so no output dir and no `<image>.json` sidecar: a lost response cannot be recovered from disk and a 404 on a chained call cannot be re-anchored automatically. Capture the returned `interaction_id` from every result, and use `async: true` + gemini_get_result for long generations. ";
   server.registerTool(
     "gemini_interact",
     {
@@ -34882,7 +34894,7 @@ function registerFileTools(server, client2) {
   server.registerTool(
     "gemini_upload_file",
     {
-      description: "Upload an image (or video/audio) to the Gemini Files API ONCE and get back a reusable `files/<id>` reference. Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever enter the conversation, and it can be reused across many generations until it expires (~48h). Provide exactly one of `url` (the server downloads it), `data_base64`" + (onDisk ? ", or `path` (a local file)." : ".") + (onDisk ? "" : " This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header and a Content-Type of image/*, which avoids base64 entirely."),
+      description: "Upload a file \u2014 an image, reference photo, picture, screenshot, video or audio clip \u2014 to the Gemini Files API ONCE, and get back a reusable `file_uri` (`files/<id>`) to attach to later image, video or music generations. Keywords: upload, upload file, upload image, upload photo, attach, reference image, reference photo, file_uri, files api, image reference, reuse across calls. Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever enter the conversation, and it can be reused across many generations until it expires (~48h). Provide exactly one of `url` (the server downloads it), `data_base64`" + (onDisk ? ", or `path` (a local file)." : ".") + (onDisk ? "" : " This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header and a Content-Type of image/*, which avoids base64 entirely."),
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         url: external_exports.string().url().optional().describe(
@@ -34952,7 +34964,7 @@ function registerFileTools(server, client2) {
   server.registerTool(
     "gemini_list_files",
     {
-      description: "List the files currently uploaded to the Gemini Files API under this API key, with their `files/<id>` references, MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.",
+      description: "List files, images and photos currently uploaded to the Gemini Files API under this API key, with their reusable `file_uri` (`files/<id>`) references, MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
         page_size: external_exports.number().int().positive().max(100).optional().describe("Maximum files to return (1-100, default 100)")
@@ -34979,7 +34991,7 @@ function registerFileTools(server, client2) {
   server.registerTool(
     "gemini_delete_file",
     {
-      description: "Delete an uploaded file from the Gemini Files API before its ~48h expiry. Any tool call still referencing it will then fail with a generic 404, so delete only references you are finished with.",
+      description: "Delete an uploaded file, image or photo (by file_uri) from the Gemini Files API before its ~48h expiry. Any tool call still referencing it will then fail with a generic 404, so delete only references you are finished with.",
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
         file_uri: external_exports.string().min(1).describe("The `files/<id>` reference (or full uri) to delete"),

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);
+        },
+    };
+}

package/dist/media-cleanup.js

@@ -0,0 +1,75 @@
+/**
+ * Retention for generated media.
+ *
+ * Every hosted generation writes an object to R2 and nothing ever removed it,
+ * so the bucket grew without bound — and the signed links pointing into it are
+ * only useful for a couple of days anyway. A scheduled sweep keeps the two in
+ * step: objects live `MEDIA_TTL_DAYS` (default 7), and a signed URL's lifetime
+ * is clamped to that, so a link never outlives the object behind it.
+ *
+ * R2 lifecycle rules would be the cheaper mechanism, but they are configured on
+ * the bucket rather than in `wrangler.jsonc`, so a fresh deploy of this repo
+ * would silently have no retention at all. A cron in the Worker ships with the
+ * code.
+ */
+const DEFAULT_MAX_OBJECTS = 5_000;
+/**
+ * `gen/` is where media is written now; `media/` is where it was written before
+ * the rename that made URLs read `/media/gen/…` instead of `/media/media/…`.
+ * Both are swept — retention that ignores the existing backlog is not retention.
+ */
+const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/'];
+/** R2 accepts bulk deletes in batches; 1000 is the documented ceiling. */
+const DELETE_BATCH = 1_000;
+/** Days → ms, defaulting to 7 for anything missing or nonsensical. */
+export function retentionMsFromDays(days) {
+    const n = Number(days);
+    return (Number.isFinite(n) && n > 0 ? n : 7) * 24 * 60 * 60 * 1000;
+}
+/**
+ * Delete generated media older than `retentionMs`. Returns counts rather than
+ * logging them, so the caller decides what to do with the numbers and the sweep
+ * itself stays testable.
+ */
+export async function cleanupExpiredMedia(bucket, retentionMs, opts = {}) {
+    const now = opts.now?.() ?? Date.now();
+    const cutoff = now - retentionMs;
+    const maxObjects = opts.maxObjects ?? DEFAULT_MAX_OBJECTS;
+    const prefixes = opts.prefixes ?? LEGACY_AND_CURRENT_PREFIXES;
+    let scanned = 0;
+    let deleted = 0;
+    let truncated = false;
+    const doomed = [];
+    const flush = async (all) => {
+        while (doomed.length >= (all ? 1 : DELETE_BATCH)) {
+            const batch = doomed.splice(0, DELETE_BATCH);
+            await bucket.delete(batch);
+            deleted += batch.length;
+        }
+    };
+    for (const prefix of prefixes) {
+        let cursor;
+        for (;;) {
+            if (scanned >= maxObjects) {
+                truncated = true;
+                break;
+            }
+            const page = await bucket.list({ prefix, cursor, limit: Math.min(1000, maxObjects - scanned) });
+            for (const object of page.objects) {
+                scanned++;
+                if (object.uploaded.getTime() < cutoff)
+                    doomed.push(object.key);
+            }
+            await flush(false);
+            if (!page.truncated)
+                break;
+            if (scanned >= maxObjects) {
+                truncated = true;
+                break;
+            }
+            cursor = page.cursor;
+        }
+    }
+    await flush(true);
+    return { scanned, deleted, truncated };
+}

package/dist/media-endpoint.js

@@ -0,0 +1,72 @@
+import { loadSigningKey, verifyMediaSignature } from './media-url.js';
+function problem(status, message) {
+    return new Response(`${message}\n`, {
+        status,
+        headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' },
+    });
+}
+/**
+ * Build the `/media` handler. `basePath` is stripped from the pathname to get
+ * the R2 key, so the key keeps its own prefix and the two never drift.
+ */
+export function createMediaHandler(env, basePath = '/media/') {
+    return async function handleMedia(request) {
+        if (request.method !== 'GET' && request.method !== 'HEAD') {
+            return problem(405, `Method ${request.method} not allowed; media links are GET-only.`);
+        }
+        const url = new URL(request.url);
+        if (!url.pathname.startsWith(basePath))
+            return problem(404, 'Not found');
+        // decodeURIComponent per segment, mirroring how the URL was built. A key
+        // cannot contain `..` (the sink sanitises every segment), and R2 has no
+        // path traversal to exploit anyway — a key is an opaque string, not a path.
+        const key = url.pathname
+            .slice(basePath.length)
+            .split('/')
+            .map((segment) => {
+            try {
+                return decodeURIComponent(segment);
+            }
+            catch {
+                return segment;
+            }
+        })
+            .join('/');
+        if (!key)
+            return problem(404, 'Not found');
+        const now = env.now?.() ?? Date.now();
+        // Read-only: verification must never CREATE a signing secret. A stale KV
+        // read here would otherwise clobber the secret every outstanding link was
+        // signed with (see loadSigningKey). No secret ⇒ nothing was legitimately
+        // signed ⇒ refuse, without touching storage or the bucket.
+        const signingKey = await loadSigningKey(env.secret, env.store);
+        const check = signingKey
+            ? await verifyMediaSignature(signingKey, key, url.searchParams.get('exp'), url.searchParams.get('sig'), now)
+            : { ok: false, reason: 'invalid' };
+        if (!check.ok) {
+            if (check.reason === 'expired') {
+                return problem(410, 'This media link has expired. Generated media is retained for a limited time — re-run the generation to get a fresh link.');
+            }
+            return problem(403, 'Invalid or missing media signature. Media links must be used exactly as returned by the tool, including the exp and sig parameters.');
+        }
+        const object = await env.bucket.get(key);
+        if (!object) {
+            return problem(404, 'That media object no longer exists — it may have been cleaned up. Re-run the generation to get a fresh one.');
+        }
+        const headers = new Headers({
+            'content-type': object.httpMetadata?.contentType ?? 'application/octet-stream',
+            // The URL is signed and expiring, so it is safe to cache for its lifetime;
+            // `private` keeps shared caches from serving it to anyone else.
+            'cache-control': 'private, max-age=3600',
+            'content-disposition': `inline; filename="${key.split('/').pop() ?? 'media'}"`,
+            // The bytes are model output being handed to a browser — never let a
+            // sniffed content type turn an image response into something executable.
+            'x-content-type-options': 'nosniff',
+        });
+        if (object.size !== undefined)
+            headers.set('content-length', String(object.size));
+        if (request.method === 'HEAD')
+            return new Response(null, { status: 200, headers });
+        return new Response(object.body, { status: 200, headers });
+    };
+}

package/dist/media-url.js

@@ -0,0 +1,135 @@
+/**
+ * Signed URLs for generated media on the hosted connector.
+ *
+ * The problem these exist to solve: a chat client shows the user whatever the
+ * assistant *says*, and MCP inline image blocks are not that. On claude.ai and
+ * the mobile app the bytes arrive in the model's context and are never rendered
+ * — so a generation that billed successfully is invisible. A URL is the only
+ * portable answer: a human can tap it and an agent can curl it.
+ *
+ * That means the media route cannot sit behind the connector's OAuth, because
+ * a browser opening a link carries no bearer token. The signature IS the
+ * authorization: a URL is valid for one key until it expires, and nothing else
+ * in the bucket is reachable without one.
+ *
+ * Kept free of any Cloudflare import so the whole thing is testable under Node:
+ * WebCrypto is the only primitive used, and it exists on both runtimes.
+ */
+/** How long a freshly minted media URL stays valid. Matches Files API retention. */
+export const MEDIA_URL_TTL_MS = 48 * 60 * 60 * 1000;
+/** KV key holding the lazily-generated signing secret (zero-config path). */
+export const SIGNING_SECRET_KV_KEY = 'media:url-signing-secret';
+function base64UrlEncode(bytes) {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let binary = '';
+    for (let i = 0; i < view.length; i++)
+        binary += String.fromCharCode(view[i]);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlDecode(text) {
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+/** Import raw secret material as an HMAC key. */
+async function importKey(material) {
+    return crypto.subtle.importKey('raw', new TextEncoder().encode(material), { name: 'HMAC', hash: 'SHA-256' }, false, [
+        'sign',
+        'verify',
+    ]);
+}
+/**
+ * The HMAC key for **signing**, creating one if this deployment has never
+ * signed anything.
+ *
+ * `MEDIA_URL_SECRET` wins when an operator sets one. Otherwise a random 32-byte
+ * secret is generated once and persisted in KV — which is what makes the whole
+ * feature work with **zero configuration**, the entire point of this change.
+ *
+ * Creating is confined to this function, and this function is called only when
+ * minting a URL. {@link loadSigningKey} is what the verify path uses. That
+ * split is load-bearing, not stylistic — see the warning there.
+ *
+ * Deliberately NOT cached in a module-level variable: `src/` holds no
+ * module-scope mutable state (see session.ts), and a KV read per sign is cheap
+ * next to an image generation. There is a narrow first-use race — two isolates
+ * generating simultaneously — so the value is re-read after writing and the
+ * stored one wins, collapsing the window to URLs minted in that same instant.
+ */
+export async function resolveSigningKey(secret, store) {
+    let material = secret?.trim();
+    if (!material) {
+        material = (await store.get(SIGNING_SECRET_KV_KEY)) ?? undefined;
+        if (!material) {
+            const generated = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
+            await store.put(SIGNING_SECRET_KV_KEY, generated);
+            // Re-read so a concurrent generator's value wins consistently for both.
+            material = (await store.get(SIGNING_SECRET_KV_KEY)) ?? generated;
+        }
+    }
+    return importKey(material);
+}
+/**
+ * The HMAC key for **verifying**. Read-only: returns `undefined` when no secret
+ * is stored, and never creates one.
+ *
+ * This is not a stylistic split. KV is eventually consistent — a `put` on one
+ * isolate is not immediately visible to another — so the verify path can and
+ * will see a miss for a secret that exists. If verification created-on-miss
+ * (as it did originally), that transient miss would mint a NEW secret and
+ * overwrite the one every outstanding link was signed with, permanently 403ing
+ * media that had been signed perfectly correctly. A self-inflicted denial of
+ * service, triggered by ordinary traffic, and irreversible once the old secret
+ * is gone.
+ *
+ * No secret stored ⇒ nothing was ever legitimately signed ⇒ refuse.
+ */
+export async function loadSigningKey(secret, store) {
+    const material = secret?.trim() || (await store.get(SIGNING_SECRET_KV_KEY));
+    return material ? importKey(material) : undefined;
+}
+/** The bytes covered by a signature: the object key and the expiry, nothing else. */
+function payload(key, expiresAtMs) {
+    return new TextEncoder().encode(`${key}\n${expiresAtMs}`);
+}
+/** Sign one object key for use until `expiresAtMs`. */
+export async function signMediaKey(signingKey, key, expiresAtMs) {
+    return base64UrlEncode(await crypto.subtle.sign('HMAC', signingKey, payload(key, expiresAtMs)));
+}
+/**
+ * Check a `?exp=&sig=` pair against an object key.
+ *
+ * Verification goes through `crypto.subtle.verify` rather than a string
+ * comparison, so it is constant-time — a `===` on the signature would leak the
+ * expected value one byte at a time to anyone willing to time it.
+ */
+export async function verifyMediaSignature(signingKey, key, exp, sig, nowMs) {
+    if (!exp || !sig)
+        return { ok: false, reason: 'missing' };
+    const expiresAtMs = Number(exp);
+    if (!Number.isFinite(expiresAtMs))
+        return { ok: false, reason: 'invalid' };
+    let valid;
+    try {
+        valid = await crypto.subtle.verify('HMAC', signingKey, base64UrlDecode(sig), payload(key, expiresAtMs));
+    }
+    catch {
+        return { ok: false, reason: 'invalid' };
+    }
+    // Signature first, then expiry: an expired-but-authentic link deserves a
+    // different message from a forged one, and saying "expired" about a forgery
+    // would confirm the attacker got the signature right.
+    if (!valid)
+        return { ok: false, reason: 'invalid' };
+    if (nowMs > expiresAtMs)
+        return { ok: false, reason: 'expired' };
+    return { ok: true };
+}
+/** `<base>/<key>?exp=…&sig=…` — the URL handed back to the caller. */
+export function buildMediaUrl(baseUrl, key, expiresAtMs, signature) {
+    const path = key.split('/').map(encodeURIComponent).join('/');
+    return `${baseUrl.replace(/\/+$/, '')}/${path}?exp=${expiresAtMs}&sig=${signature}`;
+}

package/dist/storage/media.js

@@ -30,13 +30,15 @@ export function createDiskSink() {
             // Sequential on purpose: uniquePath checks the filesystem, so writing two
             // colliding names concurrently would race onto the same path.
             for (const it of items)
-                refs.push(await writeMedia(dir, it.base, it.base64, it.mimeType));
+                refs.push({ ref: await writeMedia(dir, it.base, it.base64, it.mimeType) });
             return refs;
         },
         note: () => undefined,
     };
 }
-const KEY_PREFIX_DEFAULT = 'media';
+// `gen`, not `media`: the objects are served at `/media/<key>`, and a `media`
+// prefix would make every URL read `/media/media/…`.
+const KEY_PREFIX_DEFAULT = 'gen';
 /** Object-key-safe name: no slashes, no dot-segments, never empty. */
 function safeKeySegment(base) {
     const cleaned = base
@@ -57,7 +59,9 @@ export function createR2Sink(bucket, opts) {
     const prefix = opts.prefix ?? KEY_PREFIX_DEFAULT;
     const now = opts.now ?? (() => new Date());
     const randomId = opts.randomId ?? (() => crypto.randomUUID().slice(0, 8));
-    const base = opts.publicBaseUrl?.replace(/\/+$/, '');
+    const publicBase = opts.publicBaseUrl?.replace(/\/+$/, '');
+    const signedBase = opts.signedBaseUrl?.replace(/\/+$/, '');
+    const ttlMs = opts.urlTtlMs ?? 0;
     return {
         kind: 'r2',
         persistsFiles: false,
@@ -67,20 +71,38 @@ export function createR2Sink(bucket, opts) {
             // module graph.
             const { mediaExt } = await import('../images.js');
             const day = now().toISOString().slice(0, 10);
+            const expiresAtMs = now().getTime() + ttlMs;
             const refs = [];
             for (const it of items) {
                 const key = `${prefix}/${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;
-                const bytes = base64ToBytes(it.base64);
-                await bucket.put(key, bytes, { httpMetadata: { contentType: it.mimeType } });
-                refs.push(base ? `${base}/${key}` : `r2://${opts.bucketName ?? 'media'}/${key}`);
+                await bucket.put(key, base64ToBytes(it.base64), { httpMetadata: { contentType: it.mimeType } });
+                refs.push(await describe(key, expiresAtMs));
             }
             return refs;
         },
-        note: () => base
-            ? 'Generated media was uploaded to R2; the values above are public URLs, not local file paths. ' +
+        note: () => publicBase
+            ? 'Generated media was uploaded to R2 and the values above are public URLs (not local file paths) — open or download them directly. ' +
                 '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.'
-            : 'Generated media was uploaded to R2, which is not publicly served: the values above are object refs (r2://bucket/key), NOT fetchable URLs. ' +
-                'Set MEDIA_PUBLIC_BASE_URL on the Worker to get URLs, or pass inline: true to receive the bytes directly. ' +
-                '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.',
+            : signedBase
+                ? 'Generated media is served by this connector at the signed URLs above — open them in a browser or fetch them with curl; no auth header is needed, the signature is in the link. ' +
+                    'They expire (see media[].expires_at), and the objects behind them are cleaned up on a retention schedule. ' +
+                    '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.'
+                : 'Generated media was stored, but this connector has no public media URL configured and no signing route available, so the values above are bare object keys rather than fetchable links. ' +
+                    'Set MEDIA_PUBLIC_BASE_URL on the Worker, or pass inline: true to receive the bytes directly.',
     };
+    /** One stored object → the ref the caller sees, plus its key and expiry. */
+    async function describe(key, expiresAtMs) {
+        // A bucket served directly (r2.dev or a custom domain) needs no signature.
+        if (publicBase)
+            return { ref: `${publicBase}/${key}`, key };
+        if (signedBase && opts.sign) {
+            const { buildMediaUrl } = await import('../media-url.js');
+            const signature = await opts.sign(key, expiresAtMs);
+            return { ref: buildMediaUrl(signedBase, key, expiresAtMs, signature), key, expiresAt: new Date(expiresAtMs).toISOString() };
+        }
+        // Neither configured. Unreachable in the Worker (which always passes its
+        // own origin), so this is a misconfiguration rather than a mode — say so
+        // explicitly rather than returning something that looks like a filename.
+        return { ref: key, key, unavailable: true };
+    }
 }

package/dist/tools/files.js

@@ -63,7 +63,10 @@ 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`' +
@@ -143,7 +146,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: {
@@ -169,7 +172,7 @@ export function registerFileTools(server, client) {
         });
     });
     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/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/shared.js

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

package/package.json

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