@chrischall/gemini-mcp 0.7.2 → 0.8.0

package/dist/client.js

@@ -8,8 +8,24 @@ const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'; // v1 lacks
 const SERVICE = 'Gemini';
 const INTERACTIONS_SERVICE = 'Gemini Interactions';
 // Per-request abort budget. Image generation routinely runs 30s+ on the Pro
-// model, so this is deliberately 60s (NOT the fleet's usual 15–30s).
+// model, so this is deliberately 60s (NOT the fleet's usual 15–30s) — and 4K
+// output routinely runs past 60s, hence the doubled 4K default. Both are
+// overridable: per-call `timeout_ms` beats $GEMINI_TIMEOUT_MS beats these.
 const REQUEST_TIMEOUT_MS = 60_000;
+const REQUEST_TIMEOUT_4K_MS = 120_000;
+/**
+ * Effective upstream timeout for one request:
+ * per-call `timeout_ms` → `$GEMINI_TIMEOUT_MS` → 120s for 4K output → 60s.
+ * Resolved at request time so an env change doesn't require a new process.
+ */
+export function resolveTimeoutMs(perCallMs, imageSize) {
+    if (perCallMs !== undefined && perCallMs > 0)
+        return perCallMs;
+    const env = Number(readEnvVar('GEMINI_TIMEOUT_MS'));
+    if (Number.isFinite(env) && env > 0)
+        return env;
+    return imageSize === '4K' ? REQUEST_TIMEOUT_4K_MS : REQUEST_TIMEOUT_MS;
+}
 // Files API (local-video upload — docs/GEMINI-API.md "Files API — local video
 // upload", verified 2026-06-12). The resumable upload endpoint lives under
 // `/upload/v1beta`, NOT the normal `/v1beta` base.
@@ -31,8 +47,7 @@ const CHAIN_404_RETRY_MS = 2_000;
 export class GeminiClient {
     apiKey;
     configError;
-    api;
-    interactionsApi;
+    apis = new Map();
     fetchImpl;
     sleep;
     constructor(opts = {}) {
@@ -47,30 +62,39 @@ export class GeminiClient {
             this.apiKey = key;
             this.configError = null;
         }
-        // Both paths share: the key in the `x-goog-api-key` header (Gemini does not
-        // use `Authorization: Bearer`), a 60s abort budget, and the default 429
-        // retry (once after 2s — the free tier rate-limits aggressively).
-        // `getToken` calls requireKey() so key resolution stays at REQUEST time:
-        // the server boots without a key and the actionable config error (with its
-        // aistudio hint) surfaces on the first tool call, not at startup.
         this.fetchImpl = opts.fetchImpl ?? fetch;
         this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-        const shared = {
-            tokenHeader: 'x-goog-api-key',
-            getToken: () => this.requireKey(),
-            timeout: REQUEST_TIMEOUT_MS,
-            fetchImpl: this.fetchImpl,
-        };
-        this.api = createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared });
-        // Separate client for the Interactions API so errors name the right API.
-        // The beta-era Api-Revision header is gone: the API went GA and requests
-        // succeed without it (verified live 2026-07-06; see docs/GEMINI-API.md).
-        // Don't re-add a pinned revision — it would freeze us on old semantics.
-        this.interactionsApi = createApiClient({
-            baseUrl: BASE_URL,
-            serviceName: INTERACTIONS_SERVICE,
-            ...shared,
-        });
+    }
+    /**
+     * The `createApiClient` pair for one timeout budget, built lazily and
+     * memoized per distinct timeout (a handful of values in practice). Both
+     * share: the key in the `x-goog-api-key` header (Gemini does not use
+     * `Authorization: Bearer`) and the default 429 retry (once after 2s — the
+     * free tier rate-limits aggressively). `getToken` calls requireKey() so key
+     * resolution stays at REQUEST time: the server boots without a key and the
+     * actionable config error (with its aistudio hint) surfaces on the first
+     * tool call, not at startup.
+     */
+    apisFor(timeoutMs) {
+        let entry = this.apis.get(timeoutMs);
+        if (!entry) {
+            const shared = {
+                tokenHeader: 'x-goog-api-key',
+                getToken: () => this.requireKey(),
+                timeout: timeoutMs,
+                fetchImpl: this.fetchImpl,
+            };
+            entry = {
+                api: createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared }),
+                // Separate client for the Interactions API so errors name the right API.
+                // The beta-era Api-Revision header is gone: the API went GA and requests
+                // succeed without it (verified live 2026-07-06; see docs/GEMINI-API.md).
+                // Don't re-add a pinned revision — it would freeze us on old semantics.
+                interactionsApi: createApiClient({ baseUrl: BASE_URL, serviceName: INTERACTIONS_SERVICE, ...shared }),
+            };
+            this.apis.set(timeoutMs, entry);
+        }
+        return entry;
     }
     requireKey() {
         if (this.configError)
@@ -81,8 +105,9 @@ export class GeminiClient {
     defaultModel() {
         return resolveModel(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));
     }
-    async call(method, path, body) {
-        return this.api.fetchJson(method, path, body !== undefined ? { body } : {});
+    async call(method, path, body, timeoutMs) {
+        const { api } = this.apisFor(timeoutMs ?? resolveTimeoutMs());
+        return api.fetchJson(method, path, body !== undefined ? { body } : {});
     }
     /**
      * Upload a local video to the Gemini Files API (resumable protocol) and wait
@@ -200,7 +225,7 @@ export class GeminiClient {
         const requestBody = { contents: [{ parts }], generationConfig };
         if (opts.googleSearch)
             requestBody.tools = [{ google_search: {} }];
-        const data = await this.call('POST', `/models/${model}:generateContent`, requestBody);
+        const data = await this.call('POST', `/models/${model}:generateContent`, requestBody, resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
         const images = [];
         const textParts = [];
         let groundingMeta;
@@ -263,10 +288,11 @@ export class GeminiClient {
                 searchTool.search_types = opts.searchTypes;
             body.tools = [searchTool];
         }
+        const { interactionsApi } = this.apisFor(resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
         let data;
         for (let attempt = 0;; attempt++) {
             try {
-                data = await this.interactionsApi.fetchJson('POST', '/interactions', {
+                data = await interactionsApi.fetchJson('POST', '/interactions', {
                     body,
                 });
                 break;

package/dist/images.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, access, stat, open } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
 import { readEnvVar, McpToolError } from '@chrischall/mcp-utils';
@@ -57,6 +57,16 @@ export async function writeImage(dir, base, base64, mimeType) {
     await writeFile(path, Buffer.from(base64, 'base64'));
     return resolve(path);
 }
+/**
+ * Write `<imagePath>.json` recording generation metadata (notably the
+ * interaction id) next to a written image. The MCP host's tools/call timeout
+ * can expire while the server-side generation finishes anyway — the response
+ * (and its interaction id) is then lost, but this sidecar survives, so the
+ * multi-turn chain is recoverable from disk.
+ */
+export async function writeSidecar(imagePath, data) {
+    await writeFile(`${imagePath}.json`, JSON.stringify(data, null, 2));
+}
 /**
  * Resolve an input file path, checking (in order):
  *  1. Absolute path that exists → returned as-is.
@@ -116,6 +126,37 @@ export function videoMimeType(p) {
     }
     return mime;
 }
+/**
+ * Preview a local IMAGE input WITHOUT sending it anywhere: resolve the path to
+ * an absolute one, sniff its mime from the leading bytes, and measure its size.
+ * Reads the file locally (to sniff/measure) but makes NO network/API call — so a
+ * prompt-injected `image_path` (e.g. a local secret) is visible before upload.
+ */
+export async function previewImageInput(path) {
+    const resolved = resolveImagePath(path);
+    // Read only the header bytes needed to sniff the MIME (≤12), and take the size
+    // from stat() — a dry-run must not load a large reference image into memory
+    // just to report it (matches previewVideoInput).
+    const { size } = await stat(resolved);
+    const fh = await open(resolved, 'r');
+    try {
+        const head = Buffer.alloc(16);
+        const { bytesRead } = await fh.read(head, 0, 16, 0);
+        return { path: resolved, mimeType: sniffMimeBytes(head.subarray(0, bytesRead)), size };
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Preview a local VIDEO input WITHOUT uploading it: resolve the path, derive its
+ * mime from the extension, and measure its size. Makes NO network/API call.
+ */
+export async function previewVideoInput(path) {
+    const resolved = resolveVideoPath(path);
+    const { size } = await stat(resolved);
+    return { path: resolved, mimeType: videoMimeType(resolved), size };
+}
 /** Read an image file into `{ base64, mimeType }` for an inline_data part. */
 export async function readImageAsInline(path) {
     const resolved = resolveImagePath(path);

package/dist/tools/_confirm.js

@@ -0,0 +1,39 @@
+import { schemaConfirm, textResult } from '@chrischall/mcp-utils';
+import { previewImageInput, previewVideoInput } from '../images.js';
+export { schemaConfirm };
+/**
+ * Confirm-gate for a mutating tool (the fleet convention). When `confirm` is not
+ * `true`, returns a no-network dry-run preview of exactly what would be sent;
+ * when it is `true`, returns `null` so the caller proceeds with the write.
+ */
+export function previewUnlessConfirmed(confirm, action, method, path, body) {
+    if (confirm === true)
+        return null;
+    return textResult({
+        dryRun: true,
+        action,
+        method,
+        path,
+        ...(body !== undefined ? { willSend: body } : {}),
+        note: 'Re-run with confirm: true to execute.',
+    });
+}
+/**
+ * Confirm-gate for a Gemini tool that ships LOCAL input files (image/video
+ * paths) to Google. Returns `null` (proceed) when `confirm === true` OR the call
+ * has no local file inputs — so pure text-to-image / base64 / clipboard calls
+ * are unaffected. Otherwise returns a NO-API dry-run echoing each RESOLVED
+ * ABSOLUTE input path plus its mime and size, so a prompt-injected path (e.g.
+ * `~/.ssh/id_rsa`) is visible and interceptable before any byte leaves the box.
+ */
+export async function previewLocalInputsUnlessConfirmed(confirm, action, endpoint, imagePaths, videoPath) {
+    const hasLocal = (imagePaths?.length ?? 0) > 0 || Boolean(videoPath);
+    if (confirm === true || !hasLocal)
+        return null;
+    const inputs = [];
+    for (const p of imagePaths ?? [])
+        inputs.push(await previewImageInput(p));
+    if (videoPath)
+        inputs.push(await previewVideoInput(videoPath));
+    return previewUnlessConfirmed(confirm, action, 'POST', endpoint, { inputs });
+}

package/dist/tools/generate.js

@@ -3,7 +3,10 @@ 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 } from './shared.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, resolveVideoInput, videoPathSchema, withProgressHeartbeat } from './shared.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';
 // generateContent output can't seed an Interactions-API conversation, so
 // results point follow-up edits at gemini_interact instead of an id.
 const REFINE_HINT = 'To iteratively refine this image, use gemini_interact (pass the output file via `images` on the first call, ' +
@@ -21,9 +24,16 @@ export function registerGenerateTools(server) {
             images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs'),
             video_url: z.string().url().optional().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,
+            confirm: schemaConfirm,
             ...sharedImageSchema,
         },
-    }, async (args) => {
+    }, async (args, extra) => {
+        // Confirm-gate local file inputs: a prompt-injected `images`/`video_path`
+        // could exfiltrate a local file. Pure text-to-image calls (no local input)
+        // are unaffected. Dry-run makes NO API call.
+        const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images, args.video_path);
+        if (gate)
+            return gate;
         const count = args.count ?? 1;
         const seed = pickSeed(args.seed);
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
@@ -31,34 +41,37 @@ export function registerGenerateTools(server) {
         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 resolveVideoInput(args);
+        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;
-        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,
-            });
-            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')}` });
-        }
+        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;
@@ -80,19 +93,25 @@ export function registerGenerateTools(server) {
             images: z.array(z.string().min(1)).optional().describe('Paths to input image file(s) (1 = edit, 2+ = compose)'),
             images_base64: z.array(z.string().min(1)).optional().describe('Input images as base64 strings or data URIs'),
             filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
+            confirm: schemaConfirm,
             ...sharedImageSchema,
         },
-    }, async (args) => {
+    }, async (args, extra) => {
         const hasPaths = (args.images?.length ?? 0) > 0;
         const hasBase64 = (args.images_base64?.length ?? 0) > 0;
         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 /
+        // 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 client.generate({
+        const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client.generate({
             prompt: args.prompt,
             images: inputs,
             model: args.model,
@@ -101,7 +120,8 @@ export function registerGenerateTools(server) {
             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)

package/dist/tools/interact.js

@@ -2,8 +2,9 @@ import { z } from 'zod';
 import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
-import { slugify, baseName, gatherImageInputs, resolveImagePath } from '../images.js';
-import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema } from './shared.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 { 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
 // host session, so "last" means "last in this session".
@@ -14,6 +15,16 @@ let lastInteractionId;
 // the model against the requested edit (observed in the wild — callers pass
 // the last result path back via `images` despite the description saying not to).
 const writtenOutputs = new Set();
+/**
+ * Test-only: clear the module-level session memory (`lastInteractionId` and the
+ * written-outputs set) so tests that assert the "no prior interaction" path are
+ * order-independent — they can't rely on module-load state once other tests have
+ * run first (e.g. under `--sequence.shuffle`).
+ */
+export function __resetInteractSessionForTest() {
+    lastInteractionId = undefined;
+    writtenOutputs.clear();
+}
 /** Shared warning for the reference-image params. */
 const NEW_REFERENCES_ONLY = 'NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, ' +
     "do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it " +
@@ -43,6 +54,9 @@ export function registerInteractTools(server) {
             'To refine, capture the returned interaction `id` and pass it as `previous_interaction_id` ' +
             'on the next call — do NOT start a new interaction or re-upload the image for each tweak. ' +
             '`continue_last: true` chains from this session\'s most recent interaction without threading the id. ' +
+            '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 — check the output dir before re-issuing (a re-issue is a second billable generation). ' +
             'Output is JPEG.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
@@ -103,12 +117,14 @@ export function registerInteractTools(server) {
                 .optional()
                 .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,
             from_clipboard: z
                 .boolean()
                 .optional()
                 .describe('Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)'),
+            confirm: schemaConfirm,
         },
-    }, async (args) => {
+    }, async (args, extra) => {
         let previousInteractionId = args.previous_interaction_id;
         if (!previousInteractionId && args.continue_last) {
             if (!lastInteractionId) {
@@ -123,9 +139,16 @@ export function registerInteractTools(server) {
         if (previousInteractionId && images?.length) {
             ({ kept: images, dropped } = splitReattachedOutputs(images));
         }
+        // Confirm-gate local file inputs AFTER the re-attach split, so the preview
+        // reflects the paths actually sent (dropped prior-output paths aren't). A
+        // prompt-injected `images`/`video_path` could exfiltrate a local file;
+        // base64/clipboard inputs pass through ungated. Dry-run makes NO API call.
+        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 resolveVideoInput(args);
-        const r = await client.interact({
+        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,
@@ -137,7 +160,8 @@ export function registerInteractTools(server) {
             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 };
@@ -160,7 +184,19 @@ export function registerInteractTools(server) {
             base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
         }));
         // writeImage returns already-resolved absolute paths.
-        return emit(named, args, meta, (paths) => { for (const p of paths)
-            writtenOutputs.add(p); });
+        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 {
+                for (const p of paths)
+                    await writeSidecar(p, { ...meta, images: paths });
+            }
+            catch (err) {
+                meta.sidecar_error = err instanceof Error ? err.message : String(err);
+            }
+        });
     });
 }

package/dist/tools/set.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 } from './shared.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, withProgressHeartbeat } from './shared.js';
+import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerSetTools(server) {
     server.registerTool('gemini_generate_set', {
         description: 'Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master).',
@@ -16,44 +17,55 @@ export function registerSetTools(server) {
             basename: z.string().optional().describe('Base filename prefix for output images (default: slugified master_prompt)'),
             master_images: z.array(z.string().min(1)).optional().describe('Reference image paths passed to the master generation call'),
             master_images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs for master generation'),
+            confirm: schemaConfirm,
             ...sharedImageSchema,
         },
-    }, async (args) => {
+    }, async (args, extra) => {
         // `scenes` is min(1) at the schema, so a non-undefined value is non-empty.
         if ((args.scenes && args.count) || (!args.scenes && !args.count)) {
             throw new McpToolError('Provide exactly one of `scenes` or `count`.');
         }
+        // Confirm-gate local file inputs: only `master_images` (paths) can read a
+        // local file; base64 references pass through ungated. Dry-run makes NO API call.
+        const gate = await previewLocalInputsUnlessConfirmed(args.confirm, 'Send local master image input(s) to the Gemini API', '/v1beta/models/{model}:generateContent', args.master_images);
+        if (gate)
+            return gate;
         const seed = pickSeed(args.seed);
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
-        const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search };
+        const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
         const slug = args.basename ? baseName(args.basename) : slugify(args.master_prompt);
         // 1. master (optionally seeded from reference images)
         const masterRefInputs = await gatherImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard });
-        const masterResult = await client.generate({
-            prompt: args.master_prompt,
-            images: masterRefInputs.length > 0 ? masterRefInputs : undefined,
-            seed,
-            ...cfg,
-        });
-        const { images: [master], text: masterText } = masterResult;
-        const named = [{ image: master, base: `${slug}-master` }];
-        // Only the master's text is surfaced (below). Per-scene text is intentionally
-        // dropped — a set returns one combined result and merging N captions is noise.
-        // 2. scene prompts (explicit, or N repeats of master_prompt for variations)
-        const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
-        const mode = args.reference_mode ?? 'master';
-        if (mode === 'chain') {
-            let ref = master;
-            for (let i = 0; i < scenePrompts.length; i++) {
-                const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref], seed: seed + i + 1, ...cfg });
-                named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` });
-                ref = img;
+        const named = [];
+        const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
+            const result = await client.generate({
+                prompt: args.master_prompt,
+                images: masterRefInputs.length > 0 ? masterRefInputs : undefined,
+                seed,
+                ...cfg,
+            });
+            const master = result.images[0];
+            named.push({ image: master, base: `${slug}-master` });
+            // Only the master's text is surfaced (below). Per-scene text is intentionally
+            // dropped — a set returns one combined result and merging N captions is noise.
+            // 2. scene prompts (explicit, or N repeats of master_prompt for variations)
+            const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
+            const mode = args.reference_mode ?? 'master';
+            if (mode === 'chain') {
+                let ref = master;
+                for (let i = 0; i < scenePrompts.length; i++) {
+                    const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref], seed: seed + i + 1, ...cfg });
+                    named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` });
+                    ref = img;
+                }
             }
-        }
-        else {
-            const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
-            scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` }));
-        }
+            else {
+                const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
+                scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` }));
+            }
+            return result;
+        });
+        const masterText = masterResult.text;
         const meta = buildMeta(model, seed, args);
         if (masterText)
             meta.text = masterText;