@chrischall/gemini-mcp 1.3.0 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
-    "version": "1.3.0"
+    "version": "1.5.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Gemini Images",
       "source": "./",
       "description": "Generate and edit images with Google Gemini image models (Nano Banana / Nano Banana Pro) via natural language prompts",
-      "version": "1.3.0",
+      "version": "1.5.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gemini-mcp",
   "displayName": "Gemini Images",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -86,6 +86,19 @@ progress), two guards make re-issuing safe and unnecessary:
 | `gemini_upload_file` | Upload an image (or video/audio) to the Gemini Files API once — from a `url`, `data_base64`, or a local `path` — and get a reusable `files/<id>` reference |
 | `gemini_list_files` | List the files currently uploaded under this API key, with MIME types and expiry times |
 | `gemini_delete_file` | Delete an uploaded file before its ~48h expiry (confirm-gated) |
+| `gemini_sign_media` | *(hosted connector only)* Mint a fresh signed URL for generated media from its `r2_key` — an expired link is not a dead end |
+| `gemini_get_upload_url` | *(hosted connector only)* Mint a short-lived signed PUT URL so a shell can upload a reference image with no auth header; the PUT returns an `r2_key` usable in `images_r2_keys`, `gemini_save_character`, or `gemini_upload_file` |
+| `gemini_save_character` / `gemini_list_characters` / `gemini_delete_character` | *(hosted connector only)* Persistent per-account character library: save a reference image + description under a name, then pass `characters: ["name"]` on generation tools. No expiry |
+| `gemini_save_style` / `gemini_list_styles` / `gemini_delete_style` | *(hosted connector only)* Persistent per-account style presets: a reusable prompt fragment (optionally with a reference image), applied by passing `style: "name"` on generation tools. No expiry |
+
+Generation tools also share three throughput/latency controls: `async: true` (return a `job_id`
+immediately), `max_wait_ms` (wait up to a budget, then hand back the `job_id` — fast results stay
+in-band, slow batches never trip the host timeout), and `idempotency_key` (a retry returns the
+recorded result instead of re-billing). On the hosted connector, a `gemini_image_set` result with
+more than one image also carries a **`bundle_url`** — one signed URL for a zip of every image in
+the set — and set links are signed for ~7 days instead of the default ~48h. (A set too large to
+zip safely in Worker memory skips the bundle and says so via `bundle_skipped`; the per-image
+links are unaffected.)
 
 ## Seeing your images (hosted connector)
 
@@ -96,13 +109,22 @@ something you can *open*. It does: **every result includes a URL**, with no conf
 {
   "images": ["https://connector.example.com/media/gen/2026-07-29/ab12cd34-a-cat.png?exp=…&sig=…"],
   "media":  [{ "url": "https://…", "r2_key": "gen/2026-07-29/ab12cd34-a-cat.png",
-               "expires_at": "2026-07-31T12:00:00.000Z" }]
+               "expires_at": "2026-07-31T12:00:00.000Z",
+               "curl_hint": "curl -sS -o a-cat.png \"https://…\"" }]
 }
 ```
 
 Those links need no auth header — the signature is in the URL — so they work in a browser, in
 `curl`, and in a chat message. They expire (48h by default) and the objects behind them are
-swept on a retention schedule.
+swept on a retention schedule. The `r2_key` is the durable handle for that window:
+
+- **`gemini_sign_media`** (hosted connector only) mints a fresh signed URL from an `r2_key`,
+  so an expired link never forces you to re-generate — and re-pay for — the image.
+- **`gemini_upload_file` with `r2_key`** turns media the connector generated into a Files API
+  reference (the connector reads its own bucket — no HTTP round trip, no signature needed), so
+  a generated image can become the reference image for the next generation in one cheap call.
+- Idempotent replays (`idempotency_key`) re-mint the URLs inside the recorded result before
+  returning it, so a reused result never carries a dead link.
 
 **Why this matters:** MCP's inline image content blocks (`inline: true`) are visible to the
 *assistant* but many chat clients never render them to the user, and the assistant cannot
@@ -140,7 +162,7 @@ safe form, and a markdown link is a reasonable enhancement where you know it ren
 
 | Variable | Default | Effect |
 |---|---|---|
-| `MEDIA_TTL_DAYS` | `7` | Objects older than this are deleted by a daily cron (both the current `gen/` prefix and the legacy `media/` one) |
+| `MEDIA_TTL_DAYS` | `7` | Objects older than this are deleted by a daily cron — generated media (`gen/`, legacy `media/`) and signed uploads (`up/`). The character/style library (`lib/`) is exempt: saved entries never expire |
 | `MEDIA_URL_SECRET` | generated | HMAC key for `/media` links; rotate to revoke all outstanding URLs |
 | `MEDIA_PUBLIC_BASE_URL` | unset | Serve from R2 directly instead of the Worker route |
 
@@ -157,7 +179,9 @@ Every tool that takes a reference image — `gemini_image_generate`, `gemini_ima
 |---|---|---|
 | `images_url` (`master_images_url`) | the **server** downloads the https URL | none |
 | `images_file_uris` (`master_images_file_uris`) | a `files/<id>` reference, already uploaded | none |
+| `images_r2_keys` (`master_images_r2_keys`) | the connector reads its **own store** (hosted connector only) | none |
 | `images` | read off local disk (stdio builds only) | none |
+| `characters` / `style` | saved library entries, attached by name (hosted connector only) | none |
 | `images_base64` | **through the tool-call JSON** | **~14k tokens per JPEG** |
 
 `images_base64` is the fallback of last resort. It costs roughly 14k tokens per modest photo,
@@ -218,6 +242,55 @@ straight to the Files API (nothing is buffered), so `Content-Length` is required
 automatically with `--data-binary @file`. Accepted content types are `image/*`, `video/*` and
 `audio/*`; an optional `?name=` or `X-Filename` header sets the display name.
 
+### Signed upload URLs — no token at all (hosted connector)
+
+`POST /upload` needs the MCP session's OAuth bearer token, which a sandboxed shell often does
+not have. `gemini_get_upload_url` closes that gap: the authenticated MCP session mints a
+short-lived (~10 min) signed **PUT** URL, and the shell uploads with zero auth headers — the
+signature in the URL is the authorization, mirroring how `/media` downloads work.
+
+```bash
+# 1. tool call: gemini_get_upload_url { filename: "photo.jpg", content_type: "image/jpeg" }
+#    → { upload_url, r2_key, expires_at, curl_hint }
+
+# 2. shell:
+curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "$UPLOAD_URL"
+# → { "r2_key": "up/<tenant>/2026-07-31/ab12cd34-photo.jpg", "size_bytes": 812345, ... }
+```
+
+The signature covers one tenant-scoped object key, the declared content type and the expiry;
+uploads are capped at 15MB, enforced while reading the stream. Only **raster** image types are
+accepted (jpeg/png/webp/gif/avif/heic/heif/bmp/tiff) — SVG is deliberately refused, because an
+SVG is a scriptable document and `/media` serves from the connector's own origin. The returned
+`r2_key` is then usable three ways: directly as `images_r2_keys` on any generation tool (the
+server reads its own bucket — no bytes in the conversation), permanently via
+`gemini_save_character`, or as a ~48h Files API reference via `gemini_upload_file({ r2_key })`.
+Uploads themselves follow the media retention schedule (`up/` prefix, default 7 days).
+
+### Character & style library (hosted connector)
+
+Recurring subjects and styles can be saved once, per account, with **no expiry** (the retention
+cron deliberately skips the library's `lib/` prefix):
+
+```jsonc
+// once:
+{ "tool": "gemini_save_character", "name": "finn",
+  "description": "6-year-old boy, curly red hair", "image_r2_key": "up/…/photo.jpg" }
+{ "tool": "gemini_save_style", "name": "bold-cartoon-sports",
+  "prompt_fragment": "bold cartoon style, thick outlines, saturated colors" }
+
+// afterwards, on any generation:
+{ "tool": "gemini_image_set",
+  "master_prompt": "Finn on a soccer field",
+  "scenes": ["kicking the ball", "celebrating a goal"],
+  "characters": ["finn"], "style": "bold-cartoon-sports" }
+```
+
+Naming a character attaches its saved reference image and weaves its description into the
+prompt; naming a style appends its fragment (and attaches its reference image, if it has one).
+`gemini_image_set` passes character references to the master *and every scene call*, which is
+what keeps the subject consistent across the set.
+
 ## Quick Start
 
 ```json