mcpField
D
Deep Research MCP Server

Deep Research MCP Server

ローカル
pinkpixel.devデータ・分析2715 週間前に更新

Deep Research MCP Server について

Deep Research MCP Server は、Tavily の検索および クロール API を用いてテーマ別の Web リサーチを行う MCP サーバーです。結果を LLM が Markdown 文書を作成しやすい構造化 JSON にまとめます。出典付きの資料を必要とする開発者や研究者に向いています。

主な機能

  1. 01Tavily 検索と詳細なコンテンツクロールの組み合わせ
  2. 02LLM 向けの構造化 JSON 出力
  3. 03環境変数または引数によるドキュメント用プロンプトの上書き
  4. 04出力パスとタイムアウトの設定
  5. 05デフォルトで無効なファイル書き込みツール

活用シーン

  1. 01技術テーマに関する Web 資料を収集し文書を作成する
  2. 02出典付きのリサーチデータを LLM に提供する
  3. 03検索とクロールの件数や時間を用途に合わせて調整する

MCP 対応

本プロジェクトは MCP サーバーであり、deep-research-tool を通じて MCP クライアントにリサーチデータを提供します。任意で write-research-file ツールも公開できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"deep-research": {
"command": "npx",
"args": [
"-y",
"@pinkpixel/deep-research-mcp"
],
"env": {
"TAVILY_API_KEY": "<TAVILY_API_KEY>",
"DOCUMENTATION_PROMPT": "<DOCUMENTATION_PROMPT>",
"RESEARCH_OUTPUT_PATH": "<RESEARCH_OUTPUT_PATH>"
}
}
}
}
起動コマンドnpx -y @pinkpixel/deep-research-mcp
設定が必要な環境変数
TAVILY_API_KEYシークレット
DOCUMENTATION_PROMPT
RESEARCH_OUTPUT_PATH

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npm@pinkpixel/deep-research-mcp

ツール

2

掲載時のツール一覧 · 3 週間前に更新

パラメーター型必須説明
daysnumberいいえ'news' トピックの場合:結果に含める、現在の日付から遡る日数。
querystringはい主な調査テーマまたは質問。
topicenumいいえTavily 検索のカテゴリ('general' または 'news')。general | news
time_rangestringいいえ検索結果の期間(例:'d' は日、'w' は週、'm' は月、'y' は年)。
crawl_limitnumberいいえ各ルート URL についてクローラーが処理するリンクの合計数(1-20)。CRAWL_LIMIT 環境変数で設定できます。
search_depthenumいいえ初回の Tavily 検索の深度('basic' または 'advanced')。basic | advanced
crawl_timeoutnumberいいえTavily のクロールリクエストのタイムアウト時間(秒)。CRAWL_TIMEOUT 環境変数で設定できます。
include_answeranyいいえTavily 検索で LLM が生成した回答を含めます(true の場合は 'basic' が適用されます)。
search_timeoutnumberいいえTavily の検索リクエストのタイムアウト時間(秒)。SEARCH_TIMEOUT 環境変数で設定できます。
crawl_max_depthnumberいいえベース URL からの最大クロール深度(1-2)。値を大きくすると処理時間が大幅に増加します。CRAWL_MAX_DEPTH 環境変数で設定できます。
crawl_categoriesarrayいいえカテゴリでクロール URL を絞り込みます(例:'Blog'、'Documentation')。
chunks_per_sourcenumberいいえ'advanced' 検索の場合:各ソースから取得するコンテンツチャンク数(1-3)。
crawl_max_breadthnumberいいえクロールの各階層でたどるリンクの最大数(1-10)。
crawl_instructionsstringいいえクローラー向けの自然言語による指示。
crawl_select_pathsarrayいいえクロール対象の URL パスに使う正規表現(例:'/docs/.*')。
max_search_resultsnumberいいえクロール用に取得する検索結果の最大数(1-20)。MAX_SEARCH_RESULTS 環境変数で設定できます。
crawl_exclude_pathsarrayいいえ除外する URL パスの正規表現。
crawl_extract_depthenumいいえクロールの抽出深度('basic' または 'advanced')。basic | advanced
crawl_allow_externalbooleanいいえクローラーが外部ドメインへのリンクをたどることを許可します。
crawl_include_imagesbooleanいいえクロールしたページから画像 URL を抽出します。
crawl_select_domainsarrayいいえクロール対象のドメイン/サブドメインの正規表現(例:'^docs\.example\.com$')。自動ドメインフォーカスを上書きします。
documentation_promptstringいいえ任意。LLM によるドキュメント生成用のカスタムプロンプトです。'DOCUMENTATION_PROMPT' 環境変数およびデフォルト値を上書きします。設定がない場合は、包括的なデフォルト値が使用されます。
crawl_exclude_domainsarrayいいえ除外するドメイン/サブドメインの正規表現。
hardware_accelerationbooleanいいえ利用可能な場合は、ハードウェアアクセラレーション(WebGPU)の使用を試みます。
include_search_imagesbooleanいいえ初期検索結果の画像 URL を含めます。
exclude_domains_searcharrayいいえ検索から明示的に除外するドメインのリスト。
include_domains_searcharrayいいえ検索に明示的に含めるドメインのリスト。
include_raw_content_searchbooleanいいえ初回検索結果のクリーンアップ済み HTML を含めます。
include_search_image_descriptionsbooleanいいえ初回検索結果の画像の説明を含めます。

詳細

Deep Research MCP ロゴ

Deep Research MCP サーバー

NPM バージョン ライセンス: MIT Smithery インストール数

Deep Research MCP サーバーは、Model Context Protocol (MCP) に準拠したサーバーであり、包括的なウェブリサーチを実行するために設計されています。Tavily の強力な Search API と新しい Crawl API を活用して、特定のトピックに関する広範で最新の情報を収集します。そしてサーバーは、このデータをドキュメント生成の指示とともに構造化された JSON 出力に集約します。これは、LLM が詳細で高品質な Markdown ドキュメントを作成するために最適化されています。

機能

  • 多段階リサーチ: Tavily の AI を活用したウェブ検索と、深いコンテンツクロールを組み合わせて、徹底的な情報収集を行います。
  • 構造化された JSON 出力: LLM での利用に最適化された、整理されたデータ (元のクエリ、検索サマリー、ソースごとの詳細な調査結果、ドキュメント生成の指示) を提供します。
  • 設定可能なドキュメント生成プロンプト: 高品質な技術ドキュメントを生成するための、包括的なデフォルトプロンプトが含まれています。このプロンプトは次の方法で変更できます:
    • DOCUMENTATION_PROMPT 環境変数を設定することで上書きできます。
    • ツールに documentation_prompt 引数を直接渡すことで、さらに上書きできます。
  • 設定可能な出力パス: リサーチドキュメントと画像の保存先を次の方法で指定できます:
    • 環境変数の設定
    • JSON 設定
    • ツール呼び出し時の直接パラメータ
  • きめ細かな制御: 検索プロセスとクロールプロセスの両方を微調整するための、幅広いパラメータを提供します。
  • MCP 準拠: MCP ベースの AI エージェントエコシステムにシームレスに統合できるように設計されています。

前提条件

  • Node.js (バージョン 18.x 以降を推奨)
  • npm (Node.js に付属) または Yarn

インストール

Smithery 経由でのインストール

Smithery を介して Claude Desktop 用に deep-research-mcp を自動的にインストールするには:

npx -y @smithery/cli install @pinkpixel/dev-deep-research-mcp --client claude
オプション 1: NPX を使用する (手軽に使う場合に推奨)

グローバルインストールを行わずに、npx を使用してサーバーを直接実行できます:

npx @pinkpixel/deep-research-mcp
オプション 2: グローバルインストール (任意)
npm install -g @pinkpixel/deep-research-mcp

その後、次のコマンドで実行できます:

deep-research-mcp
オプション 3: ローカルプロジェクトへの統合または開発
  1. リポジトリをクローンします (変更やコントリビュートを行いたい場合):
    git clone [https://github.com/your-username/deep-research-mcp.git](https://github.com/your-username/deep-research-mcp.git)
    cd deep-research-mcp
    
  2. 依存関係をインストールします:
    npm install
    

設定

サーバーは Tavily API キーを必要とし、任意でカスタムのドキュメント生成プロンプトを受け付けることができます。

{
  "mcpServers": {
    "deep-research": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/deep-research-mcp"
      ],
      "env": {
        "TAVILY_API_KEY": "tvly-YOUR_ACTUAL_API_KEY_HERE", // Required
        "DOCUMENTATION_PROMPT": "Your custom, detailed instructions for the LLM on how to generate markdown documents from the research data...", // Optional - if not provided, the default prompt will be used
        "SEARCH_TIMEOUT": "120", // Optional - timeout in seconds for search requests (default: 60)
        "CRAWL_TIMEOUT": "300", // Optional - timeout in seconds for crawl requests (default: 180)
        "MAX_SEARCH_RESULTS": "10", // Optional - maximum search results to retrieve (default: 7)
        "CRAWL_MAX_DEPTH": "2", // Optional - maximum crawl depth (default: 1)
        "CRAWL_LIMIT": "15", // Optional - maximum URLs to crawl per source (default: 10)
        "FILE_WRITE_ENABLED": "true", // Optional - enable file writing capability (default: false)
        "ALLOWED_WRITE_PATHS": "/home/user/research,/home/user/documents", // Optional - comma-separated allowed directories (default: user home directory)
        "FILE_WRITE_LINE_LIMIT": "300" // Optional - maximum lines per file write operation (default: 200)
      }
    }
  }
}
1. Tavily API キー (必須)

TAVILY_API_KEY 環境変数に Tavily API キーを設定します。

方法:

  • .env ファイル: プロジェクトのルートに .env ファイルを作成します (開発用にローカルで実行する場合):
    TAVILY_API_KEY="tvly-YOUR_ACTUAL_API_KEY"
    
  • コマンドラインで直接指定:
    TAVILY_API_KEY="tvly-YOUR_ACTUAL_API_KEY" npx @pinkpixel/deep-research-mcp
    
  • システム環境変数: お使いのオペレーティングシステムの環境変数に設定します。
2. カスタムドキュメントプロンプト (任意)

DOCUMENTATION_PROMPT 環境変数を設定することで、デフォルトの包括的なドキュメントプロンプトを上書きできます。

設定方法 (優先順位順):

  1. ツール引数: deep-research-tool を呼び出す際に渡される documentation_prompt パラメーターが最優先されます
  2. 環境変数: ツール呼び出しでパラメーターが指定されていない場合、システムは DOCUMENTATION_PROMPT 環境変数を確認します
  3. デフォルト値: 上記のいずれも設定されていない場合、包括的な組み込みのデフォルトプロンプトが使用されます

.env ファイルでの設定:

DOCUMENTATION_PROMPT="Your custom, detailed instructions for the LLM on how to generate markdown..."

またはコマンドラインで直接設定:

DOCUMENTATION_PROMPT="Your custom prompt..." TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp
3. 出力パスの設定 (任意)

リサーチドキュメントと画像を保存する場所を指定できます。設定されていない場合は、ユーザーの Documents フォルダー内のタイムスタンプ付きのデフォルトパスが使用されます。

設定方法 (優先順位順):

  1. ツール引数: deep-research-tool を呼び出す際に渡される output_path パラメーターが最優先されます
  2. 環境変数: ツール呼び出しでパラメーターが指定されていない場合、システムは RESEARCH_OUTPUT_PATH 環境変数を確認します
  3. デフォルトパス: 上記のいずれも設定されていない場合、ユーザーの Documents フォルダー内のタイムスタンプ付きサブフォルダーが使用されます: ~/Documents/research/YYYY-MM-DDTHH-MM-SS/

.env ファイルでの設定:

RESEARCH_OUTPUT_PATH="/path/to/your/research/folder"

またはコマンドラインで直接設定:

RESEARCH_OUTPUT_PATH="/path/to/your/research/folder" TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp
4. タイムアウトとパフォーマンスの設定 (任意)

環境変数を通じてタイムアウトとパフォーマンスの設定を構成し、特定のユースケースやデプロイ環境に合わせてツールを最適化できます:

利用可能な環境変数:

  • SEARCH_TIMEOUT - Tavily 検索リクエストのタイムアウト (秒) (デフォルト: 60)
  • CRAWL_TIMEOUT - Tavily クロールリクエストのタイムアウト (秒) (デフォルト: 180)
  • MAX_SEARCH_RESULTS - 取得する検索結果の最大数 (デフォルト: 7)
  • CRAWL_MAX_DEPTH - ベース URL からの最大クロール深度 (デフォルト: 1)
  • CRAWL_LIMIT - ソースごとにクロールする URL の最大数 (デフォルト: 10)

.env ファイルでの設定:

SEARCH_TIMEOUT=120
CRAWL_TIMEOUT=300
MAX_SEARCH_RESULTS=10
CRAWL_MAX_DEPTH=2
CRAWL_LIMIT=15

またはコマンドラインで直接設定:

SEARCH_TIMEOUT=120 CRAWL_TIMEOUT=300 TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp

これらの設定を調整すべきタイミング:

  • LibreChat やその他の MCP クライアントでタイムアウトエラーが発生している場合は、タイムアウトを増やしてください
  • よりシンプルなクエリを扱う際に応答を高速化したい場合は、タイムアウトを減らしてください
  • より包括的なリサーチを行いたい場合は、制限を増やしてください (ただし処理時間が長くなることを想定してください)
  • 軽いリソース使用でより高速に処理したい場合は、制限を減らしてください
5. ファイル書き込みの設定 (任意)

このサーバーには、LLM がリサーチ結果を直接ファイルに保存できる安全なファイル書き込みツールが含まれています。この機能はセキュリティ上の理由からデフォルトで無効になっています。

セキュリティ機能:

  • ファイル書き込みは FILE_WRITE_ENABLED=true で明示的に有効化する必要があります
  • ALLOWED_WRITE_PATHS によるディレクトリ制限 (デフォルトはユーザーのホームディレクトリ)
  • 悪用を防ぐための書き込み操作ごとの行数制限
  • パスの検証とサニタイズ
  • ディレクトリの自動作成

設定:

FILE_WRITE_ENABLED=true
ALLOWED_WRITE_PATHS=/home/user/research,/home/user/documents,/tmp/research
FILE_WRITE_LINE_LIMIT=500

使用例: 一度有効にすると、LLM は write-research-file ツールを使用してコンテンツを保存できます:

{
  "tool": "write-research-file",
  "arguments": {
    "file_path": "/home/user/research/quantum-computing-report.md",
    "content": "# Quantum Computing Research Report\n\n...",
    "mode": "rewrite"
  }
}

セキュリティ上の考慮事項:

  • ファイル書き込みは信頼できる環境でのみ有効にしてください
  • システム全体へのアクセスを許可するのではなく、特定のディレクトリ制限を使用してください
  • サーバーログを通じてファイル操作を監視してください
  • 機密性の高いシステムでは読み取り専用ディレクトリの使用を検討してください

サーバーの実行

  • 開発時(自動リロードあり): リポジトリをクローンしてプロジェクトディレクトリにいる場合:

    npm run dev
    

    これは nodemon と ts-node を使用して変更を監視し、サーバーを再起動します。

  • 本番/スタンドアロン: まず、TypeScript コードをビルドします:

    npm run build
    

    次に、サーバーを起動します:

    npm start
    
  • NPX またはグローバルインストールの場合: (構成で説明されているとおりに環境変数が設定されていることを確認してください)

    npx @pinkpixel/deep-research-mcp
    

    または、グローバルにインストールされている場合:

    deep-research-mcp
    

サーバーは stdio で MCP リクエストを待ち受けます。

仕組み

  1. LLM または AI エージェントがこの MCP サーバーに対して CallToolRequest を発行し、deep-research-tool を指定して、クエリやその他のオプションパラメータを渡します。
  2. deep-research-tool はまず Tavily Search を実行して、関連するウェブソースを探します。
  3. 次に Tavily Crawl を使用して、これらの各ソースから詳細なコンテンツを抽出します。
  4. 収集されたすべての情報(検索スニペット、クロールされたコンテンツ、画像 URL)が集約されます。
  5. 選択されたドキュメントプロンプト(デフォルト、ENV、またはツール引数)が含められます。
  6. サーバーは、これらすべての構造化データを含む単一の JSON 文字列を返します。
  7. 呼び出し元の LLM/エージェントは、documentation_instructions に導かれながらこの JSON 出力を使用して、包括的な markdown ドキュメントを生成します。

deep-research-tool の使用

これはサーバーによって公開される主要なツールです。

出力構造

このツールは、次の構造を持つ JSON 文字列を返します:

{
  "documentation_instructions": "string", // The detailed prompt for the LLM to generate the markdown.
  "original_query": "string",         // The initial query provided to the tool.
  "search_summary": "string | null",  // An LLM-generated answer/summary from Tavily's search phase (if include_answer was true).
  "research_data": [                  // Array of findings, one element per source.
    {
      "search_rank": "number",
      "original_url": "string",           // URL of the source found by search.
      "title": "string",                  // Title of the web page.
      "initial_content_snippet": "string",// Content snippet from the initial search result.
      "search_score": "number | undefined",// Relevance score from Tavily search.
      "published_date": "string | undefined",// Publication date (if 'news' topic and available).
      "crawled_data": [                 // Array of pages crawled starting from original_url.
        {
          "url": "string",                // URL of the specific page crawled.
          "raw_content": "string | null", // Rich, extracted content from this page.
          "images": ["string", "..."]     // Array of image URLs found on this page.
        }
      ],
      "crawl_errors": ["string", "..."]   // Array of error messages if crawling this source failed or had issues.
    }
    // ... more sources
  ],
  "output_path": "string"             // Path where research documents and images should be saved.
}
入力パラメータ

deep-research-tool は、その arguments オブジェクトで次のパラメータを受け付けます:

一般パラメータ
  • query (string、必須): 主な調査トピックまたは質問。
  • documentation_prompt (string、オプション): LLM ドキュメント生成用のカスタムプロンプト。
    • 説明: 指定された場合、このプロンプトが LLM によって使用されます。これは DOCUMENTATION_PROMPT 環境変数とサーバー内蔵のデフォルトプロンプトの両方を上書きします。ここで指定されない場合、サーバーは環境変数を確認し、それからデフォルトにフォールバックします。
  • output_path (string、オプション): 生成された調査ドキュメントと画像を保存するパス。
    • 説明: 指定された場合、このパスが調査出力の保存に使用されます。これは RESEARCH_OUTPUT_PATH 環境変数を上書きします。どちらも設定されていない場合、ユーザーの Documents ディレクトリ内のタイムスタンプ付きフォルダが使用されます。
検索パラメータ(Tavily Search API 用)
  • search_depth(文字列、任意、デフォルト: "advanced"): 最初の Tavily 検索の深さ。
    • オプション: "basic"、"advanced"。高度な検索は、より関連性の高いソースに合わせて調整されています。
  • topic(文字列、任意、デフォルト: "general"): Tavily 検索のカテゴリ。
    • オプション: "general"、"news"。
  • days(数値、任意): topic: "news" の場合、現在の日付から遡って検索結果に含める日数。
  • time_range(文字列、任意): 検索結果の期間(例: "d" は日、"w" は週、"m" は月、"y" は年)。
  • max_search_results(数値、任意、デフォルト: 7): 取得し、クロール対象として検討する検索結果の最大数(1〜20)。
  • chunks_per_source(数値、任意、デフォルト: 3): search_depth: "advanced" の場合、各ソースから取得するコンテンツチャンクの数(1〜3)。
  • include_search_images(ブール値、任意、デフォルト: false): 最初の検索から、クエリに関連する画像 URL のリストを含めます。
  • include_search_image_descriptions(ブール値、任意、デフォルト: false): 最初の検索から、URL とともに画像の説明を含めます。
  • include_answer(ブール値または文字列、任意、デフォルト: false): 検索結果に基づいて Tavily が生成した LLM による回答を含めます。
    • オプション: true("basic" を暗黙的に指定)、false、"basic"、"advanced"。
  • include_raw_content_search(ブール値、任意、デフォルト: false): 最初の各検索結果のクリーニングおよび解析済みの HTML コンテンツを含めます。
  • include_domains_search(文字列の配列、任意、デフォルト: []): 検索結果に明示的に含めるドメインのリスト。
  • exclude_domains_search(文字列の配列、任意、デフォルト: []): 検索結果から明示的に除外するドメインのリスト。
  • search_timeout(数値、任意、デフォルト: 60): Tavily 検索リクエストのタイムアウト(秒)。
クロールパラメータ(Tavily Crawl API 用 - 検索で得られた各 URL に適用されます)
  • crawl_max_depth(数値、任意、デフォルト: 1): ベース URL からのクロールの最大深さです。0 はベース URL のみ、1 はベース URL とそこで見つかったリンクを意味します。
  • crawl_max_breadth(数値、任意、デフォルト: 5): クロールツリーの各レベル(つまり各ページ)ごとにたどるリンクの最大数です。
  • crawl_limit(数値、任意、デフォルト: 10): 単一のルート URL から開始して、クローラーが停止するまでに処理するリンクの総数です。
  • crawl_instructions(文字列、任意): サイトをどのようにクロールするかについての、クローラー向けの自然言語による指示です。
  • crawl_select_paths(文字列の配列、任意、デフォルト: []): クロール対象を特定のパスパターンを持つ URL のみに絞り込むための正規表現パターンです(例: "/docs/.*")。
  • crawl_select_domains(文字列の配列、任意、デフォルト: []): クロールを特定のドメインまたはサブドメインに制限するための正規表現パターンです(例: "^docs\\.example\\.com$")。crawl_allow_external が false(デフォルト)で、これが空の場合、クロールはクロール対象 URL のドメインに集中します。この設定はその集中を上書きします。
  • crawl_exclude_paths(文字列の配列、任意、デフォルト: []): 特定のパスパターンを持つ URL をクロールから除外するための正規表現パターンです。
  • crawl_exclude_domains(文字列の配列、任意、デフォルト: []): 特定のドメインまたはサブドメインをクロールから除外するための正規表現パターンです。
  • crawl_allow_external(真偽値、任意、デフォルト: false): クローラーが外部ドメインへのリンクをたどることを許可するかどうかです。
  • crawl_include_images(真偽値、任意、デフォルト: true): クロールしたページから画像 URL を抽出するかどうかです。
  • crawl_categories(文字列の配列、任意、デフォルト: []): 定義済みのカテゴリ(例: "Blog"、"Documentation"、"Careers")を使用してクロール対象の URL をフィルタリングします。すべてのオプションについては Tavily Crawl API を参照してください。
  • crawl_extract_depth(文字列、任意、デフォルト: "advanced"): クロール中のコンテンツ抽出の深さです。
    • オプション: "basic"、"advanced"。advanced はより多くのデータ(テーブル、埋め込みコンテンツ)を取得しますが、レイテンシが高くなる可能性があります。
  • crawl_timeout(数値、任意、デフォルト: 180): 各 Tavily Crawl リクエストのタイムアウト(秒)です。

ドキュメントプロンプトの優先順位を理解する

documentation_prompt は、調査結果をどのようにフォーマットし構造化するかを LLM に指示するため、このツールの重要な要素です。システムは次の優先順位に従って、使用するプロンプトを決定します。

  1. LLM/エージェントがツール呼び出しで documentation_prompt パラメータを指定した場合:

    • これが最優先され、他の設定に関係なく使用されます
    • これにより、エンドユーザーは LLM への自然言語リクエストを通じてドキュメントのフォーマットをカスタマイズできます
  2. ツール呼び出しでパラメータが指定されていないが、DOCUMENTATION_PROMPT 環境変数が設定されている場合:

    • 環境変数の値が使用されます
    • これは、システム管理者や開発者がすべてのツール呼び出しで一貫したプロンプトを設定するのに便利です
  3. 上記のいずれも設定されていない場合:

    • 包括的な組み込みのデフォルトプロンプトが使用されます
    • このデフォルトプロンプトは、高品質な技術ドキュメントを生成するように設計されています

この柔軟性により、次のことが可能になります:

  • エンドユーザーが LLM への自然言語リクエストを通じてドキュメントをカスタマイズする
  • 開発者がシステム全体のデフォルトを設定する
  • カスタマイズが提供されない場合に、適切に設計されたデフォルトにフォールバックする

出力パスの扱い

output_path パラメータは、調査ドキュメントと画像が保存される場所を決定します。これは、LLM が次の操作を行う必要がある場合に特に重要です。

  1. 生成された markdown ドキュメントを保存する
  2. 調査から画像をダウンロードして保存する
  3. 補足ファイルやリソースを作成する

システムは、出力パスを決定するために次の優先順位に従います。

  1. LLM/エージェントがツール呼び出しで output_path パラメータを指定した場合:

    • これが最優先されます
    • エンドユーザーが自然言語のリクエストを通じてカスタムの保存場所を指定できるようにします
  2. パラメータはないものの、RESEARCH_OUTPUT_PATH 環境変数が設定されている場合:

    • その値が使用されます
    • 設定ファイルによる構成に適しています
  3. 上記のいずれも設定されていない場合は、タイムスタンプ付きのデフォルトが使用されます: ~/researcher/research/YYYY-MM-DDTHH-MM-SS/

    • これにより、以前の調査結果が上書きされるのを防ぎます

ツールは解決された出力パスをツールの JSON 内の output_path フィールドとして返すため、LLM は生成されたコンテンツをどこに保存すべきかを常に把握できます。

LLM 向けの注意: ツールの結果を処理する際は、output_path フィールドを確認して、生成するファイルをどこに保存すべきかを判断してください。このパスはレスポンスに必ず含まれます。

LLM 向けの指示

deep-research-tool の出力を使用する LLM として、あなたの主な目標は、original_query に応える、包括的で正確かつ構造化された markdown ドキュメントを生成することです。

主なステップ:

  1. JSON 出力を解析します: ツールは JSON 文字列を返します。これを解析して、documentation_instructions、original_query、search_summary、research_data の各フィールドにアクセスします。
  2. documentation_instructions に従います: このフィールドには、Markdown ドキュメントを作成するための主要なガイドラインのセットが含まれています。これは、サーバーの詳細なデフォルトプロンプト(高品質な技術ドキュメントに焦点を当てたもの)か、ユーザーが提供したカスタムプロンプトのいずれかです。コンテンツの品質、スタイル、構造、Markdown のフォーマット、技術的な詳細の扱いに関して、これらの指示に細心の注意を払って従ってください。
  3. コンテンツには research_data を活用します:
    • research_data 配列は、情報の主要なソースです。この配列内の各オブジェクトは、個別の Web ソースを表します。
    • 各ソースについて、コンテキストとしてその title、original_url、initial_content_snippet に注目してください。
    • ドキュメントの中心となる情報は、各ソース内の crawled_data 配列から得られます。具体的には、各 crawled_data オブジェクトの raw_content フィールドに、そのページから抽出されたリッチテキストが含まれています。
    • research_data 内の複数のソースにまたがって情報を統合し、包括的な視点を提供してください。あるソースの内容を次々と列挙するだけにしないでください。
    • crawled_data[].images が存在する場合、それが適切であり、documentation_instructions に沿うものであれば、それらに言及したり、その URL を記載したりしてもかまいません。
    • あるソースに crawl_errors が存在する場合、その特定のソースが不完全である可能性があることを意味します。網羅性に影響するようであれば、さりげなく言及することを選んでもかまいません。
  4. original_query に対応します: 最終的なドキュメントは、original_query に包括的に回答または対応しなければなりません。
  5. search_summary を活用します: search_summary フィールドが存在する場合(Tavily の include_answer 機能によるもの)、それは有用な出発点、エグゼクティブサマリー、または導入を組み立てる方法として役立ちます。ただし、ドキュメントの本体は、より詳細な research_data から構築する必要があります。
  6. 統合し、ただコピーしない: あなたの役割は、raw_content をそのまま吐き出すことではありません。documentation_instructions に従い、さまざまなソースからの情報を処理し、理解し、統合し、言い換え、論理的に流れる首尾一貫した、よく書かれたドキュメントに整理する必要があります。
  7. Markdown のフォーマット: documentation_instructions で提供される Markdown のフォーマットガイドライン(見出し、リスト、コードブロック、強調、リンクなど)に厳密に従ってください。
  8. 大量のデータの扱い: research_data は非常に膨大になる可能性があります。大きな入力の処理に制限がある場合、あなたを呼び出すシステムが、research_data をチャンクに分けて提供したり、ドキュメントをセクションごとに構築するために複数回のリクエストを行ったりする必要があるかもしれません。deep-research-tool 自体は、常に収集したすべてのデータを 1 つの JSON 出力で返そうとします。
  9. 技術的な正確性: documentation_instructions で義務付けられているとおり、ソースコンテンツからすべての技術的詳細、コード例、重要な具体的事項を保持してください。過度に単純化しないでください。
  10. 視覚的な魅力(指示がある場合): documentation_instructions に視覚的な魅力に関するガイドライン(HTML を使用した色付きテキストや絵文字など)が含まれている場合は、それらを慎重に適用してください。

LLM 呼び出しの思考プロセスの例:

エージェントから LLM へ: 「では、deep-research-tool をクエリ『<em>量子耐性暗号の最新の進歩は何ですか?</em>』で呼び出し、高度なクロールを使用して 5 つのソースを要求しました。これがその JSON 出力です: { ... (ツールからの JSON 出力) ... }

さて、この JSON 内で提供されている documentation_instructions と research_data を使用して、『量子耐性暗号の最新の進歩』に関する包括的な Markdown ドキュメントを生成してください。指示にあるすべてのフォーマットとコンテンツのガイドラインに従うようにしてください。」

CallToolRequest の例(概念的な引数)

エージェントは、次のような引数で MCP サーバーを呼び出すことがあります。

{
  "name": "deep-research-tool",
  "arguments": {
    "query": "Explain the architecture of modern data lakes and data lakehouses.",
    "max_search_results": 5,
    "search_depth": "advanced",
    "topic": "general",
    "crawl_max_depth": 1,
    "crawl_extract_depth": "advanced",
    "include_answer": true,
    "documentation_prompt": "Generate a highly technical whitepaper. Start with an abstract, then introduction, detailed sections for data lakes, data lakehouses, comparison, use cases, and a future outlook. Use academic tone. Include all diagrams mentioned by URL if possible as [Diagram: URL].",
    "output_path": "C:/Users/username/Documents/research/datalakes-whitepaper"
  }
}

トラブルシューティング

  • API キーエラー: TAVILY_API_KEY が正しく設定され、有効であることを確認してください。
  • SDK の問題: @modelcontextprotocol/sdk と @tavily/core がインストールされ、最新の状態であることを確認してください。
  • 出力がない/エラーが発生する: サーバーのコンソールログでエラーメッセージを確認してください。デバッグのために必要に応じて詳細度を上げてください。

変更履歴

v0.1.2 (2024-05-10)
  • 設定可能な出力パス機能を追加
  • 最新の Tavily SDK での型エラーを修正
  • 出力パスに関する包括的なドキュメントを追加
  • ロゴを追加し、ドキュメントを改善
v0.1.1
  • 初回公開リリース

コントリビューション

コントリビューションを歓迎します!お気軽に issue を送信したり、リポジトリをフォークしたり、プルリクエストを作成したりしてください。

ライセンス

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

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。