@brobertoblanko/gemini-grounding-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Broberto Blanko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# @brobertoblanko/gemini-grounding-mcp
+
+A small, self-contained MCP server that gives Claude Code - or any other MCP
+client - access to Google web search through the Gemini API with grounding.
+It uses nothing but the official `@google/genai` and `@modelcontextprotocol/sdk`
+packages: no community wrapper, no version silently changing under you.
+
+**Scope of use:** research queries only. Not intended for production use or for
+connecting to sensitive systems.
+
+Architecture and design decisions: see [specs.md](./docs/specs.md) (German).
+Working rules for Claude Code in this repository: see [CLAUDE.md](./CLAUDE.md)
+(German).
+
+## Requirements
+
+- **Node.js 20 or newer** - required by `@google/genai` and the MCP SDK.
+  Check with `node -v`.
+- **A Gemini API key**, available for free at
+  [Google AI Studio](https://aistudio.google.com/apikey).
+- **Claude Code** or any other MCP-capable client
+  ([Model Context Protocol](https://modelcontextprotocol.io)).
+
+**A note on cost:** Gemini API calls are not free in every case. There is a free
+tier with rate limits; beyond that you are billed per token, and Google Search
+grounding may be charged separately depending on model and plan. The official
+[pricing](https://ai.google.dev/gemini-api/docs/pricing) and
+[rate limit](https://ai.google.dev/gemini-api/docs/rate-limits) pages are
+authoritative - both change regularly, which is why no concrete figures appear
+here. The token footer under every answer makes the cost of each individual call
+visible.
+
+## Installation
+
+Nothing to install up front if you use `npx` - the registration command below
+fetches the package on demand. To install it permanently instead:
+
+```bash
+npm install -g @brobertoblanko/gemini-grounding-mcp
+```
+
+This provides two commands: `gemini-grounding-mcp` starts the MCP server over
+stdio, and `gemini-grounding` is the command line tool described further down.
+
+To work from the source instead:
+
+```bash
+git clone https://github.com/srzsn22q6d-sys/gemini-grounding-mcp.git
+cd gemini-grounding-mcp
+npm install
+```
+
+## Providing the API key
+
+The API key is passed exclusively through the `GEMINI_API_KEY` environment
+variable - never in the code, never in the config file. It must be set
+**persistently** before the client starts the server.
+
+**Windows (PowerShell, user scope, once):**
+
+```powershell
+[Environment]::SetEnvironmentVariable('GEMINI_API_KEY', '<your-api-key>', 'User')
+```
+
+Reopen the shell afterwards so the variable is available.
+
+**macOS / Linux** - add to `~/.zshrc`, `~/.bashrc` or equivalent:
+
+```bash
+export GEMINI_API_KEY='<your-api-key>'
+```
+
+## Registering with Claude Code
+
+**Windows (PowerShell):**
+
+```powershell
+claude mcp add gemini-grounding -s user `
+  -e 'GEMINI_API_KEY=${GEMINI_API_KEY}' `
+  -- npx -y @brobertoblanko/gemini-grounding-mcp
+```
+
+**macOS / Linux (bash / zsh):**
+
+```bash
+claude mcp add gemini-grounding -s user \
+  -e 'GEMINI_API_KEY=${GEMINI_API_KEY}' \
+  -- npx -y @brobertoblanko/gemini-grounding-mcp
+```
+
+Write `${GEMINI_API_KEY}` in **single** quotes so your shell does not expand it
+itself. Claude Code resolves it later, when it loads its configuration, from the
+environment variable you already set - that way only the placeholder ends up in
+`~/.claude.json`, not the key in plain text.
+
+If you installed globally with `npm install -g`, replace
+`npx -y @brobertoblanko/gemini-grounding-mcp` with `gemini-grounding-mcp`.
+If you cloned the repository, use `node <path-to-repo>/index.js` instead -
+`claude mcp add` needs a concrete absolute path that resolves on the machine
+in question.
+
+Verify that the server is running:
+
+```bash
+claude mcp list
+```
+
+## Command line tool
+
+The server can also be driven without an MCP client - useful for checking that
+your API key and model choice work before registering it, and for testing a
+change during development without restarting the client.
+
+```bash
+gemini-grounding config
+```
+
+Working from a clone, use `node cli.js` in place of `gemini-grounding`, or run
+`npm link` once to make the command available system-wide. `npm link` places a
+link to `cli.js` in the global npm directory (a `.cmd`/`.ps1` pair on Windows, a
+symlink elsewhere); because it is a link and not a copy, edits to `cli.js` take
+effect immediately. Undo it with
+`npm unlink -g @brobertoblanko/gemini-grounding-mcp` - npm expects the package
+name there, not the command name `gemini-grounding`. Given the command name it
+merely reports `up to date` and removes nothing.
+
+| Command | Effect |
+|---|---|
+| `gemini-grounding "<query>"` | Search using the saved defaults; prints the answer including source list and token footer |
+| `gemini-grounding config` | Shows the saved model, thinking level, whether an API key is present, and where the config file lives |
+| `gemini-grounding models [--all]` | Lists the models usable with this server and their token limits; `--all` lists every one |
+| `gemini-grounding set-model <id>` | Persists the default model |
+| `gemini-grounding set-thinking <level>` | Persists the default thinking level (`minimal`, `low`, `medium`, `high`) |
+| `gemini-grounding help` | Short help |
+
+Anything that is not a known subcommand is treated as a search query - as
+**exactly one argument**. A question containing spaces therefore has to be
+quoted. Unquoted, the call aborts with a message rather than sending a query
+that option parsing has cut individual words out of (`… what does --thinking
+high mean …` would otherwise have run as `what does mean …`). An unknown option
+(`--al` instead of `--all`) and surplus arguments are errors with exit code 1 as
+well - none of it is silently ignored.
+
+**Per-call overrides.** For a single call, model and thinking level can be set
+differently without touching the saved defaults:
+
+```bash
+gemini-grounding "query" --model gemini-3-pro-preview --thinking minimal
+```
+
+Which values were actually used is shown in the footer under every answer.
+
+**Shared configuration.** The CLI and the MCP server read and write the same
+config file. A `set-model` in the terminal therefore also changes what the MCP
+server uses on its next call - intentionally so, because it makes a model switch
+possible without having to ask the client to do it.
+
+**Errors stay fully visible.** Unlike the MCP server, which has to condense
+every error into a single line for the client, the CLI prints the full stack
+trace including the original Google API error and exits with code 1. When
+testing, that is exactly what you want: a message like
+`ApiError: {"error":{"code":503, ...}}` says the request did not get through to
+Google - not that your installation is broken. A plain usage error (wrong
+argument, unknown option, empty query) prints only the one explanatory line,
+also with exit code 1 - nobody needs a stack trace for a typo.
+
+`config` only checks whether a key arrives in the environment at all and prints
+its length - **never the value itself**. Whether the key is valid is something
+only a real request can tell you.
+
+## Tools
+
+- **`gemini-search`** - research via Google Search, URL Context and Code
+  Execution in one call. The answer contains inline citation markers, a source
+  list and a token footer. If Gemini executed code, the code and its result
+  appear under `Code execution:` after the answer text - the calculation is
+  evidence, so it belongs where the sources are. If the answer did not finish
+  normally - blocked, or cut off at the token limit - a line marked ⚠️ says so
+  along with the reason, instead of letting an empty or half answer look like a
+  success.
+- **`gemini-list-models`** - lists the models available for your API key with
+  their token limits. By default only those usable with this server (see below);
+  with `all: true`, every one.
+- **`gemini-set-model`** - persists the default model and/or default thinking
+  level (only those two values, never the API key).
+
+### Citation markers
+
+Markers such as `[1]` or `[1][3]` are placed in the answer text at the positions
+for which the API reports a source, using the same numbering as the source list
+at the end. Their point is less *which* source backs a sentence than *whether*
+it is backed at all: a sentence without a marker may well come from the model's
+own memory rather than from the search - and that is precisely the kind of
+sentence you would not want to write code against unchecked.
+
+The guarantee runs one way only. A marker that is present is reliable; a marker
+that is missing is an indication, not proof. Markers are verified against the
+text segment the API supplies and are dropped rather than guessed if they do not
+match, and they are never placed inside code spans or fenced blocks. Whenever
+markers were dropped, the footer says so. See
+[specs.md](./docs/specs.md) for the details.
+
+### Where the configuration is stored
+
+`gemini-set-model` and the CLI's `set-*` commands write the default model and
+thinking level to:
+
+| Platform | Location |
+|---|---|
+| Linux, macOS | `~/.config/gemini-grounding-mcp/config.json` |
+| Windows | `%APPDATA%\gemini-grounding-mcp\config.json` |
+| Any, if `XDG_CONFIG_HOME` is set | `$XDG_CONFIG_HOME/gemini-grounding-mcp/config.json` |
+
+Neither the file nor its directory is created until you save a setting for the
+first time. Delete the file to return to the built-in defaults
+(`gemini-flash-latest`, thinking level `medium`). It holds nothing but those two
+values - never the API key. Run `gemini-grounding config` to see the exact path
+on your machine.
+
+**Coming from a clone older than 1.1.0:** back then the file lived next to
+`index.js` inside the repository. It is no longer read and nothing is migrated
+for you - run `gemini-grounding config` to see where the file belongs now, then
+either move the old one there or simply set both values again. The leftover copy
+in the clone can be deleted.
+
+### Which models are usable
+
+Your API key exposes considerably more models than will work here. The model
+list therefore shows, by default, only those meeting two conditions - both taken
+from what the API reports about each model, not from its name:
+
+- **`generateContent`** in `supportedActions` - the model produces text at all.
+  This rules out embedding, image (Imagen), video (Veo) and live/audio models.
+- **`thinking: true`** - the model accepts a thinking level. Since every search
+  sends one, the API would otherwise answer with
+  `400 Thinking level is not supported for this model.`
+
+Filtering by name patterns would be unreliable: Google assigns code names that
+say nothing about capabilities - `nano-banana-pro-preview` is an image model.
+
+Two limitations remain:
+
+- The conditions say what runs **technically**, not what is sensible for
+  research. Some image, speech and robotics models meet them too and show up in
+  the list.
+- **Listed does not mean available.** Retired models stay in the list and answer
+  with `404 ... is no longer available`. No field announces this in advance -
+  only a real call gives you certainty.
+
+This is why `--all` / `all: true` hides nothing but instead shows the complete
+list with a status column.
+
+## License
+
+[MIT](./LICENSE)

package/citations.js

@@ -0,0 +1,147 @@
+// Belegmarker ([1], [2]) fuer den Antworttext. Die Gemini-API weist ueber
+// groundingSupports aus, welche Textstelle durch welche Quelle gestuetzt ist;
+// diese Datei setzt daraus Marker in den Text. Sichtbar werden soll dabei
+// weniger, WELCHE Quelle einen Satz stuetzt, als vielmehr, OB er ueberhaupt
+// belegt ist - gemessen an einer realen Antwort waren 27 % des Textes durch
+// keinen einzigen Support gedeckt, ohne dass man es der Antwort ansah.
+//
+// Die Datei greift bewusst weder auf die API noch auf die Konfiguration zu:
+// Sie bekommt Text und Metadaten uebergeben und liefert Text zurueck. Damit
+// ist sie ohne Netzwerk und ohne API-Key pruefbar (test/citations.test.js).
+//
+// Gerechnet wird durchgehend in BYTES, nicht in Zeichen: startIndex und
+// endIndex sind laut Typdefinition "measured in bytes". Bei einer deutschen
+// Testantwort stimmte keine einzige von 28 Positionen zeichenbasiert, alle 28
+// bytebasiert; Text und Bytes liefen am Ende um 44 Stellen auseinander. Google
+// selbst hatte diesen Fehler in der Gemini CLI (PR google-gemini/
+// gemini-cli#5956, aufgefallen an japanischem Text).
+
+/**
+ * Findet die Bereiche, in die kein Marker gesetzt werden darf: Markdown-Code
+ * im Fliesstext. Ein Marker mitten in einem Codebeispiel macht aus
+ * `copy.replace(obj, x=1)` ein `copy.replace(obj[3], x=1)` - syntaktisch
+ * gueltig, inhaltlich falsch. Da gegen die Antworten dieses Servers Code
+ * geschrieben wird, wiegt das schwerer als ein fehlender Marker.
+ *
+ * Gemeint ist NUR Code, den das Modell selbst in seinen Fliesstext schreibt.
+ * Die Bloecke aus Code Execution sind eigene Parts, werden von buildText()
+ * erst nach dem Einfuegen angehaengt und koennen hier nicht auftauchen.
+ *
+ * Gesucht wird in EINEM Durchlauf. Der Scan laeuft von links nach rechts, und
+ * weil die umzaeunten Bloecke in der Alternation vorn stehen, verschluckt ein
+ * Zaun alles, was in ihm steht - auch einzelne Backticks, die sonst als
+ * Inline-Code gelesen wuerden. Eine zweite Suche mit Ueberlappungspruefung
+ * braucht es dadurch nicht.
+ *
+ * Verworfen wurde die einfachere Variante, die Backticks vor der Zielposition
+ * zu zaehlen und bei ungerader Anzahl zu verwerfen: Ein einzelner unpaariger
+ * Backtick im Text kippt diese Zaehlung fuer den gesamten Rest, ein mit vier
+ * Backticks geschlossener Block ebenso, und innerhalb einer Backtick-Sequenz
+ * oszilliert sie bedeutungslos.
+ *
+ * Nicht erkannt werden eingerueckte Codebloecke (vier Leerzeichen). Sie sind
+ * die einzige bekannte Luecke; nachruestbar als dritte Regel, falls sie in
+ * echten Antworten auftauchen.
+ *
+ * Rueckgabe sind BYTE-Bereiche, passend zu den Offsets der API.
+ */
+function findCodeRanges(text) {
+  const toByte = (charIndex) => Buffer.byteLength(text.slice(0, charIndex), "utf8");
+
+  return [...text.matchAll(/```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`\n]+`/g)].map((match) => [
+    toByte(match.index),
+    toByte(match.index + match[0].length),
+  ]);
+}
+
+/**
+ * Setzt Belegmarker in den Text EINES Parts.
+ *
+ * - text:         der Rohtext genau eines Text-Parts
+ * - supports:     die groundingSupports, die zu DIESEM Part gehoeren
+ * - chunkNumbers: Map vom Index in groundingChunks auf die Nummer in der
+ *                 ausgegebenen Quellenliste (siehe buildSourceList)
+ *
+ * Liefert den Text mit Markern und die Zahl der verworfenen Marker. Verworfen
+ * wird bewusst grosszuegig: Ein fehlender Marker laesst eine belegte Aussage
+ * unbelegt wirken und loest damit nur zusaetzliche Vorsicht aus. Ein falsch
+ * gesetzter Marker verweist auf eine Quelle, die die Aussage nicht stuetzt -
+ * oder zerstoert Code. Deshalb im Zweifel immer gegen den Marker.
+ */
+export function insertCitations({ text, supports, chunkNumbers }) {
+  if (!text || supports.length === 0) return { text, dropped: 0 };
+
+  const bytes = Buffer.from(text, "utf8");
+  const codeRanges = findCodeRanges(text);
+  const insertions = [];
+  let dropped = 0;
+
+  for (const support of supports) {
+    const segment = support.segment ?? {};
+    const end = segment.endIndex;
+    if (typeof end !== "number") continue;
+
+    // Protobuf laesst Defaultwerte weg: startIndex fehlt im JSON, wenn er 0
+    // ist. Ohne ?? 0 ergaebe die Pruefung darunter NaN und schluege immer fehl.
+    const start = segment.startIndex ?? 0;
+
+    // Die einzige Absicherung gegen eine stille Aenderung der
+    // Offset-Semantik: Die API liefert den erwarteten Ausschnitt in
+    // segment.text mit. Passt er nicht zur berechneten Position, wird nicht
+    // geraten, sondern der Marker weggelassen. Damit kann ein Marker nie an
+    // der falschen Stelle landen - er kann nur fehlen.
+    if (segment.text !== undefined && bytes.subarray(start, end).toString("utf8") !== segment.text) {
+      dropped++;
+      continue;
+    }
+
+    if (codeRanges.some(([from, to]) => end > from && end < to)) {
+      dropped++;
+      continue;
+    }
+
+    // groundingChunkIndices verweist auf die UNDEDUPLIZIERTE Trefferliste der
+    // API - gemessen 14 Treffer bei nur 4 eindeutigen URLs. Ein naives
+    // index + 1 schriebe damit Nummern bis [14] in eine Liste mit vier
+    // Eintraegen. chunkNumbers uebersetzt; Treffer, die es nicht in die Liste
+    // geschafft haben, erzeugen keinen Marker.
+    const numbers = [
+      ...new Set(
+        (support.groundingChunkIndices ?? [])
+          .map((index) => chunkNumbers.get(index))
+          .filter((number) => number !== undefined),
+      ),
+    ].sort((a, b) => a - b);
+
+    // Kein dropped++: Hier gab es nichts zu setzen, nichts ging verloren.
+    if (numbers.length === 0) continue;
+
+    insertions.push({ index: end, marker: numbers.map((n) => `[${n}]`).join("") });
+  }
+
+  if (insertions.length === 0) return { text, dropped };
+
+  // Von hinten nach vorn, damit bereits eingesetzte Zeichen die noch
+  // ausstehenden Positionen nicht verschieben.
+  insertions.sort((a, b) => b.index - a.index);
+
+  // Die Bytestuecke werden gesammelt und EINMAL zusammengesetzt, statt bei
+  // jedem Marker einen neuen Puffer zu bauen (Muster aus Googles
+  // Referenzimplementierung). Buffer statt TextEncoder/Uint8Array: identische
+  // Byte-Semantik, aber kuerzer - der Server laeuft ausschliesslich unter
+  // Node, die Portabilitaet, wegen der Google dort TextEncoder nutzt, wird
+  // hier nicht gebraucht.
+  const chunks = [];
+  let lastIndex = bytes.length;
+  for (const { index, marker } of insertions) {
+    // Faengt einen Offset ab, der ueber das Textende hinausweist - sonst
+    // entstuende ein leeres subarray und der Marker landete am falschen Ort.
+    const position = Math.min(index, lastIndex);
+    chunks.unshift(bytes.subarray(position, lastIndex));
+    chunks.unshift(Buffer.from(marker, "utf8"));
+    lastIndex = position;
+  }
+  chunks.unshift(bytes.subarray(0, lastIndex));
+
+  return { text: Buffer.concat(chunks).toString("utf8"), dropped };
+}

package/cli.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// Kommandozeilen-Frontend auf denselben Kern, den auch index.js nutzt:
+// gemini.js fuer die API-Aufrufe, config.js fuer die gespeicherten Defaults.
+// Die relativen Imports loesen in ES-Modulen relativ zu DIESER Datei auf,
+// nicht zum Arbeitsverzeichnis - die CLI funktioniert daher aus jedem Ordner.
+
+import { runSearch, listModels } from "./gemini.js";
+import {
+  CONFIG_PATH,
+  getSavedModel,
+  getSavedThinkingLevel,
+  setSavedConfig,
+  THINKING_LEVELS,
+} from "./config.js";
+
+const HELP = `gemini-grounding - CLI for the Gemini grounding MCP server
+
+Usage:
+  gemini-grounding "<query>" [--model <id>] [--thinking <level>]
+  gemini-grounding <command> [argument]
+
+Commands:
+  config                 Show saved model, thinking level and API key status
+  models [--all]         List models usable with this server; --all lists every
+                         model the API key exposes, including unusable ones
+  set-model <id>         Persist the default model
+  set-thinking <level>   Persist the default thinking level
+  help                   Show this help
+
+Options (search only, never persisted):
+  --model <id>           Use this model for this call only
+  --thinking <level>     Use this thinking level for this call only
+
+Thinking levels: ${THINKING_LEVELS.join(", ")}
+
+Anything that is not a known command is treated as a search query. The query
+must be a single argument - put it in quotes if it contains spaces.
+The API key is read from the GEMINI_API_KEY environment variable.
+The saved defaults are shared with the MCP server; "config" prints their location.`;
+
+/**
+ * Bedienfehler - falsche Argumente, unbekannte Option, leere Anfrage. Wird
+ * anders behandelt als ein echter Laufzeitfehler: nur die Meldung, kein
+ * Stacktrace, weil ein Tippfehler auf der Kommandozeile keinen braucht.
+ */
+class UsageError extends Error {}
+
+function fail(message) {
+  throw new UsageError(message);
+}
+
+function requireThinkingLevel(value, origin) {
+  if (!THINKING_LEVELS.includes(value)) {
+    fail(`Invalid thinking level "${value}" for ${origin}. Allowed: ${THINKING_LEVELS.join(", ")}`);
+  }
+  return value;
+}
+
+/**
+ * Holt "--name <wert>" aus der Argumentliste und ENTFERNT beides daraus.
+ * Dadurch ist die Position der Flags beliebig und der uebrig bleibende Rest
+ * ist sauber Unterbefehl bzw. Suchanfrage.
+ */
+function takeFlag(args, name) {
+  const index = args.indexOf(`--${name}`);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    fail(`Missing value for --${name}`);
+  }
+  args.splice(index, 2);
+  return value;
+}
+
+/** Wie takeFlag, aber fuer Schalter ohne Wert. */
+function takeSwitch(args, name) {
+  const index = args.indexOf(`--${name}`);
+  if (index === -1) return false;
+  args.splice(index, 1);
+  return true;
+}
+
+async function main() {
+  // argv[0] ist der Node-Interpreter, argv[1] das Skript selbst - erst ab
+  // Index 2 stehen die vom Benutzer uebergebenen Argumente.
+  const args = process.argv.slice(2);
+
+  const modelFlag = takeFlag(args, "model");
+  const thinkingFlag = takeFlag(args, "thinking");
+  const allFlag = takeSwitch(args, "all");
+  if (thinkingFlag !== undefined) requireThinkingLevel(thinkingFlag, "--thinking");
+
+  // Was jetzt noch wie eine Option aussieht, kennt die CLI nicht. Ohne diese
+  // Pruefung bliebe ein Tippfehler folgenlos liegen: "models --al" haette
+  // stillschweigend die gefilterte Liste gezeigt, die man fuer die
+  // vollstaendige haelt. Bewusst nur "--", damit eine Anfrage wie
+  // "-5 Grad in Fahrenheit" weiterhin durchgeht; "--help" ist ausgenommen,
+  // weil es unten als Unterbefehl behandelt wird.
+  const unknownOption = args.find((arg) => arg.startsWith("--") && arg !== "--help");
+  if (unknownOption) fail(`Unknown option "${unknownOption}".`);
+
+  const [command, ...rest] = args;
+
+  // Jeder Zweig prueft, dass nichts Ueberzaehliges uebrig bleibt - sonst
+  // wuerde "set-thinking low unsinn" klaglos speichern und den Rest verwerfen.
+  const requireNoArgs = () => {
+    if (rest.length > 0) fail(`"${command}" takes no arguments.`);
+  };
+
+  switch (command) {
+    case undefined:
+      // Aufruf ohne Argumente ist ein Bedienfehler: Hilfe nach stderr, Exit 1.
+      fail(HELP);
+      break;
+
+    case "help":
+    case "--help":
+    case "-h":
+      requireNoArgs();
+      console.log(HELP);
+      break;
+
+    case "config": {
+      requireNoArgs();
+      const apiKey = process.env.GEMINI_API_KEY;
+      // Der Wert des Keys wird nie ausgegeben, auch nicht gekuerzt - nur seine
+      // Laenge, weil sich daran ein abgeschnittenes Einfuegen erkennen laesst.
+      const keyStatus = apiKey
+        ? `set (${apiKey.length} chars)`
+        : "NOT SET - set the GEMINI_API_KEY environment variable";
+      console.log(`${"Model:".padEnd(16)}${getSavedModel()}`);
+      console.log(`${"Thinking level:".padEnd(16)}${getSavedThinkingLevel()}`);
+      console.log(`${"API key:".padEnd(16)}${keyStatus}`);
+      // Der Pfad wird immer genannt, auch wenn die Datei noch gar nicht
+      // existiert - dann steht dort, wo sie beim ersten set-model entstehen
+      // wird, und die obigen Werte sind die eingebauten Defaults.
+      console.log(`${"Config file:".padEnd(16)}${CONFIG_PATH}`);
+      break;
+    }
+
+    case "models":
+      requireNoArgs();
+      console.log(await listModels({ all: allFlag }));
+      break;
+
+    case "set-model": {
+      if (rest.length !== 1) fail("Usage: gemini-grounding set-model <model-id>");
+      const model = rest[0];
+      setSavedConfig({ model });
+      console.log(`Saved - Model: ${model}`);
+      break;
+    }
+
+    case "set-thinking": {
+      if (rest.length !== 1) {
+        fail(`Usage: gemini-grounding set-thinking <${THINKING_LEVELS.join("|")}>`);
+      }
+      const level = requireThinkingLevel(rest[0], "set-thinking");
+      setSavedConfig({ thinkingLevel: level });
+      console.log(`Saved - Thinking level: ${level}`);
+      break;
+    }
+
+    default: {
+      // Alles, was kein bekannter Unterbefehl ist, gilt als Suchanfrage - und
+      // zwar als genau ein Argument. Eine unquotiert getippte Frage wieder
+      // zusammenzusetzen waere truegerisch: takeFlag hat vorher ein
+      // "--thinking high" mitten aus ihr herausgeschnitten, sodass eine
+      // sinnentstellte Anfrage abgeschickt wuerde, ohne dass es auffaellt.
+      if (rest.length > 0) {
+        fail("The query must be a single argument - put it in quotes.");
+      }
+      const query = command.trim();
+      // Ohne diese Pruefung ginge ein leeres Argument - etwa aus einer nicht
+      // gesetzten Shell-Variablen - als Anfrage an die API und kostet Tokens.
+      if (query === "") fail("The query is empty.");
+
+      // Gleiches Muster wie im MCP-Handler (index.js): ein Flag gilt nur fuer
+      // diesen Aufruf, sonst greift der gespeicherte Standard. config.json wird
+      // dabei nicht angefasst.
+      const text = await runSearch({
+        query,
+        model: modelFlag ?? getSavedModel(),
+        thinkingLevel: thinkingFlag ?? getSavedThinkingLevel(),
+      });
+      console.log(text);
+    }
+  }
+}
+
+try {
+  await main();
+} catch (error) {
+  // Bei einem echten Laufzeitfehler gibt console.error(error) denselben
+  // vollstaendigen Stacktrace aus, den Node bei einem unbehandelten Fehler
+  // zeigen wuerde - beim Testen ist genau das gewollt, im Gegensatz zu
+  // index.js, das den Fehler fuer den Client auf eine Zeile verdichten muss.
+  // Ein Bedienfehler braucht dagegen keinen Stacktrace, nur die Meldung.
+  //
+  // Gefangen wird er trotzdem, weil Node den Prozess bei einer unbehandelten
+  // Rejection hart beendet: haengt dabei noch eine offene Netzwerkverbindung,
+  // bricht libuv unter Windows mit "Assertion failed ... src\win\async.c" ab
+  // und der Prozess endet mit 0xC0000409 statt mit dem vereinbarten Code 1.
+  //
+  // process.exitCode statt process.exit(), damit Node regulaer herunterfaehrt -
+  // das gilt ausnahmslos, deshalb wirft auch fail() nur einen UsageError,
+  // statt selbst zu beenden: stdout und stderr sind unter Windows auf einem
+  // TTY asynchron, sodass process.exit() eine laengere Ausgabe wie HELP
+  // abschneiden koennte.
+  console.error(error instanceof UsageError ? error.message : error);
+  process.exitCode = 1;
+}

package/config.js

@@ -0,0 +1,87 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+// Plattformueblicher Ort fuer Nutzer-State, NICHT "./config.json" - das
+// Arbeitsverzeichnis eines per stdio gestarteten MCP-Servers ist nicht
+// garantiert der Projektordner. Auch nicht scriptrelativ: bei "npm install -g"
+// liegt das Script in einem Verzeichnis, das der Paketmanager verwaltet und
+// beim Update neu schreibt, bei "npx" in einem Cache, dessen Hash sich mit
+// jeder Version aendert - die Einstellung waere dort praktisch fluechtig.
+//
+// Reihenfolge: XDG_CONFIG_HOME gewinnt, wenn gesetzt (Linux-Konvention und
+// zugleich das Ventil fuer alle, die den Standardort nicht wollen). Sonst
+// unter Windows %APPDATA%, wo Nutzer-State hingehoert - nicht ~/.config.
+// macOS wird bewusst wie Linux behandelt: Der Apple-Standard waere
+// ~/Library/Application Support/, aber dies ist ein Terminal-Werkzeug, und im
+// Terminal sucht niemand in einem im Finder ausgeblendeten Ordner.
+const CONFIG_DIR = path.join(
+  process.env.XDG_CONFIG_HOME ??
+    (process.platform === "win32"
+      ? (process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"))
+      : path.join(os.homedir(), ".config")),
+  "gemini-grounding-mcp",
+);
+
+/**
+ * Vollstaendiger Pfad der Konfigurationsdatei. Exportiert, weil
+ * Auffindbarkeit ueber die Ausgabe entsteht und nicht ueber den Ort: MCP-Server
+ * und CLI nennen den Pfad, damit niemand raten muss, wo die Einstellung liegt.
+ */
+export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+const FALLBACK_MODEL = "gemini-flash-latest";
+// Bewusst "medium" und nicht "high": der Fallback greift bei jedem neuen
+// Nutzer ohne config.json, und ein hoeheres Level kostet ungefragt mehr
+// Thinking-Tokens. Wer mehr will, setzt es per gemini-set-model dauerhaft
+// oder pro Aufruf.
+const FALLBACK_THINKING_LEVEL = "medium";
+
+/**
+ * Die von der Gemini-API akzeptierten Thinking-Level - einzige Quelle fuer
+ * MCP-Server und CLI, damit beide dieselben Werte zulassen. index.js macht
+ * daraus die Zod-Schemas (z.enum nimmt dieses Array direkt), cli.js prueft
+ * damit seine Kommandozeilenargumente.
+ */
+export const THINKING_LEVELS = ["minimal", "low", "medium", "high"];
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Liest das dauerhaft gespeicherte Standardmodell.
+ * Liefert FALLBACK_MODEL, falls keine oder eine kaputte config.json existiert.
+ */
+export function getSavedModel() {
+  return readConfig().model ?? FALLBACK_MODEL;
+}
+
+/**
+ * Liest das dauerhaft gespeicherte Standard-Thinking-Level.
+ * Liefert FALLBACK_THINKING_LEVEL, falls keine oder eine kaputte config.json existiert.
+ */
+export function getSavedThinkingLevel() {
+  return readConfig().thinkingLevel ?? FALLBACK_THINKING_LEVEL;
+}
+
+/**
+ * Speichert Modell und/oder Thinking-Level dauerhaft, ohne den jeweils
+ * anderen gespeicherten Wert zu ueberschreiben (undefined-Felder bleiben
+ * unangetastet). Enthaelt ausschliesslich diese beiden Werte, niemals den
+ * API-Key oder andere sensible Daten.
+ */
+export function setSavedConfig({ model, thinkingLevel }) {
+  const config = readConfig();
+  if (model !== undefined) config.model = model;
+  if (thinkingLevel !== undefined) config.thinkingLevel = thinkingLevel;
+  // Nur hier im Schreibpfad angelegt, damit das Paket nichts ungefragt
+  // erzeugt: Solange niemand das Modell setzt, entsteht weder Verzeichnis noch
+  // Datei - readConfig() faengt die fehlende Datei bereits ab.
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}

package/gemini.js

@@ -0,0 +1,309 @@
+import { GoogleGenAI } from "@google/genai";
+import { insertCitations } from "./citations.js";
+
+function getClient() {
+  const apiKey = process.env.GEMINI_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "GEMINI_API_KEY is not set. The API key must be provided via environment " +
+        "variable (never hardcoded).",
+    );
+  }
+  return new GoogleGenAI({ apiKey });
+}
+
+/**
+ * Baut die Quellenliste aus zwei getrennten Metadaten-Quellen der Gemini-API:
+ * - groundingChunks: Treffer der Google-Suche
+ * - urlContextMetadata: Seiten, die Gemini gezielt per URL Context gelesen hat
+ * Beide Listen werden zusammengefuehrt und nach URL entduplifiziert.
+ *
+ * Liefert zusaetzlich chunkNumbers: die Zuordnung vom Index in
+ * groundingChunks auf die Nummer in der AUSGEGEBENEN Liste. Beide Zaehlungen
+ * laufen auseinander, weil groundingChunks Suchtreffer abbildet und nicht
+ * Quellen - gemessen 17 Treffer bei 14 eindeutigen URLs. Ohne diese Zuordnung
+ * verwiesen die Marker im Text auf Nummern, die es in der Liste nicht gibt.
+ */
+function buildSourceList(candidate) {
+  const searchChunks = candidate?.groundingMetadata?.groundingChunks ?? [];
+  const urlContextEntries = candidate?.urlContextMetadata?.urlMetadata ?? [];
+
+  const numberByUri = new Map();
+  const chunkNumbers = new Map();
+  const sources = [];
+
+  const addSource = (title, uri) => {
+    if (!numberByUri.has(uri)) {
+      sources.push({ title, uri });
+      numberByUri.set(uri, sources.length);
+    }
+    return numberByUri.get(uri);
+  };
+
+  searchChunks.forEach((chunk, index) => {
+    const uri = chunk.web?.uri;
+    if (!uri) return;
+    chunkNumbers.set(index, addSource(chunk.web?.title ?? uri, uri));
+  });
+
+  // URL-Context-Quellen stehen hinter den Suchtreffern und beeinflussen die
+  // Nummerierung der Marker deshalb nicht.
+  //
+  // Gemessen an einer Anfrage mit konkreter URL: Die gelesene Seite stand
+  // zusaetzlich als groundingChunk in der Antwort - mit echtem Seitentitel,
+  // direkter URL und eigenen Supports. Sie kam ueber die Deduplizierung hier
+  // also gar nicht mehr an und bekam trotzdem Marker. Hier landet nur eine
+  // Seite, die NICHT zugleich Chunk ist; die bleibt dann ohne Marker, weil es
+  // zu ihr keine Supports gibt.
+  for (const entry of urlContextEntries) {
+    if (entry.retrievedUrl) addSource(entry.retrievedUrl, entry.retrievedUrl);
+  }
+
+  return { sources, chunkNumbers };
+}
+
+function formatSourcesBlock(sources) {
+  if (sources.length === 0) return "";
+  const list = sources
+    .map((s, i) => `[${i + 1}] ${s.title} - ${s.uri}`)
+    .join("\n");
+  return `\n\nSources:\n${list}`;
+}
+
+/**
+ * Baut den Antworttext aus den Parts der Antwort, statt `response.text` zu
+ * nutzen. Der `.text`-Getter des SDK verwirft alles, was kein Textteil ist -
+ * bei aktiviertem Code Execution also gerade den ausgefuehrten Code und dessen
+ * Ergebnis - und schreibt dabei pro Aufruf eine Warnung nach stderr. Hier
+ * kommen beide als Codebloecke mit in die Antwort, damit nachvollziehbar
+ * bleibt, wie eine berechnete Zahl zustande gekommen ist.
+ *
+ * Code und Ergebnis kommen dabei ans ENDE, hinter den Antworttext. Die API
+ * liefert die Parts in Ausfuehrungsreihenfolge, sodass die Antwort sonst mit
+ * einem Codeblock beginnt und die eigentliche Auskunft erst darunter steht.
+ * Der Rechenweg ist ein Beleg und gehoert damit dorthin, wo auch die
+ * Quellenliste steht: hinter die Antwort, nicht davor.
+ *
+ * Hier werden ausserdem die Belegmarker gesetzt (siehe citations.js) -
+ * bewusst an dieser Stelle, weil die Parts nur hier noch einzeln vorliegen:
+ * Die Offsets der API zaehlen ab dem Anfang JEDES Parts, nach dem
+ * join("\n\n") waeren sie ab dem zweiten Part um zwei Bytes verschoben.
+ */
+function buildText(candidate, { supports, chunkNumbers }) {
+  const textBlocks = [];
+  const codeBlocks = [];
+  let dropped = 0;
+
+  // forEach statt for...of: Der Schleifenindex IST der partIndex, auf den sich
+  // segment.partIndex bezieht. Denk-Parts werden zwar uebersprungen, zaehlen
+  // dabei aber mit - partIndex zaehlt ueber ALLE Parts des Kandidaten.
+  (candidate?.content?.parts ?? []).forEach((part, partIndex) => {
+    // Denk-Parts gehoeren nicht in die Ausgabe - ihr Umfang steht bereits als
+    // Thinking-Tokens im Footer.
+    if (part.thought) return;
+
+    if (part.text) {
+      // partIndex fehlt im JSON, wenn er 0 ist (Protobuf-Default), daher ?? 0.
+      const result = insertCitations({
+        text: part.text,
+        supports: supports.filter((s) => (s.segment?.partIndex ?? 0) === partIndex),
+        chunkNumbers,
+      });
+      textBlocks.push(result.text);
+      dropped += result.dropped;
+    } else if (part.executableCode?.code) {
+      // language ist das Language-Enum ("PYTHON"); LANGUAGE_UNSPECIFIED ergibt
+      // keine sinnvolle Sprachangabe fuer den Codeblock.
+      const language = (part.executableCode.language ?? "").toLowerCase();
+      const fence = language.includes("unspecified") ? "" : language;
+      // trimEnd, weil Code und Ausgabe mit einem Zeilenumbruch enden - sonst
+      // steht eine Leerzeile vor dem schliessenden Codeblock.
+      codeBlocks.push(`\`\`\`${fence}\n${part.executableCode.code.trimEnd()}\n\`\`\``);
+    } else if (part.codeExecutionResult) {
+      // outcome ist "OUTCOME_OK", "OUTCOME_FAILED", ... - das Praefix traegt
+      // keine Information.
+      const outcome =
+        (part.codeExecutionResult.outcome ?? "").replace(/^OUTCOME_/, "") || "UNKNOWN";
+      const output = (part.codeExecutionResult.output ?? "").trimEnd();
+      codeBlocks.push(`Result (${outcome}):\n\`\`\`\n${output}\n\`\`\``);
+    }
+  });
+
+  // Ueberschrift wie bei der Quellenliste, damit der nachgestellte Rechenweg
+  // nicht als Fortsetzung des Antworttextes gelesen wird.
+  if (codeBlocks.length > 0) codeBlocks.unshift("Code execution:");
+
+  return { text: [...textBlocks, ...codeBlocks].join("\n\n"), dropped };
+}
+
+/**
+ * Weist auf eine Antwort hin, die nicht regulaer zu Ende gelaufen ist. Ohne
+ * diesen Hinweis saehe eine blockierte oder abgeschnittene Antwort wie ein
+ * Erfolg aus: der Text fehlt oder bricht mitten im Satz ab, Quellenliste und
+ * Footer stehen trotzdem unveraendert darunter.
+ */
+function formatNotice({ text, candidate, promptFeedback }) {
+  const blockReason = promptFeedback?.blockReason;
+  if (blockReason) {
+    return `\n\n⚠️ Request blocked by the API - blockReason: ${blockReason}`;
+  }
+
+  const finishReason = candidate?.finishReason;
+  if (text === "") {
+    return `\n\n⚠️ The response contained no text - finishReason: ${finishReason ?? "unknown"}`;
+  }
+  // STOP ist der regulaere Abschluss. Alles andere - vor allem MAX_TOKENS -
+  // bedeutet eine abgeschnittene Antwort, die sonst vollstaendig wirkt.
+  if (finishReason && finishReason !== "STOP") {
+    return `\n\n⚠️ The response is incomplete - finishReason: ${finishReason}`;
+  }
+  return "";
+}
+
+function formatFooter({ usageMetadata, model, thinkingLevel, sourceCount, dropped }) {
+  const inputTokens = usageMetadata?.promptTokenCount ?? 0;
+  const outputTokens = usageMetadata?.candidatesTokenCount ?? 0;
+  const thinkingTokens = usageMetadata?.thoughtsTokenCount ?? 0;
+
+  // Verworfene Marker gehoeren in den Footer, weil sie die Aussagekraft der
+  // Antwort veraendern: Fehlt ein Marker, kann die Stelle ungegroundet sein -
+  // oder die Pruefung hat ihn verworfen. Nur sichtbar, wenn es welche gab,
+  // damit der Normalfall den Footer nicht verlaengert.
+  const droppedNote = dropped > 0 ? ` | ⚠️ ${dropped} markers dropped` : "";
+
+  return (
+    `\n\n---\n🔢 ${inputTokens} input / ${outputTokens} output / ${thinkingTokens} thinking tokens ` +
+    `| 🔍 ${sourceCount} sources | 🤖 ${model} (thinking: ${thinkingLevel})${droppedNote}`
+  );
+}
+
+/**
+ * Fuehrt eine Gemini-Recherche mit allen drei Built-in-Tools durch
+ * (Google Search, URL Context, Code Execution), setzt die Belegmarker in den
+ * Antworttext und haengt Quellenliste sowie Token-Footer an.
+ */
+export async function runSearch({ query, model, thinkingLevel }) {
+  const ai = getClient();
+
+  const response = await ai.models.generateContent({
+    model,
+    contents: query,
+    config: {
+      tools: [{ googleSearch: {} }, { urlContext: {} }, { codeExecution: {} }],
+      thinkingConfig: { thinkingLevel },
+    },
+  });
+
+  const candidate = response.candidates?.[0];
+  const { sources, chunkNumbers } = buildSourceList(candidate);
+
+  // Das ?? [] ist die Absicherung gegen eine Antwort ohne groundingMetadata -
+  // dann laeuft alles unveraendert durch, nur ohne Marker.
+  const { text, dropped } = buildText(candidate, {
+    supports: candidate?.groundingMetadata?.groundingSupports ?? [],
+    chunkNumbers,
+  });
+
+  const notice = formatNotice({
+    text,
+    candidate,
+    promptFeedback: response.promptFeedback,
+  });
+  const sourcesBlock = formatSourcesBlock(sources);
+  const footer = formatFooter({
+    usageMetadata: response.usageMetadata,
+    model,
+    thinkingLevel,
+    sourceCount: sources.length,
+    dropped,
+  });
+
+  // Der Footer bleibt in jedem Fall der letzte Bestandteil der Antwort.
+  return text + notice + sourcesBlock + footer;
+}
+
+/** Kuerzt eine Tokenzahl lesbar ab: 1048576 -> 1M, 65536 -> 64k. */
+function formatTokenLimit(limit) {
+  if (typeof limit !== "number") return "?";
+  if (limit >= 1024 * 1024) return `${Math.round(limit / (1024 * 1024))}M`;
+  if (limit >= 1024) return `${Math.round(limit / 1024)}k`;
+  return String(limit);
+}
+
+/**
+ * Ob ein Modell mit DIESEM Server funktioniert. Zwei Bedingungen, beide aus
+ * den Angaben der API selbst statt aus dem Modellnamen - ein Namensmuster
+ * wuerde bei jeder neuen Modellfamilie brechen (Codenamen wie
+ * "nano-banana-pro-preview" verraten nichts ueber die Faehigkeiten):
+ * - generateContent: erzeugt ueberhaupt Text (schliesst Embeddings, Imagen,
+ *   Veo und die Live-/Audio-Modelle aus)
+ * - thinking: akzeptiert ein Thinking-Level. runSearch schickt immer eines
+ *   mit, andernfalls antwortet die API mit
+ *   400 "Thinking level is not supported for this model."
+ */
+function isUsableModel(model) {
+  return (model.supportedActions ?? []).includes("generateContent") && model.thinking === true;
+}
+
+/** Warum ein Modell nicht in der Standardliste steht - nur fuer die --all-Ansicht. */
+function modelStatus(model) {
+  const actions = model.supportedActions ?? [];
+  if (!actions.includes("generateContent")) return actions[0] ?? "no generateContent";
+  return model.thinking === true ? "thinking" : "no thinking";
+}
+
+/**
+ * Listet die fuer den aktuellen API-Key verfuegbaren Modelle mit Token-Limits.
+ * Standardmaessig nur die, die mit diesem Server nutzbar sind; mit all=true
+ * die vollstaendige Liste inkl. Statusspalte.
+ *
+ * Die Liste sagt nichts ueber die Verfuegbarkeit aus: abgekuendigte Modelle
+ * erscheinen weiterhin, antworten aber mit 404. Ein Feld dafuer gibt es nicht.
+ */
+export async function listModels({ all = false } = {}) {
+  const ai = getClient();
+  const pager = await ai.models.list({ config: { pageSize: 50 } });
+
+  const models = [];
+  for await (const model of pager) models.push(model);
+  if (models.length === 0) return "No models available for this API key.";
+
+  const usable = models.filter(isUsableModel);
+
+  // Sicherung gegen ein leeres Ergebnis, falls die API die ausgewerteten
+  // Felder einmal nicht mehr liefert: dann lieber die volle Liste zeigen als
+  // gar keine.
+  const filterFailed = usable.length === 0;
+  const showAll = all || filterFailed;
+  const shown = [...(showAll ? models : usable)];
+
+  const name = (model) => (model.name ?? "?").replace(/^models\//, "");
+  shown.sort((a, b) => name(a).localeCompare(name(b)));
+  const width = Math.max(...shown.map((model) => name(model).length));
+
+  const lines = shown.map((model) => {
+    const limits =
+      `${formatTokenLimit(model.inputTokenLimit).padStart(4)} in / ` +
+      `${formatTokenLimit(model.outputTokenLimit).padStart(4)} out`;
+    const status = showAll ? `  ${modelStatus(model)}` : "";
+    return `${name(model).padEnd(width)}  ${limits}${status}`;
+  });
+
+  let note;
+  if (filterFailed) {
+    note =
+      `All ${models.length} models - the usability filter matched nothing, so ` +
+      "nothing is hidden. Check whether the API still reports supportedActions and thinking.";
+  } else if (all) {
+    note =
+      `All ${models.length} models. Only the ${usable.length} marked "thinking" work with ` +
+      "this server, which always sends a thinking level. Being listed is no guarantee " +
+      "a model still answers - retired ones stay in this list and return 404.";
+  } else {
+    note =
+      `${usable.length} of ${models.length} models usable with this server (text generation ` +
+      "plus thinking level support). Request all models to see the rest.";
+  }
+
+  return `${lines.join("\n")}\n\n${note}`;
+}

package/index.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// Der Shebang macht die Datei als bin-Eintrag direkt ausfuehrbar - noetig,
+// damit "npx @brobertoblanko/gemini-grounding-mcp" den Server startet.
+
+import { createRequire } from "node:module";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { runSearch, listModels } from "./gemini.js";
+import {
+  CONFIG_PATH,
+  getSavedModel,
+  getSavedThinkingLevel,
+  setSavedConfig,
+  THINKING_LEVELS,
+} from "./config.js";
+
+// Die Version kommt aus der package.json, damit sie nur an einer Stelle
+// gepflegt wird - eine zweite, von Hand nachgezogene Zahl meldet dem Client
+// frueher oder spaeter eine Fassung, die nicht der ausgelieferten entspricht.
+// createRequire statt import ... with { type: "json" }: Import Attributes gibt
+// es erst ab Node 20.10, engines erlaubt aber jedes 20.x - dort waere es ein
+// Syntaxfehler, den niemand abfangen kann, waehrend createRequire seit jeher
+// laeuft. Die package.json liegt neben dieser Datei, im Klon wie im
+// installierten Paket: npm packt sie immer mit, unabhaengig von files.
+const { version } = createRequire(import.meta.url)("./package.json");
+
+const server = new McpServer(
+  {
+    name: "gemini-grounding",
+    title: "Gemini Web Search",
+    version,
+    description:
+      "Web search and research via Google's Gemini API with grounding - " +
+      "current, cited information for library APIs, software behavior, and recent events.",
+  },
+  {
+    instructions:
+      "Search and research the web through Google's Gemini API with grounding. " +
+      "Use this server to retrieve current, cited information - library APIs, " +
+      "software behavior, recent events, or any fact that may be newer than a " +
+      "model's training data.\n" +
+      "- gemini-search: the model and thinking level actually used are always shown in the " +
+      "response footer, so the user can see them without guessing.\n" +
+      "- On errors, report them clearly - never silently fall back to another model.\n" +
+      "- Before changing the default model, list what's available with gemini-list-models; " +
+      "use gemini-set-model only when explicitly asked.\n" +
+      "- Every answer has a source list and a token-usage footer appended - keep them intact.",
+  },
+);
+
+server.registerTool(
+  "gemini-search",
+  {
+    title: "Gemini web search with grounding",
+    description:
+      "Run a web search / research query through the Gemini API. Combines " +
+      "Google Search, URL context, and code execution in a single call. " +
+      "Uses the saved default model and thinking level unless the user " +
+      "explicitly requests a different one for this call - the default " +
+      "can be changed anytime via gemini-set-model. " +
+      "The response includes a source list and a token-usage footer.",
+    inputSchema: {
+      query: z.string().describe("The search or research query"),
+      model: z
+        .string()
+        .optional()
+        .describe(
+          "Gemini model, e.g. gemini-flash-latest. Omit to use the saved " +
+            "default; only set when the user explicitly asks for a specific model.",
+        ),
+      thinkingLevel: z
+        .enum(THINKING_LEVELS)
+        .optional()
+        .describe(
+          "Model reasoning depth. Omit to use the saved default; only set " +
+            "when the user explicitly asks for a specific thinking level.",
+        ),
+    },
+  },
+  // Die Defaults werden hier im Handler aufgeloest, NICHT als Zod-.default() im
+  // Schema: ein Schema-Default wird einmal beim Registrieren ausgewertet und
+  // eingefroren, sodass gemini-set-model erst nach einem Serverneustart wirken
+  // wuerde. Der Footer zeigt dadurch immer die tatsaechlich genutzten Werte.
+  async ({ query, model, thinkingLevel }) => {
+    try {
+      const text = await runSearch({
+        query,
+        model: model ?? getSavedModel(),
+        thinkingLevel: thinkingLevel ?? getSavedThinkingLevel(),
+      });
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error in gemini-search: ${error.message}` }],
+        isError: true,
+      };
+    }
+  },
+);
+
+server.registerTool(
+  "gemini-list-models",
+  {
+    title: "List available Gemini models",
+    description:
+      "List the Gemini models available for the current API key with their token " +
+      "limits. By default only models usable with this server - they generate text " +
+      "and accept a thinking level, which gemini-search always sends. Being listed " +
+      "is no guarantee a model still answers: retired models remain in the list and " +
+      "return 404 on use.",
+    inputSchema: {
+      all: z
+        .boolean()
+        .optional()
+        .describe(
+          "List every model the API key exposes, including those that cannot be " +
+            "used here (embedding, image, video, audio models). Off by default.",
+        ),
+    },
+  },
+  async ({ all }) => {
+    try {
+      const text = await listModels({ all });
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error in gemini-list-models: ${error.message}` }],
+        isError: true,
+      };
+    }
+  },
+);
+
+server.registerTool(
+  "gemini-set-model",
+  {
+    title: "Set default model and/or thinking level",
+    description:
+      "Persist the default model ID and/or thinking level to the user config file. " +
+      "Used by gemini-search as the default from the next call on, unless the call " +
+      "specifies otherwise. Check availability with gemini-list-models first. At " +
+      "least one of the two parameters is required.",
+    inputSchema: {
+      model: z
+        .string()
+        .optional()
+        .describe(
+          "Model ID, e.g. gemini-flash-latest or a pinned model like gemini-3.5-flash",
+        ),
+      thinkingLevel: z.enum(THINKING_LEVELS).optional().describe("Model reasoning depth"),
+    },
+  },
+  async ({ model, thinkingLevel }) => {
+    if (model === undefined && thinkingLevel === undefined) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Error in gemini-set-model: model or thinkingLevel must be provided.",
+          },
+        ],
+        isError: true,
+      };
+    }
+    // Schreibfehler sind hier real moeglich - das Zielverzeichnis wird beim
+    // Speichern erst angelegt und kann je nach Rechten oder verschobenem
+    // %APPDATA% unbeschreibbar sein. Ohne catch liefe der Fehler ungefangen aus
+    // dem Handler; mit catch kommt er als saubere isError-Antwort samt Pfad an.
+    try {
+      setSavedConfig({ model, thinkingLevel });
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error in gemini-set-model: could not write ${CONFIG_PATH} - ${error.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+    const parts = [];
+    if (model !== undefined) parts.push(`Model: ${model}`);
+    if (thinkingLevel !== undefined) parts.push(`Thinking level: ${thinkingLevel}`);
+    return {
+      content: [{ type: "text", text: `Saved to ${CONFIG_PATH} - ${parts.join(", ")}` }],
+    };
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@brobertoblanko/gemini-grounding-mcp",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Minimal MCP server for Google web search via the Gemini API with grounding, inline citation markers and a token footer.",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "anthropic",
+    "gemini",
+    "gemini-api",
+    "google-gemini",
+    "grounding",
+    "web-search",
+    "google-search",
+    "citations",
+    "research",
+    "llm",
+    "nodejs"
+  ],
+  "homepage": "https://github.com/srzsn22q6d-sys/gemini-grounding-mcp#readme",
+  "bugs": "https://github.com/srzsn22q6d-sys/gemini-grounding-mcp/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/srzsn22q6d-sys/gemini-grounding-mcp.git"
+  },
+  "author": "Broberto Blanko <246734967+srzsn22q6d-sys@users.noreply.github.com>",
+  "license": "MIT",
+  "bin": {
+    "gemini-grounding-mcp": "index.js",
+    "gemini-grounding": "cli.js"
+  },
+  "files": [
+    "index.js",
+    "cli.js",
+    "config.js",
+    "gemini.js",
+    "citations.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@google/genai": "2.13.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "4.4.3"
+  }
+}