From 10877c9723432c38c19dec98b9e6aa33b82e3ca5 Mon Sep 17 00:00:00 2001 From: kicer Date: Mon, 2 Nov 2026 20:28:10 +0800 Subject: [PATCH] =?UTF-8?q?web=5Fsearch=20=E6=94=AF=E6=8C=81=E8=87=AA?= =?UTF-8?q?=E5=BB=BA=20/search=20=E4=B8=8A=E6=B8=B8=EF=BC=9A=E4=B8=8A?= =?UTF-8?q?=E6=B8=B8=E5=8F=82=E6=95=B0=E9=80=90=E8=AF=B7=E6=B1=82=E7=94=B1?= =?UTF-8?q?=20header=20=E5=B8=A6=E5=85=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 与 image_task / asr 同构:容器不存密钥,配置只写在 config.yml 的 mcp_servers[].headers。 - 新增 X-Web-Search-Base-Url(拼 /search)与可选 Authorization(裸 key 自动补 Bearer); 配了地址就以它为准,失败直接报错,不静默退回免费后端 - 没配地址时行为不变:Parallel 优先,失败自动退 Exa(降级从前端 provider 参数收回服务端) - 工具 schema 去掉 provider 参数(模型不该决定走哪家上游),只留 query / numResults - 响应统一归一化:丢弃无 url 条目,snippet 压平并截断 500 字,published_at 映射为 publishedAt - server.js 把 req.headers 传进协议层;stdio 模式无 header,只能用免费后端 - 设置页预设补两条可选字段(settings.js 无需改动,纯数据驱动) --- app/server/presets.json | 19 ++++++- mcp/README.md | 13 ++++- mcp/web_search/README.md | 38 ++++++++++++-- mcp/web_search/core.js | 98 +++++++++++++++++++++++++++++++++++-- mcp/web_search/mcp.js | 71 +++++++++++++++++++++------ mcp/web_search/package.json | 4 +- mcp/web_search/server.js | 11 ++++- 7 files changed, 221 insertions(+), 33 deletions(-) diff --git a/app/server/presets.json b/app/server/presets.json index c74c608..0606a75 100644 --- a/app/server/presets.json +++ b/app/server/presets.json @@ -42,10 +42,25 @@ { "key": "web_search", "label": "网页搜索", - "desc": "栈内搜索服务,无需密钥", + "desc": "内置免费搜索,也可接自建 /search", "url": "http://mcp_web_search:3000/", "mode": "advertise", - "fields": [] + "fields": [ + { + "header": "Authorization", + "label": "鉴权", + "secret": true, + "prefix": "Bearer ", + "placeholder": "API Key", + "hint": "免费后端留空" + }, + { + "header": "X-Web-Search-Base-Url", + "label": "地址", + "placeholder": "https:///v1", + "hint": "留空用免费后端" + } + ] }, { "key": "image_task", diff --git a/mcp/README.md b/mcp/README.md index db28114..3fbce7d 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -4,7 +4,7 @@ | 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 | |---|---|---|---|---| -| `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` | +| `web_search/` | `mcp_web_search` | 网页搜索(默认免费 Parallel / Exa,可换成自建 `/search` 上游) | `3000` | `POST /` | | `image_task/` | `mcp_image_task` | 图片生成 / 编辑(文生图走 `/images/generations`,图生图走 `/images/edits`,单工具 op=create/get) | `3000` | `POST /mcp` | | `video_task/` | `mcp_video_task` | 智谱 CogVideo 视频生成(异步,单工具 op=create/get) | `3000` | `POST /mcp` | | `asr/` | `mcp_asr` | 语音转文字(上游 OpenAI 兼容 `/audio/transcriptions`),**额外带一个给输入框用的 `POST /transcribe`** | `3000` | `POST /mcp` | @@ -27,6 +27,10 @@ docker compose up -d --build mcp_servers: - name: web_search url: "http://mcp_web_search:3000/" + # 可选:换成自己的搜索接口(不配 = 内置免费后端 Parallel / Exa) + # headers: + # Authorization: Bearer + # X-Web-Search-Base-Url: "https:///v1" - name: image_task url: "http://mcp_image_task:3000/mcp" - name: video_task @@ -51,6 +55,11 @@ mcp_servers: 上游地址与模型分别由 `X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定(两者都必填)。 所以这两个服务不用配任何密钥。 +`web_search` 同理:默认走内置免费后端(Parallel → Exa,无需 key);想换成自己的搜索接口, +就在这段 headers 里写 `X-Web-Search-Base-Url`(容器拼 `/search`)与可选的 `Authorization`。 +一旦配了地址就以它为准——**失败直接报错,不会静默退回免费后端**(否则 key 过期 / 地址写错 +只会表现为「结果质量突然变差」)。 + `asr` 同理:上游的 key / base_url / model 全部由调用方随请求 header 带入 (`Authorization` / `X-ASR-Base-Url` / `X-ASR-Model`,agent 侧配在 `config.yml` 的 `mcp_servers[name=asr].headers`)。输入框那条路(`agent-core` → `POST /transcribe`)不经过 MCP 调用, @@ -85,7 +94,7 @@ AI 把拿到的 URL 当 image_url 交给 video_task:3000/mcp | 服务 | 公网暴露 | 说明 | |---|---|---| -| `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | +| `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度;配了自定义上游时还会把你的 key 白送出去);agent 走内网访问 | | `mcp_image_task` | 无 | token 由调用方自带,暴露后可被拿去消耗你的上游图片额度 | | `mcp_video_task` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 | | `mcp_asr` | 无 | `/mcp` 与 `/transcribe` 都无鉴权,只能由 core 经内网调用;它不存密钥(上游参数随请求带入) | diff --git a/mcp/web_search/README.md b/mcp/web_search/README.md index e9abafd..32ef9aa 100644 --- a/mcp/web_search/README.md +++ b/mcp/web_search/README.md @@ -1,15 +1,41 @@ # web_search -免费网页搜索 MCP server 的本地重构版(上游开源实现:[@sheep233_/dsh-web-search-free](https://github.com/sheep-programmer/dsh-web-search-free),MIT)。 +网页搜索 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 +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` 压平空白并截断到 500 字(搜索结果会进对话历史、之后每轮都可能被整条重放,不截等于白烧 token), +`published_at` / `publishedAt` / `publish_date` 任一存在则映射为 `publishedAt`。 + ## 结构 | 文件 | 职责 | | --- | --- | -| `core.js` | 搜索后端:Parallel(默认)/ Exa(备用)免费 MCP 端点封装 + 响应解析 | -| `mcp.js` | MCP 协议层:`web_search` 工具定义 + JSON-RPC 分发 | +| `core.js` | 搜索后端:自定义 `/search` + Parallel / Exa 免费 MCP 端点封装 + 响应解析 | +| `mcp.js` | MCP 协议层:`web_search` 工具定义 + JSON-RPC 分发 + 从 header 取上游参数 | | `server.js` | 入口:CLI 参数 + stdio / HTTP/SSE 双传输 | ## 本地启动 @@ -33,6 +59,10 @@ MCP 端点: - `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`)。 @@ -47,4 +77,4 @@ docker exec mcp_web_search node -e "fetch('http://localhost:3000/health').then(r # {"name":"web_search","version":"...","transport":"http/sse","port":3000} ``` -该服务**无服务端鉴权**(上游是免费端点),**永远不要**对外映射端口——会被白嫆搜索额度。 +该服务**无服务端鉴权**,**永远不要**对外映射端口——会被白嫖搜索额度(自定义上游时还会把你的 key 白送出去)。 diff --git a/mcp/web_search/core.js b/mcp/web_search/core.js index 91774c6..ca6f08c 100644 --- a/mcp/web_search/core.js +++ b/mcp/web_search/core.js @@ -1,9 +1,13 @@ /** - * 零依赖搜索核心:Parallel(默认,匿名免 key)与 Exa(备用)两个免费后端的统一封装。 + * 零依赖搜索核心:三路上游,统一归一化成 `{ url, title?, snippet?, publishedAt? }[]`。 * - * 只用 Node 内置 fetch,不依赖任何 npm 包。两个后端都是公开的免费 MCP 端点, - * 本模块以 JSON-RPC `tools/call` 的方式直接调用它们,并归一化成统一的结果结构: - * `{ url, title?, snippet?, publishedAt? }[]`。 + * - 自定义上游(`X-Web-Search-Base-Url` + `Authorization`):任意 `POST {base}/search`, + * 请求体 `{ query, max_results }`、响应 `{ results: [{ title, url, snippet }] }`。 + * - Parallel(免费匿名 MCP 端点,默认后端)。 + * - Exa(免费 MCP 端点,Parallel 挂掉时的兜底)。 + * + * 只用 Node 内置 fetch,不依赖任何 npm 包。免费侧两个后端都是公开的 MCP 端点, + * 本模块以 JSON-RPC `tools/call` 的方式直接调用它们。 * * 上游实现参考:@sheep233_/dsh-web-search-free(github.com/sheep-programmer/dsh-web-search-free)。 */ @@ -13,9 +17,20 @@ export const PARALLEL_MCP_URL = 'https://search.parallel.ai/mcp'; /** Exa 免费 MCP 端点(匿名可用;EXA_API_KEY 可提升限额)。 */ export const EXA_MCP_URL = 'https://mcp.exa.ai/mcp'; -const USER_AGENT = 'web_search/1.0.0'; +const USER_AGENT = 'web_search/1.1.0'; /** 单次上游搜索请求的超时,避免远端挂起拖死 MCP 请求。 */ const REQUEST_TIMEOUT_MS = Number(process.env.SEARCH_TIMEOUT_MS ?? 30_000); +/** + * snippet 一律截断:搜索结果会进历史,之后每一轮都可能被整条重放。 + * 有些上游(如自建 v1/search)的 snippet 是整段正文,不截等于白烧 token。 + */ +const SNIPPET_MAX_CHARS = 500; + +/** 压平空白并截断;空串返回 ''(调用方据此决定要不要带这个字段)。 */ +export function capSnippet(text) { + const s = String(text == null ? '' : text).replace(/\s+/g, ' ').trim(); + return s.length > SNIPPET_MAX_CHARS ? s.slice(0, SNIPPET_MAX_CHARS) + '…' : s; +} /** * 向免费 MCP 端点发一次 `tools/call`,返回工具结果里的 text 载荷。 @@ -124,6 +139,61 @@ export function parseExaText(text) { return sources; } +/** + * 自定义上游:`POST {base}/search`,body `{ query, max_results }`。 + * 配置了地址就以它为准——失败直接抛错,不静默退回免费后端(否则 key 过期/base 写错 + * 只会表现为「结果质量突然变差」,永远没人发现)。 + * @param {{ auth: string, base: string }} up 由 mcp.js 从请求 header 解析(容器不存密钥) + */ +export async function customSearch(query, maxResults, up) { + const url = up.base.replace(/\/+$/, '') + '/search'; + const headers = { + 'content-type': 'application/json', + 'accept': 'application/json', + 'user-agent': USER_AGENT, + }; + // 免鉴权的自建服务可省;有值才带,避免给上游塞一个空 Authorization 反而被拒 + if (up.auth) headers.authorization = up.auth; + let response; + try { + response = await fetch(url, { + method: 'POST', + // 不跟随跳转:Authorization 不能被顺手带到别的地址去 + redirect: 'error', + headers, + body: JSON.stringify({ query, max_results: maxResults }), + signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS), + }); + } catch (error) { + throw new Error(`搜索上游请求失败(${url}):${String(error && error.message || error)}`); + } + const raw = await response.text(); + if (!response.ok) { + // 带上游响应片段:401 和 500 的处置完全不同,只说「请求失败」没法排查 + const detail = capSnippet(raw).slice(0, 200); + throw new Error(`搜索上游 HTTP ${response.status}${detail ? ':' + detail : ''}`); + } + let payload; + try { + payload = JSON.parse(raw); + } catch (error) { + throw new Error(`搜索上游返回了无法解析的响应:${String(error)}`); + } + const sources = []; + for (const item of payload.results ?? []) { + if (!item || !item.url) continue; + const snippet = capSnippet(item.snippet); + const publishedAt = item.published_at ?? item.publishedAt ?? item.publish_date; + sources.push({ + url: String(item.url), + ...(item.title ? { title: String(item.title) } : {}), + ...(snippet ? { snippet } : {}), + ...(publishedAt ? { publishedAt: String(publishedAt) } : {}), + }); + } + return maxResults !== undefined ? sources.slice(0, maxResults) : sources; +} + /** Parallel 搜索(默认免费后端)。 */ export async function parallelSearch(query, maxResults) { const text = await callMcpTool(PARALLEL_MCP_URL, 'web_search', { @@ -134,6 +204,24 @@ export async function parallelSearch(query, maxResults) { return maxResults !== undefined ? sources.slice(0, maxResults) : sources; } +/** + * 免费侧入口:Parallel 优先,失败自动退 Exa。 + * 降级放在服务端(而不是让模型显式传 provider)——模型看不到后端,也就不会选错。 + * @param {string} [exaApiKey] 可选,提升 Exa 匿名限额 + */ +export async function freeSearch(query, maxResults, exaApiKey) { + try { + return await parallelSearch(query, maxResults); + } catch (first) { + try { + return await exaSearch(query, maxResults, exaApiKey); + } catch (second) { + throw new Error(`免费搜索后端均不可用(parallel: ${String(first && first.message || first)};` + + `exa: ${String(second && second.message || second)})`); + } + } +} + /** Exa 搜索(备用免费后端;apiKey 可选,用于提升匿名限额)。 */ export async function exaSearch(query, maxResults, apiKey) { const endpoint = apiKey diff --git a/mcp/web_search/mcp.js b/mcp/web_search/mcp.js index 274d0ae..1435964 100644 --- a/mcp/web_search/mcp.js +++ b/mcp/web_search/mcp.js @@ -2,25 +2,30 @@ * MCP(Model Context Protocol)协议层:工具清单 + JSON-RPC 分发。 * * 与传输无关(stdio / HTTP 都在 server.js 里),只负责把一条 JSON-RPC - * 消息变成 JSON-RPC 响应。支持的 method 与上游 dsh-web-search-free 一致: - * initialize / tools/list / tools/call / ping。 + * 消息变成 JSON-RPC 响应。支持的 method:initialize / tools/list / tools/call / ping。 + * + * 上游参数逐请求从 HTTP header 取(与 mcp/asr、mcp/image_task 同构): + * X-Web-Search-Base-Url: https:///v1 → 打 {base}/search(配了就用它,不降级) + * Authorization: Bearer → 可选,裸 key 自动补 Bearer + * 两者都不配 = 内置免费后端(Parallel → Exa)。stdio 模式没有 header,因此只有免费后端。 */ -import { parallelSearch, exaSearch } from './core.js'; +import { customSearch, freeSearch } from './core.js'; export const SERVER_NAME = 'web_search'; -export const VERSION = '1.0.0'; +export const VERSION = '1.1.0'; const DEFAULT_PROTOCOL = '2025-03-26'; +const HDR_AUTH = 'authorization'; +const HDR_BASE = 'x-web-search-base-url'; /** 暴露给 MCP 客户端的工具清单。 */ const TOOLS = [ { name: 'web_search', - description: 'Free web search tool. Uses Parallel by default or Exa as fallback. Returns an array of results with title, url, snippet, and publishedAt.', + description: 'Search the web. Returns results with title, url, snippet and (when available) publishedAt.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query text' }, - provider: { type: 'string', enum: ['parallel', 'exa'], description: "Backend provider: 'parallel' (default) or 'exa' (fallback)" }, numResults: { type: 'integer', minimum: 1, default: 8, description: 'Maximum number of results to return (default 8)' }, }, required: ['query'], @@ -28,8 +33,27 @@ const TOOLS = [ }, ]; -/** 执行一次 tools/call;失败时抛 { code, message } 表示工具级错误。 */ -async function callTool(name, args) { +/** 从请求 header 取上游两要素;Authorization 允许写裸 key(自动补 Bearer)。 */ +function upstreamOf(headers) { + const h = headers || {}; + const raw = String(h[HDR_AUTH] || '').trim(); + return { + auth: raw ? (/^bearer\s/i.test(raw) ? raw : 'Bearer ' + raw) : '', + base: String(h[HDR_BASE] || '').trim().replace(/\/+$/, ''), + }; +} + +/** 配了地址就必须是完整 http(s):不能是相对路径,也不能把 key 发到别的协议上。 */ +function assertBase(base) { + let u = null; + try { u = new URL(base); } catch (_) { u = null; } + if (!u || (u.protocol !== 'http:' && u.protocol !== 'https:')) { + throw new Error('X-Web-Search-Base-Url 必须是完整的 http(s) 地址,如 https:///v1'); + } +} + +/** 执行一次 tools/call;失败时抛 { code, message } 表示协议级错误。 */ +async function callTool(name, args, headers) { if (name !== 'web_search') throw { code: -32602, message: `unknown tool: ${name}` }; const params = args ?? {}; @@ -38,20 +62,33 @@ async function callTool(name, args) { : null; if (query === null) throw { code: -32602, message: 'query is required' }; - const provider = params.provider === 'exa' ? 'exa' : 'parallel'; const numResults = typeof params.numResults === 'number' && Number.isFinite(params.numResults) ? Math.max(1, Math.floor(params.numResults)) : 8; - const sources = provider === 'exa' - ? await exaSearch(query, numResults, process.env.EXA_API_KEY) - : await parallelSearch(query, numResults); + const up = upstreamOf(headers); + let sources; + try { + if (up.base) { + assertBase(up.base); + sources = await customSearch(query, numResults, up); + } else { + sources = await freeSearch(query, numResults, process.env.EXA_API_KEY); + } + } catch (error) { + // 工具级错误回文本、协议层仍成功:模型能读懂并换查询/换工具, + // 回 JSON-RPC error 只会被 core 拼成「调用失败」,模型反而不好自纠。 + return { + isError: true, + content: [{ type: 'text', text: 'Error: ' + String(error && error.message || error) }], + }; + } return { content: [{ type: 'text', text: JSON.stringify(sources, null, 2) }] }; } /** 处理一条请求消息,返回 result;失败时抛 { code, message }。 */ -async function handleRequest(message) { +async function handleRequest(message, headers) { switch (message.method) { case 'initialize': return { @@ -62,7 +99,7 @@ async function handleRequest(message) { case 'tools/list': return { tools: TOOLS }; case 'tools/call': - return callTool(message.params?.name, message.params?.arguments); + return callTool(message.params?.name, message.params?.arguments, headers); case 'ping': return {}; default: @@ -72,9 +109,11 @@ async function handleRequest(message) { /** * 解析并执行一条 JSON 消息。 + * @param {string} raw JSON-RPC 文本 + * @param {object} [headers] 本次 HTTP 请求的 header(stdio 模式没有,上游参数就走免费后端) * @returns 响应信封对象;notification(无 id)返回 null;非法 JSON 返回 undefined。 */ -export async function dispatch(raw) { +export async function dispatch(raw, headers) { let message; try { message = JSON.parse(raw); @@ -83,7 +122,7 @@ export async function dispatch(raw) { } if (message.id === undefined) return null; // 通知不响应 try { - return { jsonrpc: '2.0', id: message.id, result: await handleRequest(message) }; + return { jsonrpc: '2.0', id: message.id, result: await handleRequest(message, headers) }; } catch (error) { const e = error; return { diff --git a/mcp/web_search/package.json b/mcp/web_search/package.json index 956422f..080a2f7 100644 --- a/mcp/web_search/package.json +++ b/mcp/web_search/package.json @@ -1,8 +1,8 @@ { "name": "web_search", - "version": "1.0.0", + "version": "1.1.0", "private": true, - "description": "Free web search tool. Uses Parallel by default or Exa as fallback.", + "description": "Web search tool. Uses a caller-provided /search endpoint when configured, otherwise free Parallel / Exa backends.", "license": "MIT", "type": "module", "main": "server.js", diff --git a/mcp/web_search/server.js b/mcp/web_search/server.js index 7bab7ed..276055c 100644 --- a/mcp/web_search/server.js +++ b/mcp/web_search/server.js @@ -1,16 +1,22 @@ #!/usr/bin/env node /** - * MCP server 入口 —— 免费网页搜索(Parallel 默认 / Exa 备用,匿名免 key)。 + * MCP server 入口 —— 网页搜索(自定义 /search 上游,或内置免费 Parallel / Exa)。 * * 本地重构版(上游:@sheep233_/dsh-web-search-free),零运行时依赖,直接 node 启动。 * * ## 双传输 * - **stdio**(默认):`node server.js` * - `claude mcp add web_search -- node <路径>/server.js` + * - 没有 HTTP header,因此只能用内置免费后端 * - **HTTP/SSE**(监听端口):`node server.js --http --port 3000 --host 0.0.0.0` * - 兼容 Streamable HTTP(`POST /`)与老式 SSE(`GET /sse` + `POST /messages`) * - `GET /` 或 `GET /health` 返回服务信息,可做健康检查 * + * 上游参数逐请求从 HTTP header 取(与 mcp/asr、mcp/image_task 同构,容器不存密钥): + * X-Web-Search-Base-Url: https:///v1 → 打 {base}/search + * Authorization: Bearer → 可选,裸 key 自动补 Bearer + * 两者都不配 = 免费后端。 + * * 环境变量:EXA_API_KEY(可选,提升 Exa 匿名限额);SEARCH_TIMEOUT_MS(可选,上游超时)。 */ import { createInterface } from 'node:readline'; @@ -88,7 +94,8 @@ function runHttp(host, port) { let body = ''; req.on('data', (chunk) => { body += chunk.toString(); }); req.on('end', () => { - void dispatch(body).then((response) => { + // header 必须随消息带进协议层:上游地址 / 鉴权都是逐请求带入的(容器不存密钥) + void dispatch(body, req.headers).then((response) => { if (response === null) { // 通知 res.writeHead(202).end(); return;