@chrischall/gemini-mcp 1.4.0 → 1.5.0

package/dist/tools/uploads.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { UPLOAD_MAX_BYTES, RASTER_IMAGE_TYPE_PATTERN } from '../upload-url.js';
+import { wholeMb } from '../bytes.js';
+/**
+ * `gemini_get_upload_url` — mint a short-lived signed PUT URL so a shell can
+ * upload a reference image with ZERO auth headers:
+ *
+ *   curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "<upload_url>"
+ *
+ * This closes the last gap in the no-bytes-in-the-conversation story. The two
+ * existing byte routes each exclude a common caller: `images_base64` costs
+ * ~14k tokens per photo and corrupts silently on a truncated read, and
+ * `POST /upload` needs the MCP session's OAuth bearer token, which a sandboxed
+ * shell doesn't have. A signed URL is mintable by the session and usable by
+ * the shell.
+ *
+ * Hosted connector only — stdio has no HTTP surface to PUT against (and no
+ * need: it reads local paths directly). Gated on `client.uploadUrls`, the same
+ * pattern as `gemini_sign_media` / the library tools.
+ */
+export function registerUploadUrlTools(server, client) {
+    const minter = client.uploadUrls;
+    if (!minter)
+        return;
+    server.registerTool('gemini_get_upload_url', {
+        description: 'Mint a short-lived (~10 min) signed PUT URL for uploading one reference image to this connector with NO auth ' +
+            'headers — usable from any shell: curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "<upload_url>". ' +
+            'The response to the PUT returns an `r2_key` to reference the upload: pass it in `images_r2_keys` on generation ' +
+            'tools, save it permanently with gemini_save_character, or convert it to a ~48h Files API reference with ' +
+            'gemini_upload_file({ r2_key }). Prefer this over images_base64 (which costs ~14k tokens per photo) whenever the ' +
+            `caller has a shell. Images only, up to ${wholeMb(UPLOAD_MAX_BYTES)}MB.`,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: {
+            filename: z
+                .string()
+                .min(1)
+                .max(120)
+                .describe('Filename of the upload (e.g. "finn.jpg") — sanitized into the object key and the suggested curl command'),
+            content_type: z
+                .string()
+                // Raster only — image/svg+xml is a scriptable document and /media
+                // serves from the connector's own origin (see RASTER_IMAGE_TYPE_PATTERN).
+                .regex(RASTER_IMAGE_TYPE_PATTERN, 'must be a raster image MIME type like image/jpeg (SVG is not accepted)')
+                .describe('MIME type of the bytes that will be PUT — raster images only (jpeg/png/webp/gif/avif/heic/heif/bmp/tiff; not SVG). The PUT must send exactly this Content-Type.'),
+        },
+    }, async (args) => {
+        let minted;
+        try {
+            minted = await minter.mint(args.filename, args.content_type);
+        }
+        catch (err) {
+            throw new McpToolError(err instanceof Error ? err.message : String(err));
+        }
+        return textResult({
+            upload_url: minted.url,
+            method: 'PUT',
+            r2_key: minted.key,
+            content_type: minted.contentType,
+            expires_at: new Date(minted.expiresAtMs).toISOString(),
+            max_bytes: UPLOAD_MAX_BYTES,
+            curl_hint: `curl -sS -X PUT -H "Content-Type: ${minted.contentType}" --data-binary @${args.filename} "${minted.url}"`,
+            hint: 'PUT the raw bytes within ~10 minutes; no Authorization header is needed (the signature in the URL is the auth). ' +
+                'Then reference the returned r2_key: images_r2_keys on generation tools (master_images_r2_keys on gemini_image_set), ' +
+                'gemini_save_character to keep it with no expiry, or gemini_upload_file({ r2_key }) for a ~48h files/… reference. ' +
+                'Uploads themselves follow the media retention schedule (default 7 days).',
+        });
+    });
+}

package/dist/tools/video.js

@@ -3,7 +3,7 @@ import { McpToolError } from '@chrischall/mcp-utils';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_VIDEO_MODEL } from '../models.js';
-import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 /** omni's own aspect-ratio enum — NOT the image tools' ASPECT_RATIOS. */
@@ -44,6 +44,7 @@ export function registerVideoTools(server, client) {
             timeout_ms: timeoutMsSchema,
             idempotency_key: idempotencyKeySchema,
             async: asyncSchema,
+            max_wait_ms: maxWaitMsSchema,
             confirm: schemaConfirm,
         },
     }, async (args, extra) => {
@@ -69,7 +70,7 @@ export function registerVideoTools(server, client) {
             images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
             const { inputs, report } = await resolveImageInputs(args, client);
             const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client.generateVideo({
                 input: args.prompt,

package/dist/upload-url.js

@@ -0,0 +1,138 @@
+/**
+ * Short-lived signed PUT URLs — how reference bytes get INTO the connector
+ * without either base64 through the model's context or an OAuth bearer token.
+ *
+ * The problem these solve is the mirror image of `/media`: a signed GET lets a
+ * shell *download* generated media with no auth header, but uploading a
+ * reference photo still required `images_base64` (~14k tokens per JPEG, silently
+ * corrupting on a truncated read) or `POST /upload` (which 401s from any shell
+ * that doesn't hold the MCP session's bearer token). A signed PUT URL closes
+ * that gap: the authenticated MCP session mints it, and then a bare
+ * `curl -X PUT --data-binary @photo.jpg "<url>"` stores the bytes.
+ *
+ * Same HMAC secret as the media GET URLs, but a DIFFERENT payload shape, so the
+ * two kinds of signature can never be replayed across protocols:
+ *
+ *  - media GET signs   `<key>\n<exp>`             (media-url.ts — do not change;
+ *    every outstanding link was signed with that exact shape)
+ *  - upload PUT signs  `put\0<key>\0<ct>\0<exp>`  (NUL separators)
+ *
+ * A media payload always contains a `\n` and never a NUL (the sink sanitises
+ * every key segment it mints); an upload payload always contains NULs and
+ * never a `\n` — the endpoint refuses keys and content types outside a strict
+ * charset (no whitespace, no control characters) BEFORE verifying, so no
+ * crafted value can straddle a field boundary and no byte string is valid
+ * under both interpretations in either direction.
+ *
+ * The signature also covers the content type, so the uploaded object's stored
+ * MIME is exactly what the mint call declared — a URL minted for `image/jpeg`
+ * cannot be used to store `text/html`.
+ *
+ * Like media-url.ts, this module is WebCrypto-only and free of any Cloudflare
+ * import so it tests under Node.
+ */
+import { base64UrlEncode, base64UrlDecode } from './media-url.js';
+import { safeKeySegment } from './storage/media.js';
+/** How long a minted upload URL stays usable. Deliberately short — it exists to
+ * be curled within the same conversation turn that minted it. */
+export const UPLOAD_URL_TTL_MS = 10 * 60 * 1000;
+/** Upload size cap enforced by the PUT endpoint (while reading, not from the
+ * declared length alone). Matches the `images_url` fetch cap — a reference
+ * photo, not an archive. */
+export const UPLOAD_MAX_BYTES = 15 * 1024 * 1024;
+/** Key prefix for signed uploads: `up/<tenant>/<date>/<random>-<name>`. Swept
+ * by the retention cron like generated media (`gen/`); the character library
+ * (`lib/`) is where anything meant to be permanent gets copied. */
+export const UPLOAD_KEY_PREFIX = 'up';
+/**
+ * The bytes an upload signature covers: method, object key, content type,
+ * expiry. NUL separators, written as the \u0000 ESCAPE and never a literal NUL
+ * byte — a literal one makes git classify this whole file as binary and stop
+ * diffing it (the same trap as fingerprintRequest in jobs.ts, and exactly how
+ * this security-critical module briefly shipped unreviewable). No crafted
+ * value can straddle a field boundary: the endpoint enforces a control-free
+ * charset on the key and content type before verifying (see
+ * `wellFormedUploadKey` / `acceptableUploadType`).
+ */
+function payload(key, contentType, expiresAtMs) {
+    return new TextEncoder().encode(`put\u0000${key}\u0000${contentType.toLowerCase()}\u0000${expiresAtMs}`);
+}
+/** Sign one upload: this key, this content type, until `expiresAtMs`. */
+export async function signUploadKey(signingKey, key, contentType, expiresAtMs) {
+    return base64UrlEncode(await crypto.subtle.sign('HMAC', signingKey, payload(key, contentType, expiresAtMs)));
+}
+/**
+ * Check a `?ct=&exp=&sig=` triple against an object key. Same contract as
+ * `verifyMediaSignature`: constant-time comparison via `crypto.subtle.verify`,
+ * and signature validity is checked before expiry so a forgery is never
+ * confirmed as "merely expired".
+ */
+export async function verifyUploadSignature(signingKey, key, contentType, exp, sig, nowMs) {
+    if (!contentType || !exp || !sig)
+        return { ok: false, reason: 'missing' };
+    const expiresAtMs = Number(exp);
+    if (!Number.isFinite(expiresAtMs))
+        return { ok: false, reason: 'invalid' };
+    let valid;
+    try {
+        valid = await crypto.subtle.verify('HMAC', signingKey, base64UrlDecode(sig), payload(key, contentType, expiresAtMs));
+    }
+    catch {
+        return { ok: false, reason: 'invalid' };
+    }
+    if (!valid)
+        return { ok: false, reason: 'invalid' };
+    if (nowMs > expiresAtMs)
+        return { ok: false, reason: 'expired' };
+    return { ok: true };
+}
+/** `<base>/<key>?ct=…&exp=…&sig=…` — the URL handed back by the mint tool. */
+export function buildUploadUrl(baseUrl, key, contentType, expiresAtMs, signature) {
+    const path = key.split('/').map(encodeURIComponent).join('/');
+    return `${baseUrl.replace(/\/+$/, '')}/${path}?ct=${encodeURIComponent(contentType.toLowerCase())}&exp=${expiresAtMs}&sig=${signature}`;
+}
+/**
+ * RASTER image types only — an explicit allowlist, not `image/*`.
+ *
+ * The wildcard admitted `image/svg+xml`, and an SVG is a *document*: scripts
+ * inside it execute when a browser opens the `/media` link, which serves from
+ * the SAME ORIGIN as the connector's OAuth pages — stored XSS. Everything on
+ * this list is pure pixels, and it covers what Gemini accepts as reference
+ * input. `/media` also sends a no-script CSP as defense in depth, but the
+ * allowlist is the primary gate: don't widen it to a wildcard again.
+ *
+ * Shared by the mint tool's schema, the PUT endpoint, and the library's
+ * image sources (`gemini_save_character` / `_style`), so the gate cannot
+ * drift between the front door and the side doors.
+ */
+export const RASTER_IMAGE_TYPE_PATTERN = /^image\/(jpeg|png|webp|gif|avif|heic|heif|bmp|tiff)$/i;
+/** True for the MIME types a signed upload will store: raster images only. */
+export function acceptableUploadType(contentType) {
+    return RASTER_IMAGE_TYPE_PATTERN.test(contentType);
+}
+/**
+ * Build the minter. Keys are `up/<tenant>/<YYYY-MM-DD>/<random>-<safe-name>` —
+ * tenant-scoped at MINT time, which is what "scoped to the account that minted
+ * it" means mechanically: the signature only ever covers a key inside this
+ * session's own namespace, so a signed PUT cannot write into anyone else's.
+ */
+export function createUploadUrlMinter(opts) {
+    const now = opts.now ?? (() => new Date());
+    const randomId = opts.randomId ?? (() => crypto.randomUUID().slice(0, 8));
+    const ttlMs = opts.ttlMs ?? UPLOAD_URL_TTL_MS;
+    return {
+        async mint(filename, contentType) {
+            const ct = contentType.trim().toLowerCase();
+            if (!acceptableUploadType(ct)) {
+                throw new Error(`content_type must be a raster image type (image/jpeg, image/png, image/webp, image/gif, image/avif, image/heic, image/heif, image/bmp, image/tiff), got "${contentType}". ` +
+                    'SVG is deliberately not accepted: it can carry scripts, and /media serves from the connector origin.');
+            }
+            const tenant = typeof opts.tenant === 'function' ? await opts.tenant() : opts.tenant;
+            const day = now().toISOString().slice(0, 10);
+            const key = `${UPLOAD_KEY_PREFIX}/${tenant}/${day}/${randomId()}-${safeKeySegment(filename)}`;
+            const expiresAtMs = now().getTime() + ttlMs;
+            const signature = await opts.sign(key, ct, expiresAtMs);
+            return { url: buildUploadUrl(opts.baseUrl, key, ct, expiresAtMs, signature), key, contentType: ct, expiresAtMs };
+        },
+    };
+}

package/dist/version.js

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

package/dist/zip.js

@@ -0,0 +1,113 @@
+/**
+ * Minimal ZIP writer (STORE only, no compression) for bundling a multi-image
+ * result into one downloadable archive.
+ *
+ * Why hand-rolled: the Worker has no filesystem and no archiver dependency,
+ * and the images being bundled are already-compressed PNG/JPEG — DEFLATE would
+ * buy nothing. STORE entries are just headers + raw bytes + CRC32, which is
+ * ~100 lines and runs identically under Node and workerd.
+ *
+ * Layout: [local header + name + data]* [central directory]* [EOCD]. No
+ * ZIP64 (a bundle is a handful of images, far under the 4 GB / 65k-entry
+ * limits), no encryption, no streaming.
+ */
+/** Standard CRC-32 (IEEE 802.3), table-driven. The table is immutable. */
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+export function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** MS-DOS date/time pair (ZIP's native timestamp format). */
+function dosDateTime(at) {
+    const year = Math.max(1980, at.getUTCFullYear());
+    return {
+        time: (at.getUTCHours() << 11) | (at.getUTCMinutes() << 5) | (at.getUTCSeconds() >> 1),
+        date: ((year - 1980) << 9) | ((at.getUTCMonth() + 1) << 5) | at.getUTCDate(),
+    };
+}
+const LOCAL_HEADER = 0x04034b50;
+const CENTRAL_HEADER = 0x02014b50;
+const EOCD = 0x06054b50;
+/** Version 2.0 — the minimum that understands STORE + directories. */
+const VERSION = 20;
+/** General-purpose bit 11: names are UTF-8. */
+const FLAG_UTF8 = 0x0800;
+/**
+ * Build a STORE-only zip. `modifiedAt` stamps every entry (injectable so a
+ * given input always produces identical bytes; defaults to the epoch of the
+ * format, 1980).
+ */
+export function buildZip(entries, modifiedAt = new Date(Date.UTC(1980, 0, 1))) {
+    const { time, date } = dosDateTime(modifiedAt);
+    const encoder = new TextEncoder();
+    const parts = [];
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = encoder.encode(entry.name);
+        const crc = crc32(entry.bytes);
+        const size = entry.bytes.byteLength;
+        const local = new Uint8Array(30 + name.byteLength);
+        const lv = new DataView(local.buffer);
+        lv.setUint32(0, LOCAL_HEADER, true);
+        lv.setUint16(4, VERSION, true);
+        lv.setUint16(6, FLAG_UTF8, true);
+        lv.setUint16(8, 0, true); // method: STORE
+        lv.setUint16(10, time, true);
+        lv.setUint16(12, date, true);
+        lv.setUint32(14, crc, true);
+        lv.setUint32(18, size, true); // compressed == uncompressed under STORE
+        lv.setUint32(22, size, true);
+        lv.setUint16(26, name.byteLength, true);
+        lv.setUint16(28, 0, true); // extra length
+        local.set(name, 30);
+        const dir = new Uint8Array(46 + name.byteLength);
+        const dv = new DataView(dir.buffer);
+        dv.setUint32(0, CENTRAL_HEADER, true);
+        dv.setUint16(4, VERSION, true); // version made by
+        dv.setUint16(6, VERSION, true); // version needed
+        dv.setUint16(8, FLAG_UTF8, true);
+        dv.setUint16(10, 0, true);
+        dv.setUint16(12, time, true);
+        dv.setUint16(14, date, true);
+        dv.setUint32(16, crc, true);
+        dv.setUint32(20, size, true);
+        dv.setUint32(24, size, true);
+        dv.setUint16(28, name.byteLength, true);
+        // extra len, comment len, disk start, internal attrs, external attrs = 0
+        dv.setUint32(42, offset, true);
+        dir.set(name, 46);
+        parts.push(local, entry.bytes);
+        central.push(dir);
+        offset += local.byteLength + size;
+    }
+    const centralSize = central.reduce((n, c) => n + c.byteLength, 0);
+    const eocd = new Uint8Array(22);
+    const ev = new DataView(eocd.buffer);
+    ev.setUint32(0, EOCD, true);
+    ev.setUint16(8, entries.length, true); // entries on this disk
+    ev.setUint16(10, entries.length, true); // entries total
+    ev.setUint32(12, centralSize, true);
+    ev.setUint32(16, offset, true); // central directory offset
+    // comment length = 0
+    const total = offset + centralSize + eocd.byteLength;
+    const out = new Uint8Array(total);
+    let cursor = 0;
+    for (const part of [...parts, ...central, eocd]) {
+        out.set(part, cursor);
+        cursor += part.byteLength;
+    }
+    return out;
+}

package/package.json

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

package/server.json

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