@chrischall/gemini-mcp 0.2.0 → 0.3.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/images.js

@@ -1,5 +1,5 @@
 import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { readEnvVar } from '@chrischall/mcp-utils';
 /** URL/file-safe slug from a prompt; never empty. */
 export function slugify(text, max = 40) {
@@ -30,21 +30,78 @@ 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);
 }
 /** 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 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];
+}
+/** 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, loadImageInputs } 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 loadImageInputs(args.images, args.images_base64);
         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) {
+            throw new McpToolError('Provide at least one input image via `images` or `images_base64`.');
+        }
+        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 loadImageInputs(args.images, args.images_base64);
+        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,89 @@
+import { z } from 'zod';
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { resolveModel } from '../models.js';
+import { client } from '../client.js';
+import { slugify, baseName, loadImageInputs } 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)'),
+        },
+    }, async (args) => {
+        const inputs = await loadImageInputs(args.images, args.images_base64);
+        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, loadImageInputs } 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 loadImageInputs(args.master_images, args.master_images_base64);
+        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);
     });
 }

package/dist/tools/shared.js

@@ -3,8 +3,8 @@ import { textResult } from '@chrischall/mcp-utils';
 import { writeImage, resolveOutputDir } from '../images.js';
 /** Supported output aspect ratios (Gemini image API). */
 export const ASPECT_RATIOS = ['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9', '1:4', '4:1', '1:8', '8:1'];
-/** Supported output resolutions. */
-export const IMAGE_SIZES = ['1K', '2K', '4K'];
+/** Supported output resolutions. `512` is Flash-only (0.5K); `1K`/`2K`/`4K` work on all image models. */
+export const IMAGE_SIZES = ['512', '1K', '2K', '4K'];
 /**
  * The model/aspect/size/output fields every generation tool shares. Defined once
  * here so descriptions can't drift between `generate.ts` and `set.ts`. Spread
@@ -13,23 +13,48 @@ export const IMAGE_SIZES = ['1K', '2K', '4K'];
 export const sharedImageSchema = {
     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'),
+    image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution (512 = 0.5K, Flash-only)'),
     output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
     inline: z.boolean().optional().describe('Return base64 images inline instead of writing to disk'),
+    seed: z.number().int().optional().describe('Seed for reproducible generation; random if omitted'),
+    thinking_level: z.enum(['minimal', 'high']).optional().describe('Reasoning depth (Gemini 3 models); higher can help complex/structural edits'),
+    google_search: z.boolean().optional().describe('Ground the image in live Google Search results (current events, weather, data)'),
 };
+/**
+ * Return the provided seed, or pick a random one. Capped well below INT32_MAX
+ * so derived per-image seeds (`seed + i`) can't overflow a 32-bit int.
+ */
+export function pickSeed(seed) {
+    return seed ?? Math.floor(Math.random() * 2_147_483_000);
+}
+/** Build the result metadata echoed to the caller (omitting unset optionals). */
+export function buildMeta(model, seed, opts) {
+    const meta = { model, seed };
+    if (opts.aspect_ratio)
+        meta.aspect_ratio = opts.aspect_ratio;
+    if (opts.image_size)
+        meta.image_size = opts.image_size;
+    return meta;
+}
 /**
  * Either return images inline (base64 content blocks) or write them to disk and
  * return their paths as a text result. `inline` wins when true.
+ * Optional `meta` is merged into the disk-path JSON result, or prepended as a
+ * text block in inline mode (only if meta has keys).
  */
-export async function emit(named, opts) {
+export async function emit(named, opts, meta) {
     if (opts.inline) {
-        return {
-            content: named.map((n) => ({ type: 'image', data: n.image.base64, mimeType: n.image.mimeType })),
-        };
+        const imageBlocks = named.map((n) => ({ type: 'image', data: n.image.base64, mimeType: n.image.mimeType }));
+        if (meta && Object.keys(meta).length > 0) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify(meta, null, 2) }, ...imageBlocks],
+            };
+        }
+        return { content: imageBlocks };
     }
     const dir = resolveOutputDir(opts.output_dir);
     const images = [];
     for (const n of named)
         images.push(await writeImage(dir, n.base, n.image.base64, n.image.mimeType));
-    return textResult({ images });
+    return textResult({ images, ...meta });
 }

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '0.2.0'; // x-release-please-version
+export const VERSION = '0.3.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "0.2.0",
+  "version": "0.3.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>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },