Web Research Assistant

网络研究助理MCP服务器

 ](https://pypi.org/project/web-research-assistant/)  

提供web研究和发现功能的综合模型上下文协议（MCP）服务器。 包含 13工具, 4资源，以及 5个提示 用于搜索、抓取和分析web内容，由您本地的Docker SearXNG提供支持

1. web_search --通过SearXNG跨多个引擎进行联合搜索
2. search_examples --查找代码示例、教程和文章（默认为最新内容）
3. search_images --通过Pixabay查找高质量的库存照片、插图和矢量图
4. crawl_url --使用高级爬行进行整页内容提取
5. package_info --来自npm、PyPI、crates.io、Go的详细包元数据
6. package_search --按关键字和功能发现包
7. github_repo --存储库健康指标和开发活动
8. translate_error --从stack Overflow中查找错误消息和堆栈跟踪的解决方案（自动检测CORS、fetch和web错误）
9. api_docs -自动搜索和抓取API官方文档及示例（适用于任何API-无硬编码URL）
10. extract_data --通过自动检测从网页中提取结构化数据（表、列表、字段、JSON-LD）
11. compare_tech --将技术与NPM下载、GitHub stars和方面分析（React与Vue、PostgreSQL与MongoDB等）并排比较
12. get_changelog — 新 获取带有中断更改检测的发行说明和更改日志（从版本X安全升级到Y）
13. check_service_status — 新 对超过25种服务（Stripe、AWS、GitHub、OpenAI等）进行即时健康检查——“是宕机还是只有我？”

所有工具都具有全面的错误处理、响应大小限制、使用跟踪和清晰的文档 以实现最佳的AI代理集成。

MCP资源（直接数据查找）

• package://{registry}/{name} -来自npm、PyPI、crates.io或Go模块的包信息
• github://{owner}/{repo} -存储库信息和健康指标
• status://{service} -120+项服务的服务健康状况
• changelog://{registry}/{package} -软件包发布说明和变更日志

MCP提示（可重用工作流）

• research_package -综合包评估
• debug_error -结构化错误调试及解决方案
• compare_technologies -并排技术比较
• evaluate_repository -GitHub存储库健康评估
• check_service_health -多业务状态监控

快速开始

选项1：完整的Docker设置（推荐）

一切都在Docker中运行-不需要安装Python：

./docker-start.sh

这将在容器中启动SearXNG和MCP服务器。看 了解详情。

选项2：Python+Docker SearXNG

1. 设置SearXNG （5分钟）：

   # Using Docker (recommended)
   docker run -d -p 2288:8080 searxng/searxng:latest

然后配置搜索引擎-请参阅 SEARXNG_SETUP.md 优化设置。

1. 安装MCP服务器:

   uvx web-research-assistant  # or: pip install web-research-assistant

1. 配置Claude桌面版 -添加到 claude_desktop_config.json:

   {
     "mcpServers": {
       "web-research-assistant": {
         "command": "uvx",
         "args": ["web-research-assistant"]
       }
     }
   }

1. 重新启动克劳德桌面 开始研究吧！

⚠️ 为了最佳效果：使用GitHub、Stack Overflow和其他以代码为中心的搜索引擎配置SearXNG。看 SEARXNG_SETUP.md 对于推荐的配置。

先决条件

必需的

• Python 3.10+
• 正在运行的SearXNG实例 上 http://localhost:2288

- 📖 看 SEARXNG_SETUP.md 获取完整的Docker设置指南 - ⚠️ 重要：为了获得最佳结果，请在SearXNG中启用这些搜索引擎： - GitHub，堆栈溢出，GitLab （用于代码搜索-至关重要！） - 鸭子，勇敢 （用于网络搜索） - MDN，维基百科 （用于文件编制） - Reddit、HackerNews （用于教程和讨论） - 看 SEARXNG_SETUP.md 用于完全优化的配置

可选的

• Exa API密钥 用于神经搜索- 获取API密钥 （推荐以获得更好的搜索结果）
• Pixabay API密钥 用于图像搜索- 获取免费密钥
• 剧作家浏览器 用于高级爬行（自动安装 crawl4ai-setup)

开发人员设置程序（如果从源代码运行）

uv tool install uv  # if you do not already have uv
uv sync              # creates the virtual environment
uv run crawl4ai-setup  # installs Chromium for crawl4ai

您还可以使用 pip install -r requirements.txt 如果你更喜欢pip而不是uv。

安装

选项1：使用uvx（推荐-无需安装！）

uvx web-research-assistant

这将直接从PyPI运行服务器，而无需全局安装。

选项2：使用pip安装

pip install web-research-assistant
web-research-assistant

选项3：使用uv进行安装

uv tool install web-research-assistant
web-research-assistant

默认情况下，服务器通过stdio进行通信，这使得连接到 Claude Desktop或任何其他MCP主机。

MCP客户端配置

克劳德桌面版

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

选项1：使用uvx（推荐-无需安装！）

{
  "mcpServers": {
    "web-research-assistant": {
      "command": "uvx",
      "args": ["web-research-assistant"]
    }
  }
}

选项2：使用已安装的软件包

{
  "mcpServers": {
    "web-research-assistant": {
      "command": "web-research-assistant"
    }
  }
}

开源代码

增添 ~/.config/opencode/opencode.json:

使用uvx（推荐）

{
  "mcp": {
    "web-research-assistant": {
      "type": "local",
      "command": ["uvx", "web-research-assistant"],
      "enabled": true
    }
  }
}

使用已安装的软件包

{
  "mcp": {
    "web-research-assistant": {
      "type": "local",
      "command": ["web-research-assistant"],
      "enabled": true
    }
  }
}

开发（从源代码运行）

对于Claude Desktop：

{
  "mcpServers": {
    "web-research-assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/web-research-assistant",
        "run",
        "web-research-assistant"
      ]
    }
  }
}

对于OpenCode：

{
  "mcp": {
    "web-research-assistant": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "/ABSOLUTE/PATH/TO/web-research-assistant",
        "run",
        "web-research-assistant"
      ],
      "enabled": true
    }
  }
}

重新启动MCP客户端 之后。MCP工具将立即可用。

工具行为

结果会自动修剪（默认为8KB），以便它们在MCP中保持良好状态 响应期望。如果发生截断，文本将以一条注释结束，提醒 更多细节可应要求提供。

资源

MCP资源通过URI模板提供直接的数据访问，非常适合在没有工具调用的情况下进行快速查找。

提示

MCP Prompts是可重用的消息模板，可指导AI助手完成常见的工作流程。

配置

环境变量允许您在不接触代码的情况下调整服务器：

发展

代码库有意进行模块化和组织：

web-research-assistant/
├── src/searxng_mcp/     # Source code
│   ├── config.py        # Configuration and environment
│   ├── search.py        # SearXNG integration
│   ├── exa.py           # Exa AI neural search client
│   ├── crawler.py       # Crawl4AI wrapper
│   ├── images.py        # Pixabay client
│   ├── registry.py      # Package registries (npm, PyPI, crates, Go)
│   ├── github.py        # GitHub API client
│   ├── errors.py        # Error parser (language/framework detection)
│   ├── api_docs.py      # API docs discovery (NO hardcoded URLs)
│   ├── tracking.py      # Usage analytics
│   └── server.py        # MCP server + 13 tools
├── docs/                # Documentation (27 files)
└── [config files]

每个模块少于400行，使代码库易于理解和扩展。

使用情况分析

所有工具都会自动跟踪使用指标，包括：

• 工具调用次数和成功率
• 响应时间和性能趋势
• 常见用例模式（通过 reasoning 参数）
• 错误频率和类型

分析数据存储在 ~/.config/web-research-assistant/usage.json 并且可以进行分析 优化工具使用并识别模式。每个工具都需要一个 reasoning 参数 这有助于对使用工具的原因进行分类，从而实现更好的分析和见解。

注： 截至最新更新 reasoning 参数为 必需的 适用于所有工具（以前默认情况下为可选）。这确保了有意义的分析数据收集。

文档

综合文档可在 docs/ 目录：

• 项目状态 -当前状态、指标、路线图
• API文档实现 -新工具文档
• 错误翻译器设计 -错误翻译器详细信息
• 工具创意排名 -优先次序和进展
• SearXNG配置 -推荐设置
• 快速入门示例 -使用示例

请参阅 文档自述 完整的索引。