From 710200605bcb72a3baba9db96685f5b4a9d25cbb Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 16:19:34 +0800 Subject: [PATCH] add video-gen support --- mcp/docker-compose.yml | 15 +- mcp/video-gen/.dockerignore | 3 + mcp/video-gen/Dockerfile | 15 + mcp/video-gen/README.md | 306 ++++++++++++++++++++ mcp/video-gen/package.json | 14 + mcp/video-gen/src/mcp-server.js | 475 +++++++++++++++++++++++++++++++ mcp/web-search-free/Dockerfile | 8 +- mcp/web-search-free/README.md | 42 +++ mcp/web-search-free/core.js | 150 ++++++++++ mcp/web-search-free/mcp.js | 95 +++++++ mcp/web-search-free/package.json | 19 ++ mcp/web-search-free/server.js | 130 +++++++++ 12 files changed, 1267 insertions(+), 5 deletions(-) create mode 100644 mcp/video-gen/.dockerignore create mode 100644 mcp/video-gen/Dockerfile create mode 100644 mcp/video-gen/README.md create mode 100644 mcp/video-gen/package.json create mode 100644 mcp/video-gen/src/mcp-server.js create mode 100644 mcp/web-search-free/README.md create mode 100644 mcp/web-search-free/core.js create mode 100644 mcp/web-search-free/mcp.js create mode 100644 mcp/web-search-free/package.json create mode 100644 mcp/web-search-free/server.js diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index a6d7521..1745ef1 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -25,6 +25,19 @@ services: networks: - my-app-network + mcp-video-gen: + build: ./video-gen + container_name: mcp-video-gen + restart: unless-stopped + expose: + - "3000" + environment: + - VIRTUAL_HOST=video-gen.ai.foresh.com + - VIRTUAL_PORT=3000 + - CERT_NAME=default + networks: + - my-app-network + networks: my-app-network: - external: true + external: true \ No newline at end of file diff --git a/mcp/video-gen/.dockerignore b/mcp/video-gen/.dockerignore new file mode 100644 index 0000000..2f6141d --- /dev/null +++ b/mcp/video-gen/.dockerignore @@ -0,0 +1,3 @@ +node_modules +npm-debug.log +.DS_Store \ No newline at end of file diff --git a/mcp/video-gen/Dockerfile b/mcp/video-gen/Dockerfile new file mode 100644 index 0000000..f7ed783 --- /dev/null +++ b/mcp/video-gen/Dockerfile @@ -0,0 +1,15 @@ +FROM node:22-slim + +WORKDIR /app + +# 复制 package.json 并安装依赖 +COPY package.json ./ +RUN npm install --omit=dev + +# 复制源码 +COPY . . + +EXPOSE 3000 + +# 启用 HTTP/SSE 模式,监听 3000 端口 +CMD ["node", "src/mcp-server.js", "--http", "--port", "3000", "--host", "0.0.0.0"] \ No newline at end of file diff --git a/mcp/video-gen/README.md b/mcp/video-gen/README.md new file mode 100644 index 0000000..8dec2fa --- /dev/null +++ b/mcp/video-gen/README.md @@ -0,0 +1,306 @@ +# MCP Video Gen + +基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的视频生成服务,对接智谱 BigModel 的视频生成**异步**接口,支持**文生视频**和**图生视频**。Server 只负责提交任务 + 单次查询结果,**不内部轮询**——AI 拿到 `task_id` 后自己决定什么时候调用 `query_video` 复查。 + +- 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) +- 上游:[智谱 BigModel 视频生成(异步)](https://docs.bigmodel.cn/api-reference/模型-api/视频生成异步) + [查询异步结果](https://docs.bigmodel.cn/api-reference/模型-api/查询异步结果) +- 默认模型:`cogvideox-flash` +- 端口:`3000` +- 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token + +--- + +## 快速开始 + +### 启动(docker-compose) + +仓库根目录 `docker-compose.yml` 已包含本服务: + +```bash +cd /root/workspace/tools/mcp +docker compose up -d --build mcp-video-gen +``` + +服务容器名 `mcp-video-gen`,通过反代暴露为 `https://video-gen.ai.foresh.com/mcp`。 + +直接连容器调试: + +```bash +docker exec -it mcp-video-gen sh +# 或本机 +curl http://localhost:3000/health +# {"status":"ok","service":"video-gen","sessions":0} +``` + +### MCP 客户端配置 + +#### Claude Desktop / Cursor 等支持 `headers` 配置的客户端 + +```jsonc +// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json +// Cursor: ~/.cursor/mcp.json +{ + "mcpServers": { + "video-gen": { + "url": "https://video-gen.ai.foresh.com/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +> **重要**:客户端必须在 **每一个 HTTP 请求**(`initialize` / `notifications/initialized` / `tools/call`)都带上 `Authorization` header。 + +--- + +## 工具一览 + +| 工具 | 作用 | 同步/异步 | +|---|---|---| +| `generate_video` | 提交一个视频生成任务,立刻返回 `task_id` | 同步(仅提交) | +| `query_video` | 用 `task_id` 拉一次当前结果 | 同步(单次查询,不轮询) | + +--- + +## 工具:generate_video + +提交一个视频生成任务,支持**文生视频**和**图生视频**。**至少**需要传 `prompt` 或 `image_url` 其中之一;两者都传也行(image-to-video 时 prompt 会被附加为运动/动作描述)。 + +### 参数(AI 可见) + +| 名称 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `prompt` | string | ❌ | 视频文本描述,最大 512 字符 | +| `image_url` | string | ❌ | 参考图 URL(也支持 base64)。最多两张,首张为首帧、第二张为尾帧。图片 ≤ 5MB,格式 png/jpeg/jpg | +| `size` | string | ❌ | 视频尺寸,例如 `1920x1080`、`1080x1920`、`1024x1024`、`1280x960` 等 | +| `with_audio` | boolean | ❌ | 是否生成 AI 音效,默认 `false` | + +### 服务端 Header 覆盖项(AI 看不到) + +| Header | 类型 | 默认 | 说明 | +|---|---|---|---| +| `X-Video-Gen-Model` / `X-Mcp-Model` / `X-Model` | string | `cogvideox-flash` | 覆盖模型 | +| `X-Video-Gen-Quality` | string | `speed` | `speed`(速度优先)或 `quality`(质量优先) | +| `X-Video-Gen-Fps` | int | `30` | `30` 或 `60` | +| `X-Video-Gen-Duration` | int | `5` | `5` 或 `10` 秒 | +| `X-Video-Gen-Watermark` | bool | `true` | 是否添加 AI 水印;关闭需先在智谱后台签署免责声明 | + +模型名串识别顺序(首个非空值生效):`X-Video-Gen-Model` → `X-Mcp-Model` → `X-Model` → 默认。 + +### 返回 + +工具立刻返回智谱提交结果: + +```jsonc +{ + "content": [ + { "type": "text", "text": "Model: cogvideox-flash\ntask_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nrequest_id: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy\ntask_status: PROCESSING\n\nVideo generation is asynchronous. Call query_video with task_id=\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\" to fetch the result." } + ] +} +``` + +`task_status` 通常为 `PROCESSING`,极少数情况下可能直接 `SUCCESS`(极快完成的短任务)。 + +--- + +## 工具:query_video + +根据 `task_id` 拉一次智谱异步结果。**不内部轮询**——AI 自己决定调几次、调多频。 + +### 参数(AI 可见) + +| 名称 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `task_id` | string | ✅ | `generate_video` 返回的 `id` | + +### 返回 + +- **`SUCCESS`**:返回 `Video URL`(智谱签名 URL,**24h 左右有效**,需及时转存),外加一张 `Cover` 封面图: + ```jsonc + { + "content": [ + { "type": "text", "text": "task_id: ...\nmodel: cogvideox-flash\ntask_status: SUCCESS\nVideo URL: https://...\nCover: https://..." }, + { "type": "text", "text": "https://...video url..." } + ] + } + ``` +- **`PROCESSING`**:`isError: false`,正文给出当前状态,建议稍候再查。 +- **`FAIL`**:`isError: true`,正文含 `task_status` 和智谱返回的 `error` 详情。 + +--- + +## 鉴权细节 + +每个 HTTP 请求必须携带智谱 API Token,server 从以下 header 字段按顺序识别,**首个非空值生效**: + +| 优先级 | Header | 说明 | +|---|---|---| +| 1 | `X-Video-Gen-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | +| 2 | `X-Mcp-Token: ` | 通用兜底 | +| 3 | `Authorization: Bearer ` | 标准 OAuth 风格(排最后是为避免误用) | + +Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不进 session。 + +### 错误响应 + +| 场景 | HTTP 状态 | 表现 | +|---|---|---| +| initialize 时缺 token | `401` | JSON-RPC `error.message` 提示补充 header | +| 智谱 API 4xx/5xx | `200`(MCP 工具返回) | `isError: true`,正文含智谱返回的状态码和 body | +| 网络失败 | `200`(MCP 工具返回) | `isError: true`,正文含 `fetch` 错误信息 | + +--- + +## 推荐用法(AI 视角) + +``` +1. AI 决定生成视频 → 调用 generate_video({ prompt, image_url?, size?, with_audio? }) +2. 拿到 task_id → 等待若干秒(建议 2~5 秒) +3. 调用 query_video({ task_id }) + - 若 PROCESSING → 等一会再调 + - 若 SUCCESS → 拿到 video URL,贴给用户 / 下载 / 二次编辑 + - 若 FAIL → 展示错误信息,结束 +``` + +--- + +## 用 curl 手工调试 + +MCP Streamable HTTP 不是普通 REST,**必须按顺序**:`initialize` → `notifications/initialized` → `tools/call`。下面用一行版串起来: + +```bash +# 把 替换成你智谱的 API Key +TOKEN="" + +# 1. initialize 拿 sessionId +SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2024-11-05", + "capabilities": {}, + "clientInfo": { "name": "curl", "version": "1.0" } + } + }' | grep -i '^mcp-session-id:' | awk '{print $2}' | tr -d '\r\n') + +echo "Session: $SESSION" + +# 2. notifications/initialized +curl -s -X POST http://localhost:3000/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Mcp-Session-Id: $SESSION" \ + -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}' + +# 3. 列出工具(可选验证) +curl -s -X POST http://localhost:3000/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Mcp-Session-Id: $SESSION" \ + -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' + +# 4. 提交文生视频任务 +curl -s -X POST http://localhost:3000/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Mcp-Session-Id: $SESSION" \ + -d '{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "generate_video", + "arguments": { + "prompt": "A cat is playing with a ball.", + "size": "1920x1080", + "with_audio": true + } + } + }' + +# 5. 查结果(替换下面的 ) +curl -s -X POST http://localhost:3000/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Mcp-Session-Id: $SESSION" \ + -d '{ + "jsonrpc": "2.0", + "id": 4, + "method": "tools/call", + "params": { + "name": "query_video", + "arguments": { "task_id": "" } + } + }' +``` + +响应是 SSE 格式(`event: message` + `data: {...}`),用 `grep '^data:'` 抽 JSON 即可。 + +--- + +## 架构与文件 + +``` +video-gen/ +├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server +├── .dockerignore # 排除 node_modules +├── package.json # @modelcontextprotocol/sdk + express(无新依赖) +├── README.md # 本文件 +└── src/ + └── mcp-server.js # 单文件实现:HTTP server + MCP transport + 双工具 +``` + +### 关键设计 + +- **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用,避免每请求重建 +- **Token 闭包注入**:在 Express 入口处从 header 提取 token,闭包传给 tool 回调;不依赖 SDK 内部字段 +- **AI 可见 vs AI 不可见**: + - AI 只看到 `prompt / image_url / size / with_audio` + - `model / quality / fps / duration / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 +- **异步语义暴露给 AI**:服务端不做轮询,`generate_video` 只提交、`query_video` 只查一次。AI 自主决定节奏 +- **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI + +### 默认模型 + +```js +// src/mcp-server.js +const DEFAULT_MODEL = "cogvideox-flash"; +``` + +修改后 `docker compose up -d --build mcp-video-gen` 即可生效。 + +--- + +## 常见问题 + +**Q: AI 拿到 task_id 后立刻调 query_video 一直 PROCESSING,怎么办?** +A: AI 自己 sleep 几秒再调(建议 2~5 秒间隔)。这是设计取舍:把节奏控制权交给 AI 模型,而不是服务端硬编码超时。 + +**Q: 视频 URL 多久过期?** +A: 智谱签发 URL 默认 24h 左右。需要在收到后及时转存到自己的 OSS/S3。 + +**Q: 为什么 quality / fps / duration 不让 AI 直接传?** +A: 这些是技术档位,与成本/单价挂钩。让 AI 自主挑 `quality=quality + fps=60 + duration=10` 会爆账号预算。改成 header 由部署方注入更可控。 + +**Q: 能否限制 `size` 白名单?** +A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `generate_video` 的 `size` schema 即可。 + +**Q: 报错 `Missing valid Mcp-Session-Id`?** +A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize`。 + +**Q: 同一 task_id 能并发查吗?** +A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。 + +**Q: 换模型需要重连 MCP session 吗?** +A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 \ No newline at end of file diff --git a/mcp/video-gen/package.json b/mcp/video-gen/package.json new file mode 100644 index 0000000..07ca8af --- /dev/null +++ b/mcp/video-gen/package.json @@ -0,0 +1,14 @@ +{ + "name": "mcp-video-gen", + "version": "1.0.0", + "description": "MCP server for video generation via Zhipu BigModel cogvideox-flash (text-to-video / image-to-video, async)", + "type": "module", + "main": "src/mcp-server.js", + "scripts": { + "start": "node src/mcp-server.js --http --port 3000 --host 0.0.0.0" + }, + "dependencies": { + "@modelcontextprotocol/sdk": "^1.0.4", + "express": "^4.21.0" + } +} \ No newline at end of file diff --git a/mcp/video-gen/src/mcp-server.js b/mcp/video-gen/src/mcp-server.js new file mode 100644 index 0000000..6c52cae --- /dev/null +++ b/mcp/video-gen/src/mcp-server.js @@ -0,0 +1,475 @@ +#!/usr/bin/env node +import express from "express"; +import { randomUUID } from "node:crypto"; +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; +import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; + +const ZHIPU_SUBMIT_URL = + "https://open.bigmodel.cn/api/paas/v4/videos/generations"; +const ZHIPU_QUERY_URL = (id) => + `https://open.bigmodel.cn/api/paas/v4/async-result/${encodeURIComponent(id)}`; + +// 默认模型:你说的 cogvideox-flash,文档枚举里也确认可用 +const DEFAULT_MODEL = "cogvideox-flash"; + +// AI 不可见的服务端默认(可被同名 header 覆盖) +const DEFAULT_QUALITY = "speed"; // speed | quality +const DEFAULT_FPS = 30; // 30 | 60 +const DEFAULT_DURATION = 5; // 5 | 10 +const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true + +function parseArgs(argv) { + const args = { + http: false, + port: 3000, + host: "0.0.0.0", + }; + for (let i = 0; i < argv.length; i++) { + const a = argv[i]; + if (a === "--http") args.http = true; + else if (a === "--port") args.port = parseInt(argv[++i], 10); + else if (a === "--host") args.host = argv[++i]; + } + return args; +} + +function pickToken(headers) { + if (!headers) return null; + const candidates = [ + headers["x-video-gen-token"], + headers["x-mcp-token"], + headers["authorization"], + ]; + for (const v of candidates) { + if (!v) continue; + const s = String(v).trim(); + if (!s) continue; + if (/^Bearer\s+/i.test(s)) { + const t = s.replace(/^Bearer\s+/i, "").trim(); + if (t) return t; + } else { + return s; + } + } + return null; +} + +function pickModel(headers) { + if (!headers) return null; + const v = + headers["x-video-gen-model"] || + headers["x-mcp-model"] || + headers["x-model"]; + if (!v) return null; + const s = String(v).trim(); + return s || null; +} + +function pickHeaderString(headers, name, fallback) { + if (!headers) return fallback; + const v = headers[name]; + if (v === undefined || v === null) return fallback; + const s = String(v).trim(); + return s ? s : fallback; +} + +function pickHeaderInt(headers, name, fallback) { + if (!headers) return fallback; + const v = headers[name]; + if (v === undefined || v === null) return fallback; + const n = parseInt(String(v).trim(), 10); + return Number.isFinite(n) ? n : fallback; +} + +function pickHeaderBool(headers, name, fallback) { + if (!headers) return fallback; + const v = headers[name]; + if (v === undefined || v === null) return fallback; + const s = String(v).trim().toLowerCase(); + if (s === "true" || s === "1" || s === "yes") return true; + if (s === "false" || s === "0" || s === "no") return false; + return fallback; +} + +async function callZhipu({ url, token, method = "POST", body }) { + const init = { + method, + headers: { + Authorization: `Bearer ${token}`, + "Content-Type": "application/json", + }, + }; + if (body !== undefined) init.body = JSON.stringify(body); + const resp = await fetch(url, init); + const text = await resp.text(); + let data; + try { + data = JSON.parse(text); + } catch { + data = { raw: text }; + } + if (!resp.ok) { + const err = new Error( + `Zhipu API error: ${resp.status} ${resp.statusText} - ${text}` + ); + err.status = resp.status; + err.detail = data; + throw err; + } + return data; +} + +// ===== 工具:提交视频生成(同步只提交,立刻返回)===== +async function submitVideo({ + token, + model, + prompt, + image_url, + size, + quality, + with_audio, + fps, + duration, + watermark_enabled, +}) { + // 平台要求 image_url 和 prompt 至少传一个 + const body = { + model, + quality, + with_audio: Boolean(with_audio), + watermark_enabled: Boolean(watermark_enabled), + fps, + duration, + // 由服务端生成唯一 request_id,便于日志关联;不暴露给 AI + request_id: randomUUID(), + }; + if (prompt) body.prompt = prompt; + if (image_url) body.image_url = image_url; + if (size) body.size = size; + + const data = await callZhipu({ + url: ZHIPU_SUBMIT_URL, + token, + body, + }); + return data; // { model, id, request_id, task_status } +} + +// ===== 工具:查询异步结果(单次拉取,不内部轮询)===== +async function queryAsyncResult({ token, id }) { + const data = await callZhipu({ + url: ZHIPU_QUERY_URL(id), + token, + method: "GET", + }); + return data; // { id, request_id, model, task_status, video_result?, ... } +} + +function buildServer() { + const server = new McpServer( + { + name: "video-gen", + version: "1.0.0", + }, + { + capabilities: { + tools: {}, + }, + } + ); + + // ---------- 工具 1:generate_video ---------- + server.tool( + "generate_video", + "Submit a video generation task (text-to-video or image-to-video) to Zhipu BigModel. " + + "Returns the task_id immediately; poll the result later with query_video. " + + "Provide prompt and/or image_url (at least one is required).", + { + prompt: z + .string() + .optional() + .describe( + "Video text description (max 512 chars). At least one of prompt / image_url is required." + ), + image_url: z + .string() + .optional() + .describe( + "Reference image URL (or base64) for image-to-video. Supports up to 2 URLs for first/last frame. Image <= 5MB, .png/.jpeg/.jpg." + ), + size: z + .string() + .optional() + .describe( + "Video size, e.g. 1920x1080, 1080x1920, 1024x1024, 1280x720, etc." + ), + with_audio: z + .boolean() + .optional() + .describe("Whether to generate AI audio. Default false."), + }, + async (args, extra) => { + const headers = extra?.requestInfo?.headers; + const token = pickToken(headers); + if (!token) { + return { + isError: true, + content: [{ type: "text", text: "Missing authentication token." }], + }; + } + + // AI 不可见:全部走 header + const model = pickModel(headers) || DEFAULT_MODEL; + const quality = pickHeaderString(headers, "x-video-gen-quality", DEFAULT_QUALITY); + const fps = pickHeaderInt(headers, "x-video-gen-fps", DEFAULT_FPS); + const duration = pickHeaderInt(headers, "x-video-gen-duration", DEFAULT_DURATION); + const watermark_enabled = pickHeaderBool( + headers, + "x-video-gen-watermark", + DEFAULT_WATERMARK_ENABLED + ); + + if (!args.prompt && !args.image_url) { + return { + isError: true, + content: [ + { + type: "text", + text: "Either prompt or image_url must be provided.", + }, + ], + }; + } + + try { + const data = await submitVideo({ + token, + model, + prompt: args.prompt, + image_url: args.image_url, + size: args.size, + quality, + with_audio: args.with_audio ?? false, + fps, + duration, + watermark_enabled, + }); + + const summary = + `Model: ${model}\n` + + `task_id: ${data.id}\n` + + `request_id: ${data.request_id}\n` + + `task_status: ${data.task_status}\n` + + `\n` + + `Video generation is asynchronous. Call query_video with task_id="${data.id}" to fetch the result.`; + + return { + content: [{ type: "text", text: summary }], + }; + } catch (e) { + return { + isError: true, + content: [ + { + type: "text", + text: `Failed to submit video task: ${e.message}${ + e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : "" + }`, + }, + ], + }; + } + } + ); + + // ---------- 工具 2:query_video ---------- + server.tool( + "query_video", + "Query the status of a previously submitted video generation task. " + + "Returns task_status and, if SUCCESS, the video URL(s).", + { + task_id: z + .string() + .min(1) + .describe("The task id returned by generate_video."), + }, + async (args, extra) => { + const headers = extra?.requestInfo?.headers; + const token = pickToken(headers); + if (!token) { + return { + isError: true, + content: [{ type: "text", text: "Missing authentication token." }], + }; + } + + try { + const data = await queryAsyncResult({ + token, + id: args.task_id, + }); + + const status = data.task_status || "UNKNOWN"; + if (status === "SUCCESS") { + const v = (data.video_result || [])[0]; + if (!v || !v.url) { + return { + isError: true, + content: [ + { + type: "text", + text: `Task succeeded but no video URL returned. Raw: ${JSON.stringify(data)}`, + }, + ], + }; + } + const summary = + `task_id: ${data.id}\n` + + `model: ${data.model}\n` + + `task_status: SUCCESS\n` + + `Video URL: ${v.url}\n` + + (v.cover_image_url ? `Cover: ${v.cover_image_url}\n` : ""); + return { + content: [ + { type: "text", text: summary }, + { type: "text", text: v.url }, + ], + }; + } + + // PROCESSING / FAIL / 其他:原样返回关键字段 + const errBlock = data.error + ? `\nerror: ${JSON.stringify(data.error)}` + : ""; + return { + isError: status === "FAIL", + content: [ + { + type: "text", + text: + `task_id: ${data.id}\n` + + `model: ${data.model}\n` + + `task_status: ${status}` + + errBlock, + }, + ], + }; + } catch (e) { + return { + isError: true, + content: [ + { + type: "text", + text: `Failed to query video task: ${e.message}${ + e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : "" + }`, + }, + ], + }; + } + } + ); + + return server; +} + +async function startHttp({ port, host }) { + const app = express(); + app.use(express.json({ limit: "2mb" })); + + // session -> { server, transport } 映射 + const sessions = new Map(); + + app.get("/health", (_req, res) => { + res.json({ status: "ok", service: "video-gen", sessions: sessions.size }); + }); + + async function handleSessionRequest(req, res) { + const sessionId = req.headers["mcp-session-id"]; + + // 已有 session:复用 transport + if (sessionId && sessions.has(sessionId)) { + const { transport } = sessions.get(sessionId); + await transport.handleRequest(req, res, req.body); + return; + } + + // 新 session:必须是 initialize 请求 + if (!isInitializeRequest(req.body)) { + res.status(400).json({ + jsonrpc: "2.0", + error: { + code: -32000, + message: "Bad Request: missing valid Mcp-Session-Id for non-initialize request", + }, + id: req.body?.id ?? null, + }); + return; + } + + const newId = randomUUID(); + const server = buildServer(); + const transport = new StreamableHTTPServerTransport({ + sessionIdGenerator: () => newId, + onsessioninitialized: (id) => { + sessions.set(id, { server, transport }); + }, + }); + + transport.onclose = () => { + if (transport.sessionId) { + sessions.delete(transport.sessionId); + } + }; + + await server.connect(transport); + await transport.handleRequest(req, res, req.body); + } + + // POST /mcp: 主入口 + app.post("/mcp", handleSessionRequest); + + // GET /mcp & DELETE /mcp: 用于 SSE 流 / 会话关闭 + const handleOther = async (req, res) => { + const sessionId = req.headers["mcp-session-id"]; + if (!sessionId || !sessions.has(sessionId)) { + res.status(400).send("Invalid or missing session ID"); + return; + } + const { transport } = sessions.get(sessionId); + await transport.handleRequest(req, res); + }; + app.get("/mcp", handleOther); + app.delete("/mcp", handleOther); + + app.listen(port, host, () => { + console.log( + `[video-gen] MCP HTTP server listening on http://${host}:${port}/mcp` + ); + }); +} + +async function startStdio() { + const server = buildServer(); + const { StdioServerTransport } = await import( + "@modelcontextprotocol/sdk/server/stdio.js" + ); + const transport = new StdioServerTransport(); + await server.connect(transport); + console.error("[video-gen] MCP stdio server started"); +} + +const args = parseArgs(process.argv.slice(2)); +if (args.http) { + startHttp({ port: args.port, host: args.host }).catch((e) => { + console.error("[video-gen] failed to start http server:", e); + process.exit(1); + }); +} else { + startStdio().catch((e) => { + console.error("[video-gen] failed to start stdio server:", e); + process.exit(1); + }); +} \ No newline at end of file diff --git a/mcp/web-search-free/Dockerfile b/mcp/web-search-free/Dockerfile index e280e95..6b655d4 100644 --- a/mcp/web-search-free/Dockerfile +++ b/mcp/web-search-free/Dockerfile @@ -2,10 +2,10 @@ FROM node:22-slim WORKDIR /app -# 全局安装包 -RUN npm install -g @sheep233_/dsh-web-search-free +# 零运行时依赖:直接拷贝本地重构的源码,无需 npm install +COPY package.json server.js mcp.js core.js ./ EXPOSE 3000 -# 直接用 node 执行包内的 MCP server 入口,启用 HTTP/SSE 模式,监听 3000 端口 -CMD ["node", "/usr/local/lib/node_modules/@sheep233_/dsh-web-search-free/lib/mcp-server.js", "--http", "--port", "3000", "--host", "0.0.0.0"] +# HTTP/SSE 模式监听 3000 端口(stdio 模式见 package.json 的 start:stdio) +CMD ["node", "server.js", "--http", "--port", "3000", "--host", "0.0.0.0"] diff --git a/mcp/web-search-free/README.md b/mcp/web-search-free/README.md new file mode 100644 index 0000000..2525910 --- /dev/null +++ b/mcp/web-search-free/README.md @@ -0,0 +1,42 @@ +# web-search-free + +免费网页搜索 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-free` 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 `npm install -g`)。 + +```bash +docker compose build mcp-web-search-free && docker compose up -d mcp-web-search-free +``` diff --git a/mcp/web-search-free/core.js b/mcp/web-search-free/core.js new file mode 100644 index 0000000..81301c3 --- /dev/null +++ b/mcp/web-search-free/core.js @@ -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-free/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; +} diff --git a/mcp/web-search-free/mcp.js b/mcp/web-search-free/mcp.js new file mode 100644 index 0000000..e0e3092 --- /dev/null +++ b/mcp/web-search-free/mcp.js @@ -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 = 'dsh-web-search-free'; +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: 'number', 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) }, + }; + } +} diff --git a/mcp/web-search-free/package.json b/mcp/web-search-free/package.json new file mode 100644 index 0000000..4c42281 --- /dev/null +++ b/mcp/web-search-free/package.json @@ -0,0 +1,19 @@ +{ + "name": "web-search-free", + "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-mcp": "server.js" + }, + "engines": { + "node": ">=18" + }, + "scripts": { + "start": "node server.js --http --port 3000 --host 0.0.0.0", + "start:stdio": "node server.js" + } +} diff --git a/mcp/web-search-free/server.js b/mcp/web-search-free/server.js new file mode 100644 index 0000000..970c4a8 --- /dev/null +++ b/mcp/web-search-free/server.js @@ -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 ] [--host ])────────────────────── +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-mcp] 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(); +}