Gemini Researcher

Ein leichtgewichtiger, zustandsloser MCP-Server (Model Context Protocol), der es Entwickler-Agenten (Claude Code, GitHub Copilot) ermöglicht, tiefgreifende Repository-Analysen an das Gemini CLI zu delegieren. Der Server ist schreibgeschützt, gibt strukturiertes JSON (als Textinhalt) zurück und wurde entwickelt, um den Kontext- und Modellverbrauch des aufrufenden Agenten zu reduzieren.

Status: v1 abgeschlossen. Kernfunktionen sind stabil, aber es ist noch ein frühes Stadium. Feedback ist willkommen!

Wenn Ihnen das Token gespart hat, ⭐ ziehen Sie bitte in Betracht, ihm einen Stern zu geben! :)

Die Hauptziele:

• Reduzierung des Kontextverbrauchs des Agenten, indem das Gemini CLI große Codebasen lokal lesen und seine eigene Recherche durchführen kann

• Reduzierung des Modellverbrauchs des aufrufenden Agenten durch Auslagerung schwerer Analysen an Gemini

• Den Server aus Sicherheitsgründen zustandslos und schreibgeschützt halten

Warum das verwenden?

Anstatt ganze Dateien in den Kontext Ihres Agenten zu kopieren (was Token verbraucht und die Konversation unübersichtlich macht), ermöglicht dieser Server dem Gemini CLI, Dateien direkt aus Ihrem Projekt zu lesen. Ihr Agent sendet eine Rechercheanfrage, Gemini liest und synthetisiert diese unter Verwendung seines großen Kontextfensters und gibt strukturierte Ergebnisse zurück. Sie sparen Token, Ihr Agent bleibt fokussiert und komplexe Codebase-Analysen werden praktikabel.

Verifizierte Clients: Claude Code, Cursor, VS Code (GitHub Copilot)

Inhaltsverzeichnis

• Gemini Researcher

  • Übersicht

  • Voraussetzungen

  • Schnellstart

    • Schritt 1: Umgebung validieren

    • Schritt 2: MCP-Client konfigurieren

    • Schritt 3: MCP-Client neu starten

    • Schritt 4: Testen

  • Tools

    • Beispiel-Workflows

  • Docker

  • Fehlerbehebung (häufige Probleme)

  • Mitwirken

  • Lizenz

Übersicht

Gemini Researcher akzeptiert Anfragen im Recherche-Stil über das MCP-Protokoll und startet das Gemini CLI im Headless-Modus, um lokale Dateien zu analysieren, auf die mit @path verwiesen wird. Die Ergebnisse werden als formatierte JSON-Strings für Agenten-Clients zurückgegeben.

Laufzeitsicherheitsvertrag

Kanonische Laufzeitsemantik wird in docs/runtime-contract.md gepflegt.

Gemini Researcher erzwingt diesen Aufrufvertrag für Analyseanfragen:

gemini [ -m <model> ] --output-format json --approval-mode default [--admin-policy <path>] -p "<prompt>"

• Der Server verwendet -p/--prompt für explizite, nicht-interaktive Headless-Ausführung.

• Der Server verwendet kein -y/--yolo in vom Server generierten argv.

• Schreibgeschütztes Verhalten wird standardmäßig durch eine gebündelte Admin-Richtlinie erzwungen.

• Die strikte Durchsetzung der Admin-Richtlinie kann mit GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0 (oder false|no|off) gelockert werden.

Verhalten der Schreibschutz-Richtlinie

• Der Standardmodus ist eine strikte Fail-Closed-Durchsetzung.

• Die gebündelte Richtlinie verweigert bekannte mutierende Tools (zum Beispiel: write_file, replace, run_shell_command).

• Die Richtlinie basiert auf einer Negativliste. Wenn Gemini in zukünftigen Versionen neue mutierende Tool-Namen einführt, können Richtlinienaktualisierungen erforderlich sein.

• Erweiterungen bleiben standardmäßig aktiviert. Dies ist praktisch, bedeutet aber, dass die Richtliniendurchsetzung in der Produktion aktiviert bleiben sollte.

Authentifizierungs- und Gesundheitssemantik

Wenn Sie health_check mit includeDiagnostics: true ausführen, enthalten die Diagnosen den Authentifizierungsstatus und den Durchsetzungsstatus.

health_check.status ist:

• ok nur, wenn Gemini verfügbar ist, die Authentifizierung konfiguriert ist und die strikte Schreibschutz-Durchsetzung erfüllt ist (oder absichtlich durch Umgebungsvariable gelockert wurde).

• degraded für alle Pfade mit Unsicherheiten bei Einrichtung/Sicherheit/Authentifizierung.

Voraussetzungen

• Node.js 18+ installiert

• Gemini CLI installiert: npm install -g @google/gemini-cli

• Gemini CLI authentifiziert (empfohlen: gemini → Login mit Google) oder GEMINI_API_KEY gesetzt

Schnelltests:

node --version
gemini --version

Schnellstart

Schritt 1: Umgebung validieren

Führen Sie den Einrichtungsassistenten aus, um zu überprüfen, ob das Gemini CLI installiert und authentifiziert ist:

npx gemini-researcher init

Schritt 2: MCP-Client konfigurieren

Standardkonfiguration funktioniert in den meisten Tools:

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

Fügen Sie dies zu Ihren VS Code MCP-Einstellungen hinzu (erstellen Sie bei Bedarf .vscode/mcp.json):

{
  "servers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

Option 1: Befehlszeile (empfohlen)

Lokaler (benutzerweiter) Bereich

# Add the MCP server via CLI
claude mcp add --transport stdio gemini-researcher -- npx gemini-researcher 

# Verify it was added
claude mcp list

Projektbereich

Navigieren Sie zu Ihrem Projektverzeichnis und führen Sie dann aus:

# Add the MCP server via CLI
claude mcp add --scope project --transport stdio gemini-researcher -- npx gemini-researcher

# Verify it was added
claude mcp list

Option 2: Manuelle Konfiguration

Fügen Sie dies zu .mcp.json in Ihrem Projektstammverzeichnis hinzu (Projektbereich):

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

Oder fügen Sie es für den lokalen Bereich zu ~/.claude/settings.json hinzu.

Starten Sie nach dem Hinzufügen des Servers Claude Code neu und verwenden Sie /mcp, um die Verbindung zu überprüfen.

Gehen Sie zu Cursor Settings -> Tools & MCP -> Add a Custom MCP Server. Fügen Sie die folgende Konfiguration hinzu:

{
  "mcpServers": {
    "gemini-researcher": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

Beispiel

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Schritt 3: MCP-Client neu starten

Schritt 4: Testen

Fragen Sie Ihren Agenten: "Use gemini-researcher to analyze the project."

Tools

Alle Tools geben strukturiertes JSON zurück (als MCP-Textinhalt). Große Antworten werden in Chunks unterteilt (~10 KB pro Chunk) und für 1 Stunde zwischengespeichert.

Beispiel-Workflows

Verständnis einer Sicherheitslücke:

Agent: Use deep_research to analyze authentication flow across @src/auth and @src/middleware, focusing on security

Schnelle Code-Erklärung:

Agent: Use quick_query to explain the login flow in @src/auth.ts, be concise

Abbildung einer unbekannten Codebase:

Agent: Use analyze_directory on src/ with depth 3 to understand the project structure

quick_query

{
  "prompt": "Explain @src/auth.ts login flow",
  "focus": "security",
  "responseStyle": "concise"
}

deep_research

{
  "prompt": "Analyze authentication across @src/auth and @src/middleware",
  "focus": "architecture",
  "citationMode": "paths_only"
}

analyze_directory

{
  "path": "src",
  "depth": 3,
  "maxFiles": 200
}

validate_paths

{
  "paths": ["src/auth.ts", "README.md"]
}

health_check

{
  "includeDiagnostics": true
}

fetch_chunk

{
  "cacheKey": "cache_abc123",
  "chunkIndex": 2
}

Docker

Ein vorgefertigtes Multi-Plattform-Docker-Image ist auf Docker Hub verfügbar:

# Pull the image (works on Intel/AMD and Apple Silicon)
docker pull capybearista/gemini-researcher:latest

# Run the server (mount your project and provide API key)
docker run -i --rm \
  -e GEMINI_API_KEY="your-api-key" \
  -v /path/to/your/project:/workspace \
  capybearista/gemini-researcher:latest

Für die MCP-Client-Konfiguration mit Docker:

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GEMINI_API_KEY",
        "-v", "/path/to/your/project:/workspace",
        "capybearista/gemini-researcher:latest"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Fehlerbehebung (häufige Probleme)

• GEMINI_CLI_NOT_FOUND: Installieren Sie das Gemini CLI: npm install -g @google/gemini-cli

• AUTH_MISSING: Führen Sie gemini aus und authentifizieren Sie sich oder setzen Sie GEMINI_API_KEY

• AUTH_UNKNOWN: Authentifizierung konnte nicht bestätigt werden (oft Fehler bei Netzwerk-/CLI-Tests). Überprüfen Sie, ob gemini interaktiv funktioniert, und versuchen Sie es erneut.

• ADMIN_POLICY_MISSING: Installieren Sie das Paket neu oder überprüfen Sie, ob policies/read-only-enforcement.toml im installierten Paket vorhanden ist.

• ADMIN_POLICY_UNSUPPORTED: Aktualisieren Sie das Gemini CLI auf v0.36.0+ (gemini --help sollte --admin-policy enthalten).

• GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0: Deaktiviert die strikte Richtliniendurchsetzung beim Start. Dies schwächt die Fail-Closed-Garantien.

• .gitignore blockiert Dateien: Gemini respektiert standardmäßig .gitignore; schalten Sie fileFiltering.respectGitIgnore in gemini /settings um, wenn Sie absichtlich ignorierte Dateien einbeziehen möchten (Hinweis: dies ändert das Gemini-Verhalten global)

• PATH_NOT_ALLOWED: Alle @path-Referenzen müssen innerhalb des konfigurierten Projektstammverzeichnisses aufgelöst werden (standardmäßig process.cwd()). Verwenden Sie validate_paths, um Pfade vorab zu prüfen.

• QUOTA_EXCEEDED: Der Server versucht es erneut mit Fallback-Modellen; wenn alle Kontingente erschöpft sind, reduzieren Sie den Umfang (verwenden Sie quick_query) oder warten Sie auf das Zurücksetzen des Kontingents.

Mitwirken

Lesen Sie den Contributing Guide, um loszulegen.

Schnelllinks:

• Entwicklungseinrichtung

• Tests ausführen

• Code-Richtlinien

• Änderungen einreichen

Lizenz

BSD-3-Clause License