@chrischall/gemini-mcp 0.8.0 → 1.0.0

package/dist/client.js

@@ -1,7 +1,7 @@
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadDotenvSafely, readEnvVar, McpToolError, ApiError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
-import { resolveModel, filterImageModels } from './models.js';
+import { resolveModel, filterImageModels, DEFAULT_VIDEO_MODEL, DEFAULT_MUSIC_MODEL } from './models.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
 const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'; // v1 lacks gemini-3-pro-image; confirmed via Task 5
@@ -288,22 +288,80 @@ export class GeminiClient {
                 searchTool.search_types = opts.searchTypes;
             body.tools = [searchTool];
         }
+        const data = await this.postInteraction(body, opts);
+        const { images, text, grounding } = this.extractInteraction(data, opts.searchTypes);
+        if (images.length === 0) {
+            throw new McpToolError('Gemini returned no image', {
+                hint: 'The request may have been blocked by safety filters — try rephrasing the prompt.',
+            });
+        }
+        return { id: data.id, images, text, grounding };
+    }
+    /**
+     * Generate video via the omni model (Interactions API, inline delivery). Same
+     * plumbing as {@link interact} — text/image input parts, a `video`
+     * response_format, optional `video_config.task`, and `previous_interaction_id`
+     * for edits. Preview model: shapes are docs-derived; parsing stays tolerant.
+     */
+    async generateVideo(opts) {
+        const model = opts.model ?? DEFAULT_VIDEO_MODEL;
+        const inputParts = [{ type: 'text', text: opts.input }];
+        for (const img of opts.images ?? [])
+            inputParts.push({ type: 'image', mime_type: img.mimeType, data: img.base64 });
+        const responseFormat = { type: 'video', delivery: 'inline' };
+        if (opts.aspectRatio)
+            responseFormat.aspect_ratio = opts.aspectRatio;
+        const body = { model, input: inputParts, response_format: responseFormat };
+        if (opts.task)
+            body.generation_config = { video_config: { task: opts.task } };
+        if (opts.previousInteractionId !== undefined)
+            body.previous_interaction_id = opts.previousInteractionId;
+        const data = await this.postInteraction(body, opts);
+        const { videos, text } = this.extractInteraction(data);
+        if (videos.length === 0) {
+            throw new McpToolError('Gemini returned no video', {
+                hint: 'The request may have been blocked by a safety filter, or the clip exceeded the ~4MB inline limit — try a shorter/simpler prompt or a different aspect ratio.',
+            });
+        }
+        return { id: data.id, videos, text };
+    }
+    /**
+     * Generate music via a Lyria model (Interactions API, inline audio). Reuses
+     * the interact plumbing with an `audio` response_format. Preview model.
+     */
+    async generateMusic(opts) {
+        const model = opts.model ?? DEFAULT_MUSIC_MODEL;
+        const inputParts = [{ type: 'text', text: opts.input }];
+        for (const img of opts.images ?? [])
+            inputParts.push({ type: 'image', mime_type: img.mimeType, data: img.base64 });
+        const responseFormat = { type: 'audio' };
+        if (opts.audioFormat)
+            responseFormat.audio_format = opts.audioFormat;
+        const body = { model, input: inputParts, response_format: responseFormat };
+        if (opts.previousInteractionId !== undefined)
+            body.previous_interaction_id = opts.previousInteractionId;
+        const data = await this.postInteraction(body, opts);
+        const { audios, text } = this.extractInteraction(data);
+        if (audios.length === 0) {
+            throw new McpToolError('Gemini returned no audio', {
+                hint: 'The request may have been blocked by a safety filter — try rephrasing the prompt.',
+            });
+        }
+        return { id: data.id, audios, text };
+    }
+    /** POST `/interactions` with the chained-404 retry. Shared by all media. */
+    async postInteraction(body, opts) {
         const { interactionsApi } = this.apisFor(resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
-        let data;
         for (let attempt = 0;; attempt++) {
             try {
-                data = await interactionsApi.fetchJson('POST', '/interactions', {
-                    body,
-                });
-                break;
+                return await interactionsApi.fetchJson('POST', '/interactions', { body });
             }
             catch (err) {
-                // A 404 on a chained call means the referenced interaction wasn't
-                // found. Two causes: (a) store lag right after the id was created —
-                // retry with backoff; (b) genuinely gone — interactions are retained
-                // 55 days (paid tier) / 1 day (free tier) and are scoped to the API
-                // key's project. The chain is recoverable from the last output file,
-                // so the exhausted-retries error says how.
+                // A 404 on a chained call means the referenced interaction wasn't found:
+                // (a) store lag right after the id was created — retry with backoff; or
+                // (b) genuinely gone — interactions are retained 55 days (paid) / 1 day
+                // (free), scoped to the API key's project. The chain is recoverable from
+                // the last output file, so the exhausted-retries error says how.
                 if (!(opts.previousInteractionId && err instanceof ApiError && err.status === 404))
                     throw err;
                 if (attempt < CHAIN_404_RETRIES) {
@@ -311,26 +369,27 @@ export class GeminiClient {
                     continue;
                 }
                 throw new McpToolError(`Previous interaction "${opts.previousInteractionId}" was not found (retried ${CHAIN_404_RETRIES}× — the interactions store can lag briefly after a turn completes). If the id is old: interactions are retained 55 days on the paid tier (1 day on the free tier) and are scoped to the API key that created them.`, {
-                    hint: 'Retry once more in a few seconds; if it keeps failing, start a new chain: call gemini_interact again with the last output image passed via `images` (or `images_base64`) plus the same instruction, then chain the NEW interaction id.',
+                    hint: 'Retry once more in a few seconds; if it keeps failing, start a new chain by re-attaching the last output as an input plus the same instruction, then chain the NEW interaction id.',
                     cause: err,
                 });
             }
         }
-        // Only surface the `model_output` step — that's the caller-facing result.
-        // `thought` steps hold internal reasoning (and, with includeThoughts, draft
-        // "thinking" images); collecting those would leak reasoning into `text` and
-        // pollute the returned images. The verified contract puts the output image
-        // in `model_output`.
+    }
+    /**
+     * Collect `model_output` media (image/video/audio) + text + grounding from an
+     * interactions response. Only the `model_output` step is surfaced — `thought`
+     * steps (internal reasoning / draft images) are dropped on purpose so they
+     * can't leak into text or pollute the outputs. Tolerant of snake/camel MIME.
+     */
+    extractInteraction(data, searchTypes) {
         const images = [];
+        const videos = [];
+        const audios = [];
         const textParts = [];
         const searchQueries = [];
         const searchSuggestions = new Set();
         for (const step of data.steps ?? []) {
             // Grounding queries live on the `google_search_call` step's arguments.
-            // (The `google_search_result` step only carries HTML `search_suggestions`
-            // chips — no clean source uri/title list like generateContent's
-            // groundingChunks — so interact surfaces queries, plus the suggestion
-            // chips when image_search was requested, ToS below.)
             if (step.type === 'google_search_call') {
                 for (const q of step.arguments?.queries ?? [])
                     if (q?.trim())
@@ -338,11 +397,9 @@ export class GeminiClient {
                 continue;
             }
             // ToS: image_search results' `search_suggestions` chips MUST be displayed
-            // by the caller, so surface them (deduped — the chips repeat) only when
-            // image_search grounding was requested; web-only grounding keeps the
-            // lean queries-only meta.
+            // by the caller — surface them (deduped) only when image_search was asked.
             if (step.type === 'google_search_result') {
-                if (opts.searchTypes?.includes('image_search')) {
+                if (searchTypes?.includes('image_search')) {
                     for (const r of step.result ?? [])
                         if (r.search_suggestions?.trim())
                             searchSuggestions.add(r.search_suggestions);
@@ -353,8 +410,14 @@ export class GeminiClient {
                 continue;
             for (const parts of [step.content ?? [], step.summary ?? []]) {
                 for (const part of parts) {
-                    if (part.type === 'image' && part.data) {
-                        images.push({ base64: part.data, mimeType: part.mime_type ?? 'image/jpeg' });
+                    const mime = part.mime_type ?? part.mimeType;
+                    if (part.data) {
+                        if (part.type === 'image')
+                            images.push({ base64: part.data, mimeType: mime ?? 'image/jpeg' });
+                        else if (part.type === 'video')
+                            videos.push({ base64: part.data, mimeType: mime ?? 'video/mp4' });
+                        else if (part.type === 'audio')
+                            audios.push({ base64: part.data, mimeType: mime ?? 'audio/mpeg' });
                     }
                     else if (part.type === 'text' && part.text?.trim()) {
                         textParts.push(part.text);
@@ -362,12 +425,6 @@ export class GeminiClient {
                 }
             }
         }
-        if (images.length === 0) {
-            throw new McpToolError('Gemini returned no image', {
-                hint: 'The request may have been blocked by safety filters — try rephrasing the prompt.',
-            });
-        }
-        const resultText = textParts.join('\n') || undefined;
         let grounding;
         if (searchQueries.length > 0 || searchSuggestions.size > 0) {
             grounding = {};
@@ -376,7 +433,7 @@ export class GeminiClient {
             if (searchSuggestions.size > 0)
                 grounding.search_suggestions = [...searchSuggestions];
         }
-        return { id: data.id, images, text: resultText, grounding };
+        return { images, videos, audios, text: textParts.join('\n') || undefined, grounding };
     }
 }
 /** Module-level singleton shared by every tool module (deferred-config-error). */

package/dist/images.js

@@ -49,14 +49,42 @@ function sniffMimeBytes(buf) {
     }
     return 'image/png';
 }
-/** Decode base64 image bytes and write to disk (creating dir). Returns the absolute path. */
-export async function writeImage(dir, base, base64, mimeType) {
+/** File extension for a media MIME (image/video/audio). Falls back to the MIME
+ * subtype, so an unforeseen preview type still writes with a sane extension. */
+export function mediaExt(mimeType) {
+    const m = mimeType.toLowerCase();
+    if (m.includes('jpeg'))
+        return 'jpg';
+    if (m.includes('webp'))
+        return 'webp';
+    if (m.includes('png'))
+        return 'png';
+    if (m.includes('mp4'))
+        return 'mp4';
+    if (m.includes('quicktime'))
+        return 'mov';
+    if (m.includes('webm'))
+        return 'webm';
+    if (m.includes('wav'))
+        return 'wav';
+    if (m.includes('mpeg') || m.includes('mp3'))
+        return 'mp3';
+    if (m.includes('ogg'))
+        return 'ogg';
+    return m.split('/')[1]?.split(';')[0]?.replace(/^x-/, '') || 'bin';
+}
+/** Decode base64 media bytes (image/video/audio) and write to disk (creating
+ * dir), picking the extension from the MIME. Returns the absolute path. */
+export async function writeMedia(dir, base, base64, mimeType) {
     await mkdir(dir, { recursive: true });
-    const ext = mimeType.includes('jpeg') ? 'jpg' : mimeType.includes('webp') ? 'webp' : 'png';
-    const path = await uniquePath(dir, base, ext);
+    const path = await uniquePath(dir, base, mediaExt(mimeType));
     await writeFile(path, Buffer.from(base64, 'base64'));
     return resolve(path);
 }
+/** Decode base64 image bytes and write to disk. Returns the absolute path. */
+export async function writeImage(dir, base, base64, mimeType) {
+    return writeMedia(dir, base, base64, mimeType);
+}
 /**
  * Write `<imagePath>.json` recording generation metadata (notably the
  * interaction id) next to a written image. The MCP host's tools/call timeout
@@ -208,8 +236,9 @@ export async function gatherImageInputs(opts) {
 }
 /** Caller-supplied filename → safe base name (no extension). */
 export function baseName(name) {
-    // Strip known image extensions
-    const stripped = name.replace(/\.(png|jpe?g|webp)$/i, '');
+    // Strip a known media extension (image / video / audio) so writeMedia doesn't
+    // double it (e.g. "clip.mp4" → "clip" → "clip.mp4").
+    const stripped = name.replace(/\.(png|jpe?g|webp|mp4|mov|webm|mp3|wav|ogg)$/i, '');
     // Replace non-safe chars with hyphens, collapse repeats, trim edges
     const safe = stripped
         .replace(/[^A-Za-z0-9._-]+/g, '-')

package/dist/index.js

@@ -5,6 +5,9 @@ import { registerModelTools } from './tools/models.js';
 import { registerGenerateTools } from './tools/generate.js';
 import { registerSetTools } from './tools/set.js';
 import { registerInteractTools } from './tools/interact.js';
+import { registerVideoTools } from './tools/video.js';
+import { registerMusicTools } from './tools/music.js';
+import { registerJobTools } from './tools/jobs.js';
 // The GeminiClient is a module-level singleton (imported by each tool module)
 // that defers its config error to the first request — so the server boots and
 // answers the host's install-time tools/list probe even without GEMINI_API_KEY.
@@ -12,5 +15,5 @@ await runMcp({
     name: 'gemini-mcp',
     version: VERSION,
     banner: '[gemini-mcp] This project was developed and is maintained by AI (Claude). Use at your own discretion.',
-    tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools],
+    tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerVideoTools, registerMusicTools, registerJobTools],
 });

package/dist/models.js

@@ -5,6 +5,11 @@
  * `model` param when the task warrants it (see MODEL_CHOICE_GUIDE).
  */
 export const DEFAULT_IMAGE_MODEL = 'gemini-3.1-flash-image';
+/** Default video model (omni, Interactions API). Preview — overridable per-call. */
+export const DEFAULT_VIDEO_MODEL = 'gemini-omni-flash-preview';
+/** Default music model (Lyria clips, Interactions API). `lyria-3-pro-preview` is
+ * the longer-form opt-in; both are preview and need a funded account. */
+export const DEFAULT_MUSIC_MODEL = 'lyria-3-clip-preview';
 /** Per-call → env override → hardcoded default. Blank/whitespace counts as unset. */
 export function resolveModel(perCall, envOverride) {
     return perCall?.trim() || envOverride?.trim() || DEFAULT_IMAGE_MODEL;

package/dist/tools/generate.js

@@ -3,7 +3,8 @@ import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, resolveVideoInput, videoPathSchema, withProgressHeartbeat } from './shared.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat } from './shared.js';
+import { dispatch, fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const GENERATE_ENDPOINT = '/v1beta/models/{model}:generateContent';
 const SEND_LOCAL_ACTION = 'Send local file input(s) to the Gemini API';
@@ -12,7 +13,7 @@ const SEND_LOCAL_ACTION = 'Send local file input(s) to the Gemini API';
 const REFINE_HINT = 'To iteratively refine this image, use gemini_interact (pass the output file via `images` on the first call, ' +
     'then chain `previous_interaction_id` on each subsequent call).';
 export function registerGenerateTools(server) {
-    server.registerTool('gemini_generate_image', {
+    server.registerTool('gemini_image_generate', {
         description: 'Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro). ' +
             'If the result will likely be refined iteratively, prefer gemini_interact (multi-turn) as the entry point.',
         annotations: { readOnlyHint: false, openWorldHint: true },
@@ -35,57 +36,70 @@ export function registerGenerateTools(server) {
         if (gate)
             return gate;
         const count = args.count ?? 1;
-        const seed = pickSeed(args.seed);
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
-        const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
-        const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        // Upload ONCE (before the count loop) — every generate call references
-        // the same files/… uri.
-        const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args));
-        const named = [];
-        let capturedText;
-        // For count>1, surface the FIRST call's grounding (each call grounds
-        // independently; one representative set of sources beats concatenating N).
-        let capturedGrounding;
-        await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : 'image'} (${model})`, async () => {
-            for (let i = 0; i < count; i++) {
-                // Distinct seed per image (seed+0 for the single-image case == echoed seed)
-                // so count>1 yields N *different* images, not N duplicates.
-                const result = await client.generate({
-                    prompt: args.prompt,
-                    images: refInputs.length > 0 ? refInputs : undefined,
-                    model: args.model,
-                    aspectRatio: args.aspect_ratio,
-                    imageSize: args.image_size,
-                    seed: seed + i,
-                    thinkingLevel: args.thinking_level,
-                    googleSearch: args.google_search,
-                    videoUrl: video.videoUrl,
-                    videoMimeType: video.videoMimeType,
-                    timeoutMs: args.timeout_ms,
-                });
-                const { images: [img], text } = result;
-                if (text && !capturedText)
-                    capturedText = text;
-                if (result.grounding && !capturedGrounding)
-                    capturedGrounding = result.grounding;
-                named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, '0')}` });
-            }
+        // Fingerprint the request identity (excl. server-picked seed / output path)
+        // so a blind re-issue after a host timeout dedups instead of re-billing.
+        const fingerprint = fingerprintRequest('gemini_image_generate', {
+            model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            thinking_level: args.thinking_level, google_search: args.google_search, count,
+            images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
+            video_url: args.video_url, video_path: args.video_path,
+        });
+        return dispatch({ toolName: 'gemini_image_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+            const seed = pickSeed(args.seed);
+            const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
+            const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            // Upload ONCE (before the count loop) — every generate call references
+            // the same files/… uri.
+            const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args));
+            const named = [];
+            let capturedText;
+            // For count>1, surface the FIRST call's grounding (each call grounds
+            // independently; one representative set of sources beats concatenating N).
+            let capturedGrounding;
+            await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : 'image'} (${model})`, async () => {
+                for (let i = 0; i < count; i++) {
+                    // Distinct seed per image (seed+0 for the single-image case == echoed seed)
+                    // so count>1 yields N *different* images, not N duplicates.
+                    const result = await client.generate({
+                        prompt: args.prompt,
+                        images: refInputs.length > 0 ? refInputs : undefined,
+                        model: args.model,
+                        aspectRatio: args.aspect_ratio,
+                        imageSize: args.image_size,
+                        seed: seed + i,
+                        thinkingLevel: args.thinking_level,
+                        googleSearch: args.google_search,
+                        videoUrl: video.videoUrl,
+                        videoMimeType: video.videoMimeType,
+                        timeoutMs: args.timeout_ms,
+                    });
+                    const { images: [img], text } = result;
+                    if (text && !capturedText)
+                        capturedText = text;
+                    if (result.grounding && !capturedGrounding)
+                        capturedGrounding = result.grounding;
+                    named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, '0')}` });
+                }
+            });
+            const meta = buildMeta(model, seed, args);
+            if (capturedText)
+                meta.text = capturedText;
+            if (capturedGrounding)
+                meta.grounding = capturedGrounding;
+            if (video.videoFileMeta)
+                meta.video_file = video.videoFileMeta;
+            meta.hint = REFINE_HINT;
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size, count });
+            if (risk)
+                meta.timeout_risk = risk;
+            return emit(named, args, meta);
         });
-        const meta = buildMeta(model, seed, args);
-        if (capturedText)
-            meta.text = capturedText;
-        if (capturedGrounding)
-            meta.grounding = capturedGrounding;
-        if (video.videoFileMeta)
-            meta.video_file = video.videoFileMeta;
-        meta.hint = REFINE_HINT;
-        return emit(named, args, meta);
     });
-    server.registerTool('gemini_edit_image', {
+    server.registerTool('gemini_image_edit', {
         description: 'Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. ' +
             'For a SERIES of successive edits to the same image, prefer gemini_interact (multi-turn) — it keeps edit context ' +
-            'and avoids re-processing the full image each round; use gemini_edit_image for one-off edits or composing multiple distinct inputs. ' +
+            'and avoids re-processing the full image each round; use gemini_image_edit for one-off edits or composing multiple distinct inputs. ' +
             'Gemini over-preserves the input; there is no edit-strength control — for large structural changes, reroll with a different `seed` or more forceful wording.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
@@ -102,33 +116,43 @@ export function registerGenerateTools(server) {
         if (!hasPaths && !hasBase64 && !args.from_clipboard) {
             throw new McpToolError('Provide at least one input image via `images`, `images_base64`, or `from_clipboard`.');
         }
-        // Confirm-gate local file inputs (see gemini_generate_image). base64 /
+        // Confirm-gate local file inputs (see gemini_image_generate). base64 /
         // clipboard inputs are not local-path reads and pass through ungated.
         const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images);
         if (gate)
             return gate;
-        const seed = pickSeed(args.seed);
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
-        const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
-        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client.generate({
-            prompt: args.prompt,
-            images: inputs,
-            model: args.model,
-            aspectRatio: args.aspect_ratio,
-            imageSize: args.image_size,
-            seed,
-            thinkingLevel: args.thinking_level,
-            googleSearch: args.google_search,
-            timeoutMs: args.timeout_ms,
-        }));
-        const { images: [img], text } = result;
-        const meta = buildMeta(model, seed, args);
-        if (text)
-            meta.text = text;
-        if (result.grounding)
-            meta.grounding = result.grounding;
-        meta.hint = REFINE_HINT;
-        return emit([{ image: img, base: slug }], args, meta);
+        const fingerprint = fingerprintRequest('gemini_image_edit', {
+            model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            thinking_level: args.thinking_level, google_search: args.google_search,
+            images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
+        });
+        return dispatch({ toolName: 'gemini_image_edit', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+            const seed = pickSeed(args.seed);
+            const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
+            const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client.generate({
+                prompt: args.prompt,
+                images: inputs,
+                model: args.model,
+                aspectRatio: args.aspect_ratio,
+                imageSize: args.image_size,
+                seed,
+                thinkingLevel: args.thinking_level,
+                googleSearch: args.google_search,
+                timeoutMs: args.timeout_ms,
+            }));
+            const { images: [img], text } = result;
+            const meta = buildMeta(model, seed, args);
+            if (text)
+                meta.text = text;
+            if (result.grounding)
+                meta.grounding = result.grounding;
+            meta.hint = REFINE_HINT;
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+            if (risk)
+                meta.timeout_risk = risk;
+            return emit([{ image: img, base: slug }], args, meta);
+        });
     });
 }

package/dist/tools/interact.js

@@ -3,7 +3,8 @@ import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs, resolveImagePath, writeSidecar } from '../images.js';
-import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, withProgressHeartbeat } from './shared.js';
+import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, withProgressHeartbeat } from './shared.js';
+import { dispatch, fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 // The most recent interaction id this server process created — what
 // `continue_last: true` resumes. In-memory only: an MCP server lives for the
@@ -118,6 +119,8 @@ export function registerInteractTools(server) {
                 .describe('Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
             video_path: videoPathSchema,
             timeout_ms: timeoutMsSchema,
+            idempotency_key: idempotencyKeySchema,
+            async: asyncSchema,
             from_clipboard: z
                 .boolean()
                 .optional()
@@ -146,57 +149,69 @@ export function registerInteractTools(server) {
         const gate = await previewLocalInputsUnlessConfirmed(args.confirm, 'Send local file input(s) to the Gemini Interactions API', '/v1beta/interactions', images, args.video_path);
         if (gate)
             return gate;
-        const inputs = await gatherImageInputs({ images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args));
-        const r = await withProgressHeartbeat(extra, 'Generating image (Gemini Interactions API)', () => client.interact({
-            input: args.input,
-            images: inputs.length ? inputs : undefined,
-            model: args.model,
-            aspectRatio: args.aspect_ratio,
-            imageSize: args.image_size,
-            thinkingLevel: args.thinking_level,
-            previousInteractionId,
-            googleSearch: args.google_search,
-            searchTypes: args.search_types,
-            videoUrl: video.videoUrl,
-            videoMimeType: video.videoMimeType,
-            timeoutMs: args.timeout_ms,
-        }));
-        lastInteractionId = r.id;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
-        const meta = { model, interaction_id: r.id };
-        if (previousInteractionId)
-            meta.previous_interaction_id = previousInteractionId;
-        if (dropped.length)
-            meta.dropped_previous_output = dropped;
-        meta.hint =
-            `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) — ` +
-                'do NOT re-attach the returned image as an input; the interaction already contains it.';
-        if (r.text)
-            meta.text = r.text;
-        if (r.grounding)
-            meta.grounding = r.grounding;
-        if (video.videoFileMeta)
-            meta.video_file = video.videoFileMeta;
-        const slug = args.filename ? baseName(args.filename) : slugify(args.input);
-        const named = r.images.map((image, i) => ({
-            image,
-            base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
-        }));
-        // writeImage returns already-resolved absolute paths.
-        return emit(named, args, meta, async (paths) => {
-            for (const p of paths)
-                writtenOutputs.add(p);
-            // Sidecar per image so the interaction id survives a lost MCP response
-            // (host timeout). Best-effort: the image is already on disk and the id
-            // is in the result — a sidecar failure shouldn't fail the call.
-            try {
+        const fingerprint = fingerprintRequest('gemini_interact', {
+            model, input: args.input, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            thinking_level: args.thinking_level, previous_interaction_id: previousInteractionId,
+            google_search: args.google_search, search_types: args.search_types,
+            images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
+            video_url: args.video_url, video_path: args.video_path,
+        });
+        return dispatch({ toolName: 'gemini_interact', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+            const inputs = await gatherImageInputs({ images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args));
+            const r = await withProgressHeartbeat(extra, 'Generating image (Gemini Interactions API)', () => client.interact({
+                input: args.input,
+                images: inputs.length ? inputs : undefined,
+                model: args.model,
+                aspectRatio: args.aspect_ratio,
+                imageSize: args.image_size,
+                thinkingLevel: args.thinking_level,
+                previousInteractionId,
+                googleSearch: args.google_search,
+                searchTypes: args.search_types,
+                videoUrl: video.videoUrl,
+                videoMimeType: video.videoMimeType,
+                timeoutMs: args.timeout_ms,
+            }));
+            lastInteractionId = r.id;
+            const meta = { model, interaction_id: r.id };
+            if (previousInteractionId)
+                meta.previous_interaction_id = previousInteractionId;
+            if (dropped.length)
+                meta.dropped_previous_output = dropped;
+            meta.hint =
+                `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) — ` +
+                    'do NOT re-attach the returned image as an input; the interaction already contains it.';
+            if (r.text)
+                meta.text = r.text;
+            if (r.grounding)
+                meta.grounding = r.grounding;
+            if (video.videoFileMeta)
+                meta.video_file = video.videoFileMeta;
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+            if (risk)
+                meta.timeout_risk = risk;
+            const slug = args.filename ? baseName(args.filename) : slugify(args.input);
+            const named = r.images.map((image, i) => ({
+                image,
+                base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
+            }));
+            // writeImage returns already-resolved absolute paths.
+            return emit(named, args, meta, async (paths) => {
                 for (const p of paths)
-                    await writeSidecar(p, { ...meta, images: paths });
-            }
-            catch (err) {
-                meta.sidecar_error = err instanceof Error ? err.message : String(err);
-            }
+                    writtenOutputs.add(p);
+                // Sidecar per image so the interaction id survives a lost MCP response
+                // (host timeout). Best-effort: the image is already on disk and the id
+                // is in the result — a sidecar failure shouldn't fail the call.
+                try {
+                    for (const p of paths)
+                        await writeSidecar(p, { ...meta, images: paths });
+                }
+                catch (err) {
+                    meta.sidecar_error = err instanceof Error ? err.message : String(err);
+                }
+            });
         });
     });
 }