mcpField
T
tavily

tavily

github.com/intellectronica生产力298628 次安装27 周前更新
代码仓库

关于 tavily

Tavily 是一项通过 curl 调用 Tavily REST API 的技能，可用于网页搜索、页面提取、站点 URL 发现与抓取，并支持可选研究流程。它为 LLM 工作流和调查提供结构化结果。

主要功能

  1. 01可配置结果的网页搜索
  2. 02从 URL 提取内容
  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

用途

提供基于 curl 的接口，用于调用 Tavily REST API 进行网页搜索、内容提取、网站映射、爬取和可选的研究。返回适用于大模型工作流和多步骤调查的结构化结果。

适用场景

  • 任务需要实时网页信息、网站内容提取、映射或爬取时使用。
  • 需要网页搜索但没有内置工具可用时，或 Tavily 的大模型友好型输出（摘要、分块、来源、引文）有帮助时使用。
  • 任务需要通过 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（如有请求）、results[]（包含 title、url、content、score、raw_content（可选）、favicon（可选））
  • 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：布尔值

预期响应字段：

  • results[]（包含 url、raw_content、images、favicon）
  • 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、results[]（URL 列表）、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：布尔值

预期响应字段：

  • base_url、results[]（包含 url、raw_content、favicon）
  • 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