@chrischall/gemini-mcp 1.0.4 → 1.2.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.0.4",
+  "version": "1.2.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": "1.0.4",
+  "version": "1.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.0.4",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       },

package/skills/gemini-mcp/SKILL.md

@@ -91,20 +91,62 @@ 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
+
+These apply to **every** tool that takes a reference image: the four image tools, plus
+`gemini_video_generate` (reference stills) and `gemini_music_generate`.
+
+| 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 |
 |------|-------------|
-| `gemini_video_generate(prompt, aspect_ratio?, task?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, model?, filename?, output_dir?, timeout_ms?, idempotency_key?, async?)` | Generate a short video via the Gemini omni model: `text_to_video` (default), `image_to_video` / `reference_to_video` (supply reference image[s]), or `edit` (with `previous_interaction_id` / `continue_last`). `aspect_ratio` is `16:9` or `9:16`. Written to disk as **MP4**. Runs long — use `async: true` + `gemini_get_result`, or raise `timeout_ms`. |
-| `gemini_music_generate(prompt, model?, audio_format?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, filename?, output_dir?, inline?, timeout_ms?, idempotency_key?, async?)` | Generate music from a prompt (mood/genre/instruments/structure/lyrics) via a Lyria model: `lyria-3-clip-preview` (~30s, default) or `lyria-3-pro-preview` (longer, WAV-capable). `audio_format` `mp3` (default) or `wav` (**Pro-only**). Written to disk as MP3/WAV, or returned inline. |
+| `gemini_video_generate(prompt, aspect_ratio?, task?, images_url?, images_file_uris?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, model?, filename?, output_dir?, timeout_ms?, idempotency_key?, async?)` | Generate a short video via the Gemini omni model: `text_to_video` (default), `image_to_video` / `reference_to_video` (supply reference image[s]), or `edit` (with `previous_interaction_id` / `continue_last`). `aspect_ratio` is `16:9` or `9:16`. Written to disk as **MP4**. Runs long — use `async: true` + `gemini_get_result`, or raise `timeout_ms`. |
+| `gemini_music_generate(prompt, model?, audio_format?, images_url?, images_file_uris?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, filename?, output_dir?, inline?, timeout_ms?, idempotency_key?, async?)` | Generate music from a prompt (mood/genre/instruments/structure/lyrics) via a Lyria model: `lyria-3-clip-preview` (~30s, default) or `lyria-3-pro-preview` (longer, WAV-capable). `audio_format` `mp3` (default) or `wav` (**Pro-only**). Written to disk as MP3/WAV, or returned inline. |
 
 ### Async / idempotency (any generation tool)
 | Tool | Description |
@@ -131,6 +173,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(