@chrischall/gemini-mcp 1.0.3 → 1.1.0

package/dist/tools/set.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
-import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { slugify, baseName } from '../images.js';
+import { resolveImageInputs } from '../inputs.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerSetTools(server, client) {
@@ -16,7 +17,9 @@ export function registerSetTools(server, client) {
             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'),
+            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_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs for master generation. Last resort: prefer master_images_url or master_images_file_uris, which keep image bytes out of the conversation'),
             confirm: schemaConfirm,
             ...sharedImageSchema,
         },
@@ -37,13 +40,30 @@ export function registerSetTools(server, client) {
             reference_mode: args.reference_mode, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search,
             master_images: args.master_images, master_images_base64: args.master_images_base64, from_clipboard: args.from_clipboard,
+            master_images_url: args.master_images_url, master_images_file_uris: args.master_images_file_uris,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_image_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const seed = pickSeed(args.seed);
             const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
             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 });
+            // 1. master (optionally seeded from reference images).
+            //
+            // Two resolutions, because the two groups have different lifetimes:
+            //
+            //  - `carried` — URL and Files API references. Fetched/uploaded ONCE for
+            //    the whole set (a URL repeated across master + N scenes is one
+            //    download, and a `files/…` reference costs nothing to repeat), and
+            //    passed to EVERY scene call, where they do the most good: they are
+            //    what keeps the subject consistent scene to scene.
+            //  - `masterOnly` — path / base64 / clipboard references. Master-only,
+            //    exactly as before these parameters existed, so pre-existing calls
+            //    still build byte-identical requests.
+            const carried = await resolveImageInputs({ images_url: args.master_images_url, images_file_uris: args.master_images_file_uris }, client);
+            const masterOnly = await resolveImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard }, client);
+            const masterRefInputs = [...masterOnly.inputs, ...carried.inputs];
+            const report = carried.report || masterOnly.report
+                ? { ...masterOnly.report, ...carried.report }
+                : undefined;
             const named = [];
             const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
                 const result = await client.generate({
@@ -62,13 +82,13 @@ export function registerSetTools(server, client) {
                 if (mode === 'chain') {
                     let ref = master;
                     for (let i = 0; i < scenePrompts.length; i++) {
-                        const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref], seed: seed + i + 1, ...cfg });
+                        const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], 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, i) => client.generate({ prompt: p, images: [master], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
+                    const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master, ...carried.inputs], 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 result;
@@ -79,6 +99,8 @@ export function registerSetTools(server, client) {
                 meta.text = masterText;
             if (masterResult.grounding)
                 meta.grounding = masterResult.grounding;
+            if (report)
+                meta.image_inputs = report;
             // A set is master + N scenes in one tools/call — the most timeout-prone
             // tool. Effective image count drives the risk hint.
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client.mediaSink?.persistsFiles });

package/dist/tools/shared.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { textResult, McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveVideoPath, videoMimeType } from '../images.js';
+import { IMAGE_URL_MAX_BYTES } from '../fetch-image.js';
 import { createDiskSink } from '../storage/media.js';
 /**
  * Fallback sink for call sites that pass no explicit one (every pre-existing
@@ -52,6 +53,31 @@ export const asyncSchema = z
     .boolean()
     .optional()
     .describe('Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion).');
+/**
+ * Reference images the SERVER fetches, so the bytes never pass through the
+ * model's context window. Defined once and reused under both the `images_url`
+ * and `master_images_url` names.
+ */
+export function imagesUrlSchema(label = 'Reference images') {
+    return z
+        .array(z.string().url())
+        .optional()
+        .describe(`${label} as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. ` +
+        'Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. ' +
+        `Max ${Math.round(IMAGE_URL_MAX_BYTES / (1024 * 1024))}MB each; must be a directly-linked image (Content-Type image/*).`);
+}
+/**
+ * Reference images already in the Gemini Files API. The cheapest form there is:
+ * a short string, reusable across calls until the file expires.
+ */
+export function imagesFileUrisSchema(label = 'Reference images') {
+    return z
+        .array(z.string().min(1))
+        .optional()
+        .describe(`${label} by Gemini Files API reference ("files/<id>", or the full uri) from gemini_upload_file or POST /upload. ` +
+        'Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. ' +
+        'Files are retained ~48h, after which the reference stops resolving.');
+}
 /**
  * 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
@@ -271,10 +297,15 @@ export async function emit(named, opts, meta, onWritten) {
  *  - `video_path` — the Files API upload streams the file off disk.
  *
  * Called at the top of every generation handler, BEFORE any billable upstream
- * call, so a caller gets a clear "use images_base64 / video_url instead"
- * instead of an obscure module-resolution or ENOENT crash. A no-op on the disk
- * sink, so the stdio behaviour (including its own "Image not found" errors) is
- * untouched.
+ * call, so a caller gets a clear alternative instead of an obscure
+ * module-resolution or ENOENT crash. A no-op on the disk sink, so the stdio
+ * behaviour (including its own "Image not found" errors) is untouched.
+ *
+ * The remediation deliberately does NOT lead with `images_base64` any more.
+ * Inlining a photo as a tool argument costs ~14k tokens of the model's context
+ * and silently corrupts whenever the read that produced it was truncated — so
+ * it is named last, after the three routes that move bytes without the model
+ * ever seeing them.
  */
 export function assertLocalInputsAvailable(sink, args) {
     if ((sink ?? DEFAULT_SINK).persistsFiles)
@@ -293,8 +324,14 @@ export function assertLocalInputsAvailable(sink, args) {
     // Remediation goes in the MESSAGE, not just `hint`: MCP error serialization
     // surfaces the message and drops the hint, so hint-only advice is invisible
     // exactly when it is needed.
-    const fix = 'Send image bytes as `images_base64` (raw base64 or a data: URI) instead of `images`/`master_images`/`from_clipboard`, ' +
-        'and reference video by `video_url` (a public YouTube URL, or a files/… uri uploaded elsewhere) instead of `video_path`.';
+    const fix = 'Reference images WITHOUT putting bytes in the conversation, in order of preference: ' +
+        '(1) `images_url` — public https URLs the server fetches itself; ' +
+        '(2) `images_file_uris` — upload once with `gemini_upload_file` (it takes a `url` or `data_base64`) and reuse the returned files/… uri; ' +
+        '(3) `POST /upload` on this connector with the raw bytes as the body ' +
+        "(`curl -X POST <connector-url>/upload -H 'Authorization: Bearer <token>' -H 'Content-Type: image/jpeg' --data-binary @photo.jpg`), " +
+        'then pass the returned file_uri. ' +
+        'As a last resort `images_base64` still works, but it costs ~14k tokens per photo and breaks on a truncated read. ' +
+        'Reference video by `video_url` (a public YouTube URL, or a files/… uri uploaded elsewhere) instead of `video_path`.';
     throw new McpToolError(`${unavailable.join(', ')} ${unavailable.length > 1 ? 'are' : 'is'} unavailable on the hosted connector: ` +
         `it runs on a Cloudflare Worker, which has no filesystem and no local clipboard. ${fix}`, { hint: fix });
 }

package/dist/upload-endpoint.js

@@ -0,0 +1,79 @@
+/** Media the Files API is useful for. Anything else is a caller mistake. */
+const ACCEPTED_PREFIXES = ['image/', 'video/', 'audio/'];
+function json(body, status) {
+    return new Response(JSON.stringify(body, null, 2), {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8' },
+    });
+}
+/** Every error names the fix, because the caller here is a shell, not a model. */
+function fail(status, error, hint) {
+    return json({ error, hint }, status);
+}
+/**
+ * Build the `/upload` route handler. `buildClient` is injected rather than
+ * imported so the Worker can construct a client from *this request's* OAuth
+ * props (never a shared singleton — see the cross-tenant note in session.ts),
+ * and so tests can drive the whole handler against a stub client.
+ */
+export function createUploadHandler(buildClient) {
+    return async function handleUpload(request, ctx) {
+        if (request.method === 'OPTIONS') {
+            return new Response(null, { status: 204, headers: { allow: 'POST, OPTIONS' } });
+        }
+        if (request.method !== 'POST') {
+            return fail(405, `Method ${request.method} not allowed on /upload.`, 'POST the raw file bytes as the request body.');
+        }
+        // The OAuth provider populates props from the validated bearer token. Its
+        // absence means the route was reached some other way — refuse rather than
+        // fall back to an ambient key, which on a multi-tenant Worker would bill an
+        // unauthenticated upload to whoever configured the environment.
+        const apiKey = ctx.props?.apiKey;
+        if (typeof apiKey !== 'string' || !apiKey) {
+            return fail(401, 'Unauthenticated.', 'Send the same Authorization: Bearer <access-token> you use for the /mcp endpoint.');
+        }
+        const contentType = (request.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+        if (!ACCEPTED_PREFIXES.some((p) => contentType.startsWith(p))) {
+            return fail(415, `Unsupported Content-Type "${contentType || '(none)'}".`, 'Set Content-Type to the file\'s media type, e.g. -H "Content-Type: image/jpeg".');
+        }
+        const declared = request.headers.get('content-length');
+        const contentLength = Number(declared);
+        if (!declared || !Number.isFinite(contentLength) || contentLength <= 0) {
+            return fail(411, 'Content-Length is required (and must be > 0).', 'The Files API resumable upload declares the size up front, so the body cannot be sent chunked. ' +
+                'curl sets this automatically with --data-binary @file.');
+        }
+        const body = request.body;
+        if (!body) {
+            return fail(400, 'Request had no body.', 'Send the file bytes as the request body, e.g. --data-binary @photo.jpg.');
+        }
+        try {
+            const file = await buildClient(apiKey).uploadStream(body, contentType, displayNameFor(request, contentType), contentLength);
+            return json({
+                file_uri: file.name,
+                uri: file.uri,
+                name: file.name,
+                mime_type: file.mimeType,
+                ...(file.sizeBytes ? { size_bytes: Number(file.sizeBytes) } : {}),
+                expires: file.expirationTime ?? '~48h from upload',
+                hint: `Pass "${file.name}" as images_file_uris (or video_url) on any image tool. Gemini retains it ~48h.`,
+            }, 201);
+        }
+        catch (err) {
+            // Upstream failures are the interesting case here (bad key, quota, a file
+            // over the 2 GB cap), so the message is passed through rather than
+            // flattened into "upload failed".
+            const message = err instanceof Error ? err.message : String(err);
+            return fail(502, `Upload to the Gemini Files API failed: ${message}`, 'Check the API key on this connection is still valid and funded.');
+        }
+    };
+}
+/**
+ * A display name for the upload: an explicit `?name=` wins, else the
+ * `X-Filename` header (what a wrapper script would send), else the media type.
+ * Cosmetic — the Files API keys on the returned resource name, not this.
+ */
+function displayNameFor(request, contentType) {
+    const fromQuery = new URL(request.url).searchParams.get('name');
+    const raw = fromQuery ?? request.headers.get('x-filename') ?? `upload.${contentType.split('/')[1] || 'bin'}`;
+    return raw.replace(/[^\w.\-]+/g, '-').slice(0, 120) || 'upload';
+}

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.0.3",
+  "version": "1.1.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>",
@@ -55,13 +55,13 @@
     "zod": "^4.4.2"
   },
   "devDependencies": {
-    "@chrischall/mcp-connector": "^1.0.0",
+    "@chrischall/mcp-connector": "^1.1.1",
     "@cloudflare/vitest-pool-workers": "^0.18.6",
     "@cloudflare/workers-oauth-provider": "^0.8.2",
     "@cloudflare/workers-types": "^5.20260719.1",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.2",
-    "agents": "^0.17.4",
+    "agents": "^0.19.0",
     "esbuild": "^0.28.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.2",

package/server.json

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

package/skills/gemini-mcp/SKILL.md

@@ -91,14 +91,53 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 ### Image Generation
 | Tool | Description |
 |------|-------------|
-| `gemini_image_generate(prompt, count?, images?, images_base64?, video_url?, video_path?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Generate image(s) from a text prompt (optionally image-conditioned via `images`/`images_base64`, or video-conditioned via `video_url`/`video_path`) |
-| `gemini_image_edit(prompt, images?, images_base64?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Edit or compose input image(s) — by **path** (`images`) or **value** (`images_base64`: data URI or raw base64) — with a text instruction. Requires ≥1 input |
-| `gemini_image_set(master_prompt, scenes? \| count?, reference_mode?, master_images?, master_images_base64?, google_search?, seed?, basename?, model?, thinking_level?, ...)` | Master image (optionally seeded from a reference photo) plus N consistent images referencing it |
+| `gemini_image_generate(prompt, count?, images_url?, images_file_uris?, images?, images_base64?, video_url?, video_path?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Generate image(s) from a text prompt (optionally image-conditioned — see **Reference images** below — or video-conditioned via `video_url`/`video_path`) |
+| `gemini_image_edit(prompt, images_url?, images_file_uris?, images?, images_base64?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Edit or compose input image(s) with a text instruction. Requires ≥1 input from any of the four reference forms |
+| `gemini_image_set(master_prompt, scenes? \| count?, reference_mode?, master_images_url?, master_images_file_uris?, master_images?, master_images_base64?, google_search?, seed?, basename?, model?, thinking_level?, ...)` | Master image (optionally seeded from a reference photo) plus N consistent images referencing it. `master_images_url` / `master_images_file_uris` are resolved **once** and passed to the master *and* every scene |
+
+### Reference images — four ways in, one that costs context
+
+| Parameter | Where the bytes travel | Context cost |
+|---|---|---|
+| `images_url` (`master_images_url`) | the **server** downloads the https URL | none |
+| `images_file_uris` (`master_images_file_uris`) | a `files/<id>` reference from `gemini_upload_file` | none |
+| `images` | read off local disk (stdio builds only) | none |
+| `images_base64` | **through the tool-call JSON** | **~14k tokens per JPEG** |
+
+**Reach for `images_base64` last.** It costs ~14k tokens per modest photo, and a truncated file
+read produces base64 that still *looks* valid — so the corruption surfaces as a bad generation,
+not an error.
+
+- `images_url` accepts public `https://` URLs only (private/loopback/link-local hosts refused,
+  every redirect revalidated), must be `Content-Type: image/*`, capped at 15MB. Errors name the
+  failing URL. Over 6MB is auto-uploaded to the Files API instead of inlined.
+- `images_file_uris` accepts `files/<id>` or the full uri. Retained **~48h**; reusable across
+  any number of calls until then.
+- On stdio, an `images` path referenced **more than once in a session** is auto-uploaded to the
+  Files API (keyed on path + mtime + size) so the bytes stop being re-sent.
+
+### Files API
+| Tool | Description |
+|------|-------------|
+| `gemini_upload_file(url? \| data_base64? \| path?, mime_type?, display_name?, confirm?)` | Upload once, get a reusable `files/<id>`. Exactly one source. `url` is fetched by the server (image/video/audio, ≤100MB); `path` is stdio-only and confirm-gated; `data_base64` is the last resort |
+| `gemini_list_files(page_size?)` | List current uploads with MIME types and expiry |
+| `gemini_delete_file(file_uri, confirm)` | Delete an upload before its ~48h expiry |
+
+On the **hosted connector** there is also `POST /upload`, behind the same OAuth token as
+`/mcp` — the zero-base64 path for an agent with a shell:
+
+```bash
+curl -X POST https://<connector>/upload \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H "Content-Type: image/jpeg" \
+  --data-binary @photo.jpg
+# → {"file_uri":"files/abc123", ...}   then: images_file_uris: ["files/abc123"]
+```
 
 ### Multi-turn (Interactions API)
 | Tool | Description |
 |------|-------------|
-| `gemini_interact(input, previous_interaction_id?, continue_last?, images?, images_base64?, video_url?, video_path?, google_search?, search_types?, model?, aspect_ratio?, image_size?, thinking_level?, filename?, output_dir?, inline?)` | **Preferred tool for iterative refinement.** Generate/edit via Gemini's **Interactions API**. Returns an `interaction_id`; pass it back as `previous_interaction_id` (or set `continue_last: true` to reuse the session's most recent one) to **iteratively refine the same image** conversationally — do NOT start a new interaction or re-upload the image per tweak. Output is **JPEG**. |
+| `gemini_interact(input, previous_interaction_id?, continue_last?, images_url?, images_file_uris?, images?, images_base64?, video_url?, video_path?, google_search?, search_types?, model?, aspect_ratio?, image_size?, thinking_level?, filename?, output_dir?, inline?)` | **Preferred tool for iterative refinement.** Generate/edit via Gemini's **Interactions API**. Returns an `interaction_id`; pass it back as `previous_interaction_id` (or set `continue_last: true` to reuse the session's most recent one) to **iteratively refine the same image** conversationally — do NOT start a new interaction or re-upload the image per tweak. Output is **JPEG**. |
 
 ### Video & Music (preview — funded account)
 | Tool | Description |
@@ -131,6 +170,23 @@ gemini_image_edit(prompt: "make the background blue", images: ["/path/to/image.p
 → returns path to edited PNG
 ```
 
+**Edit an image you only have a URL for (nothing downloads into the conversation):**
+```
+gemini_image_edit(prompt: "make the background blue", images_url: ["https://example.com/photo.jpg"])
+→ the server fetches the URL itself; returns path to edited PNG
+```
+
+**Reuse one photo across many generations (hosted connector, agent with a shell):**
+```
+$ curl -X POST https://<connector>/upload -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: image/jpeg" --data-binary @photo.jpg
+  → {"file_uri": "files/abc123"}
+
+gemini_image_edit(prompt: "make it winter",  images_file_uris: ["files/abc123"])
+gemini_image_edit(prompt: "make it sunrise", images_file_uris: ["files/abc123"])
+→ two edits, one upload, zero image bytes in context. Valid ~48h.
+```
+
 **Generate a consistent set (master + scenes):**
 ```
 gemini_image_set(