@chrischall/gemini-mcp 0.7.2 → 0.9.0

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,9 @@ 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, 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', {
         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,49 +18,73 @@ 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`.');
         }
-        const seed = pickSeed(args.seed);
+        // 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 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 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 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;
+            });
+            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 { 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;
-            }
-        }
-        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')}` }));
-        }
-        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

@@ -1,16 +1,11 @@
 import { z } from 'zod';
-import { textResult, McpToolError } from '@chrischall/mcp-utils';
+import { textResult, McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
 import { writeImage, resolveOutputDir, resolveVideoPath, videoMimeType } from '../images.js';
 /** Supported output aspect ratios (Gemini image API). */
 export const ASPECT_RATIOS = ['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9', '1:4', '4:1', '1:8', '8:1'];
 /** Supported output resolutions. `512` is Flash-only (0.5K); `1K`/`2K`/`4K` work on all image models. */
 export const IMAGE_SIZES = ['512', '1K', '2K', '4K'];
-/**
- * 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
- * into each tool's `inputSchema`.
- */
 /**
  * When to pick which Nano Banana model — shared by every tool's `model` param
  * so the guidance can't drift between them.
@@ -20,6 +15,42 @@ export const MODEL_CHOICE_GUIDE = 'gemini-3.1-flash-image (Nano Banana 2) is the
     'processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex ' +
     'visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. ' +
     'gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).';
+/**
+ * Per-call upstream timeout override, shared by every generation tool
+ * (spread via {@link sharedImageSchema}; `gemini_interact` imports it directly
+ * since its schema doesn't take the seed/clipboard fields).
+ */
+export const timeoutMsSchema = z
+    .number()
+    .int()
+    .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
+ * into each tool's `inputSchema`.
+ */
 export const sharedImageSchema = {
     // Bare id only: the model is interpolated into the URL path
     // (`/models/${model}:generateContent`), so slashes/colons/queries must be
@@ -37,6 +68,9 @@ export const sharedImageSchema = {
     thinking_level: z.enum(['minimal', 'high']).optional().describe('Reasoning depth (Gemini 3 models); higher can help complex/structural edits'),
     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.
@@ -71,6 +105,95 @@ export const videoPathSchema = z
 export function pickSeed(seed) {
     return seed ?? Math.floor(Math.random() * 2_147_483_000);
 }
+// Progress-heartbeat cadence while a generation is in flight. MCP hosts
+// enforce their own tools/call timeout (surfaced as -32001) but reset it on
+// notifications/progress, so a heartbeat lets a 4K/Pro generation outlive the
+// host's default budget. Tunable via $GEMINI_HEARTBEAT_MS (0 disables).
+const HEARTBEAT_DEFAULT_MS = 10_000;
+/**
+ * Run `fn`, emitting a `notifications/progress` heartbeat while it is pending —
+ * but only when the caller asked for progress (sent a `progressToken`).
+ * Send failures are swallowed (the client may have abandoned the request);
+ * `fn`'s result/rejection passes through untouched.
+ */
+export async function withProgressHeartbeat(extra, message, fn) {
+    const progressToken = extra?._meta?.progressToken;
+    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 (${elapsed}s)`,
+            },
+        }).catch(() => { });
+    }, intervalMs);
+    // Never hold the process open just for a heartbeat.
+    timer.unref?.();
+    try {
+        return await fn();
+    }
+    finally {
+        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 };
@@ -86,7 +209,8 @@ export function buildMeta(model, seed, opts) {
  * Optional `meta` is merged into the disk-path JSON result, or prepended as a
  * text block in inline mode (only if meta has keys).
  * Optional `onWritten` receives the absolute paths written in disk mode (never
- * called inline) — lets a tool remember its own outputs.
+ * called inline) — lets a tool remember its own outputs or write sidecar
+ * files; an async callback is awaited before the result is returned.
  */
 export async function emit(named, opts, meta, onWritten) {
     if (opts.inline) {
@@ -102,6 +226,6 @@ export async function emit(named, opts, meta, onWritten) {
     const images = [];
     for (const n of named)
         images.push(await writeImage(dir, n.base, n.image.base64, n.image.mimeType));
-    onWritten?.(images);
+    await onWritten?.(images);
     return textResult({ images, ...meta });
 }

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '0.7.2'; // 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.7.2",
+  "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>",
@@ -44,7 +44,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.10.3",
+    "@chrischall/mcp-utils": "^0.12.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "0.7.2",
+  "version": "0.9.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "0.7.2",
+      "version": "0.9.0",
       "transport": {
         "type": "stdio"
       },