Files
agent/mcp/web_search
kicer cc53c117e8 web_search snippet 默认不截断,改由调用方传 maxSnippetLength
之前自定义上游与 Exa 都写死 500 字,换上游就等于悄悄丢内容。现在:

- 默认原样返回整段 snippet(只压平空白)
- 传 maxSnippetLength: N 才截断到 N 字并补省略号;0 / 负数 / 非数字一律视为不传
- 三路上游(自定义 /search、Parallel、Exa)统一按同一参数处理
- 上游报错时的响应片段仍固定截 200 字(那是诊断信息,不参与该参数)
2026-11-02 20:55:55 +08:00
..
2026-09-05 20:34:42 +08:00

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 白送出去)。