MCP 深网研究服务器 (v0.3.0)

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

最新更改

• 添加了 visit_page 工具，用于直接提取网页内容
• 优化性能以符合 MCP 超时限制
  • 减少了默认的 maxDepth 和 maxBranching 参数
  • 提高了页面加载效率
  • 在整个过程中添加了超时检查
  • 增强了超时错误处理

该项目是 mzxrai 的 mcp-webresearch 项目的分支，并增加了额外的功能以支持深网研究能力。我们感谢原作者的基础工作。

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

功能

• 智能搜索队列系统

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

• 增强的内容提取

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

• 核心功能

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

先决条件

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

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Deep Web Research Server：

npx -y @smithery/cli install @PedroDnT/mcp-deepwebresearch --client 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 Desktop 在需要时自动启动网络研究 MCP 服务器。

首次设置

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

npx playwright install chromium

使用方法

只需开始与Claude的聊天，并发送一个可以从网络研究中受益的提示。如果您希望使用为深入网络研究定制的预构建提示，可以通过此包提供的agentic-research提示来实现。在Claude Desktop中，通过点击聊天输入框中的回形针图标，然后选择Choose an integration → 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. 请求频率限制

   • 症状：出现“请求过多”错误
   • 解决方案：增加 SEARCH_DELAY_MS 或减少 MAX_PARALLEL_SEARCHES

2. 网络超时

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

3. 浏览器问题

   • 症状：出现“浏览器启动失败”错误
   • 解决方案：确保正确安装了 Playwright (npx playwright install)

调试

这是测试版软件。如果您遇到问题：

1. 检查 Claude Desktop 的 MCP 日志：

   # 在 macOS 上
   tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
   
   # 在 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. 分叉仓库
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