@chrischall/gemini-mcp 0.2.0 → 0.4.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.4.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.4.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.4.0",
   "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
   "author": {
     "name": "Chris Hall",

package/.mcp.json

@@ -6,7 +6,8 @@
       "env": {
         "GEMINI_API_KEY": "${GEMINI_API_KEY}",
         "GEMINI_IMAGE_MODEL": "${GEMINI_IMAGE_MODEL}",
-        "GEMINI_OUTPUT_DIR": "${GEMINI_OUTPUT_DIR}"
+        "GEMINI_OUTPUT_DIR": "${GEMINI_OUTPUT_DIR}",
+        "GEMINI_INPUT_DIR": "${GEMINI_INPUT_DIR}"
       }
     }
   }

package/README.md

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

@@ -71,6 +71,7 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 | `GEMINI_API_KEY` | Yes | Your Google Gemini API key |
 | `GEMINI_IMAGE_MODEL` | No | Override the default image model (default: `gemini-3-pro-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) |
 
 ## Tools
 
@@ -82,9 +83,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 +130,60 @@ gemini_generate_set(
 → returns master + 5 variations
 ```
 
+**Use a reference photo by value (when you have the bytes):**
+```
+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
+```
+`images_base64` is for bytes you actually have — a file you `Read`/encode, a URL
+you fetch, or a `data:` URI the user pastes as **text**.
+
+**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.
+**⚠️ 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
+neither `images` (no file exists) nor `images_base64` (the bytes can't be
+reconstructed from a downscaled vision rendering) is obtainable from a paste.
+To use a real reference photo, the **user** must make the bytes available: save
+the file and give its **path** (→ `images`), drop it into the project dir, paste
+it as a **`data:` URI in text**, or host it at a **URL** (fetch → base64 →
+`images_base64`). This is a host/Cowork limitation, not an MCP one.
+
+Two built-in ways to get past the unreachable-paste problem without any manual
+extraction:
+- **`from_clipboard: true`** (macOS) — the tool reads the image off the system
+  clipboard itself (osascript), downscales it, and uses it. The user just needs
+  to **copy** the image (⌘C — distinct from pasting it inline into chat, which
+  doesn't keep it on the clipboard). Works on every image tool:
+  `gemini_edit_image(prompt: "…", from_clipboard: true)`.
+- **`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"])`.
+
 ## 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.