web-search-mcp

多供应商 LLM 服务端搜索网关：把搜索请求转发给支持服务端搜索（DEEP_SEARCH）的 LLM 中转网关，多供应商自动兜底。提供 REST 与 MCP（streamable HTTP）两种接口。

零第三方依赖（纯 Go 标准库），Docker 多阶段构建，镜像解压约 15MB
中文请求体统一 ASCII 转义（\uXXXX），规避网关中文乱码问题
支持 ECH（Encrypted Client Hello）

环境变量

变量	说明
`PORT`	监听端口，默认 8080
`WEBSEARCH_TIMEOUT_MS`	默认单请求超时（毫秒），默认 90000；可被 `X-Search-Config.timeoutMs` 覆盖

网关配置全部由请求头动态提供，修改配置无需重启容器。

请求头协议

头	示例	说明
`X-Search-Config`	`{"timeoutMs":90000,"retries":3,"dns":["https://223.6.6.6/dns-query"]}`	全局参数（可选）
`X-Search-Providers`	网关数组 JSON	按数组顺序兜底，改配置即切换，无需重启

X-Search-Config 全局参数

字段	说明
`timeoutMs`	单请求超时（毫秒），0=默认
`retries`	网络失败/5xx 重试轮数，0-10，默认 3
`dns`	DoH 端点数组（`https://` 开头），ECH 查询用，顺序轮询；缺省用内置端点

X-Search-Providers 数组元素

{
  "name": "primary",
  "baseURL": "https://api.example.com/v1",
  "apiKey": "sk-你的key",
  "model": "grok-4.3",
  "apiStyle": "auto",
  "channel": "auto",
  "ech": true,
  "echHost": "cdn.example.net",
  "timeoutMs": 90000,
  "ips": ["1.2.3.4"]
}

字段	必填	说明
`name`		供应商名（错误报告/日志用）
`baseURL`	✅	网关地址，如 `https://api.example.com/v1`
`apiKey`	✅	Bearer token
`model`	✅	模型名
`apiStyle`		`responses` / `chat` / `auto`（缺省 auto，按模型名含 `-search` 判 chat）
`channel`		`auto`/`openai`/`grok`/`deepseek`/`gemini`/`ds-search`/`kimi`/`glm`/`qwen`/`perplexity`
`params`		通道参数透传（如 `searchMode`、`search_context_size`）
`ech`		是否启用 ECH（默认 false）
`echHost`		查询 HTTPS 记录（获取 ECHConfig）的域名；缺省=baseURL 的 host
`timeoutMs`		单网关超时覆盖
`ips`		调试：显式 IP 列表（`ip` 或 `ip:port`），跳过 DNS 解析
`priority`		预留排序字段

ECH（Encrypted Client Hello）

网关配置开启 ech: true 时，通过 echHost（缺省为 baseURL 的 host）获取 ECHConfig 并用于 TLS 握手。

HTTP API

端点	说明
`POST /search`	`{"query":"...","provider":"可选"}` → 搜索结果 JSON
`POST /mcp`	MCP Streamable HTTP（initialize/tools/list/tools/call，非流式）
`GET /health`	健康检查
`GET /providers`	说明网关由请求头动态提供

POST /search 响应

{
  "ok": true,
  "query": "...",
  "answer": "回答文本（含 [n](url) 来源引用）",
  "searched": true,
  "sources": [{"url": "https://...", "title": "..."}],
  "usage": {"input_tokens": 112, "output_tokens": 500},
  "provider": "primary",
  "model": "grok-4.3",
  "search_calls": 1,
  "latencyMs": 15700
}

全供应商失败时返回 502 + errors 数组（每个供应商的失败原因）。

MCP 接入（Reasonix / Claude 等客户端）

在 MCP 客户端配置 HTTP MCP server：

[[plugins]]
name    = "web-search"
type    = "http"
url     = "https://your-domain.example.com/web_search/mcp"
headers = { "X-Search-Providers" = "${SEARCH_PROVIDERS}" }
call_timeout_seconds = 180

工具名 web_search，参数：query（必填）、provider（可选，指定供应商）。

网络容错

每次请求重新 DNS 解析（不缓存固定 IP，天然支持 CDN 节点轮换）
连接失败/超时/5xx 自动重试（默认 3 轮，retries 可调）；每轮重新解析、跳过已失败 IP
4xx（403 等）不重试，网关错误原文透传（据此换模型/网关）

开发

go test ./...        # 44 用例：配置/ECH/DoH/通道/MCP 协议全覆盖
go build -o bin/web-search-mcp .

Docker 部署

docker run -d --name web-search -p 8080:8080 \
  -e PORT=8080 \
  ghcr.io/mdzz-123/web-search-mcp:latest

网关配置经请求头传入（见上文协议），容器无需任何供应商环境变量。