@chrischall/gemini-mcp 2.4.0 → 2.4.2

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

package/mint.yaml

@@ -4,6 +4,19 @@ slug: gemini
 summary: >-
   Generate and edit images with Google Gemini image models (Nano Banana /
   Nano Banana Pro) via natural language prompts
+examples:
+  - prompt: >-
+      Generate a watercolor illustration of a lighthouse on a rocky coast at
+      sunset, in a 16:9 aspect ratio.
+    note: Text-to-image with gemini_image_generate.
+  - prompt: >-
+      Make a set of four images of the same cartoon fox mascot: waving,
+      reading a book, riding a bike, and sleeping under a tree.
+    note: A consistent character across scenes with gemini_image_set.
+  - prompt: >-
+      Compose a 30-second upbeat acoustic guitar instrumental for a cooking
+      video intro.
+    note: A short Lyria clip with gemini_music_generate.
 env:
   - name: GEMINI_API_KEY
     secret: true
@@ -17,12 +30,24 @@ env:
   - 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 +63,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.4.0",
+  "version": "2.4.2",
   "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.3.0",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.2",
+    "undici": "^8.12.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {
@@ -58,5 +59,9 @@
     "esbuild": "^0.28.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"
+  },
+  "allowScripts": {
+    "esbuild": false,
+    "fsevents": false
   }
 }

package/server.json

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

@@ -96,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`.
@@ -105,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
@@ -130,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 |
 |------|-------------|
@@ -183,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):**

package/dist/zip.js

@@ -1,113 +0,0 @@
-/**
- * Minimal ZIP writer (STORE only, no compression) for bundling a multi-image
- * result into one downloadable archive.
- *
- * Why hand-rolled: the Worker has no filesystem and no archiver dependency,
- * and the images being bundled are already-compressed PNG/JPEG — DEFLATE would
- * buy nothing. STORE entries are just headers + raw bytes + CRC32, which is
- * ~100 lines and runs identically under Node and workerd.
- *
- * Layout: [local header + name + data]* [central directory]* [EOCD]. No
- * ZIP64 (a bundle is a handful of images, far under the 4 GB / 65k-entry
- * limits), no encryption, no streaming.
- */
-/** Standard CRC-32 (IEEE 802.3), table-driven. The table is immutable. */
-const CRC_TABLE = (() => {
-    const table = new Uint32Array(256);
-    for (let n = 0; n < 256; n++) {
-        let c = n;
-        for (let k = 0; k < 8; k++)
-            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
-        table[n] = c >>> 0;
-    }
-    return table;
-})();
-export function crc32(bytes) {
-    let crc = 0xffffffff;
-    for (let i = 0; i < bytes.length; i++) {
-        crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
-    }
-    return (crc ^ 0xffffffff) >>> 0;
-}
-/** MS-DOS date/time pair (ZIP's native timestamp format). */
-function dosDateTime(at) {
-    const year = Math.max(1980, at.getUTCFullYear());
-    return {
-        time: (at.getUTCHours() << 11) | (at.getUTCMinutes() << 5) | (at.getUTCSeconds() >> 1),
-        date: ((year - 1980) << 9) | ((at.getUTCMonth() + 1) << 5) | at.getUTCDate(),
-    };
-}
-const LOCAL_HEADER = 0x04034b50;
-const CENTRAL_HEADER = 0x02014b50;
-const EOCD = 0x06054b50;
-/** Version 2.0 — the minimum that understands STORE + directories. */
-const VERSION = 20;
-/** General-purpose bit 11: names are UTF-8. */
-const FLAG_UTF8 = 0x0800;
-/**
- * Build a STORE-only zip. `modifiedAt` stamps every entry (injectable so a
- * given input always produces identical bytes; defaults to the epoch of the
- * format, 1980).
- */
-export function buildZip(entries, modifiedAt = new Date(Date.UTC(1980, 0, 1))) {
-    const { time, date } = dosDateTime(modifiedAt);
-    const encoder = new TextEncoder();
-    const parts = [];
-    const central = [];
-    let offset = 0;
-    for (const entry of entries) {
-        const name = encoder.encode(entry.name);
-        const crc = crc32(entry.bytes);
-        const size = entry.bytes.byteLength;
-        const local = new Uint8Array(30 + name.byteLength);
-        const lv = new DataView(local.buffer);
-        lv.setUint32(0, LOCAL_HEADER, true);
-        lv.setUint16(4, VERSION, true);
-        lv.setUint16(6, FLAG_UTF8, true);
-        lv.setUint16(8, 0, true); // method: STORE
-        lv.setUint16(10, time, true);
-        lv.setUint16(12, date, true);
-        lv.setUint32(14, crc, true);
-        lv.setUint32(18, size, true); // compressed == uncompressed under STORE
-        lv.setUint32(22, size, true);
-        lv.setUint16(26, name.byteLength, true);
-        lv.setUint16(28, 0, true); // extra length
-        local.set(name, 30);
-        const dir = new Uint8Array(46 + name.byteLength);
-        const dv = new DataView(dir.buffer);
-        dv.setUint32(0, CENTRAL_HEADER, true);
-        dv.setUint16(4, VERSION, true); // version made by
-        dv.setUint16(6, VERSION, true); // version needed
-        dv.setUint16(8, FLAG_UTF8, true);
-        dv.setUint16(10, 0, true);
-        dv.setUint16(12, time, true);
-        dv.setUint16(14, date, true);
-        dv.setUint32(16, crc, true);
-        dv.setUint32(20, size, true);
-        dv.setUint32(24, size, true);
-        dv.setUint16(28, name.byteLength, true);
-        // extra len, comment len, disk start, internal attrs, external attrs = 0
-        dv.setUint32(42, offset, true);
-        dir.set(name, 46);
-        parts.push(local, entry.bytes);
-        central.push(dir);
-        offset += local.byteLength + size;
-    }
-    const centralSize = central.reduce((n, c) => n + c.byteLength, 0);
-    const eocd = new Uint8Array(22);
-    const ev = new DataView(eocd.buffer);
-    ev.setUint32(0, EOCD, true);
-    ev.setUint16(8, entries.length, true); // entries on this disk
-    ev.setUint16(10, entries.length, true); // entries total
-    ev.setUint32(12, centralSize, true);
-    ev.setUint32(16, offset, true); // central directory offset
-    // comment length = 0
-    const total = offset + centralSize + eocd.byteLength;
-    const out = new Uint8Array(total);
-    let cursor = 0;
-    for (const part of [...parts, ...central, eocd]) {
-        out.set(part, cursor);
-        cursor += part.byteLength;
-    }
-    return out;
-}