@chrischall/gemini-mcp 0.4.0 → 0.6.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": "0.4.0"
+    "version": "0.6.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": "0.4.0",
+      "version": "0.6.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,9 @@
 # gemini-mcp
 
+[![CI](https://github.com/chrischall/gemini-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/gemini-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@chrischall/gemini-mcp)](https://www.npmjs.com/package/@chrischall/gemini-mcp)
+[![license](https://img.shields.io/npm/l/@chrischall/gemini-mcp)](LICENSE)
+
 MCP server for Google Gemini image generation and editing. Exposes four tools to Claude over stdio: list available models, generate images from text prompts, edit or compose images with text instructions, and generate a consistent set of images from a master prompt. Images are written to disk by default (path returned) or returned inline as base64. Built on the Gemini v1beta API (`generativelanguage.googleapis.com`) using the Nano Banana / Nano Banana Pro model family.
 
 Developed and maintained by AI (Claude Code).

package/SKILL.md

@@ -83,14 +83,14 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 ### Image Generation
 | Tool | Description |
 |------|-------------|
-| `gemini_generate_image(prompt, count?, images?, images_base64?, video_url?, 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`) |
+| `gemini_generate_image(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_edit_image(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_generate_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 |
 
 ### Multi-turn (Interactions API — Beta)
 | Tool | Description |
 |------|-------------|
-| `gemini_interact(input, previous_interaction_id?, images?, images_base64?, video_url?, google_search?, model?, aspect_ratio?, image_size?, thinking_level?, filename?, output_dir?, inline?)` | Generate/edit via Gemini's **Interactions API**. Returns an `interaction_id`; pass it back as `previous_interaction_id` to **iteratively refine the same image** conversationally — the recommended way to make incremental edits. Output is **JPEG**. (Beta API.) |
+| `gemini_interact(input, previous_interaction_id?, images?, images_base64?, video_url?, video_path?, google_search?, model?, aspect_ratio?, image_size?, thinking_level?, filename?, output_dir?, inline?)` | Generate/edit via Gemini's **Interactions API**. Returns an `interaction_id`; pass it back as `previous_interaction_id` to **iteratively refine the same image** conversationally — the recommended way to make incremental edits. Output is **JPEG**. (Beta API.) |
 
 ## Workflows
 
@@ -179,7 +179,7 @@ extraction:
 - **`thinking_level`** (`minimal`/`high`, Gemini 3 models) controls reasoning depth — `high` can improve complex compositions/edits at higher latency/cost.
 - **Model text.** When the model returns a caption/explanation (mostly Gemini 3 **Pro**), it's surfaced as `text` in the result metadata.
 - **`google_search: true`** grounds the image in live Google Search (current events, weather, real data — great for infographics). The result metadata includes `grounding` with the `queries` run and the `sources` (`{uri, title}`) used. (`gemini_interact` surfaces `grounding.queries` only — the Interactions API returns no clean source list.)
-- **`video_url`** (a public YouTube URL, on `gemini_generate_image` / `gemini_interact`) generates an image from a video reference — **requires a Flash model** (e.g. `model: "gemini-3.1-flash-image"`). Non-YouTube video (Files API upload) is not supported.
+- **`video_url`** (a public YouTube URL, on `gemini_generate_image` / `gemini_interact`) generates an image from a video reference — **requires a Flash model** (e.g. `model: "gemini-3.1-flash-image"`). For a **local video file**, use **`video_path`** instead: the file is uploaded to the Gemini Files API (streamed from disk, 2 GB max), waited to `ACTIVE`, and referenced by its `files/…` uri. The result metadata echoes `video_file` (`{uri, name, expires}`, ~48h retention) — reuse that uri as `video_url` in later calls to skip re-uploading.
 - **`gemini_interact`** is the multi-turn path: it returns an `interaction_id`; thread it back via `previous_interaction_id` for conversational refinement. Output is **JPEG only**. It's a **Beta** API (separate from the stable `generate`/`edit`/`set` tools).
 - `output_dir` per-call overrides `$GEMINI_OUTPUT_DIR` overrides cwd. `inline: true` returns bytes (with a metadata text block) instead of writing.
 - `count` and `scenes` are mutually exclusive in `gemini_generate_set`; `reference_mode: "chain"` references the previous image instead of the master.

package/dist/bundle.js

@@ -32095,20 +32095,9 @@ var init_server3 = __esm({
   }
 });
 
-// node_modules/@chrischall/mcp-utils/dist/response/index.js
-function textResult(data) {
-  return {
-    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
-  };
-}
-var init_response = __esm({
-  "node_modules/@chrischall/mcp-utils/dist/response/index.js"() {
-  }
-});
-
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
 function redactSecrets(text) {
-  return text.replace(BEARER_RE, "$1[REDACTED]").replace(JWT_RE, "[REDACTED]");
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(JWT_RE, "[REDACTED]");
 }
 function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
   const str = text === null || text === void 0 ? "" : String(text);
@@ -32117,7 +32106,7 @@ function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
     return redacted;
   return `${redacted.slice(0, max)}\u2026 [truncated]`;
 }
-var DEFAULT_ERROR_MESSAGE_MAX, McpToolError, BEARER_RE, JWT_RE;
+var DEFAULT_ERROR_MESSAGE_MAX, McpToolError, BEARER_RE, JWT_RE, BASIC_AUTH_RE, SET_COOKIE_RE, COOKIE_HEADER_RE, API_KEY_RE, QUERY_SECRET_RE;
 var init_errors4 = __esm({
   "node_modules/@chrischall/mcp-utils/dist/errors/index.js"() {
     DEFAULT_ERROR_MESSAGE_MAX = 500;
@@ -32134,6 +32123,36 @@ var init_errors4 = __esm({
     };
     BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
     JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,}\b/g;
+    BASIC_AUTH_RE = /(authorization\s*:\s*basic\s+)[A-Za-z0-9+/=_-]{6,}/gi;
+    SET_COOKIE_RE = /(\bset-cookie\s*:\s*)([^=;,\s]+)=[^;,\s]*/gi;
+    COOKIE_HEADER_RE = /((?<!set-)\bcookie\s*:\s*)((?:[^=;,\s]+=[^;,\s]*)(?:;\s*[^=;,\s]+=[^;,\s]*)*)/gi;
+    API_KEY_RE = new RegExp([
+      "sk-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])",
+      // OpenAI / Anthropic (incl. sk-ant-…)
+      "gh[pousr]_[A-Za-z0-9]{36,}\\b",
+      // GitHub ghp_/gho_/ghu_/ghs_/ghr_
+      "xox[baprs]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])",
+      // Slack
+      "AIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])",
+      // Google API key (39 chars total)
+      "AKIA[0-9A-Z]{16}\\b",
+      // AWS access key id (20 chars total)
+      "whsec_[A-Za-z0-9]{16,}\\b"
+      // webhook signing secret (Stripe-style)
+    ].map((p) => `\\b${p}`).join("|"), "g");
+    QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+  }
+});
+
+// node_modules/@chrischall/mcp-utils/dist/response/index.js
+function textResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+var init_response = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/response/index.js"() {
+    init_errors4();
   }
 });
 
@@ -32173,15 +32192,186 @@ var init_config = __esm({
 });
 
 // node_modules/@chrischall/mcp-utils/dist/fs/index.js
+import { openAsBlob } from "node:fs";
+async function fileBlob(path, opts = {}) {
+  let blob;
+  try {
+    blob = await openAsBlob(path, opts.type !== void 0 ? { type: opts.type } : void 0);
+  } catch {
+    throw new Error(`Cannot read file for upload: ${path}`);
+  }
+  if (opts.maxBytes !== void 0 && blob.size > opts.maxBytes) {
+    throw new Error(`${opts.label ?? "File"} is ${blob.size} bytes, over the ${opts.maxBytes}-byte limit: ${path}`);
+  }
+  return blob;
+}
 var init_fs = __esm({
   "node_modules/@chrischall/mcp-utils/dist/fs/index.js"() {
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/http/throttle.js
+var init_throttle = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/http/throttle.js"() {
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/http/index.js
+function hostOf(baseUrl) {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return baseUrl;
+  }
+}
+function createApiClient(opts) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const retry = opts.retry ?? DEFAULT_RETRY;
+  const service = opts.serviceName ?? hostOf(opts.baseUrl);
+  const doFetch = opts.fetchImpl ?? fetch;
+  const sleep = opts.sleep ?? defaultSleep;
+  const unauthorized = () => opts.onUnauthorized ? opts.onUnauthorized() : new UnauthorizedError(service);
+  const rateLimited = () => opts.onRateLimited ? opts.onRateLimited() : new RateLimitedError(service);
+  const retryStatuses = retry.statuses ?? [429];
+  const timeoutMs = opts.timeout;
+  const authHeader = (token) => !token ? {} : opts.tokenHeader ? { [opts.tokenHeader]: token } : { Authorization: `Bearer ${token}` };
+  function withTimeout(run) {
+    if (timeoutMs == null || timeoutMs <= 0)
+      return run(void 0);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return run(controller.signal).catch((err) => {
+      if (err instanceof Error && err.name === "AbortError")
+        throw new RequestTimeoutError(service, timeoutMs);
+      throw err;
+    }).finally(() => clearTimeout(timer));
+  }
+  async function send(method, path, opt) {
+    const isMultipart = opt.formData !== void 0;
+    const hasJsonBody = !isMultipart && opt.body !== void 0;
+    const reqBody = isMultipart ? opt.formData : hasJsonBody ? JSON.stringify(opt.body) : void 0;
+    const query = opt.query ? buildQueryString(opt.query) : "";
+    const url2 = `${base}${path}${query}`;
+    const bodyInit = reqBody !== void 0 ? { body: reqBody } : {};
+    const fetchWith = (token, signal) => doFetch(url2, {
+      method,
+      headers: {
+        Accept: "application/json",
+        ...hasJsonBody ? { "Content-Type": "application/json" } : {},
+        ...opts.baseHeaders,
+        ...authHeader(token || void 0),
+        ...opt.headers
+      },
+      ...signal ? { signal } : {},
+      ...bodyInit
+    });
+    const once = () => withTimeout((signal) => opts.tokenManager ? opts.tokenManager.withAuth((token) => fetchWith(token, signal)) : (async () => fetchWith(await opts.getToken?.() || void 0, signal))());
+    let attempt = 0;
+    for (; ; ) {
+      const res = await once();
+      if (retryStatuses.includes(res.status) && attempt < retry.count) {
+        attempt += 1;
+        await sleep(retry.delayMs);
+        continue;
+      }
+      return res;
+    }
+  }
+  async function fetchJson(method, path, opt = {}) {
+    const res = await send(method, path, opt);
+    if (res.status === 401)
+      throw unauthorized();
+    if (res.status === 429)
+      throw rateLimited();
+    if (res.status === 204)
+      return void 0;
+    const text = await res.text();
+    if (!res.ok) {
+      throw new ApiError(res.status, formatApiError(res.status, method, path, text, { service }));
+    }
+    if (text.length === 0)
+      return void 0;
+    return JSON.parse(text);
+  }
+  async function fetchHtml(method, path, opt = {}) {
+    const headers = { Accept: "text/html,*/*", ...opt.headers };
+    const res = await send(method, path, { ...opt, headers });
+    if (res.status === 401)
+      throw unauthorized();
+    if (res.status === 429)
+      throw rateLimited();
+    const text = await res.text();
+    if (!res.ok) {
+      throw new ApiError(res.status, formatApiError(res.status, method, path, text, { service }));
+    }
+    return text;
+  }
+  return { fetchJson, fetchHtml };
+}
+function buildQueryString(params) {
+  const parts = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null || value === "")
+      continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item === void 0 || item === null || item === "")
+          continue;
+        parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(item))}`);
+      }
+    } else {
+      parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+function formatApiError(status, method, path, errorText, opts = {}) {
+  const service = opts.service ?? "API";
+  const head = `${service} error ${status} for ${method.toUpperCase()} ${path}`;
+  const safe = truncateErrorMessage(errorText ?? "", opts.max).trim();
+  return safe.length > 0 ? `${head}: ${safe}` : head;
+}
+var DEFAULT_RETRY, defaultSleep, UnauthorizedError, RateLimitedError, RequestTimeoutError, ApiError;
 var init_http = __esm({
   "node_modules/@chrischall/mcp-utils/dist/http/index.js"() {
     init_errors4();
+    init_throttle();
+    DEFAULT_RETRY = { count: 1, delayMs: 2e3 };
+    defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    UnauthorizedError = class extends Error {
+      status = 401;
+      constructor(service) {
+        super(`Unauthorized (401) from ${service} \u2014 the token is missing, invalid, or expired.`);
+        this.name = "UnauthorizedError";
+        Object.setPrototypeOf(this, new.target.prototype);
+      }
+    };
+    RateLimitedError = class extends Error {
+      status = 429;
+      constructor(service) {
+        super(`Rate limited (429) by ${service} after retries.`);
+        this.name = "RateLimitedError";
+        Object.setPrototypeOf(this, new.target.prototype);
+      }
+    };
+    RequestTimeoutError = class extends Error {
+      timeoutMs;
+      constructor(service, timeoutMs) {
+        super(`Request to ${service} timed out after ${timeoutMs}ms.`);
+        this.name = "RequestTimeoutError";
+        this.timeoutMs = timeoutMs;
+        Object.setPrototypeOf(this, new.target.prototype);
+      }
+    };
+    ApiError = class extends Error {
+      status;
+      constructor(status, message) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        Object.setPrototypeOf(this, new.target.prototype);
+      }
+    };
   }
 });
 
@@ -32302,14 +32492,14 @@ var init_clipboard = __esm({
 init_dist();
 
 // src/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.6.0";
 
 // src/tools/models.ts
 init_dist();
 
 // src/client.ts
 init_dist();
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/models.ts
@@ -32329,12 +32519,21 @@ function filterImageModels(raw) {
 var __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, "..", ".env"), override: false });
 var BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
-var INTERACTIONS_URL = "https://generativelanguage.googleapis.com/v1beta/interactions";
 var SERVICE = "Gemini";
+var INTERACTIONS_SERVICE = "Gemini Interactions";
+var API_REVISION = "2026-05-20";
+var REQUEST_TIMEOUT_MS = 6e4;
+var UPLOAD_BASE_URL = "https://generativelanguage.googleapis.com/upload/v1beta";
+var FILE_MAX_BYTES = 2 * 1024 ** 3;
+var FILE_POLL_INTERVAL_MS = 2e3;
+var FILE_POLL_MAX_ATTEMPTS = 150;
 var GeminiClient = class {
   apiKey;
   configError;
+  api;
+  interactionsApi;
   fetchImpl;
+  sleep;
   constructor(opts = {}) {
     const key = readEnvVar("GEMINI_API_KEY");
     if (!key) {
@@ -32347,6 +32546,20 @@ var GeminiClient = class {
       this.configError = null;
     }
     this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const shared = {
+      tokenHeader: "x-goog-api-key",
+      getToken: () => this.requireKey(),
+      timeout: REQUEST_TIMEOUT_MS,
+      fetchImpl: this.fetchImpl
+    };
+    this.api = createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared });
+    this.interactionsApi = createApiClient({
+      baseUrl: BASE_URL,
+      serviceName: INTERACTIONS_SERVICE,
+      baseHeaders: { "Api-Revision": API_REVISION },
+      ...shared
+    });
   }
   requireKey() {
     if (this.configError) throw this.configError;
@@ -32357,17 +32570,94 @@ var GeminiClient = class {
     return resolveModel(void 0, readEnvVar("GEMINI_IMAGE_MODEL"));
   }
   async call(method, path, body) {
+    return this.api.fetchJson(method, path, body !== void 0 ? { body } : {});
+  }
+  /**
+   * Upload a local video to the Gemini Files API (resumable protocol) and wait
+   * for it to become usable. 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 —
+   *     a file-backed Blob (`fileBlob`/`fs.openAsBlob`), so fetch STREAMS the
+   *     video from disk; it is never buffered in memory. Response: `{file:…}`.
+   *  3. Poll `GET /v1beta/files/<id>` while `state` is `PROCESSING`, until
+   *     `ACTIVE` (the poll response is the File object UNWRAPPED).
+   *
+   * 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 video can
+   * legitimately take longer than any fixed budget.
+   *
+   * Returned files live ~48h (`expirationTime`); per-file cap is 2 GB
+   * (enforced locally before any bytes are sent).
+   */
+  async uploadVideo(path, mimeType) {
     const key = this.requireKey();
-    const res = await this.fetchImpl(`${BASE_URL}${path}`, {
-      method,
-      headers: { "x-goog-api-key": key, "content-type": "application/json" },
-      body: body !== void 0 ? JSON.stringify(body) : void 0
+    const blob = await fileBlob(path, { type: mimeType, maxBytes: FILE_MAX_BYTES, label: "Video" });
+    const startPath = "/files";
+    const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
+      method: "POST",
+      headers: {
+        "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-Type": mimeType,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ file: { display_name: basename(path) } })
     });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      throw new McpToolError(`${SERVICE} API ${res.status}: ${truncateErrorMessage(text)}`);
+    if (!startRes.ok) {
+      throw new McpToolError(
+        formatApiError(startRes.status, "POST", `/upload/v1beta${startPath}`, await startRes.text(), { service: SERVICE })
+      );
     }
-    return await res.json();
+    const uploadUrl = startRes.headers.get("x-goog-upload-url");
+    if (!uploadUrl) {
+      throw new McpToolError(`${SERVICE} upload start did not return an x-goog-upload-url header`, {
+        hint: "The Files API resumable-upload contract may have changed \u2014 see docs/GEMINI-API.md."
+      });
+    }
+    const upRes = await this.fetchImpl(uploadUrl, {
+      method: "POST",
+      headers: {
+        "X-Goog-Upload-Offset": "0",
+        "X-Goog-Upload-Command": "upload, finalize"
+      },
+      body: blob
+    });
+    if (!upRes.ok) {
+      throw new McpToolError(
+        formatApiError(upRes.status, "POST", "/upload/v1beta/files (finalize)", await upRes.text(), { service: SERVICE })
+      );
+    }
+    let file2 = (await upRes.json()).file ?? {};
+    const name = file2.name ?? "";
+    if (!/^files\/[\w-]+$/.test(name)) {
+      throw new McpToolError(`${SERVICE} upload returned an unexpected file name: ${name || "(none)"}`);
+    }
+    for (let attempt = 0; file2.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 / 6e4} minutes`, {
+          hint: "Very long videos can take a while to process \u2014 retry later by passing the file uri as video_url."
+        });
+      }
+      await this.sleep(FILE_POLL_INTERVAL_MS);
+      file2 = await this.call("GET", `/${name}`);
+    }
+    if (file2.state !== "ACTIVE") {
+      throw new McpToolError(
+        `${SERVICE} video file processing failed (state ${file2.state ?? "unknown"})${file2.error?.message ? `: ${file2.error.message}` : ""}`,
+        { hint: "Check the video is a supported format/codec and under 2 GB." }
+      );
+    }
+    if (!file2.uri) {
+      throw new McpToolError(`${SERVICE} did not return a uri for uploaded file ${name}`);
+    }
+    return { name, uri: file2.uri, mimeType: file2.mimeType ?? mimeType, expirationTime: file2.expirationTime };
   }
   async listModels() {
     const data = await this.call("GET", "/models?pageSize=200");
@@ -32380,7 +32670,7 @@ var GeminiClient = class {
       parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
     }
     if (opts.videoUrl) {
-      parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: "video/mp4" } });
+      parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" } });
     }
     const generationConfig = { responseModalities: ["TEXT", "IMAGE"] };
     if (opts.aspectRatio || opts.imageSize) {
@@ -32431,14 +32721,13 @@ var GeminiClient = class {
     return { images, text, grounding };
   }
   async interact(opts) {
-    const key = this.requireKey();
     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 });
     }
     if (opts.videoUrl) {
-      inputParts.push({ type: "video", uri: opts.videoUrl, mime_type: "video/mp4" });
+      inputParts.push({ type: "video", uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" });
     }
     const responseFormat = { type: "image", mime_type: "image/jpeg" };
     if (opts.aspectRatio) responseFormat.aspect_ratio = opts.aspectRatio;
@@ -32447,26 +32736,9 @@ var GeminiClient = class {
     if (opts.thinkingLevel !== void 0) body.generation_config = { thinking_level: opts.thinkingLevel };
     if (opts.previousInteractionId !== void 0) body.previous_interaction_id = opts.previousInteractionId;
     if (opts.googleSearch) body.tools = [{ type: "google_search" }];
-    const res = await this.fetchImpl(INTERACTIONS_URL, {
-      method: "POST",
-      headers: {
-        "x-goog-api-key": key,
-        "content-type": "application/json",
-        "Api-Revision": "2026-05-20"
-      },
-      body: JSON.stringify(body)
+    const data = await this.interactionsApi.fetchJson("POST", "/interactions", {
+      body
     });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      let message = text;
-      try {
-        const parsed = JSON.parse(text);
-        if (parsed.error?.message) message = parsed.error.message;
-      } catch {
-      }
-      throw new McpToolError(`Gemini Interactions API ${res.status}: ${truncateErrorMessage(message)}`);
-    }
-    const data = await res.json();
     const images = [];
     const textParts = [];
     const searchQueries = [];
@@ -32562,7 +32834,7 @@ async function writeImage(dir, base, base643, mimeType) {
   await writeFile(path, Buffer.from(base643, "base64"));
   return resolve(path);
 }
-function resolveImagePath(p) {
+function resolveInputPath(p, kind) {
   if (isAbsolute(p) && existsSync(p)) return p;
   const inputDir = readEnvVar("GEMINI_INPUT_DIR");
   if (inputDir) {
@@ -32571,12 +32843,40 @@ function resolveImagePath(p) {
   }
   const cwd = resolve(p);
   if (existsSync(cwd)) return cwd;
-  const hint = "Set GEMINI_INPUT_DIR to a directory containing your images, or pass an absolute path.";
+  const hint = `Set GEMINI_INPUT_DIR to a directory containing your ${kind.toLowerCase()}s, or pass an absolute path.`;
   throw new McpToolError(
-    `Image not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ""),
+    `${kind} not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ""),
     { hint }
   );
 }
+function resolveImagePath(p) {
+  return resolveInputPath(p, "Image");
+}
+function resolveVideoPath(p) {
+  return resolveInputPath(p, "Video");
+}
+var VIDEO_MIME_BY_EXT = {
+  mp4: "video/mp4",
+  mpeg: "video/mpeg",
+  mpg: "video/mpg",
+  mov: "video/mov",
+  avi: "video/avi",
+  flv: "video/x-flv",
+  webm: "video/webm",
+  wmv: "video/wmv",
+  "3gp": "video/3gpp",
+  "3gpp": "video/3gpp"
+};
+function videoMimeType(p) {
+  const ext = p.includes(".") ? p.slice(p.lastIndexOf(".") + 1).toLowerCase() : "";
+  const mime = VIDEO_MIME_BY_EXT[ext];
+  if (!mime) {
+    throw new McpToolError(`Unsupported video format: ${ext ? `.${ext}` : p}`, {
+      hint: `Supported extensions: ${Object.keys(VIDEO_MIME_BY_EXT).map((e) => `.${e}`).join(", ")}`
+    });
+  }
+  return mime;
+}
 async function readImageAsInline(path) {
   const resolved = resolveImagePath(path);
   const buf = await readFile2(resolved);
@@ -32621,7 +32921,10 @@ init_dist();
 var ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:4", "4:1", "1:8", "8:1"];
 var IMAGE_SIZES = ["512", "1K", "2K", "4K"];
 var sharedImageSchema = {
-  model: external_exports.string().optional().describe("Model id override (default: server default; see gemini_list_models)"),
+  // Bare id only: the model is interpolated into the URL path
+  // (`/models/${model}:generateContent`), so slashes/colons/queries must be
+  // rejected to keep a crafted value from escaping the path segment.
+  model: external_exports.string().regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")').optional().describe("Model id override (default: server default; see gemini_list_models)"),
   aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Output aspect ratio"),
   image_size: external_exports.enum(IMAGE_SIZES).optional().describe("Output resolution (512 = 0.5K, Flash-only)"),
   output_dir: external_exports.string().optional().describe("Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"),
@@ -32631,6 +32934,20 @@ var sharedImageSchema = {
   google_search: external_exports.boolean().optional().describe("Ground the image in live Google Search results (current events, weather, data)"),
   from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)")
 };
+async function resolveVideoInput(args) {
+  if (args.video_url && args.video_path) {
+    throw new McpToolError("Provide `video_url` OR `video_path`, not both.");
+  }
+  if (!args.video_path) return { videoUrl: args.video_url };
+  const path = resolveVideoPath(args.video_path);
+  const uploaded = await client.uploadVideo(path, videoMimeType(args.video_path));
+  const videoFileMeta = { uri: uploaded.uri, name: uploaded.name };
+  if (uploaded.expirationTime) videoFileMeta.expires = uploaded.expirationTime;
+  return { videoUrl: uploaded.uri, videoMimeType: uploaded.mimeType, videoFileMeta };
+}
+var videoPathSchema = external_exports.string().optional().describe(
+  "Path to a local video file \u2014 uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url."
+);
 function pickSeed(seed) {
   return seed ?? Math.floor(Math.random() * 2147483e3);
 }
@@ -32669,7 +32986,8 @@ function registerGenerateTools(server) {
         filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to reference input images (image-conditioned generation)"),
         images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs"),
-        video_url: external_exports.string().url().optional().describe("Public YouTube URL as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_url: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_path: videoPathSchema,
         ...sharedImageSchema
       }
     },
@@ -32679,6 +32997,7 @@ function registerGenerateTools(server) {
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
       const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
       const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+      const video = await resolveVideoInput(args);
       const named = [];
       let capturedText;
       let capturedGrounding;
@@ -32692,7 +33011,8 @@ function registerGenerateTools(server) {
           seed: seed + i,
           thinkingLevel: args.thinking_level,
           googleSearch: args.google_search,
-          videoUrl: args.video_url
+          videoUrl: video.videoUrl,
+          videoMimeType: video.videoMimeType
         });
         const { images: [img], text } = result;
         if (text && !capturedText) capturedText = text;
@@ -32702,6 +33022,7 @@ function registerGenerateTools(server) {
       const meta3 = buildMeta(model, seed, args);
       if (capturedText) meta3.text = capturedText;
       if (capturedGrounding) meta3.grounding = capturedGrounding;
+      if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
       return emit(named, args, meta3);
     }
   );
@@ -32829,12 +33150,14 @@ function registerInteractTools(server) {
         output_dir: external_exports.string().optional().describe("Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"),
         inline: external_exports.boolean().optional().describe("Return base64 images inline instead of writing to disk"),
         google_search: external_exports.boolean().optional().describe("Ground the image in live Google Search results (current events, weather, data)"),
-        video_url: external_exports.string().url().optional().describe("Public YouTube URL as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_url: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_path: videoPathSchema,
         from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)")
       }
     },
     async (args) => {
       const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+      const video = await resolveVideoInput(args);
       const r = await client.interact({
         input: args.input,
         images: inputs.length ? inputs : void 0,
@@ -32844,12 +33167,14 @@ function registerInteractTools(server) {
         thinkingLevel: args.thinking_level,
         previousInteractionId: args.previous_interaction_id,
         googleSearch: args.google_search,
-        videoUrl: args.video_url
+        videoUrl: video.videoUrl,
+        videoMimeType: video.videoMimeType
       });
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
       const meta3 = { model, interaction_id: r.id };
       if (r.text) meta3.text = r.text;
       if (r.grounding) meta3.grounding = r.grounding;
+      if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
       const slug = args.filename ? baseName(args.filename) : slugify2(args.input);
       const named = r.images.map((image, i) => ({
         image,

package/dist/client.js

@@ -1,16 +1,36 @@
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadDotenvSafely, readEnvVar, McpToolError, truncateErrorMessage } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, readEnvVar, McpToolError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
 import { resolveModel, filterImageModels } from './models.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
 const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'; // v1 lacks gemini-3-pro-image; confirmed via Task 5
-const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions';
 const SERVICE = 'Gemini';
+const INTERACTIONS_SERVICE = 'Gemini Interactions';
+// Required revision header for the beta Interactions API (verified 2026-06-08;
+// see docs/GEMINI-API.md) — load-bearing, requests 400 without it.
+const API_REVISION = '2026-05-20';
+// Per-request abort budget. Image generation routinely runs 30s+ on the Pro
+// model, so this is deliberately 60s (NOT the fleet's usual 15–30s).
+const REQUEST_TIMEOUT_MS = 60_000;
+// Files API (local-video upload — docs/GEMINI-API.md "Files API — local video
+// upload", verified 2026-06-12). The resumable upload endpoint lives under
+// `/upload/v1beta`, NOT the normal `/v1beta` base.
+const UPLOAD_BASE_URL = 'https://generativelanguage.googleapis.com/upload/v1beta';
+// Documented Files API per-file cap (2 GB); enforced locally so a too-big video
+// fails fast instead of uploading gigabytes just to be rejected.
+const FILE_MAX_BYTES = 2 * 1024 ** 3;
+// PROCESSING→ACTIVE poll: every 2s for up to 5 minutes. A 2s clip went ACTIVE
+// in ~1s (verified); longer videos take proportionally longer to process.
+const FILE_POLL_INTERVAL_MS = 2_000;
+const FILE_POLL_MAX_ATTEMPTS = 150;
 export class GeminiClient {
     apiKey;
     configError;
+    api;
+    interactionsApi;
     fetchImpl;
+    sleep;
     constructor(opts = {}) {
         const key = readEnvVar('GEMINI_API_KEY');
         if (!key) {
@@ -23,7 +43,29 @@ export class GeminiClient {
             this.apiKey = key;
             this.configError = null;
         }
+        // Both paths share: the key in the `x-goog-api-key` header (Gemini does not
+        // use `Authorization: Bearer`), a 60s abort budget, and the default 429
+        // retry (once after 2s — the free tier rate-limits aggressively).
+        // `getToken` calls requireKey() so key resolution stays at REQUEST time:
+        // the server boots without a key and the actionable config error (with its
+        // aistudio hint) surfaces on the first tool call, not at startup.
         this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        const shared = {
+            tokenHeader: 'x-goog-api-key',
+            getToken: () => this.requireKey(),
+            timeout: REQUEST_TIMEOUT_MS,
+            fetchImpl: this.fetchImpl,
+        };
+        this.api = createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared });
+        // Separate client for the beta Interactions API: same base URL, but every
+        // request must carry the Api-Revision header (and errors name the API).
+        this.interactionsApi = createApiClient({
+            baseUrl: BASE_URL,
+            serviceName: INTERACTIONS_SERVICE,
+            baseHeaders: { 'Api-Revision': API_REVISION },
+            ...shared,
+        });
     }
     requireKey() {
         if (this.configError)
@@ -35,17 +77,94 @@ export class GeminiClient {
         return resolveModel(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));
     }
     async call(method, path, body) {
+        return this.api.fetchJson(method, path, body !== undefined ? { body } : {});
+    }
+    /**
+     * Upload a local video to the Gemini Files API (resumable protocol) and wait
+     * for it to become usable. 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 —
+     *     a file-backed Blob (`fileBlob`/`fs.openAsBlob`), so fetch STREAMS the
+     *     video from disk; it is never buffered in memory. Response: `{file:…}`.
+     *  3. Poll `GET /v1beta/files/<id>` while `state` is `PROCESSING`, until
+     *     `ACTIVE` (the poll response is the File object UNWRAPPED).
+     *
+     * 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 video can
+     * legitimately take longer than any fixed budget.
+     *
+     * Returned files live ~48h (`expirationTime`); per-file cap is 2 GB
+     * (enforced locally before any bytes are sent).
+     */
+    async uploadVideo(path, mimeType) {
         const key = this.requireKey();
-        const res = await this.fetchImpl(`${BASE_URL}${path}`, {
-            method,
-            headers: { 'x-goog-api-key': key, 'content-type': 'application/json' },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
+        const blob = await fileBlob(path, { type: mimeType, maxBytes: FILE_MAX_BYTES, label: 'Video' });
+        // 1. start — establish the resumable upload session
+        const startPath = '/files';
+        const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
+            method: 'POST',
+            headers: {
+                '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-Type': mimeType,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ file: { display_name: basename(path) } }),
+        });
+        if (!startRes.ok) {
+            throw new McpToolError(formatApiError(startRes.status, 'POST', `/upload/v1beta${startPath}`, await startRes.text(), { service: SERVICE }));
+        }
+        const uploadUrl = startRes.headers.get('x-goog-upload-url');
+        if (!uploadUrl) {
+            throw new McpToolError(`${SERVICE} upload start did not return an x-goog-upload-url header`, {
+                hint: 'The Files API resumable-upload contract may have changed — see docs/GEMINI-API.md.',
+            });
+        }
+        // 2. upload + finalize — single shot; the session URL is self-authorizing
+        // (no api-key header needed; verified live).
+        const upRes = await this.fetchImpl(uploadUrl, {
+            method: 'POST',
+            headers: {
+                'X-Goog-Upload-Offset': '0',
+                'X-Goog-Upload-Command': 'upload, finalize',
+            },
+            body: blob,
         });
-        if (!res.ok) {
-            const text = await res.text().catch(() => '');
-            throw new McpToolError(`${SERVICE} API ${res.status}: ${truncateErrorMessage(text)}`);
+        if (!upRes.ok) {
+            throw new McpToolError(formatApiError(upRes.status, 'POST', '/upload/v1beta/files (finalize)', await upRes.text(), { service: SERVICE }));
         }
-        return (await res.json());
+        let file = (await upRes.json()).file ?? {};
+        // The server echoes the resource name (`files/<id>`); it is interpolated
+        // into the poll path below, so reject anything that could escape the
+        // `/files/` segment (same posture as the model-id guard).
+        const name = file.name ?? '';
+        if (!/^files\/[\w-]+$/.test(name)) {
+            throw new McpToolError(`${SERVICE} upload returned an unexpected file name: ${name || '(none)'}`);
+        }
+        // 3. poll PROCESSING → ACTIVE
+        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.',
+                });
+            }
+            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.' });
+        }
+        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 };
     }
     async listModels() {
         const data = await this.call('GET', '/models?pageSize=200');
@@ -58,7 +177,7 @@ export class GeminiClient {
             parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
         }
         if (opts.videoUrl) {
-            parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: 'video/mp4' } });
+            parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: opts.videoMimeType ?? 'video/mp4' } });
         }
         const generationConfig = { responseModalities: ['TEXT', 'IMAGE'] };
         if (opts.aspectRatio || opts.imageSize) {
@@ -115,14 +234,13 @@ export class GeminiClient {
         return { images, text, grounding };
     }
     async interact(opts) {
-        const key = this.requireKey();
         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 });
         }
         if (opts.videoUrl) {
-            inputParts.push({ type: 'video', uri: opts.videoUrl, mime_type: 'video/mp4' });
+            inputParts.push({ type: 'video', uri: opts.videoUrl, mime_type: opts.videoMimeType ?? 'video/mp4' });
         }
         const responseFormat = { type: 'image', mime_type: 'image/jpeg' };
         if (opts.aspectRatio)
@@ -136,27 +254,9 @@ export class GeminiClient {
             body.previous_interaction_id = opts.previousInteractionId;
         if (opts.googleSearch)
             body.tools = [{ type: 'google_search' }];
-        const res = await this.fetchImpl(INTERACTIONS_URL, {
-            method: 'POST',
-            headers: {
-                'x-goog-api-key': key,
-                'content-type': 'application/json',
-                'Api-Revision': '2026-05-20',
-            },
-            body: JSON.stringify(body),
+        const data = await this.interactionsApi.fetchJson('POST', '/interactions', {
+            body,
         });
-        if (!res.ok) {
-            const text = await res.text().catch(() => '');
-            let message = text;
-            try {
-                const parsed = JSON.parse(text);
-                if (parsed.error?.message)
-                    message = parsed.error.message;
-            }
-            catch { /* use raw text */ }
-            throw new McpToolError(`Gemini Interactions API ${res.status}: ${truncateErrorMessage(message)}`);
-        }
-        const data = await res.json();
         // Only surface the `model_output` step — that's the caller-facing result.
         // `thought` steps hold internal reasoning (and, with includeThoughts, draft
         // "thinking" images); collecting those would leak reasoning into `text` and

package/dist/images.js

@@ -58,13 +58,13 @@ export async function writeImage(dir, base, base64, mimeType) {
     return resolve(path);
 }
 /**
- * Resolve an image path, checking (in order):
+ * Resolve an input file path, checking (in order):
  *  1. Absolute path that exists → returned as-is.
  *  2. `GEMINI_INPUT_DIR` env var is set → look for `join(inputDir, p)`.
  *  3. Relative to cwd → `resolve(p)`.
- * Throws a helpful `McpToolError` if none are found.
+ * Throws a helpful `McpToolError` (labelled `kind`) if none are found.
  */
-export function resolveImagePath(p) {
+function resolveInputPath(p, kind) {
     if (isAbsolute(p) && existsSync(p))
         return p;
     const inputDir = readEnvVar('GEMINI_INPUT_DIR');
@@ -78,8 +78,41 @@ export function resolveImagePath(p) {
     const cwd = resolve(p);
     if (existsSync(cwd))
         return cwd;
-    const hint = 'Set GEMINI_INPUT_DIR to a directory containing your images, or pass an absolute path.';
-    throw new McpToolError(`Image not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ''), { hint });
+    const hint = `Set GEMINI_INPUT_DIR to a directory containing your ${kind.toLowerCase()}s, or pass an absolute path.`;
+    throw new McpToolError(`${kind} not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ''), { hint });
+}
+/** Resolve an image path (absolute → GEMINI_INPUT_DIR → cwd). */
+export function resolveImagePath(p) {
+    return resolveInputPath(p, 'Image');
+}
+/** Resolve a local video path (absolute → GEMINI_INPUT_DIR → cwd). */
+export function resolveVideoPath(p) {
+    return resolveInputPath(p, 'Video');
+}
+/** Video MIME types the Gemini Files API accepts, by file extension
+ * (docs/GEMINI-API.md "Files API — local video upload"). */
+const VIDEO_MIME_BY_EXT = {
+    mp4: 'video/mp4',
+    mpeg: 'video/mpeg',
+    mpg: 'video/mpg',
+    mov: 'video/mov',
+    avi: 'video/avi',
+    flv: 'video/x-flv',
+    webm: 'video/webm',
+    wmv: 'video/wmv',
+    '3gp': 'video/3gpp',
+    '3gpp': 'video/3gpp',
+};
+/** MIME type for a video file from its extension; throws for unsupported formats. */
+export function videoMimeType(p) {
+    const ext = p.includes('.') ? p.slice(p.lastIndexOf('.') + 1).toLowerCase() : '';
+    const mime = VIDEO_MIME_BY_EXT[ext];
+    if (!mime) {
+        throw new McpToolError(`Unsupported video format: ${ext ? `.${ext}` : p}`, {
+            hint: `Supported extensions: ${Object.keys(VIDEO_MIME_BY_EXT).map((e) => `.${e}`).join(', ')}`,
+        });
+    }
+    return mime;
 }
 /** Read an image file into `{ base64, mimeType }` for an inline_data part. */
 export async function readImageAsInline(path) {

package/dist/tools/generate.js

@@ -3,7 +3,7 @@ import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta } from './shared.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, resolveVideoInput, videoPathSchema } from './shared.js';
 export function registerGenerateTools(server) {
     server.registerTool('gemini_generate_image', {
         description: 'Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro).',
@@ -14,7 +14,8 @@ export function registerGenerateTools(server) {
             filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
             images: z.array(z.string().min(1)).optional().describe('Paths to reference input images (image-conditioned generation)'),
             images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs'),
-            video_url: z.string().url().optional().describe('Public YouTube URL as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
+            video_url: z.string().url().optional().describe('Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
+            video_path: videoPathSchema,
             ...sharedImageSchema,
         },
     }, async (args) => {
@@ -23,6 +24,9 @@ export function registerGenerateTools(server) {
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
         const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
         const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        // Upload ONCE (before the count loop) — every generate call references
+        // the same files/… uri.
+        const video = await resolveVideoInput(args);
         const named = [];
         let capturedText;
         // For count>1, surface the FIRST call's grounding (each call grounds
@@ -40,7 +44,8 @@ export function registerGenerateTools(server) {
                 seed: seed + i,
                 thinkingLevel: args.thinking_level,
                 googleSearch: args.google_search,
-                videoUrl: args.video_url,
+                videoUrl: video.videoUrl,
+                videoMimeType: video.videoMimeType,
             });
             const { images: [img], text } = result;
             if (text && !capturedText)
@@ -54,6 +59,8 @@ export function registerGenerateTools(server) {
             meta.text = capturedText;
         if (capturedGrounding)
             meta.grounding = capturedGrounding;
+        if (video.videoFileMeta)
+            meta.video_file = video.videoFileMeta;
         return emit(named, args, meta);
     });
     server.registerTool('gemini_edit_image', {

package/dist/tools/interact.js

@@ -3,7 +3,7 @@ import { readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, ASPECT_RATIOS, IMAGE_SIZES } from './shared.js';
+import { emit, ASPECT_RATIOS, IMAGE_SIZES, resolveVideoInput, videoPathSchema } from './shared.js';
 export function registerInteractTools(server) {
     server.registerTool('gemini_interact', {
         description: "Multi-turn image generation/editing via Gemini's Interactions API (Beta). " +
@@ -58,7 +58,8 @@ export function registerInteractTools(server) {
                 .string()
                 .url()
                 .optional()
-                .describe('Public YouTube URL as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
+                .describe('Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
+            video_path: videoPathSchema,
             from_clipboard: z
                 .boolean()
                 .optional()
@@ -66,6 +67,7 @@ export function registerInteractTools(server) {
         },
     }, async (args) => {
         const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const video = await resolveVideoInput(args);
         const r = await client.interact({
             input: args.input,
             images: inputs.length ? inputs : undefined,
@@ -75,7 +77,8 @@ export function registerInteractTools(server) {
             thinkingLevel: args.thinking_level,
             previousInteractionId: args.previous_interaction_id,
             googleSearch: args.google_search,
-            videoUrl: args.video_url,
+            videoUrl: video.videoUrl,
+            videoMimeType: video.videoMimeType,
         });
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
         const meta = { model, interaction_id: r.id };
@@ -83,6 +86,8 @@ export function registerInteractTools(server) {
             meta.text = r.text;
         if (r.grounding)
             meta.grounding = r.grounding;
+        if (video.videoFileMeta)
+            meta.video_file = video.videoFileMeta;
         const slug = args.filename ? baseName(args.filename) : slugify(args.input);
         const named = r.images.map((image, i) => ({
             image,

package/dist/tools/shared.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
-import { writeImage, resolveOutputDir } from '../images.js';
+import { textResult, McpToolError } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+import { writeImage, resolveOutputDir, resolveVideoPath, videoMimeType } from '../images.js';
 /** Supported output aspect ratios (Gemini image API). */
 export const ASPECT_RATIOS = ['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9', '1:4', '4:1', '1:8', '8:1'];
 /** Supported output resolutions. `512` is Flash-only (0.5K); `1K`/`2K`/`4K` work on all image models. */
@@ -11,7 +12,14 @@ export const IMAGE_SIZES = ['512', '1K', '2K', '4K'];
  * into each tool's `inputSchema`.
  */
 export const sharedImageSchema = {
-    model: z.string().optional().describe('Model id override (default: server default; see gemini_list_models)'),
+    // Bare id only: the model is interpolated into the URL path
+    // (`/models/${model}:generateContent`), so slashes/colons/queries must be
+    // rejected to keep a crafted value from escaping the path segment.
+    model: z
+        .string()
+        .regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")')
+        .optional()
+        .describe('Model id override (default: server default; see gemini_list_models)'),
     aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
     image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution (512 = 0.5K, Flash-only)'),
     output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
@@ -21,6 +29,32 @@ export const sharedImageSchema = {
     google_search: z.boolean().optional().describe('Ground the image in live Google Search results (current events, weather, data)'),
     from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)'),
 };
+/**
+ * Turn the `video_url` / `video_path` tool args into the client's video opts.
+ * A `video_path` is resolved locally (absolute → $GEMINI_INPUT_DIR → cwd),
+ * uploaded to the Gemini Files API (streamed, never buffered), and waited to
+ * `ACTIVE`; the returned `files/…` uri is what the generate call references.
+ * The uploaded file (uri + expiry) is echoed via `videoFileMeta` so a caller
+ * can pass the uri straight back as `video_url` instead of re-uploading.
+ */
+export async function resolveVideoInput(args) {
+    if (args.video_url && args.video_path) {
+        throw new McpToolError('Provide `video_url` OR `video_path`, not both.');
+    }
+    if (!args.video_path)
+        return { videoUrl: args.video_url };
+    const path = resolveVideoPath(args.video_path);
+    const uploaded = await client.uploadVideo(path, videoMimeType(args.video_path));
+    const videoFileMeta = { uri: uploaded.uri, name: uploaded.name };
+    if (uploaded.expirationTime)
+        videoFileMeta.expires = uploaded.expirationTime;
+    return { videoUrl: uploaded.uri, videoMimeType: uploaded.mimeType, videoFileMeta };
+}
+/** Shared zod field for the `video_path` tool param. */
+export const videoPathSchema = z
+    .string()
+    .optional()
+    .describe('Path to a local video file — uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url.');
 /**
  * Return the provided seed, or pick a random one. Capped well below INT32_MAX
  * so derived per-image seeds (`seed + i`) can't overflow a 32-bit int.

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "0.4.0",
+  "version": "0.6.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>",
@@ -44,7 +44,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.6.0",
+    "@chrischall/mcp-utils": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"

package/server.json

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