🔍 Percival Deep Research (MCPサーバー)

概要

Percival Deep Researchは、Nanobotエージェントエコシステムに自律的なディープダイブWebリサーチ機能を装備するために設計された、高性能なMCP（Model Context Protocol）サーバーです。信頼性が高く最新の情報のみに焦点を当て、多数のソースを自律的に探索・検証します。

標準的な検索ツールは手動でのフィルタリングが必要な生の断片を返しますが、Percival Deep Researchは、インテリジェントエージェントのコンテキストと推論能力を大幅に加速させる、完全に論理立てられた包括的なマルチソース資料を提供します。

注: 本プロジェクトはGPT ResearcherライブラリをコアWebドライバーとして利用していますが、percival.OSエコシステム専用に大幅なリファクタリング、堅牢化、および分離が行われています。

Related MCP server: ToolCenter MCP

✨ 主な機能と強化点

このサーバーは、オープンソースLLMや最新のデプロイメント環境の厳しい要求に耐えられるよう、大幅に修正されています：

• ⚡ 究極のプロバイダー移植性: 推論エンジンに完全に依存しません。Venice AI、MiniMax、OpenRouterなどの主要なオープンウェイトプラットフォームをネイティブかつクラッシュフリーでサポートします。サーバーはプロバイダーのプレフィックスをオンザフライで動的に書き換え、エイリアスのタイプミスを自動修正し、OpenAI互換の埋め込みエンドポイントを持たないAPIを使用する際のクラッシュやセマンティックレイテンシを完全に排除するために「ゼロレイテンシ・コンテキスト圧縮バイパス」を実装しています。

• 🛡️ JSON-RPCプロトコル・ガードレール: 厳格なstdio出力の秘匿化を強制します。基盤となるライブラリのノイズ、コンソールレンダリング、リアルタイムログは物理的にstderrにリダイレクトされます。これにより、Pydantic ValidationErrorsを完全に防ぎ、MCP同期に不可欠なstdoutストリームを保護します。

• 🔐 多層防御セキュリティ: すべての入力はプロンプトインジェクションに対して厳重にサニタイズされます。信頼できないWebコンテンツは、エージェントの自律性を保護するために実行不可能なヘッダーでラップされます。

• 🤖 Nanobotへの最適化: 緩い.env読み込みパターンを排除し、ホストアプリケーションから直接環境変数を注入する方式を厳格に守ります。

📑 目次

• ツールとリソースの参照

• 前提条件

• インストール

• 🤖 Nanobot統合 (主要な焦点)

• 💻 Claude Desktop統合

• セキュリティ

🛠️ ツールとリソースの参照

リソース

ツール

リサーチパイプライン

deep_research(query)
    └── research_id ──► write_report(research_id, custom_prompt?)
                   └──► get_research_sources(research_id)
                   └──► get_research_context(research_id)

quick_search(query)       # standalone — no research_id

⚙️ 前提条件

• Python 3.11+

• uv — プロジェクトおよび依存関係マネージャー

• 生成AIプロバイダーのAPIキー (例: Venice, MiniMax, OpenRouter)。

*注: デフォルトで設定されているWeb検索エンジンはduckduckgoであり、APIキーは不要です。必要に応じて他のWeb検索エンジンをネイティブに設定することも可能です。*

⚙️ インストール

1. 統合環境のセットアップ

統合されたpercival.OSビルドエコシステムを使用していることを確認してください：

cd percival.OS_Dev
uv sync

これにより、percival-deep-researchがグローバルな.venvを継承することが保証されます。

2. 環境設定

このモジュールは、MCPホストによって渡されるシステム変数を厳格に守るため、.envの読み込み (dotenv) を無効化しています。

Nanobot (~/.nanobot/config.json) やその他のエンドポイント経由で呼び出す場合は、設定配列内で直接環境変数を定義してください：

"OPENAI_API_KEY": "your_api_key_from_venice_minimax_openrouter_etc",
"OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
"FAST_LLM": "venice:llama-3.3-70b",
"SMART_LLM": "minimax:MiniMax-M2.7",
"STRATEGIC_LLM": "openrouter:google/gemini-2.5-flash",
"RETRIEVER": "duckduckgo"

🤖 Nanobot統合 (主要な焦点)

このサーバーは、Nanobotアシスタントによって操縦されるstdio MCPサーバーとして実行されるように根本的に調整されています。

~/.nanobot/config.jsonに以下を追加してください：

{
  "mcpServers": {
    "percival_deep_research": {
      "command": "uv",
      "args": [
        "run",
        "--no-sync",
        "percival-deep-research"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/absolute/path/to/percival.OS_Dev/.venv",
        "OPENAI_API_KEY": "actual-key-here",
        "OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
        "FAST_LLM": "venice:llama-3.3-70b",
        "RETRIEVER": "duckduckgo"
      },
      "tool_timeout": 300
    }
  }
}

注: deep_researchは最大2〜3分かかる場合があります。tool_timeoutが適切にスケーリングされていることを確認してください (例: 180-300)。

Nanobotのための重要な設計決定

• JSON辞書よりもプレーンテキスト — すべてのツールは、Nanobotにクリーンなテキストを供給するために、JSON辞書ではなくプレーンテキスト文字列を予測可能に返します。

• コンテキストのモジュール化 — deep_researchは、Nanobotのコンテキストウィンドウを圧迫しないよう、初期化レスポンスから巨大な合成コンテキストを省略します。代わりに、エージェントがget_research_contextを明示的に呼び出すために使用するresearch_idを発行します。

💻 Claude Desktop統合

Nanobotが推奨されるドライバーですが、Claude Desktopにデプロイする場合は、claude_desktop_config.jsonに以下を追記してください：

{
  "mcpServers": {
    "percival_deep_research": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/percival.OS_Dev",
        "percival-deep-research"
      ],
      "env": {
        "OPENAI_API_KEY": "your-provider-key",
        "OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
        "FAST_LLM": "venice:llama-3.3-70b",
        "RETRIEVER": "duckduckgo"
      }
    }
  }
}

🔐 セキュリティ

このサーバーは、MCPサーバーが信頼できないWebコンテンツを自律的に処理するリスクに対処するため、多層防御を実装しています。

プロンプトインジェクション保護

ユーザー入力 (query, topic, custom_prompt) は、未知の値や不正な形式の値を制限します。正規表現ベースのフィルターが、既知のジェイルブレイクパターン (<system>, [INST], ignore instructionsなど) をブロックします。

信頼できないコンテンツの分離

Webから取得されたすべてのコンテンツは、エージェントのコンテキストに提示される前に動的にプレフィックスが付与されます：

[SECURITY WARNING: The content below was obtained from unverified external...]

これにより、Nanobotのようなモデルは、Webソースのデータを厳密に情報ブロックとして扱うようになり、予期しないコマンドの実行を回避します。

📄 ライセンス

本プロジェクトはMITライセンスの下でライセンスされています。