@chrischall/gemini-mcp 0.2.0 → 0.4.0

package/dist/client.js

@@ -5,6 +5,7 @@ import { resolveModel, filterImageModels } from './models.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
 const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'; // v1 lacks gemini-3-pro-image; confirmed via Task 5
+const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions';
 const SERVICE = 'Gemini';
 export class GeminiClient {
     apiKey;
@@ -56,7 +57,10 @@ export class GeminiClient {
         for (const img of opts.images ?? []) {
             parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
         }
-        const generationConfig = { responseModalities: ['IMAGE'] };
+        if (opts.videoUrl) {
+            parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: 'video/mp4' } });
+        }
+        const generationConfig = { responseModalities: ['TEXT', 'IMAGE'] };
         if (opts.aspectRatio || opts.imageSize) {
             const imageConfig = {};
             if (opts.aspectRatio)
@@ -65,21 +69,134 @@ export class GeminiClient {
                 imageConfig.imageSize = opts.imageSize;
             generationConfig.imageConfig = imageConfig;
         }
-        const data = await this.call('POST', `/models/${model}:generateContent`, { contents: [{ parts }], generationConfig });
-        const out = [];
+        if (opts.seed !== undefined)
+            generationConfig.seed = opts.seed;
+        if (opts.thinkingLevel !== undefined)
+            generationConfig.thinkingConfig = { thinkingLevel: opts.thinkingLevel };
+        const requestBody = { contents: [{ parts }], generationConfig };
+        if (opts.googleSearch)
+            requestBody.tools = [{ google_search: {} }];
+        const data = await this.call('POST', `/models/${model}:generateContent`, requestBody);
+        const images = [];
+        const textParts = [];
+        let groundingMeta;
         for (const cand of data.candidates ?? []) {
             for (const part of cand.content?.parts ?? []) {
                 const inline = (part.inline_data ?? part.inlineData);
-                if (inline?.data)
-                    out.push({ base64: inline.data, mimeType: inline.mime_type ?? inline.mimeType ?? 'image/jpeg' });
+                if (inline?.data) {
+                    images.push({ base64: inline.data, mimeType: inline.mime_type ?? inline.mimeType ?? 'image/jpeg' });
+                }
+                else if (typeof part.text === 'string' && part.text.trim()) {
+                    textParts.push(part.text);
+                }
             }
+            if (cand.groundingMetadata)
+                groundingMeta = cand.groundingMetadata;
         }
-        if (out.length === 0) {
+        if (images.length === 0) {
             throw new McpToolError(`${SERVICE} returned no image`, {
                 hint: 'The request may have been blocked by safety filters — try rephrasing the prompt.',
             });
         }
-        return out;
+        const text = textParts.join('\n') || undefined;
+        // Parse grounding metadata if present
+        let grounding;
+        if (groundingMeta) {
+            const queries = (groundingMeta.webSearchQueries ?? []).filter(Boolean);
+            const sources = (groundingMeta.groundingChunks ?? []).map((c) => c.web).filter((w) => !!w);
+            if (queries.length > 0 || sources.length > 0) {
+                grounding = {};
+                if (queries.length > 0)
+                    grounding.queries = queries;
+                if (sources.length > 0)
+                    grounding.sources = sources;
+            }
+        }
+        return { images, text, grounding };
+    }
+    async interact(opts) {
+        const key = this.requireKey();
+        const model = resolveModel(opts.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        const inputParts = [{ type: 'text', text: opts.input }];
+        for (const img of opts.images ?? []) {
+            inputParts.push({ type: 'image', mime_type: img.mimeType, data: img.base64 });
+        }
+        if (opts.videoUrl) {
+            inputParts.push({ type: 'video', uri: opts.videoUrl, mime_type: 'video/mp4' });
+        }
+        const responseFormat = { type: 'image', mime_type: 'image/jpeg' };
+        if (opts.aspectRatio)
+            responseFormat.aspect_ratio = opts.aspectRatio;
+        if (opts.imageSize)
+            responseFormat.image_size = opts.imageSize;
+        const body = { model, input: inputParts, response_format: responseFormat };
+        if (opts.thinkingLevel !== undefined)
+            body.generation_config = { thinking_level: opts.thinkingLevel };
+        if (opts.previousInteractionId !== undefined)
+            body.previous_interaction_id = opts.previousInteractionId;
+        if (opts.googleSearch)
+            body.tools = [{ type: 'google_search' }];
+        const res = await this.fetchImpl(INTERACTIONS_URL, {
+            method: 'POST',
+            headers: {
+                'x-goog-api-key': key,
+                'content-type': 'application/json',
+                'Api-Revision': '2026-05-20',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            let message = text;
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed.error?.message)
+                    message = parsed.error.message;
+            }
+            catch { /* use raw text */ }
+            throw new McpToolError(`Gemini Interactions API ${res.status}: ${truncateErrorMessage(message)}`);
+        }
+        const data = await res.json();
+        // Only surface the `model_output` step — that's the caller-facing result.
+        // `thought` steps hold internal reasoning (and, with includeThoughts, draft
+        // "thinking" images); collecting those would leak reasoning into `text` and
+        // pollute the returned images. The verified contract puts the output image
+        // in `model_output`.
+        const images = [];
+        const textParts = [];
+        const searchQueries = [];
+        for (const step of data.steps ?? []) {
+            // Grounding queries live on the `google_search_call` step's arguments.
+            // (The `google_search_result` step only carries HTML `search_suggestions`
+            // chips — no clean source uri/title list like generateContent's
+            // groundingChunks — so interact surfaces queries only, not sources.)
+            if (step.type === 'google_search_call') {
+                for (const q of step.arguments?.queries ?? [])
+                    if (q?.trim())
+                        searchQueries.push(q);
+                continue;
+            }
+            if (step.type !== 'model_output')
+                continue;
+            for (const parts of [step.content ?? [], step.summary ?? []]) {
+                for (const part of parts) {
+                    if (part.type === 'image' && part.data) {
+                        images.push({ base64: part.data, mimeType: part.mime_type ?? 'image/jpeg' });
+                    }
+                    else if (part.type === 'text' && part.text?.trim()) {
+                        textParts.push(part.text);
+                    }
+                }
+            }
+        }
+        if (images.length === 0) {
+            throw new McpToolError('Gemini returned no image', {
+                hint: 'The request may have been blocked by safety filters — try rephrasing the prompt.',
+            });
+        }
+        const resultText = textParts.join('\n') || undefined;
+        const grounding = searchQueries.length > 0 ? { queries: searchQueries } : undefined;
+        return { id: data.id, images, text: resultText, grounding };
     }
 }
 /** Module-level singleton shared by every tool module (deferred-config-error). */

package/dist/clipboard.js

@@ -0,0 +1,67 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { McpToolError } from '@chrischall/mcp-utils';
+const execFileAsync = promisify(execFile);
+const defaultRun = async (cmd, args) => {
+    await execFileAsync(cmd, args);
+};
+/**
+ * Read the macOS system clipboard image into a base64 JPEG.
+ *
+ * Steps:
+ *  1. osascript: write clipboard PNG to a temp file.
+ *  2. sips: downscale + convert to JPEG (≤2048px, avoids 16-bit/large payloads).
+ *  3. Read the JPEG → base64.
+ *
+ * Temp files are cleaned up in a `finally` block.
+ */
+export async function readClipboardImage(run = defaultRun) {
+    if (process.platform !== 'darwin') {
+        throw new McpToolError('from_clipboard is only supported on macOS', {
+            hint: 'Save the image to a file and pass it via `images` instead.',
+        });
+    }
+    // Unique temp paths under tmpdir() — OS-controlled (/var/folders/…/T or /tmp on
+    // macOS), digits+alnum id, no user input. Commands run via execFile (no shell),
+    // so the only string-interpolated value (the path, in the AppleScript literal)
+    // can't reach a shell; a quote-bearing TMPDIR would just yield a parse error,
+    // caught as "No image found" below.
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const png = join(tmpdir(), `gemini-clip-${id}.png`);
+    const jpg = join(tmpdir(), `gemini-clip-${id}.jpg`);
+    try {
+        // Step 1: write clipboard PNG to temp file via osascript
+        try {
+            await run('osascript', [
+                '-e', `set f to (open for access POSIX file "${png}" with write permission)`,
+                '-e', 'write (the clipboard as «class PNGf») to f',
+                '-e', 'close access f',
+            ]);
+        }
+        catch {
+            throw new McpToolError('No image found on the clipboard', {
+                hint: 'Copy an image (⌘C) first, or pass `images`/`images_base64`.',
+            });
+        }
+        // Step 2: downscale + convert to JPEG via sips
+        try {
+            await run('sips', ['-Z', '2048', '-s', 'format', 'jpeg', png, '--out', jpg]);
+        }
+        catch {
+            throw new McpToolError('Failed to convert the clipboard image', {
+                hint: 'The clipboard may contain a non-standard image format.',
+            });
+        }
+        // Step 3: read JPEG → base64
+        const buf = await readFile(jpg);
+        return { base64: buf.toString('base64'), mimeType: 'image/jpeg' };
+    }
+    finally {
+        // Clean up both temp files (ignore errors if they don't exist)
+        await unlink(png).catch(() => undefined);
+        await unlink(jpg).catch(() => undefined);
+    }
+}

package/dist/images.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
-import { join } from 'node:path';
-import { readEnvVar } from '@chrischall/mcp-utils';
+import { existsSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { readEnvVar, McpToolError } from '@chrischall/mcp-utils';
 /** URL/file-safe slug from a prompt; never empty. */
 export function slugify(text, max = 40) {
     const s = text
@@ -30,21 +31,116 @@ export async function uniquePath(dir, base, ext) {
     }
     return candidate;
 }
-/** Decode base64 image bytes and write to disk (creating dir). Returns the path. */
+/** Sniff MIME type from the first bytes of an image buffer. */
+function sniffMimeBytes(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 'image/png';
+}
+/** Decode base64 image bytes and write to disk (creating dir). Returns the absolute path. */
 export async function writeImage(dir, base, base64, mimeType) {
     await mkdir(dir, { recursive: true });
-    const ext = mimeType.includes('jpeg') ? 'jpg' : 'png';
+    const ext = mimeType.includes('jpeg') ? 'jpg' : mimeType.includes('webp') ? 'webp' : 'png';
     const path = await uniquePath(dir, base, ext);
     await writeFile(path, Buffer.from(base64, 'base64'));
-    return path;
+    return resolve(path);
+}
+/**
+ * Resolve an image path, checking (in order):
+ *  1. Absolute path that exists → returned as-is.
+ *  2. `GEMINI_INPUT_DIR` env var is set → look for `join(inputDir, p)`.
+ *  3. Relative to cwd → `resolve(p)`.
+ * Throws a helpful `McpToolError` if none are found.
+ */
+export function resolveImagePath(p) {
+    if (isAbsolute(p) && existsSync(p))
+        return p;
+    const inputDir = readEnvVar('GEMINI_INPUT_DIR');
+    if (inputDir) {
+        // NOTE: a `../`-bearing `p` can escape inputDir. Acceptable for a local,
+        // single-user MCP — the caller already has the user's own filesystem access.
+        const candidate = join(inputDir, p);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    const cwd = resolve(p);
+    if (existsSync(cwd))
+        return cwd;
+    const hint = 'Set GEMINI_INPUT_DIR to a directory containing your images, or pass an absolute path.';
+    throw new McpToolError(`Image not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ''), { hint });
 }
 /** Read an image file into `{ base64, mimeType }` for an inline_data part. */
 export async function readImageAsInline(path) {
-    const buf = await readFile(path);
-    const lower = path.toLowerCase();
-    const mimeType = lower.endsWith('.jpg') || lower.endsWith('.jpeg') ? 'image/jpeg' : 'image/png';
+    const resolved = resolveImagePath(path);
+    const buf = await readFile(resolved);
+    const mimeType = sniffMimeBytes(buf);
     return { base64: buf.toString('base64'), mimeType };
 }
+/**
+ * Accept either a data URI (`data:image/png;base64,XXXX`) or raw base64.
+ * For raw base64, MIME is sniffed from the decoded bytes.
+ */
+export function decodeImageInput(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith('data:')) {
+        // data:<mediatype>[;param=value…];base64,<data> — tolerate extra params
+        // (e.g. charset) between the type and the base64 marker. Don't silently
+        // fall through to the raw-base64 path: a malformed data URI would decode to
+        // garbage bytes and ship corrupted data to the API.
+        const marker = trimmed.indexOf(';base64,');
+        if (marker === -1) {
+            throw new Error(`Unsupported data URI (expected ;base64,<data>): ${trimmed.slice(0, 48)}…`);
+        }
+        // MIME runs from after "data:" to the first ';' (a param sep or the base64 marker).
+        const mimeType = trimmed.slice(5, trimmed.indexOf(';', 5)) || 'image/png';
+        return { mimeType, base64: trimmed.slice(marker + ';base64,'.length) };
+    }
+    // Raw base64 — sniff from decoded bytes
+    const buf = Buffer.from(trimmed, 'base64');
+    return { base64: trimmed, mimeType: sniffMimeBytes(buf) };
+}
+/** Load images from file paths (via readImageAsInline) and raw base64 strings (via decodeImageInput), paths first. */
+export async function loadImageInputs(paths = [], base64s = []) {
+    const fromPaths = await Promise.all(paths.map((p) => readImageAsInline(p)));
+    const fromBase64s = base64s.map((b) => decodeImageInput(b));
+    return [...fromPaths, ...fromBase64s];
+}
+/**
+ * Aggregate image inputs from all sources: clipboard (macOS only), file paths, and base64 strings.
+ * Clipboard image is prepended if `from_clipboard` is true.
+ */
+export async function gatherImageInputs(opts) {
+    // Only load the clipboard module when actually requested (keeps the child_process
+    // path off the default code path).
+    const clipboardImages = opts.from_clipboard
+        ? [await (await import('./clipboard.js')).readClipboardImage()]
+        : [];
+    const fileImages = await loadImageInputs(opts.images, opts.images_base64);
+    return [...clipboardImages, ...fileImages];
+}
+/** Caller-supplied filename → safe base name (no extension). */
+export function baseName(name) {
+    // Strip known image extensions
+    const stripped = name.replace(/\.(png|jpe?g|webp)$/i, '');
+    // Replace non-safe chars with hyphens, collapse repeats, trim edges
+    const safe = stripped
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return safe || 'image';
+}
 /** per-call → $GEMINI_OUTPUT_DIR → cwd. */
 export function resolveOutputDir(perCall) {
     return perCall?.trim() || readEnvVar('GEMINI_OUTPUT_DIR') || process.cwd();

package/dist/index.js

@@ -4,6 +4,7 @@ import { VERSION } from './version.js';
 import { registerModelTools } from './tools/models.js';
 import { registerGenerateTools } from './tools/generate.js';
 import { registerSetTools } from './tools/set.js';
+import { registerInteractTools } from './tools/interact.js';
 // The GeminiClient is a module-level singleton (imported by each tool module)
 // that defers its config error to the first request — so the server boots and
 // answers the host's install-time tools/list probe even without GEMINI_API_KEY.
@@ -11,5 +12,5 @@ await runMcp({
     name: 'gemini-mcp',
     version: VERSION,
     banner: '[gemini-mcp] This project was developed and is maintained by AI (Claude). Use at your own discretion.',
-    tools: [registerModelTools, registerGenerateTools, registerSetTools],
+    tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools],
 });

package/dist/tools/generate.js

@@ -1,7 +1,9 @@
 import { z } from 'zod';
+import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
+import { resolveModel } from '../models.js';
 import { client } from '../client.js';
-import { slugify, readImageAsInline } from '../images.js';
-import { emit, sharedImageSchema } from './shared.js';
+import { slugify, baseName, gatherImageInputs } from '../images.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta } from './shared.js';
 export function registerGenerateTools(server) {
     server.registerTool('gemini_generate_image', {
         description: 'Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro).',
@@ -9,40 +11,88 @@ export function registerGenerateTools(server) {
         inputSchema: {
             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_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs'),
+            video_url: z.string().url().optional().describe('Public YouTube URL as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
             ...sharedImageSchema,
         },
     }, async (args) => {
         const count = args.count ?? 1;
-        const slug = slugify(args.prompt);
+        const seed = pickSeed(args.seed);
+        const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
+        const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
         const named = [];
+        let capturedText;
+        // For count>1, surface the FIRST call's grounding (each call grounds
+        // independently; one representative set of sources beats concatenating N).
+        let capturedGrounding;
         for (let i = 0; i < count; i++) {
-            const [img] = await client.generate({
+            // Distinct seed per image (seed+0 for the single-image case == echoed seed)
+            // so count>1 yields N *different* images, not N duplicates.
+            const result = await client.generate({
                 prompt: args.prompt,
+                images: refInputs.length > 0 ? refInputs : undefined,
                 model: args.model,
                 aspectRatio: args.aspect_ratio,
                 imageSize: args.image_size,
+                seed: seed + i,
+                thinkingLevel: args.thinking_level,
+                googleSearch: args.google_search,
+                videoUrl: args.video_url,
             });
+            const { images: [img], text } = result;
+            if (text && !capturedText)
+                capturedText = text;
+            if (result.grounding && !capturedGrounding)
+                capturedGrounding = result.grounding;
             named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, '0')}` });
         }
-        return emit(named, args);
+        const meta = buildMeta(model, seed, args);
+        if (capturedText)
+            meta.text = capturedText;
+        if (capturedGrounding)
+            meta.grounding = capturedGrounding;
+        return emit(named, args, meta);
     });
     server.registerTool('gemini_edit_image', {
-        description: 'Edit or compose images: provide one image to edit, or multiple images to combine/blend, plus a text instruction.',
+        description: 'Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. ' +
+            'Gemini over-preserves the input; there is no edit-strength control — for large structural changes, reroll with a different `seed` or more forceful wording.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             prompt: z.string().min(1).describe('Instruction describing the edit or composition'),
-            images: z.array(z.string().min(1)).min(1).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)'),
+            images_base64: z.array(z.string().min(1)).optional().describe('Input images as base64 strings or data URIs'),
+            filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
             ...sharedImageSchema,
         },
     }, async (args) => {
-        const inputs = await Promise.all(args.images.map((p) => readImageAsInline(p)));
-        const [img] = await client.generate({
+        const hasPaths = (args.images?.length ?? 0) > 0;
+        const hasBase64 = (args.images_base64?.length ?? 0) > 0;
+        if (!hasPaths && !hasBase64 && !args.from_clipboard) {
+            throw new McpToolError('Provide at least one input image via `images`, `images_base64`, or `from_clipboard`.');
+        }
+        const seed = pickSeed(args.seed);
+        const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
+        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const result = await client.generate({
             prompt: args.prompt,
             images: inputs,
             model: args.model,
             aspectRatio: args.aspect_ratio,
             imageSize: args.image_size,
+            seed,
+            thinkingLevel: args.thinking_level,
+            googleSearch: args.google_search,
         });
-        return emit([{ image: img, base: slugify(args.prompt) }], args);
+        const { images: [img], text } = result;
+        const meta = buildMeta(model, seed, args);
+        if (text)
+            meta.text = text;
+        if (result.grounding)
+            meta.grounding = result.grounding;
+        return emit([{ image: img, base: slug }], args, meta);
     });
 }

package/dist/tools/interact.js

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { resolveModel } from '../models.js';
+import { client } from '../client.js';
+import { slugify, baseName, gatherImageInputs } from '../images.js';
+import { emit, ASPECT_RATIOS, IMAGE_SIZES } from './shared.js';
+export function registerInteractTools(server) {
+    server.registerTool('gemini_interact', {
+        description: "Multi-turn image generation/editing via Gemini's Interactions API (Beta). " +
+            'Returns an interaction `id`; pass it back as `previous_interaction_id` to iteratively ' +
+            'refine the SAME image conversationally (the recommended way to make incremental edits). ' +
+            'Output is JPEG.',
+        annotations: { readOnlyHint: false, openWorldHint: true },
+        inputSchema: {
+            input: z.string().min(1).describe('Text prompt or editing instruction'),
+            previous_interaction_id: z
+                .string()
+                .optional()
+                .describe('ID from a prior gemini_interact call — continues that multi-turn conversation'),
+            images: z
+                .array(z.string().min(1))
+                .optional()
+                .describe('Paths to reference input images'),
+            images_base64: z
+                .array(z.string().min(1))
+                .optional()
+                .describe('Reference images as base64 strings or data URIs'),
+            model: z
+                .string()
+                .optional()
+                .describe('Model id override (default: server default; see gemini_list_models)'),
+            aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
+            image_size: z
+                .enum(IMAGE_SIZES)
+                .optional()
+                .describe('Output resolution (512 = 0.5K, Flash-only)'),
+            thinking_level: z
+                .enum(['minimal', 'high'])
+                .optional()
+                .describe('Reasoning depth; higher can help complex/structural edits'),
+            filename: z
+                .string()
+                .optional()
+                .describe('Base filename for the output image (extension stripped; default: slugified input)'),
+            output_dir: z
+                .string()
+                .optional()
+                .describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
+            inline: z
+                .boolean()
+                .optional()
+                .describe('Return base64 images inline instead of writing to disk'),
+            google_search: z
+                .boolean()
+                .optional()
+                .describe('Ground the image in live Google Search results (current events, weather, data)'),
+            video_url: z
+                .string()
+                .url()
+                .optional()
+                .describe('Public YouTube URL as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
+            from_clipboard: z
+                .boolean()
+                .optional()
+                .describe('Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)'),
+        },
+    }, async (args) => {
+        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const r = await client.interact({
+            input: args.input,
+            images: inputs.length ? inputs : undefined,
+            model: args.model,
+            aspectRatio: args.aspect_ratio,
+            imageSize: args.image_size,
+            thinkingLevel: args.thinking_level,
+            previousInteractionId: args.previous_interaction_id,
+            googleSearch: args.google_search,
+            videoUrl: args.video_url,
+        });
+        const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        const meta = { model, interaction_id: r.id };
+        if (r.text)
+            meta.text = r.text;
+        if (r.grounding)
+            meta.grounding = r.grounding;
+        const slug = args.filename ? baseName(args.filename) : slugify(args.input);
+        const named = r.images.map((image, i) => ({
+            image,
+            base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
+        }));
+        return emit(named, args, meta);
+    });
+}

package/dist/tools/set.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
-import { McpToolError } from '@chrischall/mcp-utils';
+import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
+import { resolveModel } from '../models.js';
 import { client } from '../client.js';
-import { slugify } from '../images.js';
-import { emit, sharedImageSchema } from './shared.js';
+import { slugify, baseName, gatherImageInputs } from '../images.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta } from './shared.js';
 export function registerSetTools(server) {
     server.registerTool('gemini_generate_set', {
         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).',
@@ -12,6 +13,9 @@ export function registerSetTools(server) {
             scenes: z.array(z.string().min(1)).min(1).max(8).optional().describe('Per-image prompts (1-8); each references the master'),
             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_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs for master generation'),
             ...sharedImageSchema,
         },
     }, async (args) => {
@@ -19,26 +23,42 @@ export function registerSetTools(server) {
         if ((args.scenes && args.count) || (!args.scenes && !args.count)) {
             throw new McpToolError('Provide exactly one of `scenes` or `count`.');
         }
-        const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size };
-        const slug = slugify(args.master_prompt);
-        // 1. master
-        const [master] = await client.generate({ prompt: args.master_prompt, ...cfg });
+        const seed = pickSeed(args.seed);
+        const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search };
+        const slug = args.basename ? baseName(args.basename) : slugify(args.master_prompt);
+        // 1. master (optionally seeded from reference images)
+        const masterRefInputs = await gatherImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard });
+        const masterResult = await client.generate({
+            prompt: args.master_prompt,
+            images: masterRefInputs.length > 0 ? masterRefInputs : undefined,
+            seed,
+            ...cfg,
+        });
+        const { images: [master], text: masterText } = masterResult;
         const named = [{ image: master, base: `${slug}-master` }];
+        // Only the master's text is surfaced (below). Per-scene text is intentionally
+        // dropped — a set returns one combined result and merging N captions is noise.
         // 2. scene prompts (explicit, or N repeats of master_prompt for variations)
         const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
         const mode = args.reference_mode ?? 'master';
         if (mode === 'chain') {
             let ref = master;
             for (let i = 0; i < scenePrompts.length; i++) {
-                const [img] = await client.generate({ prompt: scenePrompts[i], images: [ref], ...cfg });
+                const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref], seed: seed + i + 1, ...cfg });
                 named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` });
                 ref = img;
             }
         }
         else {
-            const scenes = await Promise.all(scenePrompts.map((p) => client.generate({ prompt: p, images: [master], ...cfg }).then((r) => r[0])));
+            const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
             scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` }));
         }
-        return emit(named, args);
+        const meta = buildMeta(model, seed, args);
+        if (masterText)
+            meta.text = masterText;
+        if (masterResult.grounding)
+            meta.grounding = masterResult.grounding;
+        return emit(named, args, meta);
     });
 }