MCP Multi Agent Deep Researcher

🚀 🤖 MCP マルチエージェントディープリサーチャー

このシステムは、モデルコンテキストプロトコル (MCP) をベースに構築された強力なマルチエージェント研究システムです。CrewAI を使ったエージェントオーケストレーション、LinkUp を用いた深層ウェブ検索、そして phi3 モデル（Ollama 経由）を使ったローカル AI 処理を備えています。API アクセスと美しいウェブインターフェイスの両方を提供し、簡単に研究タスクを実行できます。

🚀 クイックスタート

3つの簡単なステップで始めましょう:

# 1. リポジトリをクローンする
git clone https://github.com/anubhav-77-dev/MCP-Multi-Agent-Deep-Researcher.git
cd MCP-Multi-Agent-Deep-Researcher

# 2. セットアップスクリプトを実行する
python3 setup.py

# 3. すべてを起動する！
python3 launcher.py

以上です！システムは自動的にブラウザで http://localhost:3000/frontend.html を開きます。

✨ 主な機能

• 🧠 マルチエージェントシステム: 3つの専門的なAIエージェントが連携して動作します。
  • Web Searcher: LinkUp API を使った深層ウェブ検索
  • Research Analyst: 情報の合成と検証
  • Technical Writer: 明確で構造化されたコンテンツの作成
• 🌐 美しいウェブインターフェイス: 現代的でレスポンシブなフロントエンドで、簡単にやり取りできます。
• 🔌 APIアクセス: FastAPI を使った RESTful API と自動ドキュメントが用意されています。
• 🏠 ローカルAI処理: Ollama と phi3 モデルを使っており、外部のAI API は必要ありません。
• 📡 MCPプロトコル: 完全なモデルコンテキストプロトコルに準拠しており、統合が容易です。
• 🚀 1コマンドでの起動: 単一のコマンドですべてを起動できます。

📦 インストール

オプション1: 自動セットアップ（推奨）

# リポジトリをクローンする
git clone https://github.com/anubhav-77-dev/MCP-Multi-Agent-Deep-Researcher.git
cd MCP-Multi-Agent-Deep-Researcher

# 自動セットアップを実行する（依存関係のチェック、パッケージのインストール、環境の設定）
python3 setup.py

# アプリケーションを起動する（フロントエンドとバックエンドの両方を起動）
python3 launcher.py

オプション2: 手動セットアップ

# Poetry をインストールする（まだインストールされていない場合）
curl -sSL https://install.python-poetry.org | python3 -

# プロジェクトの依存関係をインストールする
poetry install

# Ollama をインストールする（OS固有の手順は https://ollama.ai/ を参照）
# macOS の場合:
brew install ollama

# Ollama サービスを起動する
ollama serve

# phi3 モデルを取得する（新しいターミナルで）
ollama pull phi3:latest

# インストールを確認する
ollama list

# 環境テンプレートをコピーする
cp .env.example .env

# .env ファイルを編集し、LinkUp API キーを追加する
nano .env

LINKUP_API_KEY=your_linkup_api_key_here
OLLAMA_BASE_URL=http://localhost:11434
MODEL_NAME=phi3:latest

# オプションA: ランチャーを使用する（推奨）
python3 launcher.py

# オプションB: サービスを手動で起動する
# ターミナル1 - バックエンドAPI
poetry run python Multi-Agent-deep-researcher-mcp-windows-linux/http_server.py

# ターミナル2 - フロントエンド
python3 -m http.server 3000

# ターミナル3 - MCPサーバー（オプション、MCPクライアントの統合用）
poetry run python Multi-Agent-deep-researcher-mcp-windows-linux/server.py

🔑 LinkUp API キーの取得

1. LinkUp.so にアクセスする
2. 無料アカウントを登録する
3. ダッシュボードからAPIキーを取得する
4. .env ファイルに追加する

💻 使用例

ウェブインターフェイス（最も簡単）

1. アプリケーションを起動する: python3 launcher.py
2. ブラウザを開く: http://localhost:3000/frontend.html（自動的に開きます）
3. 研究クエリを入力する または サンプルクエリを試す
4. モードを選択する:
   • 🔍 クイック検索: LinkUp API を使った高速なウェブ検索
   • 🧠 完全な研究: 完全なマルチエージェント分析ワークフロー
5. 結果を表示する: 整形された出力、コピー/ダウンロードオプション付き

APIアクセス

クイック検索

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query": "latest AI trends 2024"}'

完全な研究

curl -X POST http://localhost:8080/research \
  -H "Content-Type: application/json" \
  -d '{"query": "comprehensive analysis of quantum computing applications"}'

ヘルスチェック

curl http://localhost:8080/health

MCPクライアントの統合

MCP互換クライアントとの統合には、以下の設定を追加します。

{
  "mcpServers": {
    "crew_research": {
      "command": "poetry",
      "args": ["run", "python", "Multi-Agent-deep-researcher-mcp-windows-linux/server.py"],
      "env": {
        "LINKUP_API_KEY": "your_linkup_api_key_here"
      }
    }
  }
}

利用可能なエンドポイント

📚 ドキュメント

プロジェクト構造

MCP-Multi-Agent-Deep-Researcher/
├── 🚀 launcher.py                    # 1コマンドでの起動スクリプト
├── 🌐 frontend.html                  # ウェブインターフェイス
├── ⚙️ setup.py                       # 自動セットアップスクリプト
├── 📋 start.sh                       # シェル起動スクリプト
├── 📖 QUICKSTART.md                  # クイックスタートガイド
├── 🔧 Makefile                       # 開発用コマンド
├── 📦 pyproject.toml                 # Poetry 依存関係
├── 🔐 .env.example                   # 環境テンプレート
├── ⚙️ mcp.config.json                # MCPクライアント設定
└── Multi-Agent-deep-researcher-mcp-windows-linux/
    ├── 🖥️ server.py                  # MCPプロトコルサーバー
    ├── 🌐 http_server.py             # FastAPI RESTサーバー
    ├── 🧪 test_research.py           # テストユーティリティ
    └── agents/                       # マルチエージェントシステム
        ├── 🤖 research_crew.py       # CrewAIオーケストレーション
        └── tools/                    # エージェントツール
            ├── 🔍 linkup_search.py   # ウェブ検索統合
            └── 🧠 ollama_tool.py     # ローカルAI統合

サンプルクエリ

これらのサンプル研究クエリを試してみてください。

クイック検索の例

• "What are the latest AI trends in 2024?"
• "Current developments in renewable energy"
• "Recent breakthroughs in quantum computing"

完全な研究の例

• "Comprehensive analysis of the environmental impact of cryptocurrency mining"
• "How does quantum computing work and what are its real-world applications?"
• "The future of autonomous vehicles: technology, challenges, and timeline"
• "Impact of artificial intelligence on healthcare: opportunities and risks"

エージェントワークフロー

システムは CrewAI を使って3つの専門的なエージェントをオーケストレートします。

1. Web Searcherエージェント

• 役割: ウェブリサーチスペシャリスト
• 目標: LinkUp API を使って包括的で関連性の高い情報を見つける
• ツール: LinkUp Search Tool
• 出力: ウェブ検索結果の詳細な要約とソース

2. Research Analystエージェント

• 役割: リサーチアナリスト
• 目標: 情報を分析して合成し、包括的な洞察を提供する
• 入力: ウェブ検索結果
• 出力: 主要な洞察と検証された情報を含む構造化された分析

3. Technical Writerエージェント

• 役割: テクニカルライター
• 目標: 明確で包括的で構造化された書面コンテンツを作成する
• 入力: リサーチ分析
• 出力: 包括的で整形されたマークダウンドキュメント

設定

環境変数

• LINKUP_API_KEY: ウェブ検索機能に使用する LinkUp API キー
• OLLAMA_BASE_URL: Ollama API のベースURL（デフォルト: http://localhost:11434）
• MODEL_NAME: 使用する Ollama モデル（デフォルト: phi3）

エージェントのカスタマイズ

agents/research_crew.py を変更することでエージェントをカスタマイズできます。

• エージェントの役割、目標、バックストーリーを調整する
• タスクの説明と期待される出力を変更する
• 特定のエージェントにツールを追加または削除する
• プロセスフロー（シーケンシャル、階層的など）を変更する

🔧 技術詳細

アーキテクチャ

システムは3つのエージェントワークフローを実装しています。

1. Web Searcher: LinkUp API を使って複数のソースから関連する情報を見つける
2. Research Analyst: 情報を合成して検証し、深さと明確さに重点を置く
3. Technical Writer: 明確で包括的なマークダウンの回答を生成する

graph TD
    A[Web Interface] --> B[FastAPI Backend]
    B --> C[MCP Server]
    C --> D[CrewAI Orchestrator]
    D --> E[Web Searcher Agent]
    D --> F[Research Analyst Agent] 
    D --> G[Technical Writer Agent]
    E --> H[LinkUp API]
    F --> I[Ollama + phi3]
    G --> I
    H --> J[Web Search Results]
    I --> K[AI Analysis & Writing]
    J --> F
    K --> L[Final Research Output]

開発

クイックコマンド

# すべてを起動する
make start          # または make launch, make demo

# 開発セットアップ
make dev-setup      # 依存関係のインストール + セットアップ + 検証

# テストを実行する
make test           # 基本機能テスト
make quick-test     # クイック検索テスト

# メンテナンス
make clean          # キャッシュファイルをクリーンアップする
make verify         # インストールを検証する

カスタムエージェントの追加

1. agents/research_crew.py で新しいエージェントを作成する:

custom_agent = Agent(
    role='Custom Specialist',
    goal='Your specific goal',
    backstory='Agent background',
    tools=[your_tools]
)

2. クルーワークフローに追加する:

custom_task = Task(
    description="Task description",
    agent=custom_agent,
    expected_output="Expected result format"
)

新しいツールの追加

1. agents/tools/ でツールファイルを作成する:

class CustomTool(BaseTool):
    name = "Custom Tool"
    description = "Tool description"
    
    def _run(self, query: str) -> str:
        # ツールの実装
        return result

2. research_crew.py でエージェントに登録する

環境設定

🐛 トラブルシューティング

一般的な問題と解決策

# 既存のプロセスを終了する
pkill -f "python.*http_server"
pkill -f "http.server"

# または 異なるポートで再起動する
python3 launcher.py

# Ollama が実行中か確認する
ollama serve

# モデルが利用可能か確認する
ollama list

# モデルが欠落している場合は取得する
ollama pull phi3:latest

# Ollama にアクセスできるか確認する
curl http://localhost:11434/api/tags

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"q": "test"}' \
     https://api.linkup.so/v1/search

# 依存関係を再インストールする
poetry install --no-cache

# または pip を使ってフォールバックする
pip install -r requirements.txt

# Python バージョンを確認する
python3 --version  # 3.10+ である必要があります

ヘルプの取得

1. ログを確認する: ランチャーは両方のサーバーの詳細なログを表示します
2. 診断を実行する: python3 setup.py でセットアップを検証する
3. コンポーネントをテストする: python3 simple_test.py で個別のテストを実行する
4. デバッグモードを有効にする: サーバーファイルで logging.basicConfig(level=logging.DEBUG) を設定する

📊 パフォーマンスとスケーリング

• クイック検索: ~2 - 5秒（LinkUp API に依存）
• 完全な研究: ~30 - 60秒（クエリの複雑さに依存）
• 同時ユーザー: 複数の同時リクエストをサポート
• メモリ使用量: ~500MB - 1GB（Ollama モデルに依存）
• ディスク容量: ~3GB（phi3 モデルを含む）

🔒 セキュリティとプライバシー

• ✅ ローカルAI処理: データは外部のAIサービスに送信されません
• ✅ APIキーのセキュリティ: LinkUp API キーはローカルのみに保存されます
• ✅ データの永続化なし: 研究クエリはデフォルトで保存されません
• ✅ CORS保護: 構成可能なオリジン制限
• ⚠️ ウェブ検索: クエリは LinkUp API に送信されます（彼らのプライバシーポリシーを参照）

📄 ライセンス

このプロジェクトは MITライセンス の下でライセンスされています - LICENSE ファイルを参照してください。

🙏 謝辞

素晴らしいオープンソース技術を使って構築されています。

• 🤖 CrewAI - マルチエージェントオーケストレーションフレームワーク
• 🔍 LinkUp - 深層ウェブ検索API
• 🧠 Ollama - ローカルLLMサービングプラットフォーム
• ⚡ FastAPI - 現代的なPythonウェブフレームワーク
• 🎭 Model Context Protocol - AI統合標準
• 📦 Poetry - Python 依存関係管理

⭐ スター履歴