Gemini Researcher

🚀 Gemini Researcher

Gemini Researcher 是一個輕量級、無狀態的 MCP（模型上下文協議）服務器，它允許開發者代理（如 Claude Code、GitHub Copilot）將深度代碼庫分析任務委託給 Gemini CLI。該服務器為只讀模式，返回結構化的 JSON 數據（以文本形式呈現），旨在減少調用代理的上下文和模型使用量。

項目狀態

當前版本為 v1，核心功能已穩定，但仍處於早期階段，歡迎反饋！

項目目標

• 讓 Gemini CLI 在本地讀取大型代碼庫並進行自主研究，減少代理上下文的使用。
• 將繁重的分析任務卸載到 Gemini，減少調用代理的模型使用量。
• 為確保安全，服務器採用無狀態和只讀模式。

為何使用本項目

通常，將整個文件複製到代理的上下文中會消耗大量令牌並使對話變得混亂。而使用本服務器，Gemini CLI 可以直接從項目中讀取文件。代理發送研究查詢，Gemini 利用其大上下文窗口進行繁重的分析，並返回結構化結果。這樣既能節省令牌，又能使代理保持專注，讓複雜的代碼庫分析變得更加可行。

已驗證的客戶端

Claude Code、Cursor、VS Code（GitHub Copilot）

⚠️ 重要提示

該項目肯定也適用於其他客戶端，但尚未進行個人測試。如果您在其他客戶端上使用，請提交一個 issue！

🚀 快速開始

步驟 1：驗證環境

運行設置嚮導，驗證 Gemini CLI 是否已安裝並完成身份驗證：

npx gemini-researcher init

步驟 2：配置 MCP 客戶端

標準配置

適用於大多數工具：

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

VS Code 配置

添加到 VS Code 的 MCP 設置中（如果需要，創建 .vscode/mcp.json）：

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

Claude Code 配置

選項 1：命令行（推薦）

• 本地（用戶範圍）

# 通過 CLI 添加 MCP 服務器
claude mcp add --transport stdio gemini-researcher -- npx gemini-researcher 

# 驗證是否添加成功
claude mcp list

• 項目範圍 導航到項目目錄，然後運行：

# 通過 CLI 添加 MCP 服務器
claude mcp add --scope project --transport stdio gemini-researcher -- npx gemini-researcher

# 驗證是否添加成功
claude mcp list

選項 2：手動配置

添加到項目根目錄的 .mcp.json 中（項目範圍）：

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

或者添加到 ~/.claude/settings.json 中（本地範圍）。

添加服務器後，重啟 Claude Code 並使用 /mcp 驗證連接。

Cursor 配置

轉到 Cursor Settings -> Tools & MCP -> Add a Custom MCP Server，添加以下配置：

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

⚠️ 重要提示

服務器會自動將 IDE 打開工作區的目錄或終端所在目錄作為項目根目錄。若要分析其他目錄，可選擇設置 PROJECT_ROOT：

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

步驟 3：重啟 MCP 客戶端

步驟 4：測試

向代理提問："Use gemini-researcher to analyze the project."

✨ 主要特性

• 接受基於 MCP 協議的研究式查詢。
• 以無頭、只讀模式啟動 Gemini CLI，對 @path 引用的本地文件進行大上下文分析。
• 返回格式化的 JSON 字符串，便於代理客戶端進行編程式消費。

📦 安裝指南

前提條件

• 安裝 Node.js 18 及以上版本。
• 安裝 Gemini CLI：npm install -g @google/gemini-cli。
• 對 Gemini CLI 進行身份驗證（推薦：gemini → 使用 Google 登錄）或設置 GEMINI_API_KEY。

快速檢查

node --version
gemini --version

💻 使用示例

基礎用法

# 驗證環境
npx gemini-researcher init

高級用法

理解安全漏洞

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

快速代碼解釋

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

映射陌生代碼庫

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 使用

可在 Docker Hub 上獲取預構建的多平臺 Docker 鏡像：

# 拉取鏡像（適用於 Intel/AMD 和 Apple Silicon）
docker pull capybearista/gemini-researcher:latest

# 運行服務器（掛載項目並提供 API 密鑰）
docker run -i --rm \
  -e GEMINI_API_KEY="your-api-key" \
  -v /path/to/your/project:/workspace \
  capybearista/gemini-researcher:latest

MCP 客戶端 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"
      }
    }
  }
}

⚠️ 重要提示

• -i 標誌是 stdio 傳輸所必需的。
• 容器將項目掛載到 /workspace（項目根目錄）。
• 將 /path/to/your/project 替換為實際的項目路徑。
• 將 your-api-key 替換為實際的 Gemini API 密鑰（這是 Docker 使用所必需的）。

常見問題排查

• GEMINI_CLI_NOT_FOUND：安裝 Gemini CLI：npm install -g @google/gemini-cli。
• AUTH_MISSING：運行 gemini 並進行身份驗證，或設置 GEMINI_API_KEY。
• .gitignore 阻止文件：Gemini 默認遵循 .gitignore；如果您有意包含被忽略的文件，請在 gemini /settings 中切換 fileFiltering.respectGitIgnore（注意：這會全局更改 Gemini 的行為）。
• PATH_NOT_ALLOWED：所有 @path 引用必須在配置的項目根目錄內解析（默認是 process.cwd()）。使用 validate_paths 預檢查路徑。
• QUOTA_EXCEEDED：服務器會嘗試使用備用模型；如果所有層級都已用盡，請縮小範圍（使用 quick_query）或等待配額重置。

📄 許可證

本項目採用 BSD-3-Clause 許可證。

為 AI 輔助開發社區用心打造 ❤️