@chrischall/gemini-mcp 0.8.0 → 0.9.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -26,8 +26,16 @@ The server sends `notifications/progress` heartbeats so hosts that reset their t
 progress wait it out. If the host still gives up, the server-side generation usually completes
 anyway: the image is written to the output dir, `gemini_interact` also writes an
 `<image>.json` sidecar recording the `interaction_id`, and `continue_last: true` resumes the
-interaction the lost response belonged to — check the output dir before re-issuing a call
-(a re-issue is a second billable generation).
+interaction the lost response belonged to.
+
+For hosts whose timeout can't be tamed (e.g. Claude Desktop, a fixed ~30s cap that ignores
+progress), two guards make re-issuing safe and unnecessary:
+
+- **`async: true`** returns a `job_id` immediately instead of the image, so the call can't
+  time out at all; poll `gemini_get_result` with the `job_id` until it's `done`.
+- **`idempotency_key`** makes a repeat call idempotent — a retry with the same key returns the
+  recorded result (`reused: true`) instead of billing a second generation. (Even without a key,
+  two identical in-flight calls are deduplicated automatically.)
 
 ## Tools
 
@@ -38,6 +46,7 @@ interaction the lost response belonged to — check the output dir before re-iss
 | `gemini_edit_image` | One-off edits or multi-image composition with a text instruction (for a series of edits, use `gemini_interact`) |
 | `gemini_generate_set` | Generate a master image plus N consistent images referencing it |
 | `gemini_interact` | Preferred tool for iterative refinement: multi-turn generation/editing via the Interactions API — chain the returned `interaction_id` via `previous_interaction_id` (or `continue_last: true`) |
+| `gemini_get_result` | Fetch an async generation started with `async: true` by its `job_id` (status `running` → `done` result). Lets a long generation outlive a host's `tools/call` timeout |
 
 ## Quick Start
 

package/dist/bundle.js

@@ -32606,7 +32606,7 @@ var init_clipboard = __esm({
 init_dist();
 
 // src/version.ts
-var VERSION = "0.8.0";
+var VERSION = "0.9.0";
 
 // src/tools/models.ts
 init_dist();
@@ -33121,6 +33121,12 @@ var MODEL_CHOICE_GUIDE = "gemini-3.1-flash-image (Nano Banana 2) is the versatil
 var timeoutMsSchema = external_exports.number().int().positive().optional().describe(
   "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 \u2014 or 120000 when image_size is 4K, which routinely runs past 60s)"
 );
+var idempotencyKeySchema = external_exports.string().min(1).optional().describe(
+  "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."
+);
+var asyncSchema = external_exports.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)."
+);
 var sharedImageSchema = {
   // Bare id only: the model is interpolated into the URL path
   // (`/models/${model}:generateContent`), so slashes/colons/queries must be
@@ -33134,7 +33140,9 @@ var sharedImageSchema = {
   thinking_level: external_exports.enum(["minimal", "high"]).optional().describe("Reasoning depth (Gemini 3 models); higher can help complex/structural edits"),
   google_search: external_exports.boolean().optional().describe("Ground the image in live Google Search results (current events, weather, data)"),
   from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
-  timeout_ms: timeoutMsSchema
+  timeout_ms: timeoutMsSchema,
+  idempotency_key: idempotencyKeySchema,
+  async: asyncSchema
 };
 async function resolveVideoInput(args) {
   if (args.video_url && args.video_path) {
@@ -33159,16 +33167,28 @@ async function withProgressHeartbeat(extra, message, fn) {
   const send = extra?.sendNotification;
   const env = Number(readEnvVar("GEMINI_HEARTBEAT_MS"));
   const intervalMs = Number.isFinite(env) ? env : HEARTBEAT_DEFAULT_MS;
+  const debug = !!readEnvVar("GEMINI_DEBUG");
+  const active = progressToken !== void 0 && !!send && intervalMs > 0;
+  if (debug) {
+    if (active) {
+      console.error(`[gemini-mcp] heartbeat active: progressToken present, interval=${intervalMs}ms \u2014 ${message}`);
+    } else {
+      const reason = progressToken === void 0 ? "no progressToken from host (host cannot extend its tools/call timeout; long calls will hit it)" : !send ? "host provided no sendNotification channel" : "heartbeat disabled (GEMINI_HEARTBEAT_MS=0)";
+      console.error(`[gemini-mcp] heartbeat inactive: ${reason} \u2014 ${message}`);
+    }
+  }
   if (progressToken === void 0 || !send || intervalMs <= 0) return fn();
   let ticks = 0;
   const timer = setInterval(() => {
     ticks++;
+    const elapsed = Math.round(ticks * intervalMs / 1e3);
+    if (debug) console.error(`[gemini-mcp] heartbeat: ${message} \u2014 still working (${elapsed}s)`);
     void send({
       method: "notifications/progress",
       params: {
         progressToken,
         progress: ticks,
-        message: `${message} \u2014 still working (${Math.round(ticks * intervalMs / 1e3)}s)`
+        message: `${message} \u2014 still working (${elapsed}s)`
       }
     }).catch(() => {
     });
@@ -33180,6 +33200,14 @@ async function withProgressHeartbeat(extra, message, fn) {
     clearInterval(timer);
   }
 }
+function timeoutRiskHint(opts) {
+  const proModel = /(?:^|[-_./])pro(?:[-_./]|$)/i.test(opts.model);
+  const fourK = opts.imageSize === "4K";
+  const multi = (opts.count ?? 1) > 1;
+  if (!proModel && !fourK && !multi) return void 0;
+  const why = [proModel && "Pro model", fourK && "4K output", multi && `count=${opts.count}`].filter(Boolean).join(" + ");
+  return `Slow config (${why}) can exceed a host's tools/call timeout (e.g. Claude Desktop ~30s, error -32001). If the host gives up mid-generation the image is still written to disk (and gemini_interact leaves an <image>.json sidecar with the interaction id) \u2014 no rerun needed, just look in the output dir. For a faster in-band result use a Flash model, drop image_size to 1K/2K, or \u2014 in Claude Code \u2014 set MCP_TOOL_TIMEOUT.`;
+}
 function buildMeta(model, seed, opts) {
   const meta3 = { model, seed };
   if (opts.aspect_ratio) meta3.aspect_ratio = opts.aspect_ratio;
@@ -33203,6 +33231,118 @@ async function emit(named, opts, meta3, onWritten) {
   return textResult({ images, ...meta3 });
 }
 
+// src/jobs.ts
+init_dist();
+import { randomUUID, createHash } from "node:crypto";
+var JOB_TTL_MS = 6e5;
+var JOB_MAX = 64;
+var jobs = /* @__PURE__ */ new Map();
+var byKey = /* @__PURE__ */ new Map();
+var runningByFingerprint = /* @__PURE__ */ new Map();
+function isExpired(entry, now) {
+  return entry.settledAt !== void 0 && now - entry.settledAt > JOB_TTL_MS;
+}
+function evict(now) {
+  for (const [id, entry] of jobs) {
+    if (isExpired(entry, now)) remove(id, entry);
+  }
+  if (jobs.size < JOB_MAX) return;
+  const settled = [...jobs.values()].filter((e) => e.settledAt !== void 0).sort((a, b) => (a.settledAt ?? 0) - (b.settledAt ?? 0));
+  for (const e of settled) {
+    if (jobs.size < JOB_MAX) break;
+    remove(e.jobId, e);
+  }
+}
+function remove(id, entry) {
+  jobs.delete(id);
+  if (entry.idempotencyKey !== void 0 && byKey.get(entry.idempotencyKey) === id) byKey.delete(entry.idempotencyKey);
+  if (runningByFingerprint.get(entry.fingerprint) === id) runningByFingerprint.delete(entry.fingerprint);
+}
+function fingerprintRequest(toolName, parts) {
+  return createHash("sha256").update(`${toolName}\0${JSON.stringify(parts)}`).digest("hex");
+}
+function annotateReused(result, jobId) {
+  const content = result.content ?? [];
+  const first = content[0];
+  if (first && first.type === "text") {
+    let obj;
+    try {
+      obj = JSON.parse(first.text);
+    } catch {
+      obj = {};
+    }
+    obj.reused = true;
+    obj.reused_job_id = jobId;
+    return { ...result, content: [{ ...first, text: JSON.stringify(obj, null, 2) }, ...content.slice(1)] };
+  }
+  return {
+    ...result,
+    content: [{ type: "text", text: JSON.stringify({ reused: true, reused_job_id: jobId }, null, 2) }, ...content]
+  };
+}
+function jobHandle(jobId, status) {
+  return textResult({
+    job_id: jobId,
+    status,
+    hint: `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done" (results are per-process and expire ~10 min after completion).`
+  });
+}
+async function dispatch(opts, work) {
+  const { toolName, fingerprint, idempotencyKey, async } = opts;
+  const now = Date.now();
+  let hit;
+  if (idempotencyKey !== void 0) {
+    const id = byKey.get(idempotencyKey);
+    const entry2 = id ? jobs.get(id) : void 0;
+    if (entry2 && entry2.status !== "failed" && !isExpired(entry2, now)) hit = entry2;
+  } else {
+    const id = runningByFingerprint.get(fingerprint);
+    const entry2 = id ? jobs.get(id) : void 0;
+    if (entry2 && entry2.status === "running") hit = entry2;
+  }
+  if (hit) {
+    if (async) return jobHandle(hit.jobId, hit.status);
+    return annotateReused(await hit.promise, hit.jobId);
+  }
+  const jobId = randomUUID();
+  evict(now);
+  const promise2 = work();
+  const entry = { jobId, toolName, fingerprint, idempotencyKey, status: "running", promise: promise2, createdAt: now };
+  jobs.set(jobId, entry);
+  if (idempotencyKey !== void 0) byKey.set(idempotencyKey, jobId);
+  runningByFingerprint.set(fingerprint, jobId);
+  promise2.then(
+    (res) => {
+      entry.status = "done";
+      entry.result = res;
+      entry.settledAt = Date.now();
+    },
+    (err) => {
+      entry.status = "failed";
+      entry.error = { message: err instanceof Error ? err.message : String(err), hint: err?.hint };
+      entry.settledAt = Date.now();
+    }
+  ).finally(() => {
+    if (runningByFingerprint.get(fingerprint) === jobId) runningByFingerprint.delete(fingerprint);
+  });
+  if (async) return jobHandle(jobId, "running");
+  return promise2;
+}
+function getJobResult(jobId) {
+  const entry = jobs.get(jobId);
+  if (!entry) {
+    throw new McpToolError(`No job "${jobId}" \u2014 unknown or expired.`, {
+      hint: "Jobs are per-process and evicted ~10 min after completion (or on server restart). If the generation likely finished, check the output dir / <image>.json sidecar instead of polling."
+    });
+  }
+  if (entry.status === "running") return jobHandle(jobId, "running");
+  if (entry.status === "failed") {
+    throw new McpToolError(entry.error?.message ?? "Job failed.", entry.error?.hint ? { hint: entry.error.hint } : void 0);
+  }
+  if (!entry.result) throw new McpToolError(`Job "${jobId}" completed without a recorded result.`);
+  return entry.result;
+}
+
 // src/tools/_confirm.ts
 init_dist();
 function previewUnlessConfirmed(confirm, action, method, path, body) {
@@ -33251,41 +33391,59 @@ function registerGenerateTools(server) {
       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"));
-      const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
-      const refInputs = await gatherImageInputs({ images: args.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 named = [];
-      let capturedText;
-      let capturedGrounding;
-      await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : "image"} (${model})`, async () => {
-        for (let i = 0; i < count; i++) {
-          const result = await client.generate({
-            prompt: args.prompt,
-            images: refInputs.length > 0 ? refInputs : void 0,
-            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 fingerprint = fingerprintRequest("gemini_generate_image", {
+        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_generate_image", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        const seed = pickSeed(args.seed);
+        const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
+        const refInputs = await gatherImageInputs({ images: args.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 named = [];
+        let capturedText;
+        let capturedGrounding;
+        await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : "image"} (${model})`, async () => {
+          for (let i = 0; i < count; i++) {
+            const result = await client.generate({
+              prompt: args.prompt,
+              images: refInputs.length > 0 ? refInputs : void 0,
+              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 meta3 = buildMeta(model, seed, args);
+        if (capturedText) meta3.text = capturedText;
+        if (capturedGrounding) meta3.grounding = capturedGrounding;
+        if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
+        meta3.hint = REFINE_HINT;
+        const risk = timeoutRiskHint({ model, imageSize: args.image_size, count });
+        if (risk) meta3.timeout_risk = risk;
+        return emit(named, args, meta3);
       });
-      const meta3 = buildMeta(model, seed, args);
-      if (capturedText) meta3.text = capturedText;
-      if (capturedGrounding) meta3.grounding = capturedGrounding;
-      if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
-      meta3.hint = REFINE_HINT;
-      return emit(named, args, meta3);
     }
   );
   server.registerTool(
@@ -33310,27 +33468,42 @@ function registerGenerateTools(server) {
       }
       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) : slugify2(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({
+      const fingerprint = fingerprintRequest("gemini_edit_image", {
+        model,
         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 meta3 = buildMeta(model, seed, args);
-      if (text) meta3.text = text;
-      if (result.grounding) meta3.grounding = result.grounding;
-      meta3.hint = REFINE_HINT;
-      return emit([{ image: img, base: slug }], args, meta3);
+        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_edit_image", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        const seed = pickSeed(args.seed);
+        const slug = args.filename ? baseName(args.filename) : slugify2(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 meta3 = buildMeta(model, seed, args);
+        if (text) meta3.text = text;
+        if (result.grounding) meta3.grounding = result.grounding;
+        meta3.hint = REFINE_HINT;
+        const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+        if (risk) meta3.timeout_risk = risk;
+        return emit([{ image: img, base: slug }], args, meta3);
+      });
     }
   );
 }
@@ -33362,43 +33535,61 @@ function registerSetTools(server) {
       }
       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, timeoutMs: args.timeout_ms };
-      const slug = args.basename ? baseName(args.basename) : slugify2(args.master_prompt);
-      const masterRefInputs = await gatherImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard });
-      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 : void 0,
-          seed,
-          ...cfg
-        });
-        const master = result.images[0];
-        named.push({ image: master, base: `${slug}-master` });
-        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 fingerprint = fingerprintRequest("gemini_generate_set", {
+        model,
+        master_prompt: args.master_prompt,
+        scenes: args.scenes,
+        count: args.count,
+        reference_mode: args.reference_mode,
+        aspect_ratio: args.aspect_ratio,
+        image_size: args.image_size,
+        thinking_level: args.thinking_level,
+        google_search: args.google_search,
+        master_images: args.master_images,
+        master_images_base64: args.master_images_base64,
+        from_clipboard: args.from_clipboard
+      });
+      return dispatch({ toolName: "gemini_generate_set", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        const seed = pickSeed(args.seed);
+        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) : slugify2(args.master_prompt);
+        const masterRefInputs = await gatherImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard });
+        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 : void 0,
+            seed,
+            ...cfg
+          });
+          const master = result.images[0];
+          named.push({ image: master, base: `${slug}-master` });
+          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;
+          return result;
+        });
+        const masterText = masterResult.text;
+        const meta3 = buildMeta(model, seed, args);
+        if (masterText) meta3.text = masterText;
+        if (masterResult.grounding) meta3.grounding = masterResult.grounding;
+        const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length });
+        if (risk) meta3.timeout_risk = risk;
+        return emit(named, args, meta3);
       });
-      const masterText = masterResult.text;
-      const meta3 = buildMeta(model, seed, args);
-      if (masterText) meta3.text = masterText;
-      if (masterResult.grounding) meta3.grounding = masterResult.grounding;
-      return emit(named, args, meta3);
     }
   );
 }
@@ -33448,6 +33639,8 @@ function registerInteractTools(server) {
         video_url: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
         video_path: videoPathSchema,
         timeout_ms: timeoutMsSchema,
+        idempotency_key: idempotencyKeySchema,
+        async: asyncSchema,
         from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
         confirm: schemaConfirm
       }
@@ -33469,52 +33662,87 @@ 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 : void 0,
-        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 meta3 = { model, interaction_id: r.id };
-      if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
-      if (dropped.length) meta3.dropped_previous_output = dropped;
-      meta3.hint = `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) \u2014 do NOT re-attach the returned image as an input; the interaction already contains it.`;
-      if (r.text) meta3.text = r.text;
-      if (r.grounding) meta3.grounding = r.grounding;
-      if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
-      const slug = args.filename ? baseName(args.filename) : slugify2(args.input);
-      const named = r.images.map((image, i) => ({
-        image,
-        base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, "0")}` : slug
-      }));
-      return emit(named, args, meta3, async (paths) => {
-        for (const p of paths) writtenOutputs.add(p);
-        try {
-          for (const p of paths) await writeSidecar(p, { ...meta3, images: paths });
-        } catch (err) {
-          meta3.sidecar_error = err instanceof Error ? err.message : String(err);
-        }
+      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 : void 0,
+          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 meta3 = { model, interaction_id: r.id };
+        if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
+        if (dropped.length) meta3.dropped_previous_output = dropped;
+        meta3.hint = `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) \u2014 do NOT re-attach the returned image as an input; the interaction already contains it.`;
+        if (r.text) meta3.text = r.text;
+        if (r.grounding) meta3.grounding = r.grounding;
+        if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
+        const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+        if (risk) meta3.timeout_risk = risk;
+        const slug = args.filename ? baseName(args.filename) : slugify2(args.input);
+        const named = r.images.map((image, i) => ({
+          image,
+          base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, "0")}` : slug
+        }));
+        return emit(named, args, meta3, async (paths) => {
+          for (const p of paths) writtenOutputs.add(p);
+          try {
+            for (const p of paths) await writeSidecar(p, { ...meta3, images: paths });
+          } catch (err) {
+            meta3.sidecar_error = err instanceof Error ? err.message : String(err);
+          }
+        });
       });
     }
   );
 }
 
+// src/tools/jobs.ts
+init_zod();
+function registerJobTools(server) {
+  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 are per-process and expire ~10 min after completion \u2014 if a job id is unknown, check the output dir / <image>.json sidecar.',
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      inputSchema: {
+        job_id: external_exports.string().min(1).describe("The job_id returned by a generation tool called with async: true")
+      }
+    },
+    async (args) => getJobResult(args.job_id)
+  );
+}
+
 // src/index.ts
 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, registerJobTools]
 });

package/dist/index.js

@@ -5,6 +5,7 @@ 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 { 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 +13,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, registerJobTools],
 });

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';
@@ -35,52 +36,65 @@ 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_generate_image', {
+            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_generate_image', 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', {
         description: 'Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. ' +
@@ -107,28 +121,38 @@ export function registerGenerateTools(server) {
         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_edit_image', {
+            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_edit_image', 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);
+                }
+            });
         });
     });
 }

package/dist/tools/jobs.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { getJobResult } from '../jobs.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
+ * past a host's tools/call timeout); this tool retrieves that job's status and,
+ * once complete, its normal result payload.
+ */
+export function registerJobTools(server) {
+    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 are per-process and expire ~10 min after completion — if a job id is unknown, check the output dir / <image>.json sidecar.',
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: {
+            job_id: z.string().min(1).describe('The job_id returned by a generation tool called with async: true'),
+        },
+    }, async (args) => getJobResult(args.job_id));
+}

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, withProgressHeartbeat } from './shared.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat } from './shared.js';
+import { dispatch, fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerSetTools(server) {
     server.registerTool('gemini_generate_set', {
@@ -30,47 +31,60 @@ export function registerSetTools(server) {
         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, 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 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;
+        const fingerprint = fingerprintRequest('gemini_generate_set', {
+            model, master_prompt: args.master_prompt, scenes: args.scenes, count: args.count,
+            reference_mode: args.reference_mode, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            thinking_level: args.thinking_level, google_search: args.google_search,
+            master_images: args.master_images, master_images_base64: args.master_images_base64, from_clipboard: args.from_clipboard,
+        });
+        return dispatch({ toolName: 'gemini_generate_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+            const seed = pickSeed(args.seed);
+            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 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')}` }));
-            }
-            return result;
+                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;
+            if (masterResult.grounding)
+                meta.grounding = masterResult.grounding;
+            // A set is master + N scenes in one tools/call — the most timeout-prone
+            // tool. Effective image count drives the risk hint.
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length });
+            if (risk)
+                meta.timeout_risk = risk;
+            return emit(named, args, meta);
         });
-        const masterText = masterResult.text;
-        const meta = buildMeta(model, seed, args);
-        if (masterText)
-            meta.text = masterText;
-        if (masterResult.grounding)
-            meta.grounding = masterResult.grounding;
-        return emit(named, args, meta);
     });
 }

package/dist/tools/shared.js

@@ -26,6 +26,26 @@ export const timeoutMsSchema = z
     .positive()
     .optional()
     .describe('Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)');
+/**
+ * Idempotency key shared by every generation tool. A repeat call carrying the
+ * same key returns the recorded result (`reused: true`) instead of billing a
+ * fresh generation — the fix for a host timeout (`-32001`) prompting a blind
+ * re-issue of a call the server actually completed.
+ */
+export const idempotencyKeySchema = z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.');
+/**
+ * Async escape hatch shared by every generation tool: return a `job_id`
+ * immediately so a long (Pro/4K) generation can't hit a host's fixed tools/call
+ * timeout (`-32001`). The caller polls `gemini_get_result`.
+ */
+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).');
 /**
  * The model/aspect/size/output fields every generation tool shares. Defined once
  * here so descriptions can't drift between `generate.ts` and `set.ts`. Spread
@@ -49,6 +69,8 @@ export const sharedImageSchema = {
     google_search: z.boolean().optional().describe('Ground the image in live Google Search results (current events, weather, data)'),
     from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)'),
     timeout_ms: timeoutMsSchema,
+    idempotency_key: idempotencyKeySchema,
+    async: asyncSchema,
 };
 /**
  * Turn the `video_url` / `video_path` tool args into the client's video opts.
@@ -99,17 +121,41 @@ export async function withProgressHeartbeat(extra, message, fn) {
     const send = extra?.sendNotification;
     const env = Number(readEnvVar('GEMINI_HEARTBEAT_MS'));
     const intervalMs = Number.isFinite(env) ? env : HEARTBEAT_DEFAULT_MS;
+    const debug = !!readEnvVar('GEMINI_DEBUG');
+    const active = progressToken !== undefined && !!send && intervalMs > 0;
+    // Diagnostics (opt-in via GEMINI_DEBUG). Goes to stderr — the only channel
+    // safe under the stdio transport, and where the host surfaces it (Claude
+    // Desktop: ~/Library/Logs/Claude/mcp-server-*.log). The active/inactive line
+    // reveals whether the host even asked for progress: a missing progressToken
+    // means the host cannot be kept alive by our heartbeat, so a long call will
+    // hit the host's own tools/call timeout no matter what we send.
+    if (debug) {
+        if (active) {
+            console.error(`[gemini-mcp] heartbeat active: progressToken present, interval=${intervalMs}ms — ${message}`);
+        }
+        else {
+            const reason = progressToken === undefined
+                ? 'no progressToken from host (host cannot extend its tools/call timeout; long calls will hit it)'
+                : !send
+                    ? 'host provided no sendNotification channel'
+                    : 'heartbeat disabled (GEMINI_HEARTBEAT_MS=0)';
+            console.error(`[gemini-mcp] heartbeat inactive: ${reason} — ${message}`);
+        }
+    }
     if (progressToken === undefined || !send || intervalMs <= 0)
         return fn();
     let ticks = 0;
     const timer = setInterval(() => {
         ticks++;
+        const elapsed = Math.round((ticks * intervalMs) / 1000);
+        if (debug)
+            console.error(`[gemini-mcp] heartbeat: ${message} — still working (${elapsed}s)`);
         void send({
             method: 'notifications/progress',
             params: {
                 progressToken,
                 progress: ticks,
-                message: `${message} — still working (${Math.round((ticks * intervalMs) / 1000)}s)`,
+                message: `${message} — still working (${elapsed}s)`,
             },
         }).catch(() => { });
     }, intervalMs);
@@ -122,6 +168,32 @@ export async function withProgressHeartbeat(extra, message, fn) {
         clearInterval(timer);
     }
 }
+/**
+ * Some configs routinely run long enough to trip a host's tools/call timeout —
+ * Pro models, 4K output, or multi-image counts. Claude Desktop caps at ~30s,
+ * ignores our progress heartbeat, and offers no config to raise it (verified: the
+ * bundled MCP client's hard limit does not reset on notifications/progress), so
+ * such a call surfaces as `-32001 Request timed out`. Returned as
+ * `meta.timeout_risk` so a caller that *does* get the result is steered off the
+ * slow path next time and knows the image still landed on disk when a host bails.
+ * `undefined` for fast configs (no field added).
+ */
+export function timeoutRiskHint(opts) {
+    // Delimiter-anchored so real Pro ids (gemini-3-pro-image, nano-banana-pro)
+    // match but incidental substrings (…-prototype-…, …-flash-proxy) don't.
+    const proModel = /(?:^|[-_./])pro(?:[-_./]|$)/i.test(opts.model);
+    const fourK = opts.imageSize === '4K';
+    const multi = (opts.count ?? 1) > 1;
+    if (!proModel && !fourK && !multi)
+        return undefined;
+    const why = [proModel && 'Pro model', fourK && '4K output', multi && `count=${opts.count}`]
+        .filter(Boolean)
+        .join(' + ');
+    return (`Slow config (${why}) can exceed a host's tools/call timeout (e.g. Claude Desktop ~30s, error -32001). ` +
+        `If the host gives up mid-generation the image is still written to disk (and gemini_interact leaves an ` +
+        `<image>.json sidecar with the interaction id) — no rerun needed, just look in the output dir. ` +
+        `For a faster in-band result use a Flash model, drop image_size to 1K/2K, or — in Claude Code — set MCP_TOOL_TIMEOUT.`);
+}
 /** Build the result metadata echoed to the caller (omitting unset optionals). */
 export function buildMeta(model, seed, opts) {
     const meta = { model, seed };

package/dist/version.js

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

package/package.json

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