@chrischall/gemini-mcp 1.0.4 → 1.2.0

package/dist/bytes.js

@@ -0,0 +1,46 @@
+/**
+ * base64 ↔ bytes, and byte-size formatting.
+ *
+ * These conversions had grown four near-identical copies — an inline
+ * `Uint8Array.from(atob(x), c => c.charCodeAt(0))` in `inputs.ts` and twice in
+ * `tools/files.ts`, plus a private `decodeBase64` in `storage/media.ts` — and
+ * a fifth (`encodeBase64`) that was subtly different because it is the only one
+ * that has to chunk. One place, so the chunking rule can't be forgotten in copy
+ * number six.
+ *
+ * `atob`/`btoa` rather than `Buffer`: this module is on the Worker's import
+ * graph, and they are the primitive both runtimes share. Module scope stays
+ * side-effect-free for the same reason (see the note in client.ts).
+ */
+/** Decode base64 into raw bytes. */
+export function base64ToBytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/**
+ * Encode raw bytes as base64.
+ *
+ * Chunked because `String.fromCharCode(...bytes)` spreads one argument per
+ * byte and blows the engine's argument limit somewhere around 100–125k — i.e.
+ * it works fine on every small test fixture and throws on the first real
+ * photo, which is the worst possible place to learn about it.
+ */
+export function bytesToBase64(bytes) {
+    const CHUNK = 0x8000;
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+/** Whole megabytes, for limits stated in tool descriptions (`25MB`). */
+export function wholeMb(bytes) {
+    return Math.round(bytes / (1024 * 1024));
+}
+/** One-decimal megabytes, for error messages about an actual size (`15.4 MB`). */
+export function formatMb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/dist/client.js

@@ -3,6 +3,7 @@ import { readEnvVar, McpToolError, ApiError, createApiClient, formatApiError, fi
 import { resolveModel, filterImageModels, DEFAULT_VIDEO_MODEL, DEFAULT_MUSIC_MODEL } from './models.js';
 import { createDiskSink } from './storage/media.js';
 import { SessionState } from './session.js';
+import { fetchRemoteImage } from './fetch-image.js';
 // NOTE: this module must stay SIDE-EFFECT-FREE at module scope — no I/O, no
 // top-level await, no `import.meta.url`. `src/worker.ts` imports it, so every
 // line here runs during Cloudflare isolate startup, where global-scope I/O is
@@ -96,6 +97,37 @@ export class ChainedRequest404Error extends McpToolError {
         this.retries = retries;
     }
 }
+/** `generateContent` part for one reference image (by uri, else inline). */
+function generatePart(img) {
+    return img.uri
+        ? { file_data: { file_uri: img.uri, mime_type: img.mimeType } }
+        : { inline_data: { mime_type: img.mimeType, data: img.base64 } };
+}
+/** Interactions `input` part for one reference image (by uri, else inline). */
+function interactPart(img) {
+    return img.uri
+        ? { type: 'image', uri: img.uri, mime_type: img.mimeType }
+        : { type: 'image', mime_type: img.mimeType, data: img.base64 };
+}
+/**
+ * Reduce any accepted spelling of a Files API reference to the bare resource
+ * name `files/<id>`.
+ *
+ * Callers hand these back and forth all day — a result echoes the full
+ * `https://…/v1beta/files/<id>` uri, docs and error messages say `files/<id>` —
+ * so both must work. The name is interpolated into a URL path, which is why the
+ * shape is asserted rather than assumed (same posture as the model-id guard).
+ */
+export function normalizeFileName(ref) {
+    const trimmed = ref.trim();
+    const match = /(?:^|\/)(files\/[\w-]+)\/?$/.exec(trimmed);
+    if (!match) {
+        throw new McpToolError(`Not a Gemini Files API reference: "${ref}"`, {
+            hint: 'Pass the `files/<id>` name (or the full https://…/v1beta/files/<id> uri) returned by gemini_upload_file / POST /upload.',
+        });
+    }
+    return match[1];
+}
 export class GeminiClient {
     /**
      * A key handed in explicitly (the connector's per-session key). When absent
@@ -184,6 +216,17 @@ export class GeminiClient {
         }
         return key;
     }
+    /**
+     * Fetch one `images_url` reference server-side. Routed through the client so
+     * it uses the SAME injected `fetchImpl` as every upstream call — which is
+     * what makes it mockable in tests and correct on the Worker.
+     */
+    async fetchRemoteImage(url, opts = {}) {
+        // Same timeout resolution as every other upstream call (per-call
+        // `timeout_ms` → $GEMINI_TIMEOUT_MS → 60s), so a URL fetch cannot be the
+        // one unbounded network operation in the server.
+        return fetchRemoteImage(url, { ...opts, fetchImpl: this.fetchImpl, timeoutMs: resolveTimeoutMs(opts.timeoutMs) });
+    }
     /** The default model after env override (no per-call arg). */
     defaultModel() {
         return resolveModel(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));
@@ -215,8 +258,67 @@ export class GeminiClient {
      * (enforced locally before any bytes are sent).
      */
     async uploadVideo(path, mimeType) {
-        const key = this.requireKey();
         const blob = await fileBlob(path, { type: mimeType, maxBytes: FILE_MAX_BYTES, label: 'Video' });
+        return this.uploadToFilesApi(blob, mimeType, basename(path), blob.size);
+    }
+    /**
+     * Upload already-in-memory bytes (a fetched `images_url`, a `data_base64`
+     * payload, an inline `gemini_upload_file` body) to the Files API. Same three
+     * steps as {@link uploadVideo}, minus the filesystem — which is what makes it
+     * usable on the hosted connector, where there is no disk to stream from.
+     */
+    async uploadBytes(bytes, mimeType, displayName) {
+        const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+        if (view.byteLength > FILE_MAX_BYTES) {
+            throw new McpToolError(`File is ${view.byteLength} bytes, over the Gemini Files API limit of ${FILE_MAX_BYTES} bytes (2 GB).`);
+        }
+        // `new Blob([view])` already copies exactly the VIEW's bytes — its byte
+        // offset and length, not the whole backing buffer — so an extra `.slice()`
+        // here bought nothing and doubled peak memory, which matters most on the
+        // Worker's 128MB isolate where the fetched buffer is still live.
+        // The cast is a TS lib artefact: `BlobPart` is declared over
+        // `ArrayBuffer`-backed views, while a `Uint8Array` is generic in its buffer
+        // type. The runtime accepts any view.
+        const body = new Blob([view], { type: mimeType });
+        return this.uploadToFilesApi(body, mimeType, displayName, view.byteLength);
+    }
+    /**
+     * Upload a request body straight through to the Files API without buffering
+     * it — the direct-upload HTTP endpoint (`POST /upload` on the Worker) hands
+     * us a `ReadableStream` and a `Content-Length`, and the whole point of that
+     * endpoint is that the bytes never materialize anywhere they'd cost context
+     * or memory.
+     *
+     * `contentLength` is REQUIRED because the resumable protocol's start step
+     * declares it up front (`X-Goog-Upload-Header-Content-Length`); a stream of
+     * unknown length has to be buffered by the caller first.
+     */
+    async uploadStream(stream, mimeType, displayName, contentLength) {
+        if (contentLength > FILE_MAX_BYTES) {
+            throw new McpToolError(`File is ${contentLength} bytes, over the Gemini Files API limit of ${FILE_MAX_BYTES} bytes (2 GB).`);
+        }
+        return this.uploadToFilesApi(stream, mimeType, displayName, contentLength);
+    }
+    /**
+     * The resumable upload itself. Three live-verified steps (docs/GEMINI-API.md
+     * "Files API — local video upload"):
+     *
+     *  1. `POST {UPLOAD_BASE_URL}/files` (command `start`) → the upload session
+     *     URL arrives in the `x-goog-upload-url` RESPONSE HEADER (body is empty).
+     *  2. `POST <session url>` (command `upload, finalize`) with the bytes.
+     *     Response: `{file:…}`.
+     *  3. Poll `GET /v1beta/files/<id>` while `state` is `PROCESSING`, until
+     *     `ACTIVE` (the poll response is the File object UNWRAPPED). Images are
+     *     usually `ACTIVE` immediately; video is what processes.
+     *
+     * These two upload calls are raw `fetchImpl` (not `createApiClient`): step 1
+     * needs the response *header* and step 2 posts a binary body — neither fits
+     * `fetchJson`. The poll DOES go through the shared client (timeout + retry).
+     * Uploads deliberately have no abort timeout: a multi-hundred-MB file can
+     * legitimately take longer than any fixed budget.
+     */
+    async uploadToFilesApi(body, mimeType, displayName, contentLength) {
+        const key = this.requireKey();
         // 1. start — establish the resumable upload session
         const startPath = '/files';
         const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
@@ -225,11 +327,11 @@ export class GeminiClient {
                 'x-goog-api-key': key,
                 'X-Goog-Upload-Protocol': 'resumable',
                 'X-Goog-Upload-Command': 'start',
-                'X-Goog-Upload-Header-Content-Length': String(blob.size),
+                'X-Goog-Upload-Header-Content-Length': String(contentLength),
                 'X-Goog-Upload-Header-Content-Type': mimeType,
                 'Content-Type': 'application/json',
             },
-            body: JSON.stringify({ file: { display_name: basename(path) } }),
+            body: JSON.stringify({ file: { display_name: displayName } }),
         });
         if (!startRes.ok) {
             throw new McpToolError(formatApiError(startRes.status, 'POST', `/upload/v1beta${startPath}`, await startRes.text(), { service: SERVICE }));
@@ -242,13 +344,23 @@ export class GeminiClient {
         }
         // 2. upload + finalize — single shot; the session URL is self-authorizing
         // (no api-key header needed; verified live).
+        // A Blob body is left EXACTLY as the live-verified video upload sent it:
+        // fetch derives Content-Length from the blob, and setting the header by
+        // hand is the kind of change that breaks a verified path for no gain. A
+        // stream has no inherent length, so it declares one — otherwise the runtime
+        // falls back to chunked encoding, which the resumable protocol does not
+        // accept (this half is docs-derived; see docs/GEMINI-API.md).
+        const streaming = !(body instanceof Blob);
         const upRes = await this.fetchImpl(uploadUrl, {
             method: 'POST',
             headers: {
                 'X-Goog-Upload-Offset': '0',
                 'X-Goog-Upload-Command': 'upload, finalize',
+                ...(streaming ? { 'Content-Length': String(contentLength) } : {}),
             },
-            body: blob,
+            body: body,
+            // Required by undici/workerd to send a ReadableStream body at all.
+            ...(streaming ? { duplex: 'half' } : {}),
         });
         if (!upRes.ok) {
             throw new McpToolError(formatApiError(upRes.status, 'POST', '/upload/v1beta/files (finalize)', await upRes.text(), { service: SERVICE }));
@@ -261,23 +373,90 @@ export class GeminiClient {
         if (!/^files\/[\w-]+$/.test(name)) {
             throw new McpToolError(`${SERVICE} upload returned an unexpected file name: ${name || '(none)'}`);
         }
-        // 3. poll PROCESSING → ACTIVE
+        // 3. poll PROCESSING → ACTIVE. Images are normally ACTIVE on arrival; it is
+        // video that spends time here.
         for (let attempt = 0; file.state === 'PROCESSING'; attempt++) {
             if (attempt >= FILE_POLL_MAX_ATTEMPTS) {
-                throw new McpToolError(`${SERVICE} video file ${name} is still processing after ${(FILE_POLL_INTERVAL_MS * FILE_POLL_MAX_ATTEMPTS) / 60_000} minutes`, {
-                    hint: 'Very long videos can take a while to process — retry later by passing the file uri as video_url.',
+                throw new McpToolError(`${SERVICE} file ${name} is still processing after ${(FILE_POLL_INTERVAL_MS * FILE_POLL_MAX_ATTEMPTS) / 60_000} minutes`, {
+                    hint: 'Very long videos can take a while to process — retry later by passing the file uri as video_url / images_file_uris.',
                 });
             }
             await this.sleep(FILE_POLL_INTERVAL_MS);
             file = await this.call('GET', `/${name}`);
         }
         if (file.state !== 'ACTIVE') {
-            throw new McpToolError(`${SERVICE} video file processing failed (state ${file.state ?? 'unknown'})${file.error?.message ? `: ${file.error.message}` : ''}`, { hint: 'Check the video is a supported format/codec and under 2 GB.' });
+            throw new McpToolError(`${SERVICE} file processing failed (state ${file.state ?? 'unknown'})${file.error?.message ? `: ${file.error.message}` : ''}`, { hint: 'Check the file is a supported format/codec and under 2 GB.' });
         }
         if (!file.uri) {
             throw new McpToolError(`${SERVICE} did not return a uri for uploaded file ${name}`);
         }
-        return { name, uri: file.uri, mimeType: file.mimeType ?? mimeType, expirationTime: file.expirationTime };
+        return {
+            name,
+            uri: file.uri,
+            mimeType: file.mimeType ?? mimeType,
+            expirationTime: file.expirationTime,
+            sizeBytes: file.sizeBytes,
+            displayName: file.displayName,
+        };
+    }
+    /**
+     * List the files this API key currently has in the Files API. Retention is
+     * ~48h, so the list is naturally short-lived — an empty list after a day is
+     * expiry, not a bug.
+     */
+    async listFiles(pageSize = 100) {
+        const size = Math.min(Math.max(Math.trunc(pageSize), 1), 100);
+        const data = await this.call('GET', `/files?pageSize=${size}`);
+        return (data.files ?? [])
+            .filter((f) => !!f.name && !!f.uri)
+            .map((f) => ({
+            name: f.name,
+            uri: f.uri,
+            mimeType: f.mimeType ?? 'application/octet-stream',
+            state: f.state,
+            createTime: f.createTime,
+            expirationTime: f.expirationTime,
+            sizeBytes: f.sizeBytes,
+            displayName: f.displayName,
+        }));
+    }
+    /**
+     * Fetch one file's metadata. Used to resolve a caller-supplied
+     * `images_file_uris` entry to its real MIME type — and, as a side effect, to
+     * fail fast with a clear "that file is gone" instead of the Interactions
+     * API's generic 404 after a billable request was already built.
+     */
+    async getFile(ref) {
+        const resource = normalizeFileName(ref);
+        const file = await this.call('GET', `/${resource}`);
+        if (!file.uri) {
+            throw new McpToolError(`${SERVICE} returned no uri for ${resource}`, {
+                hint: 'Files expire ~48h after upload — re-upload with gemini_upload_file (or POST /upload) and use the new uri.',
+            });
+        }
+        if (file.state && file.state !== 'ACTIVE') {
+            throw new McpToolError(`${SERVICE} file ${resource} is not usable yet (state ${file.state}).`, {
+                hint: 'Wait for the upload to finish processing, then retry.',
+            });
+        }
+        return {
+            name: file.name ?? resource,
+            uri: file.uri,
+            mimeType: file.mimeType ?? 'application/octet-stream',
+            expirationTime: file.expirationTime,
+            sizeBytes: file.sizeBytes,
+            displayName: file.displayName,
+        };
+    }
+    /**
+     * Delete one uploaded file. `name` is interpolated into the URL path, so it
+     * is validated to a bare `files/<id>` for the same reason the model id is
+     * (see {@link uploadToFilesApi}); a full `https://…/v1beta/files/<id>` uri is
+     * accepted and reduced to that form, since that is what every result echoes.
+     */
+    async deleteFile(name) {
+        const resource = normalizeFileName(name);
+        await this.call('DELETE', `/${resource}`);
     }
     async listModels() {
         const data = await this.call('GET', '/models?pageSize=200');
@@ -286,9 +465,8 @@ export class GeminiClient {
     async generate(opts) {
         const model = resolveModel(opts.model, readEnvVar('GEMINI_IMAGE_MODEL'));
         const parts = [{ text: opts.prompt }];
-        for (const img of opts.images ?? []) {
-            parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
-        }
+        for (const img of opts.images ?? [])
+            parts.push(generatePart(img));
         if (opts.videoUrl) {
             parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: opts.videoMimeType ?? 'video/mp4' } });
         }
@@ -349,9 +527,8 @@ export class GeminiClient {
     async interact(opts) {
         const model = resolveModel(opts.model, readEnvVar('GEMINI_IMAGE_MODEL'));
         const inputParts = [{ type: 'text', text: opts.input }];
-        for (const img of opts.images ?? []) {
-            inputParts.push({ type: 'image', mime_type: img.mimeType, data: img.base64 });
-        }
+        for (const img of opts.images ?? [])
+            inputParts.push(interactPart(img));
         if (opts.videoUrl) {
             inputParts.push({ type: 'video', uri: opts.videoUrl, mime_type: opts.videoMimeType ?? 'video/mp4' });
         }
@@ -390,7 +567,7 @@ export class GeminiClient {
         const model = opts.model ?? DEFAULT_VIDEO_MODEL;
         const inputParts = [{ type: 'text', text: opts.input }];
         for (const img of opts.images ?? [])
-            inputParts.push({ type: 'image', mime_type: img.mimeType, data: img.base64 });
+            inputParts.push(interactPart(img));
         const responseFormat = { type: 'video', delivery: 'inline' };
         if (opts.aspectRatio)
             responseFormat.aspect_ratio = opts.aspectRatio;
@@ -416,7 +593,7 @@ export class GeminiClient {
         const model = opts.model ?? DEFAULT_MUSIC_MODEL;
         const inputParts = [{ type: 'text', text: opts.input }];
         for (const img of opts.images ?? [])
-            inputParts.push({ type: 'image', mime_type: img.mimeType, data: img.base64 });
+            inputParts.push(interactPart(img));
         const responseFormat = { type: 'audio' };
         if (opts.audioFormat)
             responseFormat.audio_format = opts.audioFormat;