mcp-tavily

######################################################## ### 弃用通知 我在2025年3月初构建了这个MCP服务器，当时MCP协议还很新颖，聊天机器人中没有一致的搜索方式，领先于其他实现。 从那时起，Tavily的优秀团队发布了他们的官方[Tavily MCP服务器](/faq/faq#how-does-tavily-ensure-the-accuracy-of-its-information)，该服务器维护良好，与他们最新的功能同步。因此，我现在废弃这个服务器，以支持他们的服务器。 ######################################################## # Tavily MCP 服务器 一个基于模型上下文协议（MCP）的服务器，提供由Tavily搜索API支持的AI驱动的网络搜索功能。该服务器使大型语言模型（LLM）能够执行复杂的网络搜索，直接获取问题的答案，并搜索最近的新闻文章，提取相关内容。 ## 功能 ### 可用工具 - `tavily_web_search` - 执行全面网络搜索，提取AI驱动的内容。 - `query`（字符串，必填）：搜索查询 - `max_results`（整数，可选）：返回结果的最大数量（默认值：5，最大值：20） - `search_depth`（字符串，可选）："basic"或"advanced"搜索深度（默认值："basic"） - `include_domains`（列表或字符串，可选）：特定域名列表，仅包含在结果中 - `exclude_domains`（列表或字符串，可选）：域名列表，从结果中排除 - `tavily_answer_search` - 执行网络搜索，生成直接答案，并提供支持证据。 - `query`（字符串，必填）：搜索查询 - `max_results`（整数，可选）：返回结果的最大数量（默认值：5，最大值：20） - `search_depth`（字符串，可选）："basic"或"advanced"搜索深度（默认值："advanced"） - `include_domains`（列表或字符串，可选）：特定域名列表，仅包含在结果中 - `exclude_domains`（列表或字符串，可选）：域名列表，从结果中排除 - `tavily_news_search` - 搜索最近的新闻文章，附带发布时间。 - `query`（字符串，必填）：搜索查询 - `max_results`（整数，可选）：返回结果的最大数量（默认值：5，最大值：20） - `days`（整数，可选）：搜索范围（默认值：3） - `include_domains`（列表或字符串，可选）：特定域名列表，仅包含在结果中 - `exclude_domains`（列表或字符串，可选）：域名列表，从结果中排除 ### 提示 服务器还为每种搜索类型提供提示模板： - **tavily_web_search** - 使用Tavily的AI驱动搜索引擎搜索网络 - **tavily_answer_search** - 搜索网络，获取AI生成的答案和支持证据 - **tavily_news_search** - 使用Tavily的新闻搜索功能搜索最近的新闻文章 ## 先决条件 - Python 3.11 或更高版本 - Tavily API 密钥（从[Tavily官网](https://tavily.com)获取） - `uv` Python 包管理器（推荐） ## 安装 ### 选项1：使用pip或uv ```bash # 使用pip pip install mcp-tavily # 或使用uv（推荐） uv add mcp-tavily ``` 您应该会看到类似的输出： ``` Resolved packages: mcp-tavily, mcp, pydantic, python-dotenv, tavily-python [...] Successfully installed mcp-tavily-0.1.4 mcp-1.0.0 [...] ``` ### 选项2：从源码安装 ```bash # 克隆仓库 git clone https://github.com/RamXX/mcp-tavily.git cd mcp-tavily # 创建虚拟环境（可选但推荐） python -m venv .venv source .venv/bin/activate # 在Windows上：.venv\Scripts\activate # 安装依赖并构建 uv sync # 或：pip install -r requirements.txt uv build # 或：pip install -e . # 安装测试依赖： uv sync --dev # 或：pip install -r requirements-dev.txt ``` 在安装过程中，您应该会看到软件包正在构建并安装其依赖项。 ### 在VS Code中使用 对于快速安装，请使用以下一键安装按钮： [](https://insiders.vscode.dev/redirect/mcp/install?name=tavily&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Tavily%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-tavily%22%5D%2C%22env%22%3A%7B%22TAVILY_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=tavily&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Tavily%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-tavily%22%5D%2C%22env%22%3A%7B%22TAVILY_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&quality=insiders) 对于手动安装，请在VS Code的用户设置（JSON）文件中添加以下JSON块。您可以通过按`Ctrl + Shift + P`并输入`Preferences: Open User Settings (JSON)`来完成此操作。 或者，您可以将其添加到工作区中的`.vscode/mcp.json`文件中。这将允许您与其他人共享配置。 > 注意，`.vscode/mcp.json`文件中不需要`mcp`键。 ```json { "mcp": { "inputs": [ { "type": "promptString", "id": "apiKey", "description": "Tavily API 密钥", "password": true } ], "servers": { "tavily": { "command": "uvx", "args": ["mcp-tavily"], "env": { "TAVILY_API_KEY": "${input:apiKey}" } } } } } ``` ## 配置 ### API密钥设置 服务器需要一个Tavily API密钥，可以通过以下三种方式提供： 1. 通过项目目录中的`.env`文件： ``` TAVILY_API_KEY=your_api_key_here ``` 2. 作为环境变量： ```bash export TAVILY_API_KEY=your_api_key_here ``` 3. 作为命令行参数： ```bash python -m mcp_server_tavily --api-key=your_api_key_here ``` ### 为Claude.app配置 将以下内容添加到您的Claude设置中： ```json "mcpServers": { "tavily": { "command": "python", "args": ["-m", "mcp_server_tavily"] }, "env": { "TAVILY_API_KEY": "your_api_key_here" } } ``` 如果您遇到问题，可能需要指定Python解释器的完整路径。运行`which python`以找到确切的路径。 ## 使用示例 对于常规网络搜索： ``` 请告诉我有关Anthropic新发布的MCP协议的信息 ``` 要生成带有域名过滤的报告： ``` 请告诉我关于红杉树的信息。请使用Markdown语法中的MLA格式，并包含引文中的URL。排除维基百科来源。 ``` 要使用答案搜索模式获取直接答案： ``` 我想要一个有具体答案和当前网络来源支持的答案：红杉树的平均寿命是多少？ ``` 对于新闻搜索： ``` 给我过去5天内的前10条与AI相关的新闻 ``` ## 测试 该项目包含一个全面的测试套件，具有自动化的依赖项兼容性测试。 ### 运行测试 1. 安装测试依赖项： ```bash source .venv/bin/activate # 如果使用虚拟环境 uv sync --dev # 或：pip install -r requirements-dev.txt ``` 2. 运行标准测试套件： ```bash ./tests/run_tests.sh # 或使用Make make test ``` ### 依赖项兼容性测试 为了确保项目与最新的依赖项版本一起工作，请使用以下命令： ```bash # 使用Make测试最新依赖项 make test-deps # 完整的兼容性测试，带有详细输出 make test-compatibility # 或使用独立脚本 ./scripts/test-compatibility.sh ``` 这些命令将： - 将所有依赖项更新到其最新版本 - 运行完整的测试套件并提供覆盖率 - 报告任何兼容性问题 - 显示版本变更以确保透明度 ### 自动测试 该项目通过GitHub Actions包含自动依赖项兼容性测试： - **每周测试**：每周一凌晨8点UTC运行 - **多Python支持**：针对Python 3.11、3.12和3.13进行测试 - **问题创建**：在测试失败时自动创建GitHub问题 - **手动触发**：可以从GitHub Actions选项卡手动触发 ### 理解测试结果 **当测试通过时**：您的项目与最新的依赖项版本兼容。您可以安全地更新您的需求文件。 **当测试失败时**：查看测试输出以识别破坏性更改，更新代码以处理API更改，更新测试（如果需要），或考虑固定有问题的依赖项版本。 ### 测试输出示例 您应该会看到类似的输出： ``` ======================================================= test session starts ======================================================== platform darwin -- Python 3.13.3, pytest-8.3.5, pluggy-1.5.0 rootdir: /Users/ramirosalas/workspace/mcp-tavily configfile: pyproject.toml plugins: cov-6.0.0, asyncio-0.25.3, anyio-4.8.0, mock-3.14.0 asyncio: mode=Mode.STRICT, asyncio_default_fixture_loop_scope=function collected 50 items tests/test_docker.py .. [ 4%] tests/test_integration.py ..... [ 14%] tests/test_models.py ................. [ 48%] tests/test_server_api.py ..................... [ 90%] tests/test_utils.py ..... [100%] ---------- coverage: platform darwin, python 3.13.3-final-0 ---------- Name Stmts Miss Cover ------------------------------------------------------- src/mcp_server_tavily/__init__.py 16 2 88% src/mcp_server_tavily/__main__.py 2 2 0% src/mcp_server_tavily/server.py 149 16 89% ------------------------------------------------------- TOTAL 167 20 88% ``` 测试套件包括数据模型、实用函数、集成测试、错误处理和参数验证的测试。它专注于验证所有API功能是否正常工作，包括域名过滤和各种输入格式。 ## 发布管理 该项目包含用于构建和发布最新依赖项版本的工具： ### 使用最新依赖项构建 ```bash # 使用最新依赖项版本构建软件包 make build-latest # 完整的发布工作流程：测试、构建和检查最新依赖项 make release-all # 准备具有版本管理的发布 ./scripts/prepare-release.sh [new_version] ``` ### 发布工作流程 **推荐的最新依赖项发布方法：** 1. **完成发布准备**：`make release-all` 2. **上传时不降级**：`make upload-latest` **替代的分步方法：** 1. **测试最新依赖项**：`make test-compatibility` 2. **构建发布版本**：`make release-build` 3. **上传时不重建**：`make upload-latest` **一键发布和发布：** ```bash make release-publish ``` **重要**：在上传过程中使用`make upload-latest`而不是`make upload`，以防止依赖项降级。`upload-latest`命令使用现有的分发文件，而不重新安装依赖项。 发布命令确保您的软件包使用最新的兼容依赖项版本构建和测试，防止传统构建链中可能出现的降级。 ## Docker 构建Docker镜像： ```bash make docker-build ``` 或者，直接使用Docker构建： ```bash docker build -t mcp_tavily . ``` 运行一个分离的Docker容器（默认名称`mcp_tavily_container`，端口8000 → 8000）： ```bash make docker-run ``` 或手动： ```bash docker run -d --name mcp_tavily_container \ -e TAVILY_API_KEY=your_api_key_here \ -p 8000:8000 mcp_tavily ``` 停止并删除容器： ```bash make docker-stop ``` 跟踪容器日志： ```bash make docker-logs ``` 您可以覆盖默认值，设置环境变量： - DOCKER_IMAGE：镜像名称（默认`mcp_tavily`） - DOCKER_CONTAINER：容器名称（默认`mcp_tavily_container`） - HOST_PORT：主机端口绑定（默认`8000`） - CONTAINER_PORT：容器端口（默认`8000`） ## 调试 您可以使用MCP检查器调试服务器： ```bash # 使用npx npx @modelcontextprotocol/inspector python -m mcp_server_tavily # 用于开发 cd path/to/mcp-tavily npx @modelcontextprotocol/inspector python -m mcp_server_tavily ``` ## 贡献 我们欢迎为mcp-tavily做出贡献！以下是您可以帮助的方式： 1. 分叉仓库 2. 创建一个功能分支（`git checkout -b feature/amazing-feature`） 3. 进行更改 4. 运行测试以确保它们通过 5. 提交更改（`git commit -m 'Add amazing feature'`） 6. 推送到分支（`git push origin feature/amazing-feature`） 7. 打开拉取请求 有关其他MCP服务器和实现模式的示例，请参阅： https://github.com/modelcontextprotocol/servers ## 许可证 mcp-tavily在MIT许可证下许可。有关详细信息，请参阅[LICENSE](LICENSE)文件。