MCP Deep Web Research Server (v0.3.0)

MCP Deep Web Research Server（v0.3.0）

用于高级网络研究的模型上下文协议（MCP）服务。

最新变更

• 新增 visit_page 工具，可直接提取网页内容
• 优化性能，使其能够在 MCP 超时限制内运行
  • 降低默认的 maxDepth 和 maxBranching 参数
  • 提高页面加载效率
  • 在整个过程中增加超时检查
  • 增强超时错误处理

本项目是 mzxrai 的 mcp-webresearch 分支，新增了深度网络研究功能。感谢原作者奠定了坚实基础。

通过智能搜索排队、增强的内容提取和深度研究功能，为 Claude 引入实时信息。

功能

• 智能搜索队列系统

  • 批量搜索操作并进行速率限制
  • 队列管理和进度跟踪
  • 错误恢复和自动重试
  • 搜索结果去重

• 增强的内容提取

  • 基于 TF-IDF 的相关性评分
  • 关键词邻近度分析
  • 内容分区加权
  • 可读性评分
  • 改进的 HTML 结构解析
  • 结构化数据提取
  • 更出色的内容清理和格式设置

• 核心功能

  • Google 搜索集成
  • 网页内容提取
  • 研究会话跟踪
  • 改进格式后的 Markdown 转换

先决条件

• Node.js >= 18（包含 npm 和 npx）
• Claude 桌面应用

安装

全局安装（推荐）

# Install globally using npm
npm install -g mcp-deepwebresearch

# Or using yarn
yarn global add mcp-deepwebresearch

# Or using pnpm
pnpm add -g mcp-deepwebresearch

本地项目安装

# Using npm
npm install mcp-deepwebresearch

# Using yarn
yarn add mcp-deepwebresearch

# Using pnpm
pnpm add mcp-deepwebresearch

Claude 桌面应用集成

安装软件包后，将以下条目添加到 claude_desktop_config.json：

Windows

{
  "mcpServers": {
    "deepwebresearch": {
      "command": "mcp-deepwebresearch",
      "args": []
    }
  }
}

位置：%APPDATA%\Claude\claude_desktop_config.json

macOS

{
  "mcpServers": {
    "deepwebresearch": {
      "command": "mcp-deepwebresearch",
      "args": []
    }
  }
}

位置：~/Library/Application Support/Claude/claude_desktop_config.json

此配置允许 Claude 桌面应用在需要时自动启动网络研究 MCP 服务。

首次设置

安装完成后，运行以下命令以安装所需的浏览器依赖项：

npx playwright install chromium

使用方法

只需与 Claude 开始聊天，并发送一个适合进行网络研究的提示词。如果你想使用为深度网络研究量身定制的预置提示词，可以使用此软件包提供的 agentic-research 提示词。在 Claude 桌面应用中，点击聊天输入框中的回形针图标，然后选择 选择集成 → deepwebresearch → agentic-research，即可访问该提示词。

工具

1. deep_research

   • 通过内容分析开展全面研究
   • 参数：

     {
       topic: string;
       maxDepth?: number;      // 默认值：2
       maxBranching?: number;  // 默认值：3
       timeout?: number;       // 默认值：55000（55 秒）
       minRelevanceScore?: number;  // 默认值：0.7
     }
     

   • 返回：

     {
       findings: {
         mainTopics: Array<{name: string, importance: number}>;
         keyInsights: Array<{text: string, confidence: number}>;
         sources: Array<{url: string, credibilityScore: number}>;
       };
       progress: {
         completedSteps: number;
         totalSteps: number;
         processedUrls: number;
       };
       timing: {
         started: string;
         completed?: string;
         duration?: number;
         operations?: {
           parallelSearch?: number;
           deduplication?: number;
           topResultsProcessing?: number;
           remainingResultsProcessing?: number;
           total?: number;
         };
       };
     }
     

2. parallel_search

   • 通过智能排队并行执行多次 Google 搜索
   • 参数：{ queries: string[], maxParallel?: number }
   • 注意：为确保性能可靠，maxParallel 上限为 5

3. visit_page

   • 访问网页并提取其内容
   • 参数：{ url: string }
   • 返回：

     {
       url: string;
       title: string;
       content: string;  // Markdown 格式的内容
     }
     

提示词

agentic-research

一条引导式研究提示词，可帮助 Claude 开展全面的网络研究。该提示词会指导 Claude：

• 从宽泛的搜索开始，了解主题概况
• 优先选择高质量、权威的来源
• 根据研究发现，逐步调整研究方向
• 随时告知你研究进展，并让你交互式地引导研究
• 始终附上来源 URL

配置选项

可通过环境变量配置服务：

• MAX_PARALLEL_SEARCHES：并发搜索的最大数量（默认值：5）
• SEARCH_DELAY_MS：搜索之间的延迟时间（毫秒，默认值：200）
• MAX_RETRIES：请求失败时的重试次数（默认值：3）
• TIMEOUT_MS：请求超时时间（毫秒，默认值：55000）
• LOG_LEVEL：日志级别（默认值：'info'）

错误处理

常见问题

1. 速率限制

   • 症状：“Too many requests”错误
   • 解决方案：增大 SEARCH_DELAY_MS 或减小 MAX_PARALLEL_SEARCHES

2. 网络超时

   • 症状：“Request timed out”错误
   • 解决方案：确保请求在 60 秒的 MCP 超时时间内完成

3. 浏览器问题

   • 症状：“Browser failed to launch”错误
   • 解决方案：确保已正确安装 Playwright（npx playwright install）

调试

这是 beta 软件。如果遇到问题：

1. 查看 Claude Desktop 的 MCP 日志：

   # On macOS
   tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
   
   # On Windows
   Get-Content -Path "$env:APPDATA\Claude\logs\mcp*.log" -Tail 20 -Wait
   

2. 启用调试日志：

   export LOG_LEVEL=debug
   

开发

设置

# Install dependencies
pnpm install

# Build the project
pnpm build

# Watch for changes
pnpm watch

# Run in development mode
pnpm dev

测试

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

代码质量

# Run linter
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type check
pnpm type-check

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

编码规范

• 遵循 TypeScript 最佳实践
• 将测试覆盖率维持在 80% 以上
• 记录新功能和 API
• 对重大更改更新 CHANGELOG.md
• 遵循语义化版本规范

性能注意事项

• 尽可能使用批量操作
• 实施恰当的错误处理和重试机制
• 处理大型数据集时考虑内存使用情况
• 适时缓存结果
• 对大型内容使用流式处理

要求

• Node.js >= 18
• Playwright（作为依赖项自动安装）

已验证的平台

• macOS
• Windows
• Linux

许可证

MIT

致谢

本项目基于 mzxrai 的优秀项目 mcp-webresearch 构建。原始代码库为我们增强后的功能和能力奠定了基础。

作者

qpd-v