web-search-server

面向 AI 的本地 Web 搜索 MCP 服务：DeepSeek 官方 Search/Fetch 为首选通路， 免费引擎聚合与本地渲染回退链作为自动降级，另含站点定向搜索。

• 传输：stdio（在 MCP 客户端里注册本地 MCP）；默认端口 8011（HTTP 模式时）

• 运行：python server.py（依赖见 requirements.txt；可选依赖缺失会自动降级）

• 测试：python -m pytest tests/ -q（全部为 mock 测试，不依赖网络）

搜索与抓取通路

改造成「官方优先 + 本地降级」两层，避免把可靠性押在不稳定的免费抓取引擎上。

抓取顺序是「先便宜后兜底」：本地解析普通页面只要 0.5s 且不花钱，只有被拦截或解析 失败才交给官方 Fetch（它还能过 JS 渲染页）。整条回退链有总预算约束（_FALLBACK_BUDGET = 38s），每一级启动前检查剩余预算，不够就跳过并在报错里说明 —— 否则「官方 20s + Crawl4AI 30s + 浏览器 30s」逐级累加会把工具自身的 45s 超时撞穿（实测表现为抓一个 只需 10s 的页面等到 45s 超时）。

为什么：免费引擎这条路要一直打补丁——实测 ddgs 后端会成批失效（2026-10 只剩 yandex/duckduckgo 可用）、Bing 直抓对中文查询返回泛化词结果（「城市洪涝 海绵城市」 返回百度百科「城市」词条）、Google 无代理必然为空、反爬标记还会误伤正常页面。 官方 Search 自带重排与权威性评分，官方 Fetch 直接给 Markdown，把这一整层不确定性 换成了可预期的接口。

官方通路要点：

• 鉴权与 DeepSeek 模型 API 同源（Bearer key），但走独立的工具端点，不消耗模型 轮次（区别于 DeepSeek Harness 里 /anthropic/v1/messages + web_search_20250305 服务端工具那条通路——那条每搜一次要花一个模型轮次）。

• 计费：Search / Fetch 各 5 元每 1000 次成功请求；失败、无结果、超时不计费， count 只控制条数不影响单次价格。

• 限速：账号级各 5 QPS（本地已先行限流）。

• 搜索语法：site:、-site:、-关键词、-"短语"、"精确短语"、lang:、 after:、before:，可组合。time_range=day|week|month|year 会自动转成 after: 日期。

• 结果字段：rerank_score（0-3，≥1.5 为优质）、authority（0-4，≥3 极权威， -1 未知）、snippet（约 100-200 字）、summary（约 600-800 字）、date（UTC）。

• 需要正文时用 need_content=true 在同一次检索里取回，比逐条抓取便宜 N 倍。

配置：把有效的 key 放进环境变量 DEEPSEEK_API_KEY（或 MCP 客户端 env）。 key 失效/未配置/余额不足/限流时不会报错中断，而是自动降级到免费通路并在结果末尾 说明原因（例如「DeepSeek 鉴权失败（401）：DEEPSEEK_API_KEY 无效或已过期」）。

Related MCP server: Web Search MCP Server

工具清单（18）

站点定向搜索

直接调各平台 API / 复用浏览器会话取结构化结果，比通用网页搜索准确（GitHub 走公开 REST API，无需任何凭据）。

Twitter(X) 接入（twitter_search）

X 没有免费公开搜索 API，未登录访问 x.com 是空白页（2026-10-04 实测）； 公共 Nitter 镜像当天也全部不可用（Cloudflare / Anubis / 429）。所以读 X 必须借登录态， 三条通路按推荐顺序：

① 遇到反爬/登录墙，回退用 Playwright MCP 驱动已登录的浏览器（零配置，推荐）

本项目的回退原则：本地抓取/渲染过不去（反爬、登录墙）时，最终回退是交给 Playwright MCP（mcp__playwright__*，browser_ 工具）在用户已登录的浏览器里打开页面完成任务* —— 不自己造浏览器、不要密码。做法：让 Playwright MCP 以 --browser msedge --executable-path <系统 Edge> --extension 的扩展模式桥接你自己的浏览器， X 登录态就在里面（2026-10-04 实测：x.com 搜索页可直接抽到实时推文）。读 X 时： browser_tabs(action="new", url=...) 开新标签页（别动扩展 connect 页），再用 browser_evaluate 抽取 article[data-testid="tweet"]。

② cookie 会话（静默，本工具自带）

不需弹浏览器时用这条路：

1. 在已登录 x.com 的浏览器（如 Edge）里：F12 → Application → Cookies → https://x.com

2. 复制 auth_token 与 ct0 两个值

3. 配到 MCP 客户端的 env（如 ZCode：%USERPROFILE%\.zcode\cli\config.json → mcp.servers.web-search-server.env）：

"env": {
  "X_AUTH_TOKEN": "<auth_token 的值>",
  "X_CT0": "<ct0 的值>"
}

4. 重启 MCP 客户端后生效。cookie 等同于账号凭据：只放本机 env，不要写进仓库、 笔记、聊天记录或记忆文件（本仓库代码也不会打印/落盘它们）。

   • 登录态过期时工具会提示「cookie 无效或已过期」，重新复制即可。

③ 调试端口浏览器（进阶，本工具自带）

Edge/Chrome ≥136 禁止用默认配置目录开 --remote-debugging-port（实测 Edge 154 拒绝），且实测把 Edge 默认配置复制到独立目录启动后 X 仍是未登录。所以这条路需要：

# 用独立配置目录启动（首次在该窗口里登录一次 X，之后登录态常驻）
& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" `
  --user-data-dir="<独立目录>\edge-agent-profile" --remote-debugging-port=9222

保持该实例运行，本工具的浏览器后端会新开标签页搜索、抽取后关闭（用户可见）。 Chrome 以调试端口启动期间不要用它登录敏感账号（调试端口对本机程序开放）。

用法

twitter_search("audio llm")                 # 最新推文
twitter_search("audio llm", mode="top")     # 热门
twitter_search("from:elonmusk grok")        # 读某人推文（X 搜索语法通用）
twitter_search("@elonmusk grok")            # 提及

返回：@handle、时间、正文、互动数（回复/转推/喜欢/查看）、推文链接。

实现说明（改版自愈）

主要环境变量

已知环境依赖

crawl4ai（抓取回退链的本地渲染级）依赖 pyOpenSSL，而 pyOpenSSL 25.x 与 cryptography 46 不兼容——import OpenSSL.crypto 会抛 AttributeError: module 'lib' has no attribute 'GEN_EMAIL'。此时 crawl4ai 整级失效 （代码已做保护：导入异常只降级为「不可用」，不会打断回退链）。如需恢复该级：

D:\anaconda3\python.exe -m pip install "pyOpenSSL>=26.0,<26.3"   # 兼容 cryptography 46

若装包报 WinError 5 拒绝访问，是安全软件拦截删除，用提权安装：

Start-Process -Verb RunAs -Wait D:\anaconda3\python.exe -ArgumentList '-m','pip','install','pyOpenSSL==26.2.0'

⚠️ 不要直接 pip install --upgrade pyOpenSSL：最新版会连带把 cryptography 升到 49+， 而升级过程一旦在删除 cryptography\hazmat\bindings\_rust.pyd 时被拦， 会留下 dist-info 已删、文件残缺的半安装状态，导致所有依赖 cryptography 的程序 import 失败。