Gemini Researcher

🚀 Gemini Researcher

Gemini Researcherは、開発者エージェント（Claude Code、GitHub Copilotなど）がGemini CLIに深いリポジトリ分析を委託できるようにする、軽量でステートレスなMCP（Model Context Protocol）サーバーです。このサーバーは読み取り専用で、構造化されたJSON（テキストコンテンツとして）を返し、呼び出しエージェントのコンテキストとモデルの使用を削減するように最適化されています。

ステータス: v1完了。コア機能は安定していますが、まだ初期段階です。フィードバックを歓迎します！

このプロジェクトがあなたの使用期間を延長した場合 ⭐ スターをつけていただけると幸いです！ :)

主な目標:

• Gemini CLIに大規模なコードベースをローカルで読み取らせ、独自の調査を行うことで、エージェントのコンテキスト使用を削減する
• 重い分析をGeminiにオフロードすることで、呼び出しエージェントのモデル使用を削減する
• サーバーをステートレスかつ読み取り専用に保ち、安全性を確保する

なぜこれを使うのか？

エージェントのコンテキストにファイル全体をコピーする代わりに（トークンを消費し、会話を混乱させる）、このサーバーはGemini CLIにプロジェクトから直接ファイルを読み取らせます。エージェントが調査クエリを送信すると、Geminiが大きなコンテキストウィンドウで重い作業を行い、構造化された結果を返します。トークンを節約し、エージェントを集中させ、複雑なコードベース分析を実用的にすることができます。

検証済みのクライアント: Claude Code、Cursor、VS Code (GitHub Copilot)

⚠️ 重要な注意

他のクライアントでも動作することは確かですが、まだ個人でテストしていません。他の場所で試した場合は、issueを開いてください！

🚀 クイックスタート

前提条件

• 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"
      ]
    }
  }
}

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

# 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

{
  "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: テストする

エージェントに「gemini-researcherを使ってプロジェクトを分析して」と尋ねます。

✨ 主な機能

すべてのツールは構造化されたJSON（MCPテキストコンテンツとして）を返します。大きなレスポンスは自動的にチャンク化され（約10KBごと）、1時間キャッシュされます。

例のワークフロー

セキュリティ脆弱性の理解:

エージェント: deep_researchを使って、@src/authと@src/middlewareの認証フローを分析し、セキュリティに焦点を当てる

コードの簡単な説明:

エージェント: quick_queryを使って、@src/auth.tsのログインフローを簡潔に説明する

不慣れなコードベースのマッピング:

エージェント: analyze_directoryをsrc/に適用し、深さ3でプロジェクト構造を理解する

{
  "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 で利用可能です。

# イメージを取得する（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

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

⚠️ 重要な注意

• -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を使用）か、クォータのリセットを待ちます。

🤝 コントリビュート

コントリビューションを歓迎します！ 始めるには Contributing Guide を読んでください。

クイックリンク:

• 開発セットアップ
• テストの実行
• コードガイドライン
• 変更の提出

📄 ライセンス

BSD-3-Clause License

AI支援開発コミュニティのために愛を込めて作られました