星战科技xingzhan.cloud
返回市场
塔维利-MCP服务器

塔维利-MCP服务器

作者：Manoj16342 星标更新：2025-08-12
安装使用来源：spider==github.com

项目介绍

Tavily MCP Server for Klavis AI

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

功能

🔍 网络搜索 (tavily_search)

在互联网上搜索当前信息和可靠的来源，具有可配置的深度和过滤选项。

功能：

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

📄 内容提取 (tavily_extract)

从一个或多个URL中提取主要内容，可选地提取图像。

功能：

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

🕷️ 网络爬虫 (tavily_crawl)

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

功能：

  • 从单个起始URL开始的基于图的遍历
  • 可配置的深度（1-3级）和广度限制
  • 带有外部链接控制的域感知爬取
  • 路径和域过滤（包含/排除）
  • 自然语言指令引导的爬取
  • 多种输出格式（markdown/text）
  • 基于类别的过滤

安装

先决条件

  • Python 3.10 或更高版本
  • Tavily 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

配置

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

变量默认值描述
TAVILY_API_KEY必需您的Tavily API密钥
TAVILY_BASE_URLhttps://api.tavily.comTavily API基础URL
TAVILY_TIMEOUT_S20请求超时时间（秒）
TAVILY_CONNECT_TIMEOUT_S5连接超时时间（秒）
TAVILY_MAX_RETRIES2-3最大重试次数
TAVILY_CONCURRENCY8最大并发请求
TAVILY_CACHE_TTL_S120缓存TTL（秒）
TTAVILY_MAX_RESULTS_CAP10最大搜索结果
TAVILY_CRAWL_MAX_PAGES50最大爬取页面数
LOG_LEVELINFO日志级别

使用

运行服务器

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

mcp dev server.py

服务器通过标准I/O运行，并与MCP客户端兼容。

工具描述

tavily_search

搜索互联网上的查询并返回总结结果。当您需要当前信息或可靠来源时使用。

参数：

  • query (str): 搜索查询文本
  • search_depth (str): "basic" 或 "advanced"
  • 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开始爬取，直到最大深度/广度/限制，返回提取的页面。用于站点探索和内容收集。

参数：

  • 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): "basic" 或 "advanced"
  • format (str): "markdown" 或 "text"
  • include_favicon (bool): 包括favicon URL

返回值： CrawlResponse，包括爬取的页面和元数据。

错误处理

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

  • ERR_UNAUTHORIZED: 检查TAVILY_API_KEY
  • ERR_RATE_LIMIT: 达到速率限制，请稍后再试
  • ERR_UPSTREAM_<状态>: 上游API错误带上下文
  • ERR_BAD_REQUEST: 参数无效
  • ERR_PAYMENT_REQUIRED: 计费或配额问题

架构

项目结构

tavily/
├── app.py                 # FastMCP应用程序设置
├── server.py             # 服务器入口点
├── pyproject.toml        # 依赖项和配置
├── tools/                # 核心功能
│   ├── client.py         # HTTP客户端配置
│   ├── search.py         # 网络搜索实现
│   ├── extract.py        # 内容提取
│   ├── crawl.py          # 网络爬虫
│   ├── types.py          # Pydantic数据模型
│   └── errors.py         # 错误处理
└── mcp_venv/             # 虚拟环境

关键组件

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. 打开拉取请求

支持

对于以下相关的问题：

  • Tavily API: 联系Tavily支持
  • MCP集成: 查看MCP文档
  • Klavis AI: 联系Klavis AI支持
  • 此项目: 在GitHub上打开一个问题

许可证

此项目根据MIT许可证授权 - 详情见LICENSE文件。