websearch-mcp

给你的 AI 装上联网搜索能力。 多引擎聚合 · 零 API Key · 自带管理面板 · 内置节点池自运维。

一条命令装好，打开面板填个订阅链接（可选），AI 客户端立刻获得联网搜索。 不依赖任何商业搜索 API，不需要申请 Key。

特性

Related MCP server: DuckDuckGo MCP Server

快速开始

# 1. 装（一条命令，幂等，可重复执行）
bash install.sh

# 2. 点开它打印的链接（自动登录，不用复制口令）
#    在「机场订阅」填你的订阅链接 → 保存 → 启动代理
#    （不填也能用：国内引擎开箱即用）

# 3. 复制面板里「把它接到你的 AI 客户端」的配置，粘到 AI 客户端

装完会打印管理面板地址，面板里用人话告诉你当前状态：

🟢 搜索服务正在运行          监听 8300 端口，可以接受 AI 客户端连接
🟡 没有配置代理（只搜国内网站） 现在能搜到百度、必应、360、微信等国内源。
                             想搜 Google 需要填一个订阅链接。[去配置]
🟢 凭据文件权限安全          订阅链接和口令只存在本机，权限 600

手动启动（不想用 install.sh）：

python -m venv venv && ./venv/bin/pip install -e .
WS_MCP_PORT=8300 ./venv/bin/python -m websearch.server

接入 AI 客户端

MCP 服务走 HTTP + Bearer token（面板里一键生成配置）。以 Claude Desktop 为例：

{
  "mcpServers": {
    "websearch": {
      "url": "http://<你的主机>:8300/mcp",
      "headers": { "Authorization": "Bearer <面板里复制的 token>" }
    }
  }
}

不同客户端的配置格式不通用，面板会给当前主机的正确写法（自动按请求 Host 生成 URL）。

工具一览

所有工具返回都带 meta，AI 能据此判断这次结果可信度如何——几个源挂了、 覆盖率多少、有没有走缓存。静默失败是最坏的失败。

能搜什么

关于节点：本服务内置「节点池」——自动从公开源搜集免费节点、实测筛选、 按站点可达性选路（不只看延迟），出网断了自己换。但免费节点寿命以小时计， 长期稳定出网还是建议用自己的订阅（填进面板即可，选路优先）。

已实测证伪的两条路（别重复投入）：

• 公开免费代理池（SOCKS/HTTP）：直测存活率 ~17%，且大量出口 IP 已被目标站拉黑

• 公共 SearXNG 实例：实测多批全部不可达（域名被 DNS 投毒）

工程要点

反爬认知（重写一次要几天）

• 必应投毒：识别为爬虫时不返回 403，而是返回一批与查询完全无关的结果。 HTTP 200、结构完整、每次 10 条，HTTP 层检测完全无效——只有相关性比例 校验能抓（相关率 <30% 判投毒）。数「有没有命中」会漏，投毒会混进 1-2 条碰巧相关的。

• 必应对 UA 极敏感：Firefox/Safari/Edge UA 下开始投毒，Chrome/Windows 正常。 UA 池 Chrome Win 占一半，随机轮换是负优化。

• 移动端比 PC 端好破：百度 PC 返回安全验证页、搜狗 PC 返回 antispider， 移动端都能拿到完整结果页（代价是各写一套解析器）。

• Accept-Encoding 必须按实际能力声明：写 br 而没装 brotli → httpx 解不开 → 不报错、直接乱码、表现成「引擎解析 0 条」，极难定位。

• 数字串查询要区别对待：搜索引擎对陌生数字返回「无结果 + 模糊推荐页」， 按投毒判定会把整批引擎熔断——实测一次纯数字查询熔断 9 个引擎 600 秒。

实时性设计（硬要求）

• 缓存 TTL 仅 5 分钟且只用于防反爬，不是数据源

• fresh=true 或传 time_range 自动绕过缓存读，但仍写缓存

• 每次返回带 fetched_at + realtime + 逐条 cached 标记

• PARSER_VERSION 在缓存 key 里：解析器升级后不会读到旧格式 URL

工具 schema 红线（改工具前必读）

严格模型（Step-5-Preview / GLM-5.3-Flash / Deepseek-V4.1-Flash）逐字校验 工具定义，两个构造会让整个请求在进模型前被拒（11129 / 11133，inputTokens: 0， 表现是「工具一多就全线崩」）：

1. 不许有 outputSchema —— 所有 @mcp.tool() 必须带 output_schema=None （用 _MCP 字典展开）。FastMCP 默认会给返回 dict 的工具自动生成 {"additionalProperties": true, ...} 的 outputSchema，纯负担；

2. inputSchema 不许有 anyOf —— 参数要支持多形态（如 urls 收字符串/数组）， 类型写 Any，别写 str | list[str]（后者生成 anyOf）。

tests/test_tool_schema.py 把这两条锁死了。

抓取的两个硬约束（2026-10-19 生产事故复盘）

• HTTP/2 默认关闭（WS_HTTP2=1 才开）。ValueError: semaphore released too many times 来自 httpcore 的 HTTP/2 流控信号量在失败/取消路径上 release 越界，只走 h2 时出现， 升级 httpcore 也救不了。而这个产品全是一次性整页抓取，连接复用 HTTP/1.1 池已经拿到， h2 多路复用零收益 —— 不值得为它背一个没有安全失败模式的状态机。

• 硬超时必须用 shield 隔开。wait_for(协程) 到点会先 cancel、再等收尾做完 才抛超时；而 DNS 解析跑在线程池里（取消等待方停不了那个线程）、httpcore/ssl 的关闭 用了 shield —— 两样都取消不动，配 17s 的硬超时实测被拖到 24s。 现在的语义是「到点就返回，收尾留给后台」，elapsed_ms 因此不再超预算。

测试

PYTHONPATH=src ./venv/bin/python -m pytest tests/ -m 'not online'   # 离线用例
PYTHONPATH=src ./venv/bin/python scripts/mcp_e2e.py                 # MCP 协议 E2E
PYTHONPATH=src ./venv/bin/python scripts/dump_tool_schema.py        # 打印 tools/list 全量 schema
PYTHONPATH=src ./venv/bin/python scripts/user_perspective_check.py  # 用户视角协议验证
PYTHONPATH=src ./venv/bin/python scripts/stress.py                  # 压测

当前基线：484 passed（离线，Linux；Windows 为 467 passed + 17 条 POSIX 权限用例自动跳过）。scripts/diag/ 下有各引擎的独立诊断脚本 （解析器改不动时用它们抓真实 HTML 比对）。

平台说明：权限类断言（凭据文件 600 / 目录 700 / 一键登录票据工具） 依赖 POSIX 权限位，在 Windows 上会自动 skip —— Windows 的 chmod 只能切只读位， stat 恒报 0o666，这类断言在那里没有意义。服务本身请部署在 Linux / WSL / 容器 / Termux，Windows 直跑会被权限自检拒绝（安全设计，不是 bug）。

部署

服务是普通 Python 进程，任何常驻环境都能跑：

• systemd：ExecStart=/opt/websearch-mcp/venv/bin/python -m websearch.server 加 Restart=always；install.sh 会给出对应 unit 文件

• 无 systemd（容器 / 安卓 Termux / 路由器）：用任何进程守护 （tmux + while true 循环、runit、supervisord 都行）—— 关键是崩溃后自动重拉

• 端口：8300（MCP 服务）+ 8500（管理面板，只监听内网）

• 日志重定向要在服务所在环境内做，别在宿主 shell 里 >> /opt/... （宿主没有 /opt 会空转循环）

scripts/ctl.sh 提供 status|restart|logs|health|warmup|token|test。

依赖

• Python ≥ 3.11（pyproject.toml 声明）

• 核心依赖：fastmcp、uvicorn、starlette、httpx、socksio （socksio 是 httpx 走 SOCKS 代理的必需品，漏装表现为「代理直测全 ImportError」）

• 可选：trafilatura（正文提取准确率更高，没装自动降级内置提取器）

• 出网组件：sing-box（面板会检查并给出安装方法）

架构

websearch-mcp/
├── src/websearch/
│   ├── server.py         # MCP 服务入口（9 工具）+ 生命周期
│   ├── orchestrator.py   # 搜索编排：扇出 → 熔断 → 校验 → 融合 → 早停
│   ├── engines.py        # 引擎定义（build/parse）+ 结果过滤
│   ├── authority.py      # 来源权威度分级
│   ├── fusion.py         # 多引擎结果融合排序（权威加权 / SimHash 去重）
│   ├── governor.py       # per-engine 熔断 + 限流 + 健康画像
│   ├── http_pool.py      # 连接池（代理 / 直连双通道）+ 请求闸门
│   ├── cache.py          # 实时性缓存（TTL 5min + PARSER_VERSION）
│   ├── nodes/            # 节点池：搜集 / 探测 / 选路 / 本地代理
│   ├── proxy/            # 出网：订阅解析 / 代理门控 / 管理面板
│   └── text.py           # 相关性校验 / SimHash / 摘要清洗
├── tests/                # 484 离线用例
├── scripts/              # 安装 / 启动 / 运维 / 诊断 / E2E / 压测
└── docs/                 # 代理与出网配置详解

License

MIT —— 见 LICENSE。