深度研究MCP

Name: 深度研究MCP
Author: pinkpixel-dev

作者：pinkpixel-dev23 星标更新：2025-06-02

项目介绍

<p align="center"> <img src="assets/deep-research-mcp-logo.png" alt="Deep Research MCP Logo" width="250" height="250"> </p> <h1 align="center">Deep Research MCP 服务器</h1> <p align="center"> <a href="https://www.npmjs.com/package/@pinkpixel/deep-research-mcp"><img src="https://img.shields.io/npm/v/@pinkpixel/deep-research-mcp.svg" alt="NPM 版本"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="许可证：MIT"></a> <a href="https://smithery.ai/server/@pinkpixel/dev-deep-research-mcp"><img src="https://smithery.ai/badge/@pinkpixel/dev-deep-research-mcp" alt="Smithery 安装"></a> </p>

Deep Research MCP 服务器是一个符合模型上下文协议（MCP）的服务器，旨在执行全面的网络研究。它利用 Tavily 强大的搜索和新的爬取 API 来收集关于给定主题的广泛且最新的信息。然后，该服务器将这些数据与文档生成指令一起整合成结构化的 JSON 输出，非常适合大型语言模型（LLMs）创建详细且高质量的 Markdown 文档。

功能

多步骤研究： 结合 Tavily 的 AI 驱动的网络搜索与深度内容爬取，以进行彻底的信息收集。
结构化 JSON 输出： 提供组织良好的数据（原始查询、搜索摘要、每个来源的详细发现以及文档生成指令），优化了 LLM 的消费。
可配置的文档提示： 包含一个全面的默认提示，用于生成高质量的技术文档。此提示可以：
- 通过设置 DOCUMENTATION_PROMPT 环境变量来覆盖。
- 直接传递 documentation_prompt 参数到工具中进一步覆盖。
可配置的输出路径： 指定研究文档和图像应保存的位置，通过：
- 环境变量配置
- JSON 配置
- 工具调用中的直接参数
细粒度控制： 提供广泛的参数以微调搜索和爬取过程。
MCP 兼容性： 设计为无缝集成到基于 MCP 的 AI 代理生态系统中。

前提条件

Node.js（推荐版本 18.x 或更高）
npm（随 Node.js 一起提供）或 Yarn

安装

通过 Smithery 安装

要通过 Smithery 自动安装 deep-research-mcp：

npx -y @smithery/cli install @pinkpixel/dev-deep-research-mcp --client claude

方案 1：使用 NPX（推荐快速使用）

您可以直接使用 npx 运行服务器，而无需全局安装：

npx @pinkpixel/deep-research-mcp

方案 2：全局安装（可选）

npm install -g @pinkpixel/deep-research-mcp

然后您可以使用以下命令运行它：

deep-research-mcp

方案 3：本地项目集成或开发

克隆仓库（如果您想要修改或贡献）：

git clone https://github.com/your-username/deep-research-mcp.git
cd deep-research-mcp

安装依赖项：
```
npm install
```

配置

服务器需要一个 Tavily API 密钥，并可以选择接受自定义文档提示。

{
  "mcpServers": {
    "deep-research": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/deep-research-mcp"
      ],
      "env": {
        "TAVILY_API_KEY": "tvly-YOUR_ACTUAL_API_KEY_HERE", // 必需
        "DOCUMENTATION_PROMPT": "您的自定义详细说明，指示 LLM 如何从研究数据生成 Markdown 文档...", // 可选 - 如果未提供，则使用默认提示
        "SEARCH_TIMEOUT": "120", // 可选 - 搜索请求超时时间（秒，默认：60）
        "CRAWL_TIMEOUT": "300", // 可选 - 爬取请求超时时间（秒，默认：180）
        "MAX_SEARCH_RESULTS": "10", // 可选 - 最大搜索结果数量（默认：7）
        "CRAWL_MAX_DEPTH": "2", // 可选 - 最大爬取深度（默认：1）
        "CRAWL_LIMIT": "15", // 可选 - 每个来源的最大爬取 URL 数量（默认：10）
        "FILE_WRITE_ENABLED": "true", // 可选 - 启用文件写入功能（默认：false）
        "ALLOWED_WRITE_PATHS": "/home/user/research,/home/user/documents", // 可选 - 逗号分隔的允许目录（默认：用户主目录）
        "FILE_WRITE_LINE_LIMIT": "300" // 可选 - 每次文件写入操作的最大行数（默认：200）
      }
    }
  }
}

1. Tavily API 密钥（必需）

设置 TAVILY_API_KEY 环境变量为您自己的 Tavily API 密钥。

方法：

.env 文件： 在项目根目录下创建一个 .env 文件（如果在本地开发）：
```
TAVILY_API_KEY="tvly-YOUR_ACTUAL_API_KEY"
```

直接在命令行中：

TAVILY_API_KEY="tvly-YOUR_ACTUAL_API_KEY" npx @pinkpixel/deep-research-mcp

系统环境变量： 在操作系统中设置环境变量。

2. 自定义文档提示（可选）

您可以通过设置 DOCUMENTATION_PROMPT 环境变量来覆盖默认的全面文档提示。

方法（按优先级顺序）：

工具参数： 调用 deep-research-tool 时传递的 documentation_prompt 参数具有最高优先级
环境变量： 如果工具调用中没有提供参数，系统会检查 DOCUMENTATION_PROMPT 环境变量
默认值： 如果上述两者都没有设置，则使用内置的全面默认提示

通过 .env 文件设置：

DOCUMENTATION_PROMPT="您的自定义详细说明，指示 LLM 如何从研究数据生成 Markdown..."

或者直接在命令行中：

DOCUMENTATION_PROMPT="您的自定义提示..." TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp

3. 输出路径配置（可选）

您可以指定研究文档和图像应保存的位置。如果没有配置，默认情况下会在用户的文档文件夹中使用带有时间戳的路径。

方法（按优先级顺序）：

工具参数： 调用 deep-research-tool 时传递的 output_path 参数具有最高优先级
环境变量： 如果工具调用中没有提供参数，系统会检查 RESEARCH_OUTPUT_PATH 环境变量
默认路径： 如果上述两者都没有设置，则使用带有时间戳的子文件夹：~/Documents/research/YYYY-MM-DDTHH-MM-SS/

通过 .env 文件设置：

RESEARCH_OUTPUT_PATH="/path/to/your/research/folder"

或者直接在命令行中：

RESEARCH_OUTPUT_PATH="/path/to/your/research/folder" TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp

4. 超时和性能配置（可选）

您可以通过环境变量配置超时和性能设置，以优化工具以适应特定的使用场景或部署环境：

可用环境变量：

SEARCH_TIMEOUT - Tavily 搜索请求的超时时间（秒，默认：60）
CRAWL_TIMEOUT - Tavily 爬取请求的超时时间（秒，默认：180）
MAX_SEARCH_RESULTS - 要检索的最大搜索结果数量（默认：7）
CRAWL_MAX_DEPTH - 从基础 URL 开始的最大爬取深度（默认：1）
CRAWL_LIMIT - 每个来源的最大爬取 URL 数量（默认：10）

通过 .env 文件设置：

SEARCH_TIMEOUT=120
CRAWL_TIMEOUT=300
MAX_SEARCH_RESULTS=10
CRAWL_MAX_DEPTH=2
CRAWL_LIMIT=15

或者直接在命令行中：

SEARCH_TIMEOUT=120 CRAWL_TIMEOUT=300 TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp

何时调整这些设置：

增加超时时间 如果您在 LibreChat 或其他 MCP 客户端中遇到超时错误
减少超时时间 当处理较简单的查询时，以获得更快的响应
增加限制 以进行更全面的研究（但预期处理时间更长）
减少限制 以减少资源使用并加快处理速度

5. 文件写入配置（可选）

服务器包含一个安全的文件写入工具，允许 LLM 将研究发现直接保存到文件中。出于安全原因，默认情况下此功能是禁用的。

安全特性：

通过 FILE_WRITE_ENABLED=true 显式启用文件写入
通过 ALLOWED_WRITE_PATHS 限制目录（默认为主目录）
写入操作每行限制以防止滥用
路径验证和清理
自动创建目录

配置：

FILE_WRITE_ENABLED=true
ALLOWED_WRITE_PATHS=/home/user/research,/home/user/documents,/tmp/research
FILE_WRITE_LINE_LIMIT=500

使用示例： 一旦启用，LLMs 可以使用 write-research-file 工具保存内容：

{
  "tool": "write-research-file",
  "arguments": {
    "file_path": "/home/user/research/quantum-computing-report.md",
    "content": "# 量子计算研究报告\n\n...",
    "mode": "rewrite"
  }
}

安全注意事项：

只在受信任的环境中启用文件写入
使用特定的目录限制而不是允许系统范围的访问
通过服务器日志监控文件操作
对于敏感系统，考虑使用只读目录

运行服务器

开发（带自动重载）： 如果您已克隆了仓库并在项目目录中：
```
npm run dev
```
这将使用 nodemon 和 ts-node 来监视更改并重新启动服务器。
生产/独立： 首先，构建 TypeScript 代码：
```
npm run build
```
然后，启动服务器：
```
npm start
```
使用 NPX 或全局安装： （确保如配置部分所述设置环境变量）
```
npx @pinkpixel/deep-research-mcp
```
或者如果已全局安装：
```
deep-research-mcp
```

服务器将在标准输入输出上监听 MCP 请求。

工作原理

LLM 或 AI 代理向此 MCP 服务器发出 CallToolRequest，指定 deep-research-tool 并提供查询和其他可选参数。
deep-research-tool 首先执行 Tavily 搜索以找到相关的网络来源。
然后使用 Tavily 爬取从这些来源提取详细内容。
所有收集的信息（搜索片段、爬取的内容、图像 URL）被汇总。
选择的文档提示（默认、ENV 或工具参数）被包括在内。
服务器返回一个包含所有这些结构化数据的单一 JSON 字符串。
调用的 LLM/代理使用此 JSON 输出，根据 documentation_instructions 生成一份详尽的 Markdown 文档。

使用 `deep-research-tool`

这是服务器公开的主要工具。

输出结构

该工具返回一个具有以下结构的 JSON 字符串：

{
  "documentation_instructions": "string", // LLM 生成 Markdown 的详细提示。
  "original_query": "string",         // 提供给工具的初始查询。
  "search_summary": "string | null",  // Tavily 搜索阶段生成的答案/摘要（如果 include_answer 为 true）。
  "research_data": [                  // 找到的数组，每个来源一个元素。
    {
      "search_rank": "number",
      "original_url": "string",           // 搜索找到的来源 URL。
      "title": "string",                  // 网页标题。
      "initial_content_snippet": "string",// 初始搜索结果的内容片段。
      "search_score": "number | undefined",// Tavily 搜索的相关性评分。
      "published_date": "string | undefined",// 发布日期（如果是新闻主题且可用）。
      "crawled_data": [                 // 从 original_url 开始爬取的页面数组。
        {
          "url": "string",                // 爬取的具体页面 URL。
          "raw_content": "string | null", // 从此页面提取的丰富内容。
          "images": ["string", "..."]     // 此页面上找到的图像 URL 数组。
        }
      ],
      "crawl_errors": ["string", "..."]   // 如果爬取此来源失败或有问题，错误消息数组。
    }
    // ... 更多来源
  ],
  "output_path": "string"             // 应保存研究文档和图像的路径。
}

输入参数

deep-research-tool 接受以下参数在其 arguments 对象中：

通用参数

query (字符串，必需): 主要的研究主题或问题。
documentation_prompt (字符串，可选): LLM 文档生成的自定义提示。
- 描述: 如果提供，此提示将由 LLM 使用。它覆盖 DOCUMENTATION_PROMPT 环境变量和服务器内置的默认提示。如果此处未提供，则服务器检查环境变量，然后回退到默认值。
output_path (字符串，可选): 生成的研究文档和图像应保存的路径。
- 描述: 如果提供，此路径将用于保存研究输出。它覆盖 RESEARCH_OUTPUT_PATH 环境变量。如果两者都没有设置，则使用带有时间戳的用户文档目录中的文件夹。

搜索参数（针对 Tavily 搜索 API）

search_depth (字符串，可选，默认: "advanced"): 初始 Tavily 搜索的深度。
- 选项: "basic", "advanced". 高级搜索针对更相关来源进行了优化。
topic (字符串，可选，默认: "general"): Tavily 搜索的类别。
- 选项: "general", "news".
days (数字，可选): 对于 topic: "news"，从当前日期回溯的天数以包含搜索结果。
time_range (字符串，可选): 搜索结果的时间范围（例如，"d" 表示一天，"w" 表示一周，"m" 表示一个月，"y" 表示一年）。
max_search_results (数字，可选，默认: 7): 要检索和考虑爬取的最大搜索结果数量（1-20）。
chunks_per_source (数字，可选，默认: 3): 对于 search_depth: "advanced"，从每个来源检索的内容块数量（1-3）。
include_search_images (布尔值，可选，默认: false): 包括初始搜索相关的图像 URL 列表。
include_search_image_descriptions (布尔值，可选，默认: false): 包括初始搜索中的图像描述和 URL。
include_answer (布尔值或字符串，可选，默认: false): 包括基于搜索结果的 Tavily 生成的答案。
- 选项: true（意味着 "basic"），false，"basic"，"advanced".
include_raw_content_search (布尔值，可选，默认: false): 包括每个初始搜索结果的清理和解析后的 HTML 内容。
include_domains_search (字符串数组，可选，默认: []): 要特别包含在搜索结果中的域名列表。
exclude_domains_search (字符串数组，可选，默认: []): 要特别排除在搜索结果中的域名列表。
search_timeout (数字，可选，默认: 60): Tavily 搜索请求的超时时间（秒）。

爬取参数（针对 Tavily 爬取 API - 应用于搜索的每个 URL）

crawl_max_depth (数字，可选，默认: 1): 从基础 URL 开始的爬取最大深度。0 表示仅基础 URL，1 表示基础 URL 和其上的链接等。
crawl_max_breadth (数字，可选，默认: 5): 爬取树每层（即每页）要跟随的链接的最大数量。
crawl_limit (数字，可选，默认: 10): 从单个根 URL 开始，爬虫将处理的链接总数，在停止之前。
crawl_instructions (字符串，可选): 用于指导爬虫如何爬取网站的自然语言说明。
`

深度研究MCP

项目介绍

功能

前提条件

安装

通过 Smithery 安装

方案 1：使用 NPX（推荐快速使用）

方案 2：全局安装（可选）

方案 3：本地项目集成或开发

配置

1. Tavily API 密钥（必需）

2. 自定义文档提示（可选）

3. 输出路径配置（可选）

4. 超时和性能配置（可选）

5. 文件写入配置（可选）

运行服务器

工作原理

使用 deep-research-tool

输出结构

输入参数

通用参数

搜索参数（针对 Tavily 搜索 API）

爬取参数（针对 Tavily 爬取 API - 应用于搜索的每个 URL）

使用 `deep-research-tool`