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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -83,6 +83,7 @@ progress), two guards make re-issuing safe and unnecessary:
 | `gemini_video_generate` | Generate a short video (text→video, image→video, or `edit`) via the Gemini omni model (preview); written to disk as MP4 |
 | `gemini_music_generate` | Generate music from a text prompt via a Lyria model — `lyria-3-clip-preview` (~30s, default) or `lyria-3-pro-preview` (longer, WAV-capable); written to disk as MP3/WAV (preview) |
 | `gemini_get_result` | Fetch an async generation started with `async: true` by its `job_id` (status `running` → `done` result). Lets a long generation outlive a host's `tools/call` timeout |
+| `gemini_token_usage` | Token usage and an estimated USD cost for this session so far. Call it before and after a workflow and subtract to attribute that workflow's spend. Priced per call against each call's own model from a dated rate card (`GEMINI_RATE_CARD` overrides it); there is no account-balance endpoint to read, so this is how spend is attributed |
 | `gemini_upload_file` | Upload an image (or video/audio) to the Gemini Files API once — from a `url`, `data_base64`, or a local `path` — and get a reusable `files/<id>` reference |
 | `gemini_list_files` | List the files currently uploaded under this API key, with MIME types and expiry times |
 | `gemini_delete_file` | Delete an uploaded file before its ~48h expiry (confirm-gated) |

package/dist/bundle.js

@@ -32549,6 +32549,14 @@ var init_parse_lenient = __esm({
 });
 
 // node_modules/@chrischall/mcp-utils/dist/zod/index.js
+function toolAnnotations(opts = {}) {
+  return {
+    ...opts.title !== void 0 ? { title: opts.title } : {},
+    readOnlyHint: opts.readOnly ?? true,
+    ...opts.idempotent !== void 0 ? { idempotentHint: opts.idempotent } : {},
+    ...opts.openWorld !== void 0 ? { openWorldHint: opts.openWorld } : {}
+  };
+}
 var PositiveInt, NonNegInt, NonEmptyString, IsoDate, IsoTime, NumericIdString, SafePathSegment, schemaOrigin, schemaConfirm, paginationSchema, pageSchema;
 var init_zod2 = __esm({
   "node_modules/@chrischall/mcp-utils/dist/zod/index.js"() {
@@ -32868,7 +32876,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.10.0";
+var VERSION = "1.11.0";
 
 // src/errors.ts
 init_dist();
@@ -33972,6 +33980,98 @@ function createBlobJobStore(bucket, opts) {
   };
 }
 
+// src/usage.ts
+var num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+function modalityTokens(list, modality) {
+  if (!Array.isArray(list)) return void 0;
+  for (const entry of list) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry;
+    if (typeof e.modality === "string" && e.modality.toLowerCase() === modality) {
+      return num(e.tokenCount) ?? num(e.tokens);
+    }
+  }
+  return void 0;
+}
+function readUsage(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const b = body;
+  const meta3 = b.usageMetadata;
+  if (meta3) {
+    const input = num(meta3.promptTokenCount);
+    const output = num(meta3.candidatesTokenCount);
+    const total = num(meta3.totalTokenCount);
+    if (input !== void 0 || output !== void 0 || total !== void 0) {
+      return compact({
+        input_tokens: input ?? 0,
+        output_tokens: output ?? 0,
+        total_tokens: total ?? (input ?? 0) + (output ?? 0),
+        image_tokens: modalityTokens(meta3.candidatesTokensDetails, "image"),
+        video_tokens: modalityTokens(meta3.candidatesTokensDetails, "video"),
+        audio_tokens: modalityTokens(meta3.candidatesTokensDetails, "audio"),
+        cached_tokens: num(meta3.cachedContentTokenCount)
+      });
+    }
+  }
+  const usage = b.usage;
+  if (usage) {
+    const input = num(usage.total_input_tokens);
+    const output = num(usage.total_output_tokens);
+    const total = num(usage.total_tokens);
+    if (input !== void 0 || output !== void 0 || total !== void 0) {
+      return compact({
+        input_tokens: input ?? 0,
+        output_tokens: output ?? 0,
+        total_tokens: total ?? (input ?? 0) + (output ?? 0),
+        image_tokens: modalityTokens(usage.output_tokens_by_modality, "image"),
+        video_tokens: modalityTokens(usage.output_tokens_by_modality, "video"),
+        audio_tokens: modalityTokens(usage.output_tokens_by_modality, "audio"),
+        cached_tokens: num(usage.total_cached_tokens),
+        thought_tokens: num(usage.total_thought_tokens)
+      });
+    }
+  }
+  return void 0;
+}
+function compact(u) {
+  const out = {
+    input_tokens: u.input_tokens,
+    output_tokens: u.output_tokens,
+    total_tokens: u.total_tokens
+  };
+  if (u.image_tokens) out.image_tokens = u.image_tokens;
+  if (u.video_tokens) out.video_tokens = u.video_tokens;
+  if (u.audio_tokens) out.audio_tokens = u.audio_tokens;
+  if (u.cached_tokens) out.cached_tokens = u.cached_tokens;
+  if (u.thought_tokens) out.thought_tokens = u.thought_tokens;
+  return out;
+}
+function sumUsage(parts) {
+  const known = parts.filter((p) => p !== void 0);
+  if (known.length === 0) return void 0;
+  return compact(
+    known.reduce(
+      (acc, u) => ({
+        input_tokens: acc.input_tokens + u.input_tokens,
+        output_tokens: acc.output_tokens + u.output_tokens,
+        total_tokens: acc.total_tokens + u.total_tokens,
+        image_tokens: (acc.image_tokens ?? 0) + (u.image_tokens ?? 0),
+        video_tokens: (acc.video_tokens ?? 0) + (u.video_tokens ?? 0),
+        audio_tokens: (acc.audio_tokens ?? 0) + (u.audio_tokens ?? 0),
+        cached_tokens: (acc.cached_tokens ?? 0) + (u.cached_tokens ?? 0),
+        thought_tokens: (acc.thought_tokens ?? 0) + (u.thought_tokens ?? 0)
+      }),
+      { input_tokens: 0, output_tokens: 0, total_tokens: 0 }
+    )
+  );
+}
+function annotateReusedUsage(meta3) {
+  if (!meta3.usage) return meta3;
+  meta3.usage_billed = false;
+  if (meta3.cost_estimate) meta3.cost_billed = false;
+  return meta3;
+}
+
 // src/jobs.ts
 var JOB_TTL_MS = 6e5;
 var DURABLE_JOB_REUSE_MS = 24 * 60 * 60 * 1e3;
@@ -34052,6 +34152,7 @@ function annotateReused(result, jobId) {
     }
     obj.reused = true;
     obj.reused_job_id = jobId;
+    annotateReusedUsage(obj);
     return { ...result, content: [{ ...first, text: JSON.stringify(obj, null, 2) }, ...content.slice(1)] };
   }
   return {
@@ -34437,6 +34538,113 @@ var JobRegistry = class {
 };
 var JOB_RECORD_RETENTION_LABEL = "30 days";
 
+// src/pricing.ts
+init_dist();
+var PRICED_AT = "2026-08-28";
+var RATE_CARD = Object.freeze({
+  "gemini-3-pro-image": { input: 2, text_output: 12, image_output: 120 },
+  "gemini-3.1-flash-image": { input: 0.5, text_output: 3, image_output: 60 },
+  "gemini-3.1-flash-lite-image": { input: 0.25, text_output: 1.5, image_output: 30 },
+  // Google publishes 2.5-flash-image's output as $0.039 PER IMAGE at 1290
+  // tokens, not as a per-1M rate. 0.039 / 1290 * 1e6 = 30.23 — a back-derived
+  // figure, unlike the four above which are published per-1M directly. The
+  // test reconciles it against the $0.039 it came from.
+  "gemini-2.5-flash-image": { input: 0.3, text_output: 3, image_output: 30.2326 },
+  // Omni is token-billed for video: $17.50/1M at ~5,792 tokens per second of
+  // 720p, which is the ~$0.10/second Google quotes. Veo is the per-second
+  // family; this server does not use it.
+  //
+  // No image-output price is published for omni, so there is no image_output
+  // here. An absent rate prices that modality at zero rather than inventing
+  // one — and the first version of this entry DID invent one ($60, copied
+  // from flash-image), along with a $0.50 input and $3.00 text rate that were
+  // both a third of the real figures. Every number here is now quoted.
+  "gemini-omni-flash": { input: 1.5, text_output: 9, video_output: 17.5 },
+  // Lyria bills per song, so tokens describe the work and not the bill.
+  "lyria-3-clip": { input: 0, text_output: 0, per_generation: 0.04 },
+  "lyria-3-pro": { input: 0, text_output: 0, per_generation: 0.08 }
+});
+function normalizeModel(model) {
+  return model.replace(/-preview$/, "");
+}
+function loadRateCard(env = process.env) {
+  const raw = readEnvVar("GEMINI_RATE_CARD", { env });
+  if (!raw) return { ...RATE_CARD };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ...RATE_CARD };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { ...RATE_CARD };
+  const out = { ...RATE_CARD };
+  for (const [model, override] of Object.entries(parsed)) {
+    if (!override || typeof override !== "object" || Array.isArray(override)) continue;
+    const key = normalizeModel(model);
+    const merged = { ...RATE_CARD[key] ?? {}, ...out[key] ?? {} };
+    for (const [field, value] of Object.entries(override)) {
+      if (typeof value === "number" && Number.isFinite(value)) merged[field] = value;
+    }
+    if (typeof merged.input === "number" && typeof merged.text_output === "number") {
+      out[key] = merged;
+    }
+  }
+  return out;
+}
+function estimateCost(model, usage, env = process.env) {
+  const card = loadRateCard(env);
+  const key = normalizeModel(model);
+  const rates = card[key];
+  if (!rates) return void 0;
+  const per = (tokens, rate) => (
+    // An absent rate prices as zero, never NaN. A modality with no published
+    // rate is not evidence of spend, and NaN is absorbing — it would poison
+    // every later total in the session.
+    typeof rate === "number" && Number.isFinite(rate) ? tokens * rate / 1e6 : 0
+  );
+  if (typeof rates.per_generation === "number") {
+    return {
+      usd: rates.per_generation,
+      breakdown: {
+        input_usd: 0,
+        text_output_usd: 0,
+        image_usd: 0,
+        video_usd: 0,
+        audio_usd: 0,
+        per_generation_usd: rates.per_generation
+      },
+      priced_at: PRICED_AT,
+      ...overriddenFor(key, rates) ? { overridden: true } : {}
+    };
+  }
+  const imageTokens = usage.image_tokens ?? 0;
+  const videoTokens = usage.video_tokens ?? 0;
+  const audioTokens = usage.audio_tokens ?? 0;
+  const textTokens = Math.max(0, usage.output_tokens - imageTokens - videoTokens - audioTokens);
+  const input_usd = per(usage.input_tokens, rates.input);
+  const text_output_usd = per(textTokens, rates.text_output);
+  const image_usd = per(imageTokens, rates.image_output);
+  const video_usd = per(videoTokens, rates.video_output);
+  const audio_usd = per(audioTokens, rates.audio_output);
+  return {
+    usd: input_usd + text_output_usd + image_usd + video_usd + audio_usd,
+    breakdown: { input_usd, text_output_usd, image_usd, video_usd, audio_usd },
+    priced_at: PRICED_AT,
+    ...overriddenFor(key, rates) ? { overridden: true } : {}
+  };
+}
+function overriddenFor(key, rates) {
+  const shipped = RATE_CARD[key];
+  if (!shipped) return true;
+  return Object.keys(rates).some((f) => rates[f] !== shipped[f]);
+}
+function attachCost(meta3, model, usage) {
+  if (!usage) return meta3;
+  const cost = estimateCost(model, usage);
+  if (cost) meta3.cost_estimate = cost;
+  return meta3;
+}
+
 // src/tools/_confirm.ts
 init_dist();
 init_images();
@@ -34526,6 +34734,7 @@ function registerGenerateTools(server, client2) {
         let capturedGrounding;
         const failed = [];
         let firstError;
+        const usages = [];
         await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : "image"} (${model})`, async () => {
           for (let i = 0; i < count; i++) {
             try {
@@ -34543,6 +34752,7 @@ function registerGenerateTools(server, client2) {
                 timeoutMs: args.timeout_ms
               });
               const { images: [img], text } = result;
+              usages.push(result.usage);
               if (text && !capturedText) capturedText = text;
               if (result.grounding && !capturedGrounding) capturedGrounding = result.grounding;
               named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, "0")}` });
@@ -34554,6 +34764,9 @@ function registerGenerateTools(server, client2) {
         });
         if (named.length === 0) throw firstError;
         const meta3 = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
+        const usage = sumUsage(usages);
+        if (usage) meta3.usage = usage;
+        attachCost(meta3, model, usage);
         if (capturedText) meta3.text = capturedText;
         if (capturedGrounding) meta3.grounding = capturedGrounding;
         if (report) meta3.image_inputs = report;
@@ -34632,6 +34845,8 @@ function registerGenerateTools(server, client2) {
         }));
         const { images: [img], text } = result;
         const meta3 = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
+        if (result.usage) meta3.usage = result.usage;
+        attachCost(meta3, model, result.usage);
         if (text) meta3.text = text;
         if (result.grounding) meta3.grounding = result.grounding;
         if (report) meta3.image_inputs = report;
@@ -34720,6 +34935,7 @@ function registerSetTools(server, client2) {
         const failed = [];
         const report = carried.report || masterOnly.report ? { ...masterOnly.report, ...carried.report } : void 0;
         const named = [];
+        const usages = [];
         const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
           const result = await client2.generate({
             prompt: masterPrompt,
@@ -34727,6 +34943,7 @@ function registerSetTools(server, client2) {
             seed,
             ...cfg
           });
+          usages.push(result.usage);
           const master = result.images[0];
           named.push({ image: master, base: `${slug}-master` });
           const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
@@ -34743,7 +34960,9 @@ function registerSetTools(server, client2) {
             let ref = master;
             for (let i = 0; i < scenePrompts.length; i++) {
               try {
-                const { images: [img] } = await client2.generate({ prompt: composePrompt(scenePrompts[i], styleOnly), images: [ref, ...carriedRefs], seed: seed + i + 1, ...cfg });
+                const scene = await client2.generate({ prompt: composePrompt(scenePrompts[i], styleOnly), images: [ref, ...carriedRefs], seed: seed + i + 1, ...cfg });
+                usages.push(scene.usage);
+                const img = scene.images[0];
                 named.push({ image: img, base: sceneName(i) });
                 ref = img;
               } catch (err) {
@@ -34752,7 +34971,10 @@ function registerSetTools(server, client2) {
             }
           } else {
             const settled = await Promise.allSettled(
-              scenePrompts.map((p, i) => client2.generate({ prompt: composePrompt(p, styleOnly), images: [master, ...carriedRefs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
+              scenePrompts.map((p, i) => client2.generate({ prompt: composePrompt(p, styleOnly), images: [master, ...carriedRefs], seed: seed + i + 1, ...cfg }).then((r) => {
+                usages.push(r.usage);
+                return r.images[0];
+              }))
             );
             settled.forEach((outcome, i) => {
               if (outcome.status === "fulfilled") named.push({ image: outcome.value, base: sceneName(i) });
@@ -34763,6 +34985,9 @@ function registerSetTools(server, client2) {
         });
         const masterText = masterResult.text;
         const meta3 = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
+        const usage = sumUsage(usages);
+        if (usage) meta3.usage = usage;
+        attachCost(meta3, model, usage);
         if (masterText) meta3.text = masterText;
         if (masterResult.grounding) meta3.grounding = masterResult.grounding;
         if (report) meta3.image_inputs = report;
@@ -35109,9 +35334,56 @@ var SessionState = class {
     }
     return hit;
   }
+  /**
+   * Everything this session has spent, in tokens, across every upstream call.
+   *
+   * Accumulated in the CLIENT rather than in the tools, so a call that was
+   * billed and then failed (a safety filter returning no image, say) still
+   * counts — it cost money regardless of whether a tool could use the result.
+   * Per session, never module scope: one hosted process serves many tenants,
+   * and a shared total would report other people's spend as yours.
+   */
+  usageTotal;
+  /** How many upstream calls contributed to {@link usageTotal}. */
+  billedCalls = 0;
+  /**
+   * What this session has spent in USD, priced per call.
+   *
+   * Accumulated as calls happen rather than derived from {@link usageTotal} at
+   * the end, because the total spans models: summing a Pro call's tokens with
+   * a Lite call's and pricing the result at one rate would be wrong by up to
+   * 4x. Each call is priced against ITS model and only the money is added up.
+   *
+   * `undefined` while nothing priceable has run — a model absent from the rate
+   * card contributes usage but no cost, so a total of `undefined` beside a
+   * non-zero usage is meaningful rather than a bug. (Video and music DO price:
+   * omni is token-billed and Lyria bills per song. It is an unknown or
+   * newly-released model id that goes unpriced.)
+   */
+  costUsd;
+  /** How many of {@link billedCalls} could actually be priced. */
+  pricedCalls = 0;
+  /**
+   * Fold one upstream call's usage into the running totals. `model` is what
+   * makes the cost side possible; without it the tokens still count.
+   */
+  recordUsage(usage, model) {
+    if (!usage) return;
+    this.usageTotal = sumUsage([this.usageTotal, usage]);
+    this.billedCalls += 1;
+    if (!model) return;
+    const cost = estimateCost(model, usage);
+    if (!cost) return;
+    this.costUsd = (this.costUsd ?? 0) + cost.usd;
+    this.pricedCalls += 1;
+  }
   /** Forget everything. Tests use this; nothing in `src/` calls it. */
   reset() {
     this.jobs.reset();
+    this.usageTotal = void 0;
+    this.billedCalls = 0;
+    this.costUsd = void 0;
+    this.pricedCalls = 0;
     this.lastInteractionId = void 0;
     this.lastMusicInteractionId = void 0;
     this.lastVideoInteractionId = void 0;
@@ -35532,6 +35804,16 @@ var GeminiClient = class {
     const data = await this.call("GET", "/models?pageSize=200");
     return filterImageModels(data.models ?? []);
   }
+  /**
+   * Fold one call's usage into the session total and hand it straight back, so
+   * a call site reads `const usage = this.recordUsage(readUsage(data), model)` right
+   * where the response lands — before any "returned no media" throw, so a
+   * billed call that a safety filter emptied is still counted.
+   */
+  recordUsage(usage, model) {
+    this.session.recordUsage(usage, model);
+    return usage;
+  }
   async generate(opts) {
     const model = resolveModel(opts.model, readEnvVar("GEMINI_IMAGE_MODEL"));
     const parts = [{ text: opts.prompt }];
@@ -35556,6 +35838,7 @@ var GeminiClient = class {
       requestBody,
       resolveTimeoutMs(opts.timeoutMs, opts.imageSize)
     );
+    const usage = this.recordUsage(readUsage(data), model);
     const images = [];
     const textParts = [];
     let groundingMeta;
@@ -35586,7 +35869,7 @@ var GeminiClient = class {
         if (sources.length > 0) grounding.sources = sources;
       }
     }
-    return { images, text, grounding };
+    return { images, text, grounding, usage };
   }
   async interact(opts) {
     const model = resolveModel(opts.model, readEnvVar("GEMINI_IMAGE_MODEL"));
@@ -35607,13 +35890,14 @@ var GeminiClient = class {
       body.tools = [searchTool];
     }
     const data = await this.postInteraction(body, opts);
+    const usage = this.recordUsage(readUsage(data), model);
     const { images, text, grounding } = this.extractInteraction(data, opts.searchTypes);
     if (images.length === 0) {
       throw new McpToolError("Gemini returned no image", {
         hint: "The request may have been blocked by safety filters \u2014 try rephrasing the prompt."
       });
     }
-    return { id: data.id, images: await this.downloadAll(images), text, grounding };
+    return { id: data.id, images: await this.downloadAll(images), text, grounding, usage };
   }
   /**
    * Generate video via the omni model (Interactions API). Same plumbing as
@@ -35652,13 +35936,14 @@ var GeminiClient = class {
       started = await this.startInteraction(body, opts, timeoutMs);
     }
     const data = await this.settleInteraction(started, body, timeoutMs);
+    const usage = this.recordUsage(readUsage(data), model);
     const { videos, text } = this.extractInteraction(data);
     if (videos.length === 0) {
       throw new McpToolError("Gemini returned no video", {
         hint: "The request may have been blocked by a safety filter \u2014 try a shorter/simpler prompt or a different aspect ratio."
       });
     }
-    return { id: data.id, videos: await this.downloadAll(videos), text };
+    return { id: data.id, videos: await this.downloadAll(videos), text, usage };
   }
   /**
    * Generate music via a Lyria model (Interactions API, inline audio). Reuses
@@ -35674,13 +35959,14 @@ var GeminiClient = class {
     if (opts.previousInteractionId !== void 0) body.previous_interaction_id = opts.previousInteractionId;
     if (opts.background === true) body.background = true;
     const data = await this.postInteraction(body, opts);
+    const usage = this.recordUsage(readUsage(data), model);
     const { audios, text } = this.extractInteraction(data);
     if (audios.length === 0) {
       throw new McpToolError("Gemini returned no audio", {
         hint: "The request may have been blocked by a safety filter \u2014 try rephrasing the prompt."
       });
     }
-    return { id: data.id, audios: await this.downloadAll(audios), text };
+    return { id: data.id, audios: await this.downloadAll(audios), text, usage };
   }
   /**
    * POST `/interactions`, wait out the store lag on a chained 404, and — when
@@ -36203,6 +36489,8 @@ function registerInteractTools(server, client2) {
         if (continuedFromSidecar) meta3.continued_from_sidecar = true;
         if (dropped.length) meta3.dropped_previous_output = dropped;
         meta3.hint = `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) \u2014 do NOT re-attach the returned image as an input; the interaction already contains it.`;
+        if (r.usage) meta3.usage = r.usage;
+        attachCost(meta3, model, r.usage);
         if (r.text) meta3.text = r.text;
         if (r.grounding) meta3.grounding = r.grounding;
         if (report) meta3.image_inputs = report;
@@ -36311,6 +36599,8 @@ function registerVideoTools(server, client2) {
         client2.session.lastVideoInteractionId = r.id;
         const meta3 = reportShape({ model, interaction_id: r.id }, { ...args, aspect_ratio: aspectRatio });
         if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
+        if (r.usage) meta3.usage = r.usage;
+        attachCost(meta3, model, r.usage);
         if (r.text) meta3.text = r.text;
         if (report) meta3.image_inputs = report;
         meta3.hint = `To edit this video, call gemini_video_generate again with task: "edit" and previous_interaction_id: "${r.id}" (or continue_last: true).`;
@@ -36408,6 +36698,8 @@ function registerMusicTools(server, client2) {
         client2.session.lastMusicInteractionId = r.id;
         const meta3 = { model, interaction_id: r.id };
         if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
+        if (r.usage) meta3.usage = r.usage;
+        attachCost(meta3, model, r.usage);
         if (r.text) meta3.text = r.text;
         if (report) meta3.image_inputs = report;
         meta3.hint = `To continue this track, call gemini_music_generate again with previous_interaction_id: "${r.id}" (or continue_last: true).`;
@@ -36503,6 +36795,45 @@ function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
+// src/tools/usage.ts
+init_zod();
+init_dist();
+function registerUsageTools(server, client2) {
+  server.registerTool(
+    "gemini_token_usage",
+    {
+      description: "Token usage for this session so far \u2014 what every generation has cost in tokens, added up. Call it before and after a workflow and subtract to get that workflow's cost; call it after a single generation for that call's. Reports tokens AND an estimated USD cost, priced per call against each call's own model and stamped with the date its rates were read (override with GEMINI_RATE_CARD). Note there is no account-balance endpoint to query \u2014 Google Cloud is post-paid and its billing data lags by hours \u2014 so this is the accurate way to attribute spend to a call.",
+      annotations: toolAnnotations({ readOnly: true }),
+      inputSchema: {
+        reset: external_exports.boolean().optional().describe("Zero the running total after reporting it, so the next call measures from here. Use it to bracket a workflow without arithmetic.")
+      }
+    },
+    async (args) => {
+      const usage = client2.session.usageTotal;
+      const calls = client2.session.billedCalls;
+      const costUsd = client2.session.costUsd;
+      const priced = client2.session.pricedCalls;
+      if (args.reset) {
+        client2.session.usageTotal = void 0;
+        client2.session.billedCalls = 0;
+        client2.session.costUsd = void 0;
+        client2.session.pricedCalls = 0;
+      }
+      return textResult({
+        usage: usage ?? null,
+        billed_calls: calls,
+        estimated_cost_usd: costUsd ?? null,
+        priced_calls: priced,
+        rates_published: PRICED_AT,
+        ...args.reset ? { reset: true } : {},
+        note: usage === void 0 ? "No generation has run in this session yet, so nothing has been billed through it." : priced < calls ? `Estimate covers ${priced} of ${calls} billed calls \u2014 the rest used a model that is not in the rate card. Add it with GEMINI_RATE_CARD to include it.` : "Estimate priced per call against each call's own model, then added up.",
+        rates: `Published rates read on ${PRICED_AT} (paid tier, USD). Override or extend with GEMINI_RATE_CARD if they have moved \u2014 an estimate is only as current as its card.`,
+        scope: "This session only. A restart starts from zero, and a hosted deployment counts each authenticated session separately \u2014 these are your tokens, not the account's."
+      });
+    }
+  );
+}
+
 // src/tools/files.ts
 init_zod();
 init_dist();
@@ -36953,6 +37284,7 @@ var TOOL_REGISTRARS = [
   registerVideoTools,
   registerMusicTools,
   registerJobTools,
+  registerUsageTools,
   registerFileTools,
   registerUploadUrlTools,
   registerLibraryTools

package/dist/client.js

@@ -1,6 +1,7 @@
 import { basename } from 'node:path';
 import { readEnvVar, McpToolError, ApiError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
 import { resolveModel, filterImageModels, DEFAULT_VIDEO_MODEL, DEFAULT_MUSIC_MODEL } from './models.js';
+import { readUsage } from './usage.js';
 import { createDiskSink, createR2Sink, tenantIdFor } from './storage/media.js';
 import { createR2Library } from './library.js';
 import { createUploadUrlMinter } from './upload-url.js';
@@ -560,6 +561,16 @@ export class GeminiClient {
         const data = await this.call('GET', '/models?pageSize=200');
         return filterImageModels(data.models ?? []);
     }
+    /**
+     * Fold one call's usage into the session total and hand it straight back, so
+     * a call site reads `const usage = this.recordUsage(readUsage(data), model)` right
+     * where the response lands — before any "returned no media" throw, so a
+     * billed call that a safety filter emptied is still counted.
+     */
+    recordUsage(usage, model) {
+        this.session.recordUsage(usage, model);
+        return usage;
+    }
     async generate(opts) {
         const model = resolveModel(opts.model, readEnvVar('GEMINI_IMAGE_MODEL'));
         const parts = [{ text: opts.prompt }];
@@ -585,6 +596,11 @@ export class GeminiClient {
         if (opts.googleSearch)
             requestBody.tools = [{ google_search: {} }];
         const data = await this.call('POST', `/models/${model}:generateContent`, requestBody, resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
+        // Recorded HERE, not at the return: the call is already billed by the
+        // time the response lands, and the "no image" throw below is a real
+        // outcome of a PAID request (a safety filter). Recording at the return
+        // omitted exactly the calls this total exists to catch.
+        const usage = this.recordUsage(readUsage(data), model);
         const images = [];
         const textParts = [];
         let groundingMeta;
@@ -620,7 +636,7 @@ export class GeminiClient {
                     grounding.sources = sources;
             }
         }
-        return { images, text, grounding };
+        return { images, text, grounding, usage };
     }
     async interact(opts) {
         const model = resolveModel(opts.model, readEnvVar('GEMINI_IMAGE_MODEL'));
@@ -647,13 +663,14 @@ export class GeminiClient {
             body.tools = [searchTool];
         }
         const data = await this.postInteraction(body, opts);
+        const usage = this.recordUsage(readUsage(data), model);
         const { images, text, grounding } = this.extractInteraction(data, opts.searchTypes);
         if (images.length === 0) {
             throw new McpToolError('Gemini returned no image', {
                 hint: 'The request may have been blocked by safety filters — try rephrasing the prompt.',
             });
         }
-        return { id: data.id, images: await this.downloadAll(images), text, grounding };
+        return { id: data.id, images: await this.downloadAll(images), text, grounding, usage };
     }
     /**
      * Generate video via the omni model (Interactions API). Same plumbing as
@@ -709,13 +726,14 @@ export class GeminiClient {
             started = await this.startInteraction(body, opts, timeoutMs);
         }
         const data = await this.settleInteraction(started, body, timeoutMs);
+        const usage = this.recordUsage(readUsage(data), model);
         const { videos, text } = this.extractInteraction(data);
         if (videos.length === 0) {
             throw new McpToolError('Gemini returned no video', {
                 hint: 'The request may have been blocked by a safety filter — try a shorter/simpler prompt or a different aspect ratio.',
             });
         }
-        return { id: data.id, videos: await this.downloadAll(videos), text };
+        return { id: data.id, videos: await this.downloadAll(videos), text, usage };
     }
     /**
      * Generate music via a Lyria model (Interactions API, inline audio). Reuses
@@ -736,13 +754,14 @@ export class GeminiClient {
         if (opts.background === true)
             body.background = true;
         const data = await this.postInteraction(body, opts);
+        const usage = this.recordUsage(readUsage(data), model);
         const { audios, text } = this.extractInteraction(data);
         if (audios.length === 0) {
             throw new McpToolError('Gemini returned no audio', {
                 hint: 'The request may have been blocked by a safety filter — try rephrasing the prompt.',
             });
         }
-        return { id: data.id, audios: await this.downloadAll(audios), text };
+        return { id: data.id, audios: await this.downloadAll(audios), text, usage };
     }
     /**
      * POST `/interactions`, wait out the store lag on a chained 404, and — when