@chrischall/gemini-mcp 1.9.0 → 1.11.0

package/dist/tools/usage.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { PRICED_AT } from '../pricing.js';
+/**
+ * What this session has spent, in tokens.
+ *
+ * This exists because the obvious thing — read the account balance before and
+ * after — cannot be built. The Generative Language API's discovery document
+ * has no billing, quota, usage, account or credit resource at all, and Cloud
+ * Billing v1 has no notion of a balance either (its schema never mentions the
+ * word): Google Cloud is post-paid, so there is no wallet to read. Even with a
+ * service account and the Cloud Billing scopes, actual spend arrives through
+ * BigQuery export hours later — far too late to attribute to one call.
+ *
+ * Tokens do the job better anyway. They are exact, they are per-call, they
+ * arrive with the response, and they attribute: a before/after balance diff
+ * cannot separate your generation from anything else billing the account in
+ * the same window, and this can.
+ *
+ * Money IS reported, with two safeguards. Image output turned out to be billed
+ * per token like everything else — just at 20-40x the text-output rate — so
+ * the published per-image prices are exactly the token arithmetic, and an
+ * estimate is arithmetic rather than guesswork (see src/pricing.ts). The
+ * safeguards are that every figure carries the date its rates were read, and
+ * `GEMINI_RATE_CARD` overrides them without waiting on a release.
+ *
+ * The session's cost is accumulated PER CALL, not derived from the token total
+ * at the end: the total spans models, and pricing a Pro call's tokens at a
+ * Lite rate would be wrong by 4x.
+ */
+export function registerUsageTools(server, client) {
+    server.registerTool('gemini_token_usage', {
+        description: 'Token usage for this session so far — 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 — Google Cloud is post-paid and its billing data lags by hours — so this is the accurate way to attribute spend to a call.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {
+            reset: z
+                .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 = client.session.usageTotal;
+        const calls = client.session.billedCalls;
+        const costUsd = client.session.costUsd;
+        const priced = client.session.pricedCalls;
+        if (args.reset) {
+            client.session.usageTotal = undefined;
+            client.session.billedCalls = 0;
+            client.session.costUsd = undefined;
+            client.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 === undefined
+                ? 'No generation has run in this session yet, so nothing has been billed through it.'
+                : priced < calls
+                    ? `Estimate covers ${priced} of ${calls} billed calls — 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 — 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 — these are your tokens, not the account\'s.',
+        });
+    });
+}

package/dist/tools/video.js

@@ -3,8 +3,9 @@ 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, 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 } 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'];
@@ -100,9 +101,14 @@ export function registerVideoTools(server, client) {
                 onInteractionStarted: ctx.reportInteraction,
             }));
             client.session.lastVideoInteractionId = r.id;
-            const meta = { model, interaction_id: r.id };
+            // 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 });
             if (previousInteractionId)
                 meta.previous_interaction_id = previousInteractionId;
+            if (r.usage)
+                meta.usage = r.usage;
+            attachCost(meta, model, r.usage);
             if (r.text)
                 meta.text = r.text;
             if (report)

package/dist/usage.js

@@ -0,0 +1,156 @@
+/**
+ * What a generation cost, in tokens.
+ *
+ * Both Gemini APIs already report this and this server used to discard it. The
+ * two disagree on more than casing: `generateContent` returns camelCase
+ * `usageMetadata` with `promptTokenCount` / `candidatesTokenCount`, while the
+ * Interactions API returns snake_case `usage` with `total_input_tokens` /
+ * `total_output_tokens` plus cached- and thought-token counts that
+ * `generateContent` has no equivalent for. This module is the one place that
+ * knows both, so nothing downstream has to.
+ *
+ * Absence is preserved deliberately. A response with no usage block yields
+ * `undefined`, never a zeroed record: "we do not know what this cost" and "this
+ * cost nothing" are different claims, and a caller adding up a workflow has to
+ * be able to tell them apart.
+ */
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+/**
+ * Pull one modality's entry out of either API's by-modality list.
+ *
+ * Modality matters for money, not just curiosity: each is billed at its own
+ * rate, and they differ by more than an order of magnitude (text output vs
+ * image output is 20-40x on the same model). A modality nobody breaks out is
+ * priced as text, which is the cheap end — so missing one understates rather
+ * than inventing spend.
+ */
+function modalityTokens(list, modality) {
+    if (!Array.isArray(list))
+        return undefined;
+    for (const entry of list) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const e = entry;
+        // generateContent shouts ("IMAGE"); the Interactions API does not ("image").
+        if (typeof e.modality === 'string' && e.modality.toLowerCase() === modality) {
+            return num(e.tokenCount) ?? num(e.tokens);
+        }
+    }
+    return undefined;
+}
+/**
+ * Read whichever usage block a response carries, or `undefined` when it
+ * carries neither — including the case where the block exists but has no
+ * totals in it, which is indistinguishable from absent for our purposes.
+ */
+export function readUsage(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const b = body;
+    const meta = b.usageMetadata;
+    if (meta) {
+        const input = num(meta.promptTokenCount);
+        const output = num(meta.candidatesTokenCount);
+        const total = num(meta.totalTokenCount);
+        if (input !== undefined || output !== undefined || total !== undefined) {
+            return compact({
+                input_tokens: input ?? 0,
+                output_tokens: output ?? 0,
+                total_tokens: total ?? (input ?? 0) + (output ?? 0),
+                image_tokens: modalityTokens(meta.candidatesTokensDetails, 'image'),
+                video_tokens: modalityTokens(meta.candidatesTokensDetails, 'video'),
+                audio_tokens: modalityTokens(meta.candidatesTokensDetails, 'audio'),
+                cached_tokens: num(meta.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 !== undefined || output !== undefined || total !== undefined) {
+            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 undefined;
+}
+/** Drop the optional counts that are absent or zero — a constant 0 is noise. */
+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;
+}
+/**
+ * Add up several calls — `count: N` bills N times, so a tool that reports only
+ * the first call understates itself. Gaps are skipped rather than counted as
+ * zero; if nothing at all is known the sum is `undefined`, so silence does not
+ * turn into a confident total.
+ */
+export function sumUsage(parts) {
+    const known = parts.filter((p) => p !== undefined);
+    if (known.length === 0)
+        return undefined;
+    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 }));
+}
+/**
+ * Mark a replayed result's usage as already billed.
+ *
+ * `JobRegistry.dispatch()` can serve a matching `idempotency_key` from the
+ * registry without calling upstream — that is what makes a host-timeout retry
+ * free. The recorded result still carries the ORIGINAL call's usage, which is
+ * correct as a description of the image you are being handed and wrong as a
+ * measure of what this call cost: nothing.
+ *
+ * So the counts stay and gain `usage_billed: false`, which is what lets a
+ * workflow total exclude them. Dropping them instead would be worse — the
+ * caller could no longer see how the image was produced — and leaving them
+ * unmarked would double-count a generation that was paid for once.
+ *
+ * A result with no usage at all is left untouched: "unknown" must not turn
+ * into the positive claim "not billed".
+ */
+export function annotateReusedUsage(meta) {
+    if (!meta.usage)
+        return meta;
+    meta.usage_billed = false;
+    // The cost estimate needs the same treatment for the same reason, and is
+    // worse if it does not get it: a token count someone forgets to exclude is a
+    // rounding error in a report, a dollar figure is the report. Marked rather
+    // than deleted, so the result still shows what the generation cost when it
+    // was actually made.
+    if (meta.cost_estimate)
+        meta.cost_billed = false;
+    return meta;
+}

package/dist/version.js

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

package/mint.yaml

@@ -0,0 +1,57 @@
+version: 1
+name: Gemini Images
+slug: gemini
+summary: >-
+  Generate and edit images with Google Gemini image models (Nano Banana /
+  Nano Banana Pro) via natural language prompts
+env:
+  - name: GEMINI_API_KEY
+    secret: true
+    required: true
+    help: >-
+      Your Google Gemini API key (aistudio.google.com/apikey)
+  - name: GEMINI_IMAGE_MODEL
+    required: false
+    help: >-
+      Override the default image model (default: gemini-3.1-flash-image)
+  - name: GEMINI_OUTPUT_DIR
+    required: false
+    help: >-
+      Default directory for generated images (default: current working
+      directory)
+  - name: GEMINI_INPUT_DIR
+    required: false
+    help: >-
+      Directory to resolve bare input-image filenames against
+  - name: GEMINI_TIMEOUT_MS
+    required: false
+    help: >-
+      Upstream request timeout in ms (default: 60000, or 120000 for 4K output)
+  - name: GEMINI_CHAIN_RETRY_MS
+    required: false
+    help: >-
+      Retry budget in milliseconds for a chained request that 404s while the
+      upstream result settles (default 120000).
+  - name: GEMINI_HEARTBEAT_MS
+    required: false
+    help: >-
+      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.
+egress:
+  allow:
+    # Only hosts the SERVER process actually fetches. Hosts that appear
+    # solely in a URL this server BUILDS and returns are excluded.
+    - generativelanguage.googleapis.com
+    #
+    # NOTE — this server also reaches at least one host determined at
+    # RUNTIME, which cannot appear as a literal here:
+    #   - a signed upload URL returned by the API (often storage.googleapis.com / s3)
+    #   - a media/CDN host supplied at runtime
+    # Confirm the concrete host(s) against a live run and add them, or
+    # the isolated tier will block the call.
+    #
+    # Also: the images_url argument makes this server fetch an ARBITRARY
+    # caller-supplied https host. That cannot be enumerated in advance, so on
+    # the isolated tier either allow the hosts you intend to pass, or expect
+    # image-by-URL to be blocked there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.9.0",
+  "version": "1.11.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>",
@@ -33,7 +33,8 @@
     ".claude-plugin",
     "skills/",
     ".mcp.json",
-    "server.json"
+    "server.json",
+    "mint.yaml"
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
@@ -41,7 +42,7 @@
     "dev": "node dist/index.js",
     "test": "npm run typecheck && vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test:coverage": "npm run typecheck && vitest run --coverage",
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {

package/server.json

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