@chrischall/gemini-mcp 0.2.0 → 0.3.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.2.0"
+    "version": "0.3.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.2.0",
+      "version": "0.3.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

@@ -20,6 +20,7 @@ Developed and maintained by AI (Claude Code).
 | `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_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 |
 
 ## Quick Start
 

package/SKILL.md

@@ -82,9 +82,14 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 ### Image Generation
 | Tool | Description |
 |------|-------------|
-| `gemini_generate_image(prompt, count?, model?, aspect_ratio?, image_size?, output_dir?, inline?)` | Generate image(s) from a text prompt |
-| `gemini_edit_image(prompt, images[], model?, aspect_ratio?, image_size?, output_dir?, inline?)` | Edit or compose one or more input images with a text instruction |
-| `gemini_generate_set(master_prompt, scenes? \| count?, reference_mode?, model?, ...)` | Generate a master image plus N consistent images referencing it |
+| `gemini_generate_image(prompt, count?, images?, images_base64?, video_url?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Generate image(s) from a text prompt (optionally image-conditioned via `images`/`images_base64`, or video-conditioned via `video_url`) |
+| `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)
+| Tool | Description |
+|------|-------------|
+| `gemini_interact(input, previous_interaction_id?, images?, images_base64?, video_url?, 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.) |
 
 ## Workflows
 
@@ -124,12 +129,40 @@ gemini_generate_set(
 → returns master + 5 variations
 ```
 
+**Use a reference photo by value (no file needed):**
+```
+gemini_edit_image(
+  prompt: "place this house on a vintage travel-poster background",
+  images_base64: ["data:image/jpeg;base64,/9j/4AAQ..."]   // or raw base64
+)
+→ returns path to the edited image
+```
+
+**Iterate on ONE image conversationally (multi-turn):**
+```
+r1 = gemini_interact(input: "a cozy reading nook, watercolor")
+   → { images: [...], interaction_id: "v1_abc…" }
+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
+```
+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.
+Pasted/attached images aren't written to disk by the host, so pass their bytes via `images_base64` (a `data:` URI or raw base64) instead of a path.
+
 ## Notes
 
-- `output_dir` per-call overrides `$GEMINI_OUTPUT_DIR` which overrides the current working directory
-- `inline: true` returns image bytes directly in the response instead of writing to disk
-- `count` and `scenes` are mutually exclusive in `gemini_generate_set`
-- `reference_mode: "chain"` makes each scene reference the previous image (vs. all referencing master)
-- Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`, and others
-- Image sizes: `1K`, `2K`, `4K`
-- Server logs to stderr only — stdout is reserved for JSON-RPC
+- **Input images** accept either file **paths** (`images` / `master_images`) or **base64/data-URI values** (`images_base64` / `master_images_base64`).
+- **`seed`** makes a result reproducible; it's echoed in the result metadata (a random one is chosen + echoed when omitted). `count>1` uses `seed, seed+1, …` so the images differ. Determinism isn't fully guaranteed by the model.
+- **`filename`/`basename`** set the output name (extension stripped); names never overwrite (a `-2`, `-3` suffix is added). The result echoes the absolute path(s), `model`, `seed`, and aspect/size.
+- **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.)
+- **`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"`). Non-YouTube video (Files API upload) is not supported.
+- **`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).
+- `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.
+- Server logs to stderr only — stdout is reserved for JSON-RPC.