@chrischall/gemini-mcp 2.3.0 → 2.3.1

package/dist/client.js

@@ -1,4 +1,4 @@
-import { basename, delimiter } from 'node:path';
+import { basename } from 'node:path';
 import { readEnvVar, McpToolError, ApiError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
 import { resolveModel, filterImageModels, DEFAULT_VIDEO_MODEL, DEFAULT_MUSIC_MODEL } from './models.js';
 import { readUsage } from './usage.js';
@@ -11,6 +11,7 @@ import { createBlobJobStore } from './job-store.js';
 import { SessionState } from './session.js';
 import { fetchRemoteImage, readCapped, MAX_REDIRECTS } from './fetch-image.js';
 import { bytesToBase64 } from './bytes.js';
+import { explainOutsideUploadDir, uploadRoots } from './images.js';
 // NOTE: this module must stay SIDE-EFFECT-FREE at module scope — no I/O, no
 // top-level await, no `import.meta.url`. `src/worker.ts` imports it, so every
 // line here runs during Cloudflare isolate startup, where global-scope I/O is
@@ -181,29 +182,6 @@ export function normalizeFileName(ref) {
     }
     return match[1];
 }
-/**
- * `GEMINI_UPLOAD_DIR` — the optional allow-list for local files streamed to
- * the Files API (`gemini_upload_file` `path`, `video_path`). One or more
- * directories separated by the platform path delimiter (`:` / `;`); `~` is
- * expanded by mcp-utils. Unset → `undefined` → uploads stay unconfined.
- * The paths are model-chosen, so a prompt-injected path could otherwise send
- * any readable file to Google.
- */
-function uploadRoots() {
-    const roots = readEnvVar('GEMINI_UPLOAD_DIR')?.split(delimiter).map((r) => r.trim()).filter(Boolean);
-    return roots && roots.length > 0 ? roots : undefined;
-}
-/**
- * Turn mcp-utils' bare "outside the allowed directories" refusal into an
- * actionable tool error. The remediation is in the MESSAGE — hosts show the
- * message and drop the hint (see CLAUDE.md, Errors).
- */
-function explainOutsideUploadDir(err) {
-    if (err instanceof Error && err.message.startsWith('Path is outside the allowed directories')) {
-        throw new McpToolError('Refusing to upload a file outside GEMINI_UPLOAD_DIR, which restricts which local files can be uploaded to Google. Move the file into GEMINI_UPLOAD_DIR, or add its directory to GEMINI_UPLOAD_DIR.');
-    }
-    throw err;
-}
 export class GeminiClient {
     /**
      * A key handed in explicitly (the connector's per-session key). When absent

package/dist/images.js

@@ -1,7 +1,89 @@
-import { mkdir, readFile, writeFile, access, stat, open } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join, resolve, isAbsolute } from 'node:path';
-import { readEnvVar, McpToolError } from '@chrischall/mcp-utils';
+import { delimiter, join, resolve, isAbsolute } from 'node:path';
+import { assertPathWithinRoots, expandPath, fileBlob, readEnvVar, McpToolError, readFileHead, resolveOutputDir as resolveSharedOutputDir, sniffMimeBytes as sniffSharedMime, writeFileSafe, writeUniqueFile, } from '@chrischall/mcp-utils';
+/**
+ * `GEMINI_UPLOAD_DIR` — the optional allow-list for local files streamed to
+ * the Files API (`gemini_upload_file` `path`, `video_path`). One or more
+ * directories separated by the platform path delimiter (`:` / `;`); `~` is
+ * expanded by mcp-utils. Unset → `undefined` → uploads stay unconfined.
+ * The paths are model-chosen, so a prompt-injected path could otherwise send
+ * any readable file to Google.
+ */
+export function uploadRoots() {
+    const roots = readEnvVar('GEMINI_UPLOAD_DIR')?.split(delimiter).map((r) => r.trim()).filter(Boolean);
+    return roots && roots.length > 0 ? roots : undefined;
+}
+/**
+ * Turn mcp-utils' bare "outside the allowed directories" refusal into an
+ * actionable tool error. The remediation is in the MESSAGE — hosts show the
+ * message and drop the hint (see CLAUDE.md, Errors).
+ */
+export function explainOutsideUploadDir(err) {
+    if (err instanceof Error && err.message.startsWith('Path is outside the allowed directories')) {
+        throw new McpToolError('Refusing to upload a file outside GEMINI_UPLOAD_DIR, which restricts which local files can be uploaded to Google. Move the file into GEMINI_UPLOAD_DIR, or add its directory to GEMINI_UPLOAD_DIR.');
+    }
+    throw err;
+}
+/** A path-delimiter list from `name`, trimmed, blanks dropped; `undefined` when empty. */
+function rootList(name, env) {
+    const roots = readEnvVar(name, { env })?.split(delimiter).map((r) => r.trim()).filter(Boolean);
+    return roots && roots.length > 0 ? roots : undefined;
+}
+/**
+ * The folders a local REFERENCE image (`images` / `image_path` paths) may be
+ * read from. Those bytes go to Google — inline, or as a Files API upload once a
+ * path is reused (inputs.ts) — and the path is model-chosen, so a
+ * prompt-injected path could otherwise send any readable file. In order:
+ *
+ * 1. `GEMINI_REFERENCE_DIR` — one or more folders (`:` / `;` separated, `~` ok);
+ * 2. else `GEMINI_UPLOAD_DIR` — the existing allow-list for local files sent to
+ *    the Files API, so an operator who restricted uploads gets reference images
+ *    restricted too;
+ * 3. else, hosted (`MCP_DATA_DIR` set) — only `$MCP_DATA_DIR/uploads`: never the
+ *    runner's home, nor the data dir itself (it holds tokens and job state);
+ * 4. else `undefined` — a local install with nothing configured stays
+ *    unconfined (the user's own files, on their own machine).
+ *
+ * When confinement is on, `GEMINI_OUTPUT_DIR` (operator config) is added, so
+ * this server's own generated images can always be fed back in as references.
+ */
+export function referenceRoots(env = process.env) {
+    let roots = rootList('GEMINI_REFERENCE_DIR', env) ?? rootList('GEMINI_UPLOAD_DIR', env);
+    if (!roots) {
+        const dataDir = readEnvVar('MCP_DATA_DIR', { env });
+        if (dataDir)
+            roots = [join(dataDir, 'uploads')];
+    }
+    if (!roots)
+        return undefined;
+    const output = readEnvVar('GEMINI_OUTPUT_DIR', { env })?.trim();
+    return output && !roots.includes(output) ? [...roots, output] : roots;
+}
+/** mcp-utils' bare out-of-roots refusal → an actionable reference-image error. */
+function explainOutsideReferenceDir(err, roots) {
+    if (err instanceof Error && err.message.startsWith('Path is outside the allowed directories')) {
+        throw new McpToolError(`Refusing to send a reference image from outside the allowed folders (${roots.join(', ')}). ` +
+            'Reference images are confined by GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR; on a hosted server, $MCP_DATA_DIR/uploads). ' +
+            'Move the image into one of those folders, or add its folder to GEMINI_REFERENCE_DIR (outside GEMINI_REFERENCE_DIR is refused).');
+    }
+    throw err;
+}
+/**
+ * Refuse a resolved reference-image path outside {@link referenceRoots} (no-op
+ * when unconfined). Checked through symlinks, before the file is stat'ed or read.
+ */
+export function assertReferenceAllowed(resolvedPath) {
+    const roots = referenceRoots();
+    if (!roots)
+        return;
+    try {
+        assertPathWithinRoots(resolvedPath, roots);
+    }
+    catch (err) {
+        explainOutsideReferenceDir(err, roots);
+    }
+}
 /** URL/file-safe slug from a prompt; never empty. */
 export function slugify(text, max = 40) {
     const s = text
@@ -12,25 +94,6 @@ export function slugify(text, max = 40) {
         .replace(/-+$/g, '');
     return s || 'image';
 }
-async function exists(p) {
-    try {
-        await access(p);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** `<base>.<ext>`, then `<base>-2.<ext>`, … until a free path is found. */
-export async function uniquePath(dir, base, ext) {
-    let candidate = join(dir, `${base}.${ext}`);
-    let n = 2;
-    while (await exists(candidate)) {
-        candidate = join(dir, `${base}-${n}.${ext}`);
-        n++;
-    }
-    return candidate;
-}
 /** Sniff MIME type from the first bytes of an image buffer (PNG fallback).
  * Only for bytes that arrive as base64 with no other type information; a LOCAL
  * file goes through {@link localImageMime}, which never guesses. */
@@ -51,23 +114,17 @@ function localImageMime(resolvedPath, head) {
     }
     return mime;
 }
-/** PNG/JPEG/WebP from the leading bytes, or `undefined` when it is none of them. */
+/** The image types Gemini takes as reference images — the only sniff results honoured here. */
+const REFERENCE_IMAGE_MIMES = new Set(['image/png', 'image/jpeg', 'image/webp']);
+/**
+ * PNG/JPEG/WebP from the leading bytes (mcp-utils' shared magic-byte sniffer),
+ * or `undefined` when it is none of them. The shared sniffer also names GIF,
+ * PDF, zip, MIDI and ISO-BMFF; those are deliberately NOT accepted here, so a
+ * reference image is still only ever one of the three types Gemini takes.
+ */
 function sniffImageMime(buf) {
-    // PNG: 89 50 4E 47
-    if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
-        return 'image/png';
-    }
-    // JPEG: FF D8 FF
-    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
-        return 'image/jpeg';
-    }
-    // WebP: RIFF....WEBP (bytes 0-3 = RIFF, bytes 8-11 = WEBP)
-    if (buf.length >= 12 &&
-        buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
-        buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50) {
-        return 'image/webp';
-    }
-    return undefined;
+    const mime = sniffSharedMime(buf);
+    return mime !== undefined && REFERENCE_IMAGE_MIMES.has(mime) ? mime : undefined;
 }
 /** File extension for a media MIME (image/video/audio). Falls back to the MIME
  * subtype, so an unforeseen preview type still writes with a sane extension. */
@@ -94,11 +151,19 @@ export function mediaExt(mimeType) {
     return m.split('/')[1]?.split(';')[0]?.replace(/^x-/, '') || 'bin';
 }
 /** Decode base64 media bytes (image/video/audio) and write to disk (creating
- * dir), picking the extension from the MIME. Returns the absolute path. */
+ * dir), picking the extension from the MIME. Returns the absolute path.
+ *
+ * Never overwrites: `<base>.<ext>`, then `<base>-2.<ext>`, … — each name is
+ * claimed with an exclusive, no-follow create (mcp-utils `writeUniqueFile`), so
+ * two writers can't race onto one name and a symlink planted at a name is
+ * skipped rather than written through. */
 export async function writeMedia(dir, base, base64, mimeType) {
-    await mkdir(dir, { recursive: true });
-    const path = await uniquePath(dir, base, mediaExt(mimeType));
-    await writeFile(path, Buffer.from(base64, 'base64'));
+    const path = await writeUniqueFile({
+        dir,
+        baseName: base,
+        extension: mediaExt(mimeType),
+        bytes: Buffer.from(base64, 'base64'),
+    });
     return resolve(path);
 }
 /** Decode base64 image bytes and write to disk. Returns the absolute path. */
@@ -113,7 +178,8 @@ export async function writeImage(dir, base, base64, mimeType) {
  * multi-turn chain is recoverable from disk.
  */
 export async function writeSidecar(imagePath, data) {
-    await writeFile(`${imagePath}.json`, JSON.stringify(data, null, 2));
+    // overwrite (a re-run may refresh it) but never through a planted symlink.
+    await writeFileSafe(`${imagePath}.json`, Buffer.from(JSON.stringify(data, null, 2)), { overwrite: true });
 }
 /**
  * Resolve an input file path, checking (in order):
@@ -174,6 +240,19 @@ export function videoMimeType(p) {
     }
     return mime;
 }
+/**
+ * The first 16 bytes of a local reference image, confined to
+ * {@link referenceRoots} when those are set.
+ */
+async function readLocalHead(path) {
+    const roots = referenceRoots();
+    try {
+        return await readFileHead(path, 16, { ...(roots ? { allowedRoots: roots } : {}) });
+    }
+    catch (err) {
+        return roots ? explainOutsideReferenceDir(err, roots) : Promise.reject(err);
+    }
+}
 /**
  * Preview a local IMAGE input WITHOUT sending it anywhere: resolve the path to
  * an absolute one, sniff its mime from the leading bytes, and measure its size.
@@ -182,19 +261,12 @@ export function videoMimeType(p) {
  */
 export async function previewImageInput(path) {
     const resolved = resolveImagePath(path);
+    assertReferenceAllowed(resolved);
     // Read only the header bytes needed to sniff the MIME (≤12), and take the size
     // from stat() — a preview must not load a large reference image into memory
     // just to report it (matches previewVideoInput).
     const { size } = await stat(resolved);
-    const fh = await open(resolved, 'r');
-    try {
-        const head = Buffer.alloc(16);
-        const { bytesRead } = await fh.read(head, 0, 16, 0);
-        return { path: resolved, mimeType: localImageMime(resolved, head.subarray(0, bytesRead)), size };
-    }
-    finally {
-        await fh.close();
-    }
+    return { path: resolved, mimeType: localImageMime(resolved, await readLocalHead(resolved)), size };
 }
 /**
  * Preview a local VIDEO input WITHOUT uploading it: resolve the path, derive its
@@ -226,17 +298,6 @@ const UPLOAD_MIME_BY_EXT = {
     flac: 'audio/flac',
     ...VIDEO_MIME_BY_EXT,
 };
-async function readHead(path, n = 16) {
-    const fh = await open(path, 'r');
-    try {
-        const head = Buffer.alloc(n);
-        const { bytesRead } = await fh.read(head, 0, n, 0);
-        return head.subarray(0, bytesRead);
-    }
-    finally {
-        await fh.close();
-    }
-}
 /**
  * The MIME a local file should be uploaded to the Files API as, or `undefined`
  * when it cannot be identified. Bytes win for the image formats we can sniff
@@ -245,19 +306,53 @@ async function readHead(path, n = 16) {
  * to label every unrecognised file image/png (chrischall/fleet-audit#117).
  */
 export async function detectUploadMime(resolvedPath) {
-    const sniffed = sniffImageMime(await readHead(resolvedPath));
+    // Confined to GEMINI_UPLOAD_DIR when set — the same roots the upload itself
+    // (fileBlob in client.ts) enforces, so an out-of-root path is refused here,
+    // before the confirmation preview, rather than after it.
+    const roots = uploadRoots();
+    let head;
+    try {
+        head = await readFileHead(resolvedPath, 16, { ...(roots ? { allowedRoots: roots } : {}) });
+    }
+    catch (err) {
+        explainOutsideUploadDir(err);
+    }
+    const sniffed = sniffImageMime(head);
     if (sniffed)
         return sniffed;
     const ext = resolvedPath.includes('.') ? resolvedPath.slice(resolvedPath.lastIndexOf('.') + 1).toLowerCase() : '';
     return UPLOAD_MIME_BY_EXT[ext];
 }
-/** Read an image file into `{ base64, mimeType }` for an inline_data part. */
+/**
+ * Read a model-supplied reference image into `{ base64, mimeType }` for an
+ * inline_data part, confined to {@link referenceRoots} when those are set
+ * (mcp-utils `fileBlob` with `allowedRoots`, checked through symlinks).
+ */
 export async function readImageAsInline(path) {
     const resolved = resolveImagePath(path);
-    const buf = await readFile(resolved);
+    const roots = referenceRoots();
+    let buf;
+    try {
+        buf = Buffer.from(await (await fileBlob(resolved, { label: 'Image', ...(roots ? { allowedRoots: roots } : {}) })).arrayBuffer());
+    }
+    catch (err) {
+        if (roots)
+            explainOutsideReferenceDir(err, roots);
+        throw err;
+    }
     const mimeType = localImageMime(resolved, buf);
     return { base64: buf.toString('base64'), mimeType };
 }
+/**
+ * Read an image THIS server wrote (an interaction's output, found by its
+ * sidecar under the GEMINI_OUTPUT_DIR-confined {@link lookupOutputDir}) for
+ * re-anchoring a chain. Not model-chosen, so not subject to the reference
+ * roots — a chain must recover its own output wherever output_dir put it.
+ */
+export async function readOutputImageAsInline(path) {
+    const buf = await readFile(path);
+    return { base64: buf.toString('base64'), mimeType: localImageMime(path, buf) };
+}
 /**
  * Accept either a data URI (`data:image/png;base64,XXXX`) or raw base64.
  * For raw base64, MIME is sniffed from the decoded bytes.
@@ -293,7 +388,36 @@ export function baseName(name) {
         .replace(/^-+|-+$/g, '');
     return safe || 'image';
 }
-/** per-call → $GEMINI_OUTPUT_DIR → cwd. */
+/**
+ * The output directory to LOOK IN (sidecar lookups: `continue_last`'s disk
+ * fallback, the chain-404 re-anchor) — the same resolution and the same
+ * GEMINI_OUTPUT_DIR confinement as {@link resolveOutputDir}, but read-only:
+ * it never creates the directory, so a lookup that writes nothing leaves no
+ * empty folder behind. A missing directory simply has no sidecars.
+ */
+export function lookupOutputDir(perCall) {
+    const trimmed = perCall?.trim() || undefined;
+    const configured = readEnvVar('GEMINI_OUTPUT_DIR');
+    const raw = trimmed ?? configured;
+    if (!raw)
+        return process.cwd();
+    const dir = expandPath(raw);
+    if (trimmed && configured)
+        assertPathWithinRoots(dir, [configured]);
+    return dir;
+}
+/**
+ * per-call → $GEMINI_OUTPUT_DIR → cwd (mcp-utils `resolveOutputDir`: `~` and
+ * relative paths expanded, the directory created; a per-call dir confined to
+ * GEMINI_OUTPUT_DIR when that is set). A blank per-call value
+ * counts as unset, so it falls through to the env var rather than to cwd.
+ */
 export function resolveOutputDir(perCall) {
-    return perCall?.trim() || readEnvVar('GEMINI_OUTPUT_DIR') || process.cwd();
+    // output_dir is model-chosen: once the operator sets GEMINI_OUTPUT_DIR, a
+    // per-call directory must stay inside it (checked through symlinks). Unset
+    // keeps the old, unconfined behaviour (the fleet pattern, as in splitwise-mcp).
+    const configured = readEnvVar('GEMINI_OUTPUT_DIR');
+    return resolveSharedOutputDir(perCall?.trim() || undefined, 'GEMINI_OUTPUT_DIR', {
+        ...(configured ? { allowedRoots: [configured] } : {}),
+    });
 }

package/dist/inputs.js

@@ -131,7 +131,7 @@ export async function resolveImageInputs(args, client) {
  * key rather than silently reusing an upload of the old content.
  */
 async function resolveLocalPath(path, client, onDisk, report) {
-    const { readImageAsInline, resolveImagePath } = await import('./images.js');
+    const { readImageAsInline, resolveImagePath, assertReferenceAllowed } = await import('./images.js');
     // A runtime with no filesystem never gets here — `assertLocalInputsAvailable`
     // rejects `images` before any of this — but if it somehow did, reading the
     // file is what would fail, so keep the pre-existing error path.
@@ -139,6 +139,8 @@ async function resolveLocalPath(path, client, onDisk, report) {
         return readImageAsInline(path);
     const { stat } = await import('node:fs/promises');
     const resolved = resolveImagePath(path);
+    // Before the stat, the read, and any Files API promotion below.
+    assertReferenceAllowed(resolved);
     let key;
     try {
         const { mtimeMs, size } = await stat(resolved);

package/dist/storage/media.js

@@ -17,7 +17,7 @@ import { signedLinks } from '../signed-url.js';
 import { tenantResolver } from '../tenant.js';
 /**
  * The stdio sink: `resolveOutputDir(output_dir)` → `writeMedia` per item, in
- * order (so `uniquePath`'s `name`/`name-2`/`name-3` sequencing is preserved).
+ * order (so the `name`/`name-2`/`name-3` sequencing is preserved).
  *
  * `node:fs` is reached through a dynamic import so this module stays loadable
  * in a Worker, where the R2 sink is the only one ever constructed.
@@ -30,8 +30,9 @@ export function createDiskSink() {
             const { writeMedia, resolveOutputDir } = await import('../images.js');
             const dir = resolveOutputDir(opts.output_dir);
             const refs = [];
-            // Sequential on purpose: uniquePath checks the filesystem, so writing two
-            // colliding names concurrently would race onto the same path.
+            // Sequential on purpose: it keeps the `name`, `name-2`, `name-3` numbering
+            // in item order (writeMedia's exclusive create makes concurrency safe,
+            // but not ordered).
             for (const it of items)
                 refs.push({ ref: await writeMedia(dir, it.base, it.base64, it.mimeType) });
             return refs;

package/dist/tools/generate.js

@@ -24,7 +24,7 @@ export function registerGenerateTools(server, client) {
             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)'),
             filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
-            images: z.array(z.string().min(1)).optional().describe('Paths to reference input images (image-conditioned generation)'),
+            images: z.array(z.string().min(1)).optional().describe('Paths to reference input images (image-conditioned generation). Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.'),
             images_url: imagesUrlSchema(),
             images_file_uris: imagesFileUrisSchema(),
             images_r2_keys: imagesR2KeysSchema(),
@@ -169,7 +169,7 @@ export function registerGenerateTools(server, client) {
         annotations: { readOnlyHint: false, 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)'),
+            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.'),
             images_url: imagesUrlSchema('Input images'),
             images_file_uris: imagesFileUrisSchema('Input images'),
             images_r2_keys: imagesR2KeysSchema('Input images'),

package/dist/tools/interact.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { McpToolError, ApiError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { ChainedRequest404Error } from '../client.js';
-import { slugify, baseName, resolveImagePath, writeSidecar, resolveOutputDir, readImageAsInline } from '../images.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';
@@ -45,7 +45,7 @@ function splitReattachedOutputs(images, writtenOutputs) {
  */
 async function reanchorFromDisk(outputDir, interactionId) {
     const refs = await findInteractionImages(outputDir, interactionId);
-    return { refs, carried: await Promise.all(refs.map((p) => readImageAsInline(p))) };
+    return { refs, carried: await Promise.all(refs.map((p) => readOutputImageAsInline(p))) };
 }
 /** The same, from the object store, for a deployment with no filesystem. */
 async function reanchorFromStore(client, interactionId) {
@@ -105,7 +105,7 @@ export function registerInteractTools(server, client) {
             images: z
                 .array(z.string().min(1))
                 .optional()
-                .describe(`Paths to reference input images. ${NEW_REFERENCES_ONLY}`),
+                .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`),
             images_base64: imagesBase64Schema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
@@ -183,7 +183,7 @@ export function registerInteractTools(server, client) {
                 // record — an `<image>.json` on disk, an object beside the media in
                 // the store — so a restart no longer ends a chain on either.
                 previousInteractionId = onDisk
-                    ? await latestInteractionId(resolveOutputDir(args.output_dir))
+                    ? await latestInteractionId(lookupOutputDir(args.output_dir))
                     // 'image' explicitly: video and music write records too, and a
                     // chained Lyria call is a documented 400. Resuming the wrong
                     // medium's chain is worse than not resuming.
@@ -274,7 +274,7 @@ export function registerInteractTools(server, client) {
                     // `<image>.json` sidecars; hosted it is the record beside each
                     // stored object. Same rule either way: no match, no guess.
                     const { refs: reanchorOn, carried } = onDisk
-                        ? await reanchorFromDisk(resolveOutputDir(args.output_dir), err.previousInteractionId)
+                        ? await reanchorFromDisk(lookupOutputDir(args.output_dir), err.previousInteractionId)
                         : await reanchorFromStore(client, err.previousInteractionId);
                     if (!reanchorOn.length)
                         throw err;

package/dist/tools/music.js

@@ -34,7 +34,7 @@ export function registerMusicTools(server, client) {
         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.`),
-            images: z.array(z.string().min(1)).optional().describe('Optional reference image path(s) to condition the music'),
+            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'),
             images_base64: imagesBase64Schema(),

package/dist/tools/set.js

@@ -20,7 +20,7 @@ export function registerSetTools(server, client) {
             count: z.number().int().positive().max(8).optional().describe('Number of variations of master_prompt (when scenes omitted)'),
             reference_mode: z.enum(['master', 'chain']).optional().describe('master: every image references the master (default). chain: each references the previous.'),
             basename: z.string().optional().describe('Base filename prefix for output images (default: slugified master_prompt)'),
-            master_images: z.array(z.string().min(1)).optional().describe('Reference image paths passed to the master generation call'),
+            master_images: z.array(z.string().min(1)).optional().describe('Reference image paths passed to the master generation call. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.'),
             master_images_url: imagesUrlSchema('Reference images passed to the master AND to every scene call (fetched once)'),
             master_images_file_uris: imagesFileUrisSchema('Reference images passed to the master AND to every scene call'),
             master_images_r2_keys: imagesR2KeysSchema('Reference images passed to the master AND to every scene call'),

package/dist/tools/video.js

@@ -45,7 +45,7 @@ export function registerVideoTools(server, client) {
             orientation: orientationSchema,
             task: z.enum(VIDEO_TASKS).optional().describe('text_to_video (default), image_to_video / reference_to_video (need image input), or edit / extend (need previous_interaction_id)'),
             resolution: z.enum(VIDEO_RESOLUTIONS).optional().describe('Output resolution (default 720p). Video is billed per output token, so 360p costs roughly a third of 720p — use it for drafts'),
-            images: z.array(z.string().min(1)).optional().describe('Reference image path(s) for image_to_video / reference_to_video'),
+            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'),
             images_base64: imagesBase64Schema(),

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "2.3.0",
+  "version": "2.3.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>",
@@ -46,13 +46,13 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.6.0",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@chrischall/mcp-utils": "^2.13.0",
+    "@modelcontextprotocol/server": "^2.2.0",
     "dotenv": "^18.0.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/client": "^2.2.0",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^5.0.0",
     "esbuild": "^0.28.0",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "2.3.0",
+  "version": "2.3.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "2.3.0",
+      "version": "2.3.1",
       "transport": {
         "type": "stdio"
       },
@@ -50,6 +50,13 @@
           "isRequired": false,
           "format": "string",
           "isSecret": false
+        },
+        {
+          "name": "GEMINI_REFERENCE_DIR",
+          "description": "Restrict local reference images (images / image paths sent to Gemini) to these directories (path.delimiter-separated), plus GEMINI_OUTPUT_DIR. Unset: GEMINI_UPLOAD_DIR applies; if that is unset too, unrestricted locally, and $MCP_DATA_DIR/uploads when MCP_DATA_DIR is set (hosted)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }