使用说明

mcp开放网络研究

用于网络搜索和内容提取的代理感知模型上下文协议（MCP）服务器。

设计坚固，与各种网络环境兼容，包括使用SOCKS和HTTP代理的网络环境。

特性

动态发动机发现：发动机从以下位置动态加载 src/infrastructure/search/ 目录。添加新引擎只需要一个新的文件夹和文件，而无需修改核心逻辑。
多引擎搜索：聚合Bing、DuckDuckGo和Brave的结果。
深入研究 (search_deep)：递归研究代理，执行多轮搜索、引文提取和答案合成。
短暂下载：使用100MB有界LRU缓存进行深度搜索报告的内存存储，具有10分钟自动过期功能。
集中节流：跨优先级引擎的速率限制管理（搜索和分页冷却）。
智能提取：可配置的提取工具(impit)具有两种操作模式：
- 浏览器模式：包括现代浏览器标头（用户代理、客户端提示），以与需要浏览器标准请求的网站兼容。
- 标准模式：对于不需要浏览器式标识的环境，使用最小的HTTP客户端配置文件。
结果抽样：可选的基于LLM的过滤，以评估结果相关性。
内容提取：网页访问和标记提取工具(visit_webpage)使用无头浏览器。
代理支持：完全支持SOCKS5、HTTPS和HTTP代理。
配置：可通过环境变量和CLI参数进行配置。
部署：Docker镜像可用于生产和测试。

学分

该项目包括以下贡献者的工作：

马纳夫·昆德拉：服务器的初始实现。
A看：添加了多个搜索引擎和Docker支持。
mzxrai：核心逻辑 visit_page 工具。

安装和快速启动

Docker（推荐）

最新稳定版本：

docker pull ghcr.io/rinaldowouterson/mcp-open-webresearch:latest
docker run -p 3000:3000 ghcr.io/rinaldowouterson/mcp-open-webresearch:latest

测试/调试映像：

docker pull ghcr.io/rinaldowouterson/mcp-open-webresearch:test

本地安装

要在本地运行服务器（例如，在Claude Desktop或Cline中）：

[！注意] 替换 /absolute/path/to/project 根据您的实际项目路径。

配置(mcp_config.json):

{
  "mcpServers": {
    "open-webresearch": {
      "command": "npm",
      "args": [
        "run",
        "start:sampling",
        "--silent",
        "--prefix",
        "/absolute/path/to/project"
      ],
      "headers": {},
      "disabled": false
    }
  }
}

远程服务器（流式HTTP）

端点： http://localhost:3000/mcp

配置：

{
  "mcpServers": {
    "open-webresearch": {
      "serverUrl": "http://localhost:3000/mcp",
      "headers": {}
    }
  }
}

客户端配置和超时

深度搜索过程可能需要几分钟才能完成。一些MCP客户端（如Cline和RooCode）的默认超时为60秒，这将导致操作失败。

您必须在客户端设置中配置更高的超时时间。

克莱恩(`cline_mcp_settings.json`)

添加 "timeout" 参数（秒）。推荐： 1800 （30分钟）。

{
  "mcpServers": {
    "open-webresearch": {
      "disabled": false,
      "timeout": 1800,
      "type": "stdio",
      "command": "npm",
      "args": [
        "run",
        "start:sampling",
        "--silent",
        "--prefix",
        "/absolute/path/to/mcp-open-webresearch"
      ],
      "autoApprove": []
    }
  }
}

房间代码(`mcp_settings.json`)

RooCode也尊重 timeout 参数。

{
  "mcpServers": {
    "open-webresearch": {
      "disabled": false,
      "timeout": 1800,
      "command": "npm",
      "args": [
        "run",
        "start:sampling",
        "--silent",
        "--prefix",
        "/absolute/path/to/mcp-open-webresearch"
      ],
      "alwaysAllow": []
    }
  }
}

反重力/风帆(`mcp_config.json`)

Antigravity/Windsurf本机处理长时间运行的工具，但如果它们允许您配置超时，最好这样做。

{
  "mcpServers": {
    "open-webresearch": {
      "command": "npm",
      "args": [
        "run",
        "start:sampling",
        "--silent",
        "--prefix",
        "/absolute/path/to/mcp-open-webresearch"
      ],
      "disabled": false
    }
  }
}

开发者指南：添加新引擎

要添加新的搜索引擎，请执行以下操作：

创建目录: src/infrastructure/search/{engine_name}/
实施逻辑：创建 {engine_name}.ts 使用获取/解析逻辑。

导出接口：创建 index.ts 导出 SearchEngine 接口：

import type { SearchEngine } from "../../../types/search.js";
import { searchMyEngine } from "./my_engine.js";
import { isThrottled } from "../../throttle.js"; // Optional

export const engine: SearchEngine = {
  name: "my_engine",
  search: searchMyEngine,
  isRateLimited: () => isThrottled("my_engine"),
};

重启：服务器将自动发现并加载新引擎。

构建并运行

本地地

# 1. Clone
git clone https://github.com/rinaldowouterson/mcp-open-webresearch.git
cd mcp-open-webresearch

# 2. Install
npm install

# 3. Build & Start
npm run build
npm start

码头工人

# Production
docker build -t mcp-websearch .
docker run -p 3000:3000 mcp-websearch

# Testing
npm run test:docker

测试

单元和E2E测试

用途 维测试 用于测试。包括对所有发现的发动机进行动态合同测试。

npm test

符合性测试

使用本地模拟服务器验证“智能获取”行为（User-Agent标头）的使用情况。

npm run test .test/engines/smart_fetch_mode.test.ts

基础设施验证

验证Docker镜像构建和基本功能。

npm run test:infrastructure

可用脚本

命令	描述
`npm run build`	将TypeScript编译为 `build/` 文件夹。
`npm run watch`	重新推荐文件更改。
`npm run inspector`	启动MCP检查器UI。
`npm start`	运行已编译的服务器。
`npm test`	运行本地测试。
`npm run test:docker`	在Docker容器中运行测试。
`npm run test:infrastructure`	验证docker镜像。
`npm run generate-certs`	生成用于测试的自签名证书。

配置

配置是通过环境变量或CLI参数进行管理的。

变量	默认值	描述
`PORT`	`3000`	服务器端口
`PUBLIC_URL`	`http://localhost:port`	下载链接的公共URL。
`ENABLE_CORS`	`false`	启用CORS。
`CORS_ORIGIN`	`*`	允许的CORS来源。
`DEFAULT_SEARCH_ENGINES`	`bing,duckduckgo,brave`	默认引擎列表。
`ENABLE_PROXY`	`false`	启用代理支持。
`HTTP_PROXY`	-	HTTP代理URL
`HTTPS_PROXY`	-	HTTPS代理URL
`SOCKS5_PROXY`	-	SOCKS5代理URL（最高优先级）。
`SAMPLING`	`false`	启用结果采样。
`SKIP_IDE_SAMPLING`	`false`	首选外部API而不是IDE。
`LLM_BASE_URL`	-	外部LLM API基础URL
`LLM_API_KEY`	-	外部LLM API密钥。
`LLM_NAME`	-	外部LLM模型名称。
`LLM_TIMEOUT_MS`	`30000`	外部LLM调用超时。
`DEEP_SEARCH_MAX_LOOPS`	`20`	最大研究迭代次数。
`DEEP_SEARCH_RESULTS_PER_ENGINE`	`5`	每台发动机每轮的结果。
`DEEP_SEARCH_SATURATION_THRESHOLD`	`0.6`	提前停止研究的门槛。
`DEEP_SEARCH_MAX_CITATION_URLS`	`10`	引用时可访问的最大URL数。
`DEEP_SEARCH_REPORT_RETENTION_MINUTES`	`10`	下载过期时间（分钟）。
`WRITE_DEBUG_TERMINAL`	`false`	将调试输出记录到stdout。
`WRITE_DEBUG_FILE`	`false`	将调试输出记录到文件中。

CLI参数

CLI参数覆盖环境变量。

参数	描述
`--port <number>`	要收听的端口
`--debug`	启用调试日志记录（stdout）。
`--debug-file`	启用调试日志记录（文件）。
`--cors`	启用CORS。
`--proxy <url>`	代理URL（http、https、socks5）。
`--engines <items>`	以逗号分隔的引擎列表。
`--sampling`	启用采样。
`--no-sampling`	禁用采样。

搜索管道和评分

服务器使用多阶段管道来聚合和优化搜索结果：

1.多引擎检索

并发请求被发送到所有配置的引擎（Bing、Brave、DuckDuckGo）。原始结果收集到一个池中。

2.共识评分和重复数据删除

结果按其规范URL（协议/www无关哈希）分组。

去重：同一URL的多个条目被合并。
评分A. consensusScore 为每个唯一的URL计算：
- 倒排和：各引擎的反向排名之和（$1/rank$）。位置越高，得分越高。
- 发动机增压：将总和乘以标识URL的唯一引擎的数量。这将优先考虑多提供商协议。
排序：最终列表按计算结果排序 consensusScore 按降序排列。

3.LLM采样（可选）

如果 SAMPLING=true，将排名靠前的结果发送给LLM，以评估与查询的语义相关性。

过滤：采样充当二进制过滤器。它删除了被确定为不相关的结果（垃圾邮件、离题）。
最后一组：保留原始共识得分。只有列表的组成发生了变化。

LLM抽样策略

启用采样后，服务器将遵循分层解析逻辑来选择要使用的LLM：

SKIP_IDE_SAMPLING	IDE可用	已配置API	分辨率
`false` （默认）	✅	✅	IDE采样
`true`	✅	❌	IDE采样
`false`	❌	✅	外部API
`true`	✅ 或❌	✅	外部API
`false` 或 `true`	❌	❌	无采样

[！提示] 您可以使用没有API密钥的模型 LLM_API_KEY 值是可选的。

[！重要] 深度搜索兼容性：The search_deep 该工具严格要求LLM功能（通过IDE或API）。如果两者都不可用，该工具将出现在MCP列表中，但在执行时会抛出错误。

工具文档

`search_deep`

用于深入调查的递归研究代理。搜索多个来源，提取引文，并综合一个全面的答案。

需要LLM采样功能。

输入：

{
  "objective": "Deep research goal",
  "max_loops": 3,
  "results_per_engine": 5,
  "max_citation_urls": 10,
  "engines": ["bing", "brave"],
  "attach_context": false
}

输出： 包含参考列表的结构化Markdown报告。如果已配置，a 下载URL 在输出的顶部允许将结果作为文件下载。

`search_web`

跨配置的引擎执行搜索。

输入：

{
  "query": "search query",
  "max_results": 10,
  "engines": ["bing", "brave"],
  "sampling": true
}

`visit_webpage`

访问URL并返回标记内容。

输入：

{
  "url": "https://example.com/article",
  "capture_screenshot": false
}

`set_engines`

更新默认搜索引擎。

输入：

{
  "engines": ["duckduckgo", "brave"]
}

`get_engines`

返回已配置的搜索引擎。

`set_sampling`

启用或禁用结果采样。

输入：

{
  "enabled": true
}

`get_sampling`

返回当前采样状态。

📥 短暂下载

深度搜索结果通过内存缓冲区缓存提供。

存储：报告存储为 Buffer C++堆中的对象，以避免V8字符串内存限制。
过期：每个条目都会完全过期 10分钟 创作之后。访问操作(get)做不延长生存时间（TTL）。
内存安全：缓存受 100MB天花板当达到限制时，最近最少使用（LRU）驱逐策略会删除最旧的条目。
URL配置：链接生成取决于 PUBLIC_URL 变量，以确保在代理环境中可访问的下载端点。

路线图

[x] 深度搜索：递归研究和综合引擎。
[ ] 无密钥GitHub适配器：实现GitHub内容访问适配器。

许可证

Apache许可证2.0。看许可证.

使用说明

mcp开放网络研究

特性

学分

安装和快速启动

Docker（推荐）

本地安装

远程服务器（流式HTTP）

客户端配置和超时

克莱恩(cline_mcp_settings.json)

房间代码(mcp_settings.json)

反重力/风帆(mcp_config.json)

开发者指南：添加新引擎

构建并运行

本地地

码头工人

测试

单元和E2E测试

符合性测试

基础设施验证

可用脚本

配置

CLI参数

搜索管道和评分

1.多引擎检索

2.共识评分和重复数据删除

3.LLM采样（可选）

LLM抽样策略

工具文档

search_deep

search_web

visit_webpage

set_engines

get_engines

set_sampling

get_sampling

📥 短暂下载

路线图

许可证

相关 MCP

网页内容抓取服务

网页内容抓取服务器

网页搜索 MCP 服务

YouTube 字幕获取 MCP 服务

网页研究服务器

网页内容获取工具

克莱恩(`cline_mcp_settings.json`)

房间代码(`mcp_settings.json`)

反重力/风帆(`mcp_config.json`)

`search_deep`

`search_web`

`visit_webpage`

`set_engines`

`get_engines`

`set_sampling`

`get_sampling`