MCP DuckDuckGo 搜索插件

一个用于模型上下文协议 (MCP) 的 DuckDuckGo 搜索插件，兼容 Claude Code。提供具有高级导航和内容探索功能的网络搜索功能。

描述

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

特性

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

要求

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

安装

从 PyPI

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

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

pip install mcp-duckduckgo

从源代码

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 服务器：

mcp-duckduckgo

或者使用自定义参数：

mcp-duckduckgo --host 127.0.0.1 --port 8000

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

./scripts/run.sh

或者使用 Make：

make run

与 Claude Code 一起使用

1. 从源代码安装软件包，如上所述。

2. 配置 Claude Code 以使用该插件：

   claude mcp add duckduckgo-search -- mcp-duckduckgo
   

3. 对于全局配置（在所有项目中可用）：

   claude mcp add duckduckgo-search --scope global -- mcp-duckduckgo
   

4. 启动 Claude Code：

   claude
   

5. 现在您可以在 Claude Code 中使用 DuckDuckGo 搜索功能。

可用端点

该插件提供以下端点：

工具: duckduckgo_web_search

使用 DuckDuckGo 执行网络搜索，具有以下参数：

• query (必需): 搜索查询（最多 400 个字符，50 个单词）
• count (可选, 默认: 10): 每页结果数 (1-20)
• page (可选, 默认: 1): 分页的页码
• site (可选): 将结果限制为特定站点（例如，“example.com”）
• time_period (可选): 按时间段过滤结果（“day”、“week”、“month”、“year”）

在 Claude Code 中的用法示例：

Search for "artificial intelligence latest developments"

工具: duckduckgo_get_details

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

• url (必需): 要获取详细信息的 URL

在 Claude Code 中的用法示例：

Get details for "https://example.com/article"

工具: duckduckgo_related_searches

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

• query (必需): 原始搜索查询（最多 400 个字符）
• count (可选, 默认: 5): 要返回的相关搜索的数量 (1-10)

在 Claude Code 中的用法示例：

Find related searches for "renewable energy"

资源: docs://search

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

在 Claude Code 中的用法示例：

Show me the documentation for the DuckDuckGo search

提示: search_assistant

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

在 Claude Code 中的用法示例：

Help me formulate a search query about climate change solutions

资源: search://{query}

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

在 Claude Code 中的用法示例：

Get search results for "quantum computing breakthroughs"

使用导航功能

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

分页

要浏览多个搜索结果页面：

Search for "climate change solutions" with 5 results per page, page 2

过滤结果

要按特定站点过滤结果：

Search for "machine learning tutorials" on "tensorflow.org"

要按时间段过滤结果：

Search for "latest news" from the past week

探索结果详情

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

Get details for "https://example.com/article-found-in-search"

查找相关搜索

要发现相关搜索查询：

Find related searches for "electric vehicles"

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

Search for "python machine learning libraries", then get details on the top result, and finally show me related search terms

实现说明

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

增强的内容提取

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

内容提取功能

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

网络爬虫功能

该插件包括基本的网络爬虫功能：

• 可配置的深度: 从原始 URL 跟踪 0 到 3 级深度的链接
• 链接限制: 控制每页要跟踪的最大链接数 (1-5)
• 域名限制: 可选择仅跟踪同一域名内的链接
• 相关内容发现: 查找和分析与原始搜索相关的内容

使用增强的内容提取

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

Get details for "https://example.com/article" with spider depth 1

要控制爬虫行为：

Get details for "https://example.com/article" with spider depth 2, max links 3, same domain only

开发

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

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

为方便起见，还提供了一个 Makefile，其中包含以下目标：

make install  # 以开发模式安装软件包
make test     # 运行测试并生成覆盖率报告
make lint     # 运行 linting 和代码格式化
make run      # 运行 MCP 服务器
make publish  # 构建并将软件包发布到 PyPI
make clean    # 清理构建工件
make all      # 运行 install、lint 和 test（默认）
make help     # 显示帮助消息

测试

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

安装测试依赖项

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

pip install -e ".[test]"

运行测试

您可以使用以下命令运行所有测试：

pytest

要运行测试并生成覆盖率报告：

pytest --cov=mcp_duckduckgo

要运行特定的测试文件：

pytest tests/test_models.py

要运行测试并显示详细输出：

pytest -v

或者使用提供的脚本：

./scripts/test.sh

或者使用 Make：

make test

测试结构

测试套件的组织方式如下：

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

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

代码格式化和 Linting

black mcp_duckduckgo
isort mcp_duckduckgo
mypy mcp_duckduckgo

或者使用提供的脚本：

./scripts/lint.sh

或者使用 Make：

make lint

发布到 PyPI

如果要将软件包发布到 PyPI：

1. 更新 pyproject.toml 中的版本
2. 确保您拥有必要的凭据和工具：

   pip install build twine
   

3. 构建和发布：

   python -m build
   twine upload dist/*
   

或者，如果可用，请使用提供的脚本：

./scripts/publish.sh

或者使用 Make：

make publish

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT

仓库

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