gemini-researcher

Gemini Researcher

一款轻量、无状态的 MCP（模型上下文协议）服务，可让开发者 Agent（Claude Code、GitHub Copilot）将深度代码仓库分析交由 Gemini CLI 处理。该服务为只读模式，以文本形式返回结构化 JSON，旨在减少调用方 Agent 的上下文和模型用量。

状态：v1 已完成。核心功能稳定，但项目仍处于早期阶段。欢迎反馈！

如果它帮你节省了令牌， ⭐ 请考虑点个星！:)

主要目标：

• 让 Gemini CLI 在本地读取大型代码库并自行研究，从而减少 Agent 的上下文用量
• 将繁重的分析工作交给 Gemini，从而减少调用方 Agent 的模型用量
• 保持服务无状态且只读，以确保安全

为什么要使用它？

无需将整个文件复制到 Agent 的上下文中（浪费令牌并让对话变得杂乱），此服务可让 Gemini CLI 直接读取项目中的文件。你的 Agent 发送研究查询，Gemini 利用其大型上下文窗口读取并综合信息，然后返回结构化结果。这样既能节省令牌，也能让 Agent 保持专注，并让复杂的代码库分析变得切实可行。

已验证的客户端： Claude Code、Cursor、VS Code（GitHub Copilot）

说明

它肯定也能与其他客户端配合使用，但我还没有亲自测试过。如果你在其他客户端上试用，请提交 issue！

目录

• Gemini Researcher
  • 概览
  • 先决条件
  • 快速入门
    • 步骤 1：验证环境
    • 步骤 2：配置 MCP 客户端
    • 步骤 3：重启 MCP 客户端
    • 步骤 4：测试
  • 工具
    • 工作流示例
  • Docker
  • 平台指南
  • 故障排除（常见问题）
  • 参与贡献
  • 许可证

概览

Gemini Researcher 接收 AI Agent 的查询，并使用 Gemini CLI 分析本地代码文件。结果将以格式化的 JSON 返回，供 Agent 使用。

运行时安全

该服务在启用安全限制的情况下运行 Gemini CLI。完整的技术细节请参阅 docs/runtime-contract.md。

默认调用模式：

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

主要安全要点：

• 使用 --approval-mode default（而非 yolo 模式）进行受控执行
• 默认强制执行只读策略，以防止文件更改
• 策略会阻止 write_file、replace、run_shell_command 等会修改内容的工具
• 可通过 GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0 禁用严格强制（不推荐）

身份验证和运行状况检查

运行 health_check 并设置 includeDiagnostics: true，即可查看身份验证状态和服务运行状况。

health_check.status 的取值：

• ok：Gemini CLI 可用、身份验证正常，且安全策略已启用
• degraded：设置不完整、身份验证状态不明确，或安全策略已禁用

前提条件

• 已安装 Node.js 18+
• 已安装 Gemini CLI：npm install -g @google/gemini-cli
• Gemini CLI 已通过身份验证（推荐：运行 gemini → 使用 Google 登录），或设置 GEMINI_API_KEY

快速检查：

node --version
gemini --version

快速开始

步骤 1：验证环境

运行设置向导，确认 Gemini CLI 已安装并通过身份验证：

npx gemini-researcher init

步骤 2：配置 MCP 客户端

标准配置适用于大多数工具：

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

说明

在原生 Windows 上，某些 MCP 主机使用不带 shell 的进程启动方式，可能无法可靠地解析 npm 命令 shim（npx、gemini）。 如果启动时出现错误（spawn ... ENOENT / GEMINI_CLI_LAUNCH_FAILED，但在 PowerShell 中运行正常），建议使用 Docker 或 WSL，以确保立即可靠运行。 请参阅 docs/platforms/windows.md 中的完整解决方案。

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

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

# Verify it was added
claude mcp list

# 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

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

{
  "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：测试

向 Agent 提问：“使用 gemini-researcher 分析该项目。”

工具

所有工具都返回结构化 JSON（作为 MCP 文本内容）。大型响应会分块（每块约 10KB），并缓存 1 小时。

查询工具的回退链会根据模型系列选择：

• quick_query：flash -> flash_lite -> auto
• deep_research：pro -> flash -> flash_lite -> auto
• analyze_directory：flash -> flash_lite -> auto

使用 API 密钥身份验证时，回退机制也会处理模型不可用/不受支持错误（而不只是配额/容量错误）。

示例工作流

了解安全漏洞：

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

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

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

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

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

{
  "includeDiagnostics": true
}

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

Docker

可在 Docker Hub 获取预构建的多平台 Docker 镜像：

# 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

使用 Docker 配置 MCP 客户端：

{
  "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"
      }
    }
  }
}

说明

• stdio 传输需要 -i 标志
• 容器会将你的项目挂载到 /workspace（项目根目录）
• 将 /path/to/your/project 替换为实际项目路径
• 将 your-api-key 替换为实际的 Gemini API 密钥（使用 Docker 时必需）

平台指南

• Windows 原生启动模式与修复方法：docs/platforms/windows.md

故障排除（常见问题）

• 修复决策树：

• GEMINI_CLI_NOT_FOUND：安装 Gemini CLI：npm install -g @google/gemini-cli
• GEMINI_CLI_LAUNCH_FAILED：这是启动路径问题，而非身份验证 / 功能问题。在 Windows 上，命令 shim 在无 shell 的启动上下文中可能会失败。以交互方式验证 gemini --help 和 npx --version，然后在宿主启动模式严格时优先使用 Docker 或 WSL。
• GEMINI_RESEARCHER_GEMINI_COMMAND：覆盖服务使用的 Gemini 命令名称 / 路径（用于包装器或固定的二进制文件位置）。
• GEMINI_RESEARCHER_GEMINI_ARGS_PREFIX：为每次调用添加 Gemini 参数前缀（例如 --config <file>）。
• health_check 诊断信息会对已配置参数前缀输出中的敏感令牌类值进行脱敏。
• AUTH_MISSING：运行 gemini，然后进行身份验证或设置 GEMINI_API_KEY
• AUTH_UNKNOWN：无法确认身份验证状态（通常是网络 / CLI 探测失败）。如果存在启动错误，请先修复启动路径；否则，请验证 gemini 能否以交互方式正常运行，然后重试。
• ADMIN_POLICY_MISSING：重新安装软件包，或确认已安装的软件包中存在 policies/read-only-enforcement.toml。
• ADMIN_POLICY_UNSUPPORTED：将 Gemini CLI 升级至 v0.36.0+（gemini --help 应包含 --admin-policy）。
• 只有在成功探测 gemini --help 后，才应解读功能错误（ADMIN_POLICY_UNSUPPORTED、不支持输出格式）。如果探测启动失败，应先将其视为启动路径故障。
• GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0：禁用严格启动策略检查。这会降低安全保障。
• .gitignore 阻止访问文件：Gemini 默认遵循 .gitignore；如果你确实希望包含被忽略的文件，请在 gemini /settings 中切换 fileFiltering.respectGitIgnore（注意：这会全局改变 Gemini 的行为）
• PATH_NOT_ALLOWED：所有 @path 引用都必须解析到已配置的项目根目录内（默认是 process.cwd()）。使用 validate_paths 预先检查路径。
• QUOTA_EXCEEDED：服务会重试备用模型；如果所有选项都已用尽，请缩小范围（使用 quick_query）或等待配额重置。

参与贡献

阅读贡献指南以开始参与。

快速链接：

• 开发环境设置
• 运行测试
• 代码规范
• 提交更改

许可证

BSD-3-Clause 许可证

为 AI 辅助开发社区倾心打造 ♡