@chrischall/gemini-mcp 2.3.4 → 2.4.1

package/dist/tools/library.js

@@ -119,10 +119,10 @@ export function registerLibraryTools(server, client) {
             tool: 'gemini_delete_character',
             action: 'character.delete',
             message: 'Review and confirm this deletion:',
-            description: 'Delete a saved character (its reference image and description)',
-            method: 'DELETE',
-            path: `characters/${args.name}`,
+            summary: 'Delete a saved character (its reference image and description)',
+            account: undefined,
             target: args.name,
+            request: { method: 'DELETE', path: `characters/${args.name}` },
             payload: { name: args.name },
             args,
             confirmToken: args.confirmToken,
@@ -189,10 +189,10 @@ export function registerLibraryTools(server, client) {
             tool: 'gemini_delete_style',
             action: 'style.delete',
             message: 'Review and confirm this deletion:',
-            description: 'Delete a saved style preset',
-            method: 'DELETE',
-            path: `styles/${args.name}`,
+            summary: 'Delete a saved style preset',
+            account: undefined,
             target: args.name,
+            request: { method: 'DELETE', path: `styles/${args.name}` },
             payload: { name: args.name },
             args,
             confirmToken: args.confirmToken,

package/dist/tools/shared.js

@@ -14,7 +14,10 @@ import { buildZip } from '../zip.js';
 const DEFAULT_SINK = createDiskSink();
 /** Supported output aspect ratios (Gemini image API). */
 export const ASPECT_RATIOS = ['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9', '1:4', '4:1', '1:8', '8:1'];
-/** Supported output resolutions. `512` is Flash-only (0.5K); `1K`/`2K`/`4K` work on all image models. */
+/**
+ * Supported output resolutions. `512` (0.5K) is gemini-3.1-flash-image only — Nano Banana 2.1, the
+ * default, documents 1K/2K/4K — while `1K`/`2K`/`4K` work on all image models.
+ */
 export const IMAGE_SIZES = ['512', '1K', '2K', '4K'];
 /**
  * The words people actually use for shape, as a shorthand over
@@ -77,7 +80,7 @@ export const orientationSchema = z
  * 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, the default) is the generalist: fast, 4K, reliable text, strong ' +
+export const MODEL_CHOICE_GUIDE = 'gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong ' +
     'multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand ' +
     'precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding.';
 /**
@@ -299,7 +302,7 @@ export const sharedImageSchema = {
         .optional()
         .describe('Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.'),
     orientation: orientationSchema,
-    image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution (512 = 0.5K, Flash-only)'),
+    image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution (512 = 0.5K, gemini-3.1-flash-image only)'),
     output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)'),
     inline: z.boolean().optional().describe('Return the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have'),
     seed: z.number().int().optional().describe('Seed for reproducible generation; random if omitted'),
@@ -544,7 +547,7 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
     const unavailable = persisted.some((p) => p.unavailable)
         ? {
             media_url_unavailable: 'The media was stored but no public URL could be generated for it, so the values above are bare object keys, not links. ' +
-                'This is a connector misconfiguration: set MEDIA_PUBLIC_BASE_URL, or use inline: true to receive the bytes directly.',
+                'This is a hosting misconfiguration — the host did not provide a blob store (mcp-host injects MCP_BLOB_BASE_URL and MCP_BLOB_SIGNING_KEY) — so ask the server operator, or use inline: true to receive the bytes directly.',
         }
         : {};
     const detailed = persisted.filter((p) => p.key !== undefined);

package/dist/tools/uploads.js

@@ -86,7 +86,7 @@ export function registerUploadUrlTools(server, client) {
                 '(the signature in the URL is the auth, and it covers the content type). On a 2xx, reference the `r2_key` from ' +
                 'THIS result — not the PUT response: images_r2_keys on generation tools (master_images_r2_keys on ' +
                 'gemini_image_set), gemini_save_character to keep it with no expiry, or gemini_upload_file({ r2_key }) for a ' +
-                '~48h files/… reference. Uploads themselves follow the media retention schedule (default 7 days).',
+                '~48h files/… reference. Uploads themselves follow the host\'s blob-store retention schedule.',
         });
     });
 }

package/dist/version.js

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

package/mint.yaml

@@ -13,16 +13,28 @@ env:
   - name: GEMINI_IMAGE_MODEL
     required: false
     help: >-
-      Override the default image model (default: gemini-3.1-flash-image)
+      Override the default image model (default: gemini-nano-banana-2.1)
   - name: GEMINI_OUTPUT_DIR
     required: false
     help: >-
-      Default directory for generated images (default: current working
-      directory)
+      Default directory for generated images (default: ~/Downloads/gemini-mcp,
+      not the cwd). When set, a per-call output_dir must be inside it.
   - name: GEMINI_INPUT_DIR
     required: false
     help: >-
       Directory to resolve bare input-image filenames against
+  - name: GEMINI_UPLOAD_DIR
+    required: false
+    help: >-
+      Directories (path.delimiter-separated) that local files uploaded to the
+      Gemini Files API must come from. Mostly a local-install knob: on a hosted
+      server, uploads come from gemini_get_upload_url instead.
+  - name: GEMINI_REFERENCE_DIR
+    required: false
+    help: >-
+      Directories (path.delimiter-separated) that local reference images must
+      come from (else GEMINI_UPLOAD_DIR). Unset on a hosted server, only
+      $MCP_DATA_DIR/uploads is allowed, so leave it unset there.
   - name: GEMINI_TIMEOUT_MS
     required: false
     help: >-
@@ -38,6 +50,10 @@ env:
       How often, in milliseconds, to emit a progress notification while a
       generation is in flight. Hosts reset their tools/call timeout on progress,
       so this lets a long 4K/Pro generation outlive the default budget.
+  - name: GEMINI_DEBUG
+    required: false
+    help: >-
+      When set, emit heartbeat diagnostics to stderr. Off by default.
   - name: GEMINI_RATE_CARD
     required: false
     help: >-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "2.3.4",
+  "version": "2.4.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>",
@@ -38,7 +38,7 @@
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
-    "bundle": "esbuild src/index.ts --bundle --alias:zod/v4=./node_modules/zod/v4/index.cjs --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
+    "bundle": "esbuild src/index.ts --bundle --alias:zod/v4=./node_modules/zod/v4/index.cjs --platform=node --format=esm --external:dotenv --banner:js=\"import { createRequire as __createRequire } from 'module'; import { fileURLToPath as __fileURLToPath } from 'url'; import { dirname as __pathDirname } from 'path'; const require = __createRequire(import.meta.url); const __filename = __fileURLToPath(import.meta.url); const __dirname = __pathDirname(__filename);\" --outfile=dist/bundle.js",
     "dev": "node dist/index.js",
     "test": "npm run typecheck && vitest run",
     "test:watch": "vitest",
@@ -46,9 +46,10 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^3.0.0",
+    "@chrischall/mcp-utils": "^3.0.3",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.2",
+    "undici": "^8.12.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "2.3.4",
+  "version": "2.4.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "2.3.4",
+      "version": "2.4.1",
       "transport": {
         "type": "stdio"
       },
@@ -25,14 +25,14 @@
         },
         {
           "name": "GEMINI_IMAGE_MODEL",
-          "description": "Override the default image model (default: gemini-3.1-flash-image)",
+          "description": "Override the default image model (default: gemini-nano-banana-2.1)",
           "isRequired": false,
           "format": "string",
           "isSecret": false
         },
         {
           "name": "GEMINI_OUTPUT_DIR",
-          "description": "Default directory for generated images (default: current working directory)",
+          "description": "Default directory for generated images (default: ~/Downloads/gemini-mcp). When set, a per-call output_dir must be inside it.",
           "isRequired": false,
           "format": "string",
           "isSecret": false

package/skills/gemini-mcp/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.1-flash-image`) |
+| `GEMINI_IMAGE_MODEL` | No | Override the default image model (default: `gemini-nano-banana-2.1`) |
 | `GEMINI_OUTPUT_DIR` | No | Default directory for saved images (default: ~/Downloads/gemini-mcp) |
 | `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) |
 
@@ -84,7 +84,8 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 
 | 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-nano-banana-2.1` (Nano Banana 2.1, **default**) | The versatile generalist workhorse for all tasks — an update to Nano Banana 2 with better visual quality, prompt adherence, character consistency and text rendering; 1K/2K/4K, $0.0336 per 1K image | up to 10 objects + 4 characters |
+| `gemini-3.1-flash-image` (Nano Banana 2, **deprecated** 2026-10-06, no shutdown date yet) | The previous 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. 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) |
 
@@ -95,7 +96,7 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 | `gemini_image_edit(prompt, images_url?, images_file_uris?, images?, images_base64?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Edit or compose input image(s) with a text instruction. Requires ≥1 input from any of the four reference forms |
 | `gemini_image_set(master_prompt, scenes? \| count?, reference_mode?, master_images_url?, master_images_file_uris?, 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. `master_images_url` / `master_images_file_uris` are resolved **once** and passed to the master *and* every scene |
 
-### Reference images — four ways in, one that costs context
+### Reference images — several ways in, one that costs context
 
 These apply to **every** tool that takes a reference image: the four image tools, plus
 `gemini_video_generate` (reference stills) and `gemini_music_generate`.
@@ -104,7 +105,9 @@ These apply to **every** tool that takes a reference image: the four image tools
 |---|---|---|
 | `images_url` (`master_images_url`) | the **server** downloads the https URL | none |
 | `images_file_uris` (`master_images_file_uris`) | a `files/<id>` reference from `gemini_upload_file` | none |
+| `images_r2_keys` (`master_images_r2_keys`) | the server reads its **own store** — an `r2_key` from `gemini_get_upload_url` or a generation result (hosted deployments only) | none |
 | `images` | read off local disk (stdio builds only) | none |
+| `characters` / `style` | saved library entries, attached by name (hosted deployments only) | none |
 | `images_base64` | **through the tool-call JSON** | **~14k tokens per JPEG** |
 
 **Reach for `images_base64` last.** It costs ~14k tokens per modest photo, and a truncated file
@@ -129,17 +132,32 @@ not an error.
 | `gemini_list_files(page_size?)` | List current uploads with MIME types and expiry |
 | `gemini_delete_file(file_uri, confirmToken?)` | Delete an upload before its ~48h expiry (confirmed first — see Notes) |
 
-On the **hosted hosted deployment** there is also `POST /upload`, behind the same OAuth token as
-`/mcp` — the zero-base64 path for an agent with a shell:
+### Hosted deployment only
+
+A hosted deployment has no filesystem, so these tools stand in for it. There is no `POST /upload`
+endpoint (it went with the retired Worker connector): an agent with a shell uploads through a
+signed URL instead.
+
+| Tool | Description |
+|------|-------------|
+| `gemini_get_upload_url(filename, content_type)` | Mint a ~10-minute signed **PUT** URL. `curl -X PUT -H "Content-Type: <type>" --data-binary @file "<upload_url>"` needs no auth header. The result's `r2_key` goes to `images_r2_keys`, `gemini_save_character`, or `gemini_upload_file({ r2_key })` |
+| `gemini_sign_media(r2_key)` | Mint a fresh signed link for stored media (links live at most 24h) — an expired link is not a reason to re-generate |
+| `gemini_view_media(r2_key)` | Return a stored image inline so you can look at what was made before refining it |
+| `gemini_list_recent_media(limit?, since_day?)` | Recent stored media with prompt, model and interaction id — how a lost result or turn is found again |
+| `gemini_save_character` / `gemini_list_characters` / `gemini_delete_character` | Per-account character library (reference image + description, no expiry); attach with `characters: ["name"]` |
+| `gemini_save_style` / `gemini_list_styles` / `gemini_delete_style` | Per-account style presets (prompt fragment, optional reference image, no expiry); attach with `style: "name"` |
 
 ```bash
-curl -X POST https://<hosted deployment>/upload \
-  -H "Authorization: Bearer $ACCESS_TOKEN" \
-  -H "Content-Type: image/jpeg" \
-  --data-binary @photo.jpg
-# → {"file_uri":"files/abc123", ...}   then: images_file_uris: ["files/abc123"]
+# 1. tool: gemini_get_upload_url { filename: "photo.jpg", content_type: "image/jpeg" }
+#    → { upload_url, r2_key, expires_at, curl_hint }
+# 2. shell:
+curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "$UPLOAD_URL"
+# 3. tool: gemini_image_edit { prompt: "make it winter", images_r2_keys: ["<r2_key from step 1>"] }
 ```
 
+Uploads are raster images only, capped at 15MB, and follow the host's retention schedule; save
+anything you want to keep with `gemini_save_character`.
+
 ### Multi-turn (Interactions API)
 | Tool | Description |
 |------|-------------|
@@ -182,15 +200,16 @@ gemini_image_edit(prompt: "make the background blue", images_url: ["https://exam
 → the server fetches the URL itself; returns path to edited PNG
 ```
 
-**Reuse one photo across many generations (hosted hosted deployment, agent with a shell):**
+**Reuse one photo across many generations (hosted deployment, agent with a shell):**
 ```
-$ curl -X POST https://<hosted deployment>/upload -H "Authorization: Bearer $TOKEN" \
-    -H "Content-Type: image/jpeg" --data-binary @photo.jpg
-  → {"file_uri": "files/abc123"}
-
-gemini_image_edit(prompt: "make it winter",  images_file_uris: ["files/abc123"])
-gemini_image_edit(prompt: "make it sunrise", images_file_uris: ["files/abc123"])
-→ two edits, one upload, zero image bytes in context. Valid ~48h.
+gemini_get_upload_url(filename: "photo.jpg", content_type: "image/jpeg")
+  → { upload_url, r2_key: "up/…/photo.jpg" }
+$ curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "$UPLOAD_URL"
+
+gemini_image_edit(prompt: "make it winter",  images_r2_keys: ["up/…/photo.jpg"])
+gemini_image_edit(prompt: "make it sunrise", images_r2_keys: ["up/…/photo.jpg"])
+→ two edits, one upload, zero image bytes in context. To keep the photo past the
+  upload retention window, gemini_save_character it and pass characters: ["name"].
 ```
 
 **Generate a consistent set (master + scenes):**