Deep Research MCP Server

深度研究 MCP 服务

深度研究 MCP 服务是一个符合模型上下文协议（MCP）的服务，旨在进行全面的网络研究。它利用 Tavily 强大的搜索和全新 Crawl API，收集有关指定主题的大量最新信息。随后，该服务会将这些数据与文档生成说明汇总为结构化 JSON 输出，专为大模型（LLM）打造，以便生成详尽且高质量的 Markdown 文档。

功能

• 多步研究： 将 Tavily 的 AI 搜索与深度内容抓取相结合，全面收集信息。
• 结构化 JSON 输出： 提供组织良好的数据（原始查询、搜索摘要、每个来源的详细发现和文档说明），优化为适合大模型处理的格式。
• 可配置的文档提示词： 内置全面的默认提示词，用于生成高质量技术文档。此提示词可通过以下方式设置：
  • 设置 DOCUMENTATION_PROMPT 环境变量进行覆盖。
  • 直接向工具传递 documentation_prompt 参数，进一步覆盖提示词。
• 可配置的输出路径： 可通过以下方式指定研究文档和图片的保存位置：
  • 环境变量配置
  • JSON 配置
  • 工具调用中的直接参数
• 精细控制： 提供丰富的参数，可微调搜索和抓取流程。
• 符合 MCP 标准： 专为无缝集成到基于 MCP 的 AI Agent 生态系统而设计。

先决条件

• Node.js（建议使用 18.x 或更高版本）
• npm（随 Node.js 一同安装）或 Yarn

安装

通过 Smithery 安装

通过 Smithery 为 Claude Desktop 自动安装 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：集成本地项目或用于开发

1. 克隆代码库（如果你想修改或参与贡献）：

   git clone [https://github.com/your-username/deep-research-mcp.git](https://github.com/your-username/deep-research-mcp.git)
   cd deep-research-mcp
   

2. 安装依赖：

   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", // Required
        "DOCUMENTATION_PROMPT": "Your custom, detailed instructions for the LLM on how to generate markdown documents from the research data...", // Optional - if not provided, the default prompt will be used
        "SEARCH_TIMEOUT": "120", // Optional - timeout in seconds for search requests (default: 60)
        "CRAWL_TIMEOUT": "300", // Optional - timeout in seconds for crawl requests (default: 180)
        "MAX_SEARCH_RESULTS": "10", // Optional - maximum search results to retrieve (default: 7)
        "CRAWL_MAX_DEPTH": "2", // Optional - maximum crawl depth (default: 1)
        "CRAWL_LIMIT": "15", // Optional - maximum URLs to crawl per source (default: 10)
        "FILE_WRITE_ENABLED": "true", // Optional - enable file writing capability (default: false)
        "ALLOWED_WRITE_PATHS": "/home/user/research,/home/user/documents", // Optional - comma-separated allowed directories (default: user home directory)
        "FILE_WRITE_LINE_LIMIT": "300" // Optional - maximum lines per file write operation (default: 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 环境变量即可覆盖默认的综合文档提示词。

设置方式（按优先级排序）：

1. 工具参数： 调用 deep-research-tool 时传入的 documentation_prompt 参数具有最高优先级
2. 环境变量： 如果工具调用时未提供参数，系统会检查 DOCUMENTATION_PROMPT 环境变量
3. 默认值： 如果以上两项均未设置，则使用内置的综合默认提示词

通过 .env 文件设置：

DOCUMENTATION_PROMPT="Your custom, detailed instructions for the LLM on how to generate markdown..."

或直接在命令行中设置：

DOCUMENTATION_PROMPT="Your custom prompt..." TAVILY_API_KEY="tvly-YOUR_KEY" npx @pinkpixel/deep-research-mcp

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

你可以指定保存研究文档和图片的位置。如果未配置，系统会使用用户 Documents 文件夹中的默认路径，并附加时间戳。

设置方式（按优先级排序）：

1. 工具参数： 调用 deep-research-tool 时传入的 output_path 参数具有最高优先级
2. 环境变量： 如果工具调用时未提供参数，系统会检查 RESEARCH_OUTPUT_PATH 环境变量
3. 默认路径： 如果以上两项均未设置，则使用用户 Documents 文件夹中带时间戳的子文件夹：~/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. 文件写入配置（可选）

此服务包含一个安全的文件写入工具，允许大模型将研究结果直接保存到文件中。出于安全考虑，此功能默认禁用。

安全功能：

• 必须通过 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

使用示例： 启用后，大模型可以使用 write-research-file 工具保存内容：

{
  "tool": "write-research-file",
  "arguments": {
    "file_path": "/home/user/research/quantum-computing-report.md",
    "content": "# Quantum Computing Research Report\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
  

服务器将在 stdio 上监听 MCP 请求。

工作原理

1. 大模型或 AI Agent 向此 MCP 服务发送 CallToolRequest，指定 deep-research-tool，并提供查询内容及其他可选参数。
2. deep-research-tool 首先执行 Tavily Search，以查找相关的网络来源。
3. 然后，它使用 Tavily Crawl 从这些来源中提取详细内容。
4. 汇总所有收集到的信息（搜索摘要、抓取的内容、图片 URL）。
5. 包含选定的文档提示词（默认提示词、ENV 或工具参数）。
6. 服务器返回一个包含所有这些结构化数据的 JSON 字符串。
7. 调用方大模型/Agent 使用此 JSON 输出，并根据 documentation_instructions 生成完整的 Markdown 文档。

使用 deep-research-tool

这是服务器提供的主要工具。

输出结构

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

{
  "documentation_instructions": "string", // The detailed prompt for the LLM to generate the markdown.
  "original_query": "string",         // The initial query provided to the tool.
  "search_summary": "string | null",  // An LLM-generated answer/summary from Tavily's search phase (if include_answer was true).
  "research_data": [                  // Array of findings, one element per source.
    {
      "search_rank": "number",
      "original_url": "string",           // URL of the source found by search.
      "title": "string",                  // Title of the web page.
      "initial_content_snippet": "string",// Content snippet from the initial search result.
      "search_score": "number | undefined",// Relevance score from Tavily search.
      "published_date": "string | undefined",// Publication date (if 'news' topic and available).
      "crawled_data": [                 // Array of pages crawled starting from original_url.
        {
          "url": "string",                // URL of the specific page crawled.
          "raw_content": "string | null", // Rich, extracted content from this page.
          "images": ["string", "..."]     // Array of image URLs found on this page.
        }
      ],
      "crawl_errors": ["string", "..."]   // Array of error messages if crawling this source failed or had issues.
    }
    // ... more sources
  ],
  "output_path": "string"             // Path where research documents and images should be saved.
}

输入参数

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

通用参数

• query（字符串，必填）：主要研究主题或问题。
• documentation_prompt（字符串，可选）：用于大模型生成文档的自定义提示词。
  • 说明： 如果提供此提示词，大模型将使用它。它会覆盖 DOCUMENTATION_PROMPT 环境变量和服务器内置的默认提示词。如果未在此处提供，服务器会检查环境变量，然后使用默认提示词。
• output_path（字符串，可选）：保存生成的研究文档和图片的路径。
  • 说明： 如果提供此路径，将使用它保存研究输出。它会覆盖 RESEARCH_OUTPUT_PATH 环境变量。如果两者都未设置，则会在用户的 Documents 目录中使用带时间戳的文件夹。

搜索参数（适用于 Tavily Search 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 Crawl API——应用于搜索结果中的每个 URL）

• crawl_max_depth（数字，可选，默认值：1）：从基础 URL 开始的最大爬取深度。0 表示仅爬取基础 URL，1 表示爬取基础 URL 及其链接，依此类推。
• crawl_max_breadth（数字，可选，默认值：5）：爬取树每层（即每个页面）要跟进的最大链接数。
• crawl_limit（数字，可选，默认值：10）：爬虫从单个根 URL 开始处理的链接总数上限，达到上限后停止。
• crawl_instructions（字符串，可选）：为爬虫提供的自然语言指令，说明如何爬取网站。
• crawl_select_paths（字符串数组，可选，默认值：[]）：用于仅选择具有特定路径模式的 URL 进行爬取的正则表达式模式（例如，"/docs/.*"）。
• crawl_select_domains（字符串数组，可选，默认值：[]）：用于将爬取范围限制到特定域名或子域名的正则表达式模式（例如，"^docs\\.example\\.com$"）。如果 crawl_allow_external 为 false（默认值）且此项为空，爬取范围将限定在正在爬取的 URL 所属域名内。此项会覆盖该范围。
• crawl_exclude_paths（字符串数组，可选，默认值：[]）：用于排除具有特定路径模式的 URL 的正则表达式模式。
• crawl_exclude_domains（字符串数组，可选，默认值：[]）：用于排除特定域名或子域名的正则表达式模式。
• crawl_allow_external（布尔值，可选，默认值：false）：是否允许爬虫跟进指向外部域名的链接。
• crawl_include_images（布尔值，可选，默认值：true）：是否从爬取的页面中提取图片 URL。
• crawl_categories（字符串数组，可选，默认值：[]）：使用预定义类别筛选要爬取的 URL（例如，"Blog"、"Documentation"、"Careers"）。所有选项请参阅 Tavily Crawl API。
• crawl_extract_depth（字符串，可选，默认值："advanced"）：爬取期间的内容提取深度。
  • 选项： "basic"、"advanced"。高级模式可提取更多数据（表格、嵌入内容），但延迟可能更高。
• crawl_timeout（数字，可选，默认值：180）：每次 Tavily Crawl 请求的超时时间（秒）。

了解文档提示词的优先级

documentation_prompt 是此工具的重要组成部分，它会指导大模型如何设置研究结果的格式和结构。系统按以下优先级确定要使用的提示词：

1. 如果大模型/Agent 在工具调用中提供了 documentation_prompt 参数：

   • 此参数具有最高优先级，无论其他设置如何，都会使用此参数
   • 这使最终用户可以通过向大模型提出自然语言请求来定制文档格式

2. 如果工具调用中未提供该参数，但已设置 DOCUMENTATION_PROMPT 环境变量：

   • 将使用该环境变量的值
   • 这有助于系统管理员或开发者为所有工具调用设置一致的提示词

3. 如果以上两项均未设置：

   • 将使用内置的综合默认提示词
   • 此默认提示词旨在生成高质量的技术文档

这种灵活性使得：

• 最终用户可以通过向大模型提出自然语言请求来定制文档
• 开发者可以设置系统级默认值
• 未提供任何自定义设置时，可以回退到精心设计的默认值

使用输出路径

output_path 参数决定研究文档和图片的保存位置。这一点尤为重要，因为大模型可能需要：

1. 保存生成的 Markdown 文档
2. 下载并保存研究中的图片
3. 创建补充文件或资源

系统按以下优先级确定输出路径：

1. 如果大模型/Agent 在工具调用中提供了 output_path 参数：

   • 优先级最高
   • 允许最终用户通过自然语言请求指定自定义保存位置

2. 如果未提供参数，但设置了 RESEARCH_OUTPUT_PATH 环境变量：

   • 将使用该环境变量的值
   • 适用于系统范围的配置

3. 如果以上两项均未设置：

   • 将使用带时间戳的默认路径：~/Documents/research/YYYY-MM-DDTHH-MM-SS/
   • 这样可以避免覆盖之前的研究结果

工具会在响应 JSON 中通过 output_path 字段向大模型返回最终确定的输出路径，因此大模型始终知道应将生成的内容保存到何处。

给大模型的注意事项： 处理工具结果时，请检查 output_path 字段，以确定保存所生成文件的位置。响应中一定会包含此路径。

给大模型的说明

作为使用 deep-research-tool 输出的大模型，你的首要目标是生成一份全面、准确、结构清晰的 Markdown 文档，解答 original_query。

关键步骤：

1. 解析 JSON 输出： 工具将返回一个 JSON 字符串。解析该字符串以访问以下字段：documentation_instructions、original_query、search_summary 和 research_data。
2. 遵循 documentation_instructions： 此字段包含创建 Markdown 文档的主要指导原则。它可能是服务器详尽的默认提示词（侧重于高质量技术文档），也可能是用户提供的自定义提示词。请严格遵循其中关于内容质量、风格、结构、Markdown 格式和技术细节处理的说明。
3. 利用 research_data 获取内容：
   • research_data 数组是主要信息来源。数组中的每个对象都代表一个不同的网络来源。
   • 请结合每个来源的 title、original_url 和 initial_content_snippet 了解上下文。
   • 文档的核心信息来自每个来源中的 crawled_data 数组。具体来说，每个 crawled_data 对象的 raw_content 字段包含从页面提取的丰富文本。
   • 综合 research_data 中的多个来源提供信息，呈现全面的概述。不要只按来源逐一罗列内容。
   • 如果存在 crawled_data[].images，且符合 documentation_instructions，可酌情提及这些图片或列出其 URL。
   • 如果某个来源存在 crawl_errors，表示该来源可能不完整。如果这会影响内容覆盖范围，可酌情简要说明。
4. 回应 original_query： 最终文档必须全面回答或回应 original_query。
5. 利用 search_summary： 如果存在 search_summary 字段（来自 Tavily 的 include_answer 功能），可将其作为有用的起点、执行摘要或引言框架。不过，正文应基于更详细的 research_data 编写。
6. 综合整理，而非照搬： 你的任务不是直接粘贴 raw_content，而是按照 documentation_instructions 处理、理解、综合、改述并组织不同来源的信息，撰写一篇连贯流畅的文档。
7. Markdown 格式： 严格遵循 documentation_instructions 中提供的 Markdown 格式指南（标题、列表、代码块、强调、链接等）。
8. 处理大量内容： research_data 可能内容繁多。如果你在处理大量输入时遇到限制，调用你的系统可能需要分块提供 research_data，或多次请求你逐节撰写文档。deep-research-tool 本身会始终尝试在一次 JSON 输出中返回所有收集到的数据。
9. 技术准确性： 按照 documentation_instructions 的要求，保留所有技术细节、代码示例和重要具体信息。不要过度简化。
10. 视觉效果（如有要求）： 如果 documentation_instructions 包含视觉效果方面的指南（例如使用 HTML 设置彩色文本或添加表情符号），请适度采用。

LLM 调用思路示例：

Agent 对 LLM： “好的，我已使用查询‘<em>抗量子密码学的最新进展有哪些？</em>’调用 deep-research-tool，并请求 5 个来源和高级爬取。以下是 JSON 输出： { ...（工具返回的 JSON 输出……）... }

现在，请根据此 JSON 中提供的 documentation_instructions 和 research_data，撰写一份关于‘抗量子密码学的最新进展’的综合 Markdown 文档。请确保遵循所有格式和内容指南。”

示例 CallToolRequest（概念性参数）

Agent 可能会使用如下参数调用 MCP 服务：

{
  "name": "deep-research-tool",
  "arguments": {
    "query": "Explain the architecture of modern data lakes and data lakehouses.",
    "max_search_results": 5,
    "search_depth": "advanced",
    "topic": "general",
    "crawl_max_depth": 1,
    "crawl_extract_depth": "advanced",
    "include_answer": true,
    "documentation_prompt": "Generate a highly technical whitepaper. Start with an abstract, then introduction, detailed sections for data lakes, data lakehouses, comparison, use cases, and a future outlook. Use academic tone. Include all diagrams mentioned by URL if possible as [Diagram: URL].",
    "output_path": "C:/Users/username/Documents/research/datalakes-whitepaper"
  }
}

故障排除

• API 密钥错误： 确保已正确设置 TAVILY_API_KEY，且其有效。
• SDK 问题： 确保已安装最新版本的 @modelcontextprotocol/sdk 和 @tavily/core。
• 无输出/错误： 检查服务控制台日志中是否有错误消息。必要时提高详细程度以便调试。

更新日志

v0.1.2（2024-05-10）

• 添加了可配置输出路径的功能
• 修复了与最新 Tavily SDK 相关的类型错误
• 添加了有关输出路径的完整文档
• 添加了徽标并改进了文档

v0.1.1

• 首次公开发布

参与贡献

欢迎贡献！欢迎提交问题、派生此仓库并创建拉取请求。

许可证

本项目采用 Apache 2.0 许可证授权，详情请参阅 LICENSE 文件。