之前自定义上游与 Exa 都写死 500 字,换上游就等于悄悄丢内容。现在: - 默认原样返回整段 snippet(只压平空白) - 传 maxSnippetLength: N 才截断到 N 字并补省略号;0 / 负数 / 非数字一律视为不传 - 三路上游(自定义 /search、Parallel、Exa)统一按同一参数处理 - 上游报错时的响应片段仍固定截 200 字(那是诊断信息,不参与该参数)
3.5 KiB
web_search
网页搜索 MCP server 的本地重构版(上游开源实现:@sheep233_/dsh-web-search-free,MIT)。
零运行时依赖,只用 Node 内置 fetch(Node ≥ 18),无需 npm install,直接 node server.js 启动。
三路上游
| 条件 | 走哪 | 说明 |
|---|---|---|
请求带了 X-Web-Search-Base-Url |
你的 POST {base}/search |
key 可选(Authorization)。失败直接报错,不静默退回免费后端 |
| 没带 | Parallel(免费匿名) | 失败自动退 Exa |
| stdio 模式 | 只能免费 | stdio 没有 HTTP header |
自定义上游的协议:
POST {base}/search
Authorization: Bearer <key>
Content-Type: application/json
{"query":"2027山东省考公告","max_results":5}
{"query":"...","type":"text2text","results":[{"title":"...","url":"https://...","snippet":"..."}]}
响应归一化成 [{url, title?, snippet?, publishedAt?}]:results[] 里没有 url 的条目丢弃,
snippet 压平空白后原样返回(默认不截断);调用方传 maxSnippetLength: 3000 才会按该长度截断,
published_at / publishedAt / publish_date 任一存在则映射为 publishedAt。
工具参数
| 参数 | 必填 | 说明 |
|---|---|---|
query |
是 | 搜什么 |
numResults |
否 | 返回条数,默认 8 |
maxSnippetLength |
否 | 每条 snippet 的最大字符数;不传 = 不截断(上游常给整段正文,长文本请自行控预算) |
结构
| 文件 | 职责 |
|---|---|
core.js |
搜索后端:自定义 /search + Parallel / Exa 免费 MCP 端点封装 + 响应解析 |
mcp.js |
MCP 协议层:web_search 工具定义 + JSON-RPC 分发 + 从 header 取上游参数 |
server.js |
入口:CLI 参数 + stdio / HTTP/SSE 双传输 |
本地启动
# HTTP/SSE 模式(默认 127.0.0.1:3100)
node server.js --http --port 3100
# stdio 模式(Claude Code / Codex 直接拉起时用)
node server.js
MCP 端点:
POST /— Streamable HTTP(也接受Accept: text/event-stream)GET /sse+POST /messages— 老式 SSE 传输GET /health— 健康检查
环境变量(均可选):
EXA_API_KEY— 提升 Exa 匿名限额SEARCH_TIMEOUT_MS— 上游搜索超时,默认 30000
上游地址 / 鉴权不是环境变量:由调用方随每个请求用 header 带入(见上面「三路上游」),
agent 侧写在 config.yml 的 mcp_servers[name=web_search].headers。换接口只改 YAML + 重启 core,
不碰 .env、不重建镜像;容器自身不存任何平台密钥。
Docker
docker-compose.yml 中的 mcp_web_search 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 npm install -g)。
容器内监听 3000,默认不占宿主端口:agent 走 agent-mcp-net 按容器名访问
(http://mcp_web_search:3000/)。要从宿主机 curl 调试,自行给该服务加 ports 映射。
docker compose build mcp_web_search && docker compose up -d mcp_web_search
# 不占端口的健康检查
docker exec mcp_web_search node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)"
# {"name":"web_search","version":"...","transport":"http/sse","port":3000}
该服务无服务端鉴权,永远不要对外映射端口——会被白嫖搜索额度(自定义上游时还会把你的 key 白送出去)。