@chrischall/gemini-mcp 1.11.1 → 1.13.0

package/dist/client.js

@@ -287,6 +287,17 @@ export class GeminiClient {
      *    That is an invisible, silent failure (the key just stops working); not
      *    depending on the order removes the hazard instead of documenting it.
      */
+    /**
+     * Which source supplies the API key, for `gemini_healthcheck` — a LABEL or
+     * `null`, never the key. Mirrors `requireKey`'s resolution order exactly, so
+     * the healthcheck reports the same source the real tools will use, but does
+     * NOT throw: "no key" is an answer here rather than an error.
+     */
+    describeCredential() {
+        if (this.explicitApiKey)
+            return { source: 'connector-session' };
+        return { source: readEnvVar('GEMINI_API_KEY') ? 'env' : null };
+    }
     requireKey() {
         const key = this.explicitApiKey || readEnvVar('GEMINI_API_KEY');
         if (!key) {

package/dist/jobs.js

@@ -1,5 +1,5 @@
 import { randomUUID, createHash } from 'node:crypto';
-import { textResult, McpToolError } from '@chrischall/mcp-utils';
+import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
 import { downloadFilename } from './media-name.js';
 import { HEARTBEAT_MS } from './job-store.js';
 import { annotateReusedUsage } from './usage.js';
@@ -151,7 +151,7 @@ function annotateReused(result, jobId) {
 }
 /** Immediate handle for an async call — the caller polls `gemini_get_result`. */
 function jobHandle(jobId, status, durable = false) {
-    return textResult({
+    return minifiedResult({
         job_id: jobId,
         status,
         hint: durable

package/dist/registrars.js

@@ -11,6 +11,7 @@
  */
 import { surfaceToolErrors } from './errors.js';
 import { registerModelTools } from './tools/models.js';
+import { registerHealthcheckTools } from './tools/healthcheck.js';
 import { registerGenerateTools } from './tools/generate.js';
 import { registerSetTools } from './tools/set.js';
 import { registerInteractTools } from './tools/interact.js';
@@ -39,6 +40,7 @@ export const reporting = (register) => (server, deps) => register(surfaceToolErr
  */
 export const TOOL_REGISTRARS = [
     registerModelTools,
+    registerHealthcheckTools,
     registerGenerateTools,
     registerSetTools,
     registerInteractTools,

package/dist/tools/_confirm.js

@@ -1,4 +1,4 @@
-import { schemaConfirm, textResult } from '@chrischall/mcp-utils';
+import { minifiedResult, schemaConfirm } from '@chrischall/mcp-utils';
 import { previewImageInput, previewVideoInput } from '../images.js';
 export { schemaConfirm };
 /**
@@ -9,7 +9,7 @@ export { schemaConfirm };
 export function previewUnlessConfirmed(confirm, action, method, path, body) {
     if (confirm === true)
         return null;
-    return textResult({
+    return minifiedResult({
         dryRun: true,
         action,
         method,

package/dist/tools/files.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
 import { withProgressHeartbeat } from './shared.js';
 import { base64ToBytes, wholeMb } from '../bytes.js';
 import { fileNameFromUrl } from '../fetch-image.js';
@@ -47,7 +47,7 @@ const RETENTION_NOTE = 'Gemini retains uploaded files for ~48h. Until then this
     '(images_file_uris on gemini_image_generate / _edit / _set / gemini_interact, or video_url) without re-sending the bytes.';
 /** Shape returned by every upload path. */
 function uploadResult(file) {
-    return textResult({
+    return minifiedResult({
         // The `files/<id>` form is what every tool parameter documents, so it leads.
         file_uri: file.name,
         // The absolute uri, for callers that would rather pass it through verbatim.
@@ -178,7 +178,7 @@ export function registerFileTools(server, client) {
         },
     }, async (args) => {
         const files = await client.listFiles(args.page_size ?? 100);
-        return textResult({
+        return minifiedResult({
             count: files.length,
             files: files.map((f) => ({
                 file_uri: f.name,
@@ -220,7 +220,7 @@ export function registerFileTools(server, client) {
                 // Remediation goes in the MESSAGE: MCP serialization drops hints.
                 throw new McpToolError(`No stored media for r2_key "${args.r2_key}" — it has probably passed its retention window. Re-run the generation to get a new one.`, { hint: 'Objects are swept on a retention schedule (MEDIA_TTL_DAYS, default 7 days).' });
             }
-            return textResult({
+            return minifiedResult({
                 url: fresh.ref,
                 r2_key: fresh.key,
                 ...(fresh.expiresAt ? { expires_at: fresh.expiresAt } : {}),
@@ -258,7 +258,7 @@ export function registerFileTools(server, client) {
                 ? await sink.listRecentPage({ limit, sinceDay: args.since_day })
                 : { media: await sink.listRecent({ limit, sinceDay: args.since_day }), truncated: false };
             const found = page.media;
-            return textResult({
+            return minifiedResult({
                 count: found.length,
                 // Never let a bounded walk pass for the whole picture: concluding an
                 // image is gone is what makes someone pay to generate it twice.
@@ -293,6 +293,6 @@ export function registerFileTools(server, client) {
         if (gate)
             return gate;
         await client.deleteFile(args.file_uri);
-        return textResult({ deleted: args.file_uri });
+        return minifiedResult({ deleted: args.file_uri });
     });
 }

package/dist/tools/healthcheck.js

@@ -0,0 +1,29 @@
+import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthcheck';
+/**
+ * Register `gemini_healthcheck` — resolves the API key the way real tools do,
+ * then makes one authenticated call to `/models`.
+ *
+ * Gemini has no browser bridge, so health here is entirely about the
+ * credential: whether one resolved, and whether Google still accepts it. Those
+ * are different problems with different fixes, and without this both surface
+ * as the same opaque tool error.
+ *
+ * `/models` is the probe because it is the cheapest endpoint that REQUIRES a
+ * key — an unauthenticated one would pass while the key was revoked, which is
+ * the failure most worth catching. It is also read-only and free, so a
+ * healthcheck never costs a generation.
+ */
+export function registerHealthcheckTools(server, client) {
+    registerCredentialHealthcheckTool({
+        server,
+        prefix: 'gemini',
+        hostLabel: 'generativelanguage.googleapis.com',
+        probePath: '/v1beta/models',
+        resolveCredential: async () => client.describeCredential(),
+        probeFn: () => client.listModels(),
+        hints: {
+            no_credential: 'No Gemini API key resolved. Set GEMINI_API_KEY (https://aistudio.google.com/apikey), or reconnect the connector so it supplies one.',
+            credential_rejected: 'Google rejected the API key. It is present but no longer valid — most often revoked, or restricted to different APIs/referrers. Issue a new key at https://aistudio.google.com/apikey.',
+        },
+    });
+}

package/dist/tools/jobs.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
 import { TERMINAL_INTERACTION_STATUSES } from '../client.js';
 import { emitMedia } from './shared.js';
 import { slugify } from '../images.js';
@@ -128,7 +128,7 @@ function recoveryNote(recordedError) {
 }
 /** The generation outlived its executor and is not finished yet. */
 function stillRunning(jobId, interactionId) {
-    return textResult({
+    return minifiedResult({
         job_id: jobId,
         status: 'running',
         interaction_id: interactionId,

package/dist/tools/library.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
 import { LIBRARY_NAME_PATTERN } from '../library.js';
 import { acceptableUploadType } from '../upload-url.js';
 import { withProgressHeartbeat } from './shared.js';
@@ -79,7 +79,7 @@ export function registerLibraryTools(server, client) {
     }, async (args, extra) => {
         const image = (await withProgressHeartbeat(extra, 'Loading the reference image', () => resolveLibraryImage(client, args, true)));
         const record = await library.saveCharacter({ name: args.name, description: args.description, image });
-        return textResult({
+        return minifiedResult({
             saved: 'character',
             name: record.name,
             description: record.description,
@@ -96,7 +96,7 @@ export function registerLibraryTools(server, client) {
         inputSchema: {},
     }, async () => {
         const characters = await library.listCharacters();
-        return textResult({
+        return minifiedResult({
             count: characters.length,
             characters: characters.map((c) => ({
                 name: c.name,
@@ -122,7 +122,7 @@ export function registerLibraryTools(server, client) {
         if (!existed) {
             throw new McpToolError(`No saved character "${args.name}". List what exists with gemini_list_characters.`);
         }
-        return textResult({ deleted: 'character', name: args.name });
+        return minifiedResult({ deleted: 'character', name: args.name });
     });
     server.registerTool('gemini_save_style', {
         description: 'Save a named style preset to this account\'s persistent reference library: a reusable prompt fragment (and ' +
@@ -141,7 +141,7 @@ export function registerLibraryTools(server, client) {
     }, async (args, extra) => {
         const image = await withProgressHeartbeat(extra, 'Loading the style reference image', () => resolveLibraryImage(client, args, false));
         const record = await library.saveStyle({ name: args.name, promptFragment: args.prompt_fragment, image });
-        return textResult({
+        return minifiedResult({
             saved: 'style',
             name: record.name,
             prompt_fragment: record.prompt_fragment,
@@ -157,7 +157,7 @@ export function registerLibraryTools(server, client) {
         inputSchema: {},
     }, async () => {
         const styles = await library.listStyles();
-        return textResult({
+        return minifiedResult({
             count: styles.length,
             styles: styles.map((s) => ({
                 name: s.name,
@@ -181,6 +181,6 @@ export function registerLibraryTools(server, client) {
         if (!existed) {
             throw new McpToolError(`No saved style "${args.name}". List what exists with gemini_list_styles.`);
         }
-        return textResult({ deleted: 'style', name: args.name });
+        return minifiedResult({ deleted: 'style', name: args.name });
     });
 }

package/dist/tools/models.js

@@ -1,10 +1,10 @@
-import { textResult } from '@chrischall/mcp-utils';
+import { minifiedResult } from '@chrischall/mcp-utils';
 export function registerModelTools(server, client) {
     server.registerTool('gemini_list_models', {
         description: 'List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.',
         annotations: { readOnlyHint: true },
     }, async () => {
         const models = await client.listModels();
-        return textResult({ default: client.defaultModel(), models });
+        return minifiedResult({ default: client.defaultModel(), models });
     });
 }

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';
@@ -535,7 +535,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

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';
@@ -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/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '1.11.1'; // x-release-please-version
+export const VERSION = '1.13.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.11.1",
+  "version": "1.13.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,7 +46,7 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.15.0",
+    "@chrischall/mcp-utils": "^0.23.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": "1.11.1",
+  "version": "1.13.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.11.1",
+      "version": "1.13.0",
       "transport": {
         "type": "stdio"
       },