@chrischall/gemini-mcp 0.6.1 → 0.7.1

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.6.1"
+    "version": "0.7.1"
   },
   "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.6.1",
+      "version": "0.7.1",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gemini-mcp",
   "displayName": "Gemini Images",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "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

@@ -13,7 +13,7 @@ Developed and maintained by AI (Claude Code).
 | Variable | Required | Description |
 |---|---|---|
 | `GEMINI_API_KEY` | Yes | Your Google Gemini API key ([aistudio.google.com/apikey](https://aistudio.google.com/apikey)) |
-| `GEMINI_IMAGE_MODEL` | No | Override the default image model (default: `gemini-3-pro-image`) |
+| `GEMINI_IMAGE_MODEL` | No | Override the default image model (default: `gemini-3.1-flash-image`) |
 | `GEMINI_OUTPUT_DIR` | No | Default directory for generated images (default: current working directory) |
 | `GEMINI_INPUT_DIR` | No | Directory to resolve bare input-image filenames against (so `images: ["foo.jpg"]` works) |
 
@@ -23,9 +23,9 @@ Developed and maintained by AI (Claude Code).
 |------|-------------|
 | `gemini_list_models` | List available Gemini image models and the current default |
 | `gemini_generate_image` | Generate image(s) from a text prompt |
-| `gemini_edit_image` | Edit or compose one or more input images with a text instruction |
+| `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` | Multi-turn generation/editing via the Interactions API (Beta); returns an `interaction_id` to refine the same image conversationally |
+| `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`) |
 
 ## Quick Start
 

package/SKILL.md

@@ -69,7 +69,7 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 | Variable | Required | Description |
 |---|---|---|
 | `GEMINI_API_KEY` | Yes | Your Google Gemini API key |
-| `GEMINI_IMAGE_MODEL` | No | Override the default image model (default: `gemini-3-pro-image`) |
+| `GEMINI_IMAGE_MODEL` | No | Override the default image model (default: `gemini-3.1-flash-image`) |
 | `GEMINI_OUTPUT_DIR` | No | Default directory for saved images (default: current working directory) |
 | `GEMINI_INPUT_DIR` | No | Directory to resolve bare input-image filenames against (e.g. point at Cowork's `uploads/` folder so `images: ["house.jpg"]` works) |
 
@@ -80,6 +80,14 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 |------|-------------|
 | `gemini_list_models` | List available Gemini image models and the current default |
 
+**Which model to pick** (per-call `model`, or `GEMINI_IMAGE_MODEL`):
+
+| Model | When to use | Reference-image caps (of 14 max) |
+|-------|-------------|----------------------------------|
+| `gemini-3.1-flash-image` (Nano Banana 2) | The versatile generalist workhorse for all tasks — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. Only model with video input + image_search grounding | 10 objects + 4 characters + 3 style refs |
+| `gemini-3-pro-image` (Nano Banana Pro) | The premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control | 6 objects + 5 characters |
+| `gemini-3.1-flash-lite-image` (Nano Banana 2 Lite) | The fastest/cheapest for simple tasks — 1K output only, no Google Search grounding | 14 objects (no character consistency) |
+
 ### Image Generation
 | Tool | Description |
 |------|-------------|
@@ -87,10 +95,10 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 | `gemini_edit_image(prompt, images?, images_base64?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Edit or compose input image(s) — by **path** (`images`) or **value** (`images_base64`: data URI or raw base64) — with a text instruction. Requires ≥1 input |
 | `gemini_generate_set(master_prompt, scenes? \| count?, reference_mode?, master_images?, master_images_base64?, google_search?, seed?, basename?, model?, thinking_level?, ...)` | Master image (optionally seeded from a reference photo) plus N consistent images referencing it |
 
-### Multi-turn (Interactions API — Beta)
+### Multi-turn (Interactions API)
 | Tool | Description |
 |------|-------------|
-| `gemini_interact(input, previous_interaction_id?, images?, images_base64?, video_url?, video_path?, google_search?, model?, aspect_ratio?, image_size?, thinking_level?, filename?, output_dir?, inline?)` | Generate/edit via Gemini's **Interactions API**. Returns an `interaction_id`; pass it back as `previous_interaction_id` to **iteratively refine the same image** conversationally — the recommended way to make incremental edits. Output is **JPEG**. (Beta API.) |
+| `gemini_interact(input, previous_interaction_id?, continue_last?, images?, images_base64?, video_url?, video_path?, google_search?, search_types?, model?, aspect_ratio?, image_size?, thinking_level?, filename?, output_dir?, inline?)` | **Preferred tool for iterative refinement.** Generate/edit via Gemini's **Interactions API**. Returns an `interaction_id`; pass it back as `previous_interaction_id` (or set `continue_last: true` to reuse the session's most recent one) to **iteratively refine the same image** conversationally — do NOT start a new interaction or re-upload the image per tweak. Output is **JPEG**. |
 
 ## Workflows
 
@@ -148,8 +156,10 @@ r1 = gemini_interact(input: "a cozy reading nook, watercolor")
 r2 = gemini_interact(input: "add a sleeping cat on the chair",
                      previous_interaction_id: r1.interaction_id)
    → refined image that preserves r1; returns a NEW interaction_id
+r3 = gemini_interact(input: "warmer lighting", continue_last: true)
+   → same chain, without threading the id (uses the session's most recent interaction)
 ```
-Prefer this over re-running `gemini_edit_image` when you're making a *series* of incremental edits — the model keeps the prior result in context.
+Prefer this over re-running `gemini_edit_image` when you're making a *series* of incremental edits — the model keeps the prior result in context. Every result echoes `interaction_id` (and `previous_interaction_id` when chaining) plus a `hint` with the exact follow-up call.
 **⚠️ Chat-pasted/attached images can't be fed to these tools directly.** A pasted
 image reaches the assistant as a *vision* block — the assistant can SEE it but
 never receives the original bytes, and the host doesn't write it to disk. So
@@ -170,6 +180,36 @@ extraction:
 - **`GEMINI_INPUT_DIR`** — point it at a folder (e.g. Cowork's `uploads/`); then a
   **bare filename** resolves against it: `gemini_edit_image(prompt: "…", images: ["house.jpg"])`.
 
+## Prompting playbook
+
+Condensed from Google's official Nano Banana prompting guide. Core rule:
+**describe the scene, don't list keywords** — narrative sentences beat tag soups.
+
+**Best practices:**
+- **Be hyper-specific.** "Ornate elven plate armor, etched with silver leaf patterns" beats "fantasy armor".
+- **Give context & intent.** "Create a logo for a high-end minimalist skincare brand" beats "create a logo".
+- **Iterate conversationally** (`gemini_interact`): "warmer lighting", "same, but more serious expression".
+- **Step-by-step for complex scenes.** "First, a misty forest background. Then a stone altar in the foreground. Finally a glowing sword on the altar."
+- **Semantic negatives.** Describe what you want positively — "an empty, deserted street" — instead of "no cars".
+- **Camera language controls composition.** Wide-angle / macro / low-angle perspective / 85mm portrait lens / three-point softbox lighting.
+
+**Generation templates (abbreviated):**
+- *Photorealistic:* `photorealistic [shot type] of [subject] in [setting], [lighting], shot from [angle] with [lens]`
+- *Sticker/illustration:* `[style] sticker of [subject] doing [activity], bold outlines, cel-shading, [palette], white background`
+- *Text in image:* `create a [type] for [brand] with the text "[exact text]" in a [font style]` — Gemini renders text well; Pro is best for professional assets. Tip: generate the wording first, then ask for the image containing it.
+- *Product shot:* `high-resolution studio-lit photo of [product] on [surface], [lighting setup], [angle], sharp focus on [detail]`
+- *Minimalist/negative space:* `single [subject] in [frame position], vast empty [color] background` — for text-overlay backgrounds.
+- *Comic/storyboard:* `make a 3 panel comic in [style]; put the character in [scene]` (Pro or 3.1 Flash).
+
+**Editing templates (abbreviated):**
+- *Add/remove:* `using the provided image of [subject], [add/remove] [element]; match the original style/lighting/perspective`
+- *Inpaint (semantic mask):* `change only the [element] to [new element]; keep everything else exactly the same`
+- *Style transfer:* `transform the photo of [subject] into the style of [artist/style]; preserve composition`
+- *Compose:* `take the [element from image 1] and place it with [element from image 2]; adjust lighting/shadows to match`
+- *Detail preservation:* describe the critical element (face, logo) in detail and say it must "remain completely unchanged"
+- *Sketch → finished:* `turn this rough sketch of [subject] into a [style] photo; keep [features], add [details]`
+- *Character 360°:* iterate angles via `gemini_interact` ("in profile looking right"), feeding prior outputs back for consistency
+
 ## Notes
 
 - **Input images** accept either file **paths** (`images` / `master_images`) or **base64/data-URI values** (`images_base64` / `master_images_base64`).
@@ -178,12 +218,15 @@ extraction:
 - **No edit-strength control.** Gemini exposes no denoise/strength knob, and Nano Banana over-preserves the input — big structural edits ("move/remove/shrink", add a mat border) are often ignored. Workarounds: reroll with a different `seed`, raise `thinking_level` to `high`, use forceful wording, do layout changes (padding/borders) externally, or use `gemini_interact` multi-turn.
 - **`thinking_level`** (`minimal`/`high`, Gemini 3 models) controls reasoning depth — `high` can improve complex compositions/edits at higher latency/cost.
 - **Model text.** When the model returns a caption/explanation (mostly Gemini 3 **Pro**), it's surfaced as `text` in the result metadata.
-- **`google_search: true`** grounds the image in live Google Search (current events, weather, real data — great for infographics). The result metadata includes `grounding` with the `queries` run and the `sources` (`{uri, title}`) used. (`gemini_interact` surfaces `grounding.queries` only — the Interactions API returns no clean source list.)
+- **`google_search: true`** grounds the image in live Google Search (current events, weather, real data — great for infographics). The result metadata includes `grounding` with the `queries` run and the `sources` (`{uri, title}`) used. (`gemini_interact` surfaces `grounding.queries` — the Interactions API returns no clean source list.)
+- **`search_types`** (`gemini_interact` only): `["web_search", "image_search"]` picks the grounding search types (setting it implies `google_search`). **`image_search`** (gemini-3.1-flash-image only) pulls web images via Google Image Search as *visual* references — useful for real-world subjects (a specific butterfly species, a landmark, a product). ⚠️ Two catches: Google ToS require **displaying the returned `grounding.search_suggestions` HTML chips** to the user, and image_search won't depict real people from web images.
 - **`video_url`** (a public YouTube URL, on `gemini_generate_image` / `gemini_interact`) generates an image from a video reference — **requires a Flash model** (e.g. `model: "gemini-3.1-flash-image"`). For a **local video file**, use **`video_path`** instead: the file is uploaded to the Gemini Files API (streamed from disk, 2 GB max), waited to `ACTIVE`, and referenced by its `files/…` uri. The result metadata echoes `video_file` (`{uri, name, expires}`, ~48h retention) — reuse that uri as `video_url` in later calls to skip re-uploading.
-- **`gemini_interact`** is the multi-turn path: it returns an `interaction_id`; thread it back via `previous_interaction_id` for conversational refinement. Output is **JPEG only**. It's a **Beta** API (separate from the stable `generate`/`edit`/`set` tools).
+- **`gemini_interact`** is the multi-turn path: it returns an `interaction_id`; thread it back via `previous_interaction_id` for conversational refinement. Output is **JPEG only**. (The Interactions API is GA as of 2026-07; it uses a different request shape than the `generate`/`edit`/`set` tools.)
 - `output_dir` per-call overrides `$GEMINI_OUTPUT_DIR` overrides cwd. `inline: true` returns bytes (with a metadata text block) instead of writing.
 - `count` and `scenes` are mutually exclusive in `gemini_generate_set`; `reference_mode: "chain"` references the previous image instead of the master.
 - Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`, … · Image sizes: `512` (0.5K, Flash only), `1K`, `2K`, `4K`. `4K` is the max native output — true 18×24 in @ 300 DPI (5400×7200) needs an external upscale step.
 - All generated images carry a **SynthID** watermark (Google).
 - The model can mis-render text/Roman numerals (e.g. years) — verify any text in the output; it's a model limitation, not a tool setting.
+- **Best-performance languages:** EN, plus ar, de, es-MX, fr, hi, id, it, ja, ko, pt-BR, ru, ua, vi, zh-CN — prefer prompting in one of these.
+- Asking the *model* for "N images" in one prompt is unreliable (documented limitation) — use the `count` parameter instead; it makes N independent calls with distinct seeds.
 - Server logs to stderr only — stdout is reserved for JSON-RPC.

package/dist/bundle.js

@@ -32510,7 +32510,7 @@ var init_clipboard = __esm({
 init_dist();
 
 // src/version.ts
-var VERSION = "0.6.1";
+var VERSION = "0.7.1";
 
 // src/tools/models.ts
 init_dist();
@@ -32521,7 +32521,7 @@ import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/models.ts
-var DEFAULT_IMAGE_MODEL = "gemini-3-pro-image";
+var DEFAULT_IMAGE_MODEL = "gemini-3.1-flash-image";
 function resolveModel(perCall, envOverride) {
   return perCall?.trim() || envOverride?.trim() || DEFAULT_IMAGE_MODEL;
 }
@@ -32539,12 +32539,13 @@ await loadDotenvSafely({ path: join(__dirname, "..", ".env"), override: false })
 var BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
 var SERVICE = "Gemini";
 var INTERACTIONS_SERVICE = "Gemini Interactions";
-var API_REVISION = "2026-05-20";
 var REQUEST_TIMEOUT_MS = 6e4;
 var UPLOAD_BASE_URL = "https://generativelanguage.googleapis.com/upload/v1beta";
 var FILE_MAX_BYTES = 2 * 1024 ** 3;
 var FILE_POLL_INTERVAL_MS = 2e3;
 var FILE_POLL_MAX_ATTEMPTS = 150;
+var CHAIN_404_RETRIES = 2;
+var CHAIN_404_RETRY_MS = 2e3;
 var GeminiClient = class {
   apiKey;
   configError;
@@ -32575,7 +32576,6 @@ var GeminiClient = class {
     this.interactionsApi = createApiClient({
       baseUrl: BASE_URL,
       serviceName: INTERACTIONS_SERVICE,
-      baseHeaders: { "Api-Revision": API_REVISION },
       ...shared
     });
   }
@@ -32753,18 +32753,48 @@ var GeminiClient = class {
     const body = { model, input: inputParts, response_format: responseFormat };
     if (opts.thinkingLevel !== void 0) body.generation_config = { thinking_level: opts.thinkingLevel };
     if (opts.previousInteractionId !== void 0) body.previous_interaction_id = opts.previousInteractionId;
-    if (opts.googleSearch) body.tools = [{ type: "google_search" }];
-    const data = await this.interactionsApi.fetchJson("POST", "/interactions", {
-      body
-    });
+    if (opts.googleSearch || opts.searchTypes?.length) {
+      const searchTool = { type: "google_search" };
+      if (opts.searchTypes?.length) searchTool.search_types = opts.searchTypes;
+      body.tools = [searchTool];
+    }
+    let data;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        data = await this.interactionsApi.fetchJson("POST", "/interactions", {
+          body
+        });
+        break;
+      } catch (err) {
+        if (!(opts.previousInteractionId && err instanceof ApiError && err.status === 404)) throw err;
+        if (attempt < CHAIN_404_RETRIES) {
+          await this.sleep(CHAIN_404_RETRY_MS * (attempt + 1));
+          continue;
+        }
+        throw new McpToolError(
+          `Previous interaction "${opts.previousInteractionId}" was not found (retried ${CHAIN_404_RETRIES}\xD7 \u2014 the interactions store can lag briefly after a turn completes). If the id is old: interactions are retained 55 days on the paid tier (1 day on the free tier) and are scoped to the API key that created them.`,
+          {
+            hint: "Retry once more in a few seconds; if it keeps failing, start a new chain: call gemini_interact again with the last output image passed via `images` (or `images_base64`) plus the same instruction, then chain the NEW interaction id.",
+            cause: err
+          }
+        );
+      }
+    }
     const images = [];
     const textParts = [];
     const searchQueries = [];
+    const searchSuggestions = /* @__PURE__ */ new Set();
     for (const step of data.steps ?? []) {
       if (step.type === "google_search_call") {
         for (const q of step.arguments?.queries ?? []) if (q?.trim()) searchQueries.push(q);
         continue;
       }
+      if (step.type === "google_search_result") {
+        if (opts.searchTypes?.includes("image_search")) {
+          for (const r of step.result ?? []) if (r.search_suggestions?.trim()) searchSuggestions.add(r.search_suggestions);
+        }
+        continue;
+      }
       if (step.type !== "model_output") continue;
       for (const parts of [step.content ?? [], step.summary ?? []]) {
         for (const part of parts) {
@@ -32782,7 +32812,12 @@ var GeminiClient = class {
       });
     }
     const resultText = textParts.join("\n") || void 0;
-    const grounding = searchQueries.length > 0 ? { queries: searchQueries } : void 0;
+    let grounding;
+    if (searchQueries.length > 0 || searchSuggestions.size > 0) {
+      grounding = {};
+      if (searchQueries.length > 0) grounding.queries = searchQueries;
+      if (searchSuggestions.size > 0) grounding.search_suggestions = [...searchSuggestions];
+    }
     return { id: data.id, images, text: resultText, grounding };
   }
 };
@@ -32938,11 +32973,12 @@ init_zod();
 init_dist();
 var 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"];
 var IMAGE_SIZES = ["512", "1K", "2K", "4K"];
+var MODEL_CHOICE_GUIDE = "gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse \u2014 balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks \u2014 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).";
 var sharedImageSchema = {
   // Bare id only: the model is interpolated into the URL path
   // (`/models/${model}:generateContent`), so slashes/colons/queries must be
   // rejected to keep a crafted value from escaping the path segment.
-  model: external_exports.string().regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")').optional().describe("Model id override (default: server default; see gemini_list_models)"),
+  model: external_exports.string().regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")').optional().describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
   aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Output aspect ratio"),
   image_size: external_exports.enum(IMAGE_SIZES).optional().describe("Output resolution (512 = 0.5K, Flash-only)"),
   output_dir: external_exports.string().optional().describe("Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"),
@@ -32992,11 +33028,12 @@ async function emit(named, opts, meta3) {
 }
 
 // src/tools/generate.ts
+var REFINE_HINT = "To iteratively refine this image, use gemini_interact (pass the output file via `images` on the first call, then chain `previous_interaction_id` on each subsequent call).";
 function registerGenerateTools(server) {
   server.registerTool(
     "gemini_generate_image",
     {
-      description: "Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro).",
+      description: "Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro). If the result will likely be refined iteratively, prefer gemini_interact (multi-turn) as the entry point.",
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         prompt: external_exports.string().min(1).describe("Text prompt describing the image"),
@@ -33041,13 +33078,14 @@ function registerGenerateTools(server) {
       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(
     "gemini_edit_image",
     {
-      description: "Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. Gemini over-preserves the input; there is no edit-strength control \u2014 for large structural changes, reroll with a different `seed` or more forceful wording.",
+      description: "Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. For a SERIES of successive edits to the same image, prefer gemini_interact (multi-turn) \u2014 it keeps edit context and avoids re-processing the full image each round; use gemini_edit_image for one-off edits or composing multiple distinct inputs. Gemini over-preserves the input; there is no edit-strength control \u2014 for large structural changes, reroll with a different `seed` or more forceful wording.",
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         prompt: external_exports.string().min(1).describe("Instruction describing the edit or composition"),
@@ -33081,6 +33119,7 @@ function registerGenerateTools(server) {
       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);
     }
   );
@@ -33149,18 +33188,20 @@ function registerSetTools(server) {
 // src/tools/interact.ts
 init_zod();
 init_dist();
+var lastInteractionId;
 function registerInteractTools(server) {
   server.registerTool(
     "gemini_interact",
     {
-      description: "Multi-turn image generation/editing via Gemini's Interactions API (Beta). Returns an interaction `id`; pass it back as `previous_interaction_id` to iteratively refine the SAME image conversationally (the recommended way to make incremental edits). Output is JPEG.",
+      description: "Preferred tool for iterative or multi-step refinement of a single image \u2014 multi-turn generation/editing via Gemini's Interactions API. To refine, capture the returned interaction `id` and pass it as `previous_interaction_id` on the next call \u2014 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. Output is JPEG.",
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         input: external_exports.string().min(1).describe("Text prompt or editing instruction"),
         previous_interaction_id: external_exports.string().optional().describe("ID from a prior gemini_interact call \u2014 continues that multi-turn conversation"),
+        continue_last: external_exports.boolean().optional().describe("Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins)"),
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to reference input images"),
         images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs"),
-        model: external_exports.string().optional().describe("Model id override (default: server default; see gemini_list_models)"),
+        model: external_exports.string().optional().describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
         aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Output aspect ratio"),
         image_size: external_exports.enum(IMAGE_SIZES).optional().describe("Output resolution (512 = 0.5K, Flash-only)"),
         thinking_level: external_exports.enum(["minimal", "high"]).optional().describe("Reasoning depth; higher can help complex/structural edits"),
@@ -33168,12 +33209,24 @@ function registerInteractTools(server) {
         output_dir: external_exports.string().optional().describe("Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"),
         inline: external_exports.boolean().optional().describe("Return base64 images inline instead of writing to disk"),
         google_search: external_exports.boolean().optional().describe("Ground the image in live Google Search results (current events, weather, data)"),
+        search_types: external_exports.array(external_exports.enum(["web_search", "image_search"])).optional().describe(
+          "Grounding search types (implies google_search). image_search (gemini-3.1-flash-image only) uses Google Image Search results as visual references; per Google ToS the returned grounding.search_suggestions HTML must then be displayed to the user. Cannot depict real people from web images."
+        ),
         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,
         from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)")
       }
     },
     async (args) => {
+      let previousInteractionId = args.previous_interaction_id;
+      if (!previousInteractionId && args.continue_last) {
+        if (!lastInteractionId) {
+          throw new McpToolError("No previous interaction to continue in this session.", {
+            hint: "Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id."
+          });
+        }
+        previousInteractionId = lastInteractionId;
+      }
       const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
       const video = await resolveVideoInput(args);
       const r = await client.interact({
@@ -33183,13 +33236,17 @@ function registerInteractTools(server) {
         aspectRatio: args.aspect_ratio,
         imageSize: args.image_size,
         thinkingLevel: args.thinking_level,
-        previousInteractionId: args.previous_interaction_id,
+        previousInteractionId,
         googleSearch: args.google_search,
+        searchTypes: args.search_types,
         videoUrl: video.videoUrl,
         videoMimeType: video.videoMimeType
       });
+      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;
+      meta3.hint = `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true).`;
       if (r.text) meta3.text = r.text;
       if (r.grounding) meta3.grounding = r.grounding;
       if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;

package/dist/client.js

@@ -1,15 +1,12 @@
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadDotenvSafely, readEnvVar, McpToolError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, readEnvVar, McpToolError, ApiError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
 import { resolveModel, filterImageModels } from './models.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
 const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'; // v1 lacks gemini-3-pro-image; confirmed via Task 5
 const SERVICE = 'Gemini';
 const INTERACTIONS_SERVICE = 'Gemini Interactions';
-// Required revision header for the beta Interactions API (verified 2026-06-08;
-// see docs/GEMINI-API.md) — load-bearing, requests 400 without it.
-const API_REVISION = '2026-05-20';
 // 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).
 const REQUEST_TIMEOUT_MS = 60_000;
@@ -24,6 +21,13 @@ const FILE_MAX_BYTES = 2 * 1024 ** 3;
 // in ~1s (verified); longer videos take proportionally longer to process.
 const FILE_POLL_INTERVAL_MS = 2_000;
 const FILE_POLL_MAX_ATTEMPTS = 150;
+// The interactions store is eventually consistent: a freshly returned id can
+// 404 for a short window right after its turn completes (observed live
+// 2026-07-06 — an id that 404'd on an immediate chain resolved fine minutes
+// later). A chained 404 generated nothing (no cost), so retry before giving up:
+// attempts wait 2s then 4s (~6s total).
+const CHAIN_404_RETRIES = 2;
+const CHAIN_404_RETRY_MS = 2_000;
 export class GeminiClient {
     apiKey;
     configError;
@@ -58,12 +62,13 @@ export class GeminiClient {
             fetchImpl: this.fetchImpl,
         };
         this.api = createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared });
-        // Separate client for the beta Interactions API: same base URL, but every
-        // request must carry the Api-Revision header (and errors name the API).
+        // 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,
-            baseHeaders: { 'Api-Revision': API_REVISION },
             ...shared,
         });
     }
@@ -252,11 +257,39 @@ export class GeminiClient {
             body.generation_config = { thinking_level: opts.thinkingLevel };
         if (opts.previousInteractionId !== undefined)
             body.previous_interaction_id = opts.previousInteractionId;
-        if (opts.googleSearch)
-            body.tools = [{ type: 'google_search' }];
-        const data = await this.interactionsApi.fetchJson('POST', '/interactions', {
-            body,
-        });
+        if (opts.googleSearch || opts.searchTypes?.length) {
+            const searchTool = { type: 'google_search' };
+            if (opts.searchTypes?.length)
+                searchTool.search_types = opts.searchTypes;
+            body.tools = [searchTool];
+        }
+        let data;
+        for (let attempt = 0;; attempt++) {
+            try {
+                data = await this.interactionsApi.fetchJson('POST', '/interactions', {
+                    body,
+                });
+                break;
+            }
+            catch (err) {
+                // A 404 on a chained call means the referenced interaction wasn't
+                // found. Two causes: (a) store lag right after the id was created —
+                // retry with backoff; (b) genuinely gone — interactions are retained
+                // 55 days (paid tier) / 1 day (free tier) and are scoped to the API
+                // key's project. The chain is recoverable from the last output file,
+                // so the exhausted-retries error says how.
+                if (!(opts.previousInteractionId && err instanceof ApiError && err.status === 404))
+                    throw err;
+                if (attempt < CHAIN_404_RETRIES) {
+                    await this.sleep(CHAIN_404_RETRY_MS * (attempt + 1));
+                    continue;
+                }
+                throw new McpToolError(`Previous interaction "${opts.previousInteractionId}" was not found (retried ${CHAIN_404_RETRIES}× — the interactions store can lag briefly after a turn completes). If the id is old: interactions are retained 55 days on the paid tier (1 day on the free tier) and are scoped to the API key that created them.`, {
+                    hint: 'Retry once more in a few seconds; if it keeps failing, start a new chain: call gemini_interact again with the last output image passed via `images` (or `images_base64`) plus the same instruction, then chain the NEW interaction id.',
+                    cause: err,
+                });
+            }
+        }
         // Only surface the `model_output` step — that's the caller-facing result.
         // `thought` steps hold internal reasoning (and, with includeThoughts, draft
         // "thinking" images); collecting those would leak reasoning into `text` and
@@ -265,17 +298,31 @@ export class GeminiClient {
         const images = [];
         const textParts = [];
         const searchQueries = [];
+        const searchSuggestions = new Set();
         for (const step of data.steps ?? []) {
             // Grounding queries live on the `google_search_call` step's arguments.
             // (The `google_search_result` step only carries HTML `search_suggestions`
             // chips — no clean source uri/title list like generateContent's
-            // groundingChunks — so interact surfaces queries only, not sources.)
+            // groundingChunks — so interact surfaces queries, plus the suggestion
+            // chips when image_search was requested, ToS below.)
             if (step.type === 'google_search_call') {
                 for (const q of step.arguments?.queries ?? [])
                     if (q?.trim())
                         searchQueries.push(q);
                 continue;
             }
+            // ToS: image_search results' `search_suggestions` chips MUST be displayed
+            // by the caller, so surface them (deduped — the chips repeat) only when
+            // image_search grounding was requested; web-only grounding keeps the
+            // lean queries-only meta.
+            if (step.type === 'google_search_result') {
+                if (opts.searchTypes?.includes('image_search')) {
+                    for (const r of step.result ?? [])
+                        if (r.search_suggestions?.trim())
+                            searchSuggestions.add(r.search_suggestions);
+                }
+                continue;
+            }
             if (step.type !== 'model_output')
                 continue;
             for (const parts of [step.content ?? [], step.summary ?? []]) {
@@ -295,7 +342,14 @@ export class GeminiClient {
             });
         }
         const resultText = textParts.join('\n') || undefined;
-        const grounding = searchQueries.length > 0 ? { queries: searchQueries } : undefined;
+        let grounding;
+        if (searchQueries.length > 0 || searchSuggestions.size > 0) {
+            grounding = {};
+            if (searchQueries.length > 0)
+                grounding.queries = searchQueries;
+            if (searchSuggestions.size > 0)
+                grounding.search_suggestions = [...searchSuggestions];
+        }
         return { id: data.id, images, text: resultText, grounding };
     }
 }

package/dist/models.js

@@ -1,5 +1,10 @@
-/** Latest top-end image model; overridable per-call and via GEMINI_IMAGE_MODEL. */
-export const DEFAULT_IMAGE_MODEL = 'gemini-3-pro-image';
+/**
+ * The generalist workhorse (Nano Banana 2) — overridable per-call and via
+ * GEMINI_IMAGE_MODEL. The premium gemini-3-pro-image is a deliberate opt-in:
+ * it costs more and needs a funded account, so callers reach for it via the
+ * `model` param when the task warrants it (see MODEL_CHOICE_GUIDE).
+ */
+export const DEFAULT_IMAGE_MODEL = 'gemini-3.1-flash-image';
 /** Per-call → env override → hardcoded default. Blank/whitespace counts as unset. */
 export function resolveModel(perCall, envOverride) {
     return perCall?.trim() || envOverride?.trim() || DEFAULT_IMAGE_MODEL;

package/dist/tools/generate.js

@@ -4,9 +4,14 @@ 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';
+// 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, ' +
+    'then chain `previous_interaction_id` on each subsequent call).';
 export function registerGenerateTools(server) {
     server.registerTool('gemini_generate_image', {
-        description: 'Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro).',
+        description: 'Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro). ' +
+            'If the result will likely be refined iteratively, prefer gemini_interact (multi-turn) as the entry point.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             prompt: z.string().min(1).describe('Text prompt describing the image'),
@@ -61,10 +66,13 @@ export function registerGenerateTools(server) {
             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. ' +
+            'For a SERIES of successive edits to the same image, prefer gemini_interact (multi-turn) — it keeps edit context ' +
+            'and avoids re-processing the full image each round; use gemini_edit_image for one-off edits or composing multiple distinct inputs. ' +
             'Gemini over-preserves the input; there is no edit-strength control — for large structural changes, reroll with a different `seed` or more forceful wording.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
@@ -100,6 +108,7 @@ export function registerGenerateTools(server) {
             meta.text = text;
         if (result.grounding)
             meta.grounding = result.grounding;
+        meta.hint = REFINE_HINT;
         return emit([{ image: img, base: slug }], args, meta);
     });
 }

package/dist/tools/interact.js

@@ -1,14 +1,20 @@
 import { z } from 'zod';
-import { readEnvVar } from '@chrischall/mcp-utils';
+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, ASPECT_RATIOS, IMAGE_SIZES, resolveVideoInput, videoPathSchema } from './shared.js';
+import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema } from './shared.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".
+let lastInteractionId;
 export function registerInteractTools(server) {
     server.registerTool('gemini_interact', {
-        description: "Multi-turn image generation/editing via Gemini's Interactions API (Beta). " +
-            'Returns an interaction `id`; pass it back as `previous_interaction_id` to iteratively ' +
-            'refine the SAME image conversationally (the recommended way to make incremental edits). ' +
+        description: 'Preferred tool for iterative or multi-step refinement of a single image — ' +
+            "multi-turn generation/editing via Gemini's Interactions API. " +
+            '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. ' +
             'Output is JPEG.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
@@ -17,6 +23,10 @@ export function registerInteractTools(server) {
                 .string()
                 .optional()
                 .describe('ID from a prior gemini_interact call — continues that multi-turn conversation'),
+            continue_last: z
+                .boolean()
+                .optional()
+                .describe('Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins)'),
             images: z
                 .array(z.string().min(1))
                 .optional()
@@ -28,7 +38,7 @@ export function registerInteractTools(server) {
             model: z
                 .string()
                 .optional()
-                .describe('Model id override (default: server default; see gemini_list_models)'),
+                .describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
             aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
             image_size: z
                 .enum(IMAGE_SIZES)
@@ -54,6 +64,11 @@ export function registerInteractTools(server) {
                 .boolean()
                 .optional()
                 .describe('Ground the image in live Google Search results (current events, weather, data)'),
+            search_types: z
+                .array(z.enum(['web_search', 'image_search']))
+                .optional()
+                .describe('Grounding search types (implies google_search). image_search (gemini-3.1-flash-image only) uses Google Image Search results as visual references; ' +
+                'per Google ToS the returned grounding.search_suggestions HTML must then be displayed to the user. Cannot depict real people from web images.'),
             video_url: z
                 .string()
                 .url()
@@ -66,6 +81,15 @@ export function registerInteractTools(server) {
                 .describe('Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)'),
         },
     }, async (args) => {
+        let previousInteractionId = args.previous_interaction_id;
+        if (!previousInteractionId && args.continue_last) {
+            if (!lastInteractionId) {
+                throw new McpToolError('No previous interaction to continue in this session.', {
+                    hint: 'Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id.',
+                });
+            }
+            previousInteractionId = lastInteractionId;
+        }
         const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
         const video = await resolveVideoInput(args);
         const r = await client.interact({
@@ -75,13 +99,18 @@ export function registerInteractTools(server) {
             aspectRatio: args.aspect_ratio,
             imageSize: args.image_size,
             thinkingLevel: args.thinking_level,
-            previousInteractionId: args.previous_interaction_id,
+            previousInteractionId,
             googleSearch: args.google_search,
+            searchTypes: args.search_types,
             videoUrl: video.videoUrl,
             videoMimeType: video.videoMimeType,
         });
+        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;
+        meta.hint = `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true).`;
         if (r.text)
             meta.text = r.text;
         if (r.grounding)

package/dist/tools/shared.js

@@ -11,6 +11,15 @@ export const IMAGE_SIZES = ['512', '1K', '2K', '4K'];
  * 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.
+ */
+export const MODEL_CHOICE_GUIDE = 'gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with ' +
+    'state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image ' +
+    '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).';
 export const sharedImageSchema = {
     // Bare id only: the model is interpolated into the URL path
     // (`/models/${model}:generateContent`), so slashes/colons/queries must be
@@ -19,7 +28,7 @@ export const sharedImageSchema = {
         .string()
         .regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")')
         .optional()
-        .describe('Model id override (default: server default; see gemini_list_models)'),
+        .describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
     aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
     image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution (512 = 0.5K, Flash-only)'),
     output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "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.6.1",
+  "version": "0.7.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "0.6.1",
+      "version": "0.7.1",
       "transport": {
         "type": "stdio"
       },
@@ -25,7 +25,7 @@
         },
         {
           "name": "GEMINI_IMAGE_MODEL",
-          "description": "Override the default image model (default: gemini-3-pro-image)",
+          "description": "Override the default image model (default: gemini-3.1-flash-image)",
           "isRequired": false,
           "format": "string",
           "isSecret": false