mcpField
T
tavily

tavily

github.com/intellectronica生産性298628 回インストール27 週間前に更新
リポジトリ

tavily について

Tavilyは、curlでTavily REST APIを呼び出すスキルです。ウェブ検索、ページ抽出、サイトURLの発見とクロールに加え、任意の調査フローにも対応し、LLMワークフロー向けに結果を構造化します。

主な機能

  1. 01条件を指定したウェブ検索
  2. 02URLからのコンテンツ抽出
  3. 03サイトURLのマッピングとクロール
  4. 04任意の複数段階の調査
  5. 05出典付きの構造化結果

活用シーン

  1. 01ウェブ上の最新情報を検索
  2. 02指定ページから内容を抽出
  3. 03サイトのページを発見またはクロール
  4. 04調査用に引用可能な出典を収集

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/intellectronica/agent-skills --skill tavily

インストール後、Claude Code で/tavilyを入力して読み込まれたか確認します。

詳細

Tavily

目的

Tavily の REST API に対して、検索、抽出、マッピング、クロール、および任意のリサーチを行う curl ベースのインターフェースを提供します。LLM のワークフローや複数ステップの調査に適した、構造化された結果を返します。

使用する場面

  • 最新のウェブ情報、サイトの抽出、マッピング、またはクロールが必要なタスクで使用します。
  • ウェブ検索が必要で、組み込みツールが利用できない場合や、Tavily の LLM 向け出力（要約、チャンク、ソース、引用）が役立つ場合に使用します。
  • Tavily による構造化された検索結果、抽出、またはサイトの検出が必要なタスクで使用します。

必要な環境

  • 環境変数に TAVILY_API_KEY が必要です。
  • TAVILY_API_KEY が設定されていない場合は、続行する前にユーザーに API キーを求めてください。

ベース URL と認証

  • ベース URL：https://api.tavily.com
  • 認証：Authorization: Bearer $TAVILY_API_KEY
  • コンテンツタイプ：Content-Type: application/json
  • 任意のプロジェクト追跡：プロジェクトへの帰属情報が必要な場合は、X-Project-ID: <project-id> を追加します。

ツールの対応関係（Tavily REST）

1) search → POST /search

回答とコンテンツ抽出を任意で行えるウェブ検索に使用します。

推奨される最小限のリクエスト：

curl -sS -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "query": "<query>",
    "search_depth": "basic",
    "max_results": 5,
    "include_answer": true,
    "include_raw_content": false,
    "include_images": false
  }'

主なパラメーター（必須と記載されているものを除き、すべて任意）：

  • query（必須）：検索テキスト
  • search_depth：basic | advanced | fast | ultra-fast
  • chunks_per_source：1～3（advanced のみ）
  • max_results：0～20
  • topic：general | news | finance
  • time_range：day|week|month|year|d|w|m|y
  • start_date、end_date：YYYY-MM-DD
  • include_answer：false | true | basic | advanced
  • include_raw_content：false | true | markdown | text
  • include_images：ブール値
  • include_image_descriptions：ブール値
  • include_favicon：ブール値
  • include_domains、exclude_domains：文字列の配列
  • country：国名（general トピックのみ）
  • auto_parameters：ブール値
  • include_usage：ブール値

想定されるレスポンスフィールド：

  • answer（要求した場合）、title、url、content、score、raw_content（任意）、favicon（任意）を含む results[]
  • response_time、usage、request_id
2) extract → POST /extract

特定の URL からコンテンツを抽出する際に使用します。

curl -sS -X POST "https://api.tavily.com/extract" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "urls": ["https://example.com/article"],
    "query": "<optional intent for reranking>",
    "chunks_per_source": 3,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false,
    "include_favicon": false
  }'

主なパラメーター：

  • urls（必須）：URL の配列
  • query：意図に応じてチャンクを再ランク付けします
  • chunks_per_source：1～5（query を指定した場合のみ）
  • extract_depth：basic | advanced
  • format：markdown | text
  • timeout：1～60 秒
  • include_usage：ブール値

想定されるレスポンスフィールド：

  • url、raw_content、images、favicon を含む results[]
  • failed_results[]、response_time、usage、request_id
3) map → POST /map

サイトマップの生成（URL の検出のみ）に使用します。

curl -sS -X POST "https://api.tavily.com/map" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "allow_external": true
  }'

主なパラメーター：

  • url（必須）
  • instructions：自然言語による指示（コストが増加します）
  • max_depth：1～5
  • max_breadth：1 以上
  • limit：1 以上
  • select_paths、select_domains、exclude_paths、exclude_domains：正規表現文字列の配列
  • allow_external：ブール値
  • timeout：10～150 秒
  • include_usage：ブール値

想定されるレスポンスフィールド：

  • base_url、URL の一覧である results[]、response_time、usage、request_id
4) crawl → POST /crawl

組み込みの抽出機能を使ってサイトを巡回する際に使用します。

curl -sS -X POST "https://api.tavily.com/crawl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "instructions": "Find all pages about the Python SDK",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false
  }'

主なパラメーター：

  • url（必須）
  • instructions：任意。コストが増加し、chunks_per_source が有効になります
  • chunks_per_source：1～5（instructions を指定した場合のみ）
  • max_depth、max_breadth、limit：map と同じ
  • extract_depth：basic | advanced
  • format：markdown | text
  • include_images、include_favicon、allow_external
  • timeout：10～150 秒
  • include_usage：ブール値

想定されるレスポンスフィールド：

  • url、raw_content、favicon を含む results[] と base_url
  • response_time、usage、request_id

任意のリサーチワークフロー（詳細調査）

複数ステップの分析と引用が必要なクエリで使用します。

研究タスクを作成 → POST /research
curl -sS -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "input": "<research question>",
    "model": "auto",
    "stream": false,
    "citation_format": "numbered"
  }'

想定されるレスポンスフィールド：

  • request_id、created_at、status（pending）、input、model、response_time
研究ステータスを取得 → GET /research/{request_id}
curl -sS -X GET "https://api.tavily.com/research/<request_id>" \
  -H "Authorization: Bearer $TAVILY_API_KEY"

想定されるレスポンスフィールド：

  • status：completed
  • content：レポートのテキストまたは構造化オブジェクト
  • sources[]：{ title, url, favicon }
ストリーミング研究（SSE）

POST の本文に "stream": true を設定し、curl で -N を指定してイベントをストリーミングします：

curl -N -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{"input":"<question>","stream":true,"model":"pro"}'

SSE イベント（ツール呼び出し、ツールの応答、コンテンツチャンク、ソース、完了）を処理します。

使用上の注意

  • 検出とコンテンツ取得には、search、extract、map、crawl を主要なエンドポイントとして使用します。
  • 後続の処理で使いやすいように、URL、タイトル、要約を含む構造化された結果を返します。
  • より幅広い情報が必要な場合を除き、保守的なパラメーター（search_depth: basic、max_results: 5）をデフォルトで使用します。
  • 結果の予測可能性を保つため、呼び出し間で一貫したリクエスト本文を再利用します。

エラー処理

  • リクエストが 401/403 を返した場合は、TAVILY_API_KEY の入力を求めるか、設定を再確認します。
  • タイムアウトが発生した場合は、max_depth／limit を下げるか、search_depth: basic を使用します。
  • レスポンスが大きすぎる場合は、max_results または chunks_per_source を減らします。

コメント

Markdown 対応