使用说明

Deep Research MCP Server

Deep Research MCP服务器是一个符合模型上下文协议（MCP）的服务器，旨在执行全面的网络研究。它利用Tavily强大的搜索和新的爬行API来收集有关给定主题的广泛、最新的信息。然后，服务器将这些数据与文档生成指令聚合成结构化的JSON输出，完美地为大型语言模型（LLM）量身定制，以创建详细和高质量的markdown文档。

特性

多步骤研究： 将Tavily的人工智能网络搜索与深度内容爬行相结合，以进行彻底的信息收集。
结构化JSON输出： 提供组织良好的数据（原始查询、搜索摘要、每个来源的详细结果和文档说明），针对LLM消费进行了优化。
可配置文档提示： 包括生成高质量技术文档的全面默认提示。该提示可以是：
- 通过设置 DOCUMENTATION_PROMPT 环境变量。
- 通过传递a进一步覆盖 documentation_prompt 直接对工具进行论证。
可配置输出路径： 通过以下方式指定研究文档和图像的保存位置：
- 环境变量配置
- JSON配置
- 工具调用中的直接参数
粒度控制： 提供广泛的参数来微调搜索和爬网过程。
符合MCP标准： 旨在无缝集成到基于MCP的AI代理生态系统中。

先决条件

Node.js （建议使用18.x或更高版本）
npm （附带Node.js）或纱线

安装

通过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：本地项目整合或开发

克隆存储库（如果您想修改或贡献）：

git clone [https://github.com/your-username/deep-research-mcp.git](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", // 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.Tavilly 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 环境变量。

方法（按优先顺序）：

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

通过设置 .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.输出路径配置（可选）

您可以指定研究文档和图像的保存位置。如果未配置，将使用用户“文档”文件夹中带有时间戳的默认路径。

方法（按优先顺序）：

工具参数： 这 output_path 调用时传递的参数 deep-research-tool 具有最高优先级
环境变量： 如果工具调用中没有提供参数，系统将检查 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

使用示例： 启用后，LLM可以使用 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请求。

运作原理

LLM或AI代理可以 CallToolRequest 指定此MCP服务器 deep-research-tool 并提供查询和其他可选参数。
这 deep-research-tool 首先执行Tavily搜索以查找相关的网络资源。
然后，它使用Tavily Crawl从这些来源中提取详细的内容。
所有收集到的信息（搜索片段、抓取内容、图像URL）都是聚合的。
包括所选的文档提示（默认值、ENV或工具参数）。
服务器返回一个包含所有这些结构化数据的JSON字符串。
调用LLM/代理使用此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 （字符串，可选）：生成LLM文档的自定义提示。
- 说明： 如果提供，LLM将使用此提示。它覆盖了这两个 DOCUMENTATION_PROMPT 环境变量和服务器的内置默认提示。如果此处未提供，服务器将检查环境变量，然后返回默认值。
output_path （字符串，可选）：应保存生成的研究文档和图像的路径。
- 说明： 如果提供，此路径将用于保存研究成果。它覆盖了 RESEARCH_OUTPUT_PATH 环境变量。如果两者都没有设置，则将使用用户“文档”目录中的带时间戳的文件夹。

搜索参数（用于Tavilly Search API）

search_depth （字符串，可选，默认值： "advanced")：初步塔维利搜索的深度。
- 选项： "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根据搜索结果生成的LLM答案。
- 选项： 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爬网请求的超时时间（秒）。

了解文档提示优先级

这 documentation_prompt 是该工具的重要组成部分，因为它指导法学硕士如何格式化和构建研究成果。系统使用此优先级来确定使用哪个提示：

如果LLM/代理提供 documentation_prompt 工具调用中的参数：
- 这具有最高优先级，无论其他设置如何，都将使用
- 这允许最终用户通过向LLM发出自然语言请求来定制文档格式
如果工具调用中没有提供参数，但 DOCUMENTATION_PROMPT 设置环境变量：
- 将使用环境变量值
- 这对于系统管理员或开发人员在所有工具调用中设置一致的提示非常有用
如果上述两项均未设置：
- 使用全面的内置默认提示
- 此默认提示旨在生成高质量的技术文档

这种灵活性允许：

最终用户通过向LLM发出自然语言请求来定制文档
开发人员设置系统范围的默认值
如果不提供自定义，则回退到设计良好的默认值

使用输出路径

这 output_path 参数决定了研究文档和图像的保存位置。当法学硕士需要：

保存生成的markdown文档
下载并保存研究中的图像
创建补充文件或资源

系统遵循此优先级来确定输出路径：

如果LLM/代理提供 output_path 工具调用中的参数：
- 这具有最高优先级
- 允许最终用户通过自然语言请求指定自定义保存位置
如果没有提供参数，但 RESEARCH_OUTPUT_PATH 设置环境变量：
- 将使用环境变量值
- 适用于全系统配置
如果上述两项均未设置：
- 使用带有时间戳的默认路径： ~/Documents/research/YYYY-MM-DDTHH-MM-SS/
- 这可以防止覆盖以前的研究结果

LLM在工具的响应JSON中接收最终解析的输出路径，作为 output_path 字段，因此它总是知道在哪里保存生成的内容。

LLM注意事项： 处理工具结果时，检查 output_path 字段，以确定将生成的任何文件保存在何处。此路径保证会出现在响应中。

LLM说明

作为LLM，使用 deep-research-tool，您的主要目标是生成一个全面、准确、结构良好的markdown文档，以解决以下问题 original_query.

关键步骤：

解析JSON输出： 该工具将返回一个JSON字符串。解析此字符串以访问其字段： documentation_instructions, original_query, search_summary，以及 research_data.
遵守 documentation_instructions: 此字段包含 主要指导方针 用于创建markdown文档。它要么是服务器的广泛默认提示（专注于高质量的技术文档），要么是用户提供的自定义提示。 仔细遵循这些说明 关于内容质量、风格、结构、标记格式和技术细节的处理。
利用 research_data 内容：
- 这 research_data 数组是您的主要信息来源。此数组中的每个对象代表一个不同的web源。
- 对于每个来源，请注意其 title, original_url，以及 initial_content_snippet 为了上下文。
- 文档的核心信息将来自 crawled_data 每个源内的数组。具体而言 raw_content 每个字段 crawled_data 对象包含从该页面提取的富文本。
- 综合信息 跨越多个来源 在 research_data 以提供全面的视图。不要只列出一个又一个来源的内容。
- 如果 crawled_data[].images 如果存在，您可以在适当的情况下提及它们或列出它们的网址，并与 documentation_instructions.
- 如果 crawl_errors 如果某个源存在，则意味着该特定源可能不完整。如果这会影响覆盖范围，您可以选择巧妙地注意到这一点。
地址 original_query: 最终文件必须全面回答或解决以下问题 original_query.
杠杆 search_summary: 如果 search_summary 现场（来自塔维利） include_answer 功能），它可以作为一个有用的起点、执行摘要或构建介绍的一种方式。但是，文档的主体应该从更详细的 research_data.
综合，不要只是复制： 你的角色不是转储 raw_content。您必须按照以下要求处理、理解、综合、改写和组织来自各种来源的信息，使其成为一份连贯、写得好、逻辑流畅的文档 documentation_instructions.
Markdown格式： 严格遵守中提供的降价格式指南 documentation_instructions （标题、列表、代码块、强调、链接等）。
处理大容量： 这 research_data 可以是广泛的。如果您在处理大型输入方面有限制，则系统调用可能需要为您提供 research_data 或者向您发出多个请求，逐节构建文档。这 deep-research-tool 它本身将始终尝试在一个JSON输出中返回所有收集到的数据。
技术精度： 按照规定，保留源内容中的所有技术细节、代码示例和重要细节 documentation_instructions不要过于简单化。
视觉吸引力（如有指示）： 如果 documentation_instructions 包括视觉吸引力的指导方针（如使用HTML的彩色文本或表情符号），明智地应用它们。

LLM调用思维过程示例：

LLM代理： “好吧，我已经打电话给 deep-research-tool 有人问：“抗量子密码学的最新进展是什么？”？</em>'并请求5个具有高级爬行功能的来源。以下是JSON输出： { ... (JSON output from the tool) ... }

现在，使用 documentation_instructions 在这个JSON中提供，以及 research_data，请生成一份关于“量子抗性密码学的最新进展”的全面降价文件。确保遵循说明中的所有格式和内容指南。"

示例 `CallToolRequest` （概念论证）

代理可能会使用以下参数调用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许可证获得许可-请参阅许可证文件以获取详细信息。

使用说明

Deep Research MCP Server

特性

先决条件

安装

通过Smithery安装

选项1：与NPX一起使用（建议快速使用）

选项2：全局安装（可选）

选项3：本地项目整合或开发

配置

1.Tavilly API密钥（必需）

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

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

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

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

运行服务器

运作原理

使用 deep-research-tool

输出结构

输入参数

通用参数

搜索参数（用于Tavilly Search API）

爬网参数（适用于Tavily Crawl API-应用于搜索中的每个URL）

了解文档提示优先级

使用输出路径

LLM说明

示例 CallToolRequest （概念论证）

故障排除

更新日志

v0.1.2（2024-05-10）

v0.1.1

贡献

许可证

相关 MCP

实时网络搜索服务

MySQL查询服务器

Qdrant向量搜索MCP服务器

知识图谱记忆系统

网页研究服务器

Prometheus MCP 服务器

使用 `deep-research-tool`

示例 `CallToolRequest` （概念论证）