Deep-research

Deep Research MCP サーバー

AI を活用したリサーチアシスタントです。 Google Search Grounding と URL コンテキストを利用し、Google Gemini 2.5 Flash で反復的な深掘りリサーチを行います。Web スクレイピングへの依存は不要です。

---

目次

• 特長
• このプロジェクトについて
• ワークフロー図
• ペルソナエージェント
• 仕組み
• プロジェクト構成
• 要件
• セットアップ
• 使い方
  • MCP ツールとして
  • スタンドアロン CLI の使い方
  • MCP Inspector でのテスト
• 設定
• クイックスタート
• 出力例
• サポート
• コントリビューション
• ロードマップ
• ライセンス

このプロジェクトの目標は、深掘りリサーチエージェントの実装として、最もシンプルでありながら 最も効果的なものを提供することです。コードベースを 500 行未満（LoC）に抑えることを目指し、理解、変更、拡張が容易になるように設計されています。

主な特長：

• MCP 統合： エージェントとシームレスに連携できるよう、Model Context Protocol（MCP）サーバー／ツールとして動作します。
• Gemini 2.5 Flash パイプライン： 長いコンテキストでの推論、構造化 JSON 出力、環境変数フラグによるツール利用（Google Search Grounding、Code Execution、Functions）に対応します。
• 反復的な深掘り： クエリを改善し、結果を分析しながら、得られたコンテキストを次の処理へ引き継ぎます。
• 深さと広さの制御： 調査範囲を細かく調整できます。
• セマンティック／再帰的分割： トークンを考慮したチャンク分割により、堅牢な要約と分析を実現します。
• バッチ処理とキャッシュ： 同時実行数を制限したモデル呼び出しをバッチ処理し、プロンプトと結果を対象とした LRU キャッシュを備えています。
• プロフェッショナルなレポート： 構造化された Markdown（概要、目次、序論、本文、方法論、制限事項、重要な知見、参考文献）を生成します。

このプロジェクトについて

• Gemini を中心とした最新のパイプライン： Gemini 2.5 Flash を基盤とし、オプションのツール（Search Grounding、Code Execution、Functions）を利用できます。
• 最小限で理解しやすいコア： 純粋な TypeScript で実装されており、監査や拡張が容易です。
• 決定論的な出力： Zod で検証された JSON と、一貫性のあるレポートのひな形を提供します。
• エージェント対応： MCP サーバーのエントリがシンプルで、Inspector や MCP 対応クライアントで動作します。

ワークフロー図

flowchart TB
    subgraph Input
        Q[User Query]
        B[Breadth Parameter]
        D[Depth Parameter]
    end

    DR[Deep Research] -->
    SQ[SERP Queries] -->
    PR[Process Results]

    subgraph Results[Results]
        direction TB
        NL((Learnings))
        ND((Directions))
    end

    PR --> NL
    PR --> ND

    DP{depth > 0?}

    RD["Next Direction:
    - Prior Goals
    - New Questions
    - Learnings"]

    MR[Markdown Report]

    %% Main Flow
    Q & B & D --> DR

    %% Results to Decision
    NL & ND --> DP

    %% Circular Flow
    DP -->|Yes| RD
    RD -->|New Context| DR

    %% Final Output
    DP -->|No| MR

    %% Styling
    classDef input fill:#7bed9f,stroke:#2ed573,color:black
    classDef process fill:#70a1ff,stroke:#1e90ff,color:black
    classDef recursive fill:#ffa502,stroke:#ff7f50,color:black
    classDef output fill:#ff4757,stroke:#ff6b81,color:black
    classDef results fill:#a8e6cf,stroke:#3b7a57,color:black

    class Q,B,D input
    class DR,SQ,PR process
    class DP,RD recursive
    class MR output
    class NL,ND results

ペルソナエージェント

ペルソナエージェントとは？

deep-research では、Gemini 言語モデルの動作を導くために、「ペルソナエージェント」という概念を活用しています。LLM に単にタスクを与えるのではなく、特定の役割、スキル、個性、コミュニケーションスタイル、価値観を付与します。このアプローチには、次のような効果があります。

• LLM の出力に焦点を絞る： 明確なペルソナを定義することで、求められる専門知識や視点に沿った応答を LLM が生成しやすくなります。
• 一貫性を高める： ペルソナにより、リサーチの全過程を通じて一貫した口調とスタイルを保てます。
• タスク固有のパフォーマンスを向上させる： 特定のタスク（例：クエリ生成、学習内容の抽出、フィードバック）に合わせてペルソナを調整することで、リサーチの各段階に最適化された出力を LLM から得られます。

使用されているペルソナの例：

• 研究戦略の専門家兼クエリ生成担当： 検索クエリの生成に使用されるこのペルソナは、戦略的思考、幅広い網羅性、正確なクエリの作成を重視します。
• 研究アシスタント兼洞察抽出の専門家： ウェブページのコンテンツを処理する際に、このペルソナは綿密な分析、事実の正確性、研究クエリに関連する重要な学びの抽出に重点を置きます。
• 研究クエリの改善と戦略的助言の専門家： フォローアップの質問を生成する際に、このペルソナは戦略的思考、ユーザーの意図の理解、より明確で効果的な研究質問へユーザーを導く能力を備えています。
• 博士号レベルのプロ研究者（システムプロンプト）： メインのシステムプロンプトに適用されるこの包括的なペルソナは、専門家レベルの分析、論理的な構成、詳細な調査を重視し、研究プロセス全体のトーンを設定します。

ペルソナエージェントを活用することで、deep-research は Gemini 言語モデルから、より的を絞った一貫性のある高品質な研究成果を得ることを目指しています。

仕組み

コアモジュール：

• src/deep-research.ts — クエリ、バッチ処理、分析、統合をオーケストレーションします
  • generateSerpQueries() は Gemini を使い、プロンプトとこれまでの学びから SERP 形式のクエリを提案します
  • processSerpResult() はコンテンツを分割し、ツールを有効にした状態で Gemini の呼び出しをバッチ処理して、学びと引用を抽出します
  • conductResearch() はセマンティックチャンクに対して分析処理を実行します
  • writeFinalReport() はプロフェッショナルな Markdown 形式の最終レポートを作成します
• src/ai/providers.ts — Gemini 2.5 Flash 用の GoogleGenAI ラッパーで、バッチ処理、トークン制御、オプションのツールに対応します
• src/ai/text-splitter.ts — RecursiveCharacter および Semantic の分割処理
• src/mcp-server.ts — MCP サーバーのエントリーポイントと型
• src/run.ts — CLI のエントリーポイント

パイプラインの主な特徴：

• Zod で検証される構造化 JSON 出力
• 同時実行数を制限したバッチ処理（generateBatch、generateBatchWithTools）
• プロンプト、SERP の提案、レポート用の LRU キャッシュ
• フラグによる Gemini ツールの任意利用：Google Search Grounding、Code Execution、Functions

プロジェクト構成

deep-research-mcp-server/
├─ src/
│  ├─ ai/
│  │  ├─ providers.ts           # Gemini wrapper, tools, batching, caching
│  │  └─ text-splitter.ts       # Semantic/recursive splitters
│  ├─ mcp-server.ts             # MCP server entry/types
│  ├─ deep-research.ts          # Orchestrator: queries → analysis → synthesis
│  ├─ prompt.ts                 # System + templates
│  ├─ feedback.ts               # Refinement/feedback loop
│  ├─ output-manager.ts         # Report/output formatting
│  ├─ progress-manager.ts       # CLI progress
│  ├─ terminal-utils.ts         # CLI helpers
│  ├─ types.ts                  # Zod schemas/types
│  └─ utils/                    # JSON/sanitize helpers
├─ dist/                        # Build output
├─ .env.example                 # Environment template
├─ package.json                 # Scripts/deps
└─ README.md

要件

• Node.js v22.x
• Google Gemini API キー

セットアップ

Node.js

1. リポジトリをクローンします：

   git clone [your-repo-link-here]
   

2. 依存関係をインストールします：

   npm install
   

3. 環境変数を設定します： プロジェクトのルートに .env.local ファイルを作成します。

   # Required
   GEMINI_API_KEY="your_gemini_key"
   
   # Recommended defaults
   GEMINI_MODEL=gemini-2.5-flash
   GEMINI_MAX_OUTPUT_TOKENS=65536
   CONCURRENCY_LIMIT=5
   
   # Gemini tools (enable as needed)
   ENABLE_GEMINI_GOOGLE_SEARCH=true
   ENABLE_GEMINI_CODE_EXECUTION=false
   ENABLE_GEMINI_FUNCTIONS=false
   

4. プロジェクトをビルドします：

   npm run build
   

使い方

MCP ツールとして

deep-research を MCP ツールとして実行するには、MCP サーバーを起動します。

node --env-file .env.local dist/mcp-server.js

次のパラメーターを使用して、MCP 互換の任意のエージェントから deep-research ツールを呼び出せます。

• query（文字列、必須）：調査クエリです。
• depth（数値、任意、1～5）：調査の深さです（デフォルト：中程度）。
• breadth（数値、任意、1～5）：調査の幅です（デフォルト：中程度）。
• existingLearnings（文字列配列、任意）：調査の指針となる、既存の調査結果です。

MCP ツール引数の例（JSON 形式）：

{
  "name": "deep-research",
  "arguments": {
    "query": "State of multi-agent research agents in 2025",
    "depth": 3,
    "breadth": 3,
    "existingLearnings": [
      "Tool use improves grounding",
      "Batching reduces latency"
    ]
  }
}

const mcp = new ModelContextProtocolClient(); // Assuming MCP client is initialized

async function invokeDeepResearchTool() {
  try {
    const result = await mcp.invoke("deep-research", {
      query: "Explain the principles of blockchain technology",
      depth: 2,
      breadth: 4
    });

    if (result.isError) {
      console.error("MCP Tool Error:", result.content[0].text);
    } else {
      console.log("Research Report:\n", result.content[0].text);
      console.log("Sources:\n", result.metadata.sources);
    }
  } catch (error) {
    console.error("MCP Invoke Error:", error);
  }
}

invokeDeepResearchTool();

スタンドアロン CLI の使用方法

コマンドラインから deep-research を直接実行するには：

npm run start "your research query"

例：

npm run start "what are latest developments in ai research agents"

MCP Inspector でのテスト

MCP サーバーを対話形式でテストおよびデバッグするには、MCP Inspector を使用します。

npx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js

MCP 統合のヒント

• 環境変数：MCP サーバープロセスに GEMINI_API_KEY を渡してください。モデルとツールのフラグは環境変数で指定します。
• ステートレスな呼び出し：サーバーは環境変数から動作を決定します。フラグはクライアントのプロファイルと同期させてください。
• レイテンシ：速度とレート制限のバランスを取るため、バッチ処理と適切な CONCURRENCY_LIMIT を有効にしてください。

設定

• GEMINI_API_KEY — 必須
• GEMINI_MODEL — デフォルトは gemini-2.5-flash
• GEMINI_MAX_OUTPUT_TOKENS — デフォルトは 65536
• CONCURRENCY_LIMIT — デフォルトは 5
• ENABLE_GEMINI_GOOGLE_SEARCH — Google Search Grounding ツールを有効化
• ENABLE_GEMINI_CODE_EXECUTION — コード実行ツールを有効化
• ENABLE_GEMINI_FUNCTIONS — 関数呼び出しを有効化

オプションのプロバイダー（今後対応予定／フラグで制御）：Exa／Tavily は後から統合できます。現在のパイプラインでは Firecrawl は不要です。

クイックスタート

1. クローンしてインストール

git clone https://github.com/ssdeanx/deep-research-mcp-server
cd deep-research-mcp-server
npm i && npm run build

2. .env.local を作成します（セットアップを参照）

3. MCP サーバーとして実行します（Inspector）

npx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js

4. または CLI として実行します

npm run start "state of multi-agent research agents in 2025"

出力例

# Abstract
Concise overview of the research goal, scope, method, and key findings.

# Table of Contents
...

# Introduction
Context and framing.

# Body
Evidence-backed sections with citations.

# Methodology
How sources were found and analyzed.

# Limitations
Assumptions and risks.

# Key Learnings
Bulleted insights and takeaways.

# References
Normalized citations to visited URLs.

サポート

• Issue： バグや機能リクエストには GitHub Issues をご利用ください。
• ディスカッション： アイデアの提案や質問にご利用ください。
• セキュリティ： 機密情報の開示について公開 Issue を作成しないでください。メンテナーに非公開でご連絡ください。

コントリビューション

• PR を歓迎します： 大幅な変更の場合は、まず Issue を作成してください。
• 標準： TypeScript 5.x、Node.js 22.x を使用し、PR の前に lint と型チェックを実行してください。
• チェック： npm run build と tsc --noEmit が成功する必要があります。
• ドキュメント： 環境変数や設定を変更した場合は、README.md と .env.example を更新してください。

ロードマップ

• Exa 検索の統合（ENABLE_EXA_PRIMARY で制御）、拡張用の Google grounding。
• プロバイダーの整理： Exa への移行後に Firecrawl を削除します（明示的な承認が必要です）。
• CI/CD： ビルド／lint／テスト用の GitHub Actions とバッジを追加します。
• サンプル： レポートとプロンプトのサンプルを追加します。

トラブルシューティング

• API キーが見つからない： .env.local に GEMINI_API_KEY が設定されていること、および --env-file .env.local を指定してプロセスを起動していることを確認してください。
• モデル／ツールのフラグ： grounding や関数が有効にならない場合は、ENABLE_GEMINI_GOOGLE_SEARCH、ENABLE_GEMINI_CODE_EXECUTION、ENABLE_GEMINI_FUNCTIONS を確認してください。
• レート制限／レイテンシ： CONCURRENCY_LIMIT を下げる（例：3）か、同時に実行するクエリ数を減らして再実行してください。
• 出力が長すぎる： 深さ／幅を下げるか、GEMINI_MAX_OUTPUT_TOKENS を小さくしてください。
• スキーマ解析エラー： 再実行してください。パイプラインでは JSON を検証して修正しますが、極端に長いプロンプトは上限を超える場合があります。プロンプトを短くするか、チャンクサイズを小さくしてください。

ライセンス

MIT License — 無料で利用できるオープンソースです。自由にお使いください！

---

🚀 調査を深く掘り下げましょう！🚀

最近の改善点（v0.3.0）

✨ 最新の変更点の概要です。ロードマップもご覧ください。

🧪 調査の検証機能を強化

• ✅ 入力検証：最低10文字＋3単語
• 📈 出力検証：引用密度（100語あたり1.5件以上）
• 🔍 最近の情報源を確認（2019年以降の参考文献を3件以上）
• ⚖️ 利益相反の開示を徹底

🧠 Gemini 連携のアップグレード

• Gemini 2.5 Flash に統一（長いコンテキスト、構造化 JSON）
• 環境変数フラグでオプションのツールを利用可能：検索グラウンディング、コード実行、関数
• コンテキスト管理にセマンティック分割と再帰的分割を採用
• 同時実行制御とキャッシュを備えた堅牢なバッチ処理
• セマンティック検索によるコンテキスト管理の強化
• エラー処理とロギングの改善

🧹 コード品質の改善

• 🚀 並行処理パイプラインを追加
• 冗長な academic-validators モジュールを削除
• 🛡️ インターフェース全体で型安全性を強化
• 📦 依存関係を最適化（node_modules を約30％削減）

🆕 新機能

• 📊 調査メトリクスの追跡（情報源／学習内容の比率）

* 📑 利益相反の開示文を自動生成 * 🔄 調査の深度を再帰的に制御（1～5段階） * 📈 調査メトリクスの追跡（情報源／学習内容の比率） * 🤖 MCP ツール連携の改善

パフォーマンス：

• 🚀 調査サイクルを30％高速化
• ⚡ 初回の調査サイクルを40％高速化
• 📉 API エラーを60％削減
• 🧮 トークン使用効率を25％向上