@chrischall/gemini-mcp 2.4.1 → 2.5.0

package/dist/tools/interact.js

@@ -5,7 +5,7 @@ import { ChainedRequest404Error } from '../client.js';
 import { slugify, baseName, resolveImagePath, writeSidecar, lookupOutputDir, readOutputImageAsInline } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { findInteractionImages, latestInteractionId } from '../sidecar.js';
-import { emit, reportShape, resolveAspectRatio, orientationSchema, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema } from './shared.js';
+import { emit, reportShape, resolveAspectRatio, orientationSchema, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema, hostedR2KeysParam, hostedUploadNote } from './shared.js';
 import { bytesToBase64 } from '../bytes.js';
 import { fingerprintRequest } from '../jobs.js';
 import { attachCost } from '../pricing.js';
@@ -89,6 +89,7 @@ export function registerInteractTools(server, client) {
             'do NOT start a new interaction or re-send the image for each tweak. `continue_last: true` chains from this ' +
             "session's most recent interaction without threading the id. " +
             recoveryDescription +
+            hostedUploadNote(client.mediaSink) +
             'Output is JPEG. ' +
             confirmNote('Local file inputs are confirmed first'),
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
@@ -108,6 +109,7 @@ export function registerInteractTools(server, client) {
                 .describe(`Paths to reference input images. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set. ${NEW_REFERENCES_ONLY}`),
             images_url: imagesUrlSchema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
             images_file_uris: imagesFileUrisSchema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
+            ...hostedR2KeysParam(client.mediaSink, `Reference images. ${NEW_REFERENCES_ONLY} Given`),
             images_base64: imagesBase64Schema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
             model: z
                 .string()
@@ -223,7 +225,7 @@ export function registerInteractTools(server, client) {
             thinking_level: args.thinking_level, previous_interaction_id: previousInteractionId,
             google_search: args.google_search, search_types: args.search_types,
             images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
-            images_url: args.images_url, images_file_uris: args.images_file_uris,
+            images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
             video_url: args.video_url, video_path: args.video_path,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_interact', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {

package/dist/tools/music.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_MUSIC_MODEL } from '../models.js';
-import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema } from './shared.js';
+import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema, hostedR2KeysParam, hostedUploadNote } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { attachCost } from '../pricing.js';
 import { confirmLocalInputs, confirmNote, confirmTokenParam } from './_confirm.js';
@@ -29,6 +29,7 @@ export function registerMusicTools(server, client) {
             'lyria-3-pro-preview (longer-form). Output is MP3, written to disk (or returned inline). Single-turn: a track ' +
             '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. ' +
+            hostedUploadNote(client.mediaSink) +
             confirmNote('Local file inputs are confirmed first'),
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
@@ -37,6 +38,7 @@ export function registerMusicTools(server, client) {
             images: z.array(z.string().min(1)).optional().describe('Optional reference image path(s) to condition the music. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.'),
             images_url: imagesUrlSchema('Reference images'),
             images_file_uris: imagesFileUrisSchema('Reference images'),
+            ...hostedR2KeysParam(client.mediaSink, 'Reference images'),
             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)'),
@@ -62,7 +64,7 @@ export function registerMusicTools(server, client) {
         const fingerprint = fingerprintRequest('gemini_music_generate', {
             model, prompt: args.prompt,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
-            images_url: args.images_url, images_file_uris: args.images_file_uris,
+            images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {
             const { inputs, report } = await resolveImageInputs(args, client);

package/dist/tools/shared.js

@@ -5,7 +5,7 @@ import { IMAGE_URL_MAX_BYTES, IMAGE_INLINE_MAX_BYTES } from '../fetch-image.js';
 import { bytesToBase64, base64ToBytes, wholeMb } from '../bytes.js';
 import { createDiskSink } from '../storage/media.js';
 import { downloadFilename } from '../media-name.js';
-import { buildZip } from '../zip.js';
+import { buildZip } from '@chrischall/mcp-utils/export';
 /**
  * Fallback sink for call sites that pass no explicit one (every pre-existing
  * test, and any caller constructed before the sink seam existed). The stdio
@@ -144,6 +144,32 @@ export function imagesR2KeysSchema(label = 'Reference images') {
         "generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. " +
         'Hosted connector only.');
 }
+/**
+ * `images_r2_keys` for a tool, but ONLY where a key can resolve.
+ *
+ * An `r2_key` names an object in the hosted connector's blob store; a disk
+ * install has no store, so there the param could never work and would be
+ * standing `tools/list` cost on every request (see tool-surface-budget). So it
+ * is registered from the sink's capability, like interact's recovery text.
+ *
+ * The cast is runtime-honest: off the hosted connector the key is absent from
+ * the schema, zod strips it, and `args.images_r2_keys` is `undefined` — which
+ * is exactly what the declared optional type allows.
+ */
+export function hostedR2KeysParam(sink, label) {
+    return ((sink ?? DEFAULT_SINK).persistsFiles ? {} : { images_r2_keys: imagesR2KeysSchema(label) });
+}
+/**
+ * The description sentence that sends a hosted caller to the upload route.
+ * Empty on disk (where `images` paths work and no upload tool exists), so it
+ * costs nothing there.
+ */
+export function hostedUploadNote(sink) {
+    return (sink ?? DEFAULT_SINK).persistsFiles
+        ? ''
+        : 'For a reference photo you hold locally: gemini_get_upload_url, curl PUT it, then pass its r2_key in images_r2_keys ' +
+            '(no bytes in the conversation; reusable across calls). ';
+}
 /** Saved-character names attached to a generation (hosted connector only). */
 export const charactersSchema = z
     .array(z.string().min(1))
@@ -616,7 +642,10 @@ export async function persistBundle(named, sink, base) {
     }
     try {
         const { mediaExt } = await import('../images.js');
-        const zip = buildZip(named.map((n) => ({ name: `${n.base}.${mediaExt(n.image.mimeType)}`, bytes: base64ToBytes(n.image.base64) })));
+        // STORE (`compress: false`): the images are already-compressed PNG/JPEG,
+        // so DEFLATE would only spend CPU, and STORE keeps the bundle byte-identical
+        // to what this repo's retired hand-rolled zip writer produced.
+        const zip = buildZip(named.map((n) => ({ name: `${n.base}.${mediaExt(n.image.mimeType)}`, bytes: base64ToBytes(n.image.base64), compress: false })));
         const [persisted] = await sink.persist([{ base: `${base}-bundle`, base64: bytesToBase64(zip), mimeType: 'application/zip' }], { urlTtlMs: SET_URL_TTL_MS });
         if (!persisted || persisted.unavailable) {
             return { bundle_skipped: 'The bundle zip could not be stored; the images themselves are unaffected — download them individually via their media urls / curl_hints.' };

package/dist/tools/video.js

@@ -3,7 +3,7 @@ import { McpToolError } from '@chrischall/mcp-utils';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_VIDEO_MODEL } from '../models.js';
-import { emitMedia, reportShape, resolveAspectRatio, orientationSchema, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema } from './shared.js';
+import { emitMedia, reportShape, resolveAspectRatio, orientationSchema, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema, hostedR2KeysParam, hostedUploadNote } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { attachCost } from '../pricing.js';
 import { confirmLocalInputs, confirmNote, confirmTokenParam } from './_confirm.js';
@@ -35,6 +35,7 @@ export function registerVideoTools(server, client) {
             'add ~3-10s each, to ~40s total). Cost scales with `resolution` — draft at 360p, keep at 1080p/4k. ' +
             '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. ' +
+            hostedUploadNote(client.mediaSink) +
             confirmNote('Local file inputs are confirmed first'),
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         inputSchema: z.object({
@@ -46,6 +47,7 @@ export function registerVideoTools(server, client) {
             images: z.array(z.string().min(1)).optional().describe('Reference image path(s) for image_to_video / reference_to_video. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.'),
             images_url: imagesUrlSchema('Reference stills'),
             images_file_uris: imagesFileUrisSchema('Reference stills'),
+            ...hostedR2KeysParam(client.mediaSink, 'Reference stills'),
             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)'),
@@ -95,7 +97,7 @@ export function registerVideoTools(server, client) {
             // where `delivery` is not (same bytes, different transport).
             model, prompt: args.prompt, aspect_ratio: aspectRatio, resolution: args.resolution, task: args.task,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
-            images_url: args.images_url, images_file_uris: args.images_file_uris,
+            images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
             previous_interaction_id: previousInteractionId,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "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": "^3.0.3",
+    "@chrischall/mcp-utils": "^3.3.0",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.2",
     "undici": "^8.12.2",
@@ -59,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.1",
+  "version": "2.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "2.4.1",
+      "version": "2.5.0",
       "transport": {
         "type": "stdio"
       },

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;
-}