@chrischall/gemini-mcp 1.0.3 → 1.1.0

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;

package/dist/fetch-image.js

@@ -0,0 +1,339 @@
+import { McpToolError } from '@chrischall/mcp-utils';
+/**
+ * Server-side fetching of `images_url` references.
+ *
+ * The point of this module is that image BYTES never travel through the model's
+ * context window. A caller hands over an `https://` URL — a few dozen tokens —
+ * and the *server* pulls the bytes down and turns them into an `inline_data`
+ * part or a Files API upload. The alternative, `images_base64`, costs roughly
+ * 14k tokens for a modest JPEG and is silently corrupted whenever a host
+ * truncates the read that produced it.
+ *
+ * Fetching a caller-supplied URL from inside the server is an SSRF primitive,
+ * and on the stdio build the server runs on the user's own machine, next to
+ * their LAN. So this is deliberately narrow:
+ *
+ *  - **https only.** `http:`, `file:`, `data:`, `gopher:` and friends are out.
+ *  - **No private/loopback/link-local destinations** — including the cloud
+ *    metadata address, the classic escalation target.
+ *  - **Redirects are followed MANUALLY**, revalidating every hop. `redirect:
+ *    'follow'` would let a public URL bounce to `http://169.254.169.254/` with
+ *    no further check, which makes the origin check theatre.
+ *  - **A hard byte cap enforced while streaming**, not from `Content-Length` —
+ *    a hostile or merely wrong server can under-report or omit it.
+ *
+ * Module scope stays side-effect-free: `src/worker.ts` reaches this file
+ * through the tool registrars, so anything executed here would run during
+ * Cloudflare isolate startup.
+ */
+/** Hard ceiling on a fetched image. Above this the URL is rejected outright. */
+export const IMAGE_URL_MAX_BYTES = 15 * 1024 * 1024;
+/**
+ * Above this an image is uploaded to the Files API and referenced by uri
+ * instead of inlined. `generateContent` caps a whole request at ~20 MB, so a
+ * couple of large inline references would fail the request itself — and a
+ * by-reference part costs nothing to repeat across calls.
+ */
+export const IMAGE_INLINE_MAX_BYTES = 6 * 1024 * 1024;
+/** Redirect hops followed before giving up. */
+const MAX_REDIRECTS = 5;
+/**
+ * Per-hop abort budget. Matches the client's default upstream timeout so a URL
+ * fetch is bounded like every other network call this server makes; callers
+ * override it with the same `timeout_ms` resolution (see `resolveTimeoutMs`).
+ */
+const DEFAULT_FETCH_TIMEOUT_MS = 60_000;
+/** Parse an IPv4 literal into its four octets, or `undefined` if it isn't one. */
+function ipv4Octets(host) {
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return undefined;
+    const octets = parts.map((p) => (/^\d{1,3}$/.test(p) ? Number(p) : NaN));
+    return octets.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? octets : undefined;
+}
+/** True for addresses that are not on the public internet. */
+function isPrivateIpv4([a, b]) {
+    if (a === 0 || a === 127)
+        return true; // this-host / loopback
+    if (a === 10)
+        return true; // RFC1918
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // RFC1918
+    if (a === 192 && b === 168)
+        return true; // RFC1918
+    if (a === 169 && b === 254)
+        return true; // link-local — includes 169.254.169.254
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // CGNAT
+    if (a === 192 && b === 0)
+        return true; // IETF protocol assignments
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // benchmarking
+    if (a >= 224)
+        return true; // multicast + reserved
+    return false;
+}
+/**
+ * Expand an IPv6 literal into its eight 16-bit groups, or `undefined` if it
+ * isn't one. Handles `::` compression and a trailing dotted-quad
+ * (`::ffff:127.0.0.1`) — the latter never comes out of `new URL`, which
+ * re-serializes it as hex, but a redirect `Location` is parsed before
+ * normalization and a human writes it that way.
+ */
+function ipv6Groups(host) {
+    if (!host.includes(':'))
+        return undefined;
+    let text = host;
+    const tail = [];
+    // A trailing dotted-quad occupies the last two groups.
+    const dotted = /:((?:\d{1,3}\.){3}\d{1,3})$/.exec(text);
+    if (dotted) {
+        const octets = ipv4Octets(dotted[1]);
+        if (!octets)
+            return undefined;
+        tail.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
+        text = text.slice(0, dotted.index);
+    }
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const parse = (part) => {
+        if (part === '')
+            return [];
+        const out = [];
+        for (const piece of part.split(':')) {
+            if (!/^[0-9a-f]{1,4}$/.test(piece))
+                return undefined;
+            out.push(parseInt(piece, 16));
+        }
+        return out;
+    };
+    const head = parse(halves[0]);
+    const rest = halves.length === 2 ? parse(halves[1]) : [];
+    if (!head || !rest)
+        return undefined;
+    const explicit = [...head, ...rest, ...tail];
+    if (halves.length === 2) {
+        if (explicit.length > 7)
+            return undefined;
+        return [...head, ...Array(8 - explicit.length).fill(0), ...rest, ...tail];
+    }
+    return explicit.length === 8 ? explicit : undefined;
+}
+/**
+ * The /96 prefixes that carry an IPv4 address in their final 32 bits, as the
+ * first six groups. A literal matching any of them is judged on the v4 address
+ * it embeds, not on the prefix.
+ *
+ * `::ffff:0:0/96` is the one that matters operationally — stacks really do
+ * resolve `[::ffff:7f00:1]` to loopback, and `new URL` normalizes
+ * `[::ffff:127.0.0.1]` into exactly that hex spelling, which is how a guard
+ * that pattern-matched the dotted form came to never fire.
+ *
+ * The rest are defense in depth: `::/96` is deprecated IPv4-compatible,
+ * `::ffff:0:0:0/96` is deprecated SIIT (RFC 2765), and `64:ff9b::/96` is the
+ * NAT64 well-known prefix (RFC 6052), which needs a translator on the network
+ * to route at all — and whose §3.1 already forbids embedding non-global v4.
+ * They are listed anyway because a function that understands one v4-carrying
+ * prefix and not its siblings is precisely the shape the original bypass had.
+ */
+const V4_BEARING_PREFIXES = [
+    [0, 0, 0, 0, 0, 0xffff], // ::ffff:0:0/96   — IPv4-mapped
+    [0, 0, 0, 0, 0, 0], //      ::/96           — IPv4-compatible (deprecated)
+    [0, 0, 0, 0, 0xffff, 0], // ::ffff:0:0:0/96 — IPv4-translated (deprecated SIIT)
+    [0x64, 0xff9b, 0, 0, 0, 0], // 64:ff9b::/96 — NAT64 well-known (RFC 6052)
+];
+/**
+ * True for IPv6 addresses that are not on the public internet.
+ *
+ * Anything carrying an IPv4 address (see {@link V4_BEARING_PREFIXES}) is
+ * decided by running that address through the same {@link isPrivateIpv4} table
+ * as a bare v4 literal — so the two guards can never disagree about whether
+ * 10.0.0.5 is private.
+ */
+function isPrivateIpv6(groups) {
+    if (groups.every((g) => g === 0))
+        return true; // ::
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return true; // ::1
+    if ((groups[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local
+    if ((groups[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique-local
+    if (V4_BEARING_PREFIXES.some((prefix) => prefix.every((g, i) => groups[i] === g))) {
+        return isPrivateIpv4([groups[6] >> 8, groups[6] & 0xff, groups[7] >> 8, groups[7] & 0xff]);
+    }
+    return false;
+}
+/**
+ * Reject a URL that isn't a plain public https endpoint. Hostname-based, so it
+ * cannot catch a public name that RESOLVES to a private address (DNS rebinding)
+ * — closing that needs resolve-then-pin, which neither Node's nor workerd's
+ * fetch exposes. It does close the direct-literal and redirect-to-metadata
+ * cases, which is what a prompt-injected URL actually reaches for.
+ */
+function assertPublicHttpsUrl(raw, requested) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new McpToolError(`Not a valid URL: ${raw}`, {
+            hint: 'images_url entries must be absolute https:// URLs.',
+        });
+    }
+    if (url.protocol !== 'https:') {
+        throw new McpToolError(`Refusing to fetch ${describeUrl(raw, requested)}: only https:// URLs are fetched (got "${url.protocol}").`, {
+            hint: 'Use an https:// URL, or send the bytes with images_base64 / gemini_upload_file.',
+        });
+    }
+    // `new URL` always brackets an IPv6 hostname, which is the reliable signal
+    // that this is a literal and not a name.
+    const rawHost = url.hostname.toLowerCase();
+    const isIpv6Literal = rawHost.startsWith('[') && rawHost.endsWith(']');
+    const host = isIpv6Literal ? rawHost.slice(1, -1) : rawHost;
+    const v4 = isIpv6Literal ? undefined : ipv4Octets(host);
+    const v6 = isIpv6Literal ? ipv6Groups(host) : undefined;
+    const blocked = isIpv6Literal
+        // Fail CLOSED on an IPv6 literal we cannot parse: a guard that allows what
+        // it does not understand is the wrong default for this control.
+        ? (v6 === undefined || isPrivateIpv6(v6))
+        : host === 'localhost' ||
+            host.endsWith('.localhost') ||
+            host.endsWith('.local') ||
+            (v4 ? isPrivateIpv4(v4) : false);
+    if (blocked) {
+        throw new McpToolError(`Refusing to fetch ${describeUrl(raw, requested)}: "${url.hostname}" is a private, loopback or link-local address, not a public host.`, { hint: 'images_url is fetched by the server, so it must point at a publicly reachable https:// image.' });
+    }
+    return url;
+}
+/** "<url>" — or "<url> (redirected from <requested>)" when they differ. */
+function describeUrl(current, requested) {
+    return current === requested ? current : `${current} (redirected from ${requested})`;
+}
+/** Read a response body, aborting as soon as it exceeds `maxBytes`. */
+async function readCapped(res, maxBytes, url, requested) {
+    const declared = Number(res.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        throw tooBig(url, requested, declared, maxBytes);
+    }
+    const reader = res.body?.getReader();
+    if (!reader) {
+        // No streaming body (some mocked/edge responses) — fall back to buffering,
+        // then apply the same cap. Correct, just less eager.
+        const buf = new Uint8Array(await res.arrayBuffer());
+        if (buf.byteLength > maxBytes)
+            throw tooBig(url, requested, buf.byteLength, maxBytes);
+        return buf;
+    }
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => { });
+                throw tooBig(url, requested, total, maxBytes, true);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+    }
+    return out;
+}
+/** A transport-level failure, told apart from a plain unreachable host. */
+function fetchFailure(err, current, requested, timeoutMs) {
+    const name = err?.name;
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return new McpToolError(`Fetching ${describeUrl(current, requested)} timed out after ${timeoutMs}ms.`, {
+            hint: 'The server accepted the connection but did not finish sending the image. Try a different URL, or raise timeout_ms.',
+        });
+    }
+    return new McpToolError(`Could not fetch ${describeUrl(current, requested)}: ${err instanceof Error ? err.message : String(err)}`, { hint: 'Check the URL is reachable from the server and serves the image without authentication.' });
+}
+function tooBig(url, requested, size, max, partial = false) {
+    const mb = (n) => `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return new McpToolError(`Image at ${describeUrl(url, requested)} is ${partial ? 'over' : ''} ${mb(size)}, above the ${mb(max)} limit for images_url.`, { hint: 'Resize or re-encode the image, or upload it yourself with gemini_upload_file and pass the returned file_uri.' });
+}
+/**
+ * Fetch one image URL server-side, validating protocol, destination, response
+ * status, content type and size. Every failure names the offending URL in the
+ * MESSAGE — MCP error serialization drops `hint`, and "one of your URLs failed"
+ * is useless when a call carried four of them.
+ */
+export async function fetchRemoteImage(requestedUrl, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const maxBytes = opts.maxBytes ?? IMAGE_URL_MAX_BYTES;
+    const accept = opts.accept ?? ['image/'];
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    let current = requestedUrl;
+    for (let hop = 0;; hop++) {
+        const url = assertPublicHttpsUrl(current, requestedUrl);
+        // One budget per hop, applied to the body read as well: aborting the signal
+        // errors the response stream, so a trickling server cannot outlast it.
+        const signal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+        let res;
+        try {
+            // Manual redirects: every hop goes back through assertPublicHttpsUrl, so
+            // a public URL cannot bounce the fetch onto the metadata service.
+            res = await doFetch(url.toString(), {
+                redirect: 'manual',
+                headers: { accept: accept.map((p) => `${p.replace(/\/$/, '')}/*`).join(', ') },
+                ...(signal ? { signal } : {}),
+            });
+        }
+        catch (err) {
+            throw fetchFailure(err, current, requestedUrl, timeoutMs);
+        }
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get('location');
+            if (!location) {
+                throw new McpToolError(`Fetching ${describeUrl(current, requestedUrl)} returned HTTP ${res.status} with no Location header.`);
+            }
+            if (hop >= MAX_REDIRECTS) {
+                throw new McpToolError(`Fetching ${requestedUrl} exceeded ${MAX_REDIRECTS} redirects (last hop: ${location}).`);
+            }
+            current = new URL(location, url).toString();
+            continue;
+        }
+        if (!res.ok) {
+            throw new McpToolError(`Fetching ${describeUrl(current, requestedUrl)} returned HTTP ${res.status} ${res.statusText || ''}`.trim(), {
+                hint: 'The URL must be publicly readable — a login page or signed-URL expiry shows up here as 401/403/404.',
+            });
+        }
+        const contentType = (res.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+        if (!accept.some((prefix) => contentType.startsWith(prefix))) {
+            const expected = accept.map((p) => `${p.replace(/\/$/, '')}/*`).join(' or ');
+            throw new McpToolError(`${describeUrl(current, requestedUrl)} is not ${accept.length === 1 && accept[0] === 'image/' ? 'an image' : 'usable media'}: ` +
+                `the server returned Content-Type "${contentType || '(none)'}", expected ${expected}.`, { hint: 'Link directly to the media file, not to the page that displays it.' });
+        }
+        let bytes;
+        try {
+            bytes = await readCapped(res, maxBytes, current, requestedUrl);
+        }
+        catch (err) {
+            // The cap is its own actionable error; anything else here is a transport
+            // failure mid-body, most usefully reported as one (including the timeout).
+            if (err instanceof McpToolError)
+                throw err;
+            throw fetchFailure(err, current, requestedUrl, timeoutMs);
+        }
+        if (bytes.byteLength === 0) {
+            throw new McpToolError(`${describeUrl(current, requestedUrl)} returned an empty body.`);
+        }
+        return { bytes, mimeType: contentType, size: bytes.byteLength, finalUrl: current, requestedUrl };
+    }
+}

package/dist/index.js

@@ -9,6 +9,7 @@ import { registerInteractTools } from './tools/interact.js';
 import { registerVideoTools } from './tools/video.js';
 import { registerMusicTools } from './tools/music.js';
 import { registerJobTools } from './tools/jobs.js';
+import { registerFileTools } from './tools/files.js';
 import { client } from './client.js';
 // Load `.env` here rather than in client.ts, which the Cloudflare Worker
 // imports: `import.meta.url` + async I/O at module scope crashes the isolate at
@@ -30,6 +31,6 @@ await runMcp({
     name: 'gemini-mcp',
     version: VERSION,
     banner: '[gemini-mcp] This project was developed and is maintained by AI (Claude). Use at your own discretion.',
-    tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerVideoTools, registerMusicTools, registerJobTools],
+    tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerVideoTools, registerMusicTools, registerJobTools, registerFileTools],
     deps: client,
 });