@chrischall/gemini-mcp 1.6.2 → 1.8.0

package/dist/storage/media.js

@@ -45,6 +45,30 @@ export async function tenantIdFor(secret) {
 // `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';
+/**
+ * How many listing pages one `listRecent` call will walk. A listing walk is
+ * unbounded work and this runs on a tool call, so it is capped — and the cap
+ * is REPORTED (see `listRecentPage`) rather than silently truncating.
+ */
+const MAX_LIST_PAGES = 10;
+/**
+ * Split a stored key back into the day it was written and the name it was asked
+ * for — the inverse of the key format `persist` builds.
+ *
+ * `undefined` for anything that is not a dated object key, so a stray object
+ * under the prefix is skipped rather than turned into a listing failure.
+ */
+function parseMediaKey(key, prefix) {
+    const rest = key.slice(prefix.length);
+    const match = /^(\d{4}-\d{2}-\d{2})\/(.+)$/.exec(rest);
+    if (!match)
+        return undefined;
+    // Drop the random id `persist` prepends and the extension, leaving the
+    // caller's own slug — which is what makes a listing recognisable to a human
+    // looking for "the summer camp ones".
+    const name = match[2].replace(/^[0-9a-f]{4,}-/i, '').replace(/\.[A-Za-z0-9]+$/, '');
+    return { day: match[1], name: name || match[2] };
+}
 /** Object-key-safe name: no slashes, no dot-segments, never empty. */
 export function safeKeySegment(base) {
     const cleaned = base
@@ -103,6 +127,52 @@ export function createR2Sink(bucket, opts) {
                 mimeType: object.httpMetadata?.contentType ?? 'application/octet-stream',
             };
         },
+        async listRecent(opts = {}) {
+            return (await this.listRecentPage(opts)).media;
+        },
+        async listRecentPage({ limit = 20, sinceDay } = {}) {
+            if (!bucket.list)
+                return { media: [], truncated: false, scannedPages: 0 };
+            // Scoped at the STORE, not filtered afterwards: asking only for our own
+            // prefix means another account's keys are never in hand to leak by a
+            // filtering mistake.
+            const prefix = await ownPrefix();
+            const found = [];
+            let cursor;
+            let truncated = false;
+            let scannedPages = 0;
+            // Bounded: a listing walk is unbounded work, and this runs on a tool call.
+            for (let page = 0; page < MAX_LIST_PAGES; page++) {
+                scannedPages = page + 1;
+                const listed = await bucket.list({ prefix, cursor, limit: 1000 });
+                for (const obj of listed.objects) {
+                    const parsed = parseMediaKey(obj.key, prefix);
+                    if (!parsed)
+                        continue; // not a dated object key — skip, never throw
+                    if (sinceDay && parsed.day < sinceDay)
+                        continue;
+                    found.push({ ...parsed, key: obj.key, ...(obj.size !== undefined ? { sizeBytes: obj.size } : {}) });
+                }
+                if (!listed.truncated || !listed.cursor)
+                    break;
+                cursor = listed.cursor;
+                // Ran out of budget with more to read: the answer is a subset, and
+                // must say so rather than passing for the whole picture.
+                if (page === MAX_LIST_PAGES - 1)
+                    truncated = true;
+            }
+            // Keys sort lexicographically by day, and the id after it is random, so
+            // ordering is by day — which is the honest grain: the store records no
+            // per-object timestamp we could do better with.
+            found.sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : a.key < b.key ? 1 : -1));
+            const page = found.slice(0, limit);
+            const expiresAtMs = now().getTime() + ttlMs;
+            const media = await Promise.all(page.map(async (entry) => {
+                const link = await describe(entry.key, expiresAtMs);
+                return { ...entry, ...(link.unavailable ? {} : { url: link.ref, expiresAt: link.expiresAt }) };
+            }));
+            return { media, truncated: truncated || found.length > limit, scannedPages };
+        },
         async resign(key) {
             if (!(await owned(key)))
                 return undefined;

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/interact.js

@@ -215,6 +215,15 @@ export function registerInteractTools(server, client) {
                 catch (err) {
                     if (!(err instanceof ChainedRequest404Error))
                         throw err;
+                    // The client already asked: if the interaction is ALIVE, the 404 was
+                    // about something else (the model id, an expired files/… uri), and
+                    // re-anchoring would bill a second generation to answer a question
+                    // that is already answered — while silently dropping the
+                    // conversation context, returning a plausible image the model built
+                    // without the prior turn. Only probe when the chain is gone or the
+                    // probe itself could not be completed.
+                    if (err.chainExists === true)
+                        throw err;
                     // Re-anchoring needs the prior output image, which only the sidecar
                     // index can locate — and that index lives on disk.
                     if (!onDisk)

package/dist/tools/jobs.js

@@ -1,4 +1,8 @@
 import { z } from 'zod';
+import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { TERMINAL_INTERACTION_STATUSES } from '../client.js';
+import { emitMedia } from './shared.js';
+import { slugify } from '../images.js';
 /**
  * Poll tool for the async generation pattern (issue #52). A generation tool
  * called with `async: true` returns a `job_id` immediately (instead of blocking
@@ -11,10 +15,135 @@ 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.',
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        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. ' +
+            'A killed video/music job started with `background: true` is recovered from its upstream interaction when it finished there.',
+        // NOT read-only any more: recovering a killed job writes the media it
+        // pulls back, exactly as the generation tool would have.
+        annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             job_id: z.string().min(1).describe('The job_id returned by a generation tool called with async: true'),
+            output_dir: z.string().optional().describe('Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or cwd)'),
         },
-    }, async (args) => client.session.jobs.getResult(args.job_id));
+    }, async (args) => {
+        try {
+            return await client.session.jobs.getResult(args.job_id);
+        }
+        catch (err) {
+            // The interesting failure is "your executor died mid-generation". If
+            // that job had reported an upstream interaction id, the generation
+            // itself may well have finished on Google's side — the machine
+            // stopping killed the *waiting*, not the work.
+            const recovered = await recoverFromInteraction(client, args.job_id, args.output_dir, err);
+            if (recovered)
+                return recovered;
+            throw err;
+        }
+    });
+}
+/**
+ * Try to answer a failed poll from the upstream interaction instead.
+ *
+ * Returns `undefined` when there is nothing to recover from — no record, no id,
+ * or an interaction that cannot be read — leaving the original (accurate)
+ * error to stand. Recovery must never convert a real loss into a false success,
+ * so every path that does not produce media falls through.
+ */
+async function recoverFromInteraction(client, jobId, outputDir, original) {
+    const record = await client.session.jobs.peekRecord(jobId);
+    const interactionId = record?.interactionId;
+    if (!interactionId || record?.status !== 'failed')
+        return undefined;
+    let found;
+    try {
+        found = await client.fetchInteractionMedia(interactionId);
+    }
+    catch (probeErr) {
+        // A 403 (and a 404, the store lag) means the work is STILL RUNNING — that
+        // is what a GET of an in-flight interaction answers, verified live:
+        // t+20s 403, t+40s completed with the clip. Reporting "unrecoverable"
+        // there is the worst wrong answer available, because the caller re-pays
+        // for a generation that was about to land.
+        if (isInFlight(probeErr))
+            return stillRunning(jobId, interactionId);
+        // Anything else: a backgrounded interaction can settle into a permanent
+        // 400 and never become retrievable. Say so on top of the real error rather
+        // than pretending the output is somewhere.
+        throw new McpToolError(`${errorMessage(original)} Its upstream interaction "${interactionId}" could not be read either (${errorMessage(probeErr)}), so the output is not recoverable.`, { hint: 'Any media the lost run did write is still listed by gemini_list_recent_media. Otherwise the generation has to be re-run.' });
+    }
+    const [kind, media] = found.videos.length
+        ? ['video', found.videos]
+        : found.audios.length
+            ? ['audio', found.audios]
+            : found.images.length
+                ? ['image', found.images]
+                : ['image', []];
+    if (media.length === 0) {
+        // Still running upstream is a genuinely different answer from lost: the
+        // caller should poll again, not re-pay. But a TERMINAL status with no media
+        // (failed, cancelled, …) is not that — telling someone to poll again would
+        // loop them forever on a generation that is never going to arrive, so the
+        // real error stands.
+        if (found.status && !TERMINAL_INTERACTION_STATUSES.has(found.status))
+            return stillRunning(jobId, interactionId);
+        return undefined;
+    }
+    const slug = slugify(`recovered-${interactionId}`.slice(0, 60));
+    const named = media.map((m, i) => ({
+        media: m,
+        base: media.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
+    }));
+    const result = await emitMedia(named, kind, { output_dir: outputDir, sink: client.mediaSink }, {
+        job_id: jobId,
+        recovered_from_interaction: interactionId,
+        note: recoveryNote(record.error?.message),
+        ...(found.text ? { text: found.text } : {}),
+    });
+    // Settle the job with what we just recovered. Otherwise it stays `failed`
+    // and the next poll re-fetches the interaction, re-downloads the media and
+    // writes another copy — the ordinary done path is idempotent, so this one
+    // has to be too.
+    await client.session.jobs.adoptResult(jobId, record.toolName, result, interactionId);
+    return result;
+}
+/**
+ * Why this job needed recovering — only claimed when it is known.
+ *
+ * Recovery fires for any failed job that got as far as an interaction id, and
+ * that is broader than "the machine stopped": a backgrounded call whose own
+ * wait expired, or a sync call that failed after the POST returned, both land
+ * here with a perfectly healthy executor. `job-store.ts` is the only thing that
+ * writes the executor-lost message, so it is the only thing that licenses the
+ * executor-lost sentence. The two facts that hold on every path — not re-run,
+ * not billed twice — are stated either way.
+ */
+function recoveryNote(recordedError) {
+    const cause = /was lost:/.test(recordedError ?? '')
+        ? 'The executor that started this job was reclaimed before it could return.'
+        : 'This job failed here before it could return its output.';
+    return `${cause} The generation had already completed upstream and its output was recovered — it was not re-run, and you were not billed twice.`;
+}
+/** The generation outlived its executor and is not finished yet. */
+function stillRunning(jobId, interactionId) {
+    return textResult({
+        job_id: jobId,
+        status: 'running',
+        interaction_id: interactionId,
+        note: 'The executor that started this job is gone, but the generation is still running upstream. Poll again — it has not been lost, and re-running it would bill a second time.',
+    });
+}
+/**
+ * Does this probe failure mean "still working"? 403 is what a GET of an
+ * in-flight background interaction returns (verified live), and 404 is the
+ * interactions store's eventual consistency.
+ */
+function isInFlight(err) {
+    const status = err?.status;
+    return status === 403 || status === 404;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
 }

package/dist/tools/music.js

@@ -36,6 +36,7 @@ export function registerMusicTools(server, client) {
             inline: z.boolean().optional().describe('Return base64 audio inline instead of writing to disk'),
             previous_interaction_id: z.string().optional().describe('Interaction id to continue from'),
             continue_last: z.boolean().optional().describe('Continue from the most recent music interaction this server created (explicit previous_interaction_id wins)'),
+            background: z.boolean().optional().describe('Run the generation on Google\'s side and poll it, so a killed job can be recovered by gemini_get_result. Off by default — see gemini_video_generate'),
             timeout_ms: timeoutMsSchema,
             idempotency_key: idempotencyKeySchema,
             async: asyncSchema,
@@ -68,7 +69,7 @@ export function registerMusicTools(server, client) {
             images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {
             const { inputs, report } = await resolveImageInputs(args, client);
             const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client.generateMusic({
                 input: args.prompt,
@@ -77,6 +78,9 @@ export function registerMusicTools(server, client) {
                 audioFormat: args.audio_format,
                 previousInteractionId,
                 timeoutMs: args.timeout_ms,
+                background: args.background,
+                // See gemini_video_generate: the id is what survives the executor.
+                onInteractionStarted: ctx.reportInteraction,
             }));
             client.session.lastMusicInteractionId = r.id;
             const meta = { model, interaction_id: r.id };

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/video.js

@@ -9,6 +9,11 @@ import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js'
 /** omni's own aspect-ratio enum — NOT the image tools' ASPECT_RATIOS. */
 const VIDEO_ASPECT_RATIOS = ['16:9', '9:16'];
 const VIDEO_TASKS = ['text_to_video', 'image_to_video', 'reference_to_video', 'edit'];
+// `delivery` is transport, not content: uri hands back a Files API link the
+// client downloads with the api key, inline returns base64 capped at ~4MB.
+// Left unset here so the client's verified default (uri) applies; this is an
+// escape hatch for a video model that rejects delivery outright.
+const VIDEO_DELIVERY = ['inline', 'uri'];
 // The most-recent video interaction id (for continue_last) lives on
 // `client.session`, NOT at module scope — one Cloudflare isolate serves many
 // authenticated connector sessions, so a module-level id would let one user's
@@ -39,6 +44,8 @@ export function registerVideoTools(server, client) {
                 .regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")')
                 .optional()
                 .describe(`Model id override (default: ${DEFAULT_VIDEO_MODEL})`),
+            delivery: z.enum(VIDEO_DELIVERY).optional().describe('How the clip comes back: "uri" (default — a Files API link the server downloads, no size ceiling) or "inline" (base64, capped ~4MB)'),
+            background: z.boolean().optional().describe('Run the generation on Google\'s side and poll it, so a killed job can be recovered by gemini_get_result. Trade-off: retrieving a backgrounded interaction is unreliable today (some become permanently unreadable), so the default is off'),
             previous_interaction_id: z.string().optional().describe('Interaction id to edit/continue (with task: "edit")'),
             continue_last: z.boolean().optional().describe('Continue from the most recent video interaction this server created (explicit previous_interaction_id wins)'),
             timeout_ms: timeoutMsSchema,
@@ -70,7 +77,7 @@ export function registerVideoTools(server, client) {
             images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {
             const { inputs, report } = await resolveImageInputs(args, client);
             const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client.generateVideo({
                 input: args.prompt,
@@ -80,6 +87,12 @@ export function registerVideoTools(server, client) {
                 task: args.task,
                 previousInteractionId,
                 timeoutMs: args.timeout_ms,
+                delivery: args.delivery,
+                background: args.background,
+                // Hand the id to the job record the moment it exists: if this
+                // machine stops mid-generation, that id is the only route back to
+                // an output that finishes upstream anyway.
+                onInteractionStarted: ctx.reportInteraction,
             }));
             client.session.lastVideoInteractionId = r.id;
             const meta = { model, interaction_id: r.id };

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.2'; // x-release-please-version
+export const VERSION = '1.8.0'; // x-release-please-version

package/package.json

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