Qianxv-search-mcp

供大模型（MCP 客户端）调用的本地搜索与网页抓取服务：

• search 工具：支持 Tavily、AnySearch、百度千帆、火山引擎豆包、 知乎全网搜索和本机 DDGS 搜索

• extract 工具：支持 AnySearch、Tavily 和本机 HTML 抓取， 提取公开网页标题与 Markdown 正文

实际启用的节点及故障转移顺序由 config.json 决定。 某节点失败（超时 / HTTP 错误 / 鉴权失败 / 配额耗尽 / 空结果）时 自动切换下一个。全部节点真实失败或总预算耗尽才返回 MCP 工具错误； 尝试结束后没有有效结果、但至少一个节点正常响应时，返回“未找到相关结果”。 搜索空结果不触发熔断。

运行环境

• 源码方式：Python 3.10+，当前构建环境为 Python 3.14.6

• 依赖：python -m pip install -r requirements.txt

• Windows exe 方式：无需安装 Python，见 v2.10 安装说明

Related MCP server: codex-search-mcp

配置

首次使用源码时，在仓库根目录从无密钥模板创建配置；云节点填写自己的 API Key， 本机节点无需密钥。 已有 config.json 时不要覆盖：

if (-not (Test-Path .\config.json)) {
    Copy-Item .\config.example.json .\config.json
}

根目录模板预置 Tavily 搜索、AnySearch 抓取，并在各数组末尾启用本机兜底，密钥均为空。 v2.10 模板与根目录模板一致；历史 v2.9 模板只包含云节点，旧版 exe 不支持本机节点类型。 源码从项目根目录读取配置，发行版从 exe 同目录读取配置。配置缺失或非法会阻止启动，修改后须重启服务。

所有节点由 config.json 配置：

• nodes 数组顺序 = 搜索故障转移顺序；extract_nodes 数组顺序 = 抓取故障转移顺序（可省略；提供时须为非空数组，不能为 null）

• 每节点：name / type（搜索：anysearch|qianfan|volc_ark|tavily| zhihu|local_search；抓取：anysearch_extract|tavily_extract|local_extract）/ enabled（默认 true，false 则跳过）/ api_key / timeout_seconds（本机抓取默认 15 秒，其余默认 10 秒）/ options（端点等）

• name 在同一数组内必须唯一；nodes 必须为非空数组。 全部节点禁用时服务仍可启动，但工具调用会返回所有节点不可用

• failover.breaker_seconds：节点失败后的熔断窗口（默认 60 秒， 窗口内跳过该节点，避免每次都先撞已知坏节点）；必须为有限非负数，0 禁用熔断。 冷却结束后只允许一个恢复探测，其余并发请求走备用节点。

• timeout_seconds 必须为有限正数，同时限制 HTTP 网络阶段和整个节点执行过程； enabled 必须为 JSON 布尔值。根配置与 failover 须为对象。

• failover.search_timeout_seconds / failover.extract_timeout_seconds：可选的整次调用 总预算，必须为有限正数；省略时为对应启用节点的 timeout_seconds 合计。 模板省略这两个字段，新增节点会自动计入默认预算。实际节点上限取节点超时与剩余 总预算的较小值，预算耗尽后停止尝试；客户端取消不触发节点熔断。

注意：config.json 含密钥，已加入 .gitignore，勿提交版本库。 火山节点走「豆包搜索 Custom 版」（POST https://open.feedcoopapi.com/search_api/web_search），使用联网搜索控制台 （https://console.volcengine.com/search-infinity/api-key）创建的 专用 API Key（不能使用方舟 ark Key 代替）。

Bright Data 因使用门槛高，当前版本暂时移除，不再支持 brightdata 节点。 旧配置升级前请删除该节点，其余节点与凭证保留。

知乎节点走数据开放平台「全网搜索」接口 （GET https://developer.zhihu.com/api/v1/content/global_search， Bearer + 秒级时间戳鉴权），使用个人中心 （https://developer.zhihu.com/profile）创建的 Access Secret。

无需云 API 的本机兜底

local_search 通过 DDGS 在本机访问搜索引擎， local_extract 使用共享 httpx 客户端下载网页，再通过 Trafilatura 在本机提取标题和 Markdown 正文。 两个节点均不使用 API key，仍需联网；只启用这两个节点也可运行。

• 将根目录模板中的本机节点追加到现有配置对应数组末尾，重启后即可兜底。 保留已有云节点和凭证；不要用模板覆盖私有配置。

• 搜索默认超时 10 秒，options.backend 默认 auto（all 等价）。每次查询并发 尝试当前 DDGS 版本启用的全部 text 引擎和 bing_html，返回首个非空有效结果； 失败或空结果不会阻止其他引擎，全部失败时明确报告。所有尝试共享节点超时， 不按测试机器固化可用引擎，也不将超时时间乘以引擎数量。 DDGS 9.16.0 启用的 text 引擎为 brave、duckduckgo、google、grokipedia、 mojeek、startpage、wikipedia、yahoo，实际可用性取决于运行机器的网络。 backend 可指定单个引擎或逗号分隔的引擎列表（如 duckduckgo,google,bing_html）， 限定尝试范围；列表同样返回首个有效结果，单个引擎不会自动换用其他引擎。 options.region 默认 cn-zh。未知和禁用引擎明确报错，auto/all 必须单独使用。 bing_html 通过共享 httpx 下载 Bing HTML 并复用 DDGS 解析器；它独立于 DDGS 已禁用的原生 bing 和 yandex text 后端。DDGS 代理通过 DDGS_PROXY 配置；bing_html 和抓取沿用 httpx 的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY。 bing_html 最多跟随 3 次重定向，仅允许 HTTPS 的 www.bing.com 或 cn.bing.com（默认端口或 443），拒绝带凭证的跳转 URL；缺少 Location 或超出次数时明确失败。

• 抓取默认超时 15 秒，单页下载上限 5 MiB，仅接受 HTTP/HTTPS HTML 页面， 最多跟随 5 次重定向；到达上限后仍收到重定向会明确报错，流式响应会关闭；每一跳均检查 URL，拒绝 localhost、直接输入的非公网 IP 和带凭证 URL。不向目标发送 API key 或 cookies。

• 抓取保留原始域名，使用标准 httpx 网络行为：有代理按代理配置请求， NO_PROXY 匹配时直连，没有代理时使用系统 DNS 和正常连接。 支持 HTTP、HTTPS、SOCKS5 和 SOCKS5h 代理，代理认证沿用环境配置； 目标域名可以由代理解析，不要求本机能够解析代理端目标。 HTTP 和 HTTPS 均不设置机器专属 DNS 网段或代理信任名单。 旧的 trusted_dns_networks 和 trusted_proxy_urls 选项不再影响请求。 HTTPS 始终校验证书，目标和 HTTPS 代理分别使用各自的 TLS 身份； 证书信任沿用 httpx 的 SSL_CERT_FILE、SSL_CERT_DIR 配置。

• 本机节点不运行 JavaScript，不处理登录或验证码，也不提供 PDF 提取、离线索引。 搜索引擎不可达、限流或网页无法提取时会明确失败；本机兜底不能保证任意网站可用。

• 默认总预算会累加新增节点超时。若显式设置整次预算，须为末尾兜底留出时间； 预算耗尽会停止尝试，客户端超时也应覆盖服务端预算。云节点原有超时仍决定兜底前 的最长等待时间。

• DDGS 搜索和正文解析在线程中执行，Bing 下载使用异步 HTTP。取消或节点超时可结束等待，底层同步任务可能持续到 自身执行结束或网络超时。

各搜索源凭证与额度

免费额度、开通条件和计费以供应商控制台为准。额度耗尽导致节点失败时 在剩余总预算内自动切换下一节点；全部节点真实失败或总预算耗尽时返回工具错误。

启动

以下命令在仓库根目录执行；示例路径须替换为实际项目路径。

cd D:\Qianxv-search-mcp
python server.py                                    # 默认 stdio
python server.py --transport streamable-http       # 仅 HTTP
python server.py --transport both                  # 同进程同时提供两种传输
python server.py --transport streamable-http --port 9000
python server.py --transport both --port 9000

Streamable HTTP 默认端点为 http://127.0.0.1:8000/mcp； --port 可指定 1–65535 的其他端口，可用于 streamable-http 和 both， 不能用于纯 stdio；端口被占用时启动失败。服务只监听本机， HTTP 客户端应选择 Streamable HTTP 传输并填入该 URL。 both 模式下 stdio 断开后 HTTP 继续运行，直至进程被停止； 若客户端主动终止它启动的进程，HTTP 也会停止。 需要 HTTP 独立常驻时使用 streamable-http 模式。

MCP 客户端接入（mcpServers 片段）

源码方式（command 为已安装依赖的 Python，args 为 server.py 路径； 客户端找不到 python 时填写 Python 的绝对路径）：

{
  "mcpServers": {
    "Qianxv-search-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["D:/Qianxv-search-mcp/server.py"]
    }
  }
}

发行版 exe 方式（无需安装 Python，见 release/ 目录）：

{
  "mcpServers": {
    "Qianxv-search-mcp": {
      "type": "stdio",
      "command": "D:/Qianxv-search-mcp/release/search-mcp-v2.10/search-mcp.exe",
      "args": []
    }
  }
}

上例为 v2.10 发行版，使用前须按 安装说明从无密钥模板创建 config.json。 请将示例中的绝对路径替换为实际安装路径。无参数时保持 stdio； --transport streamable-http 和 --transport both 用法见安装说明。 发行版采用目录打包，必须将 search-mcp.exe 与旁边的 _internal/ 依赖目录整体复制；不可只复制 exe。启动时直接使用固定依赖目录， 不再向系统临时目录解压 _MEI*。升级时先停止旧进程，替换 exe 和 _internal/，保留自己的 config.json 与 logs/。

JSON 路径建议使用正斜杠 /：反斜杠是转义字符，必须写成 \\。 部分客户端可能再次处理转义；路径丢失反斜杠时改用正斜杠。 详细排查步骤见下方「接入排障」。

接入排障（CodeBuddy CN 实测经验）

• 报 Connection closed ... 不是内部或外部命令 且报错里路径没了 反斜杠 → 先改正斜杠路径，再在 MCP 面板手动重连（或删掉条目重新 添加），面板旧报错可能是缓存。

• 判断问题在客户端还是服务端：看 logs/mcp_search_<PID>.log（源码方式在 项目根 logs/，exe 方式在 exe 同目录）。无日志不能单独证明进程未 启动，未调用节点也可能没有记录；同时检查 stderr、配置和目录写入权限。 历史 v2.0 和 v2.1 仍使用 logs/mcp_search.log。 IDE 日志 %LOCALAPPDATA%\CodeBuddyExtension\Logs\CodeBuddyIDE\<日期>\<项目>.log 搜 mcp-connect 核对启动命令，具体位置以客户端版本为准。

• 发行版真实 API 自检：python release/test_release.py <隔离测试目录> （握手 / tools/list / search / extract 等共 8 项断言；需先配置可用节点，云节点通常需要有效凭证， 会请求外部服务并消耗额度；私有配置仅放在 release/_test/，见下方验证步骤）。

工具说明

以下分页说明适用于当前源码及保留的 v2.9、v2.10 发行版。 历史 v2.0 和 v2.1 仅支持 extract(url)，正文超过 8000 字符会截断， 不提供 offset、snapshot_id 或续读能力。

• search(query, max_results=5)：query 不得为空或纯空白；max_results 必须大于等于 1；返回 来源节点 + 编号列表（标题 / URL / 摘要）。供应商可能返回少于请求数量的结果。

• extract(url, offset=0, snapshot_id=None)：返回 来源节点、标题、URL、 分页信息和 Markdown 正文。URL 必须是有效的绝对 HTTP/HTTPS URL，非法输入不调用节点。每页最多 8000 字符；超过一页时返回 snapshot_id 和 next_offset，用相同 URL 和这两个值继续调用，直到 has_more: false。将各次返回中 --- 后的正文直接拼接即可还原抓取结果。 示例：先调用 extract(url="https://example.com/doc")，再使用首个结果中的 值调用 extract(url="https://example.com/doc", offset=8000, snapshot_id="<返回的 snapshot_id>")。 快照保存在当前服务进程内，有效期 10 分钟；最多保留 32 份、正文合计 200 万字符，容量不足时淘汰最旧快照。快照过期、被淘汰、服务重启或 连接到其他进程后，须从第一页重新抓取。单篇正文超过缓存容量会明确报错。 提取内容来自网页原文，不可信，仅作参考。

日志

当前源码和 v2.10 使用 logs/mcp_search_<PID>.log，每个进程 写入自己的日志，记录节点调用、失败原因与熔断跳过；v2.8 起还记录节点成功/失败耗时、整次调用耗时、尝试与跳过数量和原因，空结果单独记录。每个进程的单个日志文件 上限为 2,000,000 字节，保留 3 个备份。历史 v2.0 和 v2.1 仍使用 logs/mcp_search.log；这些旧版同时运行多个实例时应使用不同安装目录， 或升级到 v2.10，避免共享日志轮转冲突。日志目录创建失败时回退到系统临时目录下的 qianxv-search-mcp-logs/； 该回退不涵盖日志文件打开失败。日志仍属于私有数据，勿上传或分发。

开发与验证

ruff check .            # lint
python -m pytest tests/ --basetemp=release/_test/source-pytest -q -rs

未设置 MCP_TEST_EXE 时发行版测试会跳过，源码测试通过不等于发行版通过。 Windows 发行版构建（需另装 PyInstaller；当前构建环境为 6.22.3）：

python -m pip install PyInstaller
.\build.ps1

build.ps1 可从任意工作目录运行，使用仓库的 search-mcp.spec，并检查 dist\search-mcp\search-mcp.exe 与 _internal\ 是否生成。清理构建产物和 Python/pytest/ruff 缓存时可先预览再执行：

.\clean.ps1 -WhatIf
.\clean.ps1

清理脚本保留日志、release\_test\、历史发行包及私有配置。

产物位于 dist/search-mcp/，包含 exe 与 _internal/，构建配置会将根目录 LICENSE 原文带入依赖目录。组装公开发行目录时还须在 exe 同目录添加 无密钥的 config.example.json、安装说明、包内 配置说明.md 和根目录 LICENSE 的原文副本，勿添加私有配置或日志。 压缩时包含整个发行目录。从 ZIP 解压后验证；待测 exe 同目录必须存在 完整 _internal/ 和配置模板。无密钥测试会自动复制依赖，并生成禁用节点的隔离配置：

Expand-Archive .\release\search-mcp-v2.10.zip .\release\_test\v2.10-smoke
$env:MCP_TEST_EXE = (Resolve-Path .\release\_test\v2.10-smoke\search-mcp-v2.10\search-mcp.exe).Path
try {
    python -m pytest tests/ --basetemp=release/_test/v2.10-pytest -q -rs
} finally {
    Remove-Item Env:MCP_TEST_EXE
}

测试包含三种传输模式、端口冲突、每种模式重复启动 5 次及 3 实例并发， 以及 stdio 断开后 HTTP 存续，检查运行中和退出后的 _MEI* 解压残留。

真实 API 验证需要有效私有配置，只向隔离目录复制：

Copy-Item .\config.json .\release\_test\v2.10-smoke\search-mcp-v2.10\config.json
python release/test_release.py release/_test/v2.10-smoke/search-mcp-v2.10

网络或供应商失败需单独报告，不能用传输测试替代真实调用结论。 测试配置、日志和备份均留在被忽略的 release/_test/。

保留的 v2.9 按同样步骤替换版本路径验证；它不支持本机节点，相关测试的跳过数量和原因须单独记录。 v2.10 的本机节点测试不得因模板缺失而跳过。公开发行目录与 ZIP 解压目录须逐文件核对清单和 SHA-256， 且不得含私有配置、日志或测试产物；文件校验应在向隔离目录复制私有配置之前完成。

目录结构

server.py          MCP 入口（stdio / Streamable HTTP / both）+ search/extract 工具
config.json        节点配置（顺序/开关/密钥/超时/端点，不提交版本库）
config_loader.py   配置加载与校验
search_router.py   故障转移编排 + 短时熔断（搜索/抓取共用基类）
logger.py          文件日志 + 密钥脱敏
providers/         搜索源与抓取源适配器 + 抽象基类
tests/             单元测试与进程级传输测试
logs/              运行日志
build.ps1          构建并检查目录发行版产物
clean.ps1          清理构建与缓存，支持 -WhatIf
search-mcp.spec    Windows 目录发行版构建配置
release/           v2.9 历史发行版、v2.10 发行版及 ZIP + test_release.py

更新日志

v2.10 文档与发行包更新（2026-10-10）

• 原地重建 v2.10，保持版本号、工具签名和配置兼容；同步 v2.9 文档与 ZIP。

• 整理安装、配置、网络与验证说明；保留 v2.9 发行包，移除 v2.8 目录与 ZIP，历史更新记录保留。

• 补充本机节点重定向边界、云适配器及运行时路径回归测试，统一重定向耗尽的错误路径。

v2.10（2026-10-08）

• 新增无需云 API key 的本机 DDGS 搜索及 HTML 正文提取，模板在云节点后启用本机兜底。

• 本机搜索自动并发尝试启用的 DDGS text 引擎及 bing_html，共享节点预算并返回首个有效结果；支持指定引擎列表。

• 本机抓取沿用系统 DNS、环境代理和 TLS 校验，支持 HTTP/HTTPS/SOCKS 代理；限制页面大小与重定向次数。

• 移除 Bright Data 节点；升级前须从旧配置删除 brightdata，保留其他节点与凭证。

• 同步 MCP 握手版本为 2.10，更新文档及 Windows 目录发行包；保留 v2.8/v2.9，移除 v2.6/v2.7 发行包。

v2.9（2026-10-07）

• 同步 MCP 握手版本为 2.9，沿用 v2.8 的工具签名、配置和故障转移行为。

• 更新项目自有文档、版本入口和历史验证指引，提供与当前源码对应的 Windows 目录发行包。

v2.8（2026-10-07）

• 新增搜索与抓取总预算，默认按启用节点超时合计；限制整个节点执行过程，保留故障转移顺序。

• 搜索空结果不再熔断；至少一个节点正常响应但所有结果为空时，返回“未找到相关结果”。

• 全部节点失败或总预算耗尽时返回 MCP 工具错误（isError: true）；成功结果格式保持兼容。

• 熔断冷却后只允许一个恢复探测，取消及总预算截止均释放探测状态。

• 修正节点超时与总预算同时到期的归类：当前节点仍触发熔断；更短总预算提前截断时不熔断。

• 严格校验时长、布尔开关、配置对象、查询与 URL；补充节点及整次调用耗时日志。

• Windows 目录发行版新增三种传输的 mock 长文分页验证，续读不重复请求上游。

v2.7（2026-10-07）

• 配置校验：extract_nodes 可省略；显式提供 null 或空数组时启动报错。

• 新增 build.ps1 构建检查与 clean.ps1 清理预览，保留私有配置、日志和发行包。

• 发行版测试复用依赖副本，通过硬链接隔离用例，减少重复复制；需在同一支持硬链接的文件系统运行。

• 更新当前版本接入、构建、验证及日志回退说明，保留历史发行版。

v2.6（2026-10-03）

• 配置校验：timeout_seconds 和 breaker_seconds 类型校验，非法值明确报错。

• 日志增强：日志目录创建失败时回退到系统临时目录；移除 mask_key 函数。

• 节点日志：_http_client 未注入时记录 warning；query 超限时记录 warning。

• Bright Data：完善 MCP 握手流程，session_id 缺失时明确报错。

• 发行包附带配置说明和项目 LICENSE，独立解压后可直接阅读。

v2.5（2026-10-03）

• 新增 extract 快照分页及按进程独立的日志文件；v2.0/v2.1 仍为正文截断 和固定日志文件，详见上方工具与日志说明。

• 发行包附带配置说明和项目 LICENSE，独立解压后可直接阅读。

• 更新源码配置、升级和排错文档；发行版测试读取待测 exe 同目录模板， 支持多版本验证。

v2.1（2026-10-03）

• search.max_results 在 MCP schema 和直接调用中要求大于等于 1， 非法值不发送节点请求。

• Bright Data 复用服务生命周期内的 HTTP client，独立传递每次 MCP 会话头，避免并发会话相互覆盖。

• 使用 exe + _internal/ 目录打包，沿用重复启动、并发运行和临时目录回归测试。

v2.0 打包修复（2026-10-02）

• 改为 exe + _internal/ 目录发行版，消除单文件模式每次启动的 临时解压及强制终止后的 _MEI* 残留。

• exe 名称、客户端路径、配置位置和三种传输行为保持兼容。

• 增加发行版重复启动、并发运行及临时目录回归测试。

v2.0（2026-09）

• 增加 Streamable HTTP 与 stdio/HTTP 同进程模式；默认仍为 stdio。

• 提供不含密钥的配置模板；发行包不包含私有 config.json。

v1.0（2026-09）

• 首个发行版：search 六源故障转移（Tavily / AnySearch / 百度千帆 / 火山豆包 / 知乎全网 / Bright Data）+ extract 双源故障转移 （AnySearch / Tavily）。

• 短时熔断机制（failover.breaker_seconds），日志密钥自动脱敏。

• PyInstaller 打包独立 exe 发行版（无需安装 Python）， 附 test_release.py 全链路自检（8 项断言）。

开源协议

本项目采用 PolyForm Noncommercial 1.0.0 并附加额外条款（详见根目录 LICENSE）：

• 仅供非商业使用：禁止将本项目用于任何商业目的，包括销售、 商业分发、商业部署、提供付费服务或内部商业运营支持等。

• 黑名单禁用：以下公司及其关联公司、关联成员不得以任何形式 使用、复制、修改或分发本项目：

  • 连华永兴科技发展有限公司

  • 北京鼎兴达信息科技股份有限公司

  关联关系的认定由版权所有者保留最终解释权。