@chrischall/gemini-mcp 1.6.1 → 1.7.0

package/dist/tools/files.js

@@ -228,6 +228,55 @@ export function registerFileTools(server, client) {
                 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.',
             });
         });
+        // The recovery path for media whose RESULT was lost rather than never
+        // produced — a background job killed with its machine still wrote its
+        // images, but every reference to them went with the response. Without this
+        // the only way to see them again is to pay for the generation twice.
+        server.registerTool('gemini_list_recent_media', {
+            description: 'List images/video/audio this connector recently generated for your account, newest first, with fresh openable URLs. ' +
+                'Use it when a result was lost — a generation whose response never arrived, or an async job whose id came back unknown — ' +
+                'to find what already exists BEFORE re-running (and re-paying for) it. Keywords: lost result, orphaned job, ' +
+                'missing image, what did I generate, recover, recent media.',
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            inputSchema: {
+                limit: z.number().int().positive().max(100).optional().describe('How many to return (default 20, newest first)'),
+                since_day: z
+                    .string()
+                    .regex(/^\d{4}-\d{2}-\d{2}$/)
+                    .optional()
+                    .describe('Only media stored on or after this UTC day, e.g. "2026-08-18"'),
+            },
+        }, async (args) => {
+            const sink = client.mediaSink;
+            if (!sink?.listRecent) {
+                throw new McpToolError('This server writes generated files to disk — list the output directory instead.', {
+                    hint: 'gemini_list_recent_media applies to the hosted connector only.',
+                });
+            }
+            const limit = args.limit ?? 20;
+            const page = sink.listRecentPage
+                ? await sink.listRecentPage({ limit, sinceDay: args.since_day })
+                : { media: await sink.listRecent({ limit, sinceDay: args.since_day }), truncated: false };
+            const found = page.media;
+            return textResult({
+                count: found.length,
+                // Never let a bounded walk pass for the whole picture: concluding an
+                // image is gone is what makes someone pay to generate it twice.
+                ...(page.truncated ? { truncated: true } : {}),
+                media: found.map((m) => ({
+                    r2_key: m.key,
+                    day: m.day,
+                    name: m.name,
+                    ...(m.sizeBytes !== undefined ? { size_bytes: m.sizeBytes } : {}),
+                    ...(m.url ? { url: m.url, curl_hint: `curl -sS -o ${downloadFilename(m.key)} "${m.url}"` } : {}),
+                    ...(m.expiresAt ? { expires_at: m.expiresAt } : {}),
+                })),
+                hint: found.length
+                    ? 'Ordered by the day each object was stored (the store keeps no finer timestamp), newest first. Re-sign any expired link with gemini_sign_media.' +
+                        (page.truncated ? ' More media exists than is listed here — narrow with since_day, or raise limit, before concluding something is missing.' : '')
+                    : 'Nothing stored in that window. Media is swept on a retention schedule, so an older generation may already be gone.',
+            });
+        });
     }
     server.registerTool('gemini_delete_file', {
         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 ' +

package/dist/tools/jobs.js

@@ -11,7 +11,11 @@ import { z } from 'zod';
 // other session's result by job id — see src/session.ts.
 export function registerJobTools(server, client) {
     server.registerTool('gemini_get_result', {
-        description: 'Retrieve an async generation started with `async: true`. Pass the returned `job_id`: while running it reports status "running"; on completion it returns the normal result (image paths / inline images + meta); on failure it raises the recorded error. Jobs belong to your session and expire ~10 min after completion — if a job id is unknown, check the output dir / <image>.json sidecar.',
+        description: 'Retrieve a generation started with `async: true` or handed off by `max_wait_ms`. Pass the returned `job_id`: ' +
+            'while running it reports status "running"; on completion it returns the normal result (image URLs/paths + meta); ' +
+            'on failure it raises the recorded error, including the case where the generation was killed before it finished. ' +
+            'On the hosted connector job records are stored durably and survive a restart; on a local stdio server they live ' +
+            'with the process and expire ~10 min after completion, where the output dir / <image>.json sidecar is the fallback.',
         annotations: { readOnlyHint: true, openWorldHint: false },
         inputSchema: {
             job_id: z.string().min(1).describe('The job_id returned by a generation tool called with async: true'),

package/dist/tools/shared.js

@@ -55,7 +55,10 @@ export const idempotencyKeySchema = z
 export const asyncSchema = z
     .boolean()
     .optional()
-    .describe('Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion).');
+    .describe('Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit ' +
+    'the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. ' +
+    'PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the ' +
+    'request is open, so this option is served there as a bounded wait rather than an immediate hand-off.');
 /**
  * Wait-then-hand-off budget shared by every generation tool: wait up to the
  * budget for the in-band result, and past it return a `{ job_id }` handle
@@ -361,10 +364,17 @@ export function timeoutRiskHint(opts) {
         .join(' + ');
     const lead = `Slow config (${why}) can exceed a host's tools/call timeout (e.g. Claude Desktop ~30s, error -32001). `;
     if (opts.persistsFiles === false) {
+        // Deliberately NOT `async: true`. This connector runs on a machine that is
+        // stopped whenever no request is in flight, so an immediate hand-off is
+        // what gets a generation killed mid-flight; holding the request open is
+        // what keeps it alive. Recommending async here was recommending the
+        // failure mode (see src/job-store.ts).
         return (lead +
             `This connector has no filesystem, so a lost response cannot be recovered from disk — there is no output dir and no ` +
-            `<image>.json sidecar. Use \`async: true\` to get a job_id immediately and poll gemini_get_result, ` +
-            `or use a Flash model / drop image_size to 1K/2K for a faster in-band result.`);
+            `<image>.json sidecar. Set \`max_wait_ms\` (e.g. 240000): keeping the request open is also what keeps the generation ` +
+            `running here, and a batch that outlives the budget hands back a job_id to poll with gemini_get_result. ` +
+            `For a faster in-band result use a Flash model or drop image_size to 1K/2K. If a result is ever lost, ` +
+            `list what was already generated with gemini_list_recent_media before paying for it again.`);
     }
     return (lead +
         `If the host gives up mid-generation the image is still written to disk (and gemini_interact leaves an ` +

package/dist/tools/uploads.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
-import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { textResult } from '@chrischall/mcp-utils';
 import { UPLOAD_MAX_BYTES, RASTER_IMAGE_TYPE_PATTERN } from '../upload-url.js';
 import { wholeMb } from '../bytes.js';
+import { step } from '../errors.js';
 /**
  * `gemini_get_upload_url` — mint a short-lived signed PUT URL so a shell can
  * upload a reference image with ZERO auth headers:
@@ -15,9 +16,27 @@ import { wholeMb } from '../bytes.js';
  * shell doesn't have. A signed URL is mintable by the session and usable by
  * the shell.
  *
- * Hosted connector only — stdio has no HTTP surface to PUT against (and no
- * need: it reads local paths directly). Gated on `client.uploadUrls`, the same
- * pattern as `gemini_sign_media` / the library tools.
+ * Hosted only — stdio has no HTTP surface to PUT against (and no need: it reads
+ * local paths directly). Gated on `client.uploadUrls`, the same pattern as
+ * `gemini_sign_media` / the library tools.
+ *
+ * ## The PUT response body is NOT the contract any more
+ *
+ * The retired Cloudflare connector served `/put` itself and answered
+ * `201 { r2_key, size_bytes, content_type, hint }`. mcp-host's blob gateway is
+ * a generic object store: it answers a bare 2xx and the body is whatever the
+ * gateway feels like. So the `r2_key` a caller must keep is the one in THIS
+ * result, minted here, known before a byte is sent — and success is "the PUT
+ * returned 2xx", nothing finer. Every hint below says so; don't reintroduce
+ * guidance to read the key out of the PUT response, it isn't there.
+ *
+ * ## Minting writes nothing
+ *
+ * There is no reservation, no pending-upload record, no placeholder object —
+ * a mint is a tenant id, a key string and one HMAC. That is what makes a failed
+ * mint atomic: it cannot leave orphaned state behind because it never had any
+ * to leave. `tests/upload-flow.test.ts` holds that property to a fake gateway
+ * that fails the call if it is touched at all.
  */
 export function registerUploadUrlTools(server, client) {
     const minter = client.uploadUrls;
@@ -26,10 +45,12 @@ export function registerUploadUrlTools(server, client) {
     server.registerTool('gemini_get_upload_url', {
         description: 'Mint a short-lived (~10 min) signed PUT URL for uploading one reference image to this connector with NO auth ' +
             'headers — usable from any shell: curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "<upload_url>". ' +
-            'The response to the PUT returns an `r2_key` to reference the upload: pass it in `images_r2_keys` on generation ' +
-            'tools, save it permanently with gemini_save_character, or convert it to a ~48h Files API reference with ' +
-            'gemini_upload_file({ r2_key }). Prefer this over images_base64 (which costs ~14k tokens per photo) whenever the ' +
-            `caller has a shell. Images only, up to ${wholeMb(UPLOAD_MAX_BYTES)}MB.`,
+            'A 2xx from that PUT means the bytes are stored; the key to reference them is the `r2_key` in THIS result (the PUT ' +
+            'itself returns no useful body). Pass that r2_key in `images_r2_keys` on generation tools, save it permanently with ' +
+            'gemini_save_character, or convert it to a ~48h Files API reference with gemini_upload_file({ r2_key }). Prefer this ' +
+            'over images_base64 (which costs ~14k tokens per photo) whenever the caller has a shell. Images only, up to ' +
+            `${wholeMb(UPLOAD_MAX_BYTES)}MB. The PUT must send exactly the Content-Type this URL was minted for — the signature ` +
+            'covers it, so a mismatched header is rejected.',
         annotations: { readOnlyHint: true, openWorldHint: false },
         inputSchema: {
             filename: z
@@ -45,13 +66,11 @@ export function registerUploadUrlTools(server, client) {
                 .describe('MIME type of the bytes that will be PUT — raster images only (jpeg/png/webp/gif/avif/heic/heif/bmp/tiff; not SVG). The PUT must send exactly this Content-Type.'),
         },
     }, async (args) => {
-        let minted;
-        try {
-            minted = await minter.mint(args.filename, args.content_type);
-        }
-        catch (err) {
-            throw new McpToolError(err instanceof Error ? err.message : String(err));
-        }
+        // `step` names the operation in the message, and `surfaceToolErrors`
+        // (wired in index.ts) prefixes the tool and flattens the cause chain —
+        // between them a mint failure can no longer reach the client as a bare
+        // "Error occurred during tool execution".
+        const minted = await step(`minting a signed upload URL for ${args.filename} (${args.content_type})`, () => minter.mint(args.filename, args.content_type));
         return textResult({
             upload_url: minted.url,
             method: 'PUT',
@@ -60,10 +79,14 @@ export function registerUploadUrlTools(server, client) {
             expires_at: new Date(minted.expiresAtMs).toISOString(),
             max_bytes: UPLOAD_MAX_BYTES,
             curl_hint: `curl -sS -X PUT -H "Content-Type: ${minted.contentType}" --data-binary @${args.filename} "${minted.url}"`,
-            hint: 'PUT the raw bytes within ~10 minutes; no Authorization header is needed (the signature in the URL is the auth). ' +
-                'Then reference the returned r2_key: images_r2_keys on generation tools (master_images_r2_keys on gemini_image_set), ' +
-                'gemini_save_character to keep it with no expiry, or gemini_upload_file({ r2_key }) for a ~48h files/… reference. ' +
-                'Uploads themselves follow the media retention schedule (default 7 days).',
+            // Named for what it is: the PUT's own body is the object store's, not
+            // this connector's, so 2xx is the whole success signal.
+            success_is: 'any 2xx from the PUT; the response body is not part of the contract and carries no r2_key',
+            hint: 'PUT the raw bytes within ~10 minutes with exactly the Content-Type above; no Authorization header is needed ' +
+                '(the signature in the URL is the auth, and it covers the content type). On a 2xx, reference the `r2_key` from ' +
+                'THIS result — not the PUT response: images_r2_keys on generation tools (master_images_r2_keys on ' +
+                'gemini_image_set), gemini_save_character to keep it with no expiry, or gemini_upload_file({ r2_key }) for a ' +
+                '~48h files/… reference. Uploads themselves follow the media retention schedule (default 7 days).',
         });
     });
 }

package/dist/upload-url.js

@@ -32,6 +32,7 @@
  * import so it tests under Node.
  */
 import { base64UrlEncode, base64UrlDecode } from './media-url.js';
+import { signedLinks } from './signed-url.js';
 import { safeKeySegment } from './storage/media.js';
 /** How long a minted upload URL stays usable. Deliberately short — it exists to
  * be curled within the same conversation turn that minted it. */
@@ -86,10 +87,17 @@ export async function verifyUploadSignature(signingKey, key, contentType, exp, s
         return { ok: false, reason: 'expired' };
     return { ok: true };
 }
-/** `<base>/<key>?ct=…&exp=…&sig=…` — the URL handed back by the mint tool. */
+/**
+ * `<base>/<key>?ct=…&exp=…&sig=…` — the URL handed back by the mint tool.
+ *
+ * Delegates to {@link signedLinks}, the single shape-owner it shares with
+ * `buildMediaUrl`. Prefer passing a {@link SignedLinks} into
+ * {@link createUploadUrlMinter} (`links`) over a bare `baseUrl`: a store handed
+ * to the sink and the minter as one object cannot be re-pointed for one and
+ * not the other, which is precisely how the re-host broke this flow.
+ */
 export function buildUploadUrl(baseUrl, key, contentType, expiresAtMs, signature) {
-    const path = key.split('/').map(encodeURIComponent).join('/');
-    return `${baseUrl.replace(/\/+$/, '')}/${path}?ct=${encodeURIComponent(contentType.toLowerCase())}&exp=${expiresAtMs}&sig=${signature}`;
+    return signedLinks(baseUrl).upload(key, contentType, expiresAtMs, signature);
 }
 /**
  * RASTER image types only — an explicit allowlist, not `image/*`.
@@ -117,6 +125,18 @@ export function acceptableUploadType(contentType) {
  * session's own namespace, so a signed PUT cannot write into anyone else's.
  */
 export function createUploadUrlMinter(opts) {
+    // Fail at construction, not at mint. A minter built without somewhere to
+    // point is not a degraded minter, it is a broken one — and the symptom it
+    // used to produce (a URL reading `undefined/up/…`, or one pointing at a host
+    // that no longer exists) is unreadable from the client side. This is the
+    // "mint-with-missing-env fails loudly and atomically" guarantee: it throws
+    // before any key is derived and long before anything could be written, and
+    // the tool simply does not register.
+    const links = opts.links ?? (opts.baseUrl ? signedLinks(opts.baseUrl) : undefined);
+    if (!links) {
+        throw new Error('createUploadUrlMinter requires `links` (preferred) or `baseUrl`: there is nowhere to point a signed upload URL. ' +
+            'Hosted, both come from the blob store — check MCP_BLOB_BASE_URL is set on the deployment.');
+    }
     const now = opts.now ?? (() => new Date());
     const randomId = opts.randomId ?? (() => crypto.randomUUID().slice(0, 8));
     const ttlMs = opts.ttlMs ?? UPLOAD_URL_TTL_MS;
@@ -132,7 +152,7 @@ export function createUploadUrlMinter(opts) {
             const key = `${UPLOAD_KEY_PREFIX}/${tenant}/${day}/${randomId()}-${safeKeySegment(filename)}`;
             const expiresAtMs = now().getTime() + ttlMs;
             const signature = await opts.sign(key, ct, expiresAtMs);
-            return { url: buildUploadUrl(opts.baseUrl, key, ct, expiresAtMs, signature), key, contentType: ct, expiresAtMs };
+            return { url: links.upload(key, ct, expiresAtMs, signature), key, contentType: ct, expiresAtMs };
         },
     };
 }

package/dist/version.js

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

package/package.json

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