@chrischall/gemini-mcp 0.3.0 → 0.5.0

package/dist/client.js

@@ -1,16 +1,23 @@
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadDotenvSafely, readEnvVar, McpToolError, truncateErrorMessage } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, readEnvVar, McpToolError, createApiClient } from '@chrischall/mcp-utils';
 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';
+const INTERACTIONS_SERVICE = 'Gemini Interactions';
+// Required revision header for the beta Interactions API (verified 2026-06-08;
+// see docs/GEMINI-API.md) — load-bearing, requests 400 without it.
+const API_REVISION = '2026-05-20';
+// Per-request abort budget. Image generation routinely runs 30s+ on the Pro
+// model, so this is deliberately 60s (NOT the fleet's usual 15–30s).
+const REQUEST_TIMEOUT_MS = 60_000;
 export class GeminiClient {
     apiKey;
     configError;
-    fetchImpl;
+    api;
+    interactionsApi;
     constructor(opts = {}) {
         const key = readEnvVar('GEMINI_API_KEY');
         if (!key) {
@@ -23,7 +30,27 @@ export class GeminiClient {
             this.apiKey = key;
             this.configError = null;
         }
-        this.fetchImpl = opts.fetchImpl ?? fetch;
+        // Both paths share: the key in the `x-goog-api-key` header (Gemini does not
+        // use `Authorization: Bearer`), a 60s abort budget, and the default 429
+        // retry (once after 2s — the free tier rate-limits aggressively).
+        // `getToken` calls requireKey() so key resolution stays at REQUEST time:
+        // the server boots without a key and the actionable config error (with its
+        // aistudio hint) surfaces on the first tool call, not at startup.
+        const shared = {
+            tokenHeader: 'x-goog-api-key',
+            getToken: () => this.requireKey(),
+            timeout: REQUEST_TIMEOUT_MS,
+            fetchImpl: opts.fetchImpl ?? fetch,
+        };
+        this.api = createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared });
+        // Separate client for the beta Interactions API: same base URL, but every
+        // request must carry the Api-Revision header (and errors name the API).
+        this.interactionsApi = createApiClient({
+            baseUrl: BASE_URL,
+            serviceName: INTERACTIONS_SERVICE,
+            baseHeaders: { 'Api-Revision': API_REVISION },
+            ...shared,
+        });
     }
     requireKey() {
         if (this.configError)
@@ -35,17 +62,7 @@ export class GeminiClient {
         return resolveModel(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));
     }
     async call(method, path, body) {
-        const key = this.requireKey();
-        const res = await this.fetchImpl(`${BASE_URL}${path}`, {
-            method,
-            headers: { 'x-goog-api-key': key, 'content-type': 'application/json' },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
-        if (!res.ok) {
-            const text = await res.text().catch(() => '');
-            throw new McpToolError(`${SERVICE} API ${res.status}: ${truncateErrorMessage(text)}`);
-        }
-        return (await res.json());
+        return this.api.fetchJson(method, path, body !== undefined ? { body } : {});
     }
     async listModels() {
         const data = await this.call('GET', '/models?pageSize=200');
@@ -115,7 +132,6 @@ export class GeminiClient {
         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 ?? []) {
@@ -136,27 +152,9 @@ export class GeminiClient {
             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),
+        const data = await this.interactionsApi.fetchJson('POST', '/interactions', {
+            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

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, resolve } 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
@@ -56,9 +57,34 @@ export async function writeImage(dir, base, base64, mimeType) {
     await writeFile(path, Buffer.from(base64, 'base64'));
     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 resolved = resolveImagePath(path);
+    const buf = await readFile(resolved);
     const mimeType = sniffMimeBytes(buf);
     return { base64: buf.toString('base64'), mimeType };
 }
@@ -91,6 +117,19 @@ export async function loadImageInputs(paths = [], base64s = []) {
     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

package/dist/tools/generate.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
-import { slugify, baseName, loadImageInputs } from '../images.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', {
@@ -22,7 +22,7 @@ export function registerGenerateTools(server) {
         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 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
@@ -70,13 +70,13 @@ export function registerGenerateTools(server) {
     }, async (args) => {
         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`.');
+        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 loadImageInputs(args.images, args.images_base64);
+        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,

package/dist/tools/interact.js

@@ -2,7 +2,7 @@ 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 { slugify, baseName, gatherImageInputs } from '../images.js';
 import { emit, ASPECT_RATIOS, IMAGE_SIZES } from './shared.js';
 export function registerInteractTools(server) {
     server.registerTool('gemini_interact', {
@@ -59,9 +59,13 @@ export function registerInteractTools(server) {
                 .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 loadImageInputs(args.images, args.images_base64);
+        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,

package/dist/tools/set.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
-import { slugify, baseName, loadImageInputs } from '../images.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', {
@@ -28,7 +28,7 @@ export function registerSetTools(server) {
         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 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,

package/dist/tools/shared.js

@@ -11,7 +11,14 @@ export const IMAGE_SIZES = ['512', '1K', '2K', '4K'];
  * into each tool's `inputSchema`.
  */
 export const sharedImageSchema = {
-    model: z.string().optional().describe('Model id override (default: server default; see gemini_list_models)'),
+    // Bare id only: the model is interpolated into the URL path
+    // (`/models/${model}:generateContent`), so slashes/colons/queries must be
+    // rejected to keep a crafted value from escaping the path segment.
+    model: z
+        .string()
+        .regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")')
+        .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)'),
     output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
@@ -19,6 +26,7 @@ export const sharedImageSchema = {
     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)'),
+    from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)'),
 };
 /**
  * Return the provided seed, or pick a random one. Capped well below INT32_MAX

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "mcpName": "io.github.chrischall/gemini-mcp",
   "description": "Gemini image-generation MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -44,7 +44,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.6.0",
+    "@chrischall/mcp-utils": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "0.3.0",
+  "version": "0.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "0.3.0",
+      "version": "0.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -36,6 +36,13 @@
           "isRequired": false,
           "format": "string",
           "isSecret": false
+        },
+        {
+          "name": "GEMINI_INPUT_DIR",
+          "description": "Directory to resolve bare input-image filenames against",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }