网络搜索与内容提取服务器

Klavis AI的Tavily MCP服务器

一种模型上下文协议（MCP）服务器，使用Tavily API提供网络搜索、内容提取和网络抓取功能。该服务器旨在作为自定义MCP服务器与Klavis AI无缝集成。

特性

🔍 网络搜索(tavily_search)

使用可配置的深度和过滤选项在网络上搜索当前信息和信誉良好的来源。

能力：

• 基本和高级搜索深度
• 可配置的结果限制
• 可选的合成答案
• 新鲜度过滤
• 基于主题的过滤
• 智能缓存提高性能
• 使用指数回退重试逻辑

📄 内容提取(tavily_extract)

使用可选的图像提取从一个或多个URL中提取主要内容。

能力：

• 同时从多个URL提取内容
• 可选图像提取
• 响应规范化和缓存
• 稳健的错误处理

🕷️ 网络爬行(tavily_crawl)

以可配置的深度和广度抓取网站，以进行全面的内容收集。

能力：

• 从单一起始URL进行基于图的遍历
• 可配置的深度（1-3级）和宽度限制
• 具有外部链接控制的域感知爬行
• 路径和域过滤（包括/排除）
• 引导爬行的自然语言指令
• 多种输出格式（标记/文本）
• 基于类别的过滤

安装

先决条件

• Python 3.10或更高版本
• Tavilly API密钥

设置

1. 克隆并导航到项目：

   复制

   cd tavily
   

2. 安装依赖项：

   选项A：使用pip进行可编辑安装（推荐）：

   复制

   pip install -e .
   

   选项B：使用uv（现代Python包管理器）：

   复制

   uv sync
   

3. 设置环境变量： 创建一个 .env 项目根目录中的文件：

   复制

   TAVILY_API_KEY=your_tavily_api_key_here
   

配置

服务器使用环境变量进行配置：

用法

运行服务器

使用MCP dev命令启动MCP服务器：

mcp dev server.py

服务器在stdio上运行，与MCP客户端兼容。

工具说明

tavily_search

在网络上搜索查询并返回汇总结果。当您需要最新信息或可靠来源时使用。

参数：

• query （str）：搜索查询文本
• search_depth （str）：“基本”或“高级”
• max_results （int）：1-10个结果
• include_answer （bool）：包含合成答案
• include_raw_content （bool）：包含原始内容片段
• days （int，可选）：新鲜度过滤器（0-365）
• topic （str，可选）：主题焦点

退货： 带有答案、结果、响应时间和自动参数的SearchResponse。

tavily_extract

从一个或多个URL中提取主要内容。当您已经知道URL并且需要清理文本和可选图像时使用。

参数：

• urls （str或List[str]）：要从中提取的URL
• include_images （bool）：在结果中包含图像

退货： ExtractResponse，包含提取的内容和可选图像。

tavily_crawl

从单一起始URL爬取到max_depth/max_width/limit，返回提取的页面。用于网站探索和内容收集。

参数：

• url （str）：开始爬网的根URL
• max_depth （int）：爬行深度（1-3）
• max_breadth （int）：每级链接数（≥1）
• limit （int）：最大页数（1-500）
• instructions （str，可选）：自然语言指导
• select_paths （List[str]，可选）：包括路径模式
• select_domains （List[str]，可选）：包括域模式
• exclude_paths （List[str]，可选）：排除路径模式
• exclude_domains （List[str]，可选）：排除域模式
• allow_external （bool）：包括外部域
• include_images （bool）：在结果中包含图像
• categories （List[str]，可选）：内容类别
• extract_depth （str）：“基本”或“高级”
• format （str）：“markdown”或“text”
• include_favicon （bool）：包含favicon URL

退货： 带有已爬网页面和元数据的CrawlResponse。

错误处理

服务器为不同场景提供标准化的错误消息：

• ERR_UNAUTHORIZED：检查TAVILY_API_KEY
• ERR_RATE_LIMIT：速率受限，稍后重试
• ERR_UPSTREAM_<status>：带有上下文的上游API错误
• ERR_BAD_REQUEST：无效参数
• ERR_PAYMENT_REQUIRED：计费或配额问题

建筑

项目结构

tavily/
├── app.py                 # FastMCP application setup
├── server.py             # Server entry point
├── pyproject.toml        # Dependencies and configuration
├── tools/                # Core functionality
│   ├── client.py         # HTTP client configuration
│   ├── search.py         # Web search implementation
│   ├── extract.py        # Content extraction
│   ├── crawl.py          # Web crawling
│   ├── types.py          # Pydantic data models
│   └── errors.py         # Error handling
└── mcp_venv/             # Virtual environment

关键组件

HTTP客户端(tools/client.py)

• 具有一致配置的集中式客户端工厂
• 通过TAVILY_API_KEY进行身份验证
• 可配置的超时和重试逻辑
• 请求ID跟踪以进行调试

数据模型(tools/types.py)

• 用于类型安全的Pydantic模型
• 灵活的字段映射，实现API兼容性
• 响应验证和规范化

错误处理(tools/errors.py)

• HTTP状态代码的标准化错误消息
• AI友好的调试错误提示
• 上下文的响应正文片段

依赖项

• mcp[cli]>=1.2.0：MCP Python SDK
• httpx>=0.27.0：HTTP客户端
• pydantic>=2.6.0：数据验证
• python-dotenv>=1.0.1：环境变量加载
• tenacity>=8.2.3：重试逻辑

发展

运行测试

pytest

代码质量

该项目遵循Python最佳实践：

• 全程键入提示
• 全面的错误处理
• 调试日志
• 缓存以提高性能
• 速率限制和并发控制

许可证

该项目是Klavis AI生态系统的一部分，遵循相同的许可条款。

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

支持

关于以下问题：

• 美味API：联系Tavily支持
• MCP集成：检查MCP文件
• Clavis AI：联系Klavis AI支持
• 本项目：在GitHub上打开一个问题

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。