@chrischall/gemini-mcp 0.6.0 → 0.7.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.6.0"
+    "version": "0.7.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.6.0",
+      "version": "0.7.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

@@ -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

@@ -5,11 +5,20 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -32375,6 +32384,12 @@ var init_http = __esm({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/concurrency/index.js
+var init_concurrency = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/concurrency/index.js"() {
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/dates/index.js
 var init_dates = __esm({
   "node_modules/@chrischall/mcp-utils/dist/dates/index.js"() {
@@ -32382,7 +32397,7 @@ var init_dates = __esm({
 });
 
 // node_modules/@chrischall/mcp-utils/dist/zod/index.js
-var PositiveInt, NonNegInt, NonEmptyString, IsoDate, IsoTime, schemaOrigin, schemaConfirm, paginationSchema, pageSchema;
+var PositiveInt, NonNegInt, NonEmptyString, IsoDate, IsoTime, NumericIdString, SafePathSegment, schemaOrigin, schemaConfirm, paginationSchema, pageSchema;
 var init_zod2 = __esm({
   "node_modules/@chrischall/mcp-utils/dist/zod/index.js"() {
     init_zod();
@@ -32391,6 +32406,8 @@ var init_zod2 = __esm({
     NonEmptyString = external_exports.string().min(1);
     IsoDate = external_exports.iso.date();
     IsoTime = external_exports.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, "must be HH:MM (24h), e.g. 19:30");
+    NumericIdString = external_exports.string().regex(/^\d+$/, "must be a numeric id (digits only)").describe("A numeric id string (digits only), safe to interpolate into a URL path.");
+    SafePathSegment = external_exports.string().min(1).regex(/^[^/?#\s]+$/, 'must not contain "/", "?", "#", or whitespace').refine((v) => !v.includes(".."), 'must not contain ".."').describe('A single URL path segment, safe to interpolate: no "/", "..", "?", "#", or whitespace.');
     schemaOrigin = external_exports.string().optional().describe("Portal origin (e.g. https://<vendor>.example.co) selecting which active session to use. Optional when only one session is active.");
     schemaConfirm = external_exports.boolean().optional().describe("Must be true to proceed. Without this, the tool returns a preview.");
     paginationSchema = {
@@ -32422,6 +32439,7 @@ var init_dist = __esm({
     init_config();
     init_fs();
     init_http();
+    init_concurrency();
     init_dates();
     init_zod2();
     init_auth();
@@ -32492,7 +32510,7 @@ var init_clipboard = __esm({
 init_dist();
 
 // src/version.ts
-var VERSION = "0.6.0";
+var VERSION = "0.7.0";
 
 // src/tools/models.ts
 init_dist();
@@ -32503,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;
 }
@@ -32521,7 +32539,6 @@ 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;
@@ -32557,7 +32574,6 @@ var GeminiClient = class {
     this.interactionsApi = createApiClient({
       baseUrl: BASE_URL,
       serviceName: INTERACTIONS_SERVICE,
-      baseHeaders: { "Api-Revision": API_REVISION },
       ...shared
     });
   }
@@ -32735,18 +32751,29 @@ 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" }];
+    if (opts.googleSearch || opts.searchTypes?.length) {
+      const searchTool = { type: "google_search" };
+      if (opts.searchTypes?.length) searchTool.search_types = opts.searchTypes;
+      body.tools = [searchTool];
+    }
     const data = await this.interactionsApi.fetchJson("POST", "/interactions", {
       body
     });
     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) {
@@ -32764,7 +32791,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 };
   }
 };
@@ -32920,11 +32952,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)"),
@@ -32974,11 +33007,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"),
@@ -33023,13 +33057,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"),
@@ -33063,6 +33098,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);
     }
   );
@@ -33131,18 +33167,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"),
@@ -33150,12 +33188,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({
@@ -33165,13 +33215,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

@@ -7,9 +7,6 @@ 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;
@@ -58,12 +55,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,8 +250,12 @@ 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' }];
+        if (opts.googleSearch || opts.searchTypes?.length) {
+            const searchTool = { type: 'google_search' };
+            if (opts.searchTypes?.length)
+                searchTool.search_types = opts.searchTypes;
+            body.tools = [searchTool];
+        }
         const data = await this.interactionsApi.fetchJson('POST', '/interactions', {
             body,
         });
@@ -265,17 +267,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 +311,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.0'; // x-release-please-version
+export const VERSION = '0.7.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "0.6.0",
+  "version": "0.7.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,13 +44,13 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.7.0",
+    "@chrischall/mcp-utils": "^0.10.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {
-    "@types/node": "^25.5.2",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.2",
     "esbuild": "^0.28.0",
     "typescript": "^6.0.2",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "0.6.0",
+  "version": "0.7.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "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