@chrischall/gemini-mcp 1.12.0 → 1.14.0

package/dist/tools/shared.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { textResult, McpToolError, readEnvVar } from '@chrischall/mcp-utils';
+import { McpToolError, minifiedResult, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveVideoPath, videoMimeType } from '../images.js';
 import { IMAGE_URL_MAX_BYTES, IMAGE_INLINE_MAX_BYTES } from '../fetch-image.js';
 import { bytesToBase64, base64ToBytes, wholeMb } from '../bytes.js';
@@ -71,19 +71,15 @@ export function resolveAspectRatio(opts, supported) {
 export const orientationSchema = z
     .enum(ORIENTATIONS)
     .optional()
-    .describe('Shape of the output, in plain terms: "landscape" (wide, 16:9), "portrait" (tall, 9:16) or "square" (1:1). ' +
-    'Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — ' +
-    '35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, ' +
-    'which overrides this when both are given.');
+    .describe('Output shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — ' +
+    '3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given.');
 /**
  * When to pick which Nano Banana model — shared by every tool's `model` param
  * so the guidance can't drift between them.
  */
-export const MODEL_CHOICE_GUIDE = 'gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with ' +
-    'state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image ' +
-    'processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex ' +
-    'visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. ' +
-    'gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).';
+export const MODEL_CHOICE_GUIDE = 'gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong ' +
+    'multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand ' +
+    'precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding.';
 /**
  * Per-call upstream timeout override, shared by every generation tool
  * (spread via {@link sharedImageSchema}; `gemini_interact` imports it directly
@@ -94,7 +90,7 @@ export const timeoutMsSchema = z
     .int()
     .positive()
     .optional()
-    .describe('Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)');
+    .describe('Upstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)');
 /**
  * Idempotency key shared by every generation tool. A repeat call carrying the
  * same key returns the recorded result (`reused: true`) instead of billing a
@@ -105,7 +101,7 @@ export const idempotencyKeySchema = z
     .string()
     .min(1)
     .optional()
-    .describe('Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.');
+    .describe('Repeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001).');
 /**
  * Async escape hatch shared by every generation tool: return a `job_id`
  * immediately so a long (Pro/4K) generation can't hit a host's fixed tools/call
@@ -114,10 +110,9 @@ export const idempotencyKeySchema = z
 export const asyncSchema = z
     .boolean()
     .optional()
-    .describe('Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit ' +
-    'the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. ' +
-    'PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the ' +
-    'request is open, so this option is served there as a bounded wait rather than an immediate hand-off.');
+    .describe('Return a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout ' +
+    '(-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a ' +
+    'request is open, so async is served there as a bounded wait.');
 /**
  * Wait-then-hand-off budget shared by every generation tool: wait up to the
  * budget for the in-band result, and past it return a `{ job_id }` handle
@@ -130,9 +125,9 @@ export const maxWaitMsSchema = z
     .positive()
     .max(600_000)
     .optional()
-    .describe('Wait up to this many ms for the result; if generation is still running when the budget expires, return ' +
-    '{ job_id, status: "running" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a ' +
-    'slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.');
+    .describe('Wait up to this many ms in-band, then hand back { job_id, status: "running" } to poll with gemini_get_result ' +
+    '(e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). ' +
+    'Ignored when async is set.');
 /**
  * Reference images already in THIS connector's object store, by `r2_key`.
  * Hosted connector only — the server reads its own bucket (tenant-gated), so
@@ -142,25 +137,24 @@ export function imagesR2KeysSchema(label = 'Reference images') {
     return z
         .array(z.string().min(1))
         .optional()
-        .describe(`${label} by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier ` +
-        "generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, " +
-        'no ~48h Files API expiry. Hosted connector only.');
+        .describe(`${label} by r2_key from this connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier ` +
+        "generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. " +
+        'Hosted connector only.');
 }
 /** Saved-character names attached to a generation (hosted connector only). */
 export const charactersSchema = z
     .array(z.string().min(1))
     .max(8)
     .optional()
-    .describe('Names of saved characters (see gemini_list_characters / gemini_save_character): each one\'s reference image and ' +
-    'description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. ' +
-    'Hosted connector only.');
+    .describe('Names of saved characters (gemini_list_characters): each one\'s reference image and description are attached ' +
+    'automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.');
 /** Saved-style name applied to a generation (hosted connector only). */
 export const styleSchema = z
     .string()
     .min(1)
     .optional()
-    .describe('Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, ' +
-    'if it has one — is applied to the request automatically. Hosted connector only.');
+    .describe('Name of a saved style preset (gemini_list_styles): its prompt fragment, and reference image if it has one, are ' +
+    'applied automatically. Hosted connector only.');
 /**
  * Turn `characters: ["finn", …]` / `style: "…"` into reference-image inputs
  * plus prompt text, from the account's saved library.
@@ -257,9 +251,23 @@ export function imagesUrlSchema(label = 'Reference images') {
     return z
         .array(z.string().url())
         .optional()
-        .describe(`${label} as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. ` +
-        'Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. ' +
-        `Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each; must be a directly-linked image (Content-Type image/*).`);
+        .describe(`${label} as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred ` +
+        `over images_base64, which costs ~14k tokens per photo. Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each, Content-Type image/*.`);
+}
+/**
+ * Raw base64 / data URIs — the last-resort input form, and the only one whose
+ * bytes have already crossed the conversation by the time the server sees
+ * them. The description says so, and says what to do instead NEXT time: the
+ * funnel uploads each entry once and reports the `files/<id>` back, so the
+ * repeat reference costs a short string rather than another photo.
+ */
+export function imagesBase64Schema(label = 'Reference images', prefix = 'images') {
+    return z
+        .array(z.string().min(1))
+        .optional()
+        .describe(`${label} as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer ${prefix}_url or ` +
+        `${prefix}_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to ` +
+        `${prefix}_file_uris next time instead of re-sending the bytes.`);
 }
 /**
  * Reference images already in the Gemini Files API. The cheapest form there is:
@@ -269,9 +277,8 @@ export function imagesFileUrisSchema(label = 'Reference images') {
     return z
         .array(z.string().min(1))
         .optional()
-        .describe(`${label} by Gemini Files API reference ("files/<id>", or the full uri) from gemini_upload_file or POST /upload. ` +
-        'Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. ' +
-        'Files are retained ~48h, after which the reference stops resolving.');
+        .describe(`${label} as Files API references ("files/<id>" or the full uri) from gemini_upload_file. Upload once and reuse ` +
+        'across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving.');
 }
 /**
  * The model/aspect/size/output fields every generation tool shares. Defined once
@@ -294,7 +301,7 @@ export const sharedImageSchema = {
     orientation: orientationSchema,
     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)'),
-    inline: z.boolean().optional().describe('Return base64 images inline instead of writing to disk'),
+    inline: z.boolean().optional().describe('Return the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have'),
     seed: z.number().int().optional().describe('Seed for reproducible generation; random if omitted'),
     thinking_level: z.enum(['minimal', 'high']).optional().describe('Reasoning depth (Gemini 3 models); higher can help complex/structural edits'),
     google_search: z.boolean().optional().describe('Ground the image in live Google Search results (current events, weather, data)'),
@@ -499,6 +506,28 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
     // next to, so it is skipped rather than handed URLs it would misinterpret.
     if (sink.persistsFiles)
         await onWritten?.(refs);
+    // The hosted twin of the `<image>.json` sidecar `onWritten` writes on disk.
+    // Same purpose: the interaction id has to outlive the response, or a dropped
+    // turn ends the chain and a 404 has nothing to re-anchor on. Written for
+    // EVERY stored object, since a set's scenes are as worth identifying later
+    // as its master. Best-effort inside the sink, which never throws.
+    const record = {
+        ...opts.sidecar,
+        // The kind is what keeps the three chains apart. `gemini_interact`'s
+        // continue_last reads the newest recorded id, and video and music write
+        // records too — without this it could resume an omni interaction, or a
+        // Lyria one, where a chained call is a documented 400.
+        kind,
+        ...(typeof meta?.interaction_id === 'string' ? { interaction_id: meta.interaction_id } : {}),
+        ...(typeof meta?.model === 'string' ? { model: meta.model } : {}),
+    };
+    // `kind` alone is not worth an object — a record earns its place by carrying
+    // something a later caller can act on or recognise.
+    if (!sink.persistsFiles && sink.writeSidecar && (record.interaction_id || record.prompt)) {
+        for (const p of persisted)
+            if (p.key)
+                await sink.writeSidecar(p.key, record);
+    }
     // Note a downgraded inline-video request so the caller isn't left wondering.
     const note = opts.inline && kind === 'video' ? { inline_unsupported: 'video has no MCP inline content type — written to disk instead' } : {};
     // Say where the bytes actually went whenever they are NOT local paths — the
@@ -535,7 +564,7 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
         }
         : {};
     const storage = sink.persistsFiles ? {} : { storage: sink.kind, storage_note: storageNote };
-    return textResult({ [`${kind}s`]: refs, ...media, ...unavailable, ...note, ...storage, ...meta });
+    return minifiedResult({ [`${kind}s`]: refs, ...media, ...unavailable, ...note, ...storage, ...meta });
 }
 /**
  * Image convenience wrapper over {@link emitMedia} — preserves the original
@@ -605,8 +634,9 @@ export async function persistBundle(named, sink, base) {
     }
 }
 /**
- * Inputs that can only come off a local filesystem. On the hosted connector
- * (a Cloudflare Worker) none of them exist:
+ * Inputs that can only come off a local filesystem. The hosted deployment runs
+ * as a child process on mcp-host with no access to the CALLER's machine, so
+ * none of them exist there:
  *
  *  - `images` / `master_images` — file paths read with `node:fs`.
  *  - `from_clipboard` — shells out to `osascript`/`sips` via `child_process`.
@@ -642,12 +672,13 @@ export function assertLocalInputsAvailable(sink, args) {
     // exactly when it is needed.
     const fix = 'Reference images WITHOUT putting bytes in the conversation, in order of preference: ' +
         '(1) `images_url` — public https URLs the server fetches itself; ' +
-        '(2) `images_file_uris` — upload once with `gemini_upload_file` (it takes a `url` or `data_base64`) and reuse the returned files/… uri; ' +
-        '(3) `POST /upload` on this connector with the raw bytes as the body ' +
-        "(`curl -X POST <connector-url>/upload -H 'Authorization: Bearer <token>' -H 'Content-Type: image/jpeg' --data-binary @photo.jpg`), " +
-        'then pass the returned file_uri. ' +
-        'As a last resort `images_base64` still works, but it costs ~14k tokens per photo and breaks on a truncated read. ' +
+        '(2) `images_r2_keys` — mint a signed upload URL with `gemini_get_upload_url`, PUT the file to it, then pass the r2_key back ' +
+        '(the server reads its own store; nothing crosses the conversation); ' +
+        '(3) `images_file_uris` — upload once with `gemini_upload_file` (it takes a `url` or `data_base64`) and reuse the returned files/… uri. ' +
+        'If you CANNOT make HTTP requests at all, routes (1) and (2) are closed to you and the only way to reference a local file ' +
+        'is `images_base64`, which costs ~14k tokens per photo and breaks on a truncated read — the server uploads it once and ' +
+        'returns a files/… uri under image_inputs to reuse on later calls. ' +
         'Reference video by `video_url` (a public YouTube URL, or a files/… uri uploaded elsewhere) instead of `video_path`.';
     throw new McpToolError(`${unavailable.join(', ')} ${unavailable.length > 1 ? 'are' : 'is'} unavailable on the hosted connector: ` +
-        `it runs on a Cloudflare Worker, which has no filesystem and no local clipboard. ${fix}`, { hint: fix });
+        `it runs on a remote machine with no access to your filesystem or clipboard. ${fix}`, { hint: fix });
 }

package/dist/tools/uploads.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
+import { minifiedResult } from '@chrischall/mcp-utils';
 import { UPLOAD_MAX_BYTES, RASTER_IMAGE_TYPE_PATTERN } from '../upload-url.js';
 import { wholeMb } from '../bytes.js';
 import { step } from '../errors.js';
@@ -9,12 +9,12 @@ import { step } from '../errors.js';
  *
  *   curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "<upload_url>"
  *
- * This closes the last gap in the no-bytes-in-the-conversation story. The two
- * existing byte routes each exclude a common caller: `images_base64` costs
- * ~14k tokens per photo and corrupts silently on a truncated read, and
- * `POST /upload` needs the MCP session's OAuth bearer token, which a sandboxed
- * shell doesn't have. A signed URL is mintable by the session and usable by
- * the shell.
+ * This closes the last gap in the no-bytes-in-the-conversation story. The
+ * alternatives each exclude a common caller: `images_base64` costs ~14k tokens
+ * per photo and corrupts silently on a truncated read, and the Worker's old
+ * `POST /upload` (retired with the Worker) needed the MCP session's OAuth
+ * bearer token, which a sandboxed shell does not have. A signed URL is mintable
+ * by the session and usable by the shell.
  *
  * Hosted only — stdio has no HTTP surface to PUT against (and no need: it reads
  * local paths directly). Gated on `client.uploadUrls`, the same pattern as
@@ -71,7 +71,7 @@ export function registerUploadUrlTools(server, client) {
         // between them a mint failure can no longer reach the client as a bare
         // "Error occurred during tool execution".
         const minted = await step(`minting a signed upload URL for ${args.filename} (${args.content_type})`, () => minter.mint(args.filename, args.content_type));
-        return textResult({
+        return minifiedResult({
             upload_url: minted.url,
             method: 'PUT',
             r2_key: minted.key,

package/dist/tools/usage.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { PRICED_AT } from '../pricing.js';
 /**
  * What this session has spent, in tokens.
@@ -51,7 +51,7 @@ export function registerUsageTools(server, client) {
             client.session.costUsd = undefined;
             client.session.pricedCalls = 0;
         }
-        return textResult({
+        return minifiedResult({
             usage: usage ?? null,
             billed_calls: calls,
             estimated_cost_usd: costUsd ?? null,

package/dist/tools/video.js

@@ -3,13 +3,20 @@ import { McpToolError } from '@chrischall/mcp-utils';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_VIDEO_MODEL } from '../models.js';
-import { emitMedia, reportShape, resolveAspectRatio, orientationSchema, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emitMedia, reportShape, resolveAspectRatio, orientationSchema, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { attachCost } from '../pricing.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 /** omni's own aspect-ratio enum — NOT the image tools' ASPECT_RATIOS. */
 const VIDEO_ASPECT_RATIOS = ['16:9', '9:16'];
-const VIDEO_TASKS = ['text_to_video', 'image_to_video', 'reference_to_video', 'edit'];
+const VIDEO_TASKS = ['text_to_video', 'image_to_video', 'reference_to_video', 'edit', 'extend'];
+/**
+ * omni's output resolutions (GA, verified live 2026-09-09). Unlike `delivery`
+ * this is content and not transport: it is the cost lever on the whole video
+ * path, since omni bills video output per token and a 10s clip came back at
+ * ~$0.34 in 360p against roughly triple that in 720p.
+ */
+const VIDEO_RESOLUTIONS = ['360p', '720p', '1080p', '4k'];
 // `delivery` is transport, not content: uri hands back a Files API link the
 // client downloads with the api key, inline returns base64 capped at ~4MB.
 // Left unset here so the client's verified default (uri) applies; this is an
@@ -24,20 +31,23 @@ const VIDEO_DELIVERY = ['inline', 'uri'];
 // "last video" and a "last image" are distinct chains. See src/session.ts.
 export function registerVideoTools(server, client) {
     server.registerTool('gemini_video_generate', {
-        description: 'Generate a short video via the Gemini omni model (preview): text→video, image→video / reference→video ' +
-            '(supply reference image[s]), or edit a prior video (task: "edit" + previous_interaction_id / continue_last). ' +
-            'Output is written to disk as MP4 (video has no inline MCP block). Video runs long — use `async: true` to get a ' +
-            'job_id immediately and poll gemini_get_result, or raise `timeout_ms`. Preview model: needs a funded account.',
+        description: 'Generate a short video (~10s) via the Gemini omni model: text→video, image→video / reference→video ' +
+            '(supply reference image[s]), interpolate between two stills (pass first frame then last frame as images), ' +
+            'or continue a prior video (task: "edit" or "extend" + previous_interaction_id / continue_last; extensions ' +
+            'add ~3-10s each, to ~40s total). Cost scales with `resolution` — draft at 360p, keep at 1080p/4k. ' +
+            'Output is written to disk as MP4 (video has no inline MCP block). Video runs long — give it a `max_wait_ms` budget ' +
+            '(or `async: true` + gemini_get_result on a local install), or raise `timeout_ms`. Needs a funded account.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             prompt: z.string().min(1).describe('Description of the video to generate (or the edit instruction when task=edit)'),
             aspect_ratio: z.enum(VIDEO_ASPECT_RATIOS).optional().describe('Exact output aspect ratio (omni: 16:9 or 9:16). `orientation` is the plain-language shorthand; this wins if both are given.'),
             orientation: orientationSchema,
-            task: z.enum(VIDEO_TASKS).optional().describe('text_to_video (default), image_to_video / reference_to_video (need image input), or edit (needs previous_interaction_id)'),
+            task: z.enum(VIDEO_TASKS).optional().describe('text_to_video (default), image_to_video / reference_to_video (need image input), or edit / extend (need previous_interaction_id)'),
+            resolution: z.enum(VIDEO_RESOLUTIONS).optional().describe('Output resolution (default 720p). Video is billed per output token, so 360p costs roughly a third of 720p — use it for drafts'),
             images: z.array(z.string().min(1)).optional().describe('Reference image path(s) for image_to_video / reference_to_video'),
             images_url: imagesUrlSchema('Reference stills'),
             images_file_uris: imagesFileUrisSchema('Reference stills'),
-            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
+            images_base64: imagesBase64Schema(),
             from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS clipboard as a reference'),
             filename: z.string().optional().describe('Base filename for the output video (extension stripped; default: slugified prompt)'),
             output_dir: z.string().optional().describe('Directory to write the video to (default: $GEMINI_OUTPUT_DIR or cwd)'),
@@ -78,7 +88,9 @@ export function registerVideoTools(server, client) {
         // fingerprint so "portrait" and "9:16" dedup to one billable job.
         const aspectRatio = resolveAspectRatio(args, VIDEO_ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_video_generate', {
-            model, prompt: args.prompt, aspect_ratio: aspectRatio, task: args.task,
+            // `resolution` is IN the fingerprint (a 4k render is not the 360p one)
+            // where `delivery` is not (same bytes, different transport).
+            model, prompt: args.prompt, aspect_ratio: aspectRatio, resolution: args.resolution, task: args.task,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
@@ -90,6 +102,7 @@ export function registerVideoTools(server, client) {
                 images: inputs.length ? inputs : undefined,
                 model: args.model,
                 aspectRatio,
+                resolution: args.resolution,
                 task: args.task,
                 previousInteractionId,
                 timeoutMs: args.timeout_ms,
@@ -104,6 +117,10 @@ export function registerVideoTools(server, client) {
             // The RESOLVED ratio: omni takes only 16:9/9:16, so a caller who asked
             // in words can see which of the two their request became.
             const meta = reportShape({ model, interaction_id: r.id }, { ...args, aspect_ratio: aspectRatio });
+            // Echoed for the same reason the resolved ratio is: it changed what
+            // the caller was billed, so it has to be visible in the result.
+            if (args.resolution)
+                meta.resolution = args.resolution;
             if (previousInteractionId)
                 meta.previous_interaction_id = previousInteractionId;
             if (r.usage)
@@ -119,7 +136,7 @@ export function registerVideoTools(server, client) {
                 media,
                 base: r.videos.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
             }));
-            return emitMedia(named, 'video', { output_dir: args.output_dir, sink: client.mediaSink }, meta);
+            return emitMedia(named, 'video', { output_dir: args.output_dir, sink: client.mediaSink, sidecar: { prompt: args.prompt } }, meta);
         });
     });
 }

package/dist/upload-url.js

@@ -5,9 +5,9 @@
  * The problem these solve is the mirror image of `/media`: a signed GET lets a
  * shell *download* generated media with no auth header, but uploading a
  * reference photo still required `images_base64` (~14k tokens per JPEG, silently
- * corrupting on a truncated read) or `POST /upload` (which 401s from any shell
- * that doesn't hold the MCP session's bearer token). A signed PUT URL closes
- * that gap: the authenticated MCP session mints it, and then a bare
+ * corrupting on a truncated read) or the Worker's `POST /upload`, which 401'd
+ * from any shell without the MCP session's bearer token and is gone entirely
+ * now that the Worker is. A signed PUT URL closes that gap: the authenticated MCP session mints it, and then a bare
  * `curl -X PUT --data-binary @photo.jpg "<url>"` stores the bytes.
  *
  * Same HMAC secret as the media GET URLs, but a DIFFERENT payload shape, so the

package/dist/version.js

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

package/mint.yaml

@@ -38,6 +38,12 @@ env:
       How often, in milliseconds, to emit a progress notification while a
       generation is in flight. Hosts reset their tools/call timeout on progress,
       so this lets a long 4K/Pro generation outlive the default budget.
+  - name: GEMINI_RATE_CARD
+    required: false
+    help: >-
+      JSON overriding or extending the built-in pricing card, so a stale rate is
+      yours to fix in your own environment rather than waiting on a release.
+      Anything absent from the card prices as unknown rather than zero.
 egress:
   allow:
     # Only hosts the SERVER process actually fetches. Hosts that appear

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.12.0",
+  "version": "1.14.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>",
@@ -46,16 +46,16 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.19.2",
+    "@chrischall/mcp-utils": "^0.23.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/coverage-v8": "^5.0.0",
     "esbuild": "^0.28.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.2"
+    "vitest": "^5.0.0"
   }
 }

package/server.json

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

package/skills/gemini-mcp/SKILL.md

@@ -118,6 +118,9 @@ not an error.
   any number of calls until then.
 - On stdio, an `images` path referenced **more than once in a session** is auto-uploaded to the
   Files API (keyed on path + mtime + size) so the bytes stop being re-sent.
+- `images_base64` is uploaded on the **first** sighting, not the second — the tokens are already
+  spent by then. The result reports it under `image_inputs.base64_uploaded[].file_uri`: pass that
+  to `images_file_uris` on the next call instead of pasting the bytes again.
 
 ### Files API
 | Tool | Description |
@@ -145,8 +148,8 @@ curl -X POST https://<hosted deployment>/upload \
 ### Video & Music (preview — funded account)
 | Tool | Description |
 |------|-------------|
-| `gemini_video_generate(prompt, aspect_ratio?, task?, images_url?, images_file_uris?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, model?, filename?, output_dir?, timeout_ms?, idempotency_key?, async?)` | Generate a short video via the Gemini omni model: `text_to_video` (default), `image_to_video` / `reference_to_video` (supply reference image[s]), or `edit` (with `previous_interaction_id` / `continue_last`). `aspect_ratio` is `16:9` or `9:16`. Written to disk as **MP4**. Runs long — use `async: true` + `gemini_get_result`, or raise `timeout_ms`. |
-| `gemini_music_generate(prompt, model?, audio_format?, images_url?, images_file_uris?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, filename?, output_dir?, inline?, timeout_ms?, idempotency_key?, async?)` | Generate music from a prompt (mood/genre/instruments/structure/lyrics) via a Lyria model: `lyria-3-clip-preview` (~30s, default) or `lyria-3-pro-preview` (longer, WAV-capable). `audio_format` `mp3` (default) or `wav` (**Pro-only**). Written to disk as MP3/WAV, or returned inline. |
+| `gemini_video_generate(prompt, aspect_ratio?, resolution?, task?, images_url?, images_file_uris?, images?, images_base64?, from_clipboard?, previous_interaction_id?, continue_last?, model?, filename?, output_dir?, timeout_ms?, idempotency_key?, async?)` | Generate a short video (~10s) via the Gemini omni model: `text_to_video` (default), `image_to_video` / `reference_to_video` (supply reference image[s]), interpolation (pass first frame then last frame as `images`), or `edit` / `extend` (with `previous_interaction_id` / `continue_last`; extensions add ~3-10s each, to ~40s). `aspect_ratio` is `16:9` or `9:16`; `resolution` is `360p`/`720p` (default)/`1080p`/`4k` and is the cost lever — a 10s 360p clip runs about a third of 720p. Written to disk as **MP4**. Runs long — use `async: true` + `gemini_get_result`, or raise `timeout_ms`. |
+| `gemini_music_generate(prompt, model?, images_url?, images_file_uris?, images?, images_base64?, from_clipboard?, filename?, output_dir?, inline?, timeout_ms?, idempotency_key?, async?)` | Generate music from a prompt (mood/genre/instruments/structure/lyrics) via a Lyria model: `lyria-3-clip-preview` (30s instrumental, default, $0.04), `lyria-3.5` (full-length song with vocals, $0.08) or `lyria-3-pro-preview` ($0.08). Output is MP3. **Single-turn** — there is no follow-up refinement, so put the whole brief in the prompt. Written to disk, or returned inline. |
 
 ### Async / idempotency (any generation tool)
 | Tool | Description |
@@ -217,7 +220,8 @@ gemini_image_edit(
 → returns path to the edited image
 ```
 `images_base64` is for bytes you actually have — a file you `Read`/encode, a URL
-you fetch, or a `data:` URI the user pastes as **text**.
+you fetch, or a `data:` URI the user pastes as **text**. Send them once: the result's
+`image_inputs.base64_uploaded[].file_uri` is a `files/<id>` to reuse via `images_file_uris`.
 
 **Iterate on ONE image conversationally (multi-turn):**
 ```
@@ -231,21 +235,25 @@ r3 = gemini_interact(input: "warmer lighting", continue_last: true)
 ```
 Prefer this over re-running `gemini_image_edit` when you're making a *series* of incremental edits — the model keeps the prior result in context. Every result echoes `interaction_id` (and `previous_interaction_id` when chaining) plus a `hint` with the exact follow-up call.
 
-**Generate a video (preview — runs long, use async):**
+**Generate a video (runs long, use async):**
 ```
 job = gemini_video_generate(prompt: "a paper boat sailing down a rain gutter, cinematic",
-                            aspect_ratio: "16:9", async: true)
+                            aspect_ratio: "16:9", resolution: "360p", async: true)
    → { job_id, status: "running" }   (returns immediately — no host timeout)
 gemini_get_result(job_id: job.job_id)
    → "running" until done, then the MP4 path on disk
+# Draft at 360p, re-run the keeper at 1080p — video bills per output token, so the
+# resolution is roughly the price.
 # Animate a still instead: gemini_video_generate(prompt: "…", task: "image_to_video", images: ["/path/still.png"])
+# Interpolate between two stills: images: ["/path/first.png", "/path/last.png"]
+# Extend a clip: gemini_video_generate(prompt: "…", task: "extend", continue_last: true)
 ```
 
-**Generate music (preview):**
+**Generate music:**
 ```
 gemini_music_generate(prompt: "warm lo-fi hip hop, mellow Rhodes, vinyl crackle, 70bpm")
-   → ~30s MP3 on disk (lyria-3-clip-preview)
-# Longer / WAV: gemini_music_generate(prompt: "…", model: "lyria-3-pro-preview", audio_format: "wav")
+   → 30s MP3 on disk (lyria-3-clip-preview)
+# Full-length song with vocals: gemini_music_generate(prompt: "…", model: "lyria-3.5")
 ```
 **⚠️ Chat-pasted/attached images can't be fed to these tools directly.** A pasted
 image reaches the assistant as a *vision* block — the assistant can SEE it but