@chrischall/gemini-mcp 2.3.3 → 2.3.4

package/dist/tools/files.js

@@ -89,7 +89,7 @@ export function registerFileTools(server, client) {
                 ? ' ' + confirmNote('A local `path` is confirmed first')
                 : ' To upload a local file without base64: mint a signed PUT URL with gemini_get_upload_url, PUT the bytes to it, ' +
                     'then pass the returned r2_key here.'),
-        annotations: { readOnlyHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
         inputSchema: z.object({
             url: z
                 .string()
@@ -168,6 +168,7 @@ export function registerFileTools(server, client) {
                 body: { inputs },
                 target: resolved,
                 payload: { inputs, display_name: args.display_name },
+                args,
                 confirmToken: args.confirmToken,
             });
             if (gate)
@@ -380,6 +381,7 @@ export function registerFileTools(server, client) {
             path: `/v1beta/${args.file_uri}`,
             target: args.file_uri,
             payload: { file_uri: args.file_uri },
+            args,
             confirmToken: args.confirmToken,
         });
         if (gate)

package/dist/tools/generate.js

@@ -19,7 +19,7 @@ export function registerGenerateTools(server, client) {
         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. ' +
             confirmNote('Local file inputs are confirmed first'),
-        annotations: { readOnlyHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             prompt: z.string().min(1).describe('Text prompt describing the image'),
             count: z.number().int().positive().max(8).optional().describe('Number of independent images (default 1)'),
@@ -166,7 +166,7 @@ export function registerGenerateTools(server, client) {
             'and avoids re-processing the full image each round; use gemini_image_edit 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. ' +
             confirmNote('Local file inputs are confirmed first'),
-        annotations: { readOnlyHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             prompt: z.string().min(1).describe('Instruction describing the edit or composition'),
             images: z.array(z.string().min(1)).optional().describe('Paths to input image file(s) (1 = edit, 2+ = compose). Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.'),

package/dist/tools/interact.js

@@ -11,10 +11,10 @@ import { fingerprintRequest } from '../jobs.js';
 import { attachCost } from '../pricing.js';
 import { confirmLocalInputs, confirmNote, confirmTokenParam } from './_confirm.js';
 // The last-interaction id and the written-outputs set used to live here, at
-// module scope. On the hosted connector that leaks across tenants — one
-// Cloudflare isolate serves many authenticated sessions, so `continue_last`
-// from user B would resume user A's interaction under B's key. Both now live
-// on `client.session` (src/session.ts), one per authenticated session.
+// module scope, which leaked across users on the retired multi-user Worker:
+// `continue_last` from user B resumed user A's interaction. Both now live on
+// `client.session` (src/session.ts) — one per client, and one client per
+// single-user process today (see the invariant there).
 /** Shared warning for the reference-image params. */
 const NEW_REFERENCES_ONLY = 'NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, ' +
     "do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it " +
@@ -91,7 +91,7 @@ export function registerInteractTools(server, client) {
             recoveryDescription +
             'Output is JPEG. ' +
             confirmNote('Local file inputs are confirmed first'),
-        annotations: { readOnlyHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             input: z.string().min(1).describe('Text prompt or editing instruction'),
             previous_interaction_id: z
@@ -133,7 +133,7 @@ export function registerInteractTools(server, client) {
             output_dir: z
                 .string()
                 .optional()
-                .describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
+                .describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)'),
             inline: z
                 .boolean()
                 .optional()

package/dist/tools/jobs.js

@@ -23,10 +23,10 @@ export function registerJobTools(server, client) {
             'A killed video/music job started with `background: true` is recovered from its upstream interaction when it finished there.',
         // NOT read-only any more: recovering a killed job writes the media it
         // pulls back, exactly as the generation tool would have.
-        annotations: { readOnlyHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             job_id: z.string().min(1).describe('The job_id returned by a generation tool called with async: true'),
-            output_dir: z.string().optional().describe('Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or cwd)'),
+            output_dir: z.string().optional().describe('Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)'),
         }),
     }, async (args) => {
         try {

package/dist/tools/library.js

@@ -62,7 +62,7 @@ export function registerLibraryTools(server, client) {
             'description. Saved characters have NO expiry — unlike uploads (~retention window) and Files API references (~48h) ' +
             '— so a name saved once keeps working in every later session. Re-saving a name replaces it. ' +
             USE_CHARACTERS_HINT,
-        annotations: { readOnlyHint: false, openWorldHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             name: NAME_FIELD,
             description: z
@@ -124,6 +124,7 @@ export function registerLibraryTools(server, client) {
             path: `characters/${args.name}`,
             target: args.name,
             payload: { name: args.name },
+            args,
             confirmToken: args.confirmToken,
         });
         if (gate)
@@ -138,7 +139,7 @@ export function registerLibraryTools(server, client) {
         description: 'Save a named style preset to this account\'s persistent reference library: a reusable prompt fragment (and ' +
             'optionally a reference image) that a single word then applies to any generation. No expiry; re-saving a name replaces it. ' +
             USE_STYLE_HINT,
-        annotations: { readOnlyHint: false, openWorldHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             name: NAME_FIELD,
             prompt_fragment: z
@@ -193,6 +194,7 @@ export function registerLibraryTools(server, client) {
             path: `styles/${args.name}`,
             target: args.name,
             payload: { name: args.name },
+            args,
             confirmToken: args.confirmToken,
         });
         if (gate)

package/dist/tools/models.js

@@ -1,8 +1,8 @@
-import { minifiedResult } from '@chrischall/mcp-utils';
+import { minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 export function registerModelTools(server, client) {
     server.registerTool('gemini_list_models', {
         description: 'List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.',
-        annotations: { readOnlyHint: true },
+        annotations: toolAnnotations({ readOnly: true, openWorld: true }),
     }, async () => {
         const models = await client.listModels();
         return minifiedResult({ default: client.defaultModel(), models });

package/dist/tools/music.js

@@ -30,7 +30,7 @@ export function registerMusicTools(server, client) {
             'cannot be refined by a follow-up call, so put the whole brief in the prompt. Runs long — give it a `max_wait_ms` ' +
             'budget (or `async: true` + gemini_get_result on a local install), or raise `timeout_ms`. Needs a funded account. ' +
             confirmNote('Local file inputs are confirmed first'),
-        annotations: { readOnlyHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             prompt: z.string().min(1).describe('Description of the music: mood, genre, instruments, tempo, structure, or lyrics'),
             model: z.enum(MUSIC_MODELS).optional().describe(`Lyria model (default: ${DEFAULT_MUSIC_MODEL} — 30s, $0.04). lyria-3.5 and lyria-3-pro-preview run minutes-long at $0.08.`),
@@ -40,7 +40,7 @@ export function registerMusicTools(server, client) {
             images_base64: imagesBase64Schema(),
             from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS clipboard as a reference'),
             filename: z.string().optional().describe('Base filename for the output audio (extension stripped; default: slugified prompt)'),
-            output_dir: z.string().optional().describe('Directory to write audio to (default: $GEMINI_OUTPUT_DIR or cwd)'),
+            output_dir: z.string().optional().describe('Directory to write audio to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)'),
             inline: z.boolean().optional().describe('Return base64 audio inline instead of writing to disk. A 30s track is ~1.9MB of base64 — the default hands back a path instead'),
             background: z.boolean().optional().describe('Run the generation on Google\'s side and poll it, so a killed job can be recovered by gemini_get_result. Off by default — see gemini_video_generate'),
             timeout_ms: timeoutMsSchema,

package/dist/tools/set.js

@@ -13,7 +13,7 @@ export function registerSetTools(server, client) {
         description: 'Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master). ' +
             'Scene generations run in parallel (reference_mode "master", the default). On the hosted connector: saved `characters` and a saved `style` can seed the whole set by name, multi-image results include a `bundle_url` zip of every image (one curl instead of N), and `max_wait_ms` returns a pollable job handle if the batch runs long. ' +
             confirmNote('Local file inputs are confirmed first'),
-        annotations: { readOnlyHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             master_prompt: z.string().min(1).describe('Prompt for the master/reference image'),
             scenes: z.array(z.string().min(1)).min(1).max(8).optional().describe('Per-image prompts (1-8); each references the master'),

package/dist/tools/shared.js

@@ -300,7 +300,7 @@ export const sharedImageSchema = {
         .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)'),
-    output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
+    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'),
     thinking_level: z.enum(['minimal', 'high']).optional().describe('Reasoning depth (Gemini 3 models); higher can help complex/structural edits'),

package/dist/tools/usage.js

@@ -33,7 +33,7 @@ export function registerUsageTools(server, client) {
         description: 'Token usage for this session so far — what every generation has cost in tokens, added up. ' +
             'Call it before and after a workflow and subtract to get that workflow\'s cost; call it after a ' +
             'single generation for that call\'s. Reports tokens AND an estimated USD cost, priced per call against each call\'s own model and stamped with the date its rates were read (override with GEMINI_RATE_CARD). Note there is no account-balance endpoint to query — Google Cloud is post-paid and its billing data lags by hours — so this is the accurate way to attribute spend to a call.',
-        annotations: toolAnnotations({ readOnly: true }),
+        annotations: toolAnnotations({ readOnly: true, openWorld: false }),
         inputSchema: z.object({
             reset: z
                 .boolean()

package/dist/tools/video.js

@@ -23,11 +23,9 @@ const VIDEO_RESOLUTIONS = ['360p', '720p', '1080p', '4k'];
 // escape hatch for a video model that rejects delivery outright.
 const VIDEO_DELIVERY = ['inline', 'uri'];
 // The most-recent video interaction id (for continue_last) lives on
-// `client.session`, NOT at module scope — one Cloudflare isolate serves many
-// authenticated connector sessions, so a module-level id would let one user's
-// continue_last resume another user's interaction under their own key. Video is
-// not registered on the Worker today, but the hazard is identical, so it is
-// scoped the same way. It stays separate from the image interact memory: a
+// `client.session`, NOT at module scope — on any host serving several users
+// from one process, a module-level id would let one user's continue_last
+// resume another user's interaction (see the invariant in src/session.ts). It stays separate from the image interact memory: a
 // "last video" and a "last image" are distinct chains. See src/session.ts.
 export function registerVideoTools(server, client) {
     server.registerTool('gemini_video_generate', {
@@ -38,7 +36,7 @@ export function registerVideoTools(server, client) {
             'Output is written to disk as MP4 (video has no inline MCP block). Video runs long — give it a `max_wait_ms` budget ' +
             '(or `async: true` + gemini_get_result on a local install), or raise `timeout_ms`. Needs a funded account. ' +
             confirmNote('Local file inputs are confirmed first'),
-        annotations: { readOnlyHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
             prompt: z.string().min(1).describe('Description of the video to generate (or the edit instruction when task=edit)'),
             aspect_ratio: z.enum(VIDEO_ASPECT_RATIOS).optional().describe('Exact output aspect ratio (omni: 16:9 or 9:16). `orientation` is the plain-language shorthand; this wins if both are given.'),
@@ -51,7 +49,7 @@ export function registerVideoTools(server, client) {
             images_base64: imagesBase64Schema(),
             from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS clipboard as a reference'),
             filename: z.string().optional().describe('Base filename for the output video (extension stripped; default: slugified prompt)'),
-            output_dir: z.string().optional().describe('Directory to write the video to (default: $GEMINI_OUTPUT_DIR or cwd)'),
+            output_dir: z.string().optional().describe('Directory to write the video to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)'),
             model: z
                 .string()
                 .regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")')

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.3'; // x-release-please-version
+export const VERSION = '2.3.4'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "2.3.3",
+  "version": "2.3.4",
   "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>",
@@ -46,7 +46,7 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.15.0",
+    "@chrischall/mcp-utils": "^3.0.0",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.2",
     "zod": "^4.6.5"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "2.3.3",
+  "version": "2.3.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "2.3.3",
+      "version": "2.3.4",
       "transport": {
         "type": "stdio"
       },
@@ -19,7 +19,7 @@
         {
           "name": "GEMINI_API_KEY",
           "description": "Your Google Gemini API key (aistudio.google.com/apikey)",
-          "isRequired": true,
+          "isRequired": false,
           "format": "string",
           "isSecret": true
         },
@@ -57,6 +57,41 @@
           "isRequired": false,
           "format": "string",
           "isSecret": false
+        },
+        {
+          "name": "GEMINI_TIMEOUT_MS",
+          "description": "Upstream request timeout in ms (default: 60000, or 120000 for image_size: \"4K\"); each generation tool also takes a per-call timeout_ms",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "GEMINI_HEARTBEAT_MS",
+          "description": "Progress-notification cadence in ms while a generation runs (default: 10000; 0 disables) — keeps MCP hosts that reset their timeout on progress from timing out long generations",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "GEMINI_CHAIN_RETRY_MS",
+          "description": "How long to wait out interactions-store lag when a chained call 404s (default: 120000; 0 disables retrying)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "GEMINI_DEBUG",
+          "description": "When set, emit heartbeat diagnostics to stderr. Off by default.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "GEMINI_RATE_CARD",
+          "description": "Override/extend the shipped USD-per-1M-token rates used by gemini_token_usage's cost estimate, e.g. {\"gemini-3-pro-image\":{\"input\":2,\"text_output\":12,\"image_output\":120}}. Malformed JSON is ignored (a bad card must not fail generations).",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }

package/skills/gemini-mcp/SKILL.md

@@ -70,7 +70,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.1-flash-image`) |
-| `GEMINI_OUTPUT_DIR` | No | Default directory for saved images (default: current working directory) |
+| `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) |
 
 ## Tools
@@ -318,7 +318,7 @@ Condensed from Google's official Nano Banana prompting guide. Core rule:
 - **`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_image_generate` / `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**. (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.
+- `output_dir` per-call overrides `$GEMINI_OUTPUT_DIR` overrides `~/Downloads/gemini-mcp`. `inline: true` returns bytes (with a metadata text block) instead of writing.
 - `count` and `scenes` are mutually exclusive in `gemini_image_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).