之前自定义上游与 Exa 都写死 500 字,换上游就等于悄悄丢内容。现在: - 默认原样返回整段 snippet(只压平空白) - 传 maxSnippetLength: N 才截断到 N 字并补省略号;0 / 负数 / 非数字一律视为不传 - 三路上游(自定义 /search、Parallel、Exa)统一按同一参数处理 - 上游报错时的响应片段仍固定截 200 字(那是诊断信息,不参与该参数)
89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
# web_search
|
||
|
||
网页搜索 MCP server 的本地重构版(上游开源实现:[@sheep233_/dsh-web-search-free](https://github.com/sheep-programmer/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 |
|
||
|
||
自定义上游的协议:
|
||
|
||
```http
|
||
POST {base}/search
|
||
Authorization: Bearer <key>
|
||
Content-Type: application/json
|
||
|
||
{"query":"2027山东省考公告","max_results":5}
|
||
```
|
||
|
||
```json
|
||
{"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 双传输 |
|
||
|
||
## 本地启动
|
||
|
||
```bash
|
||
# 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` 映射。
|
||
|
||
```bash
|
||
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 白送出去)。
|