MCP DuckDuckGo 搜索插件

DuckDuckGo 的模型上下文协议 (MCP) 搜索插件，兼容 Claude Code。提供网页搜索功能，并具备高级导航和内容探索功能。

描述

该项目实现了一个模型上下文协议 (MCP) 服务器，该服务器使用 DuckDuckGo 提供网页搜索功能。该插件旨在与 Claude Code 或任何其他支持 MCP 的客户端无缝协作，不仅提供基本的搜索功能，还提供高级导航和结果探索功能。

特征

• 网络搜索工具：使用 DuckDuckGo 执行网络搜索
• 详细结果：获取有关特定搜索结果的详细信息
• 相关搜索：根据原始搜索发现相关的搜索查询
• 分页支持：浏览多页搜索结果
• 域名提取：查看每个搜索结果的域名信息
• 高级过滤：按站点和时间段过滤结果
• 增强内容提取：从网页中提取丰富的内容，包括元数据、结构和片段
• 基本网络蜘蛛：跟踪搜索结果中的链接以探索相关内容（可配置深度）
• 元数据提取：提取标题、作者、关键词、出版日期等
• 社交媒体检测：从网页中识别并提取社交媒体链接
• 内容结构分析：提取标题和章节以了解网页结构
• 搜索文档：访问有关搜索功能的综合文档
• 搜索助手：获取帮助制定有效的搜索查询
• 参数化资源：检索特定查询的格式化搜索结果

要求

• Python 3.9 或更高版本
• pip（Python 包管理器）
• pyproject.toml中列出的 Python 包

安装

来自 PyPI

注意：此软件包尚未发布到 PyPI。请从下方源代码安装。

将来，一旦发布，您将能够使用以下方式安装：

来自源

1. 克隆此存储库：
   git clone https://github.com/gianlucamazza/mcp-duckduckgo.git cd mcp-duckduckgo
2. 以开发模式安装包：
   pip install -e .
   或者使用提供的脚本：
   ./scripts/install_dev.sh
   或者使用 Make：
   make install

用法

手动启动服务器

要启动 MCP 服务器：

或者使用自定义参数：

或者使用提供的脚本进行开发：

或者使用 Make：

与 Claude 代码一起使用

1. 按照上述说明从源安装包。
2. 配置 Claude Code 以使用插件：
   claude mcp add duckduckgo-search -- mcp-duckduckgo
3. 对于全局配置（所有项目可用）：
   claude mcp add duckduckgo-search --scope global -- mcp-duckduckgo
4. 启动克劳德代码：
   claude
5. 现在您可以在 Claude Code 中使用 DuckDuckGo 搜索功能。

可用端点

该插件提供以下端点：

工具： duckduckgo_web_search

使用 DuckDuckGo 执行网络搜索，参数如下：

• query （必填）：搜索查询（最多 400 个字符，50 个字）
• count （可选，默认值：10）：每页结果数（1-20）
• page （可选，默认值：1）：分页的页码
• site （可选）：将结果限制在特定网站（例如“example.com”）
• time_period （可选）：按时间段过滤结果（‘天’、‘周’、‘月’、‘年’）

Claude Code 中的示例用法：

工具： duckduckgo_get_details

检索有关特定搜索结果的详细信息：

• url （必填）：获取结果详细信息的 URL

Claude Code 中的示例用法：

工具： duckduckgo_related_searches

根据原始查询建议相关的搜索查询：

• query （必填）：原始搜索查询（最多 400 个字符）
• count （可选，默认值：5）：返回的相关搜索数量（1-10）

Claude Code 中的示例用法：

资源： docs://search

提供有关搜索功能的全面文档。

Claude Code 中的示例用法：

提示： search_assistant

帮助制定有效的搜索查询。

Claude Code 中的示例用法：

资源： search://{query}

检索特定查询的格式化搜索结果。

Claude Code 中的示例用法：

使用导航功能

该插件提供了多种功能来帮助导航和探索搜索结果：

分页

要浏览多页搜索结果：

筛选结果

要按特定站点过滤结果：

按时间段过滤结果：

探索结果详情

要获取有关特定搜索结果的更多信息：

查找相关搜索

要发现相关的搜索查询：

这些导航功能可以与 Claude 的自然语言能力相结合，打造强大的搜索和探索体验。例如：

实施说明

此实现使用 DuckDuckGo 的公共 Web 界面，并解析 HTML 响应以提取结果。此方法仅用于演示，因为 DuckDuckGo 不提供官方搜索 API。在生产环境中，建议使用带有官方 API 的搜索服务。

增强内容提取

DuckDuckGo 插件包含超越简单搜索结果的高级内容提取功能：

内容提取功能

• 完整网页分析：从搜索结果 URL 中提取并解析 HTML 内容
• 智能内容定位：从不同类型的网站中识别并提取主要内容区域
• 丰富的元数据提取：提取标题、描述、作者、关键词和出版日期
• 图像检测：识别并提取网页中的主要图像和媒体
• 社交媒体整合：检测并提取社交媒体资料的链接
• 内容结构分析：提取标题和章节以了解网页组织
• 官方来源检测：根据域名和内容信号识别来源是否为官方

网络爬取功能

该插件包括基本的网络蜘蛛功能：

• 可配置深度：跟随距离原始 URL 0 到 3 级深度的链接
• 链接限制：控制每页可关注的最大链接数（1-5）
• 域限制：仅跟踪同一域内的链接的选项
• 相关内容发现：查找并分析与原始搜索相关的内容

使用增强内容提取

要使用增强的内容提取功能：

要控制蜘蛛行为：

发展

该项目在scripts目录中包含几个实用程序脚本以帮助开发：

• install_dev.sh ：设置开发环境
• run.sh ：使用开发设置运行 MCP 服务器
• test.sh ：运行测试并报告覆盖率
• lint.sh ：运行 linting 和代码格式化
• publish.sh ：构建包并将其发布到 PyPI

为了方便起见，还提供了具有以下目标的 Makefile：

测试

该项目包含一个涵盖所有主要功能的全面测试套件。测试位于tests/目录中。

安装测试依赖项

在运行测试之前，安装测试依赖项：

运行测试

您可以使用以下方式运行所有测试：

要运行带有覆盖率报告的测试：

要运行特定的测试文件：

要运行具有详细输出的测试：

或者使用提供的脚本：

或者使用 Make：

测试结构

测试套件的组织如下：

• conftest.py - 用于测试的共享装置和配置
• test_models.py - 数据模型测试
• test_search.py - 测试搜索功能
• test_tools.py - MCP 工具测试
• test_resources.py - MCP 资源测试
• test_integration.py - 端到端集成测试
• test_server.py - 服务器生命周期测试

有关测试的更多详细信息，请参阅tests/README.md文件。

代码格式化和 Linting

或者使用提供的脚本：

或者使用 Make：

发布到 PyPI

如果您想将包发布到 PyPI：

1. 更新pyproject.toml中的版本
2. 确保您拥有必要的凭证和工具：
   pip install build twine
3. 构建并发布：
   python -m build twine upload dist/*

或者使用提供的脚本（如果可用）：

或者使用 Make：

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

麻省理工学院

存储库

https://github.com/gianlucamazza/mcp-duckduckgo