@chrischall/gemini-mcp 1.11.1 → 1.12.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.11.1"
+    "version": "1.12.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.11.1",
+      "version": "1.12.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/dist/bundle.js

@@ -32110,6 +32110,11 @@ function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
     return redacted;
   return `${redacted.slice(0, max)}\u2026 [truncated]`;
 }
+function messageOf(err) {
+  if (err instanceof Error)
+    return err.message;
+  return String(err);
+}
 var DEFAULT_ERROR_MESSAGE_MAX, McpToolError, BEARER_RE, JWT_RE, BASIC_AUTH_RE, SET_COOKIE_RE, COOKIE_HEADER_RE, API_KEY_RE, QUERY_SECRET_RE, AWS_SIGV4_RE, JSON_SECRET_KEYS, JSON_SECRET_DQ_RE, JSON_SECRET_SQ_RE;
 var init_errors4 = __esm({
   "node_modules/@chrischall/mcp-utils/dist/errors/index.js"() {
@@ -32876,7 +32881,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.11.1";
+var VERSION = "1.12.0";
 
 // src/errors.ts
 init_dist();
@@ -32952,6 +32957,135 @@ function registerModelTools(server, client2) {
   );
 }
 
+// node_modules/@chrischall/mcp-utils/dist/healthcheck/index.js
+init_errors4();
+function statusOf(err) {
+  if (typeof err !== "object" || err === null)
+    return void 0;
+  const s = err.status ?? err.statusCode;
+  return typeof s === "number" ? s : void 0;
+}
+function credentialHint(arm, prefix, hostLabel, source) {
+  switch (arm) {
+    case "ok":
+      return `Credential from '${source}' works: ${hostLabel} accepted an authenticated request. If a real tool still fails, the problem is that tool, not auth.`;
+    case "no_credential":
+      return `No credential resolved. Nothing was available to authenticate with \u2014 sign in and reconnect the connector so ${prefix} receives a token, or set the documented environment variable.`;
+    case "credential_rejected":
+      return `${hostLabel} rejected the credential from '${source}'. It is present but no longer valid \u2014 most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
+    case "timeout":
+      return `The credential from '${source}' resolved, but ${hostLabel} did not answer in time. Usually transient \u2014 retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
+    case "http":
+      return `${hostLabel} answered with an error status that is not an auth rejection. That is USUALLY a ${hostLabel}-side problem rather than an auth one \u2014 but a 404 here more often means the probe path is wrong than that ${hostLabel} is broken, so check error.message and probe.url before concluding anything about the credential.`;
+    case "transport":
+      return `Could not reach ${hostLabel} at all. Check network egress; the credential itself was never judged.`;
+    default:
+      return `Unexpected failure \u2014 see error.message.`;
+  }
+}
+function registerCredentialHealthcheckTool(args) {
+  const { server, prefix, hostLabel, probePath, resolveCredential, probeFn, classifyThrown, hints } = args;
+  const probeUrl = probePath ? `https://${hostLabel}${probePath}` : void 0;
+  server.registerTool(`${prefix}_healthcheck`, {
+    title: "Verify credentials and upstream reachability",
+    description: `Resolves the credential the way real tools do, then makes one authenticated request to ${hostLabel}. Reports which source supplied the credential, whether ${hostLabel} accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a ${hostLabel}-side problem'. Call this when a real tool fails and you want to know which hop broke. Read-only; never returns the credential itself.`,
+    annotations: {
+      title: "Verify credentials and upstream reachability",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: {}
+  }, async () => {
+    let probeStarted = 0;
+    let state;
+    try {
+      state = await resolveCredential();
+    } catch (e) {
+      const result2 = {
+        ok: false,
+        credential: { source: null, resolved: false },
+        // No `url`: nothing was probed, and naming one implies it was tried.
+        probe: { elapsed_ms: 0 },
+        error: { kind: "no_credential", message: truncateErrorMessage(messageOf(e)) },
+        hint: hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    const credential = {
+      source: state.source,
+      resolved: state.source !== null,
+      ...state.detail !== void 0 ? { detail: state.detail } : {}
+    };
+    if (!credential.resolved) {
+      const result2 = {
+        ok: false,
+        credential,
+        probe: { elapsed_ms: 0 },
+        error: { kind: "no_credential", message: "no credential source resolved" },
+        hint: hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    let arm = "ok";
+    let error51;
+    let status;
+    let customHint;
+    probeStarted = Date.now();
+    try {
+      await probeFn();
+    } catch (e) {
+      status = statusOf(e);
+      const aborted2 = e instanceof Error && e.name === "AbortError";
+      arm = status === 401 || status === 403 ? "credential_rejected" : status !== void 0 ? "http" : aborted2 || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e)) ? "timeout" : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e)) ? "transport" : "unknown";
+      let kind = arm;
+      let detail;
+      const custom2 = classifyThrown?.(e);
+      if (custom2) {
+        kind = custom2.kind;
+        customHint = custom2.hint;
+        detail = custom2.detail;
+      }
+      error51 = {
+        kind,
+        // Redacted AND bounded before it reaches the result: an upstream
+        // failure routinely quotes what it was sent, and a healthcheck is
+        // the tool people paste into a chat when something is broken.
+        message: truncateErrorMessage(messageOf(e)),
+        ...detail !== void 0 ? { detail } : {}
+      };
+    }
+    const result = {
+      ok: error51 === void 0,
+      credential,
+      probe: {
+        ...probeUrl ? { url: probeUrl } : {},
+        elapsed_ms: Date.now() - probeStarted,
+        ...status !== void 0 ? { status } : {}
+      },
+      ...error51 ? { error: error51 } : {},
+      hint: customHint ?? hints?.[arm] ?? credentialHint(arm, prefix, hostLabel, state.source)
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+}
+
+// src/tools/healthcheck.ts
+function registerHealthcheckTools(server, client2) {
+  registerCredentialHealthcheckTool({
+    server,
+    prefix: "gemini",
+    hostLabel: "generativelanguage.googleapis.com",
+    probePath: "/v1beta/models",
+    resolveCredential: async () => client2.describeCredential(),
+    probeFn: () => client2.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 \u2014 most often revoked, or restricted to different APIs/referrers. Issue a new key at https://aistudio.google.com/apikey."
+    }
+  });
+}
+
 // src/tools/generate.ts
 init_zod();
 init_dist();
@@ -35551,6 +35685,16 @@ var GeminiClient = class {
    *    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) {
@@ -37278,6 +37422,7 @@ function registerLibraryTools(server, client2) {
 var reporting = (register) => (server, deps) => register(surfaceToolErrors(server), deps);
 var TOOL_REGISTRARS = [
   registerModelTools,
+  registerHealthcheckTools,
   registerGenerateTools,
   registerSetTools,
   registerInteractTools,

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/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/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/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.12.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.11.1",
+  "version": "1.12.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.19.2",
     "@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.12.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.11.1",
+      "version": "1.12.0",
       "transport": {
         "type": "stdio"
       },