修正文件夹目录

This commit is contained in:
2026-09-05 20:34:42 +08:00
parent a673d53c08
commit 273bd9b8b0
17 changed files with 77 additions and 77 deletions
+11
View File
@@ -0,0 +1,11 @@
FROM node:22-slim
WORKDIR /app
# 零运行时依赖:直接拷贝本地重构的源码,无需 npm install
COPY package.json server.js mcp.js core.js ./
EXPOSE 3000
# HTTP/SSE 模式监听 3000 端口(stdio 模式见 package.json 的 start:stdio)
CMD ["node", "server.js", "--http", "--port", "3000", "--host", "0.0.0.0"]
+42
View File
@@ -0,0 +1,42 @@
# 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` 启动**。
## 结构
| 文件 | 职责 |
| --- | --- |
| `core.js` | 搜索后端:Parallel(默认)/ Exa(备用)免费 MCP 端点封装 + 响应解析 |
| `mcp.js` | MCP 协议层:`web_search` 工具定义 + JSON-RPC 分发 |
| `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
## Docker
`docker-compose.yml` 中的 `mcp_web_search` 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 `npm install -g`)。
```bash
docker compose build mcp_web_search && docker compose up -d mcp_web_search
```
+150
View File
@@ -0,0 +1,150 @@
/**
* 零依赖搜索核心:Parallel(默认,匿名免 key)与 Exa(备用)两个免费后端的统一封装。
*
* 只用 Node 内置 fetch,不依赖任何 npm 包。两个后端都是公开的免费 MCP 端点,
* 本模块以 JSON-RPC `tools/call` 的方式直接调用它们,并归一化成统一的结果结构:
* `{ url, title?, snippet?, publishedAt? }[]`。
*
* 上游实现参考:@sheep233_/dsh-web-search-free(github.com/sheep-programmer/dsh-web-search-free)。
*/
/** Parallel Web Search 免费 MCP 端点(匿名可用,OpenCode 默认后端之一)。 */
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';
/** 单次上游搜索请求的超时,避免远端挂起拖死 MCP 请求。 */
const REQUEST_TIMEOUT_MS = Number(process.env.SEARCH_TIMEOUT_MS ?? 30_000);
/**
* 向免费 MCP 端点发一次 `tools/call`,返回工具结果里的 text 载荷。
* 响应可能是裸 JSON,也可能是 SSE(`data: {...}`)分帧,两种都兼容。
*/
async function callMcpTool(endpoint, toolName, toolArgs, signal) {
const response = await fetch(endpoint, {
method: 'POST',
redirect: 'error',
headers: {
'content-type': 'application/json',
'accept': 'application/json, text/event-stream',
'user-agent': USER_AGENT,
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: { name: toolName, arguments: toolArgs },
}),
...(signal !== undefined ? { signal } : {}),
});
if (!response.ok) {
throw new Error(`${toolName} API error (HTTP ${response.status})`);
}
const text = extractToolText(await response.text());
if (text === undefined) {
throw new Error(`${toolName} returned no tool result`);
}
return text;
}
/** 从裸 JSON 或 SSE 文本中提取 MCP `tools/call` 的 result.content[].text。 */
export function extractToolText(body) {
const parsePayload = (raw) => {
try {
const data = JSON.parse(raw);
const item = data.result?.content?.find((c) => c.type === 'text' && typeof c.text === 'string');
return item?.text || undefined;
} catch {
return undefined; // 不是 JSON 载荷,交给 SSE 行解析
}
};
const trimmed = body.trim();
if (trimmed.length > 0) {
const direct = parsePayload(trimmed);
if (direct !== undefined) return direct;
}
for (const line of body.split('\n')) {
if (!line.startsWith('data: ')) continue;
const data = parsePayload(line.slice(6));
if (data !== undefined) return data;
}
return undefined;
}
/** Parallel 响应解析:text 是内嵌 JSON `{ results: [...] }`。 */
export function mapParallelResponse(text) {
let payload;
try {
payload = JSON.parse(text);
} catch (error) {
throw new Error(`Parallel search returned an unprocessable payload: ${String(error)}`);
}
const sources = [];
for (const item of payload.results ?? []) {
if (!item.url) continue;
sources.push({
url: item.url,
...(item.title ? { title: item.title } : {}),
...(item.excerpts?.length > 0 ? { snippet: item.excerpts.join(' ') } : {}),
...(item.publish_date ? { publishedAt: item.publish_date } : {}),
});
}
return sources;
}
/**
* Exa 响应解析:text 是纯文本块,每条结果以 `Title: ` 开头:
* ```
* Title: <标题>
* URL: <链接>
* Published: <日期 | N/A>
* Author: <作者 | N/A>
* Highlights:
* <正文摘要>
* ```
*/
export function parseExaText(text) {
const blocks = text.split(/(?=^Title: )/m).filter((block) => block.trim().length > 0);
const sources = [];
for (const block of blocks) {
const url = block.match(/^URL: (\S+)$/m)?.[1];
if (url === undefined) continue;
const title = block.match(/^Title: (.+)$/m)?.[1]?.trim();
const published = block.match(/^Published: (.+)$/m)?.[1]?.trim();
const highlights = block.split(/^Highlights:\s*$/m)[1]?.trim();
sources.push({
url,
...(title ? { title } : {}),
...(highlights ? { snippet: highlights.slice(0, 500) } : {}),
...(published && published !== 'N/A' ? { publishedAt: published } : {}),
});
}
return sources;
}
/** Parallel 搜索(默认免费后端)。 */
export async function parallelSearch(query, maxResults) {
const text = await callMcpTool(PARALLEL_MCP_URL, 'web_search', {
objective: query,
search_queries: [query],
}, AbortSignal.timeout(REQUEST_TIMEOUT_MS));
const sources = mapParallelResponse(text);
return maxResults !== undefined ? sources.slice(0, maxResults) : sources;
}
/** Exa 搜索(备用免费后端;apiKey 可选,用于提升匿名限额)。 */
export async function exaSearch(query, maxResults, apiKey) {
const endpoint = apiKey
? `${EXA_MCP_URL}?exaApiKey=${encodeURIComponent(apiKey)}`
: EXA_MCP_URL;
const text = await callMcpTool(endpoint, 'web_search_exa', {
query,
type: 'auto',
numResults: maxResults ?? 8,
livecrawl: 'fallback',
}, AbortSignal.timeout(REQUEST_TIMEOUT_MS));
const sources = parseExaText(text);
return maxResults !== undefined ? sources.slice(0, maxResults) : sources;
}
+95
View File
@@ -0,0 +1,95 @@
/**
* 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。
*/
import { parallelSearch, exaSearch } from './core.js';
export const SERVER_NAME = 'web_search';
export const VERSION = '1.0.0';
const DEFAULT_PROTOCOL = '2025-03-26';
/** 暴露给 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.',
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'],
},
},
];
/** 执行一次 tools/call;失败时抛 { code, message } 表示工具级错误。 */
async function callTool(name, args) {
if (name !== 'web_search') throw { code: -32602, message: `unknown tool: ${name}` };
const params = args ?? {};
const query = typeof params.query === 'string' && params.query.trim().length > 0
? params.query.trim()
: 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);
return { content: [{ type: 'text', text: JSON.stringify(sources, null, 2) }] };
}
/** 处理一条请求消息,返回 result;失败时抛 { code, message }。 */
async function handleRequest(message) {
switch (message.method) {
case 'initialize':
return {
protocolVersion: message.params?.protocolVersion ?? DEFAULT_PROTOCOL,
capabilities: { tools: {} },
serverInfo: { name: SERVER_NAME, version: VERSION },
};
case 'tools/list':
return { tools: TOOLS };
case 'tools/call':
return callTool(message.params?.name, message.params?.arguments);
case 'ping':
return {};
default:
throw { code: -32601, message: `method not found: ${String(message.method)}` };
}
}
/**
* 解析并执行一条 JSON 消息。
* @returns 响应信封对象;notification(无 id)返回 null;非法 JSON 返回 undefined。
*/
export async function dispatch(raw) {
let message;
try {
message = JSON.parse(raw);
} catch {
return undefined;
}
if (message.id === undefined) return null; // 通知不响应
try {
return { jsonrpc: '2.0', id: message.id, result: await handleRequest(message) };
} catch (error) {
const e = error;
return {
jsonrpc: '2.0',
id: message.id,
error: { code: typeof e.code === 'number' ? e.code : -32603, message: String(e.message ?? error) },
};
}
}
+19
View File
@@ -0,0 +1,19 @@
{
"name": "web_search",
"version": "1.0.0",
"private": true,
"description": "Free web search tool. Uses Parallel by default or Exa as fallback.",
"license": "MIT",
"type": "module",
"main": "server.js",
"bin": {
"web_search": "server.js"
},
"engines": {
"node": ">=18"
},
"scripts": {
"start": "node server.js --http --port 3000 --host 0.0.0.0",
"start:stdio": "node server.js"
}
}
+130
View File
@@ -0,0 +1,130 @@
#!/usr/bin/env node
/**
* MCP server 入口 —— 免费网页搜索(Parallel 默认 / Exa 备用,匿名免 key)。
*
* 本地重构版(上游:@sheep233_/dsh-web-search-free),零运行时依赖,直接 node 启动。
*
* ## 双传输
* - **stdio**(默认):`node server.js`
* - `claude mcp add web_search -- node <路径>/server.js`
* - **HTTP/SSE**(监听端口):`node server.js --http --port 3000 --host 0.0.0.0`
* - 兼容 Streamable HTTP(`POST /`)与老式 SSE(`GET /sse` + `POST /messages`)
* - `GET /` 或 `GET /health` 返回服务信息,可做健康检查
*
* 环境变量:EXA_API_KEY(可选,提升 Exa 匿名限额);SEARCH_TIMEOUT_MS(可选,上游超时)。
*/
import { createInterface } from 'node:readline';
import { createServer } from 'node:http';
import { randomUUID } from 'node:crypto';
import { SERVER_NAME, VERSION, dispatch } from './mcp.js';
// ── stdio 传输(默认)───────────────────────────────────────────────────────
function runStdio() {
const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
rl.on('line', (line) => {
const trimmed = line.trim();
if (trimmed.length === 0) return;
void dispatch(trimmed).then((response) => {
if (response != null) {
process.stdout.write(`${JSON.stringify(response)}\n`);
}
});
});
}
// ── HTTP/SSE 传输(--http [--port <n>] [--host <addr>])──────────────────────
function runHttp(host, port) {
/** sessionId → 老式 SSE 响应流(GET /sse 建立的连接)。 */
const sseChannels = new Map();
const server = createServer((req, res) => {
const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
// 健康检查 / 服务信息
if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/health')) {
res.writeHead(200, { 'content-type': 'application/json' });
res.end(JSON.stringify({ name: SERVER_NAME, version: VERSION, transport: 'http/sse', port }));
return;
}
// 老式 SSE 通道:GET /sse(MCP-Session-Id 关联后续 POST /messages)
if (req.method === 'GET' && url.pathname === '/sse') {
const sessionId = req.headers['mcp-session-id'] ?? randomUUID();
res.writeHead(200, {
'content-type': 'text/event-stream',
'cache-control': 'no-cache',
'connection': 'keep-alive',
'mcp-session-id': sessionId,
});
res.write(`event: endpoint\ndata: /messages?session_id=${sessionId}\n\n`);
sseChannels.set(sessionId, res);
req.on('close', () => { sseChannels.delete(sessionId); });
return;
}
// 消息端点:POST /(Streamable HTTP)与 POST /messages(老式 SSE)
if (req.method === 'POST' && (url.pathname === '/' || url.pathname === '/messages')) {
const sessionId = req.headers['mcp-session-id'] ?? url.searchParams.get('session_id') ?? undefined;
let body = '';
req.on('data', (chunk) => { body += chunk.toString(); });
req.on('end', () => {
void dispatch(body).then((response) => {
if (response === null) { // 通知
res.writeHead(202).end();
return;
}
const payload = JSON.stringify(response);
// 老式 SSE:结果推回通道连接
if (url.pathname === '/messages' && sessionId !== undefined && sseChannels.has(sessionId)) {
sseChannels.get(sessionId).write(`data: ${payload}\n\n`);
res.writeHead(202, { 'mcp-session-id': sessionId }).end();
return;
}
// Streamable HTTP:按 Accept 返回 SSE 帧或裸 JSON
if (String(req.headers.accept ?? '').includes('text/event-stream')) {
res.writeHead(200, {
'content-type': 'text/event-stream',
'cache-control': 'no-cache',
...(sessionId !== undefined ? { 'mcp-session-id': sessionId } : {}),
});
res.end(`data: ${payload}\n\n`);
return;
}
res.writeHead(200, {
'content-type': 'application/json',
...(sessionId !== undefined ? { 'mcp-session-id': sessionId } : {}),
});
res.end(payload);
});
});
return;
}
res.writeHead(404, { 'content-type': 'application/json' });
res.end(JSON.stringify({
error: 'not found',
hint: 'MCP endpoints: POST / (streamable http), GET /sse + POST /messages (legacy sse), GET / (info)',
}));
});
server.listen(port, host, () => {
process.stdout.write(`[web_search] HTTP/SSE listening on http://${host}:${port} (MCP: POST /, GET /sse + POST /messages)\n`);
});
}
// ── 入口:参数解析 ──────────────────────────────────────────────────────────
const args = process.argv.slice(2);
const httpMode = args.includes('--http')
|| (args.includes('--transport') && args[args.indexOf('--transport') + 1] === 'http');
const readFlag = (name, fallback) => {
const index = args.indexOf(name);
return index >= 0 && args[index + 1] !== undefined ? args[index + 1] : fallback;
};
if (httpMode) {
const port = Number(readFlag('--port', 3100));
runHttp(readFlag('--host', '127.0.0.1'), Number.isFinite(port) ? port : 3100);
} else {
runStdio();
}