From e387293f00d1f9e5c9d885ddb7ee85e519fb3780 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 11:11:32 +0800 Subject: [PATCH 01/41] init mcp server --- mcp/docker-compose.yml | 17 +++++++++++++++++ mcp/image-gen/Dockerfile | 15 +++++++++++++++ mcp/image-gen/package.json | 14 ++++++++++++++ mcp/web-search-free/Dockerfile | 11 +++++++++++ 4 files changed, 57 insertions(+) create mode 100644 mcp/docker-compose.yml create mode 100644 mcp/image-gen/Dockerfile create mode 100644 mcp/image-gen/package.json create mode 100644 mcp/web-search-free/Dockerfile diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml new file mode 100644 index 0000000..0a09846 --- /dev/null +++ b/mcp/docker-compose.yml @@ -0,0 +1,17 @@ +services: + mcp-web-search-free: + build: ./web-search-free + container_name: mcp-web-search-free + restart: unless-stopped + expose: + - "3000" + environment: + - VIRTUAL_HOST=web-search.ai.foresh.com + - VIRTUAL_PORT=3000 + - CERT_NAME=default + networks: + - my-app-network + +networks: + my-app-network: + external: true diff --git a/mcp/image-gen/Dockerfile b/mcp/image-gen/Dockerfile new file mode 100644 index 0000000..daa9bd6 --- /dev/null +++ b/mcp/image-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"] diff --git a/mcp/image-gen/package.json b/mcp/image-gen/package.json new file mode 100644 index 0000000..e89f44b --- /dev/null +++ b/mcp/image-gen/package.json @@ -0,0 +1,14 @@ +{ + "name": "mcp-image-gen", + "version": "1.0.0", + "description": "MCP server for image generation via Zhipu BigModel CogView-3-Flash", + "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" + } +} diff --git a/mcp/web-search-free/Dockerfile b/mcp/web-search-free/Dockerfile new file mode 100644 index 0000000..e280e95 --- /dev/null +++ b/mcp/web-search-free/Dockerfile @@ -0,0 +1,11 @@ +FROM node:22-slim + +WORKDIR /app + +# 全局安装包 +RUN npm install -g @sheep233_/dsh-web-search-free + +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"] From b2c683d455f0fc90e954c7df64bed2fb6940a158 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 11:13:03 +0800 Subject: [PATCH 02/41] add image-gen server --- mcp/docker-compose.yml | 13 ++ mcp/image-gen/.dockerignore | 3 + mcp/image-gen/src/mcp-server.js | 289 ++++++++++++++++++++++++++++++++ 3 files changed, 305 insertions(+) create mode 100644 mcp/image-gen/.dockerignore create mode 100644 mcp/image-gen/src/mcp-server.js diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index 0a09846..a6d7521 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -12,6 +12,19 @@ services: networks: - my-app-network + mcp-image-gen: + build: ./image-gen + container_name: mcp-image-gen + restart: unless-stopped + expose: + - "3000" + environment: + - VIRTUAL_HOST=image-gen.ai.foresh.com + - VIRTUAL_PORT=3000 + - CERT_NAME=default + networks: + - my-app-network + networks: my-app-network: external: true diff --git a/mcp/image-gen/.dockerignore b/mcp/image-gen/.dockerignore new file mode 100644 index 0000000..b0e3907 --- /dev/null +++ b/mcp/image-gen/.dockerignore @@ -0,0 +1,3 @@ +node_modules +npm-debug.log +.DS_Store diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js new file mode 100644 index 0000000..dc9de2b --- /dev/null +++ b/mcp/image-gen/src/mcp-server.js @@ -0,0 +1,289 @@ +#!/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_API_URL = + "https://open.bigmodel.cn/api/paas/v4/images/generations"; +const DEFAULT_MODEL = "CogView-3-Flash"; + +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(req) { + // 优先从 http header 中获取 token(兼容多种命名) + const headers = (req && req.headers) || {}; + const candidates = [ + headers["x-image-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; +} + +async function callZhipuImagesGenerations({ token, model, prompt, size }) { + const body = { model, prompt }; + if (size) body.size = size; + const resp = await fetch(ZHIPU_API_URL, { + method: "POST", + headers: { + Authorization: `Bearer ${token}`, + "Content-Type": "application/json", + }, + body: JSON.stringify(body), + }); + 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; +} + +function extractUrls(data) { + if (!data) return []; + if (Array.isArray(data.data)) { + return data.data + .map((it) => it && (it.url || it.b64_json)) + .filter(Boolean); + } + if (typeof data.url === "string") return [data.url]; + return []; +} + +function buildServer() { + const server = new McpServer( + { + name: "image-gen", + version: "1.0.0", + }, + { + capabilities: { + tools: {}, + }, + } + ); + + server.tool( + "generate_image", + "调用智谱 CogView 图片生成 API,根据 prompt 生成图片,返回图片 URL。可选指定 model 和 size。", + { + prompt: z + .string() + .min(1) + .describe("图片生成提示词,描述想要生成的画面内容"), + model: z + .string() + .optional() + .describe("模型名称,可选,默认 CogView-3-Flash"), + size: z + .string() + .optional() + .describe( + "图片尺寸,例如 1024x1024、1280x1280、1024x1792、1792x1024、768x1344、1344x768,遵循智谱 API 规格" + ), + }, + async (args, extra) => { + const req = extra?.requestInfo?.req; + const token = req ? pickToken(req) : null; + if (!token) { + return { + isError: true, + content: [ + { + type: "text", + text: + "缺少鉴权 token,请通过 HTTP 请求头(例如 Authorization: Bearer 或 X-Image-Gen-Token: )传递。", + }, + ], + }; + } + + const model = args.model || DEFAULT_MODEL; + const size = args.size; + + try { + const data = await callZhipuImagesGenerations({ + token, + model, + prompt: args.prompt, + size, + }); + const urls = extractUrls(data); + if (urls.length === 0) { + return { + isError: true, + content: [ + { + type: "text", + text: `调用成功但未返回图片 URL:${JSON.stringify(data)}`, + }, + ], + }; + } + const summary = urls + .map((u, i) => `图片 ${i + 1}: ${u}`) + .join("\n"); + return { + content: [ + { + type: "text", + text: `模型: ${model}\n提示词: ${args.prompt}\n${summary}`, + }, + ...urls.map((u) => ({ type: "text", text: u })), + ], + }; + } catch (e) { + return { + isError: true, + content: [ + { + type: "text", + text: `生成图片失败: ${e.message}${ + e.detail ? `\n详情: ${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: "image-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( + `[image-gen] MCP HTTP server listening on http://${host}:${port}/mcp` + ); + }); +} + +async function startStdio() { + // 保留 stdio 启动方式,便于本地直接调试 + const server = buildServer(); + const { StdioServerTransport } = await import( + "@modelcontextprotocol/sdk/server/stdio.js" + ); + const transport = new StdioServerTransport(); + await server.connect(transport); + console.error("[image-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("[image-gen] failed to start http server:", e); + process.exit(1); + }); +} else { + startStdio().catch((e) => { + console.error("[image-gen] failed to start stdio server:", e); + process.exit(1); + }); +} From f7b4e17cfea21f5f407f94401d74d55e96183bad Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 11:17:46 +0800 Subject: [PATCH 03/41] =?UTF-8?q?add=20model=E5=8F=82=E6=95=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/image-gen/src/mcp-server.js | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index dc9de2b..c51c6c4 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -47,6 +47,18 @@ function pickToken(req) { return null; } +function pickModel(req) { + // 从 http header 读取默认 model(可选),未设置返回 null + const headers = (req && req.headers) || {}; + const v = + headers["x-image-gen-model"] || + headers["x-mcp-model"] || + headers["x-model"]; + if (!v) return null; + const s = String(v).trim(); + return s || null; +} + async function callZhipuImagesGenerations({ token, model, prompt, size }) { const body = { model, prompt }; if (size) body.size = size; @@ -135,7 +147,9 @@ function buildServer() { }; } - const model = args.model || DEFAULT_MODEL; + // 优先级:工具参数 model > HTTP header 中的 model > DEFAULT_MODEL + const headerModel = req ? pickModel(req) : null; + const model = args.model || headerModel || DEFAULT_MODEL; const size = args.size; try { From 76aa1aa604a3c24aec61f90a6ca6a264eb4e8e81 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 12:08:54 +0800 Subject: [PATCH 04/41] =?UTF-8?q?feat(image-gen):=20=E7=A7=BB=E9=99=A4=20h?= =?UTF-8?q?eader=20=E4=BC=A0=20model=20=E7=9A=84=E9=80=BB=E8=BE=91?= =?UTF-8?q?=EF=BC=8C=E4=BB=85=E4=BF=9D=E7=95=99=E5=B7=A5=E5=85=B7=E5=8F=82?= =?UTF-8?q?=E6=95=B0=20=E2=86=92=20=E5=85=9C=E5=BA=95=E9=BB=98=E8=AE=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 extractModelFromHeaders / X-Image-Gen-Model 等 header 解析路径 - model 优先级简化为单链:arguments.model → DEFAULT_MODEL (CogView-3-Flash) - 新增 README.md,覆盖启动、客户端配置、工具用法、curl 调试、FAQ --- mcp/image-gen/README.md | 237 ++++++++++++++++++++++++++++++++ mcp/image-gen/src/mcp-server.js | 96 ++++++------- 2 files changed, 278 insertions(+), 55 deletions(-) create mode 100644 mcp/image-gen/README.md diff --git a/mcp/image-gen/README.md b/mcp/image-gen/README.md new file mode 100644 index 0000000..dff83bf --- /dev/null +++ b/mcp/image-gen/README.md @@ -0,0 +1,237 @@ +# MCP Image Gen + +一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成服务,对接智谱 BigModel 的 `CogView` 系列模型。每次调用通过 HTTP header 传入智谱 API 的 Bearer Token,支持在工具参数中按需切换模型。 + +- 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) +- 上游:[智谱 BigModel Images Generations API](https://open.bigmodel.cn/dev/api#images) +- 默认模型:`CogView-3-Flash` +- 端口:`3000` +- 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token + +--- + +## 快速开始 + +### 启动(docker-compose) + +仓库根目录 `docker-compose.yml` 已包含本服务: + +```bash +cd /root/workspace/tools/mcp +docker compose up -d --build mcp-image-gen +``` + +服务容器名 `mcp-image-gen`,通过反代暴露为 `https://image-gen.ai.foresh.com/mcp`。 + +直接连容器调试: + +```bash +docker exec -it mcp-image-gen sh +# 或本机 +curl http://localhost:3000/health +# {"status":"ok","service":"image-gen","sessions":0} +``` + +### MCP 客户端配置 + +#### Claude Desktop / Cursor 等支持 `headers` 配置的客户端 + +```jsonc +// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json +// Cursor: ~/.cursor/mcp.json +{ + "mcpServers": { + "image-gen": { + "url": "https://image-gen.ai.foresh.com/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +> **重要**:客户端必须在 **每一个 HTTP 请求**(`initialize` / `notifications/initialized` / `tools/call`)都带上 `Authorization` header。配置在 `headers` 里、由客户端自动重发即可。直连模式下 token 不在 session 间共享。 + +#### 不支持 `headers` 字段的客户端 + +如果客户端只支持 `command`/`args` 启动方式,可改用 stdio 模式(需自行包一层把 token 注入环境变量,再让工具回调从环境变量读——当前实现 HTTP 模式下不依赖环境变量,需自行扩展)。 + +--- + +## 工具:generate_image + +调用智谱图片生成接口,返回图片 URL。 + +### 参数 + +| 名称 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `prompt` | string | ✅ | 图片生成提示词,描述想要的画面内容 | +| `model` | string | ❌ | 模型名称,默认 `CogView-3-Flash`。可填 `CogView-3` / `CogView-3-Flash` 等智谱支持的模型 | +| `size` | string | ❌ | 图片尺寸,例如 `1024x1024`、`1280x1280`、`1024x1792`、`1792x1024`、`768x1344`、`1344x768`,遵循智谱 API 规格 | + +### Model 优先级(单链) + +``` +工具参数 arguments.model → DEFAULT_MODEL (CogView-3-Flash) +``` + +每次 `tools/call` 都是独立决策,**想换模型就在该次调用传 `model` 参数**,不需要重连/换 session。 + +### 返回 + +工具成功时返回若干 `text` 块,第一块是摘要,后续每块各包含一张图片的 URL(方便 LLM 直接贴图或下载): + +```jsonc +{ + "content": [ + { "type": "text", "text": "模型: CogView-3-Flash\n提示词: ...\n图片 1: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." }, + { "type": "text", "text": "https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." } + ] +} +``` + +URL 由智谱签名下发,**带有效期**(通常 24h),如需长期保存请在收到后及时转存到自己的存储。 + +失败时返回 `isError: true` 的错误描述。 + +--- + +## 鉴权细节 + +每个 HTTP 请求必须携带智谱 API Token,server 从以下 header 字段按顺序识别,**首个非空值生效**: + +| 优先级 | Header | 说明 | +|---|---|---| +| 1 | `Authorization: Bearer ` | 推荐,标准 OAuth 风格 | +| 2 | `X-Image-Gen-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | +| 3 | `X-Mcp-Token: ` | 通用兜底 | + +**Token 不会写入服务端任何存储**,仅在 initialize 阶段绑定到内存中的 session 对象,session 结束立即释放。 + +### 错误响应 + +| 场景 | HTTP 状态 | 表现 | +|---|---|---| +| initialize 时缺 token | `401` | JSON-RPC `error.message` 提示补充 header | +| 智谱 API 4xx/5xx | `200`(MCP 工具返回) | `isError: true`,正文含智谱返回的状态码和 body | +| 网络失败 | `200`(MCP 工具返回) | `isError: true`,正文含 `fetch` 错误信息 | + +--- + +## 用 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. 调 generate_image +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_image", + "arguments": { + "prompt": "一只可爱的小猫咪,坐在阳光明媚的窗台上,背景是蓝天白云", + "size": "1280x1280" + } + } + }' +``` + +响应是 SSE 格式(`event: message` + `data: {...}`),用 `grep '^data:'` 抽 JSON 即可。 + +--- + +## 架构与文件 + +``` +image-gen/ +├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server +├── .dockerignore # 排除 node_modules +├── package.json # @modelcontextprotocol/sdk + express + zod +├── README.md # 本文件 +└── src/ + └── mcp-server.js # 单文件实现:HTTP server + MCP transport + tool +``` + +### 关键设计 + +- **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用,避免每请求重建 +- **Token 闭包注入**:在 Express 入口处从 header 提取 token,闭包传给 `buildServer({ token })`,tool 回调里直接使用;不依赖 SDK 内部字段 +- **模型参数单链**:`arguments.model` → `DEFAULT_MODEL`,无 header 干预 +- **URL 提取**:`response.data[].url` 为准,若返回 `b64_json` 也会一并返回 + +### 默认模型 + +```js +// src/mcp-server.js +const DEFAULT_MODEL = "CogView-3-Flash"; +``` + +修改后 `docker compose up -d --build mcp-image-gen` 即可生效。 + +--- + +## 常见问题 + +**Q: 我能在工具参数里不传 `model` 吗?** +A: 可以,不传就走默认 `CogView-3-Flash`。 + +**Q: 换模型需要重连 MCP session 吗?** +A: 不需要。`model` 是工具参数,每次 `tools/call` 都生效,不需要重建 session。 + +**Q: Token 会不会泄露到日志?** +A: 当前实现只在 session 内存里持有,不会写入 stdout/stderr。Container 日志只打印 session id。 + +**Q: 收到 `Missing valid Mcp-Session-Id` 错误?** +A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize`。 + +**Q: URL 多久过期?** +A: 智谱签发 URL 默认 24h 左右,详见响应里的 `Expires` 参数。需要长期使用请自行转存到 OSS/S3。 + +**Q: 能否限制 `size` 白名单?** +A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `generate_image` 的 `size` schema 即可。 diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index c51c6c4..3f06e66 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -25,13 +25,13 @@ function parseArgs(argv) { return args; } -function pickToken(req) { - // 优先从 http header 中获取 token(兼容多种命名) - const headers = (req && req.headers) || {}; +// 从请求头里提取 token(兼容多种命名 + Bearer 前缀) +function extractTokenFromHeaders(headers) { + if (!headers) return null; const candidates = [ + headers["authorization"], headers["x-image-gen-token"], headers["x-mcp-token"], - headers["authorization"], ]; for (const v of candidates) { if (!v) continue; @@ -47,18 +47,6 @@ function pickToken(req) { return null; } -function pickModel(req) { - // 从 http header 读取默认 model(可选),未设置返回 null - const headers = (req && req.headers) || {}; - const v = - headers["x-image-gen-model"] || - headers["x-mcp-model"] || - headers["x-model"]; - if (!v) return null; - const s = String(v).trim(); - return s || null; -} - async function callZhipuImagesGenerations({ token, model, prompt, size }) { const body = { model, prompt }; if (size) body.size = size; @@ -99,17 +87,11 @@ function extractUrls(data) { return []; } -function buildServer() { +// 创建 McpServer,把 token 通过闭包注入到工具回调里 +function buildServer({ token }) { const server = new McpServer( - { - name: "image-gen", - version: "1.0.0", - }, - { - capabilities: { - tools: {}, - }, - } + { name: "image-gen", version: "1.0.0" }, + { capabilities: { tools: {} } } ); server.tool( @@ -131,25 +113,9 @@ function buildServer() { "图片尺寸,例如 1024x1024、1280x1280、1024x1792、1792x1024、768x1344、1344x768,遵循智谱 API 规格" ), }, - async (args, extra) => { - const req = extra?.requestInfo?.req; - const token = req ? pickToken(req) : null; - if (!token) { - return { - isError: true, - content: [ - { - type: "text", - text: - "缺少鉴权 token,请通过 HTTP 请求头(例如 Authorization: Bearer 或 X-Image-Gen-Token: )传递。", - }, - ], - }; - } - - // 优先级:工具参数 model > HTTP header 中的 model > DEFAULT_MODEL - const headerModel = req ? pickModel(req) : null; - const model = args.model || headerModel || DEFAULT_MODEL; + async (args) => { + // model 优先级:工具参数 > DEFAULT_MODEL + const model = args.model || DEFAULT_MODEL; const size = args.size; try { @@ -206,17 +172,21 @@ async function startHttp({ port, host }) { const app = express(); app.use(express.json({ limit: "2mb" })); - // session -> { server, transport } 映射 + // session -> transport + server + token/model const sessions = new Map(); app.get("/health", (_req, res) => { res.json({ status: "ok", service: "image-gen", sessions: sessions.size }); }); - async function handleSessionRequest(req, res) { + // 主入口:先从 header 取 token(每个 HTTP 请求都取一次), + // 然后用这个 token 创建一个新的 server+transport; + // 已有 session 直接复用 transport,token 沿用 session 首次创建时的值 + // (避免跨请求 token 不一致;MCP 客户端本来就该每次都带同一个 token) + const handleSessionRequest = async (req, res) => { const sessionId = req.headers["mcp-session-id"]; - // 已有 session:复用 transport + // 已有 session:复用 transport,token/model 直接从 session 缓存里拿 if (sessionId && sessions.has(sessionId)) { const { transport } = sessions.get(sessionId); await transport.handleRequest(req, res, req.body); @@ -236,26 +206,42 @@ async function startHttp({ port, host }) { return; } + // 从本次请求 header 取 token + const token = extractTokenFromHeaders(req.headers); + if (!token) { + res.status(401).json({ + jsonrpc: "2.0", + error: { + code: -32001, + message: + "缺少鉴权 token,请通过 HTTP 请求头(例如 Authorization: Bearer 或 X-Image-Gen-Token: )传递。", + }, + id: req.body?.id ?? null, + }); + return; + } + const newId = randomUUID(); - const server = buildServer(); + const server = buildServer({ token }); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newId, onsessioninitialized: (id) => { - sessions.set(id, { server, transport }); + sessions.set(id, { server, transport, token }); + console.log(`[image-gen] session initialized: ${id}`); }, }); transport.onclose = () => { if (transport.sessionId) { sessions.delete(transport.sessionId); + console.log(`[image-gen] session closed: ${transport.sessionId}`); } }; await server.connect(transport); await transport.handleRequest(req, res, req.body); - } + }; - // POST /mcp: 主入口 app.post("/mcp", handleSessionRequest); // GET /mcp & DELETE /mcp: 用于 SSE 流 / 会话关闭 @@ -279,14 +265,14 @@ async function startHttp({ port, host }) { } async function startStdio() { - // 保留 stdio 启动方式,便于本地直接调试 - const server = buildServer(); + // stdio 模式下没有 HTTP header,token 暂未支持(保留入口便于本地调试) + const server = buildServer({ token: "" }); const { StdioServerTransport } = await import( "@modelcontextprotocol/sdk/server/stdio.js" ); const transport = new StdioServerTransport(); await server.connect(transport); - console.error("[image-gen] MCP stdio server started"); + console.error("[image-gen] MCP stdio server started (no auth)"); } const args = parseArgs(process.argv.slice(2)); From eba3a3c7ffe22d6f9034123f34dfbbb683997ec9 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 12:43:23 +0800 Subject: [PATCH 05/41] =?UTF-8?q?fix(image-gen):=20=E4=BB=8E=20extra.reque?= =?UTF-8?q?stInfo.headers=20=E8=AF=BB=E5=8F=96=20token=20&=20model?= =?UTF-8?q?=EF=BC=88=E4=BF=AE=E6=AD=A3=E5=AD=97=E6=AE=B5=E8=B7=AF=E5=BE=84?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 之前 pickToken/pickModel 用的 'extra?.requestInfo?.req?.headers' 多写了一层 '.req', SDK 实际只有 extra.requestInfo.headers(参见 webStandardStreamableHttp.js buildRequestInfo), 导致 token/model 始终为 null,AI 调用时实际走默认 model 且若未额外修过 token 则报 401。 本提交: - 取 header 改用 extra.requestInfo.headers - pickToken/pickModel 签名改为接收 headers 对象(去掉对 req 的依赖) - Model 仍只在 tools/call 阶段从 header 读取,不存 session - Model 优先级:header > DEFAULT_MODEL(已删 schema 里的 model 字段,AI 无法误传) - README 同步更新鉴权与 model 章节 --- mcp/image-gen/README.md | 36 +++++++---- mcp/image-gen/src/mcp-server.js | 103 ++++++++++++++++++-------------- 2 files changed, 80 insertions(+), 59 deletions(-) diff --git a/mcp/image-gen/README.md b/mcp/image-gen/README.md index dff83bf..413b2ba 100644 --- a/mcp/image-gen/README.md +++ b/mcp/image-gen/README.md @@ -68,16 +68,23 @@ curl http://localhost:3000/health | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| | `prompt` | string | ✅ | 图片生成提示词,描述想要的画面内容 | -| `model` | string | ❌ | 模型名称,默认 `CogView-3-Flash`。可填 `CogView-3` / `CogView-3-Flash` 等智谱支持的模型 | | `size` | string | ❌ | 图片尺寸,例如 `1024x1024`、`1280x1280`、`1024x1792`、`1792x1024`、`768x1344`、`1344x768`,遵循智谱 API 规格 | -### Model 优先级(单链) +### Model 控制(不在工具参数中暴露) -``` -工具参数 arguments.model → DEFAULT_MODEL (CogView-3-Flash) -``` +模型名由调用方在 **tools/call 这一次的 HTTP header** 中传递,**AI 看不到也填不了**,避免其误传。识别顺序(首个非空值生效): -每次 `tools/call` 都是独立决策,**想换模型就在该次调用传 `model` 参数**,不需要重连/换 session。 +| 优先级 | Header | +|---|---| +| 1 | `X-Image-Gen-Model` | +| 2 | `X-Mcp-Model` | +| 3 | `X-Model` | + +如果都没传,走代码内常量 `DEFAULT_MODEL = "CogView-3-Flash"`。 + +**为什么不放进工具参数?** 调用方一般是 AI 助手(Claude / Cursor 等),它不需要也没能力选择用哪个模型;模型选择属于部署/路由策略,由请求的发起方在 HTTP header 里注入更可控。 + +### 返回 ### 返回 @@ -104,11 +111,11 @@ URL 由智谱签名下发,**带有效期**(通常 24h),如需长期保 | 优先级 | Header | 说明 | |---|---|---| -| 1 | `Authorization: Bearer ` | 推荐,标准 OAuth 风格 | -| 2 | `X-Image-Gen-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | -| 3 | `X-Mcp-Token: ` | 通用兜底 | +| 1 | `X-Image-Gen-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | +| 2 | `X-Mcp-Token: ` | 通用兜底 | +| 3 | `Authorization: Bearer ` | 标准 OAuth 风格(排最后是为避免误用) | -**Token 不会写入服务端任何存储**,仅在 initialize 阶段绑定到内存中的 session 对象,session 结束立即释放。 +Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不进 session。 ### 错误响应 @@ -218,11 +225,14 @@ const DEFAULT_MODEL = "CogView-3-Flash"; ## 常见问题 -**Q: 我能在工具参数里不传 `model` 吗?** -A: 可以,不传就走默认 `CogView-3-Flash`。 +**Q: AI 不知道有哪些 model 可选,怎么办?** +A: 这是设计意图。模型选择属于路由策略,不让 AI 决策。调用方在 HTTP header `X-Image-Gen-Model` 里注入即可。 **Q: 换模型需要重连 MCP session 吗?** -A: 不需要。`model` 是工具参数,每次 `tools/call` 都生效,不需要重建 session。 +A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取,不需要重建 session。 + +**Q: 为什么 Model 优先级不是「工具参数 > header」?** +A: 因为我们故意不在 schema 暴露 model 参数,AI 根本不会传 model,所以「工具参数 > header」这条分支实际上不存在。 **Q: Token 会不会泄露到日志?** A: 当前实现只在 session 内存里持有,不会写入 stdout/stderr。Container 日志只打印 session id。 diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index 3f06e66..1713235 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -25,13 +25,12 @@ function parseArgs(argv) { return args; } -// 从请求头里提取 token(兼容多种命名 + Bearer 前缀) -function extractTokenFromHeaders(headers) { +function pickToken(headers) { if (!headers) return null; const candidates = [ - headers["authorization"], headers["x-image-gen-token"], headers["x-mcp-token"], + headers["authorization"], ]; for (const v of candidates) { if (!v) continue; @@ -47,6 +46,17 @@ function extractTokenFromHeaders(headers) { return null; } +function pickModel(headers) { + if (!headers) return null; + const v = + headers["x-image-gen-model"] || + headers["x-mcp-model"] || + headers["x-model"]; + if (!v) return null; + const s = String(v).trim(); + return s || null; +} + async function callZhipuImagesGenerations({ token, model, prompt, size }) { const body = { model, prompt }; if (size) body.size = size; @@ -87,25 +97,27 @@ function extractUrls(data) { return []; } -// 创建 McpServer,把 token 通过闭包注入到工具回调里 -function buildServer({ token }) { +function buildServer() { const server = new McpServer( - { name: "image-gen", version: "1.0.0" }, - { capabilities: { tools: {} } } + { + name: "image-gen", + version: "1.0.0", + }, + { + capabilities: { + tools: {}, + }, + } ); server.tool( "generate_image", - "调用智谱 CogView 图片生成 API,根据 prompt 生成图片,返回图片 URL。可选指定 model 和 size。", + "调用智谱图片生成 API,根据 prompt 生成图片,返回图片 URL。可选指定 size。模型由调用方通过 HTTP header(X-Image-Gen-Model)控制,不在工具参数中暴露。", { prompt: z .string() .min(1) - .describe("图片生成提示词,描述想要生成的画面内容"), - model: z - .string() - .optional() - .describe("模型名称,可选,默认 CogView-3-Flash"), + .describe("图片生成提示词,描述想要的画面内容"), size: z .string() .optional() @@ -113,9 +125,28 @@ function buildServer({ token }) { "图片尺寸,例如 1024x1024、1280x1280、1024x1792、1792x1024、768x1344、1344x768,遵循智谱 API 规格" ), }, - async (args) => { - // model 优先级:工具参数 > DEFAULT_MODEL - const model = args.model || DEFAULT_MODEL; + async (args, extra) => { + // SDK 在 tool callback 的 extra.requestInfo.headers 里会透传当前 HTTP 请求的 headers + // (参见 webStandardStreamableHttp.js: buildRequestInfo 段) + const headers = extra?.requestInfo?.headers; + const token = pickToken(headers); + if (!token) { + return { + isError: true, + content: [ + { + type: "text", + text: + "缺少鉴权 token,请通过 HTTP 请求头(例如 Authorization: Bearer 或 X-Image-Gen-Token: )传递。", + }, + ], + }; + } + + // model 完全由 HTTP header 控制(X-Image-Gen-Model / X-Mcp-Model / X-Model), + // 不存进 session,每次从本次请求的 header 读取,未设置则用默认 CogView-3-Flash。 + // AI 看不到 model 参数(schema 中已删除),避免其误传。 + const model = pickModel(headers) || DEFAULT_MODEL; const size = args.size; try { @@ -172,21 +203,17 @@ async function startHttp({ port, host }) { const app = express(); app.use(express.json({ limit: "2mb" })); - // session -> transport + server + token/model + // session -> { server, transport } 映射 const sessions = new Map(); app.get("/health", (_req, res) => { res.json({ status: "ok", service: "image-gen", sessions: sessions.size }); }); - // 主入口:先从 header 取 token(每个 HTTP 请求都取一次), - // 然后用这个 token 创建一个新的 server+transport; - // 已有 session 直接复用 transport,token 沿用 session 首次创建时的值 - // (避免跨请求 token 不一致;MCP 客户端本来就该每次都带同一个 token) - const handleSessionRequest = async (req, res) => { + async function handleSessionRequest(req, res) { const sessionId = req.headers["mcp-session-id"]; - // 已有 session:复用 transport,token/model 直接从 session 缓存里拿 + // 已有 session:复用 transport if (sessionId && sessions.has(sessionId)) { const { transport } = sessions.get(sessionId); await transport.handleRequest(req, res, req.body); @@ -206,42 +233,26 @@ async function startHttp({ port, host }) { return; } - // 从本次请求 header 取 token - const token = extractTokenFromHeaders(req.headers); - if (!token) { - res.status(401).json({ - jsonrpc: "2.0", - error: { - code: -32001, - message: - "缺少鉴权 token,请通过 HTTP 请求头(例如 Authorization: Bearer 或 X-Image-Gen-Token: )传递。", - }, - id: req.body?.id ?? null, - }); - return; - } - const newId = randomUUID(); - const server = buildServer({ token }); + const server = buildServer(); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newId, onsessioninitialized: (id) => { - sessions.set(id, { server, transport, token }); - console.log(`[image-gen] session initialized: ${id}`); + sessions.set(id, { server, transport }); }, }); transport.onclose = () => { if (transport.sessionId) { sessions.delete(transport.sessionId); - console.log(`[image-gen] session closed: ${transport.sessionId}`); } }; await server.connect(transport); await transport.handleRequest(req, res, req.body); - }; + } + // POST /mcp: 主入口 app.post("/mcp", handleSessionRequest); // GET /mcp & DELETE /mcp: 用于 SSE 流 / 会话关闭 @@ -265,14 +276,14 @@ async function startHttp({ port, host }) { } async function startStdio() { - // stdio 模式下没有 HTTP header,token 暂未支持(保留入口便于本地调试) - const server = buildServer({ token: "" }); + // 保留 stdio 启动方式,便于本地直接调试 + const server = buildServer(); const { StdioServerTransport } = await import( "@modelcontextprotocol/sdk/server/stdio.js" ); const transport = new StdioServerTransport(); await server.connect(transport); - console.error("[image-gen] MCP stdio server started (no auth)"); + console.error("[image-gen] MCP stdio server started"); } const args = parseArgs(process.argv.slice(2)); From 594650510b0fd26fe08eae1584577e9288078b94 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 12:50:30 +0800 Subject: [PATCH 06/41] =?UTF-8?q?=E8=B0=83=E6=95=B4=E9=83=A8=E5=88=86?= =?UTF-8?q?=E6=8F=90=E7=A4=BA=E8=AF=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/image-gen/src/mcp-server.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index 1713235..7a4aff4 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -112,17 +112,17 @@ function buildServer() { server.tool( "generate_image", - "调用智谱图片生成 API,根据 prompt 生成图片,返回图片 URL。可选指定 size。模型由调用方通过 HTTP header(X-Image-Gen-Model)控制,不在工具参数中暴露。", + "根据 prompt 生成图片,返回图片 URL。可选指定 size。", { prompt: z .string() .min(1) - .describe("图片生成提示词,描述想要的画面内容"), + .describe("图片生成提示词,详细描述想要的画面内容"), size: z .string() .optional() .describe( - "图片尺寸,例如 1024x1024、1280x1280、1024x1792、1792x1024、768x1344、1344x768,遵循智谱 API 规格" + "图片尺寸,例如 1024x1024、1280x1280、1024x1792、1792x1024、768x1344、1344x768" ), }, async (args, extra) => { @@ -137,7 +137,7 @@ function buildServer() { { type: "text", text: - "缺少鉴权 token,请通过 HTTP 请求头(例如 Authorization: Bearer 或 X-Image-Gen-Token: )传递。", + "缺少鉴权 token。", }, ], }; From a29ffd9aa5428f905b9b81884ef0604e95cec9a9 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 12:52:10 +0800 Subject: [PATCH 07/41] i18n(image-gen): translate AI-facing tool response text to English The tool result content is consumed by AI agents (Claude/Cursor/...). Converted four user-facing strings to clear English: - Missing-token error message - No-URL-in-response error message - Success summary (added expiry note for AI to act on) - Generation-failure error message Code comments and tool description/describes are untouched in this commit. --- mcp/image-gen/src/mcp-server.js | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index 7a4aff4..b05484f 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -137,7 +137,7 @@ function buildServer() { { type: "text", text: - "缺少鉴权 token。", + "Missing authentication token. The caller must provide a Zhipu API token via an HTTP request header (e.g. `X-Image-Gen-Token: ` or `Authorization: Bearer `). The server is configured to read the token from the request header on every call, not from the tool arguments, so the token cannot be supplied here.", }, ], }; @@ -163,19 +163,19 @@ function buildServer() { content: [ { type: "text", - text: `调用成功但未返回图片 URL:${JSON.stringify(data)}`, + text: `The Zhipu API call succeeded but returned no image URL. Raw response: ${JSON.stringify(data)}`, }, ], }; } const summary = urls - .map((u, i) => `图片 ${i + 1}: ${u}`) + .map((u, i) => `Image ${i + 1}: ${u}`) .join("\n"); return { content: [ { type: "text", - text: `模型: ${model}\n提示词: ${args.prompt}\n${summary}`, + text: `Model: ${model}\nPrompt: ${args.prompt}\n${summary}\n\nThe image is hosted on a signed Zhipu URL and will expire (typically within 24 hours, see the URL's Expires parameter). If the user needs to keep it, download or copy the image right away.`, }, ...urls.map((u) => ({ type: "text", text: u })), ], @@ -186,8 +186,8 @@ function buildServer() { content: [ { type: "text", - text: `生成图片失败: ${e.message}${ - e.detail ? `\n详情: ${JSON.stringify(e.detail)}` : "" + text: `Failed to generate image: ${e.message}${ + e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : "" }`, }, ], From 2455778f4a7a348de367049b86d8cdf95399f485 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 12:54:00 +0800 Subject: [PATCH 08/41] Revert "i18n(image-gen): translate AI-facing tool response text to English" This reverts commit 06a9ae7151d47e0486abad1f11353164db377d45. --- mcp/image-gen/src/mcp-server.js | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index b05484f..7a4aff4 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -137,7 +137,7 @@ function buildServer() { { type: "text", text: - "Missing authentication token. The caller must provide a Zhipu API token via an HTTP request header (e.g. `X-Image-Gen-Token: ` or `Authorization: Bearer `). The server is configured to read the token from the request header on every call, not from the tool arguments, so the token cannot be supplied here.", + "缺少鉴权 token。", }, ], }; @@ -163,19 +163,19 @@ function buildServer() { content: [ { type: "text", - text: `The Zhipu API call succeeded but returned no image URL. Raw response: ${JSON.stringify(data)}`, + text: `调用成功但未返回图片 URL:${JSON.stringify(data)}`, }, ], }; } const summary = urls - .map((u, i) => `Image ${i + 1}: ${u}`) + .map((u, i) => `图片 ${i + 1}: ${u}`) .join("\n"); return { content: [ { type: "text", - text: `Model: ${model}\nPrompt: ${args.prompt}\n${summary}\n\nThe image is hosted on a signed Zhipu URL and will expire (typically within 24 hours, see the URL's Expires parameter). If the user needs to keep it, download or copy the image right away.`, + text: `模型: ${model}\n提示词: ${args.prompt}\n${summary}`, }, ...urls.map((u) => ({ type: "text", text: u })), ], @@ -186,8 +186,8 @@ function buildServer() { content: [ { type: "text", - text: `Failed to generate image: ${e.message}${ - e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : "" + text: `生成图片失败: ${e.message}${ + e.detail ? `\n详情: ${JSON.stringify(e.detail)}` : "" }`, }, ], From bc53ff31293d4b0ced19acba7d69df28aee60aa9 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 12:54:33 +0800 Subject: [PATCH 09/41] i18n(image-gen): translate tool description & token-error text to English Translate the four strings introduced in baa04d9 (\u8c03\u6574\u90e8\u5206\u63d0\u793a\u8bcd) to clear English. Other Chinese strings in this file (success summary, image-N labels, failure detail) were not changed in that commit and are intentionally left untouched here. --- mcp/image-gen/src/mcp-server.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index 7a4aff4..2fa19d3 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -112,17 +112,17 @@ function buildServer() { server.tool( "generate_image", - "根据 prompt 生成图片,返回图片 URL。可选指定 size。", + "Generate an image from a prompt and return the image URL. Optionally specify size.", { prompt: z .string() .min(1) - .describe("图片生成提示词,详细描述想要的画面内容"), + .describe("Image generation prompt; describe the desired scene in detail."), size: z .string() .optional() .describe( - "图片尺寸,例如 1024x1024、1280x1280、1024x1792、1792x1024、768x1344、1344x768" + "Image size, e.g. 1024x1024, 1280x1280, 1024x1792, 1792x1024, 768x1344, 1344x768" ), }, async (args, extra) => { @@ -137,7 +137,7 @@ function buildServer() { { type: "text", text: - "缺少鉴权 token。", + "Missing authentication token.", }, ], }; From c1eac96db1427a54dff8c8ec78c9331f2895bee7 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 12:55:42 +0800 Subject: [PATCH 10/41] i18n(image-gen): translate remaining AI-facing response text to English Translate the four remaining content.text strings in the tool callback: - 'no URL returned' error - success summary (Model / Prompt / Image N) - generation failure error - error detail label Style follows the short-sentence convention from baa04d9 (no extra explanatory notes added). --- mcp/image-gen/src/mcp-server.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index 2fa19d3..3af0655 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -163,19 +163,19 @@ function buildServer() { content: [ { type: "text", - text: `调用成功但未返回图片 URL:${JSON.stringify(data)}`, + text: `The Zhipu API call succeeded but returned no image URL. Raw response: ${JSON.stringify(data)}`, }, ], }; } const summary = urls - .map((u, i) => `图片 ${i + 1}: ${u}`) + .map((u, i) => `Image ${i + 1}: ${u}`) .join("\n"); return { content: [ { type: "text", - text: `模型: ${model}\n提示词: ${args.prompt}\n${summary}`, + text: `Model: ${model}\nPrompt: ${args.prompt}\n${summary}`, }, ...urls.map((u) => ({ type: "text", text: u })), ], @@ -186,8 +186,8 @@ function buildServer() { content: [ { type: "text", - text: `生成图片失败: ${e.message}${ - e.detail ? `\n详情: ${JSON.stringify(e.detail)}` : "" + text: `Failed to generate image: ${e.message}${ + e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : "" }`, }, ], From 44da1dcf0856f06ad38e34b1ec292828d83d02d3 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 13:04:25 +0800 Subject: [PATCH 11/41] =?UTF-8?q?=E7=BF=BB=E8=AF=91=E6=88=90=E7=AE=80?= =?UTF-8?q?=E5=8D=95=E8=8B=B1=E8=AF=AD=E6=96=B9=E4=BE=BFAI=E7=90=86?= =?UTF-8?q?=E8=A7=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/image-gen/src/mcp-server.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index 3af0655..aed9b96 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -122,7 +122,7 @@ function buildServer() { .string() .optional() .describe( - "Image size, e.g. 1024x1024, 1280x1280, 1024x1792, 1792x1024, 768x1344, 1344x768" + "Image size, Preferred sizes: 1024x1024, 1280x1280, 1536x1024, 1024x1536, Each side must be a multiple of 32." ), }, async (args, extra) => { @@ -163,7 +163,7 @@ function buildServer() { content: [ { type: "text", - text: `The Zhipu API call succeeded but returned no image URL. Raw response: ${JSON.stringify(data)}`, + text: `Returned no image URL. Raw response: ${JSON.stringify(data)}`, }, ], }; From 710200605bcb72a3baba9db96685f5b4a9d25cbb Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 16:19:34 +0800 Subject: [PATCH 12/41] 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(); +} From e378ad001f1ad76ebc8f1ebdbafa7ddd5f065ab7 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 20:58:51 +0800 Subject: [PATCH 13/41] video-gen: add /upload endpoint for local image upload Adds POST /upload (multer diskStorage, max 8MB, image/* only) returning a public URL under /uploads/* that can be passed directly to generate_video.image_url. Uploads live in container temp storage and are discarded on restart (no persistence, no auth). generate_video tool description is now built at startup with the real upload URL baked in (resolved from PUBLIC_BASE_URL env, falls back to http://localhost:) so the AI sees an exact curl command and doesn't have to guess the host. docker-compose: set PUBLIC_BASE_URL=https://video-gen.ai.foresh.com README: new upload section, reverse-proxy note, FAQ entries --- mcp/docker-compose.yml | 25 ++++---- mcp/video-gen/README.md | 101 +++++++++++++++++++++++++++++-- mcp/video-gen/package.json | 7 ++- mcp/video-gen/src/mcp-server.js | 104 +++++++++++++++++++++++++++++--- 4 files changed, 209 insertions(+), 28 deletions(-) diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index 1745ef1..24ef916 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -26,18 +26,19 @@ services: - 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 + 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 + - PUBLIC_BASE_URL=https://video-gen.ai.foresh.com + networks: + - my-app-network networks: my-app-network: - external: true \ No newline at end of file + external: true diff --git a/mcp/video-gen/README.md b/mcp/video-gen/README.md index 8dec2fa..ac8bc86 100644 --- a/mcp/video-gen/README.md +++ b/mcp/video-gen/README.md @@ -7,6 +7,7 @@ - 默认模型:`cogvideox-flash` - 端口:`3000` - 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token +- 附带 `/upload` 端点:供 AI 临时上传本地图片获取 URL(**不持久化**,容器重启即丢) --- @@ -64,6 +65,75 @@ curl http://localhost:3000/health --- +## 上传图片:POST /upload + +供 AI 临时上传本地图片、拿到 URL 后喂给 `generate_video.image_url`。**不走 MCP、不走鉴权**,仅依赖内网隔离(`my-app-network`)+ 反代层控制访问。 + +### 配置 + +通过环境变量告诉服务端「对外公开的 base URL」,用于拼接返回的 `url` 字段: + +```yaml +# docker-compose.yml +environment: + - PUBLIC_BASE_URL=https://video-gen.ai.foresh.com +``` + +未设置时 fallback 到 `http://localhost:3000`(本机调试)。 + +### 接口 + +``` +POST /upload +Content-Type: multipart/form-data + +file: <二进制图片文件> +``` + +### 限制 + +| 项 | 值 | +|---|---| +| 最大体积 | 8MB(智谱 `image_url` 上限5MB,留余量) | +| 白名单 content-type | `image/png`、`image/jpeg`、`image/jpg` | +| 存储位置 | 容器内 `/tmp/video-gen-uploads/`(`UPLOAD_DIR` 可覆盖) | +| 持久化 | **不持久化**。容器重启即丢,请尽快消费 URL | +| 鉴权 | 无 | + +### 返回 + +```jsonc +{ + "url": "https://video-gen.ai.foresh.com/uploads/abc123.png", + "filename": "abc123.png", + "size": 12345, + "content_type": "image/png", + "original_name": "my-cat.png" +} +``` + +返回的 `url` 可直接作为 `generate_video.image_url` 使用。 + +### 反代路由 + +反代需要额外暴露两条路由到 `mcp-video-gen:3000`: + +- `POST /upload` → `/upload` +- `GET /uploads/*` → `/uploads/*` + +### curl 示例 + +```bash +curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload +# {"url":"https://video-gen.ai.foresh.com/uploads/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png", ...} + +# 然后把 url 喂给 MCP: +# tool: generate_video +# args: { image_url: "https://video-gen.ai.foresh.com/uploads/xxx.png", prompt: "..." } +``` + +--- + ## 工具:generate_video 提交一个视频生成任务,支持**文生视频**和**图生视频**。**至少**需要传 `prompt` 或 `image_url` 其中之一;两者都传也行(image-to-video 时 prompt 会被附加为运动/动作描述)。 @@ -156,14 +226,17 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 ## 推荐用法(AI 视角) ``` -1. AI 决定生成视频 → 调用 generate_video({ prompt, image_url?, size?, with_audio? }) -2. 拿到 task_id → 等待若干秒(建议 2~5 秒) -3. 调用 query_video({ task_id }) +1. 如果手头是【本地文件】:先调 POST {PUBLIC_BASE_URL}/upload 拿到 url,再进第 2 步 +2. 调用 generate_video({ prompt, image_url?, size?, with_audio? }) +3. 拿到 task_id → 等待若干秒(建议 2~5 秒) +4. 调用 query_video({ task_id }) - 若 PROCESSING → 等一会再调 - 若 SUCCESS → 拿到 video URL,贴给用户 / 下载 / 二次编辑 - 若 FAIL → 展示错误信息,结束 ``` +> `generate_video` 的 tool description 里已经嵌入了完整 curl 上传命令,AI 一看就知道怎么传本地图片。 + --- ## 用 curl 手工调试 @@ -247,6 +320,17 @@ curl -s -X POST http://localhost:3000/mcp \ 响应是 SSE 格式(`event: message` + `data: {...}`),用 `grep '^data:'` 抽 JSON 即可。 +### 单独调试 `/upload` + +```bash +# 上传图片,返回 url +curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload +# {"url":"https://video-gen.ai.foresh.com/uploads/xxx.png", ...} + +# 下载上传过的文件 +curl -o cat.png https://video-gen.ai.foresh.com/uploads/xxx.png +``` + --- ## 架构与文件 @@ -255,7 +339,7 @@ curl -s -X POST http://localhost:3000/mcp \ video-gen/ ├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server ├── .dockerignore # 排除 node_modules -├── package.json # @modelcontextprotocol/sdk + express(无新依赖) +package.json # @modelcontextprotocol/sdk + express + multer ├── README.md # 本文件 └── src/ └── mcp-server.js # 单文件实现:HTTP server + MCP transport + 双工具 @@ -270,6 +354,7 @@ video-gen/ - `model / quality / fps / duration / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 - **异步语义暴露给 AI**:服务端不做轮询,`generate_video` 只提交、`query_video` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI +- **上传接口与 MCP 走同一进程**:额外 `POST /upload` + `GET /uploads/*` 不走 MCP、不鉴权,靠内网隔离;`PUBLIC_BASE_URL` 环境变量控制返回 URL 的拼接 host,AI 看到的 tool description 启动时拼接进真实地址,避免 AI 自由发挥 ### 默认模型 @@ -303,4 +388,10 @@ A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。 **Q: 换模型需要重连 MCP session 吗?** -A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 \ No newline at end of file +A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 + +**Q: 上传的图片多久过期?** +A: 容器重启即丢(本服务不持久化)。请在上传后立刻把返回的 `url` 喂给 `generate_video.image_url`。URL 本身只有可访问性,不受单独 TTL 限制;但容器一旦重启,该文件物理消失,URL 变 404。 + +**Q: `PUBLIC_BASE_URL` 不设会怎样?** +A: fallback 到 `http://localhost:3000`,AI 拿到的 curl 是 `http://localhost:3000/upload`。外网访问不到。本机调试无所谓,生产请显式设置。 \ No newline at end of file diff --git a/mcp/video-gen/package.json b/mcp/video-gen/package.json index 07ca8af..b4ab05c 100644 --- a/mcp/video-gen/package.json +++ b/mcp/video-gen/package.json @@ -8,7 +8,8 @@ "start": "node src/mcp-server.js --http --port 3000 --host 0.0.0.0" }, "dependencies": { - "@modelcontextprotocol/sdk": "^1.0.4", - "express": "^4.21.0" - } + "@modelcontextprotocol/sdk": "^1.0.4", + "express": "^4.21.0", + "multer": "^1.4.5-lts.1" + } } \ No newline at end of file diff --git a/mcp/video-gen/src/mcp-server.js b/mcp/video-gen/src/mcp-server.js index 6c52cae..46ed7b1 100644 --- a/mcp/video-gen/src/mcp-server.js +++ b/mcp/video-gen/src/mcp-server.js @@ -1,5 +1,8 @@ #!/usr/bin/env node import express from "express"; +import multer from "multer"; +import path from "node:path"; +import fs from "node:fs"; import { randomUUID } from "node:crypto"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; @@ -20,6 +23,25 @@ const DEFAULT_FPS = 30; // 30 | 60 const DEFAULT_DURATION = 5; // 5 | 10 const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true +// ===== 上传文件相关 ===== +// 公开的 base URL:拼接进 tool description,告诉 AI 该往哪里 POST 上传 +// 优先级:环境变量 > 默认 http://localhost: +function resolvePublicBaseUrl({ port, host }) { + const env = (process.env.PUBLIC_BASE_URL || "").trim(); + if (env) return env.replace(/\/+$/, ""); + return `http://localhost:${port}`; +} + +// 上传文件存储目录:容器内临时目录,服务重启即丢(你明确要求) +const UPLOAD_DIR = process.env.UPLOAD_DIR || "/tmp/video-gen-uploads"; +const UPLOAD_PATH_PREFIX = "/uploads"; // 对外的 URL 路径前缀 +const UPLOAD_MAX_BYTES = 8 * 1024 * 1024; // 8MB(智谱 image_url 上限 5MB,留余量) +const UPLOAD_ALLOWED_MIME = new Set([ + "image/png", + "image/jpeg", + "image/jpg", +]); + function parseArgs(argv) { const args = { http: false, @@ -167,7 +189,7 @@ async function queryAsyncResult({ token, id }) { return data; // { id, request_id, model, task_status, video_result?, ... } } -function buildServer() { +function buildServer({ publicBaseUrl }) { const server = new McpServer( { name: "video-gen", @@ -180,12 +202,22 @@ function buildServer() { } ); + const uploadUrl = `${publicBaseUrl}/upload`; + // ---------- 工具 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).", + `Submit a video generation task (text-to-video or image-to-video). +Returns the task_id immediately; poll the result later with query_video. +Provide prompt and/or image_url (at least one is required). + +If you need to use a LOCAL image file as image_url, upload it FIRST with this exact command (replace the path): + + curl -F "file=@/path/to/your/image.png" ${uploadUrl} + +The response JSON has a "url" field — pass that URL directly as the image_url argument below. +Supported formats: png, jpeg, jpg. Max 5MB per image. +Uploaded files live in container temp storage and are discarded on restart — do not rely on long-term URLs.`, { prompt: z .string() @@ -197,7 +229,7 @@ function buildServer() { .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." + "Reference image source for image-to-video. String or Array of up to 2 URLs for first/last frame. Image <= 5MB, .png/.jpeg/.jpg." ), size: z .string() @@ -379,6 +411,61 @@ async function startHttp({ port, host }) { const app = express(); app.use(express.json({ limit: "2mb" })); + const publicBaseUrl = resolvePublicBaseUrl({ port, host }); + console.log(`[video-gen] PUBLIC_BASE_URL = ${publicBaseUrl}`); + + // ===== /upload:接收图片,返回 URL(不走 MCP)===== + // 磁盘存储:保证 UPLOAD_DIR 存在(容器内临时,重启即丢) + fs.mkdirSync(UPLOAD_DIR, { recursive: true }); + + const storage = multer.diskStorage({ + destination: (_req, _file, cb) => cb(null, UPLOAD_DIR), + filename: (_req, file, cb) => { + const ext = (path.extname(file.originalname) || ".bin").toLowerCase(); + cb(null, `${randomUUID()}${ext}`); + }, + }); + + const upload = multer({ + storage, + limits: { fileSize: UPLOAD_MAX_BYTES, files: 1 }, + fileFilter: (_req, file, cb) => { + if (UPLOAD_ALLOWED_MIME.has(file.mimetype)) return cb(null, true); + cb(new Error(`Unsupported content-type: ${file.mimetype}. Allowed: ${[...UPLOAD_ALLOWED_MIME].join(", ")}`)); + }, + }); + + app.post("/upload", (req, res) => { + upload.single("file")(req, res, (err) => { + if (err) { + const status = err.code === "LIMIT_FILE_SIZE" ? 413 : 400; + return res.status(status).json({ + error: err.message || "upload failed", + }); + } + if (!req.file) { + return res.status(400).json({ error: "Missing form field 'file'" }); + } + const url = `${publicBaseUrl}${UPLOAD_PATH_PREFIX}/${req.file.filename}`; + return res.json({ + url, + filename: req.file.filename, + size: req.file.size, + content_type: req.file.mimetype, + original_name: req.file.originalname, + }); + }); + }); + + // 静态下载:只要文件存在于 UPLOAD_DIR 就吐出去(不鉴权、不持久化) + app.use( + UPLOAD_PATH_PREFIX, + express.static(UPLOAD_DIR, { + fallthrough: false, + maxAge: 0, + }) + ); + // session -> { server, transport } 映射 const sessions = new Map(); @@ -410,7 +497,7 @@ async function startHttp({ port, host }) { } const newId = randomUUID(); - const server = buildServer(); + const server = buildServer({ publicBaseUrl }); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newId, onsessioninitialized: (id) => { @@ -452,7 +539,8 @@ async function startHttp({ port, host }) { } async function startStdio() { - const server = buildServer(); + // stdio 模式下上传接口不可用,用 placeholder 避免 description 里出现奇怪的占位 + const server = buildServer({ publicBaseUrl: "http://localhost:3000" }); const { StdioServerTransport } = await import( "@modelcontextprotocol/sdk/server/stdio.js" ); @@ -472,4 +560,4 @@ if (args.http) { console.error("[video-gen] failed to start stdio server:", e); process.exit(1); }); -} \ No newline at end of file +} From daaa01878d330c772a03e42ec5f0a44242b30068 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 21:34:24 +0800 Subject: [PATCH 14/41] video-gen: auto-expire uploaded files older than UPLOAD_TTL_HOURS Adds cleanupUploads(): on startup and every hour, deletes files in UPLOAD_DIR whose mtime is older than UPLOAD_TTL_HOURS (default 24). Uses fs.promises + parallel stat/unlink, unref() the interval so it never blocks process shutdown, ignore ENOENT races silently. Storage is multer diskStorage so memory never holds a full file body, but disk could grow without bound if uploads pile up unused. This bounds the disk footprint without requiring a manual cron, and keeps the 'temp upload' semantics: the URL is meant to be consumed within the same session anyway. README: document UPLOAD_TTL_HOURS / UPLOAD_DIR env vars, add design note for the cleanup loop. --- mcp/video-gen/README.md | 10 +++++ mcp/video-gen/src/mcp-server.js | 69 ++++++++++++++++++++++++++++++++- 2 files changed, 77 insertions(+), 2 deletions(-) diff --git a/mcp/video-gen/README.md b/mcp/video-gen/README.md index ac8bc86..bc4caba 100644 --- a/mcp/video-gen/README.md +++ b/mcp/video-gen/README.md @@ -81,6 +81,14 @@ environment: 未设置时 fallback 到 `http://localhost:3000`(本机调试)。 +可选环境变量: + +| 变量 | 默认 | 说明 | +|---|---|---| +| `PUBLIC_BASE_URL` | `http://localhost:3000` | 返回 `url` 字段里拼接的对外 base URL | +| `UPLOAD_DIR` | `/tmp/video-gen-uploads` | 磁盘存储目录(容器内临时) | +| `UPLOAD_TTL_HOURS` | `24` | 超过该小时数的文件会在启动时和每小时被自动删除 | + ### 接口 ``` @@ -98,6 +106,7 @@ file: <二进制图片文件> | 白名单 content-type | `image/png`、`image/jpeg`、`image/jpg` | | 存储位置 | 容器内 `/tmp/video-gen-uploads/`(`UPLOAD_DIR` 可覆盖) | | 持久化 | **不持久化**。容器重启即丢,请尽快消费 URL | +| 过期清理 | 启动时 + 每小时一次删除 `>UPLOAD_TTL_HOURS` 的文件,默认 24h | | 鉴权 | 无 | ### 返回 @@ -355,6 +364,7 @@ package.json # @modelcontextprotocol/sdk + express + multer - **异步语义暴露给 AI**:服务端不做轮询,`generate_video` 只提交、`query_video` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI - **上传接口与 MCP 走同一进程**:额外 `POST /upload` + `GET /uploads/*` 不走 MCP、不鉴权,靠内网隔离;`PUBLIC_BASE_URL` 环境变量控制返回 URL 的拼接 host,AI 看到的 tool description 启动时拼接进真实地址,避免 AI 自由发挥 +- **上传过期清理**:启动时 + 每小时一次删除 `mtime > UPLOAD_TTL_HOURS` 的文件,避免磁盘被不消费的上传堆满;清理 timer 用 `unref()` 不阻塞进程退出 ### 默认模型 diff --git a/mcp/video-gen/src/mcp-server.js b/mcp/video-gen/src/mcp-server.js index 46ed7b1..626d25a 100644 --- a/mcp/video-gen/src/mcp-server.js +++ b/mcp/video-gen/src/mcp-server.js @@ -42,6 +42,50 @@ const UPLOAD_ALLOWED_MIME = new Set([ "image/jpg", ]); +// 过期清理:UPLOAD_TTL_HOURS 小时之前的文件会被定时删除 +const UPLOAD_TTL_HOURS = (() => { + const n = parseInt(process.env.UPLOAD_TTL_HOURS || "24", 10); + return Number.isFinite(n) && n > 0 ? n : 24; +})(); +const UPLOAD_TTL_MS = UPLOAD_TTL_HOURS * 60 * 60 * 1000; +const UPLOAD_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 每小时一次 + +// 清理 UPLOAD_DIR 下 mtime 早于 TTL 的文件。返回 {kept, removed, errors} +async function cleanupUploads({ now = Date.now(), dir = UPLOAD_DIR } = {}) { + let entries; + try { + entries = await fs.promises.readdir(dir); + } catch (e) { + if (e && e.code === "ENOENT") return { kept: 0, removed: 0, errors: 0 }; + console.error(`[video-gen] cleanup: readdir failed: ${e.message}`); + return { kept: 0, removed: 0, errors: 1 }; + } + + let kept = 0; + let removed = 0; + let errors = 0; + await Promise.all( + entries.map(async (name) => { + const full = path.join(dir, name); + try { + const st = await fs.promises.stat(full); + if (!st.isFile()) return; + if (now - st.mtimeMs >= UPLOAD_TTL_MS) { + await fs.promises.unlink(full); + removed++; + } else { + kept++; + } + } catch (e) { + if (e && e.code === "ENOENT") return; + errors++; + console.error(`[video-gen] cleanup: ${name}: ${e.message}`); + } + }) + ); + return { kept, removed, errors }; +} + function parseArgs(argv) { const args = { http: false, @@ -415,8 +459,29 @@ async function startHttp({ port, host }) { console.log(`[video-gen] PUBLIC_BASE_URL = ${publicBaseUrl}`); // ===== /upload:接收图片,返回 URL(不走 MCP)===== - // 磁盘存储:保证 UPLOAD_DIR 存在(容器内临时,重启即丢) - fs.mkdirSync(UPLOAD_DIR, { recursive: true }); + // 磁盘存储:保证 UPLOAD_DIR 存在(容器内临时,重启即丢) + fs.mkdirSync(UPLOAD_DIR, { recursive: true }); + + // 过期清理:启动时跑一次,之后每小时一次 + cleanupUploads() + .then((r) => + console.log( + `[video-gen] startup cleanup: kept=${r.kept} removed=${r.removed} errors=${r.errors} ttl=${UPLOAD_TTL_HOURS}h` + ) + ) + .catch((e) => console.error(`[video-gen] startup cleanup failed: ${e.message}`)); + const cleanupTimer = setInterval(() => { + cleanupUploads() + .then((r) => { + if (r.removed > 0 || r.errors > 0) { + console.log( + `[video-gen] periodic cleanup: kept=${r.kept} removed=${r.removed} errors=${r.errors}` + ); + } + }) + .catch((e) => console.error(`[video-gen] periodic cleanup failed: ${e.message}`)); + }, UPLOAD_CLEANUP_INTERVAL_MS); + cleanupTimer.unref(); // 不阻止进程退出 const storage = multer.diskStorage({ destination: (_req, _file, cb) => cb(null, UPLOAD_DIR), From 88120d61c1b850193fbbd8807c8c68d12f3720fa Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 22:28:39 +0800 Subject: [PATCH 15/41] video-gen: drop duration param, restrict image_url to a single URL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The cogvideox-flash API does not accept a duration field — passing one gets rejected upstream. Remove DEFAULT_DURATION, the X-Video-Gen-Duration header parser, and the field forwarded to Zhipu, both in code and README. image_url was documented as accepting up to 2 URLs for first/last frame, but the upstream schema only accepts a single string. Tighten the zod schema to z.string().url().optional() and update README / FAQ to make the single-URL constraint explicit. --- mcp/video-gen/README.md | 9 +++--- mcp/video-gen/src/mcp-server.js | 52 +++++++++++++++------------------ 2 files changed, 28 insertions(+), 33 deletions(-) diff --git a/mcp/video-gen/README.md b/mcp/video-gen/README.md index bc4caba..47ae9f5 100644 --- a/mcp/video-gen/README.md +++ b/mcp/video-gen/README.md @@ -152,7 +152,7 @@ curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| | `prompt` | string | ❌ | 视频文本描述,最大 512 字符 | -| `image_url` | string | ❌ | 参考图 URL(也支持 base64)。最多两张,首张为首帧、第二张为尾帧。图片 ≤ 5MB,格式 png/jpeg/jpg | +| `image_url` | string (URL) | ❌ | 参考图 URL(**单张**,不支持数组 / 多张 / 首尾帧)。图片 ≤ 5MB,格式 png/jpeg/jpg。本地文件请走 `/upload` | | `size` | string | ❌ | 视频尺寸,例如 `1920x1080`、`1080x1920`、`1024x1024`、`1280x960` 等 | | `with_audio` | boolean | ❌ | 是否生成 AI 音效,默认 `false` | @@ -163,7 +163,6 @@ curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload | `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` → 默认。 @@ -360,7 +359,7 @@ package.json # @modelcontextprotocol/sdk + express + multer - **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 误传或被诱导调高价档 + - `model / quality / fps / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 - **异步语义暴露给 AI**:服务端不做轮询,`generate_video` 只提交、`query_video` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI - **上传接口与 MCP 走同一进程**:额外 `POST /upload` + `GET /uploads/*` 不走 MCP、不鉴权,靠内网隔离;`PUBLIC_BASE_URL` 环境变量控制返回 URL 的拼接 host,AI 看到的 tool description 启动时拼接进真实地址,避免 AI 自由发挥 @@ -385,8 +384,8 @@ A: AI 自己 sleep 几秒再调(建议 2~5 秒间隔)。这是设计取舍 **Q: 视频 URL 多久过期?** A: 智谱签发 URL 默认 24h 左右。需要在收到后及时转存到自己的 OSS/S3。 -**Q: 为什么 quality / fps / duration 不让 AI 直接传?** -A: 这些是技术档位,与成本/单价挂钩。让 AI 自主挑 `quality=quality + fps=60 + duration=10` 会爆账号预算。改成 header 由部署方注入更可控。 +**Q: 为什么 quality / fps 不让 AI 直接传?** +A: 这些是技术档位,与成本/单价挂钩。让 AI 自主挑 `quality=quality + fps=60` 会爆账号预算。改成 header 由部署方注入更可控。 **Q: 能否限制 `size` 白名单?** A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `generate_video` 的 `size` schema 即可。 diff --git a/mcp/video-gen/src/mcp-server.js b/mcp/video-gen/src/mcp-server.js index 626d25a..89b88fc 100644 --- a/mcp/video-gen/src/mcp-server.js +++ b/mcp/video-gen/src/mcp-server.js @@ -20,7 +20,6 @@ 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 // ===== 上传文件相关 ===== @@ -197,7 +196,6 @@ async function submitVideo({ quality, with_audio, fps, - duration, watermark_enabled, }) { // 平台要求 image_url 和 prompt 至少传一个 @@ -207,7 +205,6 @@ async function submitVideo({ with_audio: Boolean(with_audio), watermark_enabled: Boolean(watermark_enabled), fps, - duration, // 由服务端生成唯一 request_id,便于日志关联;不暴露给 AI request_id: randomUUID(), }; @@ -270,11 +267,12 @@ Uploaded files live in container temp storage and are discarded on restart — d "Video text description (max 512 chars). At least one of prompt / image_url is required." ), image_url: z - .string() - .optional() - .describe( - "Reference image source for image-to-video. String or Array of up to 2 URLs for first/last frame. Image <= 5MB, .png/.jpeg/.jpg." - ), + .string() + .url() + .optional() + .describe( + "Reference image URL for image-to-video. Single URL only. Image <= 5MB, .png/.jpeg/.jpg. Use the /upload endpoint to get a URL from a local file." + ), size: z .string() .optional() @@ -297,15 +295,14 @@ Uploaded files live in container temp storage and are discarded on restart — d } // 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 - ); + 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 watermark_enabled = pickHeaderBool( + headers, + "x-video-gen-watermark", + DEFAULT_WATERMARK_ENABLED + ); if (!args.prompt && !args.image_url) { return { @@ -321,17 +318,16 @@ Uploaded files live in container temp storage and are discarded on restart — d 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, - }); + token, + model, + prompt: args.prompt, + image_url: args.image_url, + size: args.size, + quality, + with_audio: args.with_audio ?? false, + fps, + watermark_enabled, + }); const summary = `Model: ${model}\n` + From dab3732b50337a3696581a8ee937d0ecb801aab5 Mon Sep 17 00:00:00 2001 From: kicer Date: Fri, 4 Sep 2026 22:31:25 +0800 Subject: [PATCH 16/41] fix tools name --- mcp/image-gen/src/mcp-server.js | 2 +- mcp/video-gen/src/mcp-server.js | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image-gen/src/mcp-server.js index aed9b96..ec88d3a 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image-gen/src/mcp-server.js @@ -111,7 +111,7 @@ function buildServer() { ); server.tool( - "generate_image", + "image-gen", "Generate an image from a prompt and return the image URL. Optionally specify size.", { prompt: z diff --git a/mcp/video-gen/src/mcp-server.js b/mcp/video-gen/src/mcp-server.js index 89b88fc..885ecd7 100644 --- a/mcp/video-gen/src/mcp-server.js +++ b/mcp/video-gen/src/mcp-server.js @@ -247,7 +247,7 @@ function buildServer({ publicBaseUrl }) { // ---------- 工具 1:generate_video ---------- server.tool( - "generate_video", + "video-gen", `Submit a video generation task (text-to-video or image-to-video). Returns the task_id immediately; poll the result later with query_video. Provide prompt and/or image_url (at least one is required). @@ -267,12 +267,12 @@ Uploaded files live in container temp storage and are discarded on restart — d "Video text description (max 512 chars). At least one of prompt / image_url is required." ), image_url: z - .string() - .url() - .optional() - .describe( - "Reference image URL for image-to-video. Single URL only. Image <= 5MB, .png/.jpeg/.jpg. Use the /upload endpoint to get a URL from a local file." - ), + .string() + .url() + .optional() + .describe( + "Reference image URL string for image-to-video. Image <= 5MB, .png/.jpeg/.jpg. Use the /upload endpoint to get a URL from a local file." + ), size: z .string() .optional() From 4264ed0e39316e054f03a4d1febd8dc4a56a6a5a Mon Sep 17 00:00:00 2001 From: kicer Date: Sat, 5 Sep 2026 19:22:29 +0800 Subject: [PATCH 17/41] video-gen: make prompt a required parameter in tool schema --- mcp/video-gen/README.md | 4 ++-- mcp/video-gen/src/mcp-server.js | 5 ++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/mcp/video-gen/README.md b/mcp/video-gen/README.md index 47ae9f5..9860172 100644 --- a/mcp/video-gen/README.md +++ b/mcp/video-gen/README.md @@ -145,13 +145,13 @@ curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload ## 工具:generate_video -提交一个视频生成任务,支持**文生视频**和**图生视频**。**至少**需要传 `prompt` 或 `image_url` 其中之一;两者都传也行(image-to-video 时 prompt 会被附加为运动/动作描述)。 +提交一个视频生成任务,支持**文生视频**和**图生视频**。`prompt` 为**必填**;图生视频另传 `image_url`(两者都传也行,此时 prompt 会附加为运动/动作描述)。 ### 参数(AI 可见) | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| -| `prompt` | string | ❌ | 视频文本描述,最大 512 字符 | +| `prompt` | string | ✅ | 视频文本描述,最大 512 字符 | | `image_url` | string (URL) | ❌ | 参考图 URL(**单张**,不支持数组 / 多张 / 首尾帧)。图片 ≤ 5MB,格式 png/jpeg/jpg。本地文件请走 `/upload` | | `size` | string | ❌ | 视频尺寸,例如 `1920x1080`、`1080x1920`、`1024x1024`、`1280x960` 等 | | `with_audio` | boolean | ❌ | 是否生成 AI 音效,默认 `false` | diff --git a/mcp/video-gen/src/mcp-server.js b/mcp/video-gen/src/mcp-server.js index 885ecd7..89a15c2 100644 --- a/mcp/video-gen/src/mcp-server.js +++ b/mcp/video-gen/src/mcp-server.js @@ -250,7 +250,7 @@ function buildServer({ publicBaseUrl }) { "video-gen", `Submit a video generation task (text-to-video or image-to-video). Returns the task_id immediately; poll the result later with query_video. -Provide prompt and/or image_url (at least one is required). +prompt is required. Add image_url for image-to-video. If you need to use a LOCAL image file as image_url, upload it FIRST with this exact command (replace the path): @@ -262,9 +262,8 @@ Uploaded files live in container temp storage and are discarded on restart — d { prompt: z .string() - .optional() .describe( - "Video text description (max 512 chars). At least one of prompt / image_url is required." + "Video text description (max 512 chars). Required; when combined with image_url it serves as the motion/action description." ), image_url: z .string() From 8612c87b24538b6e3f0bf8ffc5006518713e700c Mon Sep 17 00:00:00 2001 From: kicer Date: Sat, 5 Sep 2026 19:23:34 +0800 Subject: [PATCH 18/41] video-gen: fix query_video task_id description referencing wrong tool name --- mcp/video-gen/src/mcp-server.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mcp/video-gen/src/mcp-server.js b/mcp/video-gen/src/mcp-server.js index 89a15c2..571f490 100644 --- a/mcp/video-gen/src/mcp-server.js +++ b/mcp/video-gen/src/mcp-server.js @@ -245,7 +245,7 @@ function buildServer({ publicBaseUrl }) { const uploadUrl = `${publicBaseUrl}/upload`; - // ---------- 工具 1:generate_video ---------- + // ---------- 工具 1:video-gen ---------- server.tool( "video-gen", `Submit a video generation task (text-to-video or image-to-video). @@ -364,7 +364,7 @@ Uploaded files live in container temp storage and are discarded on restart — d task_id: z .string() .min(1) - .describe("The task id returned by generate_video."), + .describe("The task id returned by video-gen."), }, async (args, extra) => { const headers = extra?.requestInfo?.headers; From a673d53c08a970cbdaa66fcdac03e162647c05c2 Mon Sep 17 00:00:00 2001 From: kicer Date: Sat, 5 Sep 2026 19:24:23 +0800 Subject: [PATCH 19/41] web-search: declare numResults as integer with minimum 1 and default 8 --- mcp/web-search-free/mcp.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mcp/web-search-free/mcp.js b/mcp/web-search-free/mcp.js index e0e3092..93baf0a 100644 --- a/mcp/web-search-free/mcp.js +++ b/mcp/web-search-free/mcp.js @@ -21,7 +21,7 @@ const TOOLS = [ 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)' }, + numResults: { type: 'integer', minimum: 1, default: 8, description: 'Maximum number of results to return (default 8)' }, }, required: ['query'], }, From 273bd9b8b032867e79a27746178b7031f71d8e9c Mon Sep 17 00:00:00 2001 From: kicer Date: Sat, 5 Sep 2026 20:34:42 +0800 Subject: [PATCH 20/41] =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E6=96=87=E4=BB=B6?= =?UTF-8?q?=E5=A4=B9=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/docker-compose.yml | 18 ++++---- mcp/{image-gen => image_gen}/.dockerignore | 0 mcp/{image-gen => image_gen}/Dockerfile | 0 mcp/{image-gen => image_gen}/README.md | 22 +++++----- mcp/{image-gen => image_gen}/package.json | 2 +- .../src/mcp-server.js | 14 +++--- mcp/{video-gen => video_gen}/.dockerignore | 0 mcp/{video-gen => video_gen}/Dockerfile | 0 mcp/{video-gen => video_gen}/README.md | 44 +++++++++---------- mcp/{video-gen => video_gen}/package.json | 2 +- .../src/mcp-server.js | 34 +++++++------- .../Dockerfile | 0 mcp/{web-search-free => web_search}/README.md | 6 +-- mcp/{web-search-free => web_search}/core.js | 2 +- mcp/{web-search-free => web_search}/mcp.js | 2 +- .../package.json | 4 +- mcp/{web-search-free => web_search}/server.js | 4 +- 17 files changed, 77 insertions(+), 77 deletions(-) rename mcp/{image-gen => image_gen}/.dockerignore (100%) rename mcp/{image-gen => image_gen}/Dockerfile (100%) rename mcp/{image-gen => image_gen}/README.md (94%) rename mcp/{image-gen => image_gen}/package.json (92%) rename mcp/{image-gen => image_gen}/src/mcp-server.js (95%) rename mcp/{video-gen => video_gen}/.dockerignore (100%) rename mcp/{video-gen => video_gen}/Dockerfile (100%) rename mcp/{video-gen => video_gen}/README.md (89%) rename mcp/{video-gen => video_gen}/package.json (94%) rename mcp/{video-gen => video_gen}/src/mcp-server.js (94%) rename mcp/{web-search-free => web_search}/Dockerfile (100%) rename mcp/{web-search-free => web_search}/README.md (81%) rename mcp/{web-search-free => web_search}/core.js (99%) rename mcp/{web-search-free => web_search}/mcp.js (98%) rename mcp/{web-search-free => web_search}/package.json (85%) rename mcp/{web-search-free => web_search}/server.js (96%) diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index 24ef916..a2685e4 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -1,7 +1,7 @@ services: - mcp-web-search-free: - build: ./web-search-free - container_name: mcp-web-search-free + mcp_web_search: + build: ./web_search + container_name: mcp_web_search restart: unless-stopped expose: - "3000" @@ -12,9 +12,9 @@ services: networks: - my-app-network - mcp-image-gen: - build: ./image-gen - container_name: mcp-image-gen + mcp_image_gen: + build: ./image_gen + container_name: mcp_image_gen restart: unless-stopped expose: - "3000" @@ -25,9 +25,9 @@ services: networks: - my-app-network - mcp-video-gen: - build: ./video-gen - container_name: mcp-video-gen + mcp_video_gen: + build: ./video_gen + container_name: mcp_video_gen restart: unless-stopped expose: - "3000" diff --git a/mcp/image-gen/.dockerignore b/mcp/image_gen/.dockerignore similarity index 100% rename from mcp/image-gen/.dockerignore rename to mcp/image_gen/.dockerignore diff --git a/mcp/image-gen/Dockerfile b/mcp/image_gen/Dockerfile similarity index 100% rename from mcp/image-gen/Dockerfile rename to mcp/image_gen/Dockerfile diff --git a/mcp/image-gen/README.md b/mcp/image_gen/README.md similarity index 94% rename from mcp/image-gen/README.md rename to mcp/image_gen/README.md index 413b2ba..7c942a5 100644 --- a/mcp/image-gen/README.md +++ b/mcp/image_gen/README.md @@ -18,18 +18,18 @@ ```bash cd /root/workspace/tools/mcp -docker compose up -d --build mcp-image-gen +docker compose up -d --build mcp_image_gen ``` -服务容器名 `mcp-image-gen`,通过反代暴露为 `https://image-gen.ai.foresh.com/mcp`。 +服务容器名 `mcp_image_gen`,通过反代暴露为 `https://image-gen.ai.foresh.com/mcp`。 直接连容器调试: ```bash -docker exec -it mcp-image-gen sh +docker exec -it mcp_image_gen sh # 或本机 curl http://localhost:3000/health -# {"status":"ok","service":"image-gen","sessions":0} +# {"status":"ok","service":"image_gen","sessions":0} ``` ### MCP 客户端配置 @@ -41,7 +41,7 @@ curl http://localhost:3000/health // Cursor: ~/.cursor/mcp.json { "mcpServers": { - "image-gen": { + "image_gen": { "url": "https://image-gen.ai.foresh.com/mcp", "headers": { "Authorization": "Bearer " @@ -59,7 +59,7 @@ curl http://localhost:3000/health --- -## 工具:generate_image +## 工具:image_gen 调用智谱图片生成接口,返回图片 URL。 @@ -169,7 +169,7 @@ curl -s -X POST http://localhost:3000/mcp \ -H "Mcp-Session-Id: $SESSION" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' -# 4. 调 generate_image +# 4. 调 image_gen curl -s -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ @@ -180,7 +180,7 @@ curl -s -X POST http://localhost:3000/mcp \ "id": 3, "method": "tools/call", "params": { - "name": "generate_image", + "name": "image_gen", "arguments": { "prompt": "一只可爱的小猫咪,坐在阳光明媚的窗台上,背景是蓝天白云", "size": "1280x1280" @@ -196,7 +196,7 @@ curl -s -X POST http://localhost:3000/mcp \ ## 架构与文件 ``` -image-gen/ +image_gen/ ├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server ├── .dockerignore # 排除 node_modules ├── package.json # @modelcontextprotocol/sdk + express + zod @@ -219,7 +219,7 @@ image-gen/ const DEFAULT_MODEL = "CogView-3-Flash"; ``` -修改后 `docker compose up -d --build mcp-image-gen` 即可生效。 +修改后 `docker compose up -d --build mcp_image_gen` 即可生效。 --- @@ -244,4 +244,4 @@ A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize A: 智谱签发 URL 默认 24h 左右,详见响应里的 `Expires` 参数。需要长期使用请自行转存到 OSS/S3。 **Q: 能否限制 `size` 白名单?** -A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `generate_image` 的 `size` schema 即可。 +A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `image_gen` 的 `size` schema 即可。 diff --git a/mcp/image-gen/package.json b/mcp/image_gen/package.json similarity index 92% rename from mcp/image-gen/package.json rename to mcp/image_gen/package.json index e89f44b..1b68546 100644 --- a/mcp/image-gen/package.json +++ b/mcp/image_gen/package.json @@ -1,5 +1,5 @@ { - "name": "mcp-image-gen", + "name": "mcp_image_gen", "version": "1.0.0", "description": "MCP server for image generation via Zhipu BigModel CogView-3-Flash", "type": "module", diff --git a/mcp/image-gen/src/mcp-server.js b/mcp/image_gen/src/mcp-server.js similarity index 95% rename from mcp/image-gen/src/mcp-server.js rename to mcp/image_gen/src/mcp-server.js index ec88d3a..10a8c86 100644 --- a/mcp/image-gen/src/mcp-server.js +++ b/mcp/image_gen/src/mcp-server.js @@ -100,7 +100,7 @@ function extractUrls(data) { function buildServer() { const server = new McpServer( { - name: "image-gen", + name: "image_gen", version: "1.0.0", }, { @@ -111,7 +111,7 @@ function buildServer() { ); server.tool( - "image-gen", + "image_gen", "Generate an image from a prompt and return the image URL. Optionally specify size.", { prompt: z @@ -207,7 +207,7 @@ async function startHttp({ port, host }) { const sessions = new Map(); app.get("/health", (_req, res) => { - res.json({ status: "ok", service: "image-gen", sessions: sessions.size }); + res.json({ status: "ok", service: "image_gen", sessions: sessions.size }); }); async function handleSessionRequest(req, res) { @@ -270,7 +270,7 @@ async function startHttp({ port, host }) { app.listen(port, host, () => { console.log( - `[image-gen] MCP HTTP server listening on http://${host}:${port}/mcp` + `[image_gen] MCP HTTP server listening on http://${host}:${port}/mcp` ); }); } @@ -283,18 +283,18 @@ async function startStdio() { ); const transport = new StdioServerTransport(); await server.connect(transport); - console.error("[image-gen] MCP stdio server started"); + console.error("[image_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("[image-gen] failed to start http server:", e); + console.error("[image_gen] failed to start http server:", e); process.exit(1); }); } else { startStdio().catch((e) => { - console.error("[image-gen] failed to start stdio server:", e); + console.error("[image_gen] failed to start stdio server:", e); process.exit(1); }); } diff --git a/mcp/video-gen/.dockerignore b/mcp/video_gen/.dockerignore similarity index 100% rename from mcp/video-gen/.dockerignore rename to mcp/video_gen/.dockerignore diff --git a/mcp/video-gen/Dockerfile b/mcp/video_gen/Dockerfile similarity index 100% rename from mcp/video-gen/Dockerfile rename to mcp/video_gen/Dockerfile diff --git a/mcp/video-gen/README.md b/mcp/video_gen/README.md similarity index 89% rename from mcp/video-gen/README.md rename to mcp/video_gen/README.md index 9860172..c52a1d4 100644 --- a/mcp/video-gen/README.md +++ b/mcp/video_gen/README.md @@ -19,18 +19,18 @@ ```bash cd /root/workspace/tools/mcp -docker compose up -d --build mcp-video-gen +docker compose up -d --build mcp_video_gen ``` -服务容器名 `mcp-video-gen`,通过反代暴露为 `https://video-gen.ai.foresh.com/mcp`。 +服务容器名 `mcp_video_gen`,通过反代暴露为 `https://video-gen.ai.foresh.com/mcp`。 直接连容器调试: ```bash -docker exec -it mcp-video-gen sh +docker exec -it mcp_video_gen sh # 或本机 curl http://localhost:3000/health -# {"status":"ok","service":"video-gen","sessions":0} +# {"status":"ok","service":"video_gen","sessions":0} ``` ### MCP 客户端配置 @@ -42,7 +42,7 @@ curl http://localhost:3000/health // Cursor: ~/.cursor/mcp.json { "mcpServers": { - "video-gen": { + "video_gen": { "url": "https://video-gen.ai.foresh.com/mcp", "headers": { "Authorization": "Bearer " @@ -60,14 +60,14 @@ curl http://localhost:3000/health | 工具 | 作用 | 同步/异步 | |---|---|---| -| `generate_video` | 提交一个视频生成任务,立刻返回 `task_id` | 同步(仅提交) | +| `video_gen` | 提交一个视频生成任务,立刻返回 `task_id` | 同步(仅提交) | | `query_video` | 用 `task_id` 拉一次当前结果 | 同步(单次查询,不轮询) | --- ## 上传图片:POST /upload -供 AI 临时上传本地图片、拿到 URL 后喂给 `generate_video.image_url`。**不走 MCP、不走鉴权**,仅依赖内网隔离(`my-app-network`)+ 反代层控制访问。 +供 AI 临时上传本地图片、拿到 URL 后喂给 `video_gen.image_url`。**不走 MCP、不走鉴权**,仅依赖内网隔离(`my-app-network`)+ 反代层控制访问。 ### 配置 @@ -86,7 +86,7 @@ environment: | 变量 | 默认 | 说明 | |---|---|---| | `PUBLIC_BASE_URL` | `http://localhost:3000` | 返回 `url` 字段里拼接的对外 base URL | -| `UPLOAD_DIR` | `/tmp/video-gen-uploads` | 磁盘存储目录(容器内临时) | +| `UPLOAD_DIR` | `/tmp/video_gen_uploads` | 磁盘存储目录(容器内临时) | | `UPLOAD_TTL_HOURS` | `24` | 超过该小时数的文件会在启动时和每小时被自动删除 | ### 接口 @@ -104,7 +104,7 @@ file: <二进制图片文件> |---|---| | 最大体积 | 8MB(智谱 `image_url` 上限5MB,留余量) | | 白名单 content-type | `image/png`、`image/jpeg`、`image/jpg` | -| 存储位置 | 容器内 `/tmp/video-gen-uploads/`(`UPLOAD_DIR` 可覆盖) | +| 存储位置 | 容器内 `/tmp/video_gen_uploads/`(`UPLOAD_DIR` 可覆盖) | | 持久化 | **不持久化**。容器重启即丢,请尽快消费 URL | | 过期清理 | 启动时 + 每小时一次删除 `>UPLOAD_TTL_HOURS` 的文件,默认 24h | | 鉴权 | 无 | @@ -121,11 +121,11 @@ file: <二进制图片文件> } ``` -返回的 `url` 可直接作为 `generate_video.image_url` 使用。 +返回的 `url` 可直接作为 `video_gen.image_url` 使用。 ### 反代路由 -反代需要额外暴露两条路由到 `mcp-video-gen:3000`: +反代需要额外暴露两条路由到 `mcp_video_gen:3000`: - `POST /upload` → `/upload` - `GET /uploads/*` → `/uploads/*` @@ -137,13 +137,13 @@ curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload # {"url":"https://video-gen.ai.foresh.com/uploads/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png", ...} # 然后把 url 喂给 MCP: -# tool: generate_video +# tool: video_gen # args: { image_url: "https://video-gen.ai.foresh.com/uploads/xxx.png", prompt: "..." } ``` --- -## 工具:generate_video +## 工具:video_gen 提交一个视频生成任务,支持**文生视频**和**图生视频**。`prompt` 为**必填**;图生视频另传 `image_url`(两者都传也行,此时 prompt 会附加为运动/动作描述)。 @@ -191,7 +191,7 @@ curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| -| `task_id` | string | ✅ | `generate_video` 返回的 `id` | +| `task_id` | string | ✅ | `video_gen` 返回的 `id` | ### 返回 @@ -235,7 +235,7 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 ``` 1. 如果手头是【本地文件】:先调 POST {PUBLIC_BASE_URL}/upload 拿到 url,再进第 2 步 -2. 调用 generate_video({ prompt, image_url?, size?, with_audio? }) +2. 调用 video_gen({ prompt, image_url?, size?, with_audio? }) 3. 拿到 task_id → 等待若干秒(建议 2~5 秒) 4. 调用 query_video({ task_id }) - 若 PROCESSING → 等一会再调 @@ -243,7 +243,7 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 - 若 FAIL → 展示错误信息,结束 ``` -> `generate_video` 的 tool description 里已经嵌入了完整 curl 上传命令,AI 一看就知道怎么传本地图片。 +> `video_gen` 的 tool description 里已经嵌入了完整 curl 上传命令,AI 一看就知道怎么传本地图片。 --- @@ -300,7 +300,7 @@ curl -s -X POST http://localhost:3000/mcp \ "id": 3, "method": "tools/call", "params": { - "name": "generate_video", + "name": "video_gen", "arguments": { "prompt": "A cat is playing with a ball.", "size": "1920x1080", @@ -344,7 +344,7 @@ curl -o cat.png https://video-gen.ai.foresh.com/uploads/xxx.png ## 架构与文件 ``` -video-gen/ +video_gen/ ├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server ├── .dockerignore # 排除 node_modules package.json # @modelcontextprotocol/sdk + express + multer @@ -360,7 +360,7 @@ package.json # @modelcontextprotocol/sdk + express + multer - **AI 可见 vs AI 不可见**: - AI 只看到 `prompt / image_url / size / with_audio` - `model / quality / fps / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 -- **异步语义暴露给 AI**:服务端不做轮询,`generate_video` 只提交、`query_video` 只查一次。AI 自主决定节奏 +- **异步语义暴露给 AI**:服务端不做轮询,`video_gen` 只提交、`query_video` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI - **上传接口与 MCP 走同一进程**:额外 `POST /upload` + `GET /uploads/*` 不走 MCP、不鉴权,靠内网隔离;`PUBLIC_BASE_URL` 环境变量控制返回 URL 的拼接 host,AI 看到的 tool description 启动时拼接进真实地址,避免 AI 自由发挥 - **上传过期清理**:启动时 + 每小时一次删除 `mtime > UPLOAD_TTL_HOURS` 的文件,避免磁盘被不消费的上传堆满;清理 timer 用 `unref()` 不阻塞进程退出 @@ -372,7 +372,7 @@ package.json # @modelcontextprotocol/sdk + express + multer const DEFAULT_MODEL = "cogvideox-flash"; ``` -修改后 `docker compose up -d --build mcp-video-gen` 即可生效。 +修改后 `docker compose up -d --build mcp_video_gen` 即可生效。 --- @@ -388,7 +388,7 @@ A: 智谱签发 URL 默认 24h 左右。需要在收到后及时转存到自己 A: 这些是技术档位,与成本/单价挂钩。让 AI 自主挑 `quality=quality + fps=60` 会爆账号预算。改成 header 由部署方注入更可控。 **Q: 能否限制 `size` 白名单?** -A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `generate_video` 的 `size` schema 即可。 +A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `video_gen` 的 `size` schema 即可。 **Q: 报错 `Missing valid Mcp-Session-Id`?** A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize`。 @@ -400,7 +400,7 @@ A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。 A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 **Q: 上传的图片多久过期?** -A: 容器重启即丢(本服务不持久化)。请在上传后立刻把返回的 `url` 喂给 `generate_video.image_url`。URL 本身只有可访问性,不受单独 TTL 限制;但容器一旦重启,该文件物理消失,URL 变 404。 +A: 容器重启即丢(本服务不持久化)。请在上传后立刻把返回的 `url` 喂给 `video_gen.image_url`。URL 本身只有可访问性,不受单独 TTL 限制;但容器一旦重启,该文件物理消失,URL 变 404。 **Q: `PUBLIC_BASE_URL` 不设会怎样?** A: fallback 到 `http://localhost:3000`,AI 拿到的 curl 是 `http://localhost:3000/upload`。外网访问不到。本机调试无所谓,生产请显式设置。 \ No newline at end of file diff --git a/mcp/video-gen/package.json b/mcp/video_gen/package.json similarity index 94% rename from mcp/video-gen/package.json rename to mcp/video_gen/package.json index b4ab05c..34d606a 100644 --- a/mcp/video-gen/package.json +++ b/mcp/video_gen/package.json @@ -1,5 +1,5 @@ { - "name": "mcp-video-gen", + "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", diff --git a/mcp/video-gen/src/mcp-server.js b/mcp/video_gen/src/mcp-server.js similarity index 94% rename from mcp/video-gen/src/mcp-server.js rename to mcp/video_gen/src/mcp-server.js index 571f490..3c6df7d 100644 --- a/mcp/video-gen/src/mcp-server.js +++ b/mcp/video_gen/src/mcp-server.js @@ -32,7 +32,7 @@ function resolvePublicBaseUrl({ port, host }) { } // 上传文件存储目录:容器内临时目录,服务重启即丢(你明确要求) -const UPLOAD_DIR = process.env.UPLOAD_DIR || "/tmp/video-gen-uploads"; +const UPLOAD_DIR = process.env.UPLOAD_DIR || "/tmp/video_gen_uploads"; const UPLOAD_PATH_PREFIX = "/uploads"; // 对外的 URL 路径前缀 const UPLOAD_MAX_BYTES = 8 * 1024 * 1024; // 8MB(智谱 image_url 上限 5MB,留余量) const UPLOAD_ALLOWED_MIME = new Set([ @@ -56,7 +56,7 @@ async function cleanupUploads({ now = Date.now(), dir = UPLOAD_DIR } = {}) { entries = await fs.promises.readdir(dir); } catch (e) { if (e && e.code === "ENOENT") return { kept: 0, removed: 0, errors: 0 }; - console.error(`[video-gen] cleanup: readdir failed: ${e.message}`); + console.error(`[video_gen] cleanup: readdir failed: ${e.message}`); return { kept: 0, removed: 0, errors: 1 }; } @@ -78,7 +78,7 @@ async function cleanupUploads({ now = Date.now(), dir = UPLOAD_DIR } = {}) { } catch (e) { if (e && e.code === "ENOENT") return; errors++; - console.error(`[video-gen] cleanup: ${name}: ${e.message}`); + console.error(`[video_gen] cleanup: ${name}: ${e.message}`); } }) ); @@ -233,7 +233,7 @@ async function queryAsyncResult({ token, id }) { function buildServer({ publicBaseUrl }) { const server = new McpServer( { - name: "video-gen", + name: "video_gen", version: "1.0.0", }, { @@ -245,9 +245,9 @@ function buildServer({ publicBaseUrl }) { const uploadUrl = `${publicBaseUrl}/upload`; - // ---------- 工具 1:video-gen ---------- + // ---------- 工具 1:video_gen ---------- server.tool( - "video-gen", + "video_gen", `Submit a video generation task (text-to-video or image-to-video). Returns the task_id immediately; poll the result later with query_video. prompt is required. Add image_url for image-to-video. @@ -364,7 +364,7 @@ Uploaded files live in container temp storage and are discarded on restart — d task_id: z .string() .min(1) - .describe("The task id returned by video-gen."), + .describe("The task id returned by video_gen."), }, async (args, extra) => { const headers = extra?.requestInfo?.headers; @@ -451,7 +451,7 @@ async function startHttp({ port, host }) { app.use(express.json({ limit: "2mb" })); const publicBaseUrl = resolvePublicBaseUrl({ port, host }); - console.log(`[video-gen] PUBLIC_BASE_URL = ${publicBaseUrl}`); + console.log(`[video_gen] PUBLIC_BASE_URL = ${publicBaseUrl}`); // ===== /upload:接收图片,返回 URL(不走 MCP)===== // 磁盘存储:保证 UPLOAD_DIR 存在(容器内临时,重启即丢) @@ -461,20 +461,20 @@ async function startHttp({ port, host }) { cleanupUploads() .then((r) => console.log( - `[video-gen] startup cleanup: kept=${r.kept} removed=${r.removed} errors=${r.errors} ttl=${UPLOAD_TTL_HOURS}h` + `[video_gen] startup cleanup: kept=${r.kept} removed=${r.removed} errors=${r.errors} ttl=${UPLOAD_TTL_HOURS}h` ) ) - .catch((e) => console.error(`[video-gen] startup cleanup failed: ${e.message}`)); + .catch((e) => console.error(`[video_gen] startup cleanup failed: ${e.message}`)); const cleanupTimer = setInterval(() => { cleanupUploads() .then((r) => { if (r.removed > 0 || r.errors > 0) { console.log( - `[video-gen] periodic cleanup: kept=${r.kept} removed=${r.removed} errors=${r.errors}` + `[video_gen] periodic cleanup: kept=${r.kept} removed=${r.removed} errors=${r.errors}` ); } }) - .catch((e) => console.error(`[video-gen] periodic cleanup failed: ${e.message}`)); + .catch((e) => console.error(`[video_gen] periodic cleanup failed: ${e.message}`)); }, UPLOAD_CLEANUP_INTERVAL_MS); cleanupTimer.unref(); // 不阻止进程退出 @@ -530,7 +530,7 @@ async function startHttp({ port, host }) { const sessions = new Map(); app.get("/health", (_req, res) => { - res.json({ status: "ok", service: "video-gen", sessions: sessions.size }); + res.json({ status: "ok", service: "video_gen", sessions: sessions.size }); }); async function handleSessionRequest(req, res) { @@ -593,7 +593,7 @@ async function startHttp({ port, host }) { app.listen(port, host, () => { console.log( - `[video-gen] MCP HTTP server listening on http://${host}:${port}/mcp` + `[video_gen] MCP HTTP server listening on http://${host}:${port}/mcp` ); }); } @@ -606,18 +606,18 @@ async function startStdio() { ); const transport = new StdioServerTransport(); await server.connect(transport); - console.error("[video-gen] MCP stdio server started"); + 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); + 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); + console.error("[video_gen] failed to start stdio server:", e); process.exit(1); }); } diff --git a/mcp/web-search-free/Dockerfile b/mcp/web_search/Dockerfile similarity index 100% rename from mcp/web-search-free/Dockerfile rename to mcp/web_search/Dockerfile diff --git a/mcp/web-search-free/README.md b/mcp/web_search/README.md similarity index 81% rename from mcp/web-search-free/README.md rename to mcp/web_search/README.md index 2525910..01cf528 100644 --- a/mcp/web-search-free/README.md +++ b/mcp/web_search/README.md @@ -1,4 +1,4 @@ -# web-search-free +# web_search 免费网页搜索 MCP server 的本地重构版(上游开源实现:[@sheep233_/dsh-web-search-free](https://github.com/sheep-programmer/dsh-web-search-free),MIT)。 @@ -35,8 +35,8 @@ MCP 端点: ## Docker -`docker-compose.yml` 中的 `mcp-web-search-free` 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 `npm install -g`)。 +`docker-compose.yml` 中的 `mcp_web_search` 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 `npm install -g`)。 ```bash -docker compose build mcp-web-search-free && docker compose up -d mcp-web-search-free +docker compose build mcp_web_search && docker compose up -d mcp_web_search ``` diff --git a/mcp/web-search-free/core.js b/mcp/web_search/core.js similarity index 99% rename from mcp/web-search-free/core.js rename to mcp/web_search/core.js index 81301c3..91774c6 100644 --- a/mcp/web-search-free/core.js +++ b/mcp/web_search/core.js @@ -13,7 +13,7 @@ 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'; +const USER_AGENT = 'web_search/1.0.0'; /** 单次上游搜索请求的超时,避免远端挂起拖死 MCP 请求。 */ const REQUEST_TIMEOUT_MS = Number(process.env.SEARCH_TIMEOUT_MS ?? 30_000); diff --git a/mcp/web-search-free/mcp.js b/mcp/web_search/mcp.js similarity index 98% rename from mcp/web-search-free/mcp.js rename to mcp/web_search/mcp.js index 93baf0a..274d0ae 100644 --- a/mcp/web-search-free/mcp.js +++ b/mcp/web_search/mcp.js @@ -7,7 +7,7 @@ */ import { parallelSearch, exaSearch } from './core.js'; -export const SERVER_NAME = 'dsh-web-search-free'; +export const SERVER_NAME = 'web_search'; export const VERSION = '1.0.0'; const DEFAULT_PROTOCOL = '2025-03-26'; diff --git a/mcp/web-search-free/package.json b/mcp/web_search/package.json similarity index 85% rename from mcp/web-search-free/package.json rename to mcp/web_search/package.json index 4c42281..956422f 100644 --- a/mcp/web-search-free/package.json +++ b/mcp/web_search/package.json @@ -1,5 +1,5 @@ { - "name": "web-search-free", + "name": "web_search", "version": "1.0.0", "private": true, "description": "Free web search tool. Uses Parallel by default or Exa as fallback.", @@ -7,7 +7,7 @@ "type": "module", "main": "server.js", "bin": { - "web-search-mcp": "server.js" + "web_search": "server.js" }, "engines": { "node": ">=18" diff --git a/mcp/web-search-free/server.js b/mcp/web_search/server.js similarity index 96% rename from mcp/web-search-free/server.js rename to mcp/web_search/server.js index 970c4a8..5d3b0d7 100644 --- a/mcp/web-search-free/server.js +++ b/mcp/web_search/server.js @@ -6,7 +6,7 @@ * * ## 双传输 * - **stdio**(默认):`node server.js` - * - `claude mcp add web-search -- 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` 返回服务信息,可做健康检查 @@ -108,7 +108,7 @@ function runHttp(host, port) { }); server.listen(port, host, () => { - process.stdout.write(`[web-search-mcp] HTTP/SSE listening on http://${host}:${port} (MCP: POST /, GET /sse + POST /messages)\n`); + process.stdout.write(`[web_search] HTTP/SSE listening on http://${host}:${port} (MCP: POST /, GET /sse + POST /messages)\n`); }); } From cd6d31c24c767be1cb8062eeb49fbd1c7e0af38d Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 15 Sep 2026 17:31:50 +0800 Subject: [PATCH 21/41] fix issues --- mcp/video_gen/src/mcp-server.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mcp/video_gen/src/mcp-server.js b/mcp/video_gen/src/mcp-server.js index 3c6df7d..b3c6145 100644 --- a/mcp/video_gen/src/mcp-server.js +++ b/mcp/video_gen/src/mcp-server.js @@ -250,7 +250,7 @@ function buildServer({ publicBaseUrl }) { "video_gen", `Submit a video generation task (text-to-video or image-to-video). Returns the task_id immediately; poll the result later with query_video. -prompt is required. Add image_url for image-to-video. +prompt is required. Must add image_url for image-to-video. If you need to use a LOCAL image file as image_url, upload it FIRST with this exact command (replace the path): From ae13be047c24a6d6549f653d6244c4f02edd586e Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 15 Sep 2026 17:54:46 +0800 Subject: [PATCH 22/41] =?UTF-8?q?=E9=83=A8=E7=BD=B2=EF=BC=9A=E6=94=B9?= =?UTF-8?q?=E4=B8=BA=20IP:=E7=AB=AF=E5=8F=A3=E7=9B=B4=E8=BF=9E=EF=BC=88?= =?UTF-8?q?=E6=97=A0=20nginx-proxy=EF=BC=89=EF=BC=8C=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docker-compose: expose 3000 → ports(WEB_SEARCH_PORT/IMAGE_GEN_PORT/VIDEO_GEN_PORT 可覆盖,默认 8081/8082/8083),去掉 VIRTUAL_HOST/VIRTUAL_PORT/CERT_NAME - video_gen: PUBLIC_BASE_URL 改为环境变量(默认 http://localhost:8083) - 新增根 README:部署步骤、端口变量、端口暴露范围(8083 需对外,8081/8082 建议只内网) - image_gen / video_gen / web_search README: 域名 URL 全部改为 IP:端口 --- mcp/README.md | 55 +++++++++++++++++++++++++++++++++++++++ mcp/docker-compose.yml | 44 ++++++++++++++----------------- mcp/image_gen/README.md | 16 ++++++------ mcp/video_gen/README.md | 56 +++++++++++++++++++++------------------- mcp/web_search/README.md | 7 +++++ 5 files changed, 119 insertions(+), 59 deletions(-) create mode 100644 mcp/README.md diff --git a/mcp/README.md b/mcp/README.md new file mode 100644 index 0000000..153c6e3 --- /dev/null +++ b/mcp/README.md @@ -0,0 +1,55 @@ +# MCP 服务集合 + +三个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: + +| 目录 | 容器名 | 作用 | 宿主机端口(默认) | MCP 端点 | +|---|---|---|---|---| +| `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `8081` | `POST /` | +| `image_gen/` | `mcp_image_gen` | 智谱 CogView 图片生成 | `8082` | `POST /mcp` | +| `video_gen/` | `mcp_video_gen` | 智谱 CogVideo 视频生成(异步)+ 图片 `/upload` | `8083` | `POST /mcp` | + +## 部署(无 nginx-proxy,IP:端口直连) + +这些服务与 `agent` 仓库的 `agent-core` 共用外部网络 `my-app-network`(agent 按**容器名**访问, +如 `http://mcp_web_search:3000/`),所以该网络要先创建一次: + +```bash +docker network create my-app-network +``` + +`image_gen` / `video_gen` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 +(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥,直接起: + +```bash +cd /root/workspace/tools/mcp +docker compose up -d --build +``` + +可选环境变量(写在仓库顶层 `.env` 即可,不写就用默认值): + +| 变量 | 默认 | 说明 | +|---|---|---| +| `WEB_SEARCH_PORT` | `8081` | web_search 映射到宿主机的端口 | +| `IMAGE_GEN_PORT` | `8082` | image_gen 映射到宿主机的端口 | +| `VIDEO_GEN_PORT` | `8083` | video_gen 映射到宿主机的端口 | +| `PUBLIC_BASE_URL` | `http://localhost:8083` | video_gen `/upload` 返回的 URL 前缀,必须是**外部可达**地址(智谱要能取到这张图);无域名时填 `http://<服务器IP>:` | + +## 端口暴露范围(安全) + +agent 走 `my-app-network` 用容器名 + 容器内端口(3000)访问,**不依赖宿主机端口**。所以对外 +只建议放行 `8083`(原因见下),`8081` / `8082` 建议不对公网开放: + +- `web_search`:服务端无鉴权,暴露即被白嫖搜索额度。 +- `image_gen`:token 由调用方自带,暴露后可被拿来消耗你自己的智谱额度(若 token 泄露)。 +- `video_gen`:`PUBLIC_BASE_URL` 指向它,智谱服务器要能下载你上传的参考图,所以**做图生视频时 + 必须对外放行**。注意它的 `/upload` 与 `/uploads/*` 本身不鉴权(8MB / 24h 临时文件), + 不需要图生视频就别放行。 + +## 单独调试 + +```bash +docker compose up -d --build mcp_web_search +curl http://localhost:8081/health +``` + +各目录下的 `README.md` 有该服务的工具说明、header 覆盖项与 curl 调试脚本。 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index a2685e4..821f2e6 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -1,14 +1,12 @@ +# 无 nginx-proxy 部署:每个服务把容器 3000 映射到各自宿主机端口,用 http://<服务器IP>:<端口>/mcp 访问。 +# 端口可用 .env / 环境变量覆盖(WEB_SEARCH_PORT / IMAGE_GEN_PORT / VIDEO_GEN_PORT)。 services: mcp_web_search: build: ./web_search container_name: mcp_web_search restart: unless-stopped - expose: - - "3000" - environment: - - VIRTUAL_HOST=web-search.ai.foresh.com - - VIRTUAL_PORT=3000 - - CERT_NAME=default + ports: + - "${WEB_SEARCH_PORT:-8081}:3000" networks: - my-app-network @@ -16,29 +14,27 @@ services: build: ./image_gen container_name: mcp_image_gen restart: unless-stopped - expose: - - "3000" - environment: - - VIRTUAL_HOST=image-gen.ai.foresh.com - - VIRTUAL_PORT=3000 - - CERT_NAME=default + ports: + - "${IMAGE_GEN_PORT:-8082}:3000" 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 - - PUBLIC_BASE_URL=https://video-gen.ai.foresh.com - networks: - - my-app-network + build: ./video_gen + container_name: mcp_video_gen + restart: unless-stopped + ports: + - "${VIDEO_GEN_PORT:-8083}:3000" + environment: + # /upload 返回给浏览器/AI 的 URL 前缀,必须是【外部可达】地址: + # 无域名时填 http://<服务器IP>:,否则智谱取不到图,图生视频会失败。 + # 不设则退化为 http://localhost:8083(只在本机 curl 调试时可用)。 + - PUBLIC_BASE_URL=${PUBLIC_BASE_URL:-http://localhost:8083} + networks: + - my-app-network networks: + # 与 agent 仓库共用:agent-core 按容器名访问这些服务(如 http://mcp_web_search:3000/)。 + # 只需创建一次:docker network create my-app-network my-app-network: external: true diff --git a/mcp/image_gen/README.md b/mcp/image_gen/README.md index 7c942a5..b7627f4 100644 --- a/mcp/image_gen/README.md +++ b/mcp/image_gen/README.md @@ -21,14 +21,14 @@ cd /root/workspace/tools/mcp docker compose up -d --build mcp_image_gen ``` -服务容器名 `mcp_image_gen`,通过反代暴露为 `https://image-gen.ai.foresh.com/mcp`。 +服务容器名 `mcp_image_gen`,容器内端口 3000,默认映射到宿主机 8082,即 `http://<服务器IP>:8082/mcp`。 直接连容器调试: ```bash docker exec -it mcp_image_gen sh -# 或本机 -curl http://localhost:3000/health +# 或本机(宿主机映射端口) +curl http://localhost:8082/health # {"status":"ok","service":"image_gen","sessions":0} ``` @@ -42,7 +42,7 @@ curl http://localhost:3000/health { "mcpServers": { "image_gen": { - "url": "https://image-gen.ai.foresh.com/mcp", + "url": "http://<服务器IP>:8082/mcp", "headers": { "Authorization": "Bearer " } @@ -136,7 +136,7 @@ MCP Streamable HTTP 不是普通 REST,**必须按顺序**:`initialize` → ` TOKEN="" # 1. initialize 拿 sessionId -SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ +SESSION=$(curl -s -D - -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -154,7 +154,7 @@ SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ echo "Session: $SESSION" # 2. notifications/initialized -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -162,7 +162,7 @@ curl -s -X POST http://localhost:3000/mcp \ -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}' # 3. 列出工具(可选验证) -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -170,7 +170,7 @@ curl -s -X POST http://localhost:3000/mcp \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' # 4. 调 image_gen -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ diff --git a/mcp/video_gen/README.md b/mcp/video_gen/README.md index c52a1d4..34cea7e 100644 --- a/mcp/video_gen/README.md +++ b/mcp/video_gen/README.md @@ -22,14 +22,14 @@ cd /root/workspace/tools/mcp docker compose up -d --build mcp_video_gen ``` -服务容器名 `mcp_video_gen`,通过反代暴露为 `https://video-gen.ai.foresh.com/mcp`。 +服务容器名 `mcp_video_gen`,容器内端口 3000,默认映射到宿主机 8083,即 `http://<服务器IP>:8083/mcp`。 直接连容器调试: ```bash docker exec -it mcp_video_gen sh -# 或本机 -curl http://localhost:3000/health +# 或本机(宿主机映射端口) +curl http://localhost:8083/health # {"status":"ok","service":"video_gen","sessions":0} ``` @@ -43,7 +43,7 @@ curl http://localhost:3000/health { "mcpServers": { "video_gen": { - "url": "https://video-gen.ai.foresh.com/mcp", + "url": "http://<服务器IP>:8083/mcp", "headers": { "Authorization": "Bearer " } @@ -67,25 +67,26 @@ curl http://localhost:3000/health ## 上传图片:POST /upload -供 AI 临时上传本地图片、拿到 URL 后喂给 `video_gen.image_url`。**不走 MCP、不走鉴权**,仅依赖内网隔离(`my-app-network`)+ 反代层控制访问。 +供 AI 临时上传本地图片、拿到 URL 后喂给 `video_gen.image_url`。**不走 MCP、不走鉴权**:以前靠反代控制访问,现在端口直连,只能靠宿主机防火墙/安全组控制(做图生视频时 `PUBLIC_BASE_URL` 指向该端口,智谱服务器得能取到图)。不需要图生视频就别对公网放行该端口。 ### 配置 通过环境变量告诉服务端「对外公开的 base URL」,用于拼接返回的 `url` 字段: ```yaml -# docker-compose.yml +# docker-compose.yml(无域名部署:填服务器 IP + 宿主机映射端口) environment: - - PUBLIC_BASE_URL=https://video-gen.ai.foresh.com + - PUBLIC_BASE_URL=http://<服务器IP>:8083 ``` -未设置时 fallback 到 `http://localhost:3000`(本机调试)。 +必须填**外部可达**地址:这个 URL 会交给智谱服务器去下载,填 `localhost` 或内网地址都会拉不到图。 +compose 未提供时的默认值是 `http://localhost:8083`(只适合本机 curl 调试);代码本身的 fallback 是 `http://localhost:3000`。 可选环境变量: | 变量 | 默认 | 说明 | |---|---|---| -| `PUBLIC_BASE_URL` | `http://localhost:3000` | 返回 `url` 字段里拼接的对外 base URL | +| `PUBLIC_BASE_URL` | `http://localhost:8083`(compose 提供;代码 fallback `http://localhost:3000`) | 返回 `url` 字段里拼接的对外 base URL | | `UPLOAD_DIR` | `/tmp/video_gen_uploads` | 磁盘存储目录(容器内临时) | | `UPLOAD_TTL_HOURS` | `24` | 超过该小时数的文件会在启动时和每小时被自动删除 | @@ -113,7 +114,7 @@ file: <二进制图片文件> ```jsonc { - "url": "https://video-gen.ai.foresh.com/uploads/abc123.png", + "url": "http://<服务器IP>:8083/uploads/abc123.png", "filename": "abc123.png", "size": 12345, "content_type": "image/png", @@ -123,22 +124,23 @@ file: <二进制图片文件> 返回的 `url` 可直接作为 `video_gen.image_url` 使用。 -### 反代路由 +### 端口与路由 -反代需要额外暴露两条路由到 `mcp_video_gen:3000`: +`/upload` 与 `/uploads/*` 由 `mcp_video_gen` 同一进程提供,不需要单独配路由;compose 已把 +容器 3000 映射到宿主机 `VIDEO_GEN_PORT`(默认 8083),两条路径直接可用: -- `POST /upload` → `/upload` -- `GET /uploads/*` → `/uploads/*` +- `POST /upload` +- `GET /uploads/*` ### curl 示例 ```bash -curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload -# {"url":"https://video-gen.ai.foresh.com/uploads/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png", ...} +curl -F "file=@/tmp/cat.png" http://<服务器IP>:8083/upload +# {"url":"http://<服务器IP>:8083/uploads/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png", ...} # 然后把 url 喂给 MCP: # tool: video_gen -# args: { image_url: "https://video-gen.ai.foresh.com/uploads/xxx.png", prompt: "..." } +# args: { image_url: "http://<服务器IP>:8083/uploads/xxx.png", prompt: "..." } ``` --- @@ -256,7 +258,7 @@ MCP Streamable HTTP 不是普通 REST,**必须按顺序**:`initialize` → ` TOKEN="" # 1. initialize 拿 sessionId -SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ +SESSION=$(curl -s -D - -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -274,7 +276,7 @@ SESSION=$(curl -s -D - -X POST http://localhost:3000/mcp \ echo "Session: $SESSION" # 2. notifications/initialized -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -282,7 +284,7 @@ curl -s -X POST http://localhost:3000/mcp \ -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}' # 3. 列出工具(可选验证) -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -290,7 +292,7 @@ curl -s -X POST http://localhost:3000/mcp \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' # 4. 提交文生视频任务 -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -310,7 +312,7 @@ curl -s -X POST http://localhost:3000/mcp \ }' # 5. 查结果(替换下面的 ) -curl -s -X POST http://localhost:3000/mcp \ +curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ @@ -331,12 +333,12 @@ curl -s -X POST http://localhost:3000/mcp \ ### 单独调试 `/upload` ```bash -# 上传图片,返回 url -curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload -# {"url":"https://video-gen.ai.foresh.com/uploads/xxx.png", ...} +# 上传图片,返回 url(宿主机映射端口) +curl -F "file=@/tmp/cat.png" http://localhost:8083/upload +# {"url":"http://localhost:8083/uploads/xxx.png", ...} # 下载上传过的文件 -curl -o cat.png https://video-gen.ai.foresh.com/uploads/xxx.png +curl -o cat.png http://localhost:8083/uploads/xxx.png ``` --- @@ -403,4 +405,4 @@ A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 A: 容器重启即丢(本服务不持久化)。请在上传后立刻把返回的 `url` 喂给 `video_gen.image_url`。URL 本身只有可访问性,不受单独 TTL 限制;但容器一旦重启,该文件物理消失,URL 变 404。 **Q: `PUBLIC_BASE_URL` 不设会怎样?** -A: fallback 到 `http://localhost:3000`,AI 拿到的 curl 是 `http://localhost:3000/upload`。外网访问不到。本机调试无所谓,生产请显式设置。 \ No newline at end of file +A: compose 会给个默认值 `http://localhost:8083`(代码 fallback 是 `http://localhost:3000`),本机 curl 调试没问题,但智谱服务器拉不到图——图生视频会失败。所以无域名部署时要显式设成 `http://<服务器IP>:<宿主机映射端口>`,并确保该端口对公网可达。 \ No newline at end of file diff --git a/mcp/web_search/README.md b/mcp/web_search/README.md index 01cf528..62d00f0 100644 --- a/mcp/web_search/README.md +++ b/mcp/web_search/README.md @@ -37,6 +37,13 @@ MCP 端点: `docker-compose.yml` 中的 `mcp_web_search` 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 `npm install -g`)。 +容器内监听 3000,默认映射到宿主机 `8081`(可用 `WEB_SEARCH_PORT` 覆盖): + ```bash docker compose build mcp_web_search && docker compose up -d mcp_web_search +curl http://localhost:8081/health +# {"name":"web_search","version":"...","transport":"http/sse","port":3000} ``` + +agent 侧走 `my-app-network` 用容器名访问(`http://mcp_web_search:3000/`),不依赖宿主机端口; +该服务**无服务端鉴权**,暴露到公网会被白嫆(消耗上游免费额度),建议不对公网放行 8081。 From e633f9b7c3f2b15247c1129270e764902d2c8825 Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 15 Sep 2026 19:17:57 +0800 Subject: [PATCH 23/41] =?UTF-8?q?=E9=83=A8=E7=BD=B2=EF=BC=9A=E7=BD=91?= =?UTF-8?q?=E7=BB=9C=E6=94=B9=E7=94=B1=20agent=20=E4=BE=A7=E5=88=9B?= =?UTF-8?q?=E5=BB=BA=EF=BC=8C=E5=8E=BB=E6=8E=89=E6=89=8B=E5=8A=A8=20docker?= =?UTF-8?q?=20network=20create?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docker-compose: my-app-network 仍为 external,注释说明依赖 agent 先起 - README: 部署步骤改为「先起 agent(创建网络),再起 mcp」,并说明 mcp 单独先起会报错 --- mcp/README.md | 13 ++++++++++--- mcp/docker-compose.yml | 4 ++-- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/mcp/README.md b/mcp/README.md index 153c6e3..aa2e22d 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -10,13 +10,20 @@ ## 部署(无 nginx-proxy,IP:端口直连) -这些服务与 `agent` 仓库的 `agent-core` 共用外部网络 `my-app-network`(agent 按**容器名**访问, -如 `http://mcp_web_search:3000/`),所以该网络要先创建一次: +这些服务与 `agent` 仓库的 `agent-core` 共用网络 `my-app-network`(agent 按**容器名**访问, +如 `http://mcp_web_search:3000/`)。该网络由 **agent 的 compose 创建**,所以全新机器上必须先起一次 agent: ```bash -docker network create my-app-network +# 1) 先起 agent(它会创建 my-app-network;首次还要先备好 config.yml 与 .env) +cd /root/workspace/tools/agent && docker compose up -d --build + +# 2) 再起 mcp +cd /root/workspace/tools/mcp && docker compose up -d --build ``` +> mcp 单独在一个没有该网络的机器上先起会报错(`network my-app-network declared as external, but could not be found`),这是预期行为。 +> 拆的时候反着来(先 down mcp 再 down agent)。 + `image_gen` / `video_gen` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 (agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥,直接起: diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index 821f2e6..ebea8e9 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -34,7 +34,7 @@ services: - my-app-network networks: - # 与 agent 仓库共用:agent-core 按容器名访问这些服务(如 http://mcp_web_search:3000/)。 - # 只需创建一次:docker network create my-app-network + # 与 agent 仓库共用:网络由 agent 的 compose 创建并命名(所以要先起 agent), + # 这里声明为 external 直接加入。agent-core 按容器名访问这些服务,如 http://mcp_web_search:3000/。 my-app-network: external: true From 8f693d0753147e8ea867faeff6166682245d166e Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 15 Sep 2026 19:40:40 +0800 Subject: [PATCH 24/41] =?UTF-8?q?=E9=83=A8=E7=BD=B2=EF=BC=9Avideo=5Fgen=20?= =?UTF-8?q?=E5=8F=8C=E7=9B=91=E5=90=AC=EF=BC=88=E5=85=A8=E9=87=8F=203000?= =?UTF-8?q?=20=E5=86=85=E7=BD=91=20/=20=E5=8F=AA=E8=AF=BB=203001=20?= =?UTF-8?q?=E5=85=AC=E7=BD=91=E4=BE=9B=E4=B8=AD=E8=BD=AC=EF=BC=89=EF=BC=8C?= =?UTF-8?q?mcp=20=E9=BB=98=E8=AE=A4=E4=B8=8D=E5=8D=A0=E5=AE=BF=E4=B8=BB?= =?UTF-8?q?=E6=9C=BA=E7=AB=AF=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - video_gen: UPLOAD_BASE_URL(AI 上传,内网)与 PUBLIC_BASE_URL(智谱下载,公网)拆开配置; 新增 PUBLIC_PORT 公网只读监听,只挂 GET /uploads/*(无 /mcp、无 POST /upload) - video_gen: 上传目录落到宿主 ./uploads(重启不让已发出的 URL 失效),Dockerfile EXPOSE 3000 3001 - docker-compose: 三个服务默认都不映射宿主机端口(调试用的 ports 注释保留); video_gen 配 UPLOAD_BASE_URL/PUBLIC_BASE_URL/PUBLIC_PORT/UPLOAD_DIR + ./uploads 挂载 - .gitignore(新): node_modules/ 与 uploads/ - 文档: 根 README 说明「只开 agent 端口」与图片到智谱的完整链路;三个子 README 同步端口与调试方式 --- mcp/.gitignore | 5 ++ mcp/README.md | 75 ++++++++++++------- mcp/docker-compose.yml | 38 ++++++---- mcp/image_gen/README.md | 15 ++-- mcp/video_gen/Dockerfile | 6 +- mcp/video_gen/README.md | 125 ++++++++++++++++++++------------ mcp/video_gen/src/mcp-server.js | 80 ++++++++++++++++---- mcp/web_search/README.md | 10 ++- 8 files changed, 241 insertions(+), 113 deletions(-) create mode 100644 mcp/.gitignore diff --git a/mcp/.gitignore b/mcp/.gitignore new file mode 100644 index 0000000..3f3ba23 --- /dev/null +++ b/mcp/.gitignore @@ -0,0 +1,5 @@ +node_modules/ +# video_gen 的上传目录(compose bind 到宿主机,运行时产物,不进库) +uploads/ +# 编排变量(PUBLIC_BASE_URL 等),含部署相关的地址,不进库 +.env diff --git a/mcp/README.md b/mcp/README.md index aa2e22d..98fdc3d 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -2,16 +2,18 @@ 三个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: -| 目录 | 容器名 | 作用 | 宿主机端口(默认) | MCP 端点 | +| 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 | |---|---|---|---|---| -| `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `8081` | `POST /` | -| `image_gen/` | `mcp_image_gen` | 智谱 CogView 图片生成 | `8082` | `POST /mcp` | -| `video_gen/` | `mcp_video_gen` | 智谱 CogVideo 视频生成(异步)+ 图片 `/upload` | `8083` | `POST /mcp` | +| `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` | +| `image_gen/` | `mcp_image_gen` | 智谱 CogView 图片生成 | `3000` | `POST /mcp` | +| `video_gen/` | `mcp_video_gen` | 智谱 CogVideo 视频生成(异步)+ 图片上传 | `3000` 全量 / `3001` 只读 | `POST /mcp` | -## 部署(无 nginx-proxy,IP:端口直连) +**这些服务默认不占宿主机端口**——它们只挂在 `my-app-network` 上,由 `agent-core` / `agent-executor` +按容器名访问。所以整台服务器对外只需要开 agent-core 那一个端口(`AGENT_PORT`,默认 8090)。 -这些服务与 `agent` 仓库的 `agent-core` 共用网络 `my-app-network`(agent 按**容器名**访问, -如 `http://mcp_web_search:3000/`)。该网络由 **agent 的 compose 创建**,所以全新机器上必须先起一次 agent: +## 部署(无 nginx-proxy) + +网络 `my-app-network` 由 **agent 的 compose 创建**,所以全新机器上必须先起一次 agent: ```bash # 1) 先起 agent(它会创建 my-app-network;首次还要先备好 config.yml 与 .env) @@ -25,38 +27,59 @@ cd /root/workspace/tools/mcp && docker compose up -d --build > 拆的时候反着来(先 down mcp 再 down agent)。 `image_gen` / `video_gen` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 -(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥,直接起: +(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥。 -```bash -cd /root/workspace/tools/mcp -docker compose up -d --build -``` +### 环境变量 -可选环境变量(写在仓库顶层 `.env` 即可,不写就用默认值): +写在仓库顶层 `.env` 里即可(不写就用默认值): | 变量 | 默认 | 说明 | |---|---|---| -| `WEB_SEARCH_PORT` | `8081` | web_search 映射到宿主机的端口 | -| `IMAGE_GEN_PORT` | `8082` | image_gen 映射到宿主机的端口 | -| `VIDEO_GEN_PORT` | `8083` | video_gen 映射到宿主机的端口 | -| `PUBLIC_BASE_URL` | `http://localhost:8083` | video_gen `/upload` 返回的 URL 前缀,必须是**外部可达**地址(智谱要能取到这张图);无域名时填 `http://<服务器IP>:` | +| `PUBLIC_BASE_URL` | `http://localhost:8090/mcp-uploads` | **必须改**。video_gen `/upload` 返回给智谱的 URL 前缀,指向 agent-core 的只读中转;无域名时填 `http://<服务器IP>:/mcp-uploads` | +| `WEB_SEARCH_PORT` | `8081` | 只在临时打开 web_search 调试端口时用 | +| `IMAGE_GEN_PORT` | `8082` | 只在临时打开 image_gen 调试端口时用 | +| `VIDEO_GEN_PORT` | `8083` | 只在临时打开 video_gen 调试端口(只读监听)时用 | -## 端口暴露范围(安全) +## 图片是怎么到智谱手上的(video_gen 特有) -agent 走 `my-app-network` 用容器名 + 容器内端口(3000)访问,**不依赖宿主机端口**。所以对外 -只建议放行 `8083`(原因见下),`8081` / `8082` 建议不对公网开放: +只有 `video_gen` 需要一个"公网可达的地址",因为智谱服务器生成视频前要**自己来拉这张参考图**, +它不带 cookie、不带 `Authorization`。链路是: -- `web_search`:服务端无鉴权,暴露即被白嫖搜索额度。 -- `image_gen`:token 由调用方自带,暴露后可被拿来消耗你自己的智谱额度(若 token 泄露)。 -- `video_gen`:`PUBLIC_BASE_URL` 指向它,智谱服务器要能下载你上传的参考图,所以**做图生视频时 - 必须对外放行**。注意它的 `/upload` 与 `/uploads/*` 本身不鉴权(8MB / 24h 临时文件), - 不需要图生视频就别放行。 +``` +AI(agent-executor 内执行 curl) + │ POST /upload(走 docker 内网,不经过公网) + ▼ +mcp_video_gen:3000 ──存储──► ./uploads/.png + │ 返回 url = PUBLIC_BASE_URL + /uploads/ + ▼ +视频任务提交给智谱,image_url 就是上面那个 url + │ + ▼ +智谱 ──匿名 GET──► http://<服务器IP>:8090/mcp-uploads/uploads/ + │ agent-core 只转发 GET/HEAD + ▼ + mcp_video_gen:3001(只读监听,那边没有任何写路由) +``` + +所以:**写路径(`POST /upload`)永远不出公网**,公网只暴露一个只读、不可枚举、24h 过期的下载路径。 + +## 端口与安全 + +| 服务 | 公网暴露 | 说明 | +|---|---|---| +| `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | +| `mcp_image_gen` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | +| `mcp_video_gen` | 无 | 只读路径已经由 agent-core 的 `/mcp-uploads` 代拉,无需自己占端口 | + +需要从宿主机直接 curl 调试时,去 `docker-compose.yml` 把对应服务注释掉的 `ports` 两行打开 +(video_gen 那个映的是只读监听 3001,不会暴露 `POST /upload`),调试完记得再注释回去。 +`video_gen` 的用户上传文件落在宿主 `./uploads/`(已 gitignore,24h 自动清理)。 ## 单独调试 ```bash docker compose up -d --build mcp_web_search -curl http://localhost:8081/health +docker exec mcp_web_search node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" ``` 各目录下的 `README.md` 有该服务的工具说明、header 覆盖项与 curl 调试脚本。 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index ebea8e9..11d8178 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -1,12 +1,14 @@ -# 无 nginx-proxy 部署:每个服务把容器 3000 映射到各自宿主机端口,用 http://<服务器IP>:<端口>/mcp 访问。 -# 端口可用 .env / 环境变量覆盖(WEB_SEARCH_PORT / IMAGE_GEN_PORT / VIDEO_GEN_PORT)。 +# 无 nginx-proxy 部署:这些服务**默认不占宿主机端口**,只挂在 my-app-network 上被 agent 按容器名访问。 +# 因此对外只需要开 agent-core 那一个端口(AGENT_PORT,默认 8090)。 +# 需要从宿主机 curl 调试某个服务时,把它下面注释掉的 ports 两行打开。 services: mcp_web_search: build: ./web_search container_name: mcp_web_search restart: unless-stopped - ports: - - "${WEB_SEARCH_PORT:-8081}:3000" + # 调试用(默认关): + # ports: + # - "${WEB_SEARCH_PORT:-8081}:3000" networks: - my-app-network @@ -14,8 +16,9 @@ services: build: ./image_gen container_name: mcp_image_gen restart: unless-stopped - ports: - - "${IMAGE_GEN_PORT:-8082}:3000" + # 调试用(默认关): + # ports: + # - "${IMAGE_GEN_PORT:-8082}:3000" networks: - my-app-network @@ -23,18 +26,27 @@ services: build: ./video_gen container_name: mcp_video_gen restart: unless-stopped - ports: - - "${VIDEO_GEN_PORT:-8083}:3000" + # 调试用(默认关;这里映的是只读监听 3001,不会暴露 POST /upload): + # ports: + # - "${VIDEO_GEN_PORT:-8083}:3001" environment: - # /upload 返回给浏览器/AI 的 URL 前缀,必须是【外部可达】地址: - # 无域名时填 http://<服务器IP>:,否则智谱取不到图,图生视频会失败。 - # 不设则退化为 http://localhost:8083(只在本机 curl 调试时可用)。 - - PUBLIC_BASE_URL=${PUBLIC_BASE_URL:-http://localhost:8083} + # AI 往哪上传(拼进 video_gen 工具的 curl 模板):走 docker 内网即可,不需要公网。 + - UPLOAD_BASE_URL=http://mcp_video_gen:3000 + # 智谱从哪下载(拼进 /upload 返回的 url 字段):必须【公网可达】。 + # 无域名时填 http://<服务器IP>:/mcp-uploads(agent-core 的只读中转,默认端口 8090)。 + # 填错的现象:图传上去了,但智谱取不到图、图生视频失败;启动日志会打印实际生效的地址便于核对。 + - PUBLIC_BASE_URL=${PUBLIC_BASE_URL:-http://localhost:8090/mcp-uploads} + # 公网只读监听(容器内):agent 的 MCP_UPLOADS_URL 指向它;也只被上面那个调试端口映射。 + - PUBLIC_PORT=3001 + # 上传落宿主 ./uploads(重启不让已发出的 URL 失效),TTL 清理照旧 + - UPLOAD_DIR=/uploads + volumes: + - ./uploads:/uploads networks: - my-app-network networks: # 与 agent 仓库共用:网络由 agent 的 compose 创建并命名(所以要先起 agent), - # 这里声明为 external 直接加入。agent-core 按容器名访问这些服务,如 http://mcp_web_search:3000/。 + # 这里声明为 external 直接加入。agent-core / agent-executor 按容器名访问这些服务。 my-app-network: external: true diff --git a/mcp/image_gen/README.md b/mcp/image_gen/README.md index b7627f4..91184d9 100644 --- a/mcp/image_gen/README.md +++ b/mcp/image_gen/README.md @@ -21,14 +21,13 @@ cd /root/workspace/tools/mcp docker compose up -d --build mcp_image_gen ``` -服务容器名 `mcp_image_gen`,容器内端口 3000,默认映射到宿主机 8082,即 `http://<服务器IP>:8082/mcp`。 - -直接连容器调试: +服务容器名 `mcp_image_gen`,容器内端口 3000,**默认不占宿主端口**:agent 走 `my-app-network` +按容器名访问(`http://mcp_image_gen:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 +`docker-compose.yml` 把 `mcp_image_gen` 注释掉的 `ports` 两行打开(默认写的是 8082),调试完记得注释回去。 ```bash -docker exec -it mcp_image_gen sh -# 或本机(宿主机映射端口) -curl http://localhost:8082/health +# 不占端口的健康检查 +docker exec mcp_image_gen node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" # {"status":"ok","service":"image_gen","sessions":0} ``` @@ -42,7 +41,7 @@ curl http://localhost:8082/health { "mcpServers": { "image_gen": { - "url": "http://<服务器IP>:8082/mcp", + "url": "http://localhost:8082/mcp", "headers": { "Authorization": "Bearer " } @@ -51,6 +50,8 @@ curl http://localhost:8082/health } ``` +> 上面 `url` 里的端口 `8082` 需要先把 compose 里注释的 `ports` 打开(默认不占宿主端口)。 + > **重要**:客户端必须在 **每一个 HTTP 请求**(`initialize` / `notifications/initialized` / `tools/call`)都带上 `Authorization` header。配置在 `headers` 里、由客户端自动重发即可。直连模式下 token 不在 session 间共享。 #### 不支持 `headers` 字段的客户端 diff --git a/mcp/video_gen/Dockerfile b/mcp/video_gen/Dockerfile index f7ed783..889d13c 100644 --- a/mcp/video_gen/Dockerfile +++ b/mcp/video_gen/Dockerfile @@ -9,7 +9,9 @@ RUN npm install --omit=dev # 复制源码 COPY . . -EXPOSE 3000 +EXPOSE 3000 3001 -# 启用 HTTP/SSE 模式,监听 3000 端口 +# 启用 HTTP/SSE 模式: +# 3000 = MCP(/mcp) + POST /upload + GET /uploads/*,容器外不映射(只在 docker 网络内可达) +# 3001 = 公网只读的 GET /uploads/*,由 compose 映射到宿主机给智谱下载(PUBLIC_PORT 开启) 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 index 34cea7e..0f8d948 100644 --- a/mcp/video_gen/README.md +++ b/mcp/video_gen/README.md @@ -5,9 +5,9 @@ - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - 上游:[智谱 BigModel 视频生成(异步)](https://docs.bigmodel.cn/api-reference/模型-api/视频生成异步) + [查询异步结果](https://docs.bigmodel.cn/api-reference/模型-api/查询异步结果) - 默认模型:`cogvideox-flash` -- 端口:`3000` +- 端口:容器内 `3000`(`/mcp` + `POST /upload` + `GET /uploads/*`,**容器外不映射**)、容器内 `3001`(公网只读的 `GET /uploads/*`) - 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token -- 附带 `/upload` 端点:供 AI 临时上传本地图片获取 URL(**不持久化**,容器重启即丢) +- 附带 `/upload`:供 AI 上传本地图片换取 URL(写路径只在 docker 内网可达;落宿主 `./uploads/`,按 TTL 自动清理) --- @@ -22,17 +22,18 @@ cd /root/workspace/tools/mcp docker compose up -d --build mcp_video_gen ``` -服务容器名 `mcp_video_gen`,容器内端口 3000,默认映射到宿主机 8083,即 `http://<服务器IP>:8083/mcp`。 - -直接连容器调试: +服务容器名 `mcp_video_gen`,**默认不占宿主机端口**:由 agent 走 `my-app-network` 按容器名访问 +(`http://mcp_video_gen:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 `docker-compose.yml` +把 `mcp_video_gen` 注释掉的 `ports` 两行打开(映的是只读监听 3001)。 ```bash -docker exec -it mcp_video_gen sh -# 或本机(宿主机映射端口) -curl http://localhost:8083/health +# 容器内健康检查(无需占端口) +docker exec mcp_video_gen node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" # {"status":"ok","service":"video_gen","sessions":0} ``` +> 下文 curl 示例里的 `localhost:8083` 均指“临时打开了调试端口”的情形。 + ### MCP 客户端配置 #### Claude Desktop / Cursor 等支持 `headers` 配置的客户端 @@ -43,7 +44,7 @@ curl http://localhost:8083/health { "mcpServers": { "video_gen": { - "url": "http://<服务器IP>:8083/mcp", + "url": "http://localhost:8083/mcp", "headers": { "Authorization": "Bearer " } @@ -52,6 +53,8 @@ curl http://localhost:8083/health } ``` +> 上面 `url` 里的端口 `8083` 需要先把 compose 里注释的 `ports` 打开(默认不占宿主端口)。 + > **重要**:客户端必须在 **每一个 HTTP 请求**(`initialize` / `notifications/initialized` / `tools/call`)都带上 `Authorization` header。 --- @@ -67,33 +70,44 @@ curl http://localhost:8083/health ## 上传图片:POST /upload -供 AI 临时上传本地图片、拿到 URL 后喂给 `video_gen.image_url`。**不走 MCP、不走鉴权**:以前靠反代控制访问,现在端口直连,只能靠宿主机防火墙/安全组控制(做图生视频时 `PUBLIC_BASE_URL` 指向该端口,智谱服务器得能取到图)。不需要图生视频就别对公网放行该端口。 +供 AI 上传本地图片、拿到 URL 后喂给 `video_gen.image_url`。**不走 MCP、不走鉴权**,但**写路径只在内网**(容器内 3000,容器外不映射), +所以公网上没有任何写入入口。唯一公网可达的是**只读**的下载路径,而且由 agent-core 代拉: -### 配置 - -通过环境变量告诉服务端「对外公开的 base URL」,用于拼接返回的 `url` 字段: - -```yaml -# docker-compose.yml(无域名部署:填服务器 IP + 宿主机映射端口) -environment: - - PUBLIC_BASE_URL=http://<服务器IP>:8083 +``` +AI(agent-executor 内 curl) + │ POST http://mcp_video_gen:3000/upload ← docker 内网,不经公网 + ▼ + ./uploads/.png 返回 url = PUBLIC_BASE_URL + /uploads/ + │ + ▼ +智谱服务器 ──匿名 GET──► http://<服务器IP>:/mcp-uploads/uploads/ + │ agent-core 只转发 GET/HEAD + ▼ + mcp_video_gen:3001(只读监听,那边没有 /upload) ``` -必须填**外部可达**地址:这个 URL 会交给智谱服务器去下载,填 `localhost` 或内网地址都会拉不到图。 -compose 未提供时的默认值是 `http://localhost:8083`(只适合本机 curl 调试);代码本身的 fallback 是 `http://localhost:3000`。 +### 配置(两个地址刻意分开) -可选环境变量: +| 变量 | 作用 | 该填什么 | +|---|---|---| +| `UPLOAD_BASE_URL` | 拼进 tool description 里那条 curl,告诉 AI 往哪上传 | 内网地址 `http://mcp_video_gen:3000`(compose 已配好) | +| `PUBLIC_BASE_URL` | 拼进 `/upload` 返回的 `url` 字段,给**智谱**下载用 | **必须外部可达**:`http://<服务器IP>:/mcp-uploads` | +| `PUBLIC_PORT` | 只读监听的容器内端口(agent 的 `MCP_UPLOADS_URL` 指向它) | compose 里是 `3001`;留 `0` 则不开双监听 | + +`UPLOAD_BASE_URL` 未设时会退回 `PUBLIC_BASE_URL`,两个都没设则都是 `http://localhost:`(本机调试)。 +启动日志会打印两个实际生效的地址,配错了一看就知道。 + +其它环境变量: | 变量 | 默认 | 说明 | |---|---|---| -| `PUBLIC_BASE_URL` | `http://localhost:8083`(compose 提供;代码 fallback `http://localhost:3000`) | 返回 `url` 字段里拼接的对外 base URL | -| `UPLOAD_DIR` | `/tmp/video_gen_uploads` | 磁盘存储目录(容器内临时) | +| `UPLOAD_DIR` | `/tmp/video_gen_uploads` | 磁盘存储目录;compose 里指向宿主挂载的 `/uploads` | | `UPLOAD_TTL_HOURS` | `24` | 超过该小时数的文件会在启动时和每小时被自动删除 | ### 接口 ``` -POST /upload +POST /upload (只在容器内 3000,内网可达) Content-Type: multipart/form-data file: <二进制图片文件> @@ -105,16 +119,16 @@ file: <二进制图片文件> |---|---| | 最大体积 | 8MB(智谱 `image_url` 上限5MB,留余量) | | 白名单 content-type | `image/png`、`image/jpeg`、`image/jpg` | -| 存储位置 | 容器内 `/tmp/video_gen_uploads/`(`UPLOAD_DIR` 可覆盖) | -| 持久化 | **不持久化**。容器重启即丢,请尽快消费 URL | +| 存储位置 | 宿主 `./uploads/`(compose 挂到容器 `/uploads`,`UPLOAD_DIR` 可覆盖) | +| 持久化 | 落盘,重启不失效;但按 TTL 到期自动删,**不要依赖长期 URL** | | 过期清理 | 启动时 + 每小时一次删除 `>UPLOAD_TTL_HOURS` 的文件,默认 24h | -| 鉴权 | 无 | +| 鉴权 | 无(靠“不映射到宿主机”隔离;AI 走内网访问) | ### 返回 ```jsonc { - "url": "http://<服务器IP>:8083/uploads/abc123.png", + "url": "http://<服务器IP>:8090/mcp-uploads/uploads/abc123.png", "filename": "abc123.png", "size": 12345, "content_type": "image/png", @@ -122,25 +136,44 @@ file: <二进制图片文件> } ``` -返回的 `url` 可直接作为 `video_gen.image_url` 使用。 +返回的 `url` 可直接作为 `video_gen.image_url` 使用(前缀 = `PUBLIC_BASE_URL`)。 ### 端口与路由 -`/upload` 与 `/uploads/*` 由 `mcp_video_gen` 同一进程提供,不需要单独配路由;compose 已把 -容器 3000 映射到宿主机 `VIDEO_GEN_PORT`(默认 8083),两条路径直接可用: +| 容器内端口 | 路由 | 容器外 | +|---|---|---| +| `3000` | `/mcp` + `POST /upload` + `GET /uploads/*` | 不映射,只在 `my-app-network` 内可达 | +| `3001`(`PUBLIC_PORT`) | 只有 `GET /uploads/*` + `/health` | 也不映射;由 agent-core 的 `MCP_UPLOADS_URL` 指向它代拉 | -- `POST /upload` -- `GET /uploads/*` +只读监听的意义:公网那条入站链路(智谱拉图)接的是它,所以即使 agent 侧中转有 bug 把写方法转过来, +这边也没路由可打(纵深防御)。 ### curl 示例 -```bash -curl -F "file=@/tmp/cat.png" http://<服务器IP>:8083/upload -# {"url":"http://<服务器IP>:8083/uploads/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png", ...} +默认不占宿主端口。推荐用 `docker exec` 在容器内测(不破坏安全边界): -# 然后把 url 喂给 MCP: -# tool: video_gen -# args: { image_url: "http://<服务器IP>:8083/uploads/xxx.png", prompt: "..." } +```bash +# 上传(走全量监听的 3000):把 /etc/hostname 当假图片,只为看返回结构 +docker exec mcp_video_gen node -e " + const fs=require('fs'); + const fd=new FormData(); + fd.append('file',new File([fs.readFileSync('/etc/hostname')],'t.png',{type:'image/png'})); + fetch('http://localhost:3000/upload',{method:'POST',body:fd}).then(r=>r.json()).then(j=>console.log(j)); +" + +# 只读监听取文件(把 换成上一步返回的 filename) +docker exec mcp_video_gen node -e "fetch('http://localhost:3001/uploads/').then(r=>console.log(r.status,r.headers.get('content-type')))" + +# 只读监听上试写:应当 404(那边没有 /upload) +docker exec mcp_video_gen node -e "fetch('http://localhost:3001/upload',{method:'POST'}).then(r=>console.log(r.status))" +``` + +要从宿主机 curl 调试,临时把 compose 里注释的 `ports` 打开(打开的是只读侧 `8083:3001`; +想试上传就临时改成 `8083:3000`,测完记得改回来): + +```bash +curl -sI http://localhost:8083/uploads/ # 只读侧取图:200 +curl -s http://localhost:8083/upload # 只读侧写:404(本来就没这个路由) ``` --- @@ -236,7 +269,7 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 ## 推荐用法(AI 视角) ``` -1. 如果手头是【本地文件】:先调 POST {PUBLIC_BASE_URL}/upload 拿到 url,再进第 2 步 +1. 如果手头是【本地文件】:先调 POST {UPLOAD_BASE_URL}/upload 拿到 url,再进第 2 步 2. 调用 video_gen({ prompt, image_url?, size?, with_audio? }) 3. 拿到 task_id → 等待若干秒(建议 2~5 秒) 4. 调用 query_video({ task_id }) @@ -333,11 +366,11 @@ curl -s -X POST http://localhost:8083/mcp \ ### 单独调试 `/upload` ```bash -# 上传图片,返回 url(宿主机映射端口) +# 上传(需先在 compose 里临时把 ports 打开成 8083:3000;默认不映射) curl -F "file=@/tmp/cat.png" http://localhost:8083/upload -# {"url":"http://localhost:8083/uploads/xxx.png", ...} +# {"url":"http://<服务器IP>:8090/mcp-uploads/uploads/xxx.png", ...} ← 返回的是公网地址(PUBLIC_BASE_URL) -# 下载上传过的文件 +# 直接从只读监听取文件(compose 默认那行就是 8083:3001) curl -o cat.png http://localhost:8083/uploads/xxx.png ``` @@ -364,7 +397,7 @@ package.json # @modelcontextprotocol/sdk + express + multer - `model / quality / fps / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 - **异步语义暴露给 AI**:服务端不做轮询,`video_gen` 只提交、`query_video` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI -- **上传接口与 MCP 走同一进程**:额外 `POST /upload` + `GET /uploads/*` 不走 MCP、不鉴权,靠内网隔离;`PUBLIC_BASE_URL` 环境变量控制返回 URL 的拼接 host,AI 看到的 tool description 启动时拼接进真实地址,避免 AI 自由发挥 +- **上传接口与 MCP 走同一进程**:额外 `POST /upload` + `GET /uploads/*` 不走 MCP、不鉴权;写路径只在容器内 3000(不外映射),公网只暴露只读监听 3001。写入时的 `UPLOAD_BASE_URL` 与返回给智谱的 `PUBLIC_BASE_URL` **分开配置**(前者内网、后者公网),AI 看到的 tool description 启动时拼接进真实地址,避免 AI 自由发挥 - **上传过期清理**:启动时 + 每小时一次删除 `mtime > UPLOAD_TTL_HOURS` 的文件,避免磁盘被不消费的上传堆满;清理 timer 用 `unref()` 不阻塞进程退出 ### 默认模型 @@ -402,7 +435,7 @@ A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。 A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 **Q: 上传的图片多久过期?** -A: 容器重启即丢(本服务不持久化)。请在上传后立刻把返回的 `url` 喂给 `video_gen.image_url`。URL 本身只有可访问性,不受单独 TTL 限制;但容器一旦重启,该文件物理消失,URL 变 404。 +A: 落宿主 `./uploads/`(重启不失效),但按 `UPLOAD_TTL_HOURS`(默认 24h)自动删除,所以拿到 `url` 后尽快喂给 `video_gen.image_url`。过期后 URL 变 404。 **Q: `PUBLIC_BASE_URL` 不设会怎样?** -A: compose 会给个默认值 `http://localhost:8083`(代码 fallback 是 `http://localhost:3000`),本机 curl 调试没问题,但智谱服务器拉不到图——图生视频会失败。所以无域名部署时要显式设成 `http://<服务器IP>:<宿主机映射端口>`,并确保该端口对公网可达。 \ No newline at end of file +A: compose 给个默认值 `http://localhost:8090/mcp-uploads`(代码 fallback 是 `http://localhost:`)。本机调试无所谓,但智谱服务器拉不到图——图生视频会失败。无域名部署时要显式设成 `http://<服务器IP>:/mcp-uploads`,并确认 agent-core 那边配了 `MCP_UPLOADS_URL`(否则中转路由不存在)。启动日志会打印两个实际生效的地址,一眼就能看出配对没。 \ No newline at end of file diff --git a/mcp/video_gen/src/mcp-server.js b/mcp/video_gen/src/mcp-server.js index b3c6145..24e5f93 100644 --- a/mcp/video_gen/src/mcp-server.js +++ b/mcp/video_gen/src/mcp-server.js @@ -23,15 +23,36 @@ const DEFAULT_FPS = 30; // 30 | 60 const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true // ===== 上传文件相关 ===== -// 公开的 base URL:拼接进 tool description,告诉 AI 该往哪里 POST 上传 -// 优先级:环境变量 > 默认 http://localhost: -function resolvePublicBaseUrl({ port, host }) { - const env = (process.env.PUBLIC_BASE_URL || "").trim(); - if (env) return env.replace(/\/+$/, ""); - return `http://localhost:${port}`; +// 两个地址刻意分开——无域名/无反代部署的关键: +// uploadBaseUrl —— 拼进 tool description 里那条 curl,告诉 AI 该往哪里 POST。这跳由 AI 在 +// agent-executor 里执行,走 docker 内网即可,不需要公网。 +// publicBaseUrl —— 拼进 /upload 返回的 url 字段。这跳是【智谱服务器】去 GET,必须公网可达。 +// 都不配时两者退化为 http://localhost:(本机调试)。 +function normalizeBaseUrl(s) { + return String(s || "").trim().replace(/\/+$/, ""); } -// 上传文件存储目录:容器内临时目录,服务重启即丢(你明确要求) +function resolveUploadBaseUrl({ port }) { + return ( + normalizeBaseUrl(process.env.UPLOAD_BASE_URL) || + normalizeBaseUrl(process.env.PUBLIC_BASE_URL) || + `http://localhost:${port}` + ); +} + +function resolvePublicBaseUrl({ port }) { + return ( + normalizeBaseUrl(process.env.PUBLIC_BASE_URL) || + `http://localhost:${port}` + ); +} + +// 公网只读监听端口(容器内):>0 时额外起一个只挂 GET /uploads/* 的监听,专门给智谱下载。 +// 0/未设 = 不开(单监听模式,本机开发默认);等于主端口时也跳过。 +// 主端口(--port,容器内 3000)挂着 /mcp 与 POST /upload,容器外不映射,只在 docker 网络内可达。 +const PUBLIC_PORT = parseInt(process.env.PUBLIC_PORT || "0", 10) || 0; + +// 上传文件存储目录:compose 里 bind 到宿主 ./uploads(重启不让已发出的 URL 失效);本机裸跑默认 /tmp。 const UPLOAD_DIR = process.env.UPLOAD_DIR || "/tmp/video_gen_uploads"; const UPLOAD_PATH_PREFIX = "/uploads"; // 对外的 URL 路径前缀 const UPLOAD_MAX_BYTES = 8 * 1024 * 1024; // 8MB(智谱 image_url 上限 5MB,留余量) @@ -230,7 +251,7 @@ async function queryAsyncResult({ token, id }) { return data; // { id, request_id, model, task_status, video_result?, ... } } -function buildServer({ publicBaseUrl }) { +function buildServer({ publicBaseUrl, uploadBaseUrl }) { const server = new McpServer( { name: "video_gen", @@ -243,7 +264,7 @@ function buildServer({ publicBaseUrl }) { } ); - const uploadUrl = `${publicBaseUrl}/upload`; + const uploadUrl = `${uploadBaseUrl}/upload`; // ---------- 工具 1:video_gen ---------- server.tool( @@ -258,7 +279,7 @@ If you need to use a LOCAL image file as image_url, upload it FIRST with this ex The response JSON has a "url" field — pass that URL directly as the image_url argument below. Supported formats: png, jpeg, jpg. Max 5MB per image. -Uploaded files live in container temp storage and are discarded on restart — do not rely on long-term URLs.`, +Uploaded files are kept on the server temporarily and auto-deleted after a TTL — do not rely on long-term URLs.`, { prompt: z .string() @@ -450,11 +471,13 @@ async function startHttp({ port, host }) { const app = express(); app.use(express.json({ limit: "2mb" })); - const publicBaseUrl = resolvePublicBaseUrl({ port, host }); - console.log(`[video_gen] PUBLIC_BASE_URL = ${publicBaseUrl}`); + const publicBaseUrl = resolvePublicBaseUrl({ port }); + const uploadBaseUrl = resolveUploadBaseUrl({ port }); + console.log(`[video_gen] UPLOAD_BASE_URL = ${uploadBaseUrl} (AI 往哪上传,走内网)`); + console.log(`[video_gen] PUBLIC_BASE_URL = ${publicBaseUrl} (返回给智谱的下载地址,须公网可达)`); // ===== /upload:接收图片,返回 URL(不走 MCP)===== - // 磁盘存储:保证 UPLOAD_DIR 存在(容器内临时,重启即丢) + // 磁盘存储:保证 UPLOAD_DIR 存在(compose 里挂到宿主 ./uploads,重启不失效) fs.mkdirSync(UPLOAD_DIR, { recursive: true }); // 过期清理:启动时跑一次,之后每小时一次 @@ -557,7 +580,7 @@ async function startHttp({ port, host }) { } const newId = randomUUID(); - const server = buildServer({ publicBaseUrl }); + const server = buildServer({ publicBaseUrl, uploadBaseUrl }); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newId, onsessioninitialized: (id) => { @@ -596,11 +619,38 @@ async function startHttp({ port, host }) { `[video_gen] MCP HTTP server listening on http://${host}:${port}/mcp` ); }); + + // ===== 公网只读监听(只给智谱下载用)===== + // 只挂 GET /uploads/* 与 /health:没有 /mcp、没有 POST /upload —— 写入口物理上不在这个端口上, + // 不靠 token,而是压根没监听。这一侧必须【匿名】可达(智谱拉图不带任何 header/凭据)。 + if (PUBLIC_PORT && PUBLIC_PORT !== port) { + const publicApp = express(); + publicApp.get("/health", (_req, res) => { + res.json({ status: "ok", service: "video_gen", scope: "public-read" }); + }); + publicApp.use( + UPLOAD_PATH_PREFIX, + express.static(UPLOAD_DIR, { + fallthrough: false, + maxAge: 0, + index: false, + }) + ); + publicApp.use((_req, res) => { + res.status(404).json({ error: "not found", scope: "public-read" }); + }); + publicApp.listen(PUBLIC_PORT, host, () => { + console.log( + `[video_gen] public read-only server listening on http://${host}:${PUBLIC_PORT}${UPLOAD_PATH_PREFIX}/*` + ); + }); + } } async function startStdio() { // stdio 模式下上传接口不可用,用 placeholder 避免 description 里出现奇怪的占位 - const server = buildServer({ publicBaseUrl: "http://localhost:3000" }); + const local = "http://localhost:3000"; + const server = buildServer({ publicBaseUrl: local, uploadBaseUrl: local }); const { StdioServerTransport } = await import( "@modelcontextprotocol/sdk/server/stdio.js" ); diff --git a/mcp/web_search/README.md b/mcp/web_search/README.md index 62d00f0..c1bafe0 100644 --- a/mcp/web_search/README.md +++ b/mcp/web_search/README.md @@ -37,13 +37,15 @@ MCP 端点: `docker-compose.yml` 中的 `mcp_web_search` 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 `npm install -g`)。 -容器内监听 3000,默认映射到宿主机 `8081`(可用 `WEB_SEARCH_PORT` 覆盖): +容器内监听 3000,**默认不占宿主端口**:agent 走 `my-app-network` 按容器名访问 +(`http://mcp_web_search:3000/`)。需要从宿主机 curl 调试时,把仓库根 `docker-compose.yml` 里 +`mcp_web_search` 注释掉的 `ports` 两行打开(默认写的是 8081),调试完记得注释回去。 ```bash docker compose build mcp_web_search && docker compose up -d mcp_web_search -curl http://localhost:8081/health +# 不占端口的健康检查 +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} ``` -agent 侧走 `my-app-network` 用容器名访问(`http://mcp_web_search:3000/`),不依赖宿主机端口; -该服务**无服务端鉴权**,暴露到公网会被白嫆(消耗上游免费额度),建议不对公网放行 8081。 +该服务**无服务端鉴权**(上游是免费端点),**永远不要**对外映射端口——会被白嫆搜索额度。 From 3e46dd637589b33a131fd34d28e0b1afe76a2a61 Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 15 Sep 2026 19:57:45 +0800 Subject: [PATCH 25/41] =?UTF-8?q?video=5Fgen:=20=E4=B8=A2=E6=8E=89?= =?UTF-8?q?=E4=B8=8A=E4=BC=A0/=E8=90=BD=E7=9B=98=E6=95=B4=E5=A5=97?= =?UTF-8?q?=EF=BC=8C=E6=9C=AC=E5=9C=B0=E5=9B=BE=E7=89=87=E6=94=B9=E7=94=B1?= =?UTF-8?q?=20agent=20=E5=86=85=E7=BD=91=E7=8E=B0=E7=AD=BE=E5=85=AC?= =?UTF-8?q?=E7=BD=91=E9=93=BE=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 POST /upload、GET /uploads/*、multer、上传目录与 TTL 清理、公网只读监听(PUBLIC_PORT/3001) - 删除 UPLOAD_BASE_URL / PUBLIC_BASE_URL / UPLOAD_DIR,改为单一个 PUBLIC_LINK_URL: 工具描述里给的命令变成 curl -s "?path=<绝对路径>",stdout 即现成 URL - package.json: 去掉 multer 依赖;Dockerfile: EXPOSE 3000,去掉 3001 与上传说明 - docker-compose.yml: 去掉 ./uploads 挂载与相关 env,只留 PUBLIC_LINK_URL - .gitignore: 去掉 uploads/ - 文档: 根 README 与 video_gen README 改写「图片怎么到智谱手上」(零拷贝 + 签名链接) --- mcp/.gitignore | 4 +- mcp/README.md | 49 ++++--- mcp/docker-compose.yml | 20 +-- mcp/video_gen/Dockerfile | 7 +- mcp/video_gen/README.md | 145 +++----------------- mcp/video_gen/package.json | 3 +- mcp/video_gen/src/mcp-server.js | 226 ++++---------------------------- 7 files changed, 80 insertions(+), 374 deletions(-) diff --git a/mcp/.gitignore b/mcp/.gitignore index 3f3ba23..d58a2ca 100644 --- a/mcp/.gitignore +++ b/mcp/.gitignore @@ -1,5 +1,3 @@ node_modules/ -# video_gen 的上传目录(compose bind 到宿主机,运行时产物,不进库) -uploads/ -# 编排变量(PUBLIC_BASE_URL 等),含部署相关的地址,不进库 +# 编排变量(PUBLIC_LINK_URL 等),含部署相关的地址,不进库 .env diff --git a/mcp/README.md b/mcp/README.md index 98fdc3d..f44cd08 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -6,10 +6,11 @@ |---|---|---|---|---| | `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` | | `image_gen/` | `mcp_image_gen` | 智谱 CogView 图片生成 | `3000` | `POST /mcp` | -| `video_gen/` | `mcp_video_gen` | 智谱 CogVideo 视频生成(异步)+ 图片上传 | `3000` 全量 / `3001` 只读 | `POST /mcp` | +| `video_gen/` | `mcp_video_gen` | 智谱 CogVideo 视频生成(异步) | `3000` | `POST /mcp` | -**这些服务默认不占宿主机端口**——它们只挂在 `my-app-network` 上,由 `agent-core` / `agent-executor` +**这些服务一个宿主机端口都不占**——它们只挂在 `my-app-network` 上,由 `agent-core` / `agent-executor` 按容器名访问。所以整台服务器对外只需要开 agent-core 那一个端口(`AGENT_PORT`,默认 8090)。 +(要从宿主机 curl 调试时,把 `docker-compose.yml` 里对应服务注释掉的 `ports` 两行打开。) ## 部署(无 nginx-proxy) @@ -35,33 +36,32 @@ cd /root/workspace/tools/mcp && docker compose up -d --build | 变量 | 默认 | 说明 | |---|---|---| -| `PUBLIC_BASE_URL` | `http://localhost:8090/mcp-uploads` | **必须改**。video_gen `/upload` 返回给智谱的 URL 前缀,指向 agent-core 的只读中转;无域名时填 `http://<服务器IP>:/mcp-uploads` | +| `PUBLIC_LINK_URL` | `http://agent-core:8081/public-link` | video_gen 用:告诉 AI「本地图片怎么换成公网 URL」的 agent 内网签发入口 | | `WEB_SEARCH_PORT` | `8081` | 只在临时打开 web_search 调试端口时用 | | `IMAGE_GEN_PORT` | `8082` | 只在临时打开 image_gen 调试端口时用 | -| `VIDEO_GEN_PORT` | `8083` | 只在临时打开 video_gen 调试端口(只读监听)时用 | +| `VIDEO_GEN_PORT` | `8083` | 只在临时打开 video_gen 调试端口(MCP 口,仅本机短时调试)时用 | -## 图片是怎么到智谱手上的(video_gen 特有) +## 图片是怎么到智谱手上的(只有 video_gen 关心) -只有 `video_gen` 需要一个"公网可达的地址",因为智谱服务器生成视频前要**自己来拉这张参考图**, -它不带 cookie、不带 `Authorization`。链路是: +智谱服务器生成视频前要**自己来拉参考图**,它不带 cookie、不带 `Authorization`。这套链路里**没有任何人上传文件**: ``` -AI(agent-executor 内执行 curl) - │ POST /upload(走 docker 内网,不经过公网) - ▼ -mcp_video_gen:3000 ──存储──► ./uploads/.png - │ 返回 url = PUBLIC_BASE_URL + /uploads/ - ▼ -视频任务提交给智谱,image_url 就是上面那个 url - │ - ▼ -智谱 ──匿名 GET──► http://<服务器IP>:8090/mcp-uploads/uploads/ - │ agent-core 只转发 GET/HEAD - ▼ - mcp_video_gen:3001(只读监听,那边没有任何写路由) +AI(agent 的 executor 沙箱里) + │ curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/foo.png" + ▼ +agent-core :8081(内网、不映射宿主机 -> 无需凭据) + │ 现签一条签名下载链接(HMAC,含会话/路径/过期时间) + ▼ +AI 把拿到的 URL 当 image_url 交给 video_gen:3000/mcp + │ + ▼ +智谱 ──匿名 GET──► http://<服务器IP>:8090/api/sessions/<会话>/files/download-name/…&t=… + 那个文件始终躺在 agent 的任务目录里,零拷贝 ``` -所以:**写路径(`POST /upload`)永远不出公网**,公网只暴露一个只读、不可枚举、24h 过期的下载路径。 +- 链接:不可猜(HMAC)、会过期(默认 30 分钟)、绑会话、agent 重启即全部失效。 +- 前提:agent 侧 `config.yml` 配了 `public_link.base_url`(就是那个对外地址),否则签发端口不启动。 +- 唯一公网可达的东西是 agent 的 8090,以及那条**签名**下载路径;mcp 这三家一个端口都不露。 ## 端口与安全 @@ -69,16 +69,13 @@ mcp_video_gen:3000 ──存储──► ./uploads/.png |---|---|---| | `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | | `mcp_image_gen` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | -| `mcp_video_gen` | 无 | 只读路径已经由 agent-core 的 `/mcp-uploads` 代拉,无需自己占端口 | - -需要从宿主机直接 curl 调试时,去 `docker-compose.yml` 把对应服务注释掉的 `ports` 两行打开 -(video_gen 那个映的是只读监听 3001,不会暴露 `POST /upload`),调试完记得再注释回去。 -`video_gen` 的用户上传文件落在宿主 `./uploads/`(已 gitignore,24h 自动清理)。 +| `mcp_video_gen` | 无 | 它需要的公网下载路径由 agent 的签名链接提供,自己不占端口 | ## 单独调试 ```bash docker compose up -d --build mcp_web_search +# 不占端口的健康检查 docker exec mcp_web_search node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" ``` diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index 11d8178..d39245c 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -26,22 +26,14 @@ services: build: ./video_gen container_name: mcp_video_gen restart: unless-stopped - # 调试用(默认关;这里映的是只读监听 3001,不会暴露 POST /upload): + # 调试用(默认关;这里映的是 MCP 端口,会暴露 /mcp,仅本机短时调试用): # ports: - # - "${VIDEO_GEN_PORT:-8083}:3001" + # - "${VIDEO_GEN_PORT:-8083}:3000" environment: - # AI 往哪上传(拼进 video_gen 工具的 curl 模板):走 docker 内网即可,不需要公网。 - - UPLOAD_BASE_URL=http://mcp_video_gen:3000 - # 智谱从哪下载(拼进 /upload 返回的 url 字段):必须【公网可达】。 - # 无域名时填 http://<服务器IP>:/mcp-uploads(agent-core 的只读中转,默认端口 8090)。 - # 填错的现象:图传上去了,但智谱取不到图、图生视频失败;启动日志会打印实际生效的地址便于核对。 - - PUBLIC_BASE_URL=${PUBLIC_BASE_URL:-http://localhost:8090/mcp-uploads} - # 公网只读监听(容器内):agent 的 MCP_UPLOADS_URL 指向它;也只被上面那个调试端口映射。 - - PUBLIC_PORT=3001 - # 上传落宿主 ./uploads(重启不让已发出的 URL 失效),TTL 清理照旧 - - UPLOAD_DIR=/uploads - volumes: - - ./uploads:/uploads + # 本地图片 -> 公网 URL:agent-core 的【内网】签发入口(agent 侧 public_link 功能), + # agent-core:8081 就是它那个不映射宿主机的签发端口(env PUBLIC_LINK_PORT,默认 8081)。 + # 本服务不搬字节:只把这条命令拼进工具描述,AI 自己在沙箱里 curl,拿回一条短命链接。 + - PUBLIC_LINK_URL=${PUBLIC_LINK_URL:-http://agent-core:8081/public-link} networks: - my-app-network diff --git a/mcp/video_gen/Dockerfile b/mcp/video_gen/Dockerfile index 889d13c..77d8bef 100644 --- a/mcp/video_gen/Dockerfile +++ b/mcp/video_gen/Dockerfile @@ -9,9 +9,8 @@ RUN npm install --omit=dev # 复制源码 COPY . . -EXPOSE 3000 3001 +EXPOSE 3000 -# 启用 HTTP/SSE 模式: -# 3000 = MCP(/mcp) + POST /upload + GET /uploads/*,容器外不映射(只在 docker 网络内可达) -# 3001 = 公网只读的 GET /uploads/*,由 compose 映射到宿主机给智谱下载(PUBLIC_PORT 开启) +# HTTP 模式:只提供 MCP(/mcp)与 /health;容器外不映射,只在 my-app-network 内被 agent 访问。 +# 本地图片需要公网 URL 时,AI 去 curl agent 的内网签发入口(env PUBLIC_LINK_URL),本服务不搬字节。 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 index 0f8d948..1cb75be 100644 --- a/mcp/video_gen/README.md +++ b/mcp/video_gen/README.md @@ -5,9 +5,9 @@ - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - 上游:[智谱 BigModel 视频生成(异步)](https://docs.bigmodel.cn/api-reference/模型-api/视频生成异步) + [查询异步结果](https://docs.bigmodel.cn/api-reference/模型-api/查询异步结果) - 默认模型:`cogvideox-flash` -- 端口:容器内 `3000`(`/mcp` + `POST /upload` + `GET /uploads/*`,**容器外不映射**)、容器内 `3001`(公网只读的 `GET /uploads/*`) +- 端口:容器内 `3000`(MCP `/mcp` + `/health`,**容器外不映射**,只在 `my-app-network` 内被 agent 访问) - 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token -- 附带 `/upload`:供 AI 上传本地图片换取 URL(写路径只在 docker 内网可达;落宿主 `./uploads/`,按 TTL 自动清理) +- 本地文件需要公网 URL 时:不传字节,让 AI 去 agent 的内网签发入口现签一条短命链接(见下节) --- @@ -24,7 +24,7 @@ docker compose up -d --build mcp_video_gen 服务容器名 `mcp_video_gen`,**默认不占宿主机端口**:由 agent 走 `my-app-network` 按容器名访问 (`http://mcp_video_gen:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 `docker-compose.yml` -把 `mcp_video_gen` 注释掉的 `ports` 两行打开(映的是只读监听 3001)。 +把 `mcp_video_gen` 注释掉的 `ports` 两行打开(映的是 MCP 端口 3000,仅本机短时调试用)。 ```bash # 容器内健康检查(无需占端口) @@ -68,113 +68,23 @@ docker exec mcp_video_gen node -e "fetch('http://localhost:3000/health').then(r= --- -## 上传图片:POST /upload -供 AI 上传本地图片、拿到 URL 后喂给 `video_gen.image_url`。**不走 MCP、不走鉴权**,但**写路径只在内网**(容器内 3000,容器外不映射), -所以公网上没有任何写入入口。唯一公网可达的是**只读**的下载路径,而且由 agent-core 代拉: +## 本地文件 → 公网 URL(本服务不搬字节) -``` -AI(agent-executor 内 curl) - │ POST http://mcp_video_gen:3000/upload ← docker 内网,不经公网 - ▼ - ./uploads/.png 返回 url = PUBLIC_BASE_URL + /uploads/ - │ - ▼ -智谱服务器 ──匿名 GET──► http://<服务器IP>:/mcp-uploads/uploads/ - │ agent-core 只转发 GET/HEAD - ▼ - mcp_video_gen:3001(只读监听,那边没有 /upload) -``` - -### 配置(两个地址刻意分开) - -| 变量 | 作用 | 该填什么 | -|---|---|---| -| `UPLOAD_BASE_URL` | 拼进 tool description 里那条 curl,告诉 AI 往哪上传 | 内网地址 `http://mcp_video_gen:3000`(compose 已配好) | -| `PUBLIC_BASE_URL` | 拼进 `/upload` 返回的 `url` 字段,给**智谱**下载用 | **必须外部可达**:`http://<服务器IP>:/mcp-uploads` | -| `PUBLIC_PORT` | 只读监听的容器内端口(agent 的 `MCP_UPLOADS_URL` 指向它) | compose 里是 `3001`;留 `0` 则不开双监听 | - -`UPLOAD_BASE_URL` 未设时会退回 `PUBLIC_BASE_URL`,两个都没设则都是 `http://localhost:`(本机调试)。 -启动日志会打印两个实际生效的地址,配错了一看就知道。 - -其它环境变量: - -| 变量 | 默认 | 说明 | -|---|---|---| -| `UPLOAD_DIR` | `/tmp/video_gen_uploads` | 磁盘存储目录;compose 里指向宿主挂载的 `/uploads` | -| `UPLOAD_TTL_HOURS` | `24` | 超过该小时数的文件会在启动时和每小时被自动删除 | - -### 接口 - -``` -POST /upload (只在容器内 3000,内网可达) -Content-Type: multipart/form-data - -file: <二进制图片文件> -``` - -### 限制 - -| 项 | 值 | -|---|---| -| 最大体积 | 8MB(智谱 `image_url` 上限5MB,留余量) | -| 白名单 content-type | `image/png`、`image/jpeg`、`image/jpg` | -| 存储位置 | 宿主 `./uploads/`(compose 挂到容器 `/uploads`,`UPLOAD_DIR` 可覆盖) | -| 持久化 | 落盘,重启不失效;但按 TTL 到期自动删,**不要依赖长期 URL** | -| 过期清理 | 启动时 + 每小时一次删除 `>UPLOAD_TTL_HOURS` 的文件,默认 24h | -| 鉴权 | 无(靠“不映射到宿主机”隔离;AI 走内网访问) | - -### 返回 - -```jsonc -{ - "url": "http://<服务器IP>:8090/mcp-uploads/uploads/abc123.png", - "filename": "abc123.png", - "size": 12345, - "content_type": "image/png", - "original_name": "my-cat.png" -} -``` - -返回的 `url` 可直接作为 `video_gen.image_url` 使用(前缀 = `PUBLIC_BASE_URL`)。 - -### 端口与路由 - -| 容器内端口 | 路由 | 容器外 | -|---|---|---| -| `3000` | `/mcp` + `POST /upload` + `GET /uploads/*` | 不映射,只在 `my-app-network` 内可达 | -| `3001`(`PUBLIC_PORT`) | 只有 `GET /uploads/*` + `/health` | 也不映射;由 agent-core 的 `MCP_UPLOADS_URL` 指向它代拉 | - -只读监听的意义:公网那条入站链路(智谱拉图)接的是它,所以即使 agent 侧中转有 bug 把写方法转过来, -这边也没路由可打(纵深防御)。 - -### curl 示例 - -默认不占宿主端口。推荐用 `docker exec` 在容器内测(不破坏安全边界): +`image_url` 必须是一个**公网可达**的 URL(智谱服务器会自己去拉)。图片在本地盘上时,本服务不负责上传, +而是让 AI 去 agent 那边现签一条短命的公网链接(实现见 agent 仓库 `app/server/routes/public-link.js`): ```bash -# 上传(走全量监听的 3000):把 /etc/hostname 当假图片,只为看返回结构 -docker exec mcp_video_gen node -e " - const fs=require('fs'); - const fd=new FormData(); - fd.append('file',new File([fs.readFileSync('/etc/hostname')],'t.png',{type:'image/png'})); - fetch('http://localhost:3000/upload',{method:'POST',body:fd}).then(r=>r.json()).then(j=>console.log(j)); -" - -# 只读监听取文件(把 换成上一步返回的 filename) -docker exec mcp_video_gen node -e "fetch('http://localhost:3001/uploads/').then(r=>console.log(r.status,r.headers.get('content-type')))" - -# 只读监听上试写:应当 404(那边没有 /upload) -docker exec mcp_video_gen node -e "fetch('http://localhost:3001/upload',{method:'POST'}).then(r=>console.log(r.status))" +# AI 在 agent 的 executor 沙箱里执行;路径就是它平时看到的那个绝对路径 +curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/foo.png" +# stdout 就是现成 URL(纯文本,不需要解析 JSON): +# http://<服务器IP>:8090/api/sessions/<会话>/files/download-name/foo.png?path=foo.png&expires=…&t=… ``` -要从宿主机 curl 调试,临时把 compose 里注释的 `ports` 打开(打开的是只读侧 `8083:3001`; -想试上传就临时改成 `8083:3000`,测完记得改回来): - -```bash -curl -sI http://localhost:8083/uploads/ # 只读侧取图:200 -curl -s http://localhost:8083/upload # 只读侧写:404(本来就没这个路由) -``` +- 那条链接是 agent 的**签名下载链接**:不可猜(HMAC)、会过期(默认 30 分钟)、绑会话、agent 重启即全部失效。 +- `8081` 是 agent 侧的**内网**签发端口(`PUBLIC_LINK_PORT`),**不映射到宿主机**,所以接它不需要任何凭据; + 地址由 env `PUBLIC_LINK_URL` 告诉本服务(compose 已默认指向 `http://agent-core:8081/public-link`)。 +- `PUBLIC_LINK_URL` 没配时,工具描述里不会出现这条命令,而是提示“请运维配置”。 --- @@ -187,7 +97,7 @@ curl -s http://localhost:8083/upload # 只读侧写:404(本来 | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| | `prompt` | string | ✅ | 视频文本描述,最大 512 字符 | -| `image_url` | string (URL) | ❌ | 参考图 URL(**单张**,不支持数组 / 多张 / 首尾帧)。图片 ≤ 5MB,格式 png/jpeg/jpg。本地文件请走 `/upload` | +| `image_url` | string (URL) | ❌ | 参考图 URL(**单张**,不支持数组 / 多张 / 首尾帧)。图片 ≤ 5MB,格式 png/jpeg/jpg。本地文件请先用上一节的命令换一条公网链接 | | `size` | string | ❌ | 视频尺寸,例如 `1920x1080`、`1080x1920`、`1024x1024`、`1280x960` 等 | | `with_audio` | boolean | ❌ | 是否生成 AI 音效,默认 `false` | @@ -269,7 +179,7 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 ## 推荐用法(AI 视角) ``` -1. 如果手头是【本地文件】:先调 POST {UPLOAD_BASE_URL}/upload 拿到 url,再进第 2 步 +1. 如果手头是【本地文件】:先 `curl -s "http://agent-core:8081/public-link?path=<绝对路径>"` 拿到一条公网链接(上一节),再进第 2 步 2. 调用 video_gen({ prompt, image_url?, size?, with_audio? }) 3. 拿到 task_id → 等待若干秒(建议 2~5 秒) 4. 调用 query_video({ task_id }) @@ -363,19 +273,6 @@ curl -s -X POST http://localhost:8083/mcp \ 响应是 SSE 格式(`event: message` + `data: {...}`),用 `grep '^data:'` 抽 JSON 即可。 -### 单独调试 `/upload` - -```bash -# 上传(需先在 compose 里临时把 ports 打开成 8083:3000;默认不映射) -curl -F "file=@/tmp/cat.png" http://localhost:8083/upload -# {"url":"http://<服务器IP>:8090/mcp-uploads/uploads/xxx.png", ...} ← 返回的是公网地址(PUBLIC_BASE_URL) - -# 直接从只读监听取文件(compose 默认那行就是 8083:3001) -curl -o cat.png http://localhost:8083/uploads/xxx.png -``` - ---- - ## 架构与文件 ``` @@ -397,8 +294,8 @@ package.json # @modelcontextprotocol/sdk + express + multer - `model / quality / fps / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 - **异步语义暴露给 AI**:服务端不做轮询,`video_gen` 只提交、`query_video` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI -- **上传接口与 MCP 走同一进程**:额外 `POST /upload` + `GET /uploads/*` 不走 MCP、不鉴权;写路径只在容器内 3000(不外映射),公网只暴露只读监听 3001。写入时的 `UPLOAD_BASE_URL` 与返回给智谱的 `PUBLIC_BASE_URL` **分开配置**(前者内网、后者公网),AI 看到的 tool description 启动时拼接进真实地址,避免 AI 自由发挥 -- **上传过期清理**:启动时 + 每小时一次删除 `mtime > UPLOAD_TTL_HOURS` 的文件,避免磁盘被不消费的上传堆满;清理 timer 用 `unref()` 不阻塞进程退出 +- **不搬字节**:本地文件 -> 公网 URL 完全由 agent 侧完成(`GET /public-link` 现签一条签名下载链接),本服务只把命令拼进工具描述;那只所以能不给本体加任何写入口、不落盘、不需要额外端口 +- **链接短命**:签名链接默认 30 分钟过期、绑会话、agent 重启即全失效;`PUBLIC_LINK_URL` 未配时工具描述退化为“请运维配置” ### 默认模型 @@ -435,7 +332,7 @@ A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。 A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 **Q: 上传的图片多久过期?** -A: 落宿主 `./uploads/`(重启不失效),但按 `UPLOAD_TTL_HOURS`(默认 24h)自动删除,所以拿到 `url` 后尽快喂给 `video_gen.image_url`。过期后 URL 变 404。 +A: 本服务不存图,不存在“上传的图片”:要用的图在 agent 的任务目录里,AI 现签一条签名链接给智谱拉。链接按 agent 的 `public_link.ttl_ms`(默认 30 分钟)过期,过期后 URL 变 403。 -**Q: `PUBLIC_BASE_URL` 不设会怎样?** -A: compose 给个默认值 `http://localhost:8090/mcp-uploads`(代码 fallback 是 `http://localhost:`)。本机调试无所谓,但智谱服务器拉不到图——图生视频会失败。无域名部署时要显式设成 `http://<服务器IP>:/mcp-uploads`,并确认 agent-core 那边配了 `MCP_UPLOADS_URL`(否则中转路由不存在)。启动日志会打印两个实际生效的地址,一眼就能看出配对没。 \ No newline at end of file +**Q: `PUBLIC_LINK_URL` 不配会怎样?** +A: 工具描述里不会出现“怎么把本地文件变成公网 URL”的命令,而是提示让运维配置,AI 就只能用已经是公网 URL 的图片(比如 image_gen 刚生成的图)。配的时候注意:它指向的是 agent 侧的**内网**签发端口(`http://agent-core:8081/public-link`),不是 agent 对外的 8090。 \ No newline at end of file diff --git a/mcp/video_gen/package.json b/mcp/video_gen/package.json index 34d606a..ca15cbb 100644 --- a/mcp/video_gen/package.json +++ b/mcp/video_gen/package.json @@ -9,7 +9,6 @@ }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.4", - "express": "^4.21.0", - "multer": "^1.4.5-lts.1" + "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 index 24e5f93..348bbca 100644 --- a/mcp/video_gen/src/mcp-server.js +++ b/mcp/video_gen/src/mcp-server.js @@ -1,8 +1,5 @@ #!/usr/bin/env node import express from "express"; -import multer from "multer"; -import path from "node:path"; -import fs from "node:fs"; import { randomUUID } from "node:crypto"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; @@ -22,88 +19,13 @@ const DEFAULT_QUALITY = "speed"; // speed | quality const DEFAULT_FPS = 30; // 30 | 60 const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true -// ===== 上传文件相关 ===== -// 两个地址刻意分开——无域名/无反代部署的关键: -// uploadBaseUrl —— 拼进 tool description 里那条 curl,告诉 AI 该往哪里 POST。这跳由 AI 在 -// agent-executor 里执行,走 docker 内网即可,不需要公网。 -// publicBaseUrl —— 拼进 /upload 返回的 url 字段。这跳是【智谱服务器】去 GET,必须公网可达。 -// 都不配时两者退化为 http://localhost:(本机调试)。 -function normalizeBaseUrl(s) { - return String(s || "").trim().replace(/\/+$/, ""); -} - -function resolveUploadBaseUrl({ port }) { - return ( - normalizeBaseUrl(process.env.UPLOAD_BASE_URL) || - normalizeBaseUrl(process.env.PUBLIC_BASE_URL) || - `http://localhost:${port}` - ); -} - -function resolvePublicBaseUrl({ port }) { - return ( - normalizeBaseUrl(process.env.PUBLIC_BASE_URL) || - `http://localhost:${port}` - ); -} - -// 公网只读监听端口(容器内):>0 时额外起一个只挂 GET /uploads/* 的监听,专门给智谱下载。 -// 0/未设 = 不开(单监听模式,本机开发默认);等于主端口时也跳过。 -// 主端口(--port,容器内 3000)挂着 /mcp 与 POST /upload,容器外不映射,只在 docker 网络内可达。 -const PUBLIC_PORT = parseInt(process.env.PUBLIC_PORT || "0", 10) || 0; - -// 上传文件存储目录:compose 里 bind 到宿主 ./uploads(重启不让已发出的 URL 失效);本机裸跑默认 /tmp。 -const UPLOAD_DIR = process.env.UPLOAD_DIR || "/tmp/video_gen_uploads"; -const UPLOAD_PATH_PREFIX = "/uploads"; // 对外的 URL 路径前缀 -const UPLOAD_MAX_BYTES = 8 * 1024 * 1024; // 8MB(智谱 image_url 上限 5MB,留余量) -const UPLOAD_ALLOWED_MIME = new Set([ - "image/png", - "image/jpeg", - "image/jpg", -]); - -// 过期清理:UPLOAD_TTL_HOURS 小时之前的文件会被定时删除 -const UPLOAD_TTL_HOURS = (() => { - const n = parseInt(process.env.UPLOAD_TTL_HOURS || "24", 10); - return Number.isFinite(n) && n > 0 ? n : 24; -})(); -const UPLOAD_TTL_MS = UPLOAD_TTL_HOURS * 60 * 60 * 1000; -const UPLOAD_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 每小时一次 - -// 清理 UPLOAD_DIR 下 mtime 早于 TTL 的文件。返回 {kept, removed, errors} -async function cleanupUploads({ now = Date.now(), dir = UPLOAD_DIR } = {}) { - let entries; - try { - entries = await fs.promises.readdir(dir); - } catch (e) { - if (e && e.code === "ENOENT") return { kept: 0, removed: 0, errors: 0 }; - console.error(`[video_gen] cleanup: readdir failed: ${e.message}`); - return { kept: 0, removed: 0, errors: 1 }; - } - - let kept = 0; - let removed = 0; - let errors = 0; - await Promise.all( - entries.map(async (name) => { - const full = path.join(dir, name); - try { - const st = await fs.promises.stat(full); - if (!st.isFile()) return; - if (now - st.mtimeMs >= UPLOAD_TTL_MS) { - await fs.promises.unlink(full); - removed++; - } else { - kept++; - } - } catch (e) { - if (e && e.code === "ENOENT") return; - errors++; - console.error(`[video_gen] cleanup: ${name}: ${e.message}`); - } - }) - ); - return { kept, removed, errors }; +// ===== 本地图片怎么拿到公网 URL ===== +// 本服务不搬字节:本地文件 -> 公网 URL 这件事由 agent(agent-core)侧完成: +// agent-core 在【内网】端口上提供签发入口(GET /public-link?path=<绝对路径>), +// 沙箱里的 AI 命令 curl 它,换回一条短命的签名下载链接(复用登录下载那套:不可猜/会过期/绑会话)。 +// 这里只把那条命令拼进 tool description 告诉 AI;agent 侧的具体实现见其 routes/public-link.js。 +function resolvePublicLinkUrl() { + return String(process.env.PUBLIC_LINK_URL || "").trim().replace(/\/+$/, ""); } function parseArgs(argv) { @@ -251,7 +173,7 @@ async function queryAsyncResult({ token, id }) { return data; // { id, request_id, model, task_status, video_result?, ... } } -function buildServer({ publicBaseUrl, uploadBaseUrl }) { +function buildServer({ publicLinkUrl }) { const server = new McpServer( { name: "video_gen", @@ -264,7 +186,15 @@ function buildServer({ publicBaseUrl, uploadBaseUrl }) { } ); - const uploadUrl = `${uploadBaseUrl}/upload`; + // 本地文件 -> 公网 URL 的那条命令。由 agent-core 的内网签发入口提供(见 resolvePublicLinkUrl 注释): + // 它返回 text/plain,stdout 就是现成 URL,所以 AI 不需要解析 JSON。 + const localFileHint = publicLinkUrl + ? `If you need to use a LOCAL image file as image_url, first mint a temporary public URL for it by running this exact command in the shell (replace the path with the file's absolute path): + + curl -s "${publicLinkUrl}?path=/workspace/tasks//your-image.png" + +The command prints ONE URL as plain text — pass that URL directly as the image_url argument below. The link is short-lived (minutes), so mint it right before calling this tool.` + : `If you need to use a LOCAL image file as image_url but no public-link minting endpoint is configured, ask the operator to configure it (env PUBLIC_LINK_URL). You cannot upload files from here.`; // ---------- 工具 1:video_gen ---------- server.tool( @@ -273,13 +203,9 @@ function buildServer({ publicBaseUrl, uploadBaseUrl }) { Returns the task_id immediately; poll the result later with query_video. prompt is required. Must add image_url for image-to-video. -If you need to use a LOCAL image file as image_url, upload it FIRST with this exact command (replace the path): +${localFileHint} - curl -F "file=@/path/to/your/image.png" ${uploadUrl} - -The response JSON has a "url" field — pass that URL directly as the image_url argument below. -Supported formats: png, jpeg, jpg. Max 5MB per image. -Uploaded files are kept on the server temporarily and auto-deleted after a TTL — do not rely on long-term URLs.`, +Supported formats: png, jpeg, jpg. Max 5MB per image, and the URL must be reachable from the public internet (the upstream fetches it itself).`, { prompt: z .string() @@ -291,7 +217,7 @@ Uploaded files are kept on the server temporarily and auto-deleted after a TTL .url() .optional() .describe( - "Reference image URL string for image-to-video. Image <= 5MB, .png/.jpeg/.jpg. Use the /upload endpoint to get a URL from a local file." + "Reference image URL string for image-to-video. Image <= 5MB, .png/.jpeg/.jpg. For a local file, first mint a temporary public URL with the shell command shown in this tool's description." ), size: z .string() @@ -471,83 +397,8 @@ async function startHttp({ port, host }) { const app = express(); app.use(express.json({ limit: "2mb" })); - const publicBaseUrl = resolvePublicBaseUrl({ port }); - const uploadBaseUrl = resolveUploadBaseUrl({ port }); - console.log(`[video_gen] UPLOAD_BASE_URL = ${uploadBaseUrl} (AI 往哪上传,走内网)`); - console.log(`[video_gen] PUBLIC_BASE_URL = ${publicBaseUrl} (返回给智谱的下载地址,须公网可达)`); - - // ===== /upload:接收图片,返回 URL(不走 MCP)===== - // 磁盘存储:保证 UPLOAD_DIR 存在(compose 里挂到宿主 ./uploads,重启不失效) - fs.mkdirSync(UPLOAD_DIR, { recursive: true }); - - // 过期清理:启动时跑一次,之后每小时一次 - cleanupUploads() - .then((r) => - console.log( - `[video_gen] startup cleanup: kept=${r.kept} removed=${r.removed} errors=${r.errors} ttl=${UPLOAD_TTL_HOURS}h` - ) - ) - .catch((e) => console.error(`[video_gen] startup cleanup failed: ${e.message}`)); - const cleanupTimer = setInterval(() => { - cleanupUploads() - .then((r) => { - if (r.removed > 0 || r.errors > 0) { - console.log( - `[video_gen] periodic cleanup: kept=${r.kept} removed=${r.removed} errors=${r.errors}` - ); - } - }) - .catch((e) => console.error(`[video_gen] periodic cleanup failed: ${e.message}`)); - }, UPLOAD_CLEANUP_INTERVAL_MS); - cleanupTimer.unref(); // 不阻止进程退出 - - const storage = multer.diskStorage({ - destination: (_req, _file, cb) => cb(null, UPLOAD_DIR), - filename: (_req, file, cb) => { - const ext = (path.extname(file.originalname) || ".bin").toLowerCase(); - cb(null, `${randomUUID()}${ext}`); - }, - }); - - const upload = multer({ - storage, - limits: { fileSize: UPLOAD_MAX_BYTES, files: 1 }, - fileFilter: (_req, file, cb) => { - if (UPLOAD_ALLOWED_MIME.has(file.mimetype)) return cb(null, true); - cb(new Error(`Unsupported content-type: ${file.mimetype}. Allowed: ${[...UPLOAD_ALLOWED_MIME].join(", ")}`)); - }, - }); - - app.post("/upload", (req, res) => { - upload.single("file")(req, res, (err) => { - if (err) { - const status = err.code === "LIMIT_FILE_SIZE" ? 413 : 400; - return res.status(status).json({ - error: err.message || "upload failed", - }); - } - if (!req.file) { - return res.status(400).json({ error: "Missing form field 'file'" }); - } - const url = `${publicBaseUrl}${UPLOAD_PATH_PREFIX}/${req.file.filename}`; - return res.json({ - url, - filename: req.file.filename, - size: req.file.size, - content_type: req.file.mimetype, - original_name: req.file.originalname, - }); - }); - }); - - // 静态下载:只要文件存在于 UPLOAD_DIR 就吐出去(不鉴权、不持久化) - app.use( - UPLOAD_PATH_PREFIX, - express.static(UPLOAD_DIR, { - fallthrough: false, - maxAge: 0, - }) - ); + const publicLinkUrl = resolvePublicLinkUrl(); + console.log(`[video_gen] PUBLIC_LINK_URL = ${publicLinkUrl || "(未配置 -> 工具描述里不会出现本地文件取公网 URL 的命令)"}`); // session -> { server, transport } 映射 const sessions = new Map(); @@ -580,7 +431,7 @@ async function startHttp({ port, host }) { } const newId = randomUUID(); - const server = buildServer({ publicBaseUrl, uploadBaseUrl }); + const server = buildServer({ publicLinkUrl }); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newId, onsessioninitialized: (id) => { @@ -619,38 +470,11 @@ async function startHttp({ port, host }) { `[video_gen] MCP HTTP server listening on http://${host}:${port}/mcp` ); }); - - // ===== 公网只读监听(只给智谱下载用)===== - // 只挂 GET /uploads/* 与 /health:没有 /mcp、没有 POST /upload —— 写入口物理上不在这个端口上, - // 不靠 token,而是压根没监听。这一侧必须【匿名】可达(智谱拉图不带任何 header/凭据)。 - if (PUBLIC_PORT && PUBLIC_PORT !== port) { - const publicApp = express(); - publicApp.get("/health", (_req, res) => { - res.json({ status: "ok", service: "video_gen", scope: "public-read" }); - }); - publicApp.use( - UPLOAD_PATH_PREFIX, - express.static(UPLOAD_DIR, { - fallthrough: false, - maxAge: 0, - index: false, - }) - ); - publicApp.use((_req, res) => { - res.status(404).json({ error: "not found", scope: "public-read" }); - }); - publicApp.listen(PUBLIC_PORT, host, () => { - console.log( - `[video_gen] public read-only server listening on http://${host}:${PUBLIC_PORT}${UPLOAD_PATH_PREFIX}/*` - ); - }); - } } async function startStdio() { - // stdio 模式下上传接口不可用,用 placeholder 避免 description 里出现奇怪的占位 - const local = "http://localhost:3000"; - const server = buildServer({ publicBaseUrl: local, uploadBaseUrl: local }); + // stdio 模式:拿不到 agent 的内网签发入口也没关系,description 里会退化为“请运维配 PUBLIC_LINK_URL” + const server = buildServer({ publicLinkUrl: resolvePublicLinkUrl() }); const { StdioServerTransport } = await import( "@modelcontextprotocol/sdk/server/stdio.js" ); From 4300c8e5b4fdc199611e76848ed72dddf705b988 Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 15 Sep 2026 21:00:02 +0800 Subject: [PATCH 26/41] =?UTF-8?q?=E6=9E=84=E5=BB=BA=E6=8F=90=E9=80=9F?= =?UTF-8?q?=EF=BC=9Anpm=20=E9=BB=98=E8=AE=A4=E8=B5=B0=E8=85=BE=E8=AE=AF?= =?UTF-8?q?=E4=BA=91=E9=95=9C=E5=83=8F=EF=BC=88=E5=8F=AF=E7=94=A8=20--buil?= =?UTF-8?q?d-arg=20NPM=5FREGISTRY=20=E8=A6=86=E7=9B=96=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - image_gen/Dockerfile、video_gen/Dockerfile: 加 ARG NPM_REGISTRY + npm config set registry (web_search 零依赖、不需要) --- mcp/image_gen/Dockerfile | 6 +++++- mcp/video_gen/Dockerfile | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/mcp/image_gen/Dockerfile b/mcp/image_gen/Dockerfile index daa9bd6..449aca1 100644 --- a/mcp/image_gen/Dockerfile +++ b/mcp/image_gen/Dockerfile @@ -2,9 +2,13 @@ FROM node:22-slim WORKDIR /app +# 国内构建慢:npm 默认源在国外(web_search 零依赖不需要,这个要)。 +# 想换回官方:docker compose build --build-arg NPM_REGISTRY=https://registry.npmjs.org/ mcp_image_gen +ARG NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ + # 复制 package.json 并安装依赖 COPY package.json ./ -RUN npm install --omit=dev +RUN npm config set registry "$NPM_REGISTRY" && npm install --omit=dev # 复制源码 COPY . . diff --git a/mcp/video_gen/Dockerfile b/mcp/video_gen/Dockerfile index 77d8bef..5c7ca5f 100644 --- a/mcp/video_gen/Dockerfile +++ b/mcp/video_gen/Dockerfile @@ -2,9 +2,13 @@ FROM node:22-slim WORKDIR /app +# 国内构建慢:npm 默认源在国外。想换回官方: +# docker compose build --build-arg NPM_REGISTRY=https://registry.npmjs.org/ mcp_video_gen +ARG NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ + # 复制 package.json 并安装依赖 COPY package.json ./ -RUN npm install --omit=dev +RUN npm config set registry "$NPM_REGISTRY" && npm install --omit=dev # 复制源码 COPY . . From 8814fcb67a674d7bb565c2b132952f62f81781dc Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 15 Sep 2026 21:27:51 +0800 Subject: [PATCH 27/41] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E5=85=AC?= =?UTF-8?q?=E7=BD=91=E4=B8=B4=E6=97=B6=E9=93=BE=E6=8E=A5=E6=94=B9=E4=B8=BA?= =?UTF-8?q?=E4=B8=8D=E9=80=8F=E6=98=8E=E7=9F=AD=20ID=EF=BC=88/p/?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 根 README: 图片到智谱的链路图与说明改为短 ID(约 50 字符、纯 ASCII、不带文件名/签名) - video_gen/README: 同上;补一句“为什么做短”(URL 会留在会话历史每轮重发);过期现象 403 → 404 - video_gen/src/mcp-server.js: 工具描述附近的注释同步 --- mcp/README.md | 10 ++++++---- mcp/video_gen/README.md | 13 ++++++++----- mcp/video_gen/src/mcp-server.js | 5 +++-- 3 files changed, 17 insertions(+), 11 deletions(-) diff --git a/mcp/README.md b/mcp/README.md index f44cd08..e0f88e5 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -50,16 +50,18 @@ AI(agent 的 executor 沙箱里) │ curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/foo.png" ▼ agent-core :8081(内网、不映射宿主机 -> 无需凭据) - │ 现签一条签名下载链接(HMAC,含会话/路径/过期时间) + │ 现签一个不透明短 ID(22 字符随机),内存表记着“哪个会话的哪个文件 + 何时过期” ▼ AI 把拿到的 URL 当 image_url 交给 video_gen:3000/mcp │ ▼ -智谱 ──匿名 GET──► http://<服务器IP>:8090/api/sessions/<会话>/files/download-name/…&t=… +智谱 ──匿名 GET──► http://<服务器IP>:8090/p/9fQ2mZ7xK4tR1vBn 那个文件始终躺在 agent 的任务目录里,零拷贝 ``` -- 链接:不可猜(HMAC)、会过期(默认 30 分钟)、绑会话、agent 重启即全部失效。 +- 链接:`/p/<22 字符随机 ID>`,约 50 字符、纯 ASCII(不带文件名/会话名/签名)——因为这条 URL 会被模型 + 抄进工具参数、并永久留在会话历史里每轮重发,越短越安全也越省 token。 +- 过期:agent 侧 `public_link.ttl_ms`(默认 30 分钟);agent 重启或过期后该 ID 立即失效(内存表)。 - 前提:agent 侧 `config.yml` 配了 `public_link.base_url`(就是那个对外地址),否则签发端口不启动。 - 唯一公网可达的东西是 agent 的 8090,以及那条**签名**下载路径;mcp 这三家一个端口都不露。 @@ -69,7 +71,7 @@ AI 把拿到的 URL 当 image_url 交给 video_gen:3000/mcp |---|---|---| | `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | | `mcp_image_gen` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | -| `mcp_video_gen` | 无 | 它需要的公网下载路径由 agent 的签名链接提供,自己不占端口 | +| `mcp_video_gen` | 无 | 它需要的公网下载路径由 agent 现签的匿名短链(`/p/`)提供,自己不占端口 | ## 单独调试 diff --git a/mcp/video_gen/README.md b/mcp/video_gen/README.md index 1cb75be..c54a559 100644 --- a/mcp/video_gen/README.md +++ b/mcp/video_gen/README.md @@ -78,10 +78,13 @@ docker exec mcp_video_gen node -e "fetch('http://localhost:3000/health').then(r= # AI 在 agent 的 executor 沙箱里执行;路径就是它平时看到的那个绝对路径 curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/foo.png" # stdout 就是现成 URL(纯文本,不需要解析 JSON): -# http://<服务器IP>:8090/api/sessions/<会话>/files/download-name/foo.png?path=foo.png&expires=…&t=… +# http://124.221.199.237:8090/p/9fQ2mZ7xK4tR1vBn ``` -- 那条链接是 agent 的**签名下载链接**:不可猜(HMAC)、会过期(默认 30 分钟)、绑会话、agent 重启即全部失效。 +- 那条链接是不透明短 ID:22 字符随机、纯 ASCII、不带文件名/会话名/签名,约 50 字符 + (签完由 agent 的 `public_files` 内存表记住“哪个文件 + 何时过期”)。刻意做短是因为它会被模型 + 抄进 `image_url` 参数、并永久留在会话历史里每轮重发。 +- 不可猜、会过期(默认 30 分钟)、agent 重启即全失效。 - `8081` 是 agent 侧的**内网**签发端口(`PUBLIC_LINK_PORT`),**不映射到宿主机**,所以接它不需要任何凭据; 地址由 env `PUBLIC_LINK_URL` 告诉本服务(compose 已默认指向 `http://agent-core:8081/public-link`)。 - `PUBLIC_LINK_URL` 没配时,工具描述里不会出现这条命令,而是提示“请运维配置”。 @@ -294,8 +297,8 @@ package.json # @modelcontextprotocol/sdk + express + multer - `model / quality / fps / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 - **异步语义暴露给 AI**:服务端不做轮询,`video_gen` 只提交、`query_video` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI -- **不搬字节**:本地文件 -> 公网 URL 完全由 agent 侧完成(`GET /public-link` 现签一条签名下载链接),本服务只把命令拼进工具描述;那只所以能不给本体加任何写入口、不落盘、不需要额外端口 -- **链接短命**:签名链接默认 30 分钟过期、绑会话、agent 重启即全失效;`PUBLIC_LINK_URL` 未配时工具描述退化为“请运维配置” +- **不搬字节**:本地文件 -> 公网 URL 完全由 agent 侧完成(`GET /public-link` 现签一个 22 字符随机短 ID),本服务只把命令拼进工具描述;所以能给本体不加任何写入口、不落盘、不需要额外端口 +- **链接短命且极短**:默认 30 分钟过期、agent 重启即全失效;`PUBLIC_LINK_URL` 未配时工具描述退化为“请运维配置” ### 默认模型 @@ -332,7 +335,7 @@ A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。 A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 **Q: 上传的图片多久过期?** -A: 本服务不存图,不存在“上传的图片”:要用的图在 agent 的任务目录里,AI 现签一条签名链接给智谱拉。链接按 agent 的 `public_link.ttl_ms`(默认 30 分钟)过期,过期后 URL 变 403。 +A: 本服务不存图,不存在“上传的图片”:要用的图在 agent 的任务目录里,AI 现签一个短 ID 给智谱拉。链接按 agent 的 `public_link.ttl_ms`(默认 30 分钟)过期,过期或 agent 重启后该 URL 变 404。 **Q: `PUBLIC_LINK_URL` 不配会怎样?** A: 工具描述里不会出现“怎么把本地文件变成公网 URL”的命令,而是提示让运维配置,AI 就只能用已经是公网 URL 的图片(比如 image_gen 刚生成的图)。配的时候注意:它指向的是 agent 侧的**内网**签发端口(`http://agent-core:8081/public-link`),不是 agent 对外的 8090。 \ No newline at end of file diff --git a/mcp/video_gen/src/mcp-server.js b/mcp/video_gen/src/mcp-server.js index 348bbca..ccba590 100644 --- a/mcp/video_gen/src/mcp-server.js +++ b/mcp/video_gen/src/mcp-server.js @@ -22,8 +22,9 @@ const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true // ===== 本地图片怎么拿到公网 URL ===== // 本服务不搬字节:本地文件 -> 公网 URL 这件事由 agent(agent-core)侧完成: // agent-core 在【内网】端口上提供签发入口(GET /public-link?path=<绝对路径>), -// 沙箱里的 AI 命令 curl 它,换回一条短命的签名下载链接(复用登录下载那套:不可猜/会过期/绑会话)。 -// 这里只把那条命令拼进 tool description 告诉 AI;agent 侧的具体实现见其 routes/public-link.js。 +// 沙箱里的 AI 命令 curl 它,换回一个约 50 字符的短链(http://:8090/p/<22 字符随机 ID>, +// 不可猜 / 会过期 / 不带文件名与签名 —— 因为这个 URL 会进会话历史每轮重发)。 +// 这里只把那条命令拼进 tool description 告诉 AI;agent 侧实现见其 routes/public-link.js。 function resolvePublicLinkUrl() { return String(process.env.PUBLIC_LINK_URL || "").trim().replace(/\/+$/, ""); } From 6fff0dd936ce542c7d542c980c73d384e1aa8fa1 Mon Sep 17 00:00:00 2001 From: root Date: Tue, 15 Sep 2026 22:23:39 +0800 Subject: [PATCH 28/41] =?UTF-8?q?=E7=BD=91=E7=BB=9C=E6=94=B9=E5=90=8D?= =?UTF-8?q?=EF=BC=9Amy-app-network=20=E2=86=92=20agent-mcp-net=EF=BC=88?= =?UTF-8?q?=E4=B8=8E=20agent=20=E4=BE=A7=E4=B8=80=E8=87=B4=EF=BC=8C?= =?UTF-8?q?=E7=BA=AF=E6=94=B9=E5=90=8D=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/README.md | 8 ++++---- mcp/docker-compose.yml | 10 +++++----- mcp/image_gen/README.md | 2 +- mcp/video_gen/Dockerfile | 2 +- mcp/video_gen/README.md | 4 ++-- mcp/web_search/README.md | 2 +- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/mcp/README.md b/mcp/README.md index e0f88e5..c878093 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -8,23 +8,23 @@ | `image_gen/` | `mcp_image_gen` | 智谱 CogView 图片生成 | `3000` | `POST /mcp` | | `video_gen/` | `mcp_video_gen` | 智谱 CogVideo 视频生成(异步) | `3000` | `POST /mcp` | -**这些服务一个宿主机端口都不占**——它们只挂在 `my-app-network` 上,由 `agent-core` / `agent-executor` +**这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor` 按容器名访问。所以整台服务器对外只需要开 agent-core 那一个端口(`AGENT_PORT`,默认 8090)。 (要从宿主机 curl 调试时,把 `docker-compose.yml` 里对应服务注释掉的 `ports` 两行打开。) ## 部署(无 nginx-proxy) -网络 `my-app-network` 由 **agent 的 compose 创建**,所以全新机器上必须先起一次 agent: +网络 `agent-mcp-net` 由 **agent 的 compose 创建**,所以全新机器上必须先起一次 agent: ```bash -# 1) 先起 agent(它会创建 my-app-network;首次还要先备好 config.yml 与 .env) +# 1) 先起 agent(它会创建 agent-mcp-net;首次还要先备好 config.yml 与 .env) cd /root/workspace/tools/agent && docker compose up -d --build # 2) 再起 mcp cd /root/workspace/tools/mcp && docker compose up -d --build ``` -> mcp 单独在一个没有该网络的机器上先起会报错(`network my-app-network declared as external, but could not be found`),这是预期行为。 +> mcp 单独在一个没有该网络的机器上先起会报错(`network agent-mcp-net declared as external, but could not be found`),这是预期行为。 > 拆的时候反着来(先 down mcp 再 down agent)。 `image_gen` / `video_gen` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index d39245c..bbfd304 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -1,4 +1,4 @@ -# 无 nginx-proxy 部署:这些服务**默认不占宿主机端口**,只挂在 my-app-network 上被 agent 按容器名访问。 +# 无 nginx-proxy 部署:这些服务**默认不占宿主机端口**,只挂在 agent-mcp-net 上被 agent 按容器名访问。 # 因此对外只需要开 agent-core 那一个端口(AGENT_PORT,默认 8090)。 # 需要从宿主机 curl 调试某个服务时,把它下面注释掉的 ports 两行打开。 services: @@ -10,7 +10,7 @@ services: # ports: # - "${WEB_SEARCH_PORT:-8081}:3000" networks: - - my-app-network + - agent-mcp-net mcp_image_gen: build: ./image_gen @@ -20,7 +20,7 @@ services: # ports: # - "${IMAGE_GEN_PORT:-8082}:3000" networks: - - my-app-network + - agent-mcp-net mcp_video_gen: build: ./video_gen @@ -35,10 +35,10 @@ services: # 本服务不搬字节:只把这条命令拼进工具描述,AI 自己在沙箱里 curl,拿回一条短命链接。 - PUBLIC_LINK_URL=${PUBLIC_LINK_URL:-http://agent-core:8081/public-link} networks: - - my-app-network + - agent-mcp-net networks: # 与 agent 仓库共用:网络由 agent 的 compose 创建并命名(所以要先起 agent), # 这里声明为 external 直接加入。agent-core / agent-executor 按容器名访问这些服务。 - my-app-network: + agent-mcp-net: external: true diff --git a/mcp/image_gen/README.md b/mcp/image_gen/README.md index 91184d9..cb81c02 100644 --- a/mcp/image_gen/README.md +++ b/mcp/image_gen/README.md @@ -21,7 +21,7 @@ cd /root/workspace/tools/mcp docker compose up -d --build mcp_image_gen ``` -服务容器名 `mcp_image_gen`,容器内端口 3000,**默认不占宿主端口**:agent 走 `my-app-network` +服务容器名 `mcp_image_gen`,容器内端口 3000,**默认不占宿主端口**:agent 走 `agent-mcp-net` 按容器名访问(`http://mcp_image_gen:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 `docker-compose.yml` 把 `mcp_image_gen` 注释掉的 `ports` 两行打开(默认写的是 8082),调试完记得注释回去。 diff --git a/mcp/video_gen/Dockerfile b/mcp/video_gen/Dockerfile index 5c7ca5f..e60de04 100644 --- a/mcp/video_gen/Dockerfile +++ b/mcp/video_gen/Dockerfile @@ -15,6 +15,6 @@ COPY . . EXPOSE 3000 -# HTTP 模式:只提供 MCP(/mcp)与 /health;容器外不映射,只在 my-app-network 内被 agent 访问。 +# HTTP 模式:只提供 MCP(/mcp)与 /health;容器外不映射,只在 agent-mcp-net 内被 agent 访问。 # 本地图片需要公网 URL 时,AI 去 curl agent 的内网签发入口(env PUBLIC_LINK_URL),本服务不搬字节。 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 index c54a559..3274d5c 100644 --- a/mcp/video_gen/README.md +++ b/mcp/video_gen/README.md @@ -5,7 +5,7 @@ - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - 上游:[智谱 BigModel 视频生成(异步)](https://docs.bigmodel.cn/api-reference/模型-api/视频生成异步) + [查询异步结果](https://docs.bigmodel.cn/api-reference/模型-api/查询异步结果) - 默认模型:`cogvideox-flash` -- 端口:容器内 `3000`(MCP `/mcp` + `/health`,**容器外不映射**,只在 `my-app-network` 内被 agent 访问) +- 端口:容器内 `3000`(MCP `/mcp` + `/health`,**容器外不映射**,只在 `agent-mcp-net` 内被 agent 访问) - 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token - 本地文件需要公网 URL 时:不传字节,让 AI 去 agent 的内网签发入口现签一条短命链接(见下节) @@ -22,7 +22,7 @@ cd /root/workspace/tools/mcp docker compose up -d --build mcp_video_gen ``` -服务容器名 `mcp_video_gen`,**默认不占宿主机端口**:由 agent 走 `my-app-network` 按容器名访问 +服务容器名 `mcp_video_gen`,**默认不占宿主机端口**:由 agent 走 `agent-mcp-net` 按容器名访问 (`http://mcp_video_gen:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 `docker-compose.yml` 把 `mcp_video_gen` 注释掉的 `ports` 两行打开(映的是 MCP 端口 3000,仅本机短时调试用)。 diff --git a/mcp/web_search/README.md b/mcp/web_search/README.md index c1bafe0..8e5f60a 100644 --- a/mcp/web_search/README.md +++ b/mcp/web_search/README.md @@ -37,7 +37,7 @@ MCP 端点: `docker-compose.yml` 中的 `mcp_web_search` 服务直接构建本目录,Dockerfile 已改为拷贝源码启动(不再有 `npm install -g`)。 -容器内监听 3000,**默认不占宿主端口**:agent 走 `my-app-network` 按容器名访问 +容器内监听 3000,**默认不占宿主端口**:agent 走 `agent-mcp-net` 按容器名访问 (`http://mcp_web_search:3000/`)。需要从宿主机 curl 调试时,把仓库根 `docker-compose.yml` 里 `mcp_web_search` 注释掉的 `ports` 两行打开(默认写的是 8081),调试完记得注释回去。 From 485a604d2d2560a28e7bf444e3023f91402a124a Mon Sep 17 00:00:00 2001 From: kicer Date: Thu, 17 Sep 2026 19:38:05 +0800 Subject: [PATCH 29/41] =?UTF-8?q?=E7=A7=BB=E9=99=A4=20PUBLIC=5FLINK=5FURL?= =?UTF-8?q?=20=E7=BB=95=E8=B7=AF=E9=93=BE=E8=B7=AF=EF=BC=9A=E6=9C=AC?= =?UTF-8?q?=E5=9C=B0=E6=96=87=E4=BB=B6=E5=8F=96=E5=85=AC=E7=BD=91=20URL=20?= =?UTF-8?q?=E6=94=B9=E7=94=B1=20agent=20=E5=86=85=E7=BD=AE=E5=B7=A5?= =?UTF-8?q?=E5=85=B7=E7=9B=B4=E5=8F=91=EF=BC=9Bvideo=5Fgen=20=E4=B8=8D?= =?UTF-8?q?=E5=86=8D=E9=80=8F=E4=BC=A0=20size=EF=BC=88=E4=B8=8A=E6=B8=B8?= =?UTF-8?q?=E7=94=A8=E9=BB=98=E8=AE=A4=E5=B0=BA=E5=AF=B8=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/.gitignore | 2 +- mcp/README.md | 20 ++++------ mcp/docker-compose.yml | 5 --- mcp/video_gen/Dockerfile | 1 - mcp/video_gen/README.md | 47 +++++++--------------- mcp/video_gen/src/mcp-server.js | 70 ++++++++------------------------- 6 files changed, 39 insertions(+), 106 deletions(-) diff --git a/mcp/.gitignore b/mcp/.gitignore index d58a2ca..88b017e 100644 --- a/mcp/.gitignore +++ b/mcp/.gitignore @@ -1,3 +1,3 @@ node_modules/ -# 编排变量(PUBLIC_LINK_URL 等),含部署相关的地址,不进库 +# 编排变量(调试端口等),含部署相关的地址,不进库 .env diff --git a/mcp/README.md b/mcp/README.md index c878093..2e67333 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -36,7 +36,6 @@ cd /root/workspace/tools/mcp && docker compose up -d --build | 变量 | 默认 | 说明 | |---|---|---| -| `PUBLIC_LINK_URL` | `http://agent-core:8081/public-link` | video_gen 用:告诉 AI「本地图片怎么换成公网 URL」的 agent 内网签发入口 | | `WEB_SEARCH_PORT` | `8081` | 只在临时打开 web_search 调试端口时用 | | `IMAGE_GEN_PORT` | `8082` | 只在临时打开 image_gen 调试端口时用 | | `VIDEO_GEN_PORT` | `8083` | 只在临时打开 video_gen 调试端口(MCP 口,仅本机短时调试)时用 | @@ -46,24 +45,19 @@ cd /root/workspace/tools/mcp && docker compose up -d --build 智谱服务器生成视频前要**自己来拉参考图**,它不带 cookie、不带 `Authorization`。这套链路里**没有任何人上传文件**: ``` -AI(agent 的 executor 沙箱里) - │ curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/foo.png" - ▼ -agent-core :8081(内网、不映射宿主机 -> 无需凭据) - │ 现签一个不透明短 ID(22 字符随机),内存表记着“哪个会话的哪个文件 + 何时过期” +AI ──调用 agent 内置的「公开临时 URL」工具(直接传文件路径)──► 拿到一条短命公网 URL + │ ▼ AI 把拿到的 URL 当 image_url 交给 video_gen:3000/mcp │ ▼ -智谱 ──匿名 GET──► http://<服务器IP>:8090/p/9fQ2mZ7xK4tR1vBn +智谱 ──匿名 GET──► agent 侧提供的公开临时 URL 那个文件始终躺在 agent 的任务目录里,零拷贝 ``` -- 链接:`/p/<22 字符随机 ID>`,约 50 字符、纯 ASCII(不带文件名/会话名/签名)——因为这条 URL 会被模型 - 抄进工具参数、并永久留在会话历史里每轮重发,越短越安全也越省 token。 -- 过期:agent 侧 `public_link.ttl_ms`(默认 30 分钟);agent 重启或过期后该 ID 立即失效(内存表)。 -- 前提:agent 侧 `config.yml` 配了 `public_link.base_url`(就是那个对外地址),否则签发端口不启动。 -- 唯一公网可达的东西是 agent 的 8090,以及那条**签名**下载路径;mcp 这三家一个端口都不露。 +- 签发与托管全在 agent 侧(它已集成为一个 tool,AI 直接调用即可,不需要 curl 任何内网入口)。 +- 链接短命:到期或 agent 重启后失效;智谱只在提交任务那一刻拉一次图,完全够用。 +- mcp 这三家一个端口都不露,唯一公网可达的东西只有 agent 自己。 ## 端口与安全 @@ -71,7 +65,7 @@ AI 把拿到的 URL 当 image_url 交给 video_gen:3000/mcp |---|---|---| | `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | | `mcp_image_gen` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | -| `mcp_video_gen` | 无 | 它需要的公网下载路径由 agent 现签的匿名短链(`/p/`)提供,自己不占端口 | +| `mcp_video_gen` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 | ## 单独调试 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index bbfd304..ecb9a2e 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -29,11 +29,6 @@ services: # 调试用(默认关;这里映的是 MCP 端口,会暴露 /mcp,仅本机短时调试用): # ports: # - "${VIDEO_GEN_PORT:-8083}:3000" - environment: - # 本地图片 -> 公网 URL:agent-core 的【内网】签发入口(agent 侧 public_link 功能), - # agent-core:8081 就是它那个不映射宿主机的签发端口(env PUBLIC_LINK_PORT,默认 8081)。 - # 本服务不搬字节:只把这条命令拼进工具描述,AI 自己在沙箱里 curl,拿回一条短命链接。 - - PUBLIC_LINK_URL=${PUBLIC_LINK_URL:-http://agent-core:8081/public-link} networks: - agent-mcp-net diff --git a/mcp/video_gen/Dockerfile b/mcp/video_gen/Dockerfile index e60de04..3f59400 100644 --- a/mcp/video_gen/Dockerfile +++ b/mcp/video_gen/Dockerfile @@ -16,5 +16,4 @@ COPY . . EXPOSE 3000 # HTTP 模式:只提供 MCP(/mcp)与 /health;容器外不映射,只在 agent-mcp-net 内被 agent 访问。 -# 本地图片需要公网 URL 时,AI 去 curl agent 的内网签发入口(env PUBLIC_LINK_URL),本服务不搬字节。 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 index 3274d5c..d6c116d 100644 --- a/mcp/video_gen/README.md +++ b/mcp/video_gen/README.md @@ -7,7 +7,7 @@ - 默认模型:`cogvideox-flash` - 端口:容器内 `3000`(MCP `/mcp` + `/health`,**容器外不映射**,只在 `agent-mcp-net` 内被 agent 访问) - 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token -- 本地文件需要公网 URL 时:不传字节,让 AI 去 agent 的内网签发入口现签一条短命链接(见下节) +- 本地文件需要公网 URL 时:不传字节,AI 直接调用 agent 内置的「公开临时 URL」工具拿到短命链接(见下节) --- @@ -71,23 +71,12 @@ docker exec mcp_video_gen node -e "fetch('http://localhost:3000/health').then(r= ## 本地文件 → 公网 URL(本服务不搬字节) -`image_url` 必须是一个**公网可达**的 URL(智谱服务器会自己去拉)。图片在本地盘上时,本服务不负责上传, -而是让 AI 去 agent 那边现签一条短命的公网链接(实现见 agent 仓库 `app/server/routes/public-link.js`): +`image_url` 必须是一个**公网可达**的 URL(智谱服务器会自己去拉)。图片在本地盘上时,本服务不负责上传: +agent 侧已集成为一个 **tool**,AI 直接传文件路径就能拿到一条公开临时 URL,拿来填 `image_url` 即可, +不需要 curl 任何地址、不需要任何配置。 -```bash -# AI 在 agent 的 executor 沙箱里执行;路径就是它平时看到的那个绝对路径 -curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/foo.png" -# stdout 就是现成 URL(纯文本,不需要解析 JSON): -# http://124.221.199.237:8090/p/9fQ2mZ7xK4tR1vBn -``` - -- 那条链接是不透明短 ID:22 字符随机、纯 ASCII、不带文件名/会话名/签名,约 50 字符 - (签完由 agent 的 `public_files` 内存表记住“哪个文件 + 何时过期”)。刻意做短是因为它会被模型 - 抄进 `image_url` 参数、并永久留在会话历史里每轮重发。 -- 不可猜、会过期(默认 30 分钟)、agent 重启即全失效。 -- `8081` 是 agent 侧的**内网**签发端口(`PUBLIC_LINK_PORT`),**不映射到宿主机**,所以接它不需要任何凭据; - 地址由 env `PUBLIC_LINK_URL` 告诉本服务(compose 已默认指向 `http://agent-core:8081/public-link`)。 -- `PUBLIC_LINK_URL` 没配时,工具描述里不会出现这条命令,而是提示“请运维配置”。 +- 文件始终躺在 agent 的任务目录里,零拷贝;链接短命、到期或 agent 重启后失效。 +- 智谱只在提交任务那一刻拉一次图,短命链接完全够用。 --- @@ -100,8 +89,7 @@ curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/foo.p | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| | `prompt` | string | ✅ | 视频文本描述,最大 512 字符 | -| `image_url` | string (URL) | ❌ | 参考图 URL(**单张**,不支持数组 / 多张 / 首尾帧)。图片 ≤ 5MB,格式 png/jpeg/jpg。本地文件请先用上一节的命令换一条公网链接 | -| `size` | string | ❌ | 视频尺寸,例如 `1920x1080`、`1080x1920`、`1024x1024`、`1280x960` 等 | +| `image_url` | string (URL) | ❌ | 参考图 URL(**单张**,不支持数组 / 多张 / 首尾帧)。图片 ≤ 5MB,格式 png/jpeg/jpg。本地文件请先用 agent 内置的公开临时 URL 工具换成公网链接(上一节) | | `with_audio` | boolean | ❌ | 是否生成 AI 音效,默认 `false` | ### 服务端 Header 覆盖项(AI 看不到) @@ -182,8 +170,8 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 ## 推荐用法(AI 视角) ``` -1. 如果手头是【本地文件】:先 `curl -s "http://agent-core:8081/public-link?path=<绝对路径>"` 拿到一条公网链接(上一节),再进第 2 步 -2. 调用 video_gen({ prompt, image_url?, size?, with_audio? }) +1. 如果手头是【本地文件】:先调用 agent 内置的「公开临时 URL」工具拿到一条公网链接(上一节),再进第 2 步 +2. 调用 video_gen({ prompt, image_url?, with_audio? }) 3. 拿到 task_id → 等待若干秒(建议 2~5 秒) 4. 调用 query_video({ task_id }) - 若 PROCESSING → 等一会再调 @@ -191,7 +179,7 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 - 若 FAIL → 展示错误信息,结束 ``` -> `video_gen` 的 tool description 里已经嵌入了完整 curl 上传命令,AI 一看就知道怎么传本地图片。 +> `image_url` 必须是公网可达 URL;本地文件走 agent 内置工具,本服务不参与上传。 --- @@ -251,7 +239,6 @@ curl -s -X POST http://localhost:8083/mcp \ "name": "video_gen", "arguments": { "prompt": "A cat is playing with a ball.", - "size": "1920x1080", "with_audio": true } } @@ -293,12 +280,12 @@ package.json # @modelcontextprotocol/sdk + express + multer - **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用,避免每请求重建 - **Token 闭包注入**:在 Express 入口处从 header 提取 token,闭包传给 tool 回调;不依赖 SDK 内部字段 - **AI 可见 vs AI 不可见**: - - AI 只看到 `prompt / image_url / size / with_audio` + - AI 只看到 `prompt / image_url / with_audio` - `model / quality / fps / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 - **异步语义暴露给 AI**:服务端不做轮询,`video_gen` 只提交、`query_video` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI -- **不搬字节**:本地文件 -> 公网 URL 完全由 agent 侧完成(`GET /public-link` 现签一个 22 字符随机短 ID),本服务只把命令拼进工具描述;所以能给本体不加任何写入口、不落盘、不需要额外端口 -- **链接短命且极短**:默认 30 分钟过期、agent 重启即全失效;`PUBLIC_LINK_URL` 未配时工具描述退化为“请运维配置” +- **不搬字节**:本地文件 -> 公网 URL 完全由 agent 侧集成的「公开临时 URL」工具完成,本服务不参与;所以本体不加任何写入口、不落盘、不需要额外端口 +- **链接短命**:公开临时 URL 到期或 agent 重启后失效;智谱只需在提交任务那一刻拉一次图 ### 默认模型 @@ -322,9 +309,6 @@ A: 智谱签发 URL 默认 24h 左右。需要在收到后及时转存到自己 **Q: 为什么 quality / fps 不让 AI 直接传?** A: 这些是技术档位,与成本/单价挂钩。让 AI 自主挑 `quality=quality + fps=60` 会爆账号预算。改成 header 由部署方注入更可控。 -**Q: 能否限制 `size` 白名单?** -A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `video_gen` 的 `size` schema 即可。 - **Q: 报错 `Missing valid Mcp-Session-Id`?** A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize`。 @@ -335,7 +319,4 @@ A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。 A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 **Q: 上传的图片多久过期?** -A: 本服务不存图,不存在“上传的图片”:要用的图在 agent 的任务目录里,AI 现签一个短 ID 给智谱拉。链接按 agent 的 `public_link.ttl_ms`(默认 30 分钟)过期,过期或 agent 重启后该 URL 变 404。 - -**Q: `PUBLIC_LINK_URL` 不配会怎样?** -A: 工具描述里不会出现“怎么把本地文件变成公网 URL”的命令,而是提示让运维配置,AI 就只能用已经是公网 URL 的图片(比如 image_gen 刚生成的图)。配的时候注意:它指向的是 agent 侧的**内网**签发端口(`http://agent-core:8081/public-link`),不是 agent 对外的 8090。 \ No newline at end of file +A: 本服务不存图,不存在“上传的图片”:要用的图在 agent 的任务目录里,AI 用 agent 内置的公开临时 URL 工具现取一条短命链接给智谱拉。链接过期或 agent 重启后该 URL 失效,但智谱只在提交任务时拉一次,不受影响。 \ No newline at end of file diff --git a/mcp/video_gen/src/mcp-server.js b/mcp/video_gen/src/mcp-server.js index ccba590..6a08dd3 100644 --- a/mcp/video_gen/src/mcp-server.js +++ b/mcp/video_gen/src/mcp-server.js @@ -19,16 +19,6 @@ const DEFAULT_QUALITY = "speed"; // speed | quality const DEFAULT_FPS = 30; // 30 | 60 const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true -// ===== 本地图片怎么拿到公网 URL ===== -// 本服务不搬字节:本地文件 -> 公网 URL 这件事由 agent(agent-core)侧完成: -// agent-core 在【内网】端口上提供签发入口(GET /public-link?path=<绝对路径>), -// 沙箱里的 AI 命令 curl 它,换回一个约 50 字符的短链(http://:8090/p/<22 字符随机 ID>, -// 不可猜 / 会过期 / 不带文件名与签名 —— 因为这个 URL 会进会话历史每轮重发)。 -// 这里只把那条命令拼进 tool description 告诉 AI;agent 侧实现见其 routes/public-link.js。 -function resolvePublicLinkUrl() { - return String(process.env.PUBLIC_LINK_URL || "").trim().replace(/\/+$/, ""); -} - function parseArgs(argv) { const args = { http: false, @@ -136,7 +126,6 @@ async function submitVideo({ model, prompt, image_url, - size, quality, with_audio, fps, @@ -154,7 +143,6 @@ async function submitVideo({ }; 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, @@ -174,7 +162,7 @@ async function queryAsyncResult({ token, id }) { return data; // { id, request_id, model, task_status, video_result?, ... } } -function buildServer({ publicLinkUrl }) { +function buildServer() { const server = new McpServer( { name: "video_gen", @@ -187,26 +175,13 @@ function buildServer({ publicLinkUrl }) { } ); - // 本地文件 -> 公网 URL 的那条命令。由 agent-core 的内网签发入口提供(见 resolvePublicLinkUrl 注释): - // 它返回 text/plain,stdout 就是现成 URL,所以 AI 不需要解析 JSON。 - const localFileHint = publicLinkUrl - ? `If you need to use a LOCAL image file as image_url, first mint a temporary public URL for it by running this exact command in the shell (replace the path with the file's absolute path): - - curl -s "${publicLinkUrl}?path=/workspace/tasks//your-image.png" - -The command prints ONE URL as plain text — pass that URL directly as the image_url argument below. The link is short-lived (minutes), so mint it right before calling this tool.` - : `If you need to use a LOCAL image file as image_url but no public-link minting endpoint is configured, ask the operator to configure it (env PUBLIC_LINK_URL). You cannot upload files from here.`; - // ---------- 工具 1:video_gen ---------- server.tool( "video_gen", - `Submit a video generation task (text-to-video or image-to-video). -Returns the task_id immediately; poll the result later with query_video. -prompt is required. Must add image_url for image-to-video. + `Submit an async video generation task. Returns a task_id; poll with query_video. -${localFileHint} - -Supported formats: png, jpeg, jpg. Max 5MB per image, and the URL must be reachable from the public internet (the upstream fetches it itself).`, +- text-to-video: provide prompt only. +- image-to-video: also provide image_url.`, { prompt: z .string() @@ -218,13 +193,7 @@ Supported formats: png, jpeg, jpg. Max 5MB per image, and the URL must be reacha .url() .optional() .describe( - "Reference image URL string for image-to-video. Image <= 5MB, .png/.jpeg/.jpg. For a local file, first mint a temporary public URL with the shell command shown in this tool's description." - ), - size: z - .string() - .optional() - .describe( - "Video size, e.g. 1920x1080, 1080x1920, 1024x1024, 1280x720, etc." + "Reference image for image-to-video. Must be a publicly reachable URL to a png/jpeg/jpg <= 5MB (for local files, first use the agent's built-in tool to mint a public temporary URL)." ), with_audio: z .boolean() @@ -265,16 +234,15 @@ Supported formats: png, jpeg, jpg. Max 5MB per image, and the URL must be reacha 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, - watermark_enabled, - }); + token, + model, + prompt: args.prompt, + image_url: args.image_url, + quality, + with_audio: args.with_audio ?? false, + fps, + watermark_enabled, + }); const summary = `Model: ${model}\n` + @@ -312,7 +280,7 @@ Supported formats: png, jpeg, jpg. Max 5MB per image, and the URL must be reacha task_id: z .string() .min(1) - .describe("The task id returned by video_gen."), + .describe("task_id returned by video_gen."), }, async (args, extra) => { const headers = extra?.requestInfo?.headers; @@ -398,9 +366,6 @@ async function startHttp({ port, host }) { const app = express(); app.use(express.json({ limit: "2mb" })); - const publicLinkUrl = resolvePublicLinkUrl(); - console.log(`[video_gen] PUBLIC_LINK_URL = ${publicLinkUrl || "(未配置 -> 工具描述里不会出现本地文件取公网 URL 的命令)"}`); - // session -> { server, transport } 映射 const sessions = new Map(); @@ -432,7 +397,7 @@ async function startHttp({ port, host }) { } const newId = randomUUID(); - const server = buildServer({ publicLinkUrl }); + const server = buildServer(); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newId, onsessioninitialized: (id) => { @@ -474,8 +439,7 @@ async function startHttp({ port, host }) { } async function startStdio() { - // stdio 模式:拿不到 agent 的内网签发入口也没关系,description 里会退化为“请运维配 PUBLIC_LINK_URL” - const server = buildServer({ publicLinkUrl: resolvePublicLinkUrl() }); + const server = buildServer(); const { StdioServerTransport } = await import( "@modelcontextprotocol/sdk/server/stdio.js" ); From ab667c136c00820b987a9c4fa3c9374290812b41 Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 22 Sep 2026 19:47:03 +0800 Subject: [PATCH 30/41] =?UTF-8?q?=E4=BC=98=E5=8C=96=E9=87=8D=E5=90=AF?= =?UTF-8?q?=E9=80=BB=E8=BE=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/image_gen/src/mcp-server.js | 36 ++++++++++++++++++++++++++++++++- mcp/video_gen/src/mcp-server.js | 36 ++++++++++++++++++++++++++++++++- mcp/web_search/server.js | 28 +++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 2 deletions(-) diff --git a/mcp/image_gen/src/mcp-server.js b/mcp/image_gen/src/mcp-server.js index 10a8c86..4c8903a 100644 --- a/mcp/image_gen/src/mcp-server.js +++ b/mcp/image_gen/src/mcp-server.js @@ -10,6 +10,26 @@ const ZHIPU_API_URL = "https://open.bigmodel.cn/api/paas/v4/images/generations"; const DEFAULT_MODEL = "CogView-3-Flash"; +// ── 优雅退出 ────────────────────────────────────────────────────────────── +// 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 +// 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 +// 显式注册处理器,关闭 MCP session 与长连接后立即退出;3s 定时器为兑底。 +let httpServer = null; +let closeAllSessions = () => {}; +let shuttingDown = false; + +function shutdown(sig) { + if (shuttingDown) return; + shuttingDown = true; + console.log(`[image_gen] 收到 ${sig},停止服务`); + closeAllSessions(); + if (!httpServer) process.exit(0); // stdio 模式无监听,直接退 + httpServer.close(() => process.exit(0)); + setTimeout(() => process.exit(0), 3000).unref(); +} +process.on("SIGTERM", () => shutdown("SIGTERM")); +process.on("SIGINT", () => shutdown("SIGINT")); + function parseArgs(argv) { const args = { http: false, @@ -206,6 +226,20 @@ async function startHttp({ port, host }) { // session -> { server, transport } 映射 const sessions = new Map(); + closeAllSessions = () => { + for (const { server, transport } of sessions.values()) { + try { + transport.close(); + } catch {} + try { + server.close(); + } catch {} + } + sessions.clear(); + // 掰掉未关闭的 SSE / keep-alive 连接,否则 httpServer.close() 回调不会触发 + httpServer?.closeAllConnections?.(); + }; + app.get("/health", (_req, res) => { res.json({ status: "ok", service: "image_gen", sessions: sessions.size }); }); @@ -268,7 +302,7 @@ async function startHttp({ port, host }) { app.get("/mcp", handleOther); app.delete("/mcp", handleOther); - app.listen(port, host, () => { + httpServer = app.listen(port, host, () => { console.log( `[image_gen] MCP HTTP server listening on http://${host}:${port}/mcp` ); diff --git a/mcp/video_gen/src/mcp-server.js b/mcp/video_gen/src/mcp-server.js index 6a08dd3..e78df68 100644 --- a/mcp/video_gen/src/mcp-server.js +++ b/mcp/video_gen/src/mcp-server.js @@ -19,6 +19,26 @@ const DEFAULT_QUALITY = "speed"; // speed | quality const DEFAULT_FPS = 30; // 30 | 60 const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true +// ── 优雅退出 ────────────────────────────────────────────────────────────── +// 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 +// 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 +// 显式注册处理器,关闭 MCP session 与长连接后立即退出;3s 定时器为兑底。 +let httpServer = null; +let closeAllSessions = () => {}; +let shuttingDown = false; + +function shutdown(sig) { + if (shuttingDown) return; + shuttingDown = true; + console.log(`[video_gen] 收到 ${sig},停止服务`); + closeAllSessions(); + if (!httpServer) process.exit(0); // stdio 模式无监听,直接退 + httpServer.close(() => process.exit(0)); + setTimeout(() => process.exit(0), 3000).unref(); +} +process.on("SIGTERM", () => shutdown("SIGTERM")); +process.on("SIGINT", () => shutdown("SIGINT")); + function parseArgs(argv) { const args = { http: false, @@ -369,6 +389,20 @@ async function startHttp({ port, host }) { // session -> { server, transport } 映射 const sessions = new Map(); + closeAllSessions = () => { + for (const { server, transport } of sessions.values()) { + try { + transport.close(); + } catch {} + try { + server.close(); + } catch {} + } + sessions.clear(); + // 掰掉未关闭的 SSE / keep-alive 连接,否则 httpServer.close() 回调不会触发 + httpServer?.closeAllConnections?.(); + }; + app.get("/health", (_req, res) => { res.json({ status: "ok", service: "video_gen", sessions: sessions.size }); }); @@ -431,7 +465,7 @@ async function startHttp({ port, host }) { app.get("/mcp", handleOther); app.delete("/mcp", handleOther); - app.listen(port, host, () => { + httpServer = app.listen(port, host, () => { console.log( `[video_gen] MCP HTTP server listening on http://${host}:${port}/mcp` ); diff --git a/mcp/web_search/server.js b/mcp/web_search/server.js index 5d3b0d7..7bab7ed 100644 --- a/mcp/web_search/server.js +++ b/mcp/web_search/server.js @@ -18,6 +18,26 @@ import { createServer } from 'node:http'; import { randomUUID } from 'node:crypto'; import { SERVER_NAME, VERSION, dispatch } from './mcp.js'; +// ── 优雅退出 ──────────────────────────────────────────────────────────────── +// 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 +// 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 +// 显式注册处理器立即关服务;3s 兜底定时器防止长连接卡住 close 回调。 +let httpServer = null; +let forceCloseConnections = () => {}; +let shuttingDown = false; + +function shutdown(sig) { + if (shuttingDown) return; + shuttingDown = true; + process.stdout.write(`[web_search] 收到 ${sig},停止服务\n`); + forceCloseConnections(); + if (httpServer === null) process.exit(0); // stdio 模式无监听,直接退 + httpServer.close(() => process.exit(0)); + setTimeout(() => process.exit(0), 3000).unref(); +} +process.on('SIGTERM', () => shutdown('SIGTERM')); +process.on('SIGINT', () => shutdown('SIGINT')); + // ── stdio 传输(默认)─────────────────────────────────────────────────────── function runStdio() { const rl = createInterface({ input: process.stdin, crlfDelay: Infinity }); @@ -107,6 +127,14 @@ function runHttp(host, port) { })); }); + httpServer = server; + forceCloseConnections = () => { + // 掐掉老式 SSE 长连接与 keep-alive 连接,否则 server.close() 回调不会触发 + for (const res of sseChannels.values()) res.destroy(); + sseChannels.clear(); + server.closeAllConnections?.(); + }; + server.listen(port, host, () => { process.stdout.write(`[web_search] HTTP/SSE listening on http://${host}:${port} (MCP: POST /, GET /sse + POST /messages)\n`); }); From d799c4f47f4b7ae941753dac777877b05a060473 Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 23 Sep 2026 08:29:54 +0800 Subject: [PATCH 31/41] =?UTF-8?q?=E6=94=B9=E5=90=8D=EF=BC=9Avideo=5Fgen=20?= =?UTF-8?q?=E2=86=92=20video=5Ftask=EF=BC=88=E5=8F=8C=E5=B7=A5=E5=85=B7?= =?UTF-8?q?=E5=90=88=E5=B9=B6=E4=B8=BA=E5=8D=95=E5=B7=A5=E5=85=B7=EF=BC=8C?= =?UTF-8?q?op=3Dcreate/get=EF=BC=89=EF=BC=9Bimage=5Fgen=20=E2=86=92=20imag?= =?UTF-8?q?e=5Ftask=EF=BC=88=E5=8D=95=E5=B7=A5=E5=85=B7=EF=BC=8Cop=3Dcreat?= =?UTF-8?q?e=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - header 前缀同步改为 X-Video-Task-* / X-Image-Task-*(方案 B,agent 侧 config.yml 的 headers 需同步更新) - docker-compose 服务名 / 容器名 / 调试端口变量(VIDEO_TASK_PORT / IMAGE_TASK_PORT)同步改名 - README(根目录与两份服务文档)按新工具形态重写:op 参数表、curl 示例、架构图 --- mcp/README.md | 18 +- mcp/docker-compose.yml | 16 +- mcp/{image_gen => image_task}/.dockerignore | 0 mcp/{image_gen => image_task}/Dockerfile | 2 +- mcp/{image_gen => image_task}/README.md | 64 +-- mcp/{image_gen => image_task}/package.json | 4 +- .../src/mcp-server.js | 137 ++++--- mcp/{video_gen => video_task}/.dockerignore | 0 mcp/{video_gen => video_task}/Dockerfile | 4 +- mcp/{video_gen => video_task}/README.md | 127 +++--- mcp/{video_gen => video_task}/package.json | 4 +- .../src/mcp-server.js | 368 +++++++++--------- 12 files changed, 389 insertions(+), 355 deletions(-) rename mcp/{image_gen => image_task}/.dockerignore (100%) rename mcp/{image_gen => image_task}/Dockerfile (92%) rename mcp/{image_gen => image_task}/README.md (75%) rename mcp/{image_gen => image_task}/package.json (79%) rename mcp/{image_gen => image_task}/src/mcp-server.js (72%) rename mcp/{video_gen => video_task}/.dockerignore (100%) rename mcp/{video_gen => video_task}/Dockerfile (92%) rename mcp/{video_gen => video_task}/README.md (75%) rename mcp/{video_gen => video_task}/package.json (60%) rename mcp/{video_gen => video_task}/src/mcp-server.js (58%) diff --git a/mcp/README.md b/mcp/README.md index 2e67333..cfa8e55 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -5,8 +5,8 @@ | 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 | |---|---|---|---|---| | `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` | -| `image_gen/` | `mcp_image_gen` | 智谱 CogView 图片生成 | `3000` | `POST /mcp` | -| `video_gen/` | `mcp_video_gen` | 智谱 CogVideo 视频生成(异步) | `3000` | `POST /mcp` | +| `image_task/` | `mcp_image_task` | 智谱 CogView 图片生成(单工具 op=create) | `3000` | `POST /mcp` | +| `video_task/` | `mcp_video_task` | 智谱 CogVideo 视频生成(异步,单工具 op=create/get) | `3000` | `POST /mcp` | **这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor` 按容器名访问。所以整台服务器对外只需要开 agent-core 那一个端口(`AGENT_PORT`,默认 8090)。 @@ -27,7 +27,7 @@ cd /root/workspace/tools/mcp && docker compose up -d --build > mcp 单独在一个没有该网络的机器上先起会报错(`network agent-mcp-net declared as external, but could not be found`),这是预期行为。 > 拆的时候反着来(先 down mcp 再 down agent)。 -`image_gen` / `video_gen` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 +`image_task` / `video_task` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 (agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥。 ### 环境变量 @@ -37,10 +37,10 @@ cd /root/workspace/tools/mcp && docker compose up -d --build | 变量 | 默认 | 说明 | |---|---|---| | `WEB_SEARCH_PORT` | `8081` | 只在临时打开 web_search 调试端口时用 | -| `IMAGE_GEN_PORT` | `8082` | 只在临时打开 image_gen 调试端口时用 | -| `VIDEO_GEN_PORT` | `8083` | 只在临时打开 video_gen 调试端口(MCP 口,仅本机短时调试)时用 | +| `IMAGE_TASK_PORT` | `8082` | 只在临时打开 image_task 调试端口时用 | +| `VIDEO_TASK_PORT` | `8083` | 只在临时打开 video_task 调试端口(MCP 口,仅本机短时调试)时用 | -## 图片是怎么到智谱手上的(只有 video_gen 关心) +## 图片是怎么到智谱手上的(只有 video_task 关心) 智谱服务器生成视频前要**自己来拉参考图**,它不带 cookie、不带 `Authorization`。这套链路里**没有任何人上传文件**: @@ -48,7 +48,7 @@ cd /root/workspace/tools/mcp && docker compose up -d --build AI ──调用 agent 内置的「公开临时 URL」工具(直接传文件路径)──► 拿到一条短命公网 URL │ ▼ -AI 把拿到的 URL 当 image_url 交给 video_gen:3000/mcp +AI 把拿到的 URL 当 image_url 交给 video_task:3000/mcp │ ▼ 智谱 ──匿名 GET──► agent 侧提供的公开临时 URL @@ -64,8 +64,8 @@ AI 把拿到的 URL 当 image_url 交给 video_gen:3000/mcp | 服务 | 公网暴露 | 说明 | |---|---|---| | `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | -| `mcp_image_gen` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | -| `mcp_video_gen` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 | +| `mcp_image_task` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | +| `mcp_video_task` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 | ## 单独调试 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index ecb9a2e..e503405 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -12,23 +12,23 @@ services: networks: - agent-mcp-net - mcp_image_gen: - build: ./image_gen - container_name: mcp_image_gen + mcp_image_task: + build: ./image_task + container_name: mcp_image_task restart: unless-stopped # 调试用(默认关): # ports: - # - "${IMAGE_GEN_PORT:-8082}:3000" + # - "${IMAGE_TASK_PORT:-8082}:3000" networks: - agent-mcp-net - mcp_video_gen: - build: ./video_gen - container_name: mcp_video_gen + mcp_video_task: + build: ./video_task + container_name: mcp_video_task restart: unless-stopped # 调试用(默认关;这里映的是 MCP 端口,会暴露 /mcp,仅本机短时调试用): # ports: - # - "${VIDEO_GEN_PORT:-8083}:3000" + # - "${VIDEO_TASK_PORT:-8083}:3000" networks: - agent-mcp-net diff --git a/mcp/image_gen/.dockerignore b/mcp/image_task/.dockerignore similarity index 100% rename from mcp/image_gen/.dockerignore rename to mcp/image_task/.dockerignore diff --git a/mcp/image_gen/Dockerfile b/mcp/image_task/Dockerfile similarity index 92% rename from mcp/image_gen/Dockerfile rename to mcp/image_task/Dockerfile index 449aca1..324ba3c 100644 --- a/mcp/image_gen/Dockerfile +++ b/mcp/image_task/Dockerfile @@ -3,7 +3,7 @@ FROM node:22-slim WORKDIR /app # 国内构建慢:npm 默认源在国外(web_search 零依赖不需要,这个要)。 -# 想换回官方:docker compose build --build-arg NPM_REGISTRY=https://registry.npmjs.org/ mcp_image_gen +# 想换回官方:docker compose build --build-arg NPM_REGISTRY=https://registry.npmjs.org/ mcp_image_task ARG NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ # 复制 package.json 并安装依赖 diff --git a/mcp/image_gen/README.md b/mcp/image_task/README.md similarity index 75% rename from mcp/image_gen/README.md rename to mcp/image_task/README.md index cb81c02..cd4f17e 100644 --- a/mcp/image_gen/README.md +++ b/mcp/image_task/README.md @@ -1,6 +1,6 @@ -# MCP Image Gen +# MCP Image Task -一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成服务,对接智谱 BigModel 的 `CogView` 系列模型。每次调用通过 HTTP header 传入智谱 API 的 Bearer Token,支持在工具参数中按需切换模型。 +一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成服务,对接智谱 BigModel 的 `CogView` 系列模型。每次调用通过 HTTP header 传入智谱 API 的 Bearer Token。只有一个工具 `image_task`,用 `op` 区分动作(图片生成为同步接口,当前仅支持 `op=create`)。 - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - 上游:[智谱 BigModel Images Generations API](https://open.bigmodel.cn/dev/api#images) @@ -18,17 +18,17 @@ ```bash cd /root/workspace/tools/mcp -docker compose up -d --build mcp_image_gen +docker compose up -d --build mcp_image_task ``` -服务容器名 `mcp_image_gen`,容器内端口 3000,**默认不占宿主端口**:agent 走 `agent-mcp-net` -按容器名访问(`http://mcp_image_gen:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 -`docker-compose.yml` 把 `mcp_image_gen` 注释掉的 `ports` 两行打开(默认写的是 8082),调试完记得注释回去。 +服务容器名 `mcp_image_task`,容器内端口 3000,**默认不占宿主端口**:agent 走 `agent-mcp-net` +按容器名访问(`http://mcp_image_task:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 +`docker-compose.yml` 把 `mcp_image_task` 注释掉的 `ports` 两行打开(默认写的是 8082),调试完记得注释回去。 ```bash # 不占端口的健康检查 -docker exec mcp_image_gen node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" -# {"status":"ok","service":"image_gen","sessions":0} +docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" +# {"status":"ok","service":"image_task","sessions":0} ``` ### MCP 客户端配置 @@ -40,7 +40,7 @@ docker exec mcp_image_gen node -e "fetch('http://localhost:3000/health').then(r= // Cursor: ~/.cursor/mcp.json { "mcpServers": { - "image_gen": { + "image_task": { "url": "http://localhost:8082/mcp", "headers": { "Authorization": "Bearer " @@ -60,16 +60,21 @@ docker exec mcp_image_gen node -e "fetch('http://localhost:3000/health').then(r= --- -## 工具:image_gen +## 工具:image_task -调用智谱图片生成接口,返回图片 URL。 +调用智谱图片生成接口,返回图片 URL。生成为**同步**接口,`op=create` 直接出结果,无需轮询。 -### 参数 +| op | 作用 | 同步/异步 | +|---|---|---| +| `create` | 按 prompt 生成图片,返回图片 URL | 同步(直接返回结果) | + +### 参数(AI 可见) | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| -| `prompt` | string | ✅ | 图片生成提示词,描述想要的画面内容 | -| `size` | string | ❌ | 图片尺寸,例如 `1024x1024`、`1280x1280`、`1024x1792`、`1792x1024`、`768x1344`、`1344x768`,遵循智谱 API 规格 | +| `op` | `"create"` | ✅ | 要执行的操作(当前仅 `create`) | +| `prompt` | string | ✅ | 图片生成提示词,描述想要的画面内容(仅 op=create 使用) | +| `size` | string | ❌ | 图片尺寸,例如 `1024x1024`、`1280x1280`、`1024x1792`、`1792x1024`、`768x1344`、`1344x768`,遵循智谱 API 规格(仅 op=create 使用) | ### Model 控制(不在工具参数中暴露) @@ -77,7 +82,7 @@ docker exec mcp_image_gen node -e "fetch('http://localhost:3000/health').then(r= | 优先级 | Header | |---|---| -| 1 | `X-Image-Gen-Model` | +| 1 | `X-Image-Task-Model` | | 2 | `X-Mcp-Model` | | 3 | `X-Model` | @@ -87,14 +92,12 @@ docker exec mcp_image_gen node -e "fetch('http://localhost:3000/health').then(r= ### 返回 -### 返回 - 工具成功时返回若干 `text` 块,第一块是摘要,后续每块各包含一张图片的 URL(方便 LLM 直接贴图或下载): ```jsonc { "content": [ - { "type": "text", "text": "模型: CogView-3-Flash\n提示词: ...\n图片 1: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." }, + { "type": "text", "text": "Model: CogView-3-Flash\nPrompt: ...\nImage 1: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." }, { "type": "text", "text": "https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." } ] } @@ -112,7 +115,7 @@ URL 由智谱签名下发,**带有效期**(通常 24h),如需长期保 | 优先级 | Header | 说明 | |---|---|---| -| 1 | `X-Image-Gen-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | +| 1 | `X-Image-Task-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | | 2 | `X-Mcp-Token: ` | 通用兜底 | | 3 | `Authorization: Bearer ` | 标准 OAuth 风格(排最后是为避免误用) | @@ -170,7 +173,7 @@ curl -s -X POST http://localhost:8082/mcp \ -H "Mcp-Session-Id: $SESSION" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' -# 4. 调 image_gen +# 4. 调 image_task(op=create) curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ @@ -181,8 +184,9 @@ curl -s -X POST http://localhost:8082/mcp \ "id": 3, "method": "tools/call", "params": { - "name": "image_gen", + "name": "image_task", "arguments": { + "op": "create", "prompt": "一只可爱的小猫咪,坐在阳光明媚的窗台上,背景是蓝天白云", "size": "1280x1280" } @@ -197,20 +201,21 @@ curl -s -X POST http://localhost:8082/mcp \ ## 架构与文件 ``` -image_gen/ +image_task/ ├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server ├── .dockerignore # 排除 node_modules ├── package.json # @modelcontextprotocol/sdk + express + zod ├── README.md # 本文件 └── src/ - └── mcp-server.js # 单文件实现:HTTP server + MCP transport + tool + └── mcp-server.js # 单文件实现:HTTP server + MCP transport + 单工具(op 分发) ``` ### 关键设计 +- **单工具 + `op` 分发**:`image_task(op=create)`,与 `video_task` 的服务形态保持一致;生成为同步接口,所以 `op` 只有 `create` 一个取值 - **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用,避免每请求重建 -- **Token 闭包注入**:在 Express 入口处从 header 提取 token,闭包传给 `buildServer({ token })`,tool 回调里直接使用;不依赖 SDK 内部字段 -- **模型参数单链**:`arguments.model` → `DEFAULT_MODEL`,无 header 干预 +- **Token 闭包注入**:在 Express 入口处从 header 提取 token,闭包传给 tool 回调;不依赖 SDK 内部字段 +- **模型参数不入 schema**:model 只从 HTTP header 读取(`X-Image-Task-Model` / `X-Mcp-Model` / `X-Model`),AI 不可见 - **URL 提取**:`response.data[].url` 为准,若返回 `b64_json` 也会一并返回 ### 默认模型 @@ -220,18 +225,21 @@ image_gen/ const DEFAULT_MODEL = "CogView-3-Flash"; ``` -修改后 `docker compose up -d --build mcp_image_gen` 即可生效。 +修改后 `docker compose up -d --build mcp_image_task` 即可生效。 --- ## 常见问题 **Q: AI 不知道有哪些 model 可选,怎么办?** -A: 这是设计意图。模型选择属于路由策略,不让 AI 决策。调用方在 HTTP header `X-Image-Gen-Model` 里注入即可。 +A: 这是设计意图。模型选择属于路由策略,不让 AI 决策。调用方在 HTTP header `X-Image-Task-Model` 里注入即可。 **Q: 换模型需要重连 MCP session 吗?** A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取,不需要重建 session。 +**Q: 为什么 op 只有 create?** +A: 图片生成是同步接口,`op=create` 直接返回结果,不存在需要轮询的异步任务。保留 `op` 参数是为了与 `video_task` 等异步任务型服务形态一致;将来若上游出现异步接口再加 `get`。 + **Q: 为什么 Model 优先级不是「工具参数 > header」?** A: 因为我们故意不在 schema 暴露 model 参数,AI 根本不会传 model,所以「工具参数 > header」这条分支实际上不存在。 @@ -245,4 +253,4 @@ A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize A: 智谱签发 URL 默认 24h 左右,详见响应里的 `Expires` 参数。需要长期使用请自行转存到 OSS/S3。 **Q: 能否限制 `size` 白名单?** -A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `image_gen` 的 `size` schema 即可。 +A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `image_task` 的 `size` schema 即可。 diff --git a/mcp/image_gen/package.json b/mcp/image_task/package.json similarity index 79% rename from mcp/image_gen/package.json rename to mcp/image_task/package.json index 1b68546..f172c50 100644 --- a/mcp/image_gen/package.json +++ b/mcp/image_task/package.json @@ -1,7 +1,7 @@ { - "name": "mcp_image_gen", + "name": "mcp_image_task", "version": "1.0.0", - "description": "MCP server for image generation via Zhipu BigModel CogView-3-Flash", + "description": "MCP server for image generation via Zhipu BigModel CogView (single tool image_task with op=create)", "type": "module", "main": "src/mcp-server.js", "scripts": { diff --git a/mcp/image_gen/src/mcp-server.js b/mcp/image_task/src/mcp-server.js similarity index 72% rename from mcp/image_gen/src/mcp-server.js rename to mcp/image_task/src/mcp-server.js index 4c8903a..4a02b0a 100644 --- a/mcp/image_gen/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -13,7 +13,7 @@ const DEFAULT_MODEL = "CogView-3-Flash"; // ── 优雅退出 ────────────────────────────────────────────────────────────── // 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 // 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 -// 显式注册处理器,关闭 MCP session 与长连接后立即退出;3s 定时器为兑底。 +// 显式注册处理器,关闭 MCP session 与长连接后立即退出;3s 定时器为兜底。 let httpServer = null; let closeAllSessions = () => {}; let shuttingDown = false; @@ -21,7 +21,7 @@ let shuttingDown = false; function shutdown(sig) { if (shuttingDown) return; shuttingDown = true; - console.log(`[image_gen] 收到 ${sig},停止服务`); + console.log(`[image] received ${sig}, shutting down`); closeAllSessions(); if (!httpServer) process.exit(0); // stdio 模式无监听,直接退 httpServer.close(() => process.exit(0)); @@ -48,7 +48,7 @@ function parseArgs(argv) { function pickToken(headers) { if (!headers) return null; const candidates = [ - headers["x-image-gen-token"], + headers["x-image-task-token"], headers["x-mcp-token"], headers["authorization"], ]; @@ -69,7 +69,7 @@ function pickToken(headers) { function pickModel(headers) { if (!headers) return null; const v = - headers["x-image-gen-model"] || + headers["x-image-task-model"] || headers["x-mcp-model"] || headers["x-model"]; if (!v) return null; @@ -117,10 +117,64 @@ function extractUrls(data) { return []; } +// ===== op=create:提交图片生成(同步,直接返回图片 URL)===== +async function handleCreate({ args, headers, token }) { + // model 完全由 HTTP header 控制(X-Image-Task-Model / X-Mcp-Model / X-Model), + // 不存进 session,每次从本次请求的 header 读取,未设置则用默认 CogView-3-Flash。 + // AI 看不到 model 参数(schema 中已删除),避免其误传。 + const model = pickModel(headers) || DEFAULT_MODEL; + const size = args.size; + + try { + const data = await callZhipuImagesGenerations({ + token, + model, + prompt: args.prompt, + size, + }); + const urls = extractUrls(data); + if (urls.length === 0) { + return { + isError: true, + content: [ + { + type: "text", + text: `Returned no image URL. Raw response: ${JSON.stringify(data)}`, + }, + ], + }; + } + const summary = urls + .map((u, i) => `Image ${i + 1}: ${u}`) + .join("\n"); + return { + content: [ + { + type: "text", + text: `Model: ${model}\nPrompt: ${args.prompt}\n${summary}`, + }, + ...urls.map((u) => ({ type: "text", text: u })), + ], + }; + } catch (e) { + return { + isError: true, + content: [ + { + type: "text", + text: `Failed to generate image: ${e.message}${ + e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : "" + }`, + }, + ], + }; + } +} + function buildServer() { const server = new McpServer( { - name: "image_gen", + name: "image_task", version: "1.0.0", }, { @@ -131,18 +185,27 @@ function buildServer() { ); server.tool( - "image_gen", - "Generate an image from a prompt and return the image URL. Optionally specify size.", + "image_task", + `Manages image generation. Generation is synchronous: op=create returns the image URLs directly. + +op=create Generate an image from a prompt. Requires prompt; optional size.`, { + op: z + .enum(["create"]) + .describe( + 'Operation to perform. Only "create" is supported (generation is synchronous, so there is no task to poll).' + ), prompt: z .string() .min(1) - .describe("Image generation prompt; describe the desired scene in detail."), + .describe( + "Image generation prompt; describe the desired scene in detail. Used with op=create." + ), size: z .string() .optional() .describe( - "Image size, Preferred sizes: 1024x1024, 1280x1280, 1536x1024, 1024x1536, Each side must be a multiple of 32." + "Image size, Preferred sizes: 1024x1024, 1280x1280, 1536x1024, 1024x1536, Each side must be a multiple of 32. Used with op=create." ), }, async (args, extra) => { @@ -163,55 +226,19 @@ function buildServer() { }; } - // model 完全由 HTTP header 控制(X-Image-Gen-Model / X-Mcp-Model / X-Model), - // 不存进 session,每次从本次请求的 header 读取,未设置则用默认 CogView-3-Flash。 - // AI 看不到 model 参数(schema 中已删除),避免其误传。 - const model = pickModel(headers) || DEFAULT_MODEL; - const size = args.size; - - try { - const data = await callZhipuImagesGenerations({ - token, - model, - prompt: args.prompt, - size, - }); - const urls = extractUrls(data); - if (urls.length === 0) { + switch (args.op) { + case "create": + return await handleCreate({ args, headers, token }); + default: return { isError: true, content: [ { type: "text", - text: `Returned no image URL. Raw response: ${JSON.stringify(data)}`, + text: `Unknown op "${args.op}" (available: create).`, }, ], }; - } - const summary = urls - .map((u, i) => `Image ${i + 1}: ${u}`) - .join("\n"); - return { - content: [ - { - type: "text", - text: `Model: ${model}\nPrompt: ${args.prompt}\n${summary}`, - }, - ...urls.map((u) => ({ type: "text", text: u })), - ], - }; - } catch (e) { - return { - isError: true, - content: [ - { - type: "text", - text: `Failed to generate image: ${e.message}${ - e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : "" - }`, - }, - ], - }; } } ); @@ -241,7 +268,7 @@ async function startHttp({ port, host }) { }; app.get("/health", (_req, res) => { - res.json({ status: "ok", service: "image_gen", sessions: sessions.size }); + res.json({ status: "ok", service: "image_task", sessions: sessions.size }); }); async function handleSessionRequest(req, res) { @@ -304,7 +331,7 @@ async function startHttp({ port, host }) { httpServer = app.listen(port, host, () => { console.log( - `[image_gen] MCP HTTP server listening on http://${host}:${port}/mcp` + `[image] MCP HTTP server listening on http://${host}:${port}/mcp` ); }); } @@ -317,18 +344,18 @@ async function startStdio() { ); const transport = new StdioServerTransport(); await server.connect(transport); - console.error("[image_gen] MCP stdio server started"); + console.error("[image] 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("[image_gen] failed to start http server:", e); + console.error("[image] failed to start http server:", e); process.exit(1); }); } else { startStdio().catch((e) => { - console.error("[image_gen] failed to start stdio server:", e); + console.error("[image] failed to start stdio server:", e); process.exit(1); }); } diff --git a/mcp/video_gen/.dockerignore b/mcp/video_task/.dockerignore similarity index 100% rename from mcp/video_gen/.dockerignore rename to mcp/video_task/.dockerignore diff --git a/mcp/video_gen/Dockerfile b/mcp/video_task/Dockerfile similarity index 92% rename from mcp/video_gen/Dockerfile rename to mcp/video_task/Dockerfile index 3f59400..b15f6ad 100644 --- a/mcp/video_gen/Dockerfile +++ b/mcp/video_task/Dockerfile @@ -3,7 +3,7 @@ FROM node:22-slim WORKDIR /app # 国内构建慢:npm 默认源在国外。想换回官方: -# docker compose build --build-arg NPM_REGISTRY=https://registry.npmjs.org/ mcp_video_gen +# docker compose build --build-arg NPM_REGISTRY=https://registry.npmjs.org/ mcp_video_task ARG NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ # 复制 package.json 并安装依赖 @@ -16,4 +16,4 @@ COPY . . EXPOSE 3000 # HTTP 模式:只提供 MCP(/mcp)与 /health;容器外不映射,只在 agent-mcp-net 内被 agent 访问。 -CMD ["node", "src/mcp-server.js", "--http", "--port", "3000", "--host", "0.0.0.0"] \ No newline at end of file +CMD ["node", "src/mcp-server.js", "--http", "--port", "3000", "--host", "0.0.0.0"] diff --git a/mcp/video_gen/README.md b/mcp/video_task/README.md similarity index 75% rename from mcp/video_gen/README.md rename to mcp/video_task/README.md index d6c116d..083ba66 100644 --- a/mcp/video_gen/README.md +++ b/mcp/video_task/README.md @@ -1,6 +1,6 @@ -# MCP Video Gen +# MCP Video Task -基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的视频生成服务,对接智谱 BigModel 的视频生成**异步**接口,支持**文生视频**和**图生视频**。Server 只负责提交任务 + 单次查询结果,**不内部轮询**——AI 拿到 `task_id` 后自己决定什么时候调用 `query_video` 复查。 +基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的视频生成服务,对接智谱 BigModel 的视频生成**异步**接口,支持**文生视频**和**图生视频**。只有一个工具 `video_task`,用 `op` 区分动作:`op=create` 提交任务、`op=get` 单次查询结果。Server **不内部轮询**——AI 拿到 `task_id` 后自己决定什么时候用 `op="get"` 复查。 - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - 上游:[智谱 BigModel 视频生成(异步)](https://docs.bigmodel.cn/api-reference/模型-api/视频生成异步) + [查询异步结果](https://docs.bigmodel.cn/api-reference/模型-api/查询异步结果) @@ -19,17 +19,17 @@ ```bash cd /root/workspace/tools/mcp -docker compose up -d --build mcp_video_gen +docker compose up -d --build mcp_video_task ``` -服务容器名 `mcp_video_gen`,**默认不占宿主机端口**:由 agent 走 `agent-mcp-net` 按容器名访问 -(`http://mcp_video_gen:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 `docker-compose.yml` -把 `mcp_video_gen` 注释掉的 `ports` 两行打开(映的是 MCP 端口 3000,仅本机短时调试用)。 +服务容器名 `mcp_video_task`,**默认不占宿主机端口**:由 agent 走 `agent-mcp-net` 按容器名访问 +(`http://mcp_video_task:3000/mcp`)。需要从宿主机 curl 调试时,去仓库根 `docker-compose.yml` +把 `mcp_video_task` 注释掉的 `ports` 两行打开(映的是 MCP 端口 3000,仅本机短时调试用)。 ```bash # 容器内健康检查(无需占端口) -docker exec mcp_video_gen node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" -# {"status":"ok","service":"video_gen","sessions":0} +docker exec mcp_video_task node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" +# {"status":"ok","service":"video_task","sessions":0} ``` > 下文 curl 示例里的 `localhost:8083` 均指“临时打开了调试端口”的情形。 @@ -43,7 +43,7 @@ docker exec mcp_video_gen node -e "fetch('http://localhost:3000/health').then(r= // Cursor: ~/.cursor/mcp.json { "mcpServers": { - "video_gen": { + "video_task": { "url": "http://localhost:8083/mcp", "headers": { "Authorization": "Bearer " @@ -59,77 +59,51 @@ docker exec mcp_video_gen node -e "fetch('http://localhost:3000/health').then(r= --- -## 工具一览 +## 工具:video_task -| 工具 | 作用 | 同步/异步 | +单个工具,`op` 必填,只有两个取值: + +| op | 作用 | 同步/异步 | |---|---|---| -| `video_gen` | 提交一个视频生成任务,立刻返回 `task_id` | 同步(仅提交) | -| `query_video` | 用 `task_id` 拉一次当前结果 | 同步(单次查询,不轮询) | - ---- - - -## 本地文件 → 公网 URL(本服务不搬字节) - -`image_url` 必须是一个**公网可达**的 URL(智谱服务器会自己去拉)。图片在本地盘上时,本服务不负责上传: -agent 侧已集成为一个 **tool**,AI 直接传文件路径就能拿到一条公开临时 URL,拿来填 `image_url` 即可, -不需要 curl 任何地址、不需要任何配置。 - -- 文件始终躺在 agent 的任务目录里,零拷贝;链接短命、到期或 agent 重启后失效。 -- 智谱只在提交任务那一刻拉一次图,短命链接完全够用。 - ---- - -## 工具:video_gen - -提交一个视频生成任务,支持**文生视频**和**图生视频**。`prompt` 为**必填**;图生视频另传 `image_url`(两者都传也行,此时 prompt 会附加为运动/动作描述)。 +| `create` | 提交一个视频生成任务,立刻返回 `task_id` | 同步(仅提交) | +| `get` | 用 `task_id` 拉一次当前结果 | 同步(单次查询,不轮询) | ### 参数(AI 可见) | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| -| `prompt` | string | ✅ | 视频文本描述,最大 512 字符 | +| `op` | `"create"` \| `"get"` | ✅ | 要执行的操作 | +| `prompt` | string | op=create 时与 `image_url` 二选一 | 视频文本描述,最大 512 字符;与 `image_url` 同传时作为运动/动作描述 | | `image_url` | string (URL) | ❌ | 参考图 URL(**单张**,不支持数组 / 多张 / 首尾帧)。图片 ≤ 5MB,格式 png/jpeg/jpg。本地文件请先用 agent 内置的公开临时 URL 工具换成公网链接(上一节) | -| `with_audio` | boolean | ❌ | 是否生成 AI 音效,默认 `false` | +| `with_audio` | boolean | ❌ | 是否生成 AI 音效,默认 `false`(仅 op=create 使用) | +| `task_id` | string | op=get 时必填 | `op=create` 返回的 `id` | ### 服务端 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-Watermark` | bool | `true` | 是否添加 AI 水印;关闭需先在智谱后台签署免责声明 | +| `X-Video-Task-Model` / `X-Mcp-Model` / `X-Model` | string | `cogvideox-flash` | 覆盖模型 | +| `X-Video-Task-Quality` | string | `speed` | `speed`(速度优先)或 `quality`(质量优先) | +| `X-Video-Task-Fps` | int | `30` | `30` 或 `60` | +| `X-Video-Task-Watermark` | bool | `true` | 是否添加 AI 水印;关闭需先在智谱后台签署免责声明 | -模型名串识别顺序(首个非空值生效):`X-Video-Gen-Model` → `X-Mcp-Model` → `X-Model` → 默认。 +模型名串识别顺序(首个非空值生效):`X-Video-Task-Model` → `X-Mcp-Model` → `X-Model` → 默认。 -### 返回 +### 返回(op=create) -工具立刻返回智谱提交结果: +立刻返回智谱提交结果: ```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." } + { "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 this tool again with op=\"get\" and task_id=\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\" to fetch the result." } ] } ``` `task_status` 通常为 `PROCESSING`,极少数情况下可能直接 `SUCCESS`(极快完成的短任务)。 ---- - -## 工具:query_video - -根据 `task_id` 拉一次智谱异步结果。**不内部轮询**——AI 自己决定调几次、调多频。 - -### 参数(AI 可见) - -| 名称 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `task_id` | string | ✅ | `video_gen` 返回的 `id` | - -### 返回 +### 返回(op=get) - **`SUCCESS`**:返回 `Video URL`(智谱签名 URL,**24h 左右有效**,需及时转存),外加一张 `Cover` 封面图: ```jsonc @@ -145,13 +119,24 @@ agent 侧已集成为一个 **tool**,AI 直接传文件路径就能拿到一 --- +## 本地文件 → 公网 URL(本服务不搬字节) + +`image_url` 必须是一个**公网可达**的 URL(智谱服务器会自己去拉)。图片在本地盘上时,本服务不负责上传: +agent 侧已集成为一个 **tool**,AI 直接传文件路径就能拿到一条公开临时 URL,拿来填 `image_url` 即可, +不需要 curl 任何地址、不需要任何配置。 + +- 文件始终躺在 agent 的任务目录里,零拷贝;链接短命、到期或 agent 重启后失效。 +- 智谱只在提交任务那一刻拉一次图,短命链接完全够用。 + +--- + ## 鉴权细节 每个 HTTP 请求必须携带智谱 API Token,server 从以下 header 字段按顺序识别,**首个非空值生效**: | 优先级 | Header | 说明 | |---|---|---| -| 1 | `X-Video-Gen-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | +| 1 | `X-Video-Task-Token: ` | 直传,避免与客户端自身的 Authorization 冲突 | | 2 | `X-Mcp-Token: ` | 通用兜底 | | 3 | `Authorization: Bearer ` | 标准 OAuth 风格(排最后是为避免误用) | @@ -171,9 +156,9 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 ``` 1. 如果手头是【本地文件】:先调用 agent 内置的「公开临时 URL」工具拿到一条公网链接(上一节),再进第 2 步 -2. 调用 video_gen({ prompt, image_url?, with_audio? }) +2. 调用 video_task({ op: "create", prompt, image_url?, with_audio? }) 3. 拿到 task_id → 等待若干秒(建议 2~5 秒) -4. 调用 query_video({ task_id }) +4. 调用 video_task({ op: "get", task_id }) - 若 PROCESSING → 等一会再调 - 若 SUCCESS → 拿到 video URL,贴给用户 / 下载 / 二次编辑 - 若 FAIL → 展示错误信息,结束 @@ -225,7 +210,7 @@ curl -s -X POST http://localhost:8083/mcp \ -H "Mcp-Session-Id: $SESSION" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' -# 4. 提交文生视频任务 +# 4. 提交文生视频任务(op=create) curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ @@ -236,15 +221,16 @@ curl -s -X POST http://localhost:8083/mcp \ "id": 3, "method": "tools/call", "params": { - "name": "video_gen", + "name": "video_task", "arguments": { + "op": "create", "prompt": "A cat is playing with a ball.", "with_audio": true } } }' -# 5. 查结果(替换下面的 ) +# 5. 查结果(op=get,替换下面的 ) curl -s -X POST http://localhost:8083/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ @@ -255,8 +241,8 @@ curl -s -X POST http://localhost:8083/mcp \ "id": 4, "method": "tools/call", "params": { - "name": "query_video", - "arguments": { "task_id": "" } + "name": "video_task", + "arguments": { "op": "get", "task_id": "" } } }' ``` @@ -266,23 +252,24 @@ curl -s -X POST http://localhost:8083/mcp \ ## 架构与文件 ``` -video_gen/ +video_task/ ├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server ├── .dockerignore # 排除 node_modules -package.json # @modelcontextprotocol/sdk + express + multer +package.json # @modelcontextprotocol/sdk + express ├── README.md # 本文件 └── src/ - └── mcp-server.js # 单文件实现:HTTP server + MCP transport + 双工具 + └── mcp-server.js # 单文件实现:HTTP server + MCP transport + 单工具(op 分发) ``` ### 关键设计 +- **单工具 + `op` 分发**:`video_task(op=create|get)` 替代原来的 `video_gen` + `query_video` 双工具,AI 面对的工具面更小,参数按 op 在 handler 侧校验 - **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用,避免每请求重建 - **Token 闭包注入**:在 Express 入口处从 header 提取 token,闭包传给 tool 回调;不依赖 SDK 内部字段 - **AI 可见 vs AI 不可见**: - - AI 只看到 `prompt / image_url / with_audio` + - AI 只看到 `op / prompt / image_url / with_audio / task_id` - `model / quality / fps / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档 -- **异步语义暴露给 AI**:服务端不做轮询,`video_gen` 只提交、`query_video` 只查一次。AI 自主决定节奏 +- **异步语义暴露给 AI**:服务端不做轮询,`op=create` 只提交、`op=get` 只查一次。AI 自主决定节奏 - **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI - **不搬字节**:本地文件 -> 公网 URL 完全由 agent 侧集成的「公开临时 URL」工具完成,本服务不参与;所以本体不加任何写入口、不落盘、不需要额外端口 - **链接短命**:公开临时 URL 到期或 agent 重启后失效;智谱只需在提交任务那一刻拉一次图 @@ -294,13 +281,13 @@ package.json # @modelcontextprotocol/sdk + express + multer const DEFAULT_MODEL = "cogvideox-flash"; ``` -修改后 `docker compose up -d --build mcp_video_gen` 即可生效。 +修改后 `docker compose up -d --build mcp_video_task` 即可生效。 --- ## 常见问题 -**Q: AI 拿到 task_id 后立刻调 query_video 一直 PROCESSING,怎么办?** +**Q: AI 拿到 task_id 后立刻 op=get 一直 PROCESSING,怎么办?** A: AI 自己 sleep 几秒再调(建议 2~5 秒间隔)。这是设计取舍:把节奏控制权交给 AI 模型,而不是服务端硬编码超时。 **Q: 视频 URL 多久过期?** @@ -319,4 +306,4 @@ A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。 A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。 **Q: 上传的图片多久过期?** -A: 本服务不存图,不存在“上传的图片”:要用的图在 agent 的任务目录里,AI 用 agent 内置的公开临时 URL 工具现取一条短命链接给智谱拉。链接过期或 agent 重启后该 URL 失效,但智谱只在提交任务时拉一次,不受影响。 \ No newline at end of file +A: 本服务不存图,不存在“上传的图片”:要用的图在 agent 的任务目录里,AI 用 agent 内置的公开临时 URL 工具现取一条短命链接给智谱拉。链接过期或 agent 重启后该 URL 失效,但智谱只在提交任务时拉一次,不受影响。 diff --git a/mcp/video_gen/package.json b/mcp/video_task/package.json similarity index 60% rename from mcp/video_gen/package.json rename to mcp/video_task/package.json index ca15cbb..dcc7e0a 100644 --- a/mcp/video_gen/package.json +++ b/mcp/video_task/package.json @@ -1,7 +1,7 @@ { - "name": "mcp_video_gen", + "name": "mcp_video_task", "version": "1.0.0", - "description": "MCP server for video generation via Zhipu BigModel cogvideox-flash (text-to-video / image-to-video, async)", + "description": "MCP server for async video generation tasks via Zhipu BigModel cogvideox-flash (single tool video_task with op=create/get)", "type": "module", "main": "src/mcp-server.js", "scripts": { diff --git a/mcp/video_gen/src/mcp-server.js b/mcp/video_task/src/mcp-server.js similarity index 58% rename from mcp/video_gen/src/mcp-server.js rename to mcp/video_task/src/mcp-server.js index e78df68..88a82a2 100644 --- a/mcp/video_gen/src/mcp-server.js +++ b/mcp/video_task/src/mcp-server.js @@ -11,18 +11,18 @@ const ZHIPU_SUBMIT_URL = const ZHIPU_QUERY_URL = (id) => `https://open.bigmodel.cn/api/paas/v4/async-result/${encodeURIComponent(id)}`; -// 默认模型:你说的 cogvideox-flash,文档枚举里也确认可用 +// 默认模型:cogvideox-flash const DEFAULT_MODEL = "cogvideox-flash"; // AI 不可见的服务端默认(可被同名 header 覆盖) const DEFAULT_QUALITY = "speed"; // speed | quality -const DEFAULT_FPS = 30; // 30 | 60 +const DEFAULT_FPS = 30; // 30 | 60 const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true // ── 优雅退出 ────────────────────────────────────────────────────────────── // 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 // 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 -// 显式注册处理器,关闭 MCP session 与长连接后立即退出;3s 定时器为兑底。 +// 显式注册处理器,关闭 MCP session 与长连接后立即退出;3s 定时器为兜底。 let httpServer = null; let closeAllSessions = () => {}; let shuttingDown = false; @@ -30,7 +30,7 @@ let shuttingDown = false; function shutdown(sig) { if (shuttingDown) return; shuttingDown = true; - console.log(`[video_gen] 收到 ${sig},停止服务`); + console.log(`[video] received ${sig}, shutting down`); closeAllSessions(); if (!httpServer) process.exit(0); // stdio 模式无监听,直接退 httpServer.close(() => process.exit(0)); @@ -57,7 +57,7 @@ function parseArgs(argv) { function pickToken(headers) { if (!headers) return null; const candidates = [ - headers["x-video-gen-token"], + headers["x-video-task-token"], headers["x-mcp-token"], headers["authorization"], ]; @@ -78,7 +78,7 @@ function pickToken(headers) { function pickModel(headers) { if (!headers) return null; const v = - headers["x-video-gen-model"] || + headers["x-video-task-model"] || headers["x-mcp-model"] || headers["x-model"]; if (!v) return null; @@ -140,7 +140,7 @@ async function callZhipu({ url, token, method = "POST", body }) { return data; } -// ===== 工具:提交视频生成(同步只提交,立刻返回)===== +// ===== op=create:提交视频生成(同步只提交,立刻返回)===== async function submitVideo({ token, model, @@ -151,7 +151,7 @@ async function submitVideo({ fps, watermark_enabled, }) { - // 平台要求 image_url 和 prompt 至少传一个 + // 平台要求 image_url 和 prompt 至少传一个(handler 侧已校验) const body = { model, quality, @@ -164,143 +164,202 @@ async function submitVideo({ if (prompt) body.prompt = prompt; if (image_url) body.image_url = image_url; - const data = await callZhipu({ - url: ZHIPU_SUBMIT_URL, - token, - body, - }); - return data; // { model, id, request_id, task_status } + return await callZhipu({ url: ZHIPU_SUBMIT_URL, token, body }); + // { model, id, request_id, task_status } } -// ===== 工具:查询异步结果(单次拉取,不内部轮询)===== +// ===== op=get:查询异步结果(单次拉取,不内部轮询)===== async function queryAsyncResult({ token, id }) { - const data = await callZhipu({ + return await callZhipu({ url: ZHIPU_QUERY_URL(id), token, method: "GET", }); - return data; // { id, request_id, model, task_status, video_result?, ... } + // { id, request_id, model, task_status, video_result?, ... } +} + +// ---------- op=create 的业务处理 ---------- +async function handleCreate({ args, headers, token }) { + if (!args.prompt && !args.image_url) { + return { + isError: true, + content: [ + { + type: "text", + text: 'op=create requires at least one of "prompt" or "image_url".', + }, + ], + }; + } + + // AI 不可见:全部走 header + const model = pickModel(headers) || DEFAULT_MODEL; + const quality = pickHeaderString( + headers, + "x-video-task-quality", + DEFAULT_QUALITY + ); + const fps = pickHeaderInt(headers, "x-video-task-fps", DEFAULT_FPS); + const watermark_enabled = pickHeaderBool( + headers, + "x-video-task-watermark", + DEFAULT_WATERMARK_ENABLED + ); + + try { + const data = await submitVideo({ + token, + model, + prompt: args.prompt, + image_url: args.image_url, + quality, + with_audio: args.with_audio ?? false, + fps, + 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 this tool again with op="get" and 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)}` : "" + }`, + }, + ], + }; + } +} + +// ---------- op=get 的业务处理 ---------- +async function handleGet({ args, token }) { + if (!args.task_id) { + return { + isError: true, + content: [{ type: "text", text: 'op=get requires "task_id".' }], + }; + } + + 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)}` : "" + }`, + }, + ], + }; + } } function buildServer() { const server = new McpServer( - { - name: "video_gen", - version: "1.0.0", - }, - { - capabilities: { - tools: {}, - }, - } + { name: "video_task", version: "1.0.0" }, + { capabilities: { tools: {} } } ); - // ---------- 工具 1:video_gen ---------- server.tool( - "video_gen", - `Submit an async video generation task. Returns a task_id; poll with query_video. + "video_task", + `Manages asynchronous video generation tasks. -- text-to-video: provide prompt only. -- image-to-video: also provide image_url.`, +op=create Submit a new task. Returns a task_id immediately; generation runs asynchronously. + Requires at least one of prompt or image_url. + - text-to-video: pass prompt only. + - image-to-video: also pass image_url. +op=get Fetch the status of a previously submitted task. Requires task_id. + On SUCCESS, returns the video URL. + +Typical flow: call op=create, then call op=get with the returned task_id until task_status is SUCCESS or FAIL.`, { + op: z.enum(["create", "get"]).describe("Operation to perform."), prompt: z .string() + .max(512) + .optional() .describe( - "Video text description (max 512 chars). Required; when combined with image_url it serves as the motion/action description." + "Video text description (max 512 chars). Used with op=create. When combined with image_url it serves as the motion/action description." ), image_url: z .string() .url() .optional() .describe( - "Reference image for image-to-video. Must be a publicly reachable URL to a png/jpeg/jpg <= 5MB (for local files, first use the agent's built-in tool to mint a public temporary URL)." + "Reference image for image-to-video. Used with op=create. Must be a publicly reachable URL to a png/jpeg/jpg <= 5MB (for local files, first use the agent's built-in tool to mint a public temporary URL)." ), 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 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, - quality, - with_audio: args.with_audio ?? false, - fps, - 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).", - { + .describe( + "Whether to generate AI audio. Used with op=create. Default false." + ), task_id: z .string() .min(1) - .describe("task_id returned by video_gen."), + .optional() + .describe("task_id returned by op=create. Required when op=get."), }, async (args, extra) => { const headers = extra?.requestInfo?.headers; @@ -312,69 +371,21 @@ function buildServer() { }; } - 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` : ""); + switch (args.op) { + case "create": + return await handleCreate({ args, headers, token }); + case "get": + return await handleGet({ args, token }); + default: return { + isError: true, content: [ - { type: "text", text: summary }, - { type: "text", text: v.url }, + { + type: "text", + text: `Unknown op "${args.op}" (available: create, get).`, + }, ], }; - } - - // 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)}` : "" - }`, - }, - ], - }; } } ); @@ -404,7 +415,7 @@ async function startHttp({ port, host }) { }; app.get("/health", (_req, res) => { - res.json({ status: "ok", service: "video_gen", sessions: sessions.size }); + res.json({ status: "ok", service: "video_task", sessions: sessions.size }); }); async function handleSessionRequest(req, res) { @@ -423,7 +434,8 @@ async function startHttp({ port, host }) { jsonrpc: "2.0", error: { code: -32000, - message: "Bad Request: missing valid Mcp-Session-Id for non-initialize request", + message: + "Bad Request: missing valid Mcp-Session-Id for non-initialize request", }, id: req.body?.id ?? null, }); @@ -467,7 +479,7 @@ async function startHttp({ port, host }) { httpServer = app.listen(port, host, () => { console.log( - `[video_gen] MCP HTTP server listening on http://${host}:${port}/mcp` + `[video] MCP HTTP server listening on http://${host}:${port}/mcp` ); }); } @@ -479,18 +491,18 @@ async function startStdio() { ); const transport = new StdioServerTransport(); await server.connect(transport); - console.error("[video_gen] MCP stdio server started"); + console.error("[video] 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); + console.error("[video] failed to start http server:", e); process.exit(1); }); } else { startStdio().catch((e) => { - console.error("[video_gen] failed to start stdio server:", e); + console.error("[video] failed to start stdio server:", e); process.exit(1); }); } From e54645bf622c6a163931c3ace07395a1efbab5f9 Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 23 Sep 2026 08:46:09 +0800 Subject: [PATCH 32/41] =?UTF-8?q?image=5Ftask:=20=E5=8E=BB=E6=8E=89=20size?= =?UTF-8?q?=20=E5=8F=82=E6=95=B0=EF=BC=8C=E5=9B=BE=E7=89=87=E5=B0=BA?= =?UTF-8?q?=E5=AF=B8=E8=B5=B0=E4=B8=8A=E6=B8=B8=E9=BB=98=E8=AE=A4=EF=BC=88?= =?UTF-8?q?AI=20=E4=BC=A0=E9=94=99=E5=80=BC=E7=BB=8F=E5=B8=B8=E6=8A=A5?= =?UTF-8?q?=E9=94=99=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/image_task/README.md | 9 +++------ mcp/image_task/src/mcp-server.js | 13 ++----------- 2 files changed, 5 insertions(+), 17 deletions(-) diff --git a/mcp/image_task/README.md b/mcp/image_task/README.md index cd4f17e..5125f6d 100644 --- a/mcp/image_task/README.md +++ b/mcp/image_task/README.md @@ -74,7 +74,8 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r |---|---|---|---| | `op` | `"create"` | ✅ | 要执行的操作(当前仅 `create`) | | `prompt` | string | ✅ | 图片生成提示词,描述想要的画面内容(仅 op=create 使用) | -| `size` | string | ❌ | 图片尺寸,例如 `1024x1024`、`1280x1280`、`1024x1792`、`1792x1024`、`768x1344`、`1344x768`,遵循智谱 API 规格(仅 op=create 使用) | + +> 图片尺寸不再透传,走上游默认;尺寸档位与成本/成功率挂钩,AI 传错值经常直接报错。 ### Model 控制(不在工具参数中暴露) @@ -187,8 +188,7 @@ curl -s -X POST http://localhost:8082/mcp \ "name": "image_task", "arguments": { "op": "create", - "prompt": "一只可爱的小猫咪,坐在阳光明媚的窗台上,背景是蓝天白云", - "size": "1280x1280" + "prompt": "一只可爱的小猫咪,坐在阳光明媚的窗台上,背景是蓝天白云" } } }' @@ -251,6 +251,3 @@ A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize **Q: URL 多久过期?** A: 智谱签发 URL 默认 24h 左右,详见响应里的 `Expires` 参数。需要长期使用请自行转存到 OSS/S3。 - -**Q: 能否限制 `size` 白名单?** -A: 当前透传给智谱 API,不做强制校验。如需加白名单,修改 `src/mcp-server.js` 中 `image_task` 的 `size` schema 即可。 diff --git a/mcp/image_task/src/mcp-server.js b/mcp/image_task/src/mcp-server.js index 4a02b0a..6afff20 100644 --- a/mcp/image_task/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -77,9 +77,8 @@ function pickModel(headers) { return s || null; } -async function callZhipuImagesGenerations({ token, model, prompt, size }) { +async function callZhipuImagesGenerations({ token, model, prompt }) { const body = { model, prompt }; - if (size) body.size = size; const resp = await fetch(ZHIPU_API_URL, { method: "POST", headers: { @@ -123,14 +122,12 @@ async function handleCreate({ args, headers, token }) { // 不存进 session,每次从本次请求的 header 读取,未设置则用默认 CogView-3-Flash。 // AI 看不到 model 参数(schema 中已删除),避免其误传。 const model = pickModel(headers) || DEFAULT_MODEL; - const size = args.size; try { const data = await callZhipuImagesGenerations({ token, model, prompt: args.prompt, - size, }); const urls = extractUrls(data); if (urls.length === 0) { @@ -188,7 +185,7 @@ function buildServer() { "image_task", `Manages image generation. Generation is synchronous: op=create returns the image URLs directly. -op=create Generate an image from a prompt. Requires prompt; optional size.`, +op=create Generate an image from a prompt. Requires prompt.`, { op: z .enum(["create"]) @@ -201,12 +198,6 @@ op=create Generate an image from a prompt. Requires prompt; optional size.`, .describe( "Image generation prompt; describe the desired scene in detail. Used with op=create." ), - size: z - .string() - .optional() - .describe( - "Image size, Preferred sizes: 1024x1024, 1280x1280, 1536x1024, 1024x1536, Each side must be a multiple of 32. Used with op=create." - ), }, async (args, extra) => { // SDK 在 tool callback 的 extra.requestInfo.headers 里会透传当前 HTTP 请求的 headers From 5269dee70d3cb3deca87d4bbc1f42ef8cc6e0fdb Mon Sep 17 00:00:00 2001 From: kicer Date: Thu, 24 Sep 2026 17:02:30 +0800 Subject: [PATCH 33/41] =?UTF-8?q?image=5Ftask:=20=E6=94=B9=E6=88=90?= =?UTF-8?q?=E5=BC=82=E6=AD=A5=E4=BB=BB=E5=8A=A1=E5=BD=A2=E6=80=81=EF=BC=88?= =?UTF-8?q?op=3Dcreate/get=EF=BC=89=EF=BC=8C=E5=AF=B9=E9=BD=90=20video=5Ft?= =?UTF-8?q?ask=20=E5=A5=91=E7=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 上游智谱 images 是同步接口,异步语义由服务自维护的进程内任务表模拟: create 登记 task_id 后把同步调用丢后台执行、立即返回;get 只读本地表。 已完成任务保留 1h、容量上限 1000;容器重启任务丢失,仅限单实例部署。 --- mcp/image_task/README.md | 87 ++++++++++--- mcp/image_task/src/mcp-server.js | 205 ++++++++++++++++++++++++------- 2 files changed, 230 insertions(+), 62 deletions(-) diff --git a/mcp/image_task/README.md b/mcp/image_task/README.md index 5125f6d..26154ea 100644 --- a/mcp/image_task/README.md +++ b/mcp/image_task/README.md @@ -1,6 +1,6 @@ # MCP Image Task -一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成服务,对接智谱 BigModel 的 `CogView` 系列模型。每次调用通过 HTTP header 传入智谱 API 的 Bearer Token。只有一个工具 `image_task`,用 `op` 区分动作(图片生成为同步接口,当前仅支持 `op=create`)。 +一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成服务,对接智谱 BigModel 的 `CogView` 系列模型。每次调用通过 HTTP header 传入智谱 API 的 Bearer Token。只有一个工具 `image_task`,用 `op` 区分动作(`create` / `get`),对外提供与 `video_task` 一致的**异步任务**契约;上游为同步接口,异步语义由服务自维护的任务表模拟(见「架构与文件」)。 - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - 上游:[智谱 BigModel Images Generations API](https://open.bigmodel.cn/dev/api#images) @@ -28,7 +28,7 @@ docker compose up -d --build mcp_image_task ```bash # 不占端口的健康检查 docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" -# {"status":"ok","service":"image_task","sessions":0} +# {"status":"ok","service":"image_task","sessions":0,"tasks":0} ``` ### MCP 客户端配置 @@ -62,18 +62,22 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r ## 工具:image_task -调用智谱图片生成接口,返回图片 URL。生成为**同步**接口,`op=create` 直接出结果,无需轮询。 +管理图片生成异步任务。典型流程:`op=create` 拿 `task_id`,然后不断 `op=get` 直到 `task_status` 为 `SUCCESS` 或 `FAIL`。 -| op | 作用 | 同步/异步 | +| op | 作用 | 说明 | |---|---|---| -| `create` | 按 prompt 生成图片,返回图片 URL | 同步(直接返回结果) | +| `create` | 提交图片生成任务,**立即**返回 `task_id`,生成在后台执行 | 需要 `prompt` | +| `get` | 查询任务状态;`SUCCESS` 时返回图片 URL | 需要 `task_id` | + +> 上游智谱 images 接口是同步阻塞的;这里的异步是对外的统一形态(对齐 `video_task`),服务内部把同步调用丢到后台跑并回写任务表。 ### 参数(AI 可见) | 名称 | 类型 | 必填 | 说明 | |---|---|---|---| -| `op` | `"create"` | ✅ | 要执行的操作(当前仅 `create`) | -| `prompt` | string | ✅ | 图片生成提示词,描述想要的画面内容(仅 op=create 使用) | +| `op` | `"create"` \| `"get"` | ✅ | 要执行的操作 | +| `prompt` | string | op=create 时 ✅ | 图片生成提示词,描述想要的画面内容 | +| `task_id` | string | op=get 时 ✅ | `op=create` 返回的任务 ID | > 图片尺寸不再透传,走上游默认;尺寸档位与成本/成功率挂钩,AI 传错值经常直接报错。 @@ -93,20 +97,33 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r ### 返回 -工具成功时返回若干 `text` 块,第一块是摘要,后续每块各包含一张图片的 URL(方便 LLM 直接贴图或下载): +`op=create` 成功时立即返回 `task_id`(生成已转入后台): ```jsonc { "content": [ - { "type": "text", "text": "Model: CogView-3-Flash\nPrompt: ...\nImage 1: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." }, + { "type": "text", "text": "Model: CogView-3-Flash\ntask_id: \ntask_status: PROCESSING\n\nImage generation is running in background. Call this tool again with op=\"get\" and task_id=\"\" to fetch the result." } + ] +} +``` + +`op=get` 按任务状态返回: + +- `PROCESSING`:提示几秒后再查; +- `SUCCESS`:若干 `text` 块,第一块是摘要,后续每块各包含一张图片的 URL(方便 LLM 直接贴图或下载): + +```jsonc +{ + "content": [ + { "type": "text", "text": "task_id: \nmodel: CogView-3-Flash\ntask_status: SUCCESS\nImage 1: https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." }, { "type": "text", "text": "https://maas-watermark-prod-new.cn-wlcb.ufileos.com/..." } ] } ``` -URL 由智谱签名下发,**带有效期**(通常 24h),如需长期保存请在收到后及时转存到自己的存储。 +- `FAIL`:`isError: true`,正文含 `task_status: FAIL` 与错误信息(上游 4xx/5xx、无 URL 返回等都会归档到这里)。 -失败时返回 `isError: true` 的错误描述。 +URL 由智谱签名下发,**带有效期**(通常 24h),如需长期保存请在收到后及时转存到自己的存储。 --- @@ -127,8 +144,10 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 | 场景 | HTTP 状态 | 表现 | |---|---|---| | initialize 时缺 token | `401` | JSON-RPC `error.message` 提示补充 header | -| 智谱 API 4xx/5xx | `200`(MCP 工具返回) | `isError: true`,正文含智谱返回的状态码和 body | -| 网络失败 | `200`(MCP 工具返回) | `isError: true`,正文含 `fetch` 错误信息 | +| op=create 缺 prompt / op=get 缺 task_id | `200`(MCP 工具返回) | `isError: true`,参数提示 | +| op=get 查不到任务(ID 错/已过期/服务重启过) | `200`(MCP 工具返回) | `isError: true`,提示 unknown task_id | +| 智谱 API 4xx/5xx | `200`(MCP 工具返回) | 在 `op=get` 中以 `isError: true` + `task_status: FAIL` 呈现,正文含智谱返回的状态码和 body | +| 网络失败 | `200`(MCP 工具返回) | 同上,`task_status: FAIL`,正文含 `fetch` 错误信息 | --- @@ -174,7 +193,7 @@ curl -s -X POST http://localhost:8082/mcp \ -H "Mcp-Session-Id: $SESSION" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' -# 4. 调 image_task(op=create) +# 4. 调 image_task(op=create,立即返回 task_id) curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ @@ -192,6 +211,25 @@ curl -s -X POST http://localhost:8082/mcp \ } } }' + +# 5. 拿上一步返回的 task_id 轮询结果(直到 SUCCESS / FAIL) +curl -s -X POST http://localhost:8082/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": "image_task", + "arguments": { + "op": "get", + "task_id": "<上一步返回的 task_id>" + } + } + }' ``` 响应是 SSE 格式(`event: message` + `data: {...}`),用 `grep '^data:'` 抽 JSON 即可。 @@ -212,11 +250,16 @@ image_task/ ### 关键设计 -- **单工具 + `op` 分发**:`image_task(op=create)`,与 `video_task` 的服务形态保持一致;生成为同步接口,所以 `op` 只有 `create` 一个取值 +- **单工具 + `op` 分发**:`image_task(op=create|get)`,与 `video_task` 的服务形态完全一致,agent 侧一套轮询逻辑通吃图片/视频 +- **同步上游 → 异步契约**:智谱 images 接口只支持同步,所以服务自维护一张任务表来模拟异步: + - `create` 本地生成 `task_id`(`randomUUID`),登记 `PROCESSING`,把同步调用丢后台(fire-and-forget),立即返回 + - 后台完成时回写 `SUCCESS`(含 URLs)或 `FAIL`(含错误) + - `get` 只读本地表,不碰上游 + - 表为进程内存 Map:已完成任务保留 1 小时(TTL)、容量上限 1000,每次 `create` 顺带淘汰;**容器重启后任务丢失**,`get` 会报 unknown task_id;**不适用于多副本部署**(表不互通) + - token/model 在 `create` 那一刻从请求 header 捕获进闭包,后台完成前不再读取,保持「每请求读 header」的无状态设计 - **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用,避免每请求重建 -- **Token 闭包注入**:在 Express 入口处从 header 提取 token,闭包传给 tool 回调;不依赖 SDK 内部字段 - **模型参数不入 schema**:model 只从 HTTP header 读取(`X-Image-Task-Model` / `X-Mcp-Model` / `X-Model`),AI 不可见 -- **URL 提取**:`response.data[].url` 为准,若返回 `b64_json` 也会一并返回 +- **URL 提取**:`response.data[].url` 为准,若返回 `b64_json` 也会一并归档进任务表 ### 默认模型 @@ -237,8 +280,14 @@ A: 这是设计意图。模型选择属于路由策略,不让 AI 决策。调 **Q: 换模型需要重连 MCP session 吗?** A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取,不需要重建 session。 -**Q: 为什么 op 只有 create?** -A: 图片生成是同步接口,`op=create` 直接返回结果,不存在需要轮询的异步任务。保留 `op` 参数是为了与 `video_task` 等异步任务型服务形态一致;将来若上游出现异步接口再加 `get`。 +**Q: 上游是同步接口,为什么对外做成异步?** +A: 为了和 `video_task` 保持同一套任务型契约,agent 侧只需维护一种「create 后轮询 get」的调用模式。同步调用被放到后台执行,对 AI 而言表现为标准异步任务。 + +**Q: create 之后服务容器重启了,get 会怎样?** +A: 任务表在进程内存里,重启即丢失,`get` 会返回 unknown task_id 的 `isError`。需要重新 `create`。图片生成只跑几秒,受影响窗口很小;若将来要上多副本或需要可靠恢复,再把表换成持久化存储。 + +**Q: 为什么 get 不需要等上游?** +A: `get` 只读本地任务表,上游调用只发生在 `create` 的后台一次,不会因轮询而重复计费/重复生图。 **Q: 为什么 Model 优先级不是「工具参数 > header」?** A: 因为我们故意不在 schema 暴露 model 参数,AI 根本不会传 model,所以「工具参数 > header」这条分支实际上不存在。 diff --git a/mcp/image_task/src/mcp-server.js b/mcp/image_task/src/mcp-server.js index 6afff20..336a23c 100644 --- a/mcp/image_task/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -116,56 +116,161 @@ function extractUrls(data) { return []; } -// ===== op=create:提交图片生成(同步,直接返回图片 URL)===== +// ===== 自维护任务表(异步语义全靠这层模拟) ===== +// 上游智谱 images 接口是同步阻塞的,但对外要和 video_task 一样提供 +// create(立即返回 task_id)+ get(轮询结果)的异步契约: +// create 登记 PROCESSING 后把同步调用丢到后台跑,get 从表里读最新状态。 +// +// 已知取舍: +// - 表在进程内存里:容器重启/重建后任务丢失,get 会报 unknown task_id; +// 图片生成只跑几秒,窗口很小,不值得为此引入持久化。 +// - 只适用于单实例部署:多副本时 create 和 get 可能打到不同进程,表不互通。 +const TASK_TTL_MS = 60 * 60 * 1000; // 已完成(SUCCESS/FAIL)任务保留 1 小时 +const MAX_TASKS = 1000; // 表容量上限,超出从最老的已完成任务开始淘汰 + +// task_id -> { status, model, prompt, createdAt, urls?, error? } +const tasks = new Map(); + +function pruneTasks() { + const now = Date.now(); + for (const [id, t] of tasks) { + if (t.status !== "PROCESSING" && now - t.createdAt > TASK_TTL_MS) { + tasks.delete(id); + } + } + if (tasks.size > MAX_TASKS) { + // Map 按插入序迭代;PROCESSING 永不主动淘汰 + for (const [id, t] of tasks) { + if (tasks.size <= MAX_TASKS) break; + if (t.status !== "PROCESSING") tasks.delete(id); + } + } +} + +// 后台跑同步上游调用,结果回写任务表(fire-and-forget,不 await) +function runImageTask({ task, token, model, prompt }) { + callZhipuImagesGenerations({ token, model, prompt }) + .then((data) => { + const urls = extractUrls(data); + if (urls.length === 0) { + task.status = "FAIL"; + task.error = `Zhipu returned no image URL. Raw response: ${JSON.stringify(data)}`; + } else { + task.status = "SUCCESS"; + task.urls = urls; + } + }) + .catch((e) => { + task.status = "FAIL"; + task.error = `${e.message}${ + e.detail ? ` Details: ${JSON.stringify(e.detail)}` : "" + }`; + }); +} + +// ===== op=create:提交图片生成(立即返回 task_id,后台执行)===== async function handleCreate({ args, headers, token }) { + if (!args.prompt) { + return { + isError: true, + content: [{ type: "text", text: 'op=create requires "prompt".' }], + }; + } + // model 完全由 HTTP header 控制(X-Image-Task-Model / X-Mcp-Model / X-Model), // 不存进 session,每次从本次请求的 header 读取,未设置则用默认 CogView-3-Flash。 // AI 看不到 model 参数(schema 中已删除),避免其误传。 const model = pickModel(headers) || DEFAULT_MODEL; - try { - const data = await callZhipuImagesGenerations({ - token, - model, - prompt: args.prompt, - }); - const urls = extractUrls(data); - if (urls.length === 0) { - return { - isError: true, - content: [ - { - type: "text", - text: `Returned no image URL. Raw response: ${JSON.stringify(data)}`, - }, - ], - }; - } - const summary = urls - .map((u, i) => `Image ${i + 1}: ${u}`) - .join("\n"); + pruneTasks(); + const taskId = randomUUID(); + const task = { + status: "PROCESSING", + model, + prompt: args.prompt, + createdAt: Date.now(), + }; + tasks.set(taskId, task); + + // token/model 在此刻从本次请求 header 捕获进闭包,后台完成前无需再取 + runImageTask({ task, token, model, prompt: args.prompt }); + + const summary = + `Model: ${model}\n` + + `task_id: ${taskId}\n` + + `task_status: PROCESSING\n` + + `\n` + + `Image generation is running in background. ` + + `Call this tool again with op="get" and task_id="${taskId}" to fetch the result.`; + + return { content: [{ type: "text", text: summary }] }; +} + +// ===== op=get:查询任务状态(只读本地表,不碰上游)===== +async function handleGet({ args }) { + if (!args.task_id) { return { - content: [ - { - type: "text", - text: `Model: ${model}\nPrompt: ${args.prompt}\n${summary}`, - }, - ...urls.map((u) => ({ type: "text", text: u })), - ], + isError: true, + content: [{ type: "text", text: 'op=get requires "task_id".' }], }; - } catch (e) { + } + + const task = tasks.get(args.task_id); + if (!task) { return { isError: true, content: [ { type: "text", - text: `Failed to generate image: ${e.message}${ - e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : "" - }`, + text: + `Unknown task_id "${args.task_id}". ` + + `Finished tasks are kept for 1 hour and are lost on service restart.`, }, ], }; } + + if (task.status === "PROCESSING") { + return { + content: [ + { + type: "text", + text: + `task_id: ${args.task_id}\n` + + `model: ${task.model}\n` + + `task_status: PROCESSING\n` + + `\n` + + `Call op="get" again in a few seconds.`, + }, + ], + }; + } + + if (task.status === "FAIL") { + return { + isError: true, + content: [ + { + type: "text", + text: `task_id: ${args.task_id}\ntask_status: FAIL\nerror: ${task.error}`, + }, + ], + }; + } + + // SUCCESS:输出格式与原同步版 create 一致(摘要块 + 每张图一个 URL 块) + const lines = task.urls.map((u, i) => `Image ${i + 1}: ${u}`).join("\n"); + const summary = + `task_id: ${args.task_id}\n` + + `model: ${task.model}\n` + + `task_status: SUCCESS\n` + + `${lines}`; + return { + content: [ + { type: "text", text: summary }, + ...task.urls.map((u) => ({ type: "text", text: u })), + ], + }; } function buildServer() { @@ -183,21 +288,28 @@ function buildServer() { server.tool( "image_task", - `Manages image generation. Generation is synchronous: op=create returns the image URLs directly. + `Manages asynchronous image generation tasks. -op=create Generate an image from a prompt. Requires prompt.`, +op=create Submit a new task. Returns a task_id immediately; generation runs in background. + Requires prompt. +op=get Fetch the status of a previously submitted task. Requires task_id. + On SUCCESS, returns the image URLs. + +Typical flow: call op=create, then call op=get with the returned task_id until task_status is SUCCESS or FAIL.`, { - op: z - .enum(["create"]) - .describe( - 'Operation to perform. Only "create" is supported (generation is synchronous, so there is no task to poll).' - ), + op: z.enum(["create", "get"]).describe("Operation to perform."), prompt: z .string() .min(1) + .optional() .describe( - "Image generation prompt; describe the desired scene in detail. Used with op=create." + "Image generation prompt; describe the desired scene in detail. Required when op=create." ), + task_id: z + .string() + .min(1) + .optional() + .describe("task_id returned by op=create. Required when op=get."), }, async (args, extra) => { // SDK 在 tool callback 的 extra.requestInfo.headers 里会透传当前 HTTP 请求的 headers @@ -220,13 +332,15 @@ op=create Generate an image from a prompt. Requires prompt.`, switch (args.op) { case "create": return await handleCreate({ args, headers, token }); + case "get": + return await handleGet({ args }); default: return { isError: true, content: [ { type: "text", - text: `Unknown op "${args.op}" (available: create).`, + text: `Unknown op "${args.op}" (available: create, get).`, }, ], }; @@ -259,7 +373,12 @@ async function startHttp({ port, host }) { }; app.get("/health", (_req, res) => { - res.json({ status: "ok", service: "image_task", sessions: sessions.size }); + res.json({ + status: "ok", + service: "image_task", + sessions: sessions.size, + tasks: tasks.size, + }); }); async function handleSessionRequest(req, res) { From 90395eeefe5bc5ba3b152f00ce2ac14239facd95 Mon Sep 17 00:00:00 2001 From: kicer Date: Thu, 24 Sep 2026 17:04:55 +0800 Subject: [PATCH 34/41] =?UTF-8?q?image=5Ftask:=20=E4=B8=8A=E6=B8=B8?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=E8=B0=83=E7=94=A8=E5=8A=A0=20120s=20?= =?UTF-8?q?=E8=B6=85=E6=97=B6=EF=BC=88AbortSignal.timeout=EF=BC=89?= =?UTF-8?q?=EF=BC=8C=E8=B6=85=E6=97=B6=E8=AE=B0=20FAIL=EF=BC=8C=E6=9D=9C?= =?UTF-8?q?=E7=BB=9D=E5=83=B5=E5=B0=B8=20PROCESSING=20=E4=BB=BB=E5=8A=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/image_task/README.md | 6 +++++- mcp/image_task/src/mcp-server.js | 31 +++++++++++++++++++++++-------- 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/mcp/image_task/README.md b/mcp/image_task/README.md index 26154ea..042b1de 100644 --- a/mcp/image_task/README.md +++ b/mcp/image_task/README.md @@ -148,6 +148,7 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 | op=get 查不到任务(ID 错/已过期/服务重启过) | `200`(MCP 工具返回) | `isError: true`,提示 unknown task_id | | 智谱 API 4xx/5xx | `200`(MCP 工具返回) | 在 `op=get` 中以 `isError: true` + `task_status: FAIL` 呈现,正文含智谱返回的状态码和 body | | 网络失败 | `200`(MCP 工具返回) | 同上,`task_status: FAIL`,正文含 `fetch` 错误信息 | +| 上游挂住不回(超时 >120s) | `200`(MCP 工具返回) | 同上,`task_status: FAIL`,正文提示 timed out;不会出现永久 PROCESSING 的僵尸任务 | --- @@ -253,7 +254,7 @@ image_task/ - **单工具 + `op` 分发**:`image_task(op=create|get)`,与 `video_task` 的服务形态完全一致,agent 侧一套轮询逻辑通吃图片/视频 - **同步上游 → 异步契约**:智谱 images 接口只支持同步,所以服务自维护一张任务表来模拟异步: - `create` 本地生成 `task_id`(`randomUUID`),登记 `PROCESSING`,把同步调用丢后台(fire-and-forget),立即返回 - - 后台完成时回写 `SUCCESS`(含 URLs)或 `FAIL`(含错误) + - 后台完成时回写 `SUCCESS`(含 URLs)或 `FAIL`(含错误);上游同步调用带 120s 超时(`AbortSignal.timeout`),超时记 `FAIL`,杜绝僵尸 `PROCESSING` - `get` 只读本地表,不碰上游 - 表为进程内存 Map:已完成任务保留 1 小时(TTL)、容量上限 1000,每次 `create` 顺带淘汰;**容器重启后任务丢失**,`get` 会报 unknown task_id;**不适用于多副本部署**(表不互通) - token/model 在 `create` 那一刻从请求 header 捕获进闭包,后台完成前不再读取,保持「每请求读 header」的无状态设计 @@ -283,6 +284,9 @@ A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取, **Q: 上游是同步接口,为什么对外做成异步?** A: 为了和 `video_task` 保持同一套任务型契约,agent 侧只需维护一种「create 后轮询 get」的调用模式。同步调用被放到后台执行,对 AI 而言表现为标准异步任务。 +**Q: 任务一直 PROCESSING 会不会没完没了?** +A: 不会。上游同步调用封顶 120s(`AbortSignal.timeout`),超时直接记 `FAIL`,`get` 会拿到明确的 timed out 错误;不存在僵尸任务。 + **Q: create 之后服务容器重启了,get 会怎样?** A: 任务表在进程内存里,重启即丢失,`get` 会返回 unknown task_id 的 `isError`。需要重新 `create`。图片生成只跑几秒,受影响窗口很小;若将来要上多副本或需要可靠恢复,再把表换成持久化存储。 diff --git a/mcp/image_task/src/mcp-server.js b/mcp/image_task/src/mcp-server.js index 336a23c..c77f058 100644 --- a/mcp/image_task/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -10,6 +10,10 @@ const ZHIPU_API_URL = "https://open.bigmodel.cn/api/paas/v4/images/generations"; const DEFAULT_MODEL = "CogView-3-Flash"; +// 上游同步调用耗时上限(出图几十秒量级,留足余量)。 +// 超时后任务记为 FAIL,避免上游挂而不回时永远卡在 PROCESSING。 +const UPSTREAM_TIMEOUT_MS = 120_000; + // ── 优雅退出 ────────────────────────────────────────────────────────────── // 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 // 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 @@ -79,14 +83,25 @@ function pickModel(headers) { async function callZhipuImagesGenerations({ token, model, prompt }) { const body = { model, prompt }; - const resp = await fetch(ZHIPU_API_URL, { - method: "POST", - headers: { - Authorization: `Bearer ${token}`, - "Content-Type": "application/json", - }, - body: JSON.stringify(body), - }); + let resp; + try { + resp = await fetch(ZHIPU_API_URL, { + method: "POST", + headers: { + Authorization: `Bearer ${token}`, + "Content-Type": "application/json", + }, + body: JSON.stringify(body), + signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS), + }); + } catch (e) { + // AbortSignal.timeout 中止时抛 TimeoutError/AbortError, + // 转成普通错误后由 runImageTask 回写 FAIL + if (e?.name === "TimeoutError" || e?.name === "AbortError") { + throw new Error(`Upstream request timed out after ${UPSTREAM_TIMEOUT_MS} ms`); + } + throw e; + } const text = await resp.text(); let data; try { From cb090fe8e0f5b9d4709f0a5981e23386e5530b64 Mon Sep 17 00:00:00 2001 From: kicer Date: Thu, 24 Sep 2026 17:04:55 +0800 Subject: [PATCH 35/41] =?UTF-8?q?video=5Ftask:=20=E4=B8=8A=E6=B8=B8=20subm?= =?UTF-8?q?it/query=20=E5=8A=A0=2030s=20=E8=B6=85=E6=97=B6=EF=BC=8C?= =?UTF-8?q?=E9=81=BF=E5=85=8D=E4=B8=8A=E6=B8=B8=E6=8C=82=E8=80=8C=E4=B8=8D?= =?UTF-8?q?=E5=9B=9E=E6=97=B6=E6=8B=96=E6=AD=BB=E5=B7=A5=E5=85=B7=E8=B0=83?= =?UTF-8?q?=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/video_task/README.md | 1 + mcp/video_task/src/mcp-server.js | 15 ++++++++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/mcp/video_task/README.md b/mcp/video_task/README.md index 083ba66..4936baf 100644 --- a/mcp/video_task/README.md +++ b/mcp/video_task/README.md @@ -149,6 +149,7 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不 | initialize 时缺 token | `401` | JSON-RPC `error.message` 提示补充 header | | 智谱 API 4xx/5xx | `200`(MCP 工具返回) | `isError: true`,正文含智谱返回的状态码和 body | | 网络失败 | `200`(MCP 工具返回) | `isError: true`,正文含 `fetch` 错误信息 | +| 上游挂住不回(超时 >30s) | `200`(MCP 工具返回) | `isError: true`,正文提示 timed out;`fetch` 带 `AbortSignal.timeout`,不会无限卡住工具调用 | --- diff --git a/mcp/video_task/src/mcp-server.js b/mcp/video_task/src/mcp-server.js index 88a82a2..92a9467 100644 --- a/mcp/video_task/src/mcp-server.js +++ b/mcp/video_task/src/mcp-server.js @@ -19,6 +19,9 @@ const DEFAULT_QUALITY = "speed"; // speed | quality const DEFAULT_FPS = 30; // 30 | 60 const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true +// submit/query 都是快接口,卡住基本等于上游挂了;限时避免工具调用被拖死 +const UPSTREAM_TIMEOUT_MS = 30_000; + // ── 优雅退出 ────────────────────────────────────────────────────────────── // 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 // 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 @@ -119,9 +122,19 @@ async function callZhipu({ url, token, method = "POST", body }) { Authorization: `Bearer ${token}`, "Content-Type": "application/json", }, + signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS), }; if (body !== undefined) init.body = JSON.stringify(body); - const resp = await fetch(url, init); + let resp; + try { + resp = await fetch(url, init); + } catch (e) { + // AbortSignal.timeout 中止时抛 TimeoutError/AbortError,转成明确的超时错误 + if (e?.name === "TimeoutError" || e?.name === "AbortError") { + throw new Error(`Upstream request timed out after ${UPSTREAM_TIMEOUT_MS} ms`); + } + throw e; + } const text = await resp.text(); let data; try { From 1fe8945a2de3b4ccee8e35a6a163fdb1f475d2ec Mon Sep 17 00:00:00 2001 From: kicer Date: Thu, 24 Sep 2026 17:10:48 +0800 Subject: [PATCH 36/41] =?UTF-8?q?=E8=B6=85=E6=97=B6=E6=97=B6=E9=97=B4?= =?UTF-8?q?=E6=94=B9=E6=88=903=E5=88=86=E9=92=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/image_task/src/mcp-server.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mcp/image_task/src/mcp-server.js b/mcp/image_task/src/mcp-server.js index c77f058..1b85e10 100644 --- a/mcp/image_task/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -12,7 +12,7 @@ const DEFAULT_MODEL = "CogView-3-Flash"; // 上游同步调用耗时上限(出图几十秒量级,留足余量)。 // 超时后任务记为 FAIL,避免上游挂而不回时永远卡在 PROCESSING。 -const UPSTREAM_TIMEOUT_MS = 120_000; +const UPSTREAM_TIMEOUT_MS = 180_000; // ── 优雅退出 ────────────────────────────────────────────────────────────── // 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 From 6b40ced355efa7a69db28c009f8537d1dad6c53a Mon Sep 17 00:00:00 2001 From: kicer Date: Sun, 18 Oct 2026 22:56:54 +0800 Subject: [PATCH 37/41] =?UTF-8?q?officecli:=20=E6=96=B0=E5=A2=9E=20Office?= =?UTF-8?q?=20=E6=96=87=E6=A1=A3=20MCP=20=E6=9C=8D=E5=8A=A1=EF=BC=88docx/x?= =?UTF-8?q?lsx/pptx=20=E5=88=9B=E5=BB=BA=E4=BF=AE=E6=94=B9=20+=20=E6=B5=8F?= =?UTF-8?q?=E8=A7=88=E5=99=A8=E5=AE=9E=E6=97=B6=E9=A2=84=E8=A7=88=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 零 npm 依赖 node shim:officecli mcp stdio→Streamable HTTP 桥(命令治理/交付取件链)+ watch 槽位 + 预览网关(:3100) - 二进制不进 git 也不进镜像:entrypoint 容器首启拉取到命名卷 officecli-bin(pin v1.0.157+sha256,每次启动校验;源链 GitHub→gh-proxy,支持自托管镜像覆盖;离线可手工放置,sha 对上就认);clone 后 docker compose up 即完整入口 - server.js 启动自检 fail fast;compose 注册 mcp_officecli(scratch 工作区独立卷,不挂 agent/tasks) --- mcp/.gitignore | 2 + mcp/README.md | 10 +- mcp/docker-compose.yml | 27 ++ mcp/officecli/Dockerfile | 29 ++ mcp/officecli/README.md | 119 ++++++ mcp/officecli/gateway.js | 89 +++++ mcp/officecli/package.json | 8 + mcp/officecli/scripts/entrypoint.sh | 64 ++++ mcp/officecli/server.js | 551 ++++++++++++++++++++++++++++ mcp/officecli/watch.js | 328 +++++++++++++++++ 10 files changed, 1226 insertions(+), 1 deletion(-) create mode 100644 mcp/officecli/Dockerfile create mode 100644 mcp/officecli/README.md create mode 100644 mcp/officecli/gateway.js create mode 100644 mcp/officecli/package.json create mode 100755 mcp/officecli/scripts/entrypoint.sh create mode 100644 mcp/officecli/server.js create mode 100644 mcp/officecli/watch.js diff --git a/mcp/.gitignore b/mcp/.gitignore index 88b017e..09cb07f 100644 --- a/mcp/.gitignore +++ b/mcp/.gitignore @@ -1,3 +1,5 @@ node_modules/ # 编排变量(调试端口等),含部署相关的地址,不进库 .env +# officecli 二进制:部署前由 ./officecli/get-officecli.sh 生成,不进库 +officecli/bin/ diff --git a/mcp/README.md b/mcp/README.md index cfa8e55..b7ac8ef 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -1,12 +1,16 @@ # MCP 服务集合 -三个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: +四个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: | 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 | |---|---|---|---|---| | `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` | | `image_task/` | `mcp_image_task` | 智谱 CogView 图片生成(单工具 op=create) | `3000` | `POST /mcp` | | `video_task/` | `mcp_video_task` | 智谱 CogVideo 视频生成(异步,单工具 op=create/get) | `3000` | `POST /mcp` | +| `officecli/` | `mcp_officecli` | Office 文档(docx/xlsx/pptx)创建修改 + 浏览器实时预览 | `3000`/`3100` | `POST /` | + +officecli 的预览页面同样不占宿主机端口:浏览器走 agent-core 的通用预览反代 +`/preview/<会话id>/<文档>/…`(登录 cookie 门禁),链路与槽位细节见 `officecli/README.md`。 **这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor` 按容器名访问。所以整台服务器对外只需要开 agent-core 那一个端口(`AGENT_PORT`,默认 8090)。 @@ -30,6 +34,9 @@ cd /root/workspace/tools/mcp && docker compose up -d --build `image_task` / `video_task` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 (agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥。 +`officecli` 与 agent **不共盘**:工作区是独立 scratch 卷(容器内布局同构 `/workspace/tasks/<会话id>/...`, +容器对会话数据盲视),数据交换只走桥的 push(mint 外链拉入)/ save 交付链(AI 在自己会话目录 curl 回写);且要先起 agent(external 网络 `agent-mcp-net` 由 agent 的 compose 创建)。 + ### 环境变量 写在仓库顶层 `.env` 里即可(不写就用默认值): @@ -66,6 +73,7 @@ AI 把拿到的 URL 当 image_url 交给 video_task:3000/mcp | `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | | `mcp_image_task` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | | `mcp_video_task` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 | +| `mcp_officecli` | 无 | MCP 口与预览网关口都只在内网;预览页由 agent-core 通用预览反代加登录 cookie 门禁 | ## 单独调试 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index e503405..710653a 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -32,8 +32,35 @@ services: networks: - agent-mcp-net + mcp_officecli: + build: ./officecli + container_name: mcp_officecli + restart: unless-stopped + environment: + # 关自动 resident:实测对时延零增益(瓶颈是 .NET 进程启动),换来无 file_locked 冲突、无常驻进程堆积 + - OFFICECLI_NO_AUTO_RESIDENT=1 + # 每次改动命令返回前落盘(含 open 起的 resident):编辑即自动保存,save/close 只为签发取件链接 + - OFFICECLI_RESIDENT_FLUSH=each + # scratch 卫生:闲置 7 天整目录回收;容量水位 2G(超限按目录 mtime 从旧到新删,删到 80% 为止) + - OFFICE_SCRATCH_TTL_MS=604800000 + - OFFICE_SCRATCH_MAX_BYTES=2147483648 + volumes: + # officecli 二进制缓存:entrypoint 首启拉取(镜像内 pin 版本+sha256,每次启动都校验),容器重建不重拉;down -v 后下次启动自动重拉;纯离线机改 bind 挂载手工放置(见 officecli/README) + - officecli-bin:/opt/officecli + # 刻意不挂 ../agent/tasks:容器对会话数据盲视,只有自己的 scratch 工作区(布局同构 /workspace/tasks/<会话id>/...)。 + # 与交付区的数据交换全部经 push(拉 mint 外链进来)/ pull(AI 在 executor 里执行 curl 写回自己目录)。 + - office-scratch:/workspace/tasks + networks: + - agent-mcp-net + networks: # 与 agent 仓库共用:网络由 agent 的 compose 创建并命名(所以要先起 agent), # 这里声明为 external 直接加入。agent-core / agent-executor 按容器名访问这些服务。 agent-mcp-net: external: true + +volumes: + # officecli 工作区:丢了不要紧(push/pull 流程会重建),down -v 即清空 + office-scratch: + # officecli 二进制缓存:丢了也不要紧,下次启动 entrypoint 自动重新拉取 + officecli-bin: diff --git a/mcp/officecli/Dockerfile b/mcp/officecli/Dockerfile new file mode 100644 index 0000000..2510f83 --- /dev/null +++ b/mcp/officecli/Dockerfile @@ -0,0 +1,29 @@ +FROM node:22-slim + +# libssl3: officecli is a .NET self-contained binary and hard-requires libssl. +# ICU is NOT needed: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 disables globalization. +# curl: the entrypoint fetches the officecli binary at FIRST boot (image intentionally +# does NOT vendor the binary -> nothing to pre-run after clone, `docker compose up` is the whole entry). +RUN apt-get update -qq \ + && apt-get install -y -qq --no-install-recommends libssl3 ca-certificates curl \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /app + +# Zero npm deps: node shim (server.js + watch.js + gateway.js). +# scripts/entrypoint.sh downloads the pinned officecli into /opt/officecli (named volume +# `officecli-bin`, cached across restarts; sha256 verified every boot, GitHub -> gh-proxy fallback) +# then execs CMD. /opt/officecli goes first in PATH so the shim still spawns bare `officecli`. +COPY package.json server.js watch.js gateway.js ./ +COPY scripts/entrypoint.sh /app/scripts/entrypoint.sh +RUN chmod +x /app/scripts/entrypoint.sh + +ENV PATH=/opt/officecli:${PATH} +ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 +ENV OFFICE_WORKSPACE=/workspace/tasks +ENV PORT=3000 + +EXPOSE 3000 + +ENTRYPOINT ["/app/scripts/entrypoint.sh"] +CMD ["node", "server.js"] diff --git a/mcp/officecli/README.md b/mcp/officecli/README.md new file mode 100644 index 0000000..fad43e8 --- /dev/null +++ b/mcp/officecli/README.md @@ -0,0 +1,119 @@ +# officecli + +Office 文档(.docx / .xlsx / .pptx)创建、检视、修改 + 浏览器实时预览的 MCP 服务。 + +上游开源 CLI:[officecli](https://d.officecli.ai)(.NET self-contained 单文件二进制,**不进 git 也不进镜像**;容器首次启动由 `scripts/entrypoint.sh` 拉取到命名卷缓存,pin 版本 + 每次启动 sha256 校验)。 +本目录是一个**零 npm 依赖**的 node shim:把 officecli 自带的 stdio 形态 MCP 桥成 +Streamable HTTP,外加一个按任务路径路由的预览网关。 + +- 协议:MCP **Streamable HTTP**,端点 `POST /`(任何路径都收) +- 鉴权:**无服务端鉴权**,只挂 `agent-mcp-net`(公网必须经 agent-core 登录门禁反代进来),永远不要映射出去 +- 端口:`3000`(MCP)+ `3100`(预览网关,单入口);`26315..26318` 是 watch 进程内部回环端口,不出容器 + +## 结构 + +| 文件 | 职责 | +| --- | --- | +| `server.js` | 入口(容器 PID1):常驻 `officecli mcp` stdio 子进程 + JSON-RPC id 重映射;命令治理(绝对化 / 隐去命令 / 扩展命令 / help 对齐,见下);save/close 附交付取件链、文件缺失附同步教学;桥级失败自动换子进程 | +| `watch.js` | 预览槽位管理:spawn `officecli watch`(只绑 127.0.0.1,vendor 限制),url 按任务组织,槽位号不出容器;`/f/` 交付能力链签发与取件;scratch 过期清理 | +| `gateway.js` | 预览网关(:3100):按路径把请求路由到槽位 watch;Referer 兜底 vendor 页面硬编码的根绝对 API;Host/Origin 成对改写回环自源 + 头白名单 | +| `scripts/entrypoint.sh` | 容器入口(ENTRYPOINT):确保二进制就位(`/opt/officecli`,compose 挂命名卷 `officecli-bin` 缓存;pin 在本文件,镜像升级=版本升级;源链 GitHub → gh-proxy 备源,可 `OFFICECLI_URL`/`OFFICECLI_MIRROR` 加源)→ exec 服务命令;拉不到 fail fast 教手动动作 | + +## 工具面与命令治理 + +只有**一个工具** `officecli`(command 字符串或 argv 数组,原样交给 CLI;schema 查询 `{"command":"help docx paragraph"}`)。 +模型看到的描述 = vendor 原文 + 一句扩展命令能力陈述;**行为约束全部代码化,不写教条**: + +| 机制 | 行为 | +| --- | --- | +| 相对路径自动绝对化 | 调用方(agent-core)每请求带 `X-Session-Dir`,裸文件名/相对路径自动补全会话目录(`key=value` 属性值亦可,如 `src=a.png`;AI 无感,与 terminal 直觉一致);`--type picture` 的 `path=` 属性自动别名为 vendor 真名 `src=` | +| 隐去命令(报原生风格 `Unrecognized command or argument 'X'.`,help 清单同步对齐:删隐去行、补录扩展行) | `mcp`(自锁死)、`skills` / `install` / `plugins`(装环境类);`watch` 的 mark/unmark/marks/goto 子命令同理 | +| `view` 渲染族屏蔽 | 其它模式(outline/stats/issues/text/annotated)照常透传;仅渲染族 `view html` / `screenshot` / `svg` / `pdf` / `forms`(需无头浏览器/导出插件)拦截,返回 `view is disabled by environment policy. Use 'view outline' or 'view issues' for structural/semantic checks.` | +| 回包文案 | `create` / `open` / `push` 成功只回 `Created/Opened/Imported: <相对会话目录文件名>`;预览链接不随回包出现(固定格式 `<公网前缀>/preview/<会话id>/<相对路径>/`,前端自己拼,AI 面不需要知道);`save` / `close` 成功附 `download url:`(限时取件链,同文件复用同一链接);失败文案剥掉工作区路径前缀与 vendor 异常包装,只留文件名 | +| 桥内拦截(对 AI 不公示) | `watch` / `unwatch ` 仅本会话目录(必须拦截:vendor 原生 watch 会占死 stdio;help 里同步不显示);`unwatch --session [--purge]` 校验 id==X-Session-Dir 尾段,core 会话清理钩子专用 [--purge 杀槽外连带删会话目录副本,幂等];`get-pos ` 改写原生 `get … selected --json`;`push ` 外链拉入(http(s) only、100MB、非覆盖需 `--force`;读不到外链时报「读取文件失败」而非「下载失败」——AI 视角是上传) | +| 用法指引投递 | `load_skill office-preview` 只讲:get-pos / 两份盘同步;不出现 watch、不出现预览 url | + +`get` / `query` / `set` 等短命令照常透传(与槽位 watch 进程同容器 IPC 直达);`get-pos` 即桥内改写的 `get … selected --json`。 + +## 预览链路(为什么 watch 必须待在本容器) + +刷新信号 = officecli watch 进程内的 IPC,所以 watch 只能与 officecli 同容器; +槽位进程由shim(容器 PID1)托管才能跨 MCP 调用存活。浏览器不直连本容器, +必须经 agent-core 的通用预览反代(登录 cookie 即门禁,对外依旧只开 core 一个端口): + +``` +用户浏览器(已登录 agent) + │ https:///preview/<会话id>/<文档相对路径>/... + ▼ +agent-core routes/preview-proxy.js(注册表驱动,信任模型同 data-page) + │ 头白名单转发(Referer 兜底 vendor 页面的根绝对 /api/*、/events) + ▼ +mcp_officecli:3100 gateway.js ——按路径找槽位、改写 Host/Origin 回环自源──► 127.0.0.1:26315+N officecli watch +``` + +- url 按任务组织:文档必须在会话目录下(`/<会话id>/…`,任务根下不可预览);重启换槽不影响链接含义。 +- 预览 url 不由本服务下发:链接按固定格式 `<公网前缀>/preview/<会话id>/<文档相对路径>/` 由前端自拼;`X-Public-Base` 仅供桥内 watch 状态/日志用,对 AI 的回包里 `url`/`path` 字段已被剥掉。 +- 槽位数 `OFFICE_SLOTS`(默认 4);满了优先踢「无活动连接且最久未用」;闲置超 `OFFICE_IDLE_MS`(默认 6h)回收,挂着活动连接的槽不回收;预览每一帧回传与 AI 命令都会续命。 +- 槽位是缓存不是承诺:预览链接按任务路径寻址,被回收/挤占后页面再访问由网关就地复活(一次冷启动)。 +- AI 面不公示 watch/unwatch(也没有 watch ls / --all 这类跨会话动作):预览完全由前端拼链接、网关按需复活槽位 + LRU 管理;core 删会话时经校验的 `unwatch --session --purge` 清槽并删工作区目录副本(不等 scratch TTL)。 +- 同一文件同时只允许一个 watch(vendor 限制;同文件并发 watch 已合并为一次启动)。 + +## 两份盘与同步(push / download url) + +容器工作区与 `agent/tasks/<会话id>/` 是两份盘;桥负责在响应里教会 AI 换盘动线(拦截即教学,不设协议): + +| 方向 | 动线 | 执行者 | +| --- | --- | --- | +| 任务目录 → 工作区 | `mint_public_link` 签发外链 → `officecli push ` | 桥拉入(护栏:WORKSPACE 内、白名单扩展名(office/图片/常见数据)、100MB、非覆盖需 --force) | +| 工作区 → 任务目录 | `save ` / `close ` 回包尾附 `download url` → AI 在自己终端下载 | AI(executor 的会话 jail 天然框住写路径,core 零改动零新 API) | + +- 每次改动命令返回前落盘(compose 置 `OFFICECLI_RESIDENT_FLUSH=each`):编辑即自动保存,save/close 的主要作用只是签发取件链。 +- 成功/失败文案只带相对文件名,不出现工作区绝对路径:工作区与任务目录同名不同盘,全路径极易让 AI 误判文件落点。 + +- 取件链 `GET /f/<随机id>`:与 core `/p/` 同款能力链(随机不可猜 + TTL + 只吐 guard 过的路径),只在内部网络可达(core 反代只转 `/preview`,公网够不着)。同一文件重复 save/close 复用原 token(滑动 TTL,链接永远指向盘上最新内容)。过期 404 文案提示重新 save。 +- vendor 命令报"文件不存在"且引用路径确实缺失时,桥在错误尾附 push/交付动线提示;`X-Session-Dir` 首次出现时桥顺手 mkdir 会话目录。 +- core 会话删除时 `engine.deleteSession` 尽力打一发 `unwatch --session <会话id> --purge`(`mcp.notifyTool`,失败只记日志):桥端杀预览槽 + 删 `tasks/<会话id>` 工作区副本,幂等。 + +## 请求头契约(调用方 → 本服务) + +| 头 | 说明 | +| --- | --- | +| `X-Public-Base` | core 公网前缀(已归一),仅供桥内 watch 状态展示;预览 url 不再下发给 AI,缺省也无影响 | +| `X-Session-Dir` | 本次调用的会话工作目录,用于裸文件名/相对路径补全;core 的 mcp.js 从工具执行 ctx 自动注入,其它 MCP 服务忽略即可 | + +## 环境变量 + +| 变量 | 默认 | 说明 | +| --- | --- | --- | +| `OFFICE_WORKSPACE` | `/workspace/tasks` | 容器内工作区根(独立 scratch 卷,布局同构 `/<会话id>/...`;与 core 的 tasks 不同盘,数据交换只走 push / save 交付链) | +| `OFFICE_SLOTS` | `4` | 预览槽位数(内部端口段宽度) | +| `OFFICE_IDLE_MS` | `21600000`(6h) | 槽位闲置回收阈值;有活动预览连接的槽不回收,链接再访问自动复活 | +| `OFFICE_PREVIEW_PORT` | `3100` | 预览网关端口(与 core 注册表对齐) | +| `OFFICE_PREVIEW_PREFIX` | `/preview` | 预览 url 的路径前缀(与 core 注册表 prefix 一致) | +| `OFFICECLI_TIMEOUT_MS` | `120000` | 单次 MCP 请求等 officecli 回包的上限,超时 换子进程 | +| `OFFICE_DL_BASE` | `http://mcp_officecli:3100` | download url 的前缀(executor 可达的内网地址;改服务名时覆盖) | +| `OFFICE_DL_TTL_MS` | `1800000`(30min) | 取件链有效期,过期 404 并提示重新 save | +| `OFFICE_SCRATCH_TTL_MS` | `604800000`(7d) | scratch 会话目录闲置清理阈值(每小时一次 + 启动后 10s 首扫;槽位占用的目录不碰;0=关) | +| `OFFICE_SCRATCH_MAX_BYTES` | `2147483648`(2G) | scratch 容量水位:总量超限时按目录 mtime 从旧到新删非 busy 目录,删到 80% 为止(0=关) | +| `OFFICECLI_NO_AUTO_RESIDENT` | compose 置 `1` | 关 vendor 自动 resident:实测时延零增益,消掉 file_locked 冲突与常驻进程堆积(vendor 未公开变量,help 只写 `OFFICECLI_RESIDENT_FLUSH`) | +| `OFFICECLI_RESIDENT_FLUSH` | compose 置 `each` | 每次改动命令返回前落盘(含 open 起的 resident):编辑即自动保存,save/close 只为签发取件链 | + +## 部署与调试 + +`docker-compose.yml` 中的 `mcp_officecli` 服务构建本目录;工作区用独立命名卷 `office-scratch`, +**刻意不挂 `../agent/tasks`**:容器对会话数据盲视,泄漏面归零;容器内路径仍同构 `/workspace/tasks/<会话id>/...`,AI 无感。 + +二进制不进库也不进镜像:首次启动 entrypoint 自动拉取到命名卷 `officecli-bin`(容器重建不重拉;每次启动 sha256 秒级校验;版本 pin 在 `scripts/entrypoint.sh`,改版本=改文件重新 build)。GitHub 不通自动落 gh-proxy 备源;都失败则启动 fail fast(日志教手动动作,`unless-stopped` 重启即重试);`down -v` 清卷后下次启动自动重拉。 + +**离线放置**:GitHub 与备源都不可达的机器,把同名二进制放进挂载目录即可(sha256 对上就认):`docker cp mcp_officecli:/opt/officecli/officecli` 后 restart,或把 compose 里 `officecli-bin` 卷换成 bind 挂载。 + +```bash +docker compose up -d --build mcp_officecli # clone 后即可直接起;首启多一次二进制下载(仅首次) +# MCP 健康检查(含预览槽位列表) +docker exec mcp_officecli node -e "fetch('http://localhost:3000/').then(r=>r.json()).then(j=>console.log(JSON.stringify(j)))" +#预览网关健康检查 +docker exec mcp_officecli node -e "fetch('http://localhost:3100/gateway-healthz').then(r=>r.text()).then(console.log)" +``` + +agent 侧两处登记(缺一不可):`config.yml` 的 `mcp_servers: [{name: officecli, url: "http://mcp_officecli:3000/"}]`; +core 预览注册表默认已含 officecli(`routes/preview-proxy.js`,改 config.yml 后重启 core 生效)。 diff --git a/mcp/officecli/gateway.js b/mcp/officecli/gateway.js new file mode 100644 index 0000000..278d816 --- /dev/null +++ b/mcp/officecli/gateway.js @@ -0,0 +1,89 @@ +// 预览网关:单入口端口(:OFFICE_PREVIEW_PORT,默认 3100)按路径路由到槽位 watch —— 槽位号不出容器。 +// 主路由:/<会话id>/<文档相对路径>/** → 槽位注册表最长前缀匹配 → 转发该槽位 watch。 +// 自愈:路由未命中但请求路径本身是存在的会话文档 → 就地复活 watch(watch.revive)—— +// 槽位只是缓存不是承诺,闲置回收/被别的会话挤掉后,页面再访问 = 正常冷启动。 +// 兜底:vendor 预览页把交互 API 硬编码成根绝对路径(/api/selection、/events…)→ 按 Referer 找回槽位,原样转发。 +// masquerade:头白名单 + Host/Origin 成对改写为目标回环自源(watch 自带 DNS-rebinding/跨源防护); +// 凭据永不转发(core 那层已过滤,这里是容器内第二道防线)。 +'use strict'; +const http = require('node:http'); +const watch = require('./watch'); + +const PREFIX = watch.PREFIX; +// 上游(watch)确实用得到的头;cookie/authorization/referer/sec-fetch/user-agent 等一律不进 +const PASS = new Set(['accept', 'accept-encoding', 'cache-control', 'pragma', 'content-type', 'content-length', 'last-event-id', 'if-modified-since', 'if-none-match']); + +function forwardTo(entry, req, res, innerPath) { // innerPath:页面内相对路径(主路由剥前缀)或根绝对原路径(Referer 兜底),不再二次加工 + const selfHost = '127.0.0.1:' + entry.port; + const fwd = { host: selfHost }; + for (const k of Object.keys(req.headers)) if (PASS.has(k)) fwd[k] = req.headers[k]; + if (req.headers.origin) fwd.origin = 'http://' + selfHost; + const qpos = req.url.indexOf('?'); + const search = qpos >= 0 ? req.url.slice(qpos) : ''; + const inner = innerPath.startsWith('/') ? innerPath : '/' + innerPath; + // 槽位续命信号:建连即续,此后每帧回传再续(SSE 是长连接,只在建连那刻续会把长驻页面误判成闲置)。 + // conns 记「正在回传」的请求数:conns>0 = 有人正开着预览页,闲置回收/槽位挤占都绕着它走。 + entry.lastUsed = Date.now(); + entry.conns = (entry.conns || 0) + 1; + let released = false; + const release = () => { if (!released) { released = true; entry.conns = Math.max(0, entry.conns - 1); } }; + res.once('close', release); + res.once('finish', release); + const upstream = http.request( + { host: '127.0.0.1', port: entry.port, path: encodeURI(inner) + search, method: req.method, headers: fwd }, + (up) => { + const h = Object.assign({}, up.headers); + if (String(h['content-type'] || '').includes('text/event-stream')) { h['cache-control'] = 'no-cache'; h['x-accel-buffering'] = 'no'; } + res.writeHead(up.statusCode, h); + up.on('data', () => { entry.lastUsed = Date.now(); }); // 含 SSE 心跳/事件帧:任何回传 = 上游活着 + up.pipe(res); + }); + upstream.on('error', () => { + if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }).end('预览槽位不可达(可能刚停止或已到期回收)'); + else res.destroy(); + release(); // 上面两条终结路径各自触发 close/finish 前,这里幂等兜底 + }); + req.pipe(upstream); +} + +function matchReferer(req) { + const ref = req.headers.referer || req.headers.referrer || ''; + if (!ref) return null; + try { + const rp = decodeURIComponent(new URL(ref).pathname); + if (!rp.startsWith(PREFIX + '/')) return null; + return watch.matchPage(rp.slice(PREFIX.length)); + } catch (_) { return null; } +} + +function start(port, host) { + return http.createServer((req, res) => { + route(req, res).catch(() => { if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' }).end('预览网关内部错误'); }); + }).listen(port, host); +} + +async function route(req, res) { + let u; + try { u = decodeURIComponent((req.url || '/').split('?')[0]); } catch (_) { res.writeHead(400).end('bad path'); return; } + if (req.method === 'GET' && u === '/gateway-healthz') { + const body = JSON.stringify({ ok: true, prefix: PREFIX, slots: watch.status('').length }); + res.writeHead(200, { 'content-type': 'application/json' }).end(body); + return; + } + if (req.method === 'GET' && u.startsWith('/f/')) return watch.serveDl(decodeURIComponent(u.slice(3)), req, res); // 交付取件口:URL 即能力,只在内部网络可达(core 反代只转 /preview) + if (u === PREFIX + '/' || u.startsWith(PREFIX + '/')) { + const rel = u.slice(PREFIX.length) || '/'; + let m = watch.matchPage(rel); + if (!m) m = await watch.revive(rel); // 槽=缓存:页面重开/冷槽就地复活 + if (m) { + if (m.exact && !u.endsWith('/')) { res.writeHead(301, { location: (req.url || u) + '/' }).end(); return; } // 相对路径资源解析需要尾斜杠 + const cut = PREFIX.length + m.entry.pageDec.length; // 剥掉「前缀+页面路径」才是 watch 的内层路径 + return forwardTo(m.entry, req, res, u.length > cut ? u.slice(cut) : '/'); + } + } + const viaRef = matchReferer(req); // vendor 页面的根绝对 API:Referer 找回来源槽位,原路径原样转发(不剥页面前缀!) + if (viaRef) return forwardTo(viaRef.entry, req, res, u); + res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('无匹配预览(文档不存在/不在会话目录下,或不是 .docx/.xlsx/.pptx;若文档在任务目录里,先 officecli push 进来)'); +} + +module.exports = { start }; diff --git a/mcp/officecli/package.json b/mcp/officecli/package.json new file mode 100644 index 0000000..8179d05 --- /dev/null +++ b/mcp/officecli/package.json @@ -0,0 +1,8 @@ +{ + "name": "officecli-mcp", + "version": "0.1.0", + "private": true, + "description": "Streamable-HTTP MCP shim bridging officecli mcp (stdio) + live preview slots", + "main": "server.js", + "scripts": { "start": "node server.js" } +} diff --git a/mcp/officecli/scripts/entrypoint.sh b/mcp/officecli/scripts/entrypoint.sh new file mode 100755 index 0000000..1c59c2e --- /dev/null +++ b/mcp/officecli/scripts/entrypoint.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# 容器入口:确保 officecli 二进制就位(命名卷缓存)→ exec 真正的服务命令。 +# +# - 二进制不进 git 也不进镜像:首次启动下载到 /opt/officecli(compose 挂命名卷 officecli-bin), +# 之后每次启动只做 sha256 秒级校验,容器重建不重复下载;卷删了(down -v)下次启动自动重拉。 +# - 信任锚是镜像里的 pin(本脚本写死版本+sha256;镜像升级=版本升级): +# 缓存有效性 = 实际 sha256 与 pin 一致——换版本后旧缓存自动作废,无需额外标记文件。 +# - 源链(依次尝试,产物一律过 sha256):OFFICECLI_URL 整URL覆盖 → GitHub → gh-proxy 备源 → OFFICECLI_MIRROR 前缀。 +# - 离线兜底:往挂载目录放一份同名二进制即可(sha 对上就认),见 README「离线放置」。 +# - 拉取失败:fail fast 非零退出(unless-stopped 重启即重试),日志教手动动作。 +set -euo pipefail + +VERSION="${OFFICECLI_VERSION:-v1.0.157}" +SHA256="${OFFICECLI_SHA256:-f8eefe88dbfa7464bee421e5421efe57fc26bc3180b30e56eef58594c8245c94}" +ASSET="officecli-linux-x64" +GH_URL="https://github.com/iOfficeAI/OfficeCLI/releases/download/${VERSION}/${ASSET}" + +BIN_DIR="${OFFICECLI_DIR:-/opt/officecli}" +BIN="${BIN_DIR}/officecli" + +log() { echo "[officecli-fetch] $*"; } + +sha_ok() { printf '%s %s\n' "${SHA256}" "$1" | sha256sum -c --status - >/dev/null 2>&1; } + +# 缓存命中 = 可执行 + sha256 与镜像内 pin 一致(顺带覆盖 docker cp / 手工放置的兜底场景) +if [ -x "${BIN}" ] && sha_ok "${BIN}"; then + log "officecli ${VERSION} in place (${BIN}); skip fetch" + exec "$@" +fi + +urls=() +if [ -n "${OFFICECLI_URL:-}" ]; then urls+=("${OFFICECLI_URL}"); fi +urls+=( "${GH_URL}" "https://gh-proxy.com/${GH_URL}" ) +if [ -n "${OFFICECLI_MIRROR:-}" ]; then + p="${OFFICECLI_MIRROR}"; case "${p}" in */) ;; *) p="${p}/";; esac + urls+=( "${p}${GH_URL}" ) +fi + +mkdir -p "${BIN_DIR}" +rm -f "${BIN_DIR}"/.dl.* 2>/dev/null || true # 清理上次被中断的半成品 +tmp="$(mktemp "${BIN_DIR}/.dl.XXXXXX")" # 与目标同目录:最后 mv 原子就位,中断永远不会留下残缺拷贝 +trap 'rm -f "${tmp}"' EXIT + +for url in "${urls[@]}"; do + log "trying ${url}" + if curl -fsSL --connect-timeout 10 --retry 1 --max-time 600 -o "${tmp}" "${url}"; then + got="$(sha256sum "${tmp}" | awk '{print $1}')" + if [ "${got}" = "${SHA256}" ]; then + chmod +x "${tmp}" + mv -f "${tmp}" "${BIN}" + log "officecli ${VERSION} installed -> ${BIN}" + exec "$@" + fi + log "sha256 mismatch (got ${got}), trying next source" + fi + rm -f "${tmp}" +done + +log "FATAL: officecli ${VERSION} 所有源都拉不到(或校验不过)。" +log " asset: ${GH_URL}" +log " sha256: ${SHA256}" +log " 手动放置(sha 对上就认):docker cp <本地二进制> mcp_officecli:${BIN} && docker compose restart mcp_officecli" +log " 或把 compose 里 officecli-bin 卷换成 bind 挂载(./某目录:${BIN_DIR})离线放置,再 up -d。" +exit 1 diff --git a/mcp/officecli/server.js b/mcp/officecli/server.js new file mode 100644 index 0000000..63e3f80 --- /dev/null +++ b/mcp/officecli/server.js @@ -0,0 +1,551 @@ +// officecli MCP 服务 shim —— Streamable HTTP(:3000) ⇄ officecli mcp(stdio) 桥。 +// +// 为什么需要这么一层:officecli 的 MCP 只有 stdio 形态;且 watch(预览)必须与 +// officecli 同容器(刷新信号=进程内 IPC)、与 shim 同父(躲开任何命令级进程回收)。 +// 本进程是容器 PID1:常驻 officecli mcp 子进程 + watch.js 管槽位 watch 子进程。 +// +// 工具面:单工具 officecli(command 字符串透传 + 桥内命令治理):create/open/push 成功只回文件名确认, +// 预览链接固定格式由前端自拼(AI 面不出现 url);save/close 自带 download url,点选回读 get-pos;watch/unwatch 桥内拦截但不向 AI 公示 +//(必须拦截:vendor 原生 watch 会占死 stdio;且仅开放本会话目录);隐去命令报原生风格 Unrecognized, +// help 同步对齐可见面;用法指引走 load_skill office-preview(见 DEPLOY_SKILL),零教条。 +// 环境变量:OFFICE_WORKSPACE(= /workspace/tasks)、OFFICE_SLOTS(=4)、OFFICE_PREVIEW_PORT(=3100)。 +// 公网 url 前缀不配置在这里:调用方(agent-core)每请求用 X-Public-Base 头注入(真相只在 core 一处), +// 会话工作目录同理经 X-Session-Dir 头注入(裸文件名自动补全会话目录,AI 无感)。 +'use strict'; +const http = require('node:http'); +const { createServer } = http; +const fs = require('node:fs'); +const path = require('node:path'); +const { spawn } = require('node:child_process'); + +// 启动自检:officecli 缺失/不可执行不在首个 MCP 请求时以诡异超时现身——PID1 直接 fail fast 并教部署动作。 +if (!(process.env.PATH || '').split(':').some((d) => { try { fs.accessSync(path.join(d, 'officecli'), fs.constants.X_OK); return true; } catch (_) { return false; } })) { + console.error("[bridge] FATAL: officecli binary not found in PATH (expected /opt/officecli/officecli,由 entrypoint 拉取就位)。" + + "查 [officecli-fetch] 启动日志;离线放置见 officecli/README「离线放置」(sha256 对上就认)。"); + process.exit(1); +} + +const watch = require('./watch'); +const gateway = require('./gateway'); + +const PORT = Number(process.env.PORT || 3000); +const PREVIEW_PORT = Number(process.env.OFFICE_PREVIEW_PORT || 3100); +const HOST = process.env.HOST || '0.0.0.0'; +const CALL_TIMEOUT_MS = Number(process.env.OFFICECLI_TIMEOUT_MS || 120000); +const SERVER_NAME = 'officecli-mcp'; + +// ---------- stdio 桥:单条常驻 officecli mcp 子进程 ---------- +let child = null; +let ready = false; // officecli 子进程是否已完成 initialize 握手 +let buf = ''; +let seq = 0; +const pending = new Map(); // bridge id -> {res 回调, timer:http 等待方} + +function resetChild() { + for (const [, p] of pending) { clearTimeout(p.timer); p.reject(new Error('officecli process exited, retry')); } + pending.clear(); buf = ''; child = null; ready = false; +} + +function ensureChild() { + if (child) return child; + // cwd 进共享卷:否则相对路径产物落在容器根 fs(/app),core/executor 都看不见 + child = spawn('officecli', ['mcp'], { stdio: ['pipe', 'pipe', 'inherit'], cwd: watch.WORKSPACE }); + const me = child; // 身份守卫:只有当前子进程的 exit 才重置桥(换新后的旧进程迟到的 exit 不得误伤) + child.stdout.on('data', (d) => { + buf += d; let i; + while ((i = buf.indexOf('\n')) >= 0) { + const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1); + if (!line) continue; + let msg; try { msg = JSON.parse(line); } catch (_) { continue; } + if (msg.id !== undefined && pending.has(msg.id)) { + const p = pending.get(msg.id); pending.delete(msg.id); + clearTimeout(p.timer); p.resolve(msg); + } else if (msg.method) { + console.log('[bridge] officecli 通知:', msg.method); // 桥接侧暂无需处理 + } + } + }); + me.on('exit', (code) => { console.log('[bridge] officecli mcp 退出', code); if (child === me) resetChild(); }); + return child; +} +// 向 officecli 子进程发一条 JSON-RPC 请求并等回包(id 重映射,多 HTTP 请求并发安全) +function rpc(method, params) { + return new Promise((resolve, reject) => { + const c = ensureChild(); + const id = ++seq; + const timer = setTimeout(() => { + if (!pending.has(id)) return; + pending.delete(id); reject(new Error('Timeout waiting for officecli response: ' + method)); + }, CALL_TIMEOUT_MS); + pending.set(id, { resolve, reject, timer }); + c.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); + }); +} + +function sendNotify(method, params) { + const c = ensureChild(); + c.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); +} + +// 桥自己补一次 initialize 握手(兜底:子进程重建后,客户端还没发过 initialize 就来请求) +async function selfInit() { + await rpc('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'officecli-mcp-shim', version: '0' } }); + sendNotify('notifications/initialized', {}); +} + +// 会话 id 从预览 url 拷回来时可能是百分号编码形态;解不动就用原样(id 字符集本不需编码) +function decSafe(s) { try { return decodeURIComponent(s); } catch (_) { return s; } } + +// ---------- 部署面治理:隐藏命令报原生风格 unrecognized,help 同步对齐(AI 眼里 = 原生 CLI)---------- +const unrecognized = (v) => "Unrecognized command or argument '" + v + "'."; +const HIDDEN_SUBS = new Set(['mark', 'unmark', 'marks', 'goto']); // 标注/滚动族:本部署只保留 watch / watch ls / unwatch / get-pos +const HIDDEN_VERBS = 'mcp|skills|install|plugins'; // 与 handle 里的 mblk 黑名单同步(view 已放开,只拦 html/screenshot 渲染模式) +const HIDDEN_LINE = /^ {2}(?:mcp|skills|install|plugins)\b/; // 注意:绝不能用字符串拼 RegExp,'\b' 在 JS 字符串里是退格符 +const HELP_STRIP = /^ {2}(?:watch|unwatch)\b/; // 预览已自动化(create/open/push 附链接):help 也不出示 watch/unwatch,防 AI 想起没用过的命令 +const VIEW_BLOCKED = new Set(['html', 'screenshot', 'svg', 'pdf', 'forms']); // view 渲染族:需无头浏览器/导出插件,本环境一律屏蔽 + +// push 护栏:目标必须落在 WORKSPACE 内且是白名单扩展名(office + 资源图 + 常见数据;目标可以尚不存在,故不复用 watch.guard)。 +// 裸相对名以会话目录为基准(absolutize 只处理 office/图片,其余允许类型若按 WORKSPACE 根解会落到会话外,与回执/files 列表不一致); +// 显式绝对路径仍可指向工作区任意位置(既有设计)。pushTarget(p, base):base 越界时退回 WORKSPACE。 +function pushTarget(p, base) { + const wsRoot = path.resolve(watch.WORKSPACE); + const root = base && path.resolve(base).startsWith(wsRoot + path.sep) ? path.resolve(base) : wsRoot; + const abs = path.resolve(root, String(p || '')); + const rel = path.relative(wsRoot, abs); + if (!rel || rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) throw new Error('Target must be inside the workspace (' + watch.WORKSPACE + '): ' + p); + if (!PUSH_EXT_RE.test(abs)) throw new Error('Unsupported file type: ' + p + '. Allowed: office (.docx/.xlsx/.pptx), images (png/jpg/jpeg/gif/webp/bmp/tiff), pdf/csv/txt/json/md'); + return abs; +} +const PUSH_TIMEOUT_MS = 60000; +const PUSH_MAX_BYTES = 100 * 1024 * 1024; + +// 交付取件链接前缀:executor 与本源同网,AI 终端里的 curl 直接用它(改名部署时用 env 覆盖) +const DL_BASE = (process.env.OFFICE_DL_BASE || 'http://mcp_officecli:' + PREVIEW_PORT).replace(/\/+$/, ''); +const SYNC_TEACH = 'Your task directory and the officecli workspace are two separate disks. To edit a file that already ' + + 'exists in your task directory: sign a link for it with mint_public_link, then run officecli push ' + + 'to sync it in. When done editing, save the file and download the returned download url back into your task directory.'; + +// help 照透传,但文本过一道:隐去的命令行删掉、桥扩展命令补进 Commands 清单(可见面 = 可调用面) +const HELP_ADD = [ + ' get-pos Read what the user selected in the live preview (returns JSON).', + ' push Download an http(s) URL into the workspace as .', + ' files List files under the current workspace directory (server-side).', +]; +function alignHelp(reply) { + const items = reply && reply.result && Array.isArray(reply.result.content) ? reply.result.content : []; + for (const it of items) { + if (!it || typeof it.text !== 'string' || !it.text.includes('Commands:')) continue; + const text = it.text.replace(/ ?Subcommands \(mark\/unmark\/marks\/goto\) operate on the running preview\./g, ''); + const out = []; + let added = false; + for (const ln of text.split('\n')) { + if (HIDDEN_LINE.test(ln) || HELP_STRIP.test(ln)) continue; + out.push(ln); + if (!added && /^ {2}help\s/.test(ln)) { out.push(...HELP_ADD); added = true; } + } + if (!added) out.push(...HELP_ADD); + it.text = out.join('\n'); + } +} + +// 成功回执三词式:vendor 原文带工作区绝对路径(与 AI 任务目录同名不同盘,极易误判落点),统一替换成 +// "Created/Opened: <相对会话目录文件名>"。预览链接是固定格式(<公网前缀>/preview/<会话id>/<相对路径>/), +// 调用方自拼,不再随回包附带。 +function ackNote(cmd, reply, sessDir) { + const verb = /^create\b/.test(cmd) ? 'Created' : /^open\b/.test(cmd) ? 'Opened' : ''; + if (!verb) return; + const res = reply && reply.result; + if (!res || res.isError || !Array.isArray(res.content)) return; + const first = res.content.find((c) => c && typeof c.text === 'string'); + if (!first) return; + const t = (tokenizeCmd(cmd) || []).find((x) => x.startsWith(watch.WORKSPACE + '/') && OFFICE_EXT_RE.test(x)); + if (!t) return; + const jail = sessDir && sessDir.startsWith('/') ? path.resolve(sessDir) : ''; + first.text = verb + ': ' + (jail && t.startsWith(jail + '/') ? path.relative(jail, t) : path.basename(t)); +} + +// 失败文案整形:剥掉工作区路径前缀只留文件名(与任务目录同名不同盘,全路径只会诱发误判); +// 顺带拆掉 vendor resident 异常包装("Resident process exited. Unhandled exception: X.CliException: …")只留内层真错 +const WS_PATH_RE = new RegExp(watch.WORKSPACE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/(?:[^\\s\'"`,;:()()]+/)*', 'g'); +function scrubErr(reply) { + const res = reply && reply.result; + if (!res || !res.isError || !Array.isArray(res.content)) return; + for (const c of res.content) { + if (!c || typeof c.text !== 'string') continue; + c.text = c.text + .replace(/Resident process exited\.\s*Unhandled exception:\s*[\w.]*Exception:\s*/g, '') + .replace(WS_PATH_RE, ''); + } +} + +// 透传报错误且引用的工作区路径确实不存在:十有八九是文件只在任务目录里 —— 拦截即教学(push 方向) +function teachOnMiss(cmd, reply) { + const res = reply && reply.result; + if (!res || !res.isError) return; + const txt = (res.content || []).map((c) => (c && c.text) || '').join(' '); + if (/unrecognized/i.test(txt)) return; + const toks = tokenizeCmd(cmd) || []; + // key=value 属性里的路径同样检查(如 src=/workspace/…):缺失才附同步教学 Hint + if (!toks.some((x) => { const v = x.includes('=') && !x.slice(0, x.indexOf('=')).includes('/') ? x.slice(x.indexOf('=') + 1) : x; return v.startsWith(watch.WORKSPACE + '/') && !fs.existsSync(v); })) return; + const first = (res.content || []).find((c) => c && typeof c.text === 'string'); + if (first) first.text += '\nHint: ' + SYNC_TEACH; +} + +// save/close 是 AI 的原生收尾仪式:成功时附限时取件链接(同 core /p/:URL 即能力),下载回任务目录的动作留给 AI +function deliverNote(cmd, reply) { + if (!/^(save|close)\b/.test(cmd)) return; + const res = reply && reply.result; + if (!res || res.isError || !Array.isArray(res.content)) return; + const toks = (tokenizeCmd(cmd) || []).filter((t) => t.startsWith(watch.WORKSPACE + '/') && OFFICE_EXT_RE.test(t) && fs.existsSync(t)); + if (!toks.length) return; + const first = res.content.find((c) => c && typeof c.text === 'string'); + if (!first) return; + first.text += toks.map((t) => '\ndownload url: ' + DL_BASE + '/f/' + watch.dlMint(t)).join(''); +} + +// ---------- 预览伪命令(桥内拦截,不落 vendor 进程)---------- +// watch 族命令不走透传(常驻服务占死 stdio 会挂满超时):从命令尾取文件参数,跳过旗标,支持引号 +function watchArg(rest) { + let s = String(rest || '').trim(); + s = s.replace(/^--port(?:\s*=|\s+)\S+\s*/, ''); + s = s.replace(/\s+--port(?:\s*=|\s+)\S+/, ''); + const m = /^"([^"]*)"|^'([^']*)'|^(\S+)/.exec(s); + return m ? (m[1] !== undefined ? m[1] : m[2] !== undefined ? m[2] : m[3]) : ''; +} + +// ---------- 命令治理:路径自动绝对化 / 黑名单 / 部署技能(能用代码处理的绝不写成提示词) ---------- +const quoteArg = (s) => (/[\s"'\\]/.test(s) ? "'" + s.replace(/'/g, "'\\''") + "'" : s); + +// 引号感知分词;引号不闭合返回 null(调用方放弃改写,不动原命令) +function tokenizeCmd(s) { + const out = []; let cur = null, q = null; + for (const c of s) { + if (q) { if (c === q) q = null; else cur += c; continue; } + if (c === '"' || c === "'") { if (cur === null) cur = ''; q = c; continue; } + if (/\s/.test(c)) { if (cur !== null) { out.push(cur); cur = null; } continue; } + if (cur === null) cur = ''; + cur += c; + } + if (q !== null) return null; + if (cur !== null) out.push(cur); + return out; +} + +const OFFICE_EXT_RE = /\.(?:docx|xlsx|pptx)$/i; +// 资源图(插图命令的参数)也要绝对化:vendor cwd 是工作区根而非会话目录,裸 logo.png 会错解到 /workspace/logo.png +const RESOURCE_EXT_RE = /\.(?:png|jpe?g|gif|webp|bmp|tiff?)$/i; +// --input 类数据文件同样要绝对化:原生 cwd 是工作区根而非会话目录,裸名永远碰不到会话目录里的文件 +const DATA_EXT_RE = /\.(?:json|csv|tsv|txt|md)$/i; +// push 目标类型白名单:office + 资源图 + 常见数据;服务端不落盘执行任何内容,风险主要是工作区积灰,白名单聊胜于无 +const PUSH_EXT_RE = /\.(?:docx|xlsx|pptx|pdf|csv|txt|json|md|png|jpe?g|gif|webp|bmp|tiff?)$/i; +function absToken(t, sess) { + if (!t || t.startsWith('-') || t.startsWith('/') || /:\/\//.test(t)) return t; + // key=value 属性(如 src=a.png):只对值部分绝对化再拼回 key= 前缀;整体拼会把 src= 也吃进路径 + let key = ''; + let val = t; + const eq = t.indexOf('='); + if (eq > 0 && !t.slice(0, eq).includes('/')) { key = t.slice(0, eq + 1); val = t.slice(eq + 1); } + if (!val || val.startsWith('-') || val.startsWith('/') || /:\/\//.test(val)) return t; + const core = val.replace(/^(?:\.\.?\/)+/, ''); + if (!OFFICE_EXT_RE.test(core) && !RESOURCE_EXT_RE.test(core) && !DATA_EXT_RE.test(core)) return t; + return key + sess + '/' + core; +} +// 裸文件名/相对路径 → 会话目录绝对路径(X-Session-Dir);没有实际改动时原样返回,最小侵入 vendor 解析 +function absolutize(cmd, sessDir) { + if (!sessDir || !sessDir.startsWith('/')) return cmd; + const sess = sessDir.replace(/\/+$/, ''); + const toks = tokenizeCmd(cmd); + if (!toks) return cmd; + let changed = false; + const out = toks.map((t) => { const a = absToken(t, sess); if (a !== t) changed = true; return a; }); + return changed ? out.map(quoteArg).join(' ') : cmd; +} + +// 用法指引:只讲 AI 用得上的(预览链接是固定格式、前端自拼,AI 面不出现 url;也从不要求 AI 主动 watch) +const DEPLOY_SKILL = `# office-preview usage + +## Read back the user's selection +get-pos +Returns the structured node the user selected in the live preview. The @id= in its path stays stable across later edits; use it directly with set / get to target the change. + +## Sync: your task directory and the workspace are two separate disks +Check: files lists what the workspace (server side) already holds. +Pull in: to edit a file that already exists in your task directory, sign its link with mint_public_link first, then push . +Hand back: every edit is flushed to disk automatically. Before delivery, save to get the download url and download it into your task directory; if you edit again afterwards, save and download again. close does the same.`; + +// tools/list 时追加的唯一一句:能力 + 指针,零教条(规矩全在代码与错误文案里) +const DESC_PATCH = '\n\nExtensions: push pulls a URL file into the workspace; files lists the files already inside the workspace (server side); get-pos reads back what the user selected in the live preview; every edit is auto-saved to disk; before delivery run save and download the returned download url into your task directory. Full usage: load_skill office-preview.'; +// ---------- Streamable HTTP 入口 ---------- +// vendor 的 picture 类型收图片属性名为 src,AI 惯写 path=(会被报 'src' property is required): +// --type picture/image 时把属性键 path= 别名成 src=(token 层替换,不碰值) +// --commands 内联 JSON 保护:分词器按 POSIX 规则吞词中引号,绝对化触发整行重组后 +// JSON 会被剥光双引号(原生报 invalid start of property name)。在分词前从原始串 +// 扫描出配平的 JSON,单引号包裹后放回(原生认单引号包裹,含内部双引号/空格)。 +// 但原生不认 POSIX 的单引号转义 '\'':JSON 内含 ' 时改写会话目录点文件走 --input +// (绝对路径通道已实测可靠;点文件对 files 隐藏,随会话 purge/TTL 回收)。 +// 解析不了就原样放行,桥不装懂。 +function quoteInlineJson(cmd, sessDir) { + const m = /(^|\s)--commands(?:=|[ \t]+)/.exec(cmd); + if (!m) return cmd; + const head = cmd.slice(0, m.index) + m[1]; + const valStart = m.index + m[0].length; + const rest = cmd.slice(valStart); + const lead = /^\s*/.exec(rest)[0]; + const body = rest.slice(lead.length); + if (body[0] === "'" || body[0] === '"') return cmd; // 已自带外层引号,交给现有分词管线 + const json = scanBalancedJson(body); + if (!json) return cmd; + const tail = body.slice(json.length).replace(/^\s+/, ''); + let flag = '--commands', val; + if (!json.includes("'")) val = quoteArg(json); + else if (sessDir && sessDir.startsWith('/')) { + const fp = sessDir.replace(/\/+$/, '') + '/.batch-inline-' + Date.now().toString(36) + '.json'; + try { fs.writeFileSync(fp, json); flag = '--input'; val = quoteArg(fp); } catch (_) { return cmd; } + } else return cmd; + return head + flag + ' ' + val + (tail ? ' ' + tail : ''); +} + +// 从首个 [ / { 起扫描 balanced JSON 片段(处理 "..." 字符串与 \ 转义); +// 配平后再 JSON.parse 验真,不成 = 返回 null 放弃改写 +function scanBalancedJson(s) { + if (s[0] !== '[' && s[0] !== '{') return null; + let depth = 0, inStr = false, esc = false; + for (let i = 0; i < s.length; i++) { + const c = s[i]; + if (inStr) { if (esc) esc = false; else if (c === '\\') esc = true; else if (c === '"') inStr = false; continue; } + if (c === '"') inStr = true; + else if (c === '[' || c === '{') depth++; + else if (c === ']' || c === '}') { + depth--; + if (depth === 0) { + const frag = s.slice(0, i + 1); + try { JSON.parse(frag); return frag; } catch (_) { return null; } + } + } + } + return null; +} + +function pictureSrcAlias(cmd) { + if (!/(?:^|\s)--type\s+(?:picture|image)(?:\s|$)/.test(cmd)) return cmd; + const toks = tokenizeCmd(cmd); + if (!toks) return cmd; + let changed = false; + const out = toks.map((t) => { if (!/^path=/.test(t)) return t; changed = true; return 'src=' + t.slice(5); }); + return changed ? out.map(quoteArg).join(' ') : cmd; +} + +function json(res, code, obj) { + const body = JSON.stringify(obj); + res.writeHead(code, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) }); + res.end(body); +} + +function toolText(resObj) { + return { content: [{ type: 'text', text: typeof resObj === 'string' ? resObj : JSON.stringify(resObj, null, 2) }], isError: false }; +} +function toolErr(msg) { + return { content: [{ type: 'text', text: 'Error: ' + (msg && msg.message || String(msg)) }], isError: true }; +} + +async function handle(msg, pubBase, sessDir) { // pubBase/sessDir:调用方每请求注入(X-Public-Base / X-Session-Dir) + const isReq = msg.id !== undefined && msg.id !== null; + let helpCmd = false; // 本次调用是否为 help 族:透传后要把文本对齐可调用面 + // 通知(含 notifications/initialized):透传不等回包 + if (!isReq) { sendNotify(msg.method, msg.params || {}); return null; } + + if (msg.method === 'tools/call') { + const args = msg.params && msg.params.arguments || {}; + // 命令归一:argv 数组 → 命令串;相对路径自动绝对化(会话目录由调用方头注入) + let cmd = Array.isArray(args.command) ? args.command.map((a) => quoteArg(String(a))).join(' ') : String(args.command || ''); + cmd = absolutize(pictureSrcAlias(quoteInlineJson(cmd, sessDir)), sessDir).trim(); + args.command = cmd; + // 会话目录在 scratch 卷里可能尚不存在(首建):顺手补齐,create/push 才有落点(仅工作区内); + // 但 unwatch(含 --purge)是清理命令,不得反向重建刚删的目录 + if (sessDir && !/^unwatch\b/.test(cmd)) { + const sd = path.resolve(sessDir); + if (sd.startsWith(watch.WORKSPACE + '/')) { try { fs.mkdirSync(sd, { recursive: true }); } catch (_) {} } + } + + // 本部署不合适的命令(装自己/装环境那族):报原生风格 unrecognized,不露壳; + // help 清单里的这些行同步在 alignHelp 删除,可见面 = 可调用面。 + const mblk = /^(mcp|skills|install|plugins)(?:\s|$)/.exec(cmd) || /^help\s+(mcp|skills|install|plugins)(?:\s|$)/.exec(cmd); + if (mblk) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized(mblk[1])) }; + helpCmd = /^help(?:\s|$)/.test(cmd) || /(?:^|\s)(?:--help|-h)(?:\s|$)/.test(cmd); + // view 放开结构/语义模式(outline/stats/issues/text/annotated),只拦渲染族(需无头浏览器/导出插件,本环境没有); + // 给模型指明替代路径,别让它抱着文档里的强制渲染门反复试错。 + if (!helpCmd && /^view(?:\s|$)/.test(cmd)) { + const vpos = (tokenizeCmd(cmd) || []).slice(1).filter((t) => !t.startsWith('-')); // [file, mode, ...] + const vmode = String(vpos[1] || '').toLowerCase(); + if (VIEW_BLOCKED.has(vmode)) { + return { jsonrpc: '2.0', id: msg.id, result: toolErr( + "view " + vmode + " is disabled by environment policy. Use 'view outline' or 'view issues' for structural/semantic checks.") }; + } + } + // 部署技能:伪装进 vendor 的 load_skill 机制;无名/vendor 已知名照旧透传(清单/其它技能) + const ms = /^load_skill\b\s*([\s\S]*)$/.exec(cmd); + if (ms && /^(?:office[-_]?preview|preview)$/.test(ms[1].trim().replace(/^["']|["']$/g, ''))) { + return { jsonrpc: '2.0', id: msg.id, result: toolText(DEPLOY_SKILL) }; + } + // files(桥扩展):列当前会话目录(工作区侧)下的文件,AI 据此判断哪些文件已同步进来; + // 只报相对文件名,隐藏文件/目录略去,深度与条数封顶。 + if (!helpCmd && /^files(?:\s|$)/.test(cmd)) { + const root = sessDir ? path.resolve(sessDir) : ''; + if (!root.startsWith(watch.WORKSPACE + '/')) return { jsonrpc: '2.0', id: msg.id, result: toolErr('files: no workspace session directory for this request') }; + const names = []; + (function walk(dir, depth) { + if (depth > 4 || names.length >= 500) return; + let ents; + try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; } + for (const e of ents) { + if (e.name.startsWith('.')) continue; + const p = path.join(dir, e.name); + if (e.isDirectory()) walk(p, depth + 1); + else if (names.length < 500) names.push(path.relative(root, p)); + } + })(root, 0); + return { jsonrpc: '2.0', id: msg.id, result: toolText('# Workspace (server-side):\n' + (names.length ? names.join('\n') : '(no files)')) }; + } + // 桥内拦截(不占 vendor stdio;对 AI 不公示,见 DEPLOY_SKILL):watch/unwatch 仅本会话目录, + // unwatch --session <本会话id> 供 core 会话清理钩子,get-pos 改写原生回读,push 外链拉入 + const mr = /^(watch|unwatch|get-pos|push)\b([\s\S]*)$/.exec(cmd); + if (mr) { + const rest = String(mr[2] || '').trim(); + const file = watchArg(rest.replace(/(?:^|\s)--session(?:\s*=|\s+)\S+/g, ' ')); + const jail = sessDir ? path.resolve(sessDir) : watch.WORKSPACE; + const inJail = (x) => x && path.resolve(x).startsWith(jail + '/'); + try { + if (mr[1] !== 'push' && HIDDEN_SUBS.has(file)) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized(file)) }; + if (mr[1] === 'push') { + const toks = tokenizeCmd(rest) || []; + const url = String(toks[0] || ''); + const dest = toks[1] || ''; + if (!/^https?:\/\//i.test(url) || !dest) throw new Error('Usage: push (url is typically a link signed by mint_public_link)'); + const abs = pushTarget(dest, jail); + // 成功/失败文案只带相对文件名:工作区绝对路径对 AI 是干扰项(与任务目录同名不同盘) + let name = path.relative(jail, abs); if (name.startsWith('..')) name = path.basename(abs); + if (fs.existsSync(abs) && !/(?:^|\s)--force\b/.test(rest)) throw new Error('File already exists: ' + name + '. Use --force to overwrite.'); + // AI 视角是把文件「上传」进工作区,不说 download + let r; + try { r = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(PUSH_TIMEOUT_MS) }); } + catch (e) { throw new Error('Failed to read file: ' + String(e && e.message || e).slice(0, 120) + ' (link expired or unreachable? re-sign with mint_public_link and retry)'); } + if (!r.ok) throw new Error('Failed to read file: HTTP ' + r.status + ' (link expired? re-sign with mint_public_link and retry)'); + const data = Buffer.from(await r.arrayBuffer()); + if (data.length > PUSH_MAX_BYTES) throw new Error('File too large: limit is ' + Math.floor(PUSH_MAX_BYTES / 1048576) + ' MB'); + fs.mkdirSync(path.dirname(abs), { recursive: true }); + fs.writeFileSync(abs, data); + return { jsonrpc: '2.0', id: msg.id, result: toolText('Imported: ' + name) }; + } + if (mr[1] === 'watch') { + if (!file) throw new Error('Usage: watch '); + if (!inJail(file)) throw new Error('Preview is only available for documents inside the current session directory: ' + file); + // 预览链接是固定格式、前端自拼:url/path 不透给 AI 面 + const winfo = Object.assign({}, await watch.start(file, pubBase)); + delete winfo.url; delete winfo.path; + return { jsonrpc: '2.0', id: msg.id, result: toolText(winfo) }; + } + if (mr[1] === 'get-pos') { + if (!file) throw new Error('Usage: get-pos (works once the user opens the preview and selects something)'); + // 文件不存在:vendor 风格失败信封 {success:false, message},只报相对文件名,顺手带上两盘同步指引 + if (!fs.existsSync(path.resolve(file))) { + let nm = path.relative(jail, path.resolve(file)); if (nm.startsWith('..')) nm = path.basename(file); + return { jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: JSON.stringify({ + success: false, + message: 'File not found: ' + nm + '. If it lives in your task directory, sign a link with mint_public_link and pull it in with push .' + }, null, 2) }], isError: true } }; + } + // 没有预览槽在跑 = 没有选区来源:直接回空结果(信封与 vendor 一致:{success, data})。 + // watch 与否不需要 AI 关心,别把这事抛回给模型。 + if (![...watch.slots.values()].some((s) => s.file === path.resolve(file))) { + return { jsonrpc: '2.0', id: msg.id, result: toolText({ success: true, data: { matches: 0, results: [] } }) }; + } + cmd = 'get ' + quoteArg(file) + ' selected --json'; // 语义糖:改写为原生命令走原生回读实现 + args.command = cmd; + } else { + const msess = /(?:^|\s)--session(?:\s*=|\s+)(\S+)/.exec(rest); // core 会话清理专用:会话号必须等于本次请求的会话目录 + if (msess) { + const sid = decSafe(msess[1]); + // --purge(资源篮/core 删会话专用):杀槽之外连带删会话目录副本(幂等) + const purge = /(?:^|\s)--purge(?:\s|$)/.test(rest); + if (sid && sid === path.basename(jail)) return { jsonrpc: '2.0', id: msg.id, result: toolText(watch.stopSession(sid, purge)) }; + return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized('unwatch')) }; + } + if (!file) throw new Error('Usage: unwatch '); + if (!inJail(file)) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized('unwatch')) }; + return { jsonrpc: '2.0', id: msg.id, result: toolText(watch.stopOne(file)) }; + } + } catch (e) { + const t = String(e && e.message || e); + return { jsonrpc: '2.0', id: msg.id, result: toolErr(/文件不存在|not found/i.test(t) ? t + ' Hint: ' + SYNC_TEACH : t) }; + } + } + watch.touch(cmd); // 命中的预览槽位续命 + } + + try { + if (msg.method === 'initialize') { + if (!ready) { + // 子进程新鲜:客户端握手就是它的真握手(顺序天然正确) + const fresh = await rpc('initialize', msg.params || {}); + sendNotify('notifications/initialized', {}); + ready = true; fresh.id = msg.id; + return fresh; + } + // 子进程已被桥自举初始化:.NET SDK 不容二次握手、officecli 又单实例不容换新 —— 桥层合成应答 + return { jsonrpc: '2.0', id: msg.id, result: { + protocolVersion: (msg.params && msg.params.protocolVersion) || '2024-11-05', + capabilities: { tools: {} }, + serverInfo: { name: 'officecli', version: '1.0' } } }; + } + if (!ready) { await selfInit(); ready = true; } + const reply = await rpc(msg.method, msg.params || {}); + if (msg.method === 'tools/list' && reply.result && Array.isArray(reply.result.tools)) { + for (const t of reply.result.tools) { + if (t) t.description = String(t.description || '') + DESC_PATCH; // 部署侧须知随描述发给模型 + } + } + if (helpCmd) alignHelp(reply); // help 文本对齐可调用面:隐去命令删行,扩展命令补录 + if (msg.method === 'tools/call' && sessDir) { // 两份盘的教学与交付链都附在响应里(cmd 作用域仅限 tools/call 块,这里从参数重建) + const c = String((msg.params && msg.params.arguments || {}).command || ''); + teachOnMiss(c, reply); deliverNote(c, reply); ackNote(c, reply, sessDir); scrubErr(reply); + } + reply.id = msg.id; // 桥接 id 换回调用方 id + return reply; + } catch (e) { + try { if (child) child.kill(); } catch (_) {} + resetChild(); // 桥级失败(超时/进程死):换掉子进程,下次请求从干净状态重建 + return { jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: String(e && e.message || e) } }; + } +} + +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')) { + return json(res, 200, { name: SERVER_NAME, transport: 'streamable-http->stdio', preview: { port: PREVIEW_PORT, prefix: watch.PREFIX }, preview_slots: watch.status('') }); + } + if (req.method !== 'POST') return json(res, 404, { error: 'POST / only' }); + let body = ''; + req.on('data', (c) => { body += c; }); + req.on('end', () => { + let msg; try { msg = JSON.parse(body); } catch (_) { return json(res, 400, { error: 'bad json' }); } + handle(msg, String(req.headers['x-public-base'] || '').replace(/\/+$/, ''), String(req.headers['x-session-dir'] || '')).then((r) => { if (r === null) { res.writeHead(202).end(); return; } json(res, 200, r); }) + .catch((e) => json(res, 500, { error: String(e && e.message || e) })); + }); +}); + +// ---------- 优雅退出(容器 PID1 惯例,同 web_search) ---------- +function shutdown(sig) { + console.log(`[${SERVER_NAME}] 收到 ${sig},停止服务`); + try { if (child) child.kill(); } catch (_) {} + try { previewServer.close(); } catch (_) {} + server.close(() => process.exit(0)); + setTimeout(() => process.exit(0), 3000).unref(); +} +process.on('SIGTERM', () => shutdown('SIGTERM')); +process.on('SIGINT', () => shutdown('SIGINT')); + +const previewServer = gateway.start(PREVIEW_PORT, HOST); // 预览网关:单入口按任务路径路由,槽位号不出容器 + +server.listen(PORT, HOST, () => { + console.log(`${SERVER_NAME} HTTP listening on http://${HOST}:${PORT} (officecli mcp bridge, workspace=${watch.WORKSPACE}, slots=${process.env.OFFICE_SLOTS || 4}, preview=:${PREVIEW_PORT}${watch.PREFIX}/…)`); +}); diff --git a/mcp/officecli/watch.js b/mcp/officecli/watch.js new file mode 100644 index 0000000..53b7a07 --- /dev/null +++ b/mcp/officecli/watch.js @@ -0,0 +1,328 @@ +// watch 槽位管理:officecli watch 只绑 127.0.0.1(实测),且 watch 进程必须与 +// officecli MCP 子进程同容器(刷新信号 = 进程内 IPC,跨容器收不到)。 +// 本模块在 shim(容器 PID1)里 spawn watch 子进程 → 跨命令存活。 +// 不再开对外 TCP 转发口:预览路由交给 gateway.js —— url 按任务身份组织 +// (/preview/<会话id>/<文档相对路径>/),槽位号不出容器。 +// 槽位语义 = 可再生缓存而非承诺:链接按任务路径寻址,被回收/被别人挤掉后 +// 页面再访问由 gateway 就地复活(revive)。因此闲置阈值可以放心激进,AI 忘了 +// unwatch 不再有实质危害。 +'use strict'; +const net = require('node:net'); +const fs = require('node:fs'); +const path = require('node:path'); +const crypto = require('node:crypto'); +const { spawn } = require('node:child_process'); + +const WORKSPACE = process.env.OFFICE_WORKSPACE || '/workspace/tasks'; +const SLOTS = Number(process.env.OFFICE_SLOTS || 4); +const WATCH_BASE = Number(process.env.OFFICE_WATCH_BASE || 26315); // watch 自身端口(+slot),仅容器内回环 +const PREFIX = (process.env.OFFICE_PREVIEW_PREFIX || '/preview').replace(/\/+$/, ''); +const IDLE_MS = Number(process.env.OFFICE_IDLE_MS || 6 * 3600 * 1000); // 闲置回收阈值(默认 6h;槽=缓存,链接自愈,激进无副作用) +const EXTS = new Set(['.docx', '.xlsx', '.pptx']); + +const slots = new Map(); // slot -> {file, task, rel, port, watch, lastUsed, conns, pageDec, pageEnc} +const starting = new Map(); // 文件绝对路径 -> Promise:同文件并发 watch 合并为一次 spawn(watch 启动需秒级,窗口不窄) + +function log(...a) { console.log('[watch]', ...a); } + +// 路径护栏:限定 WORKSPACE 下的办公文档,禁止穿越 +function guard(p) { + const abs = path.resolve(WORKSPACE, String(p || '')); + const rel = path.relative(path.resolve(WORKSPACE), abs); + if (rel.startsWith('..') || path.isAbsolute(rel)) throw new Error('Path must be inside ' + WORKSPACE + ': ' + p); + if (!EXTS.has(path.extname(abs).toLowerCase())) throw new Error('Only .docx/.xlsx/.pptx files are supported: ' + p); + if (!fs.existsSync(abs)) throw new Error('File not found: ' + p); + return abs; +} + +// 文件 → 预览页前缀:WORKSPACE/<会话>/ → /<会话>/(另有分段编码形态供 url 用)。 +// 任务根下的文件没有预览页(url 必须挂在会话身份下,才能鉴权/稳定),要求至少两层。 +function pageOf(abs) { + const segs = path.relative(path.resolve(WORKSPACE), abs).split(path.sep).filter(Boolean); + if (segs.length < 2) throw new Error('Preview only supports files under a session directory (<' + WORKSPACE + '//...>): ' + abs); + return { + task: segs[0], + rel: segs.slice(1).join('/'), + pageDec: '/' + segs.join('/'), + pageEnc: '/' + segs.map((s) => encodeURIComponent(s)).join('/'), + }; +} + +function portUp(port, tries = 40) { + return new Promise((res, rej) => { + let n = 0; + (function probe() { + const s = net.connect(port, '127.0.0.1'); + s.on('connect', () => { s.destroy(); res(); }); + s.on('error', () => { s.destroy(); if (++n >= tries) return rej(new Error('watch server did not come up')); setTimeout(probe, 250); }); + })(); + }); +} + +async function start(file, publicBase) { + const abs = guard(file); + for (const [slot, s] of slots) if (s.file === abs) { s.lastUsed = Date.now(); return info(slot, publicBase); } + if (starting.has(abs)) { // vendor 限制同文件只许一个 watch:并发调用共享在飞的启动结果 + try { await starting.get(abs); } catch (_) {} + for (const [slot, s] of slots) if (s.file === abs) return info(slot, publicBase); + throw new Error('Failed to start watch (concurrent start for the same file); retry'); + } + const p = spawnWatch(abs, publicBase).finally(() => starting.delete(abs)); + starting.set(abs, p); + return p; +} + +async function spawnWatch(abs, publicBase) { + const page = pageOf(abs); // 先验证 url 可组织,再占坑 + let slot = -1; + for (let i = 0; i < SLOTS; i++) if (!slots.has(i)) { slot = i; break; } + if (slot < 0) { // 槽位满:优先踢「没有在看且最久未用」;全都有活动连接(= 页面开着)才抢最冷的活跃槽 + const ent = [...slots.entries()]; + const idle = ent.filter(([, s]) => !s.conns); + slot = (idle.length ? idle : ent).sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0][0]; + stop(slot); + } + const wp = WATCH_BASE + slot; + const child = spawn('officecli', ['watch', abs, '--port', String(wp)], { stdio: 'ignore' }); + child.on('exit', () => { if (slots.get(slot)?.watch === child) stop(slot); }); + const entry = { file: abs, task: page.task, rel: page.rel, port: wp, watch: child, lastUsed: Date.now(), conns: 0, pageDec: page.pageDec, pageEnc: page.pageEnc }; + slots.set(slot, entry); // 同步占坑:等端口就绪期间也不给并发 spawn 踩同一槽 + try { + await portUp(wp); + } catch (e) { + child.kill(); + if (slots.get(slot) === entry) slots.delete(slot); + throw new Error('Failed to start watch (only one watch per file is allowed): ' + e.message); + } + log(`slot${slot} ${abs} watch:${wp} page=${PREFIX}${page.pageDec}`); + return info(slot, publicBase); +} + +function stop(slot) { + const s = slots.get(slot); + if (!s) return false; + try { s.watch.kill(); } catch (_) {} + slots.delete(slot); + log(`slot${slot} 已停止`); + return true; +} + +function stopOne(file) { + const abs = guard(file); + for (const [slot, s] of slots) if (s.file === abs) { stop(slot); return { stopped: abs }; } + throw new Error('No watch running for this file: ' + abs); +} + +// command 透传时顺带给命中的槽位续命(AI 活跃 = 预览还有人关心) +function touch(command) { + for (const s of slots.values()) if (String(command || '').includes(s.file)) s.lastUsed = Date.now(); +} + +function info(slot, publicBase) { + const s = slots.get(slot); + return { + slot: slot, file: s.file, + path: PREFIX + s.pageEnc + '/', + url: (publicBase || '') + PREFIX + s.pageEnc + '/', + idle_min: Math.round((Date.now() - s.lastUsed) / 60000), // 闲置分钟(watch ls 给模型/用户看活性) + conns: s.conns || 0, // 正在回传的预览请求数(SSE 在场 = 页面开着) + }; +} + +// gateway 路由用:rel = 已解码、剥掉 PREFIX 的请求路径(以 / 开头); +// exact = 正好是页面本身(缺尾斜杠由 gateway 补 301),prefix = 页面下的资源/端点。最长前缀优先。 +function matchPage(rel) { + if (!rel) return null; + const rr = rel.startsWith('/') ? rel : '/' + rel; + let best = null; + for (const s of slots.values()) { + if (rr === s.pageDec) return { entry: s, exact: true }; + if (rr.startsWith(s.pageDec + '/')) { + if (!best || s.pageDec.length > best.entry.pageDec.length) best = { entry: s, exact: false }; + } + } + return best; +} + +function status(publicBase) { + return [...slots.keys()].map((slot) => info(slot, publicBase)); +} + +// 会话结束批量清理:core 删会话时经桥打一发 unwatch --session <会话id> [--purge]。 +// --purge:连带删除该会话在本工作区的目录副本(任务真相在 core/executor 侧,这里只是可再生 scratch); +// purge 语义下幂等:无槽/目录不存在都不报错,只在会话号非法时拒(防穿越)。 +function stopSession(taskId, purge) { + const t = String(taskId || ''); + const stopped = []; + for (const [slot, s] of slots) if (s.task === t) { stop(slot); stopped.push(s.file); } + let purged = false; + if (purge) { + if (!t || t === '.' || t === '..' || /[/\\]/.test(t) || t.includes('\0')) throw new Error('Invalid session id.'); + const dir = path.join(path.resolve(WORKSPACE), t); + if (path.relative(path.resolve(WORKSPACE), dir) !== t) throw new Error('Invalid session id.'); + if (fs.existsSync(dir)) { try { fs.rmSync(dir, { recursive: true, force: true }); purged = true; log('会话 purge:', t); } catch (_) {} } + } + if (!stopped.length && !purge) throw new Error('No watch running for this session: ' + t); + return { session: t, stopped, purged }; +} + +// gateway 未命中兜底:请求路径本身就是一个存在的会话文档 → 回收/被挤掉后就地复活。 +// 只接受整体形如办公文档的路径(扩展名把关);/api/… 等资源路径无扩展名 → null,404 语义不变。 +async function revive(rel) { + const rr = (rel || '').replace(/\/+$/, ''); + if (!rr || rr === '/') return null; + try { + await start(path.join(WORKSPACE, rr)); // guard/pageOf 复核越界、存在性、会话层级;不行 = 维持原 404 + return matchPage(rr); + } catch (_) { return null; } +} + +// 纯路径推导预览页地址(无需 watch 在场;布局不满足——越界/任务根下——返回 null) +function pageUrl(abs, publicBase) { + const rel = path.relative(path.resolve(WORKSPACE), abs); + if (!rel || rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) return null; + let page; + try { page = pageOf(abs); } catch (_) { return null; } + const p = PREFIX + page.pageEnc + '/'; + return { path: p, url: (publicBase || '') + p }; +} + +// ---------- /f/ 交付能力链:save/close 成功时签发(同 core /p/ 的设计:随机 id + TTL,URL 即能力)---------- +const DL_TTL_MS = Number(process.env.OFFICE_DL_TTL_MS || 30 * 60 * 1000); +const DL_MAX = 512; +const dls = new Map(); // token -> { abs, exp } +const MIME = { + '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', + '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', + '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation', +}; + +function dlMint(abs) { + const now = Date.now(); + for (const [k, v] of dls) if (v.exp <= now) dls.delete(k); + // 同一文件重复 save/close 复用原 token(滑动 TTL):serveDl 实时读盘,链接永远指向盘上最新内容,AI 改完重新下载原链即可 + for (const [k, v] of dls) if (v.abs === abs) { v.exp = now + DL_TTL_MS; return k; } + while (dls.size >= DL_MAX) dls.delete(dls.keys().next().value); + const token = crypto.randomBytes(16).toString('base64url'); + dls.set(token, { abs, exp: now + DL_TTL_MS }); + return token; +} + +function serveDl(token, req, res) { + const e = token ? dls.get(token) : null; + if (!e || e.exp <= Date.now()) { + if (e) dls.delete(token); + res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('Link not found or expired. Run save on the file again to issue a new link.'); + return; + } + let st; + try { st = fs.statSync(e.abs); } catch (_) { + dls.delete(token); + res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('File is no longer in the workspace; save or push it again first'); + return; + } + if (!st.isFile()) { res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('File is no longer in the workspace; save or push it again first'); return; } + const base = path.basename(e.abs); + const ascii = base.replace(/[^\x20-\x7e]|["\\]/g, '_') || 'document'; + res.writeHead(200, { + 'content-type': MIME[path.extname(base).toLowerCase()] || 'application/octet-stream', + 'content-length': String(st.size), + 'content-disposition': 'attachment; filename="' + ascii + '"; filename*=UTF-8\'\'' + encodeURIComponent(base), + 'cache-control': 'no-store', + }); + fs.createReadStream(e.abs).pipe(res); +} + +// ---------- scratch 卫生:这份盘只是工作副本(交付真相在 core 的 tasks),两道闸:闲置 TTL + 容量水位 ---------- +const SCRATCH_TTL_MS = Number(process.env.OFFICE_SCRATCH_TTL_MS || 7 * 24 * 3600 * 1000); +// 容量水位:总量(含 busy)超上限时,按目录最新 mtime 从旧到新删非 busy 目录,删到低水位为止。 +// busy(正开预览)永不触碰,宁可短时超水位也不打扰活跃会话;编辑即落盘会把 mtime 刷新,活跃会话天然排最后。 +const SCRATCH_MAX_BYTES = Number(process.env.OFFICE_SCRATCH_MAX_BYTES || 2 * 1073741824); // 0 = 关 +const SCRATCH_LOW_RATIO = 0.8; + +function newestMtime(dir, budget) { // 目录树最新 mtime;budget 封顶防巨目录卡住定时器 + let best = 0; + try { best = fs.statSync(dir).mtimeMs; } catch (_) { return 0; } + const stack = [dir]; + while (stack.length && budget.n > 0) { + const d = stack.pop(); + let ents; + try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { continue; } + for (const en of ents) { + if (budget.n-- <= 0) break; + const p = path.join(d, en.name); + if (en.isSymbolicLink()) continue; + if (en.isDirectory()) { stack.push(p); continue; } + try { const m = fs.statSync(p).mtimeMs; if (m > best) best = m; } catch (_) {} + } + } + return best; +} + +function dirSize(dir, budget) { // 目录树总字节;budget 封顶,截断时偏小(水位是粗粒度启发式,可接受) + let total = 0; + const stack = [dir]; + while (stack.length && budget.n > 0) { + const d = stack.pop(); + let ents; + try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { continue; } + for (const en of ents) { + if (budget.n-- <= 0) break; + const p = path.join(d, en.name); + if (en.isSymbolicLink()) continue; + if (en.isDirectory()) { stack.push(p); continue; } + try { total += fs.statSync(p).size; } catch (_) {} + } + } + return total; +} + +function pruneScratch() { + if (!(SCRATCH_TTL_MS > 0) && !(SCRATCH_MAX_BYTES > 0)) return []; + const now = Date.now(); + const busy = new Set([...slots.values()].map((s) => path.relative(WORKSPACE, s.file).split(path.sep)[0])); + let tops; + try { tops = fs.readdirSync(WORKSPACE, { withFileTypes: true }); } catch (_) { return []; } + const removed = []; + // 道闸一:闲置 TTL(整目录最新 mtime 超时即回收) + if (SCRATCH_TTL_MS > 0) { + for (const en of tops) { + if (!en.isDirectory() || en.isSymbolicLink() || busy.has(en.name)) continue; + const dir = path.join(WORKSPACE, en.name); + const m = newestMtime(dir, { n: 800 }); + if (m && now - m > SCRATCH_TTL_MS) { + try { fs.rmSync(dir, { recursive: true, force: true }); removed.push(en.name); } catch (_) {} + } + } + } + // 道闸二:容量水位总量超限则从旧到新删非 busy 目录,删到低水位或候选耗尽 + if (SCRATCH_MAX_BYTES > 0) { + const infos = []; + let total = 0; + for (const en of tops) { + if (!en.isDirectory() || en.isSymbolicLink()) continue; + const dir = path.join(WORKSPACE, en.name); + const size = dirSize(dir, { n: 4000 }); + total += size; + if (!busy.has(en.name) && !removed.includes(en.name)) infos.push({ name: en.name, dir, size, m: newestMtime(dir, { n: 800 }) }); + } + infos.sort((a, b) => a.m - b.m); + const lowLimit = SCRATCH_MAX_BYTES * SCRATCH_LOW_RATIO; + for (const it of infos) { + if (total <= lowLimit) break; + try { fs.rmSync(it.dir, { recursive: true, force: true }); total -= it.size; removed.push(it.name); } catch (_) {} + } + } + if (removed.length) log('scratch 清理:', removed.join(', ')); + return removed; +} +setInterval(pruneScratch, 3600 * 1000).unref(); +setTimeout(pruneScratch, 10000).unref(); // 重启后不等整点,早扫一轮 + +setInterval(() => { + const now = Date.now(); + // 有活动连接的槽 = 有人正开着页面,永不闲置回收(槽满时它最后被抢,见 spawnWatch) + for (const [slot, s] of slots) if (!s.conns && now - s.lastUsed > IDLE_MS) { log(`slot${slot} 闲置回收`); stop(slot); } +}, 60000).unref(); + +module.exports = { start, stop, stopOne, stopSession, touch, status, guard, slots, IDLE_MS, matchPage, revive, pageUrl, dlMint, serveDl, pruneScratch, DL_TTL_MS, WORKSPACE, PREFIX }; From 4dd51ba18cf143fb363bd8d0da482f452752dd22 Mon Sep 17 00:00:00 2001 From: kicer Date: Mon, 19 Oct 2026 00:23:28 +0800 Subject: [PATCH 38/41] =?UTF-8?q?=E4=BC=98=E5=8C=96=E5=9B=BD=E5=86=85?= =?UTF-8?q?=E8=AE=BF=E9=97=AE=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/officecli/Dockerfile | 15 +++++++++++++++ mcp/officecli/scripts/entrypoint.sh | 16 +++++++++++++--- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/mcp/officecli/Dockerfile b/mcp/officecli/Dockerfile index 2510f83..171db8d 100644 --- a/mcp/officecli/Dockerfile +++ b/mcp/officecli/Dockerfile @@ -1,5 +1,20 @@ FROM node:22-slim +# 国内构建慢:apt/pip 默认源在国外,apt-get update 能卡十几分钟。默认换成腾讯云镜像。 +# 境外构建或想换源:docker compose build --build-arg DEBIAN_MIRROR=deb.debian.org +# 腾讯云 CVM 上想更快可用内网镜像 mirrors.tencentyun.com(仅腾讯云内网可达)。 +ARG DEBIAN_MIRROR=mirrors.cloud.tencent.com + +# 换 apt 源:bookworm 可能是 /etc/apt/sources.list,也可能是 deb822 的 /etc/apt/sources.list.d/*.sources, +# 直接用 grep 扫一遍、只替换域名,两种格式都盖住(路径 /debian、/debian-security 保持不变)。 +RUN set -eux; \ + files="$(grep -rl 'deb.debian.org' /etc/apt/ 2>/dev/null || true)"; \ + if [ -n "$files" ]; then sed -i "s|deb.debian.org|${DEBIAN_MIRROR}|g" $files; fi; \ + grep -rn "${DEBIAN_MIRROR}" /etc/apt/ | head -5 || true + +# TZ=Asia/Shanghai:统一时区。 +ENV TZ=Asia/Shanghai + # libssl3: officecli is a .NET self-contained binary and hard-requires libssl. # ICU is NOT needed: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 disables globalization. # curl: the entrypoint fetches the officecli binary at FIRST boot (image intentionally diff --git a/mcp/officecli/scripts/entrypoint.sh b/mcp/officecli/scripts/entrypoint.sh index 1c59c2e..da4d08b 100755 --- a/mcp/officecli/scripts/entrypoint.sh +++ b/mcp/officecli/scripts/entrypoint.sh @@ -42,16 +42,26 @@ tmp="$(mktemp "${BIN_DIR}/.dl.XXXXXX")" # 与目标同目录:最后 m trap 'rm -f "${tmp}"' EXIT for url in "${urls[@]}"; do - log "trying ${url}" - if curl -fsSL --connect-timeout 10 --retry 1 --max-time 600 -o "${tmp}" "${url}"; then + log "trying ${url} (connect<=10s, speed>=10KB/s, max 300s)" + t0=$(date +%s) + if curl -fL \ + --connect-timeout 10 \ + --max-time 300 \ + --speed-limit 102400 \ + --speed-time 20 \ + --retry 1 \ + --progress-bar \ + -o "${tmp}" "${url}"; then got="$(sha256sum "${tmp}" | awk '{print $1}')" if [ "${got}" = "${SHA256}" ]; then chmod +x "${tmp}" mv -f "${tmp}" "${BIN}" - log "officecli ${VERSION} installed -> ${BIN}" + log "officecli ${VERSION} installed -> ${BIN} ($(( $(date +%s) - t0 ))s)" exec "$@" fi log "sha256 mismatch (got ${got}), trying next source" + else + log "failed after $(( $(date +%s) - t0 ))s: ${url}" fi rm -f "${tmp}" done From db27ade2ac6a5ce0400aa1e5e7bbdb00179a94d0 Mon Sep 17 00:00:00 2001 From: kicer Date: Mon, 19 Oct 2026 09:11:16 +0800 Subject: [PATCH 39/41] =?UTF-8?q?=E5=8A=A0=E5=85=A5=E9=A2=84=E8=A7=88?= =?UTF-8?q?=E5=8D=A1=E7=89=87=E6=94=AF=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/officecli/README.md | 1 + mcp/officecli/server.js | 20 ++++++++++++++++++-- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/mcp/officecli/README.md b/mcp/officecli/README.md index fad43e8..231362e 100644 --- a/mcp/officecli/README.md +++ b/mcp/officecli/README.md @@ -53,6 +53,7 @@ mcp_officecli:3100 gateway.js ——按路径找槽位、改写 Host/Origin 回 - url 按任务组织:文档必须在会话目录下(`/<会话id>/…`,任务根下不可预览);重启换槽不影响链接含义。 - 预览 url 不由本服务下发:链接按固定格式 `<公网前缀>/preview/<会话id>/<文档相对路径>/` 由前端自拼;`X-Public-Base` 仅供桥内 watch 状态/日志用,对 AI 的回包里 `url`/`path` 字段已被剥掉。 +- 回包可附通用 UI 卡片块 `{type:'ui_card', action, arg, title?, note?}`(非 text:core 的 MCP 层剥离后不进模型面,整块经 SSE `ui_card` 转前端,动作注册表驱动渲染)。当前动作 `open_preview`:arg=相对会话目录的文件路径,聊天流出可点卡片直接开预览窗(无需等文件回任务盘);create/open/push 成功自动附带(文案由产生方给)。卡片为实时事件不落库,刷新后从任务文件列表进入。 - 槽位数 `OFFICE_SLOTS`(默认 4);满了优先踢「无活动连接且最久未用」;闲置超 `OFFICE_IDLE_MS`(默认 6h)回收,挂着活动连接的槽不回收;预览每一帧回传与 AI 命令都会续命。 - 槽位是缓存不是承诺:预览链接按任务路径寻址,被回收/挤占后页面再访问由网关就地复活(一次冷启动)。 - AI 面不公示 watch/unwatch(也没有 watch ls / --all 这类跨会话动作):预览完全由前端拼链接、网关按需复活槽位 + LRU 管理;core 删会话时经校验的 `unwatch --session --purge` 清槽并删工作区目录副本(不等 scratch TTL)。 diff --git a/mcp/officecli/server.js b/mcp/officecli/server.js index 63e3f80..9788ed7 100644 --- a/mcp/officecli/server.js +++ b/mcp/officecli/server.js @@ -161,7 +161,9 @@ function ackNote(cmd, reply, sessDir) { const t = (tokenizeCmd(cmd) || []).find((x) => x.startsWith(watch.WORKSPACE + '/') && OFFICE_EXT_RE.test(x)); if (!t) return; const jail = sessDir && sessDir.startsWith('/') ? path.resolve(sessDir) : ''; - first.text = verb + ': ' + (jail && t.startsWith(jail + '/') ? path.relative(jail, t) : path.basename(t)); + const jailRel = jail && t.startsWith(jail + '/') ? path.relative(jail, t) : ''; + first.text = verb + ': ' + (jailRel || path.basename(t)); + if (jailRel) attachPreviewCard(res, verb === 'Created' ? 'created' : 'opened', jailRel); } // 失败文案整形:剥掉工作区路径前缀只留文件名(与任务目录同名不同盘,全路径只会诱发误判); @@ -348,6 +350,18 @@ function toolErr(msg) { return { content: [{ type: 'text', text: 'Error: ' + (msg && msg.message || String(msg)) }], isError: true }; } + +// create/open/push 成功附带一个通用 ui_card 块(action=open_preview):core 的 MCP 层剥离后不进模型面, +// 经 SSE ui_card 转聊天流可点卡片。后续其它命令/其它服务出卡片走同一协议: +// {type:'ui_card', action, arg, title?, note?}。arg 相对会话目录(前端 openFilePreview 拼预览链接 +// 正好用);组不出会话目录则不附。卡片的展示文案由产生方负责(前端只做动作分发)。 +const CARD_NOTE = { created: '已创建', opened: '已打开', imported: '已导入' }; +function attachPreviewCard(res, op, rel) { + if (!res || !Array.isArray(res.content)) return; + if (!rel || rel === '.' || rel.startsWith('..')) return; + res.content.push({ type: 'ui_card', action: 'open_preview', arg: rel, title: rel, note: CARD_NOTE[op] || '' }); +} + async function handle(msg, pubBase, sessDir) { // pubBase/sessDir:调用方每请求注入(X-Public-Base / X-Session-Dir) const isReq = msg.id !== undefined && msg.id !== null; let helpCmd = false; // 本次调用是否为 help 族:透传后要把文本对齐可调用面 @@ -434,7 +448,9 @@ async function handle(msg, pubBase, sessDir) { // pubBase/sessDir:调用方每 if (data.length > PUSH_MAX_BYTES) throw new Error('File too large: limit is ' + Math.floor(PUSH_MAX_BYTES / 1048576) + ' MB'); fs.mkdirSync(path.dirname(abs), { recursive: true }); fs.writeFileSync(abs, data); - return { jsonrpc: '2.0', id: msg.id, result: toolText('Imported: ' + name) }; + const pushRes = { jsonrpc: '2.0', id: msg.id, result: toolText('Imported: ' + name) }; + if (sessDir) attachPreviewCard(pushRes.result, 'imported', path.relative(path.resolve(sessDir), abs)); + return pushRes; } if (mr[1] === 'watch') { if (!file) throw new Error('Usage: watch '); From 8232236fc88d1cf7d2dc33827a33f83d46442513 Mon Sep 17 00:00:00 2001 From: kicer Date: Mon, 19 Oct 2026 11:29:04 +0800 Subject: [PATCH 40/41] =?UTF-8?q?officecli=20=E4=B8=8B=E7=BA=BF=EF=BC=9AMC?= =?UTF-8?q?P=20=E6=9C=8D=E5=8A=A1=E9=80=80=E5=BD=B9=EF=BC=8C=E8=83=BD?= =?UTF-8?q?=E5=8A=9B=E6=95=B4=E4=BD=93=E8=BF=81=E5=85=A5=20agent=20?= =?UTF-8?q?=E4=BE=A7=20skills/office=20+=20executor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 跨容器双盘同步(push/mint 外链/save 取件链)随容器边界消失,officecli 直接读写任务文件 - 预览槽位+网关迁入 agent/executor/preview.js,core 反代上游切至 agent-executor:3100 - 二进制由 skills/office/install.sh 按技能资产约定拉到技能卷(不进 git/不进 mcp 镜像) --- mcp/README.md | 10 +- mcp/docker-compose.yml | 25 -- mcp/officecli/Dockerfile | 44 --- mcp/officecli/README.md | 120 ------ mcp/officecli/gateway.js | 89 ----- mcp/officecli/package.json | 8 - mcp/officecli/scripts/entrypoint.sh | 74 ---- mcp/officecli/server.js | 567 ---------------------------- mcp/officecli/watch.js | 328 ---------------- 9 files changed, 1 insertion(+), 1264 deletions(-) delete mode 100644 mcp/officecli/Dockerfile delete mode 100644 mcp/officecli/README.md delete mode 100644 mcp/officecli/gateway.js delete mode 100644 mcp/officecli/package.json delete mode 100755 mcp/officecli/scripts/entrypoint.sh delete mode 100644 mcp/officecli/server.js delete mode 100644 mcp/officecli/watch.js diff --git a/mcp/README.md b/mcp/README.md index b7ac8ef..cfa8e55 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -1,16 +1,12 @@ # MCP 服务集合 -四个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: +三个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: | 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 | |---|---|---|---|---| | `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` | | `image_task/` | `mcp_image_task` | 智谱 CogView 图片生成(单工具 op=create) | `3000` | `POST /mcp` | | `video_task/` | `mcp_video_task` | 智谱 CogVideo 视频生成(异步,单工具 op=create/get) | `3000` | `POST /mcp` | -| `officecli/` | `mcp_officecli` | Office 文档(docx/xlsx/pptx)创建修改 + 浏览器实时预览 | `3000`/`3100` | `POST /` | - -officecli 的预览页面同样不占宿主机端口:浏览器走 agent-core 的通用预览反代 -`/preview/<会话id>/<文档>/…`(登录 cookie 门禁),链路与槽位细节见 `officecli/README.md`。 **这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor` 按容器名访问。所以整台服务器对外只需要开 agent-core 那一个端口(`AGENT_PORT`,默认 8090)。 @@ -34,9 +30,6 @@ cd /root/workspace/tools/mcp && docker compose up -d --build `image_task` / `video_task` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 (agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥。 -`officecli` 与 agent **不共盘**:工作区是独立 scratch 卷(容器内布局同构 `/workspace/tasks/<会话id>/...`, -容器对会话数据盲视),数据交换只走桥的 push(mint 外链拉入)/ save 交付链(AI 在自己会话目录 curl 回写);且要先起 agent(external 网络 `agent-mcp-net` 由 agent 的 compose 创建)。 - ### 环境变量 写在仓库顶层 `.env` 里即可(不写就用默认值): @@ -73,7 +66,6 @@ AI 把拿到的 URL 当 image_url 交给 video_task:3000/mcp | `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | | `mcp_image_task` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | | `mcp_video_task` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 | -| `mcp_officecli` | 无 | MCP 口与预览网关口都只在内网;预览页由 agent-core 通用预览反代加登录 cookie 门禁 | ## 单独调试 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index 710653a..7c1c7ef 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -32,27 +32,6 @@ services: networks: - agent-mcp-net - mcp_officecli: - build: ./officecli - container_name: mcp_officecli - restart: unless-stopped - environment: - # 关自动 resident:实测对时延零增益(瓶颈是 .NET 进程启动),换来无 file_locked 冲突、无常驻进程堆积 - - OFFICECLI_NO_AUTO_RESIDENT=1 - # 每次改动命令返回前落盘(含 open 起的 resident):编辑即自动保存,save/close 只为签发取件链接 - - OFFICECLI_RESIDENT_FLUSH=each - # scratch 卫生:闲置 7 天整目录回收;容量水位 2G(超限按目录 mtime 从旧到新删,删到 80% 为止) - - OFFICE_SCRATCH_TTL_MS=604800000 - - OFFICE_SCRATCH_MAX_BYTES=2147483648 - volumes: - # officecli 二进制缓存:entrypoint 首启拉取(镜像内 pin 版本+sha256,每次启动都校验),容器重建不重拉;down -v 后下次启动自动重拉;纯离线机改 bind 挂载手工放置(见 officecli/README) - - officecli-bin:/opt/officecli - # 刻意不挂 ../agent/tasks:容器对会话数据盲视,只有自己的 scratch 工作区(布局同构 /workspace/tasks/<会话id>/...)。 - # 与交付区的数据交换全部经 push(拉 mint 外链进来)/ pull(AI 在 executor 里执行 curl 写回自己目录)。 - - office-scratch:/workspace/tasks - networks: - - agent-mcp-net - networks: # 与 agent 仓库共用:网络由 agent 的 compose 创建并命名(所以要先起 agent), # 这里声明为 external 直接加入。agent-core / agent-executor 按容器名访问这些服务。 @@ -60,7 +39,3 @@ networks: external: true volumes: - # officecli 工作区:丢了不要紧(push/pull 流程会重建),down -v 即清空 - office-scratch: - # officecli 二进制缓存:丢了也不要紧,下次启动 entrypoint 自动重新拉取 - officecli-bin: diff --git a/mcp/officecli/Dockerfile b/mcp/officecli/Dockerfile deleted file mode 100644 index 171db8d..0000000 --- a/mcp/officecli/Dockerfile +++ /dev/null @@ -1,44 +0,0 @@ -FROM node:22-slim - -# 国内构建慢:apt/pip 默认源在国外,apt-get update 能卡十几分钟。默认换成腾讯云镜像。 -# 境外构建或想换源:docker compose build --build-arg DEBIAN_MIRROR=deb.debian.org -# 腾讯云 CVM 上想更快可用内网镜像 mirrors.tencentyun.com(仅腾讯云内网可达)。 -ARG DEBIAN_MIRROR=mirrors.cloud.tencent.com - -# 换 apt 源:bookworm 可能是 /etc/apt/sources.list,也可能是 deb822 的 /etc/apt/sources.list.d/*.sources, -# 直接用 grep 扫一遍、只替换域名,两种格式都盖住(路径 /debian、/debian-security 保持不变)。 -RUN set -eux; \ - files="$(grep -rl 'deb.debian.org' /etc/apt/ 2>/dev/null || true)"; \ - if [ -n "$files" ]; then sed -i "s|deb.debian.org|${DEBIAN_MIRROR}|g" $files; fi; \ - grep -rn "${DEBIAN_MIRROR}" /etc/apt/ | head -5 || true - -# TZ=Asia/Shanghai:统一时区。 -ENV TZ=Asia/Shanghai - -# libssl3: officecli is a .NET self-contained binary and hard-requires libssl. -# ICU is NOT needed: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 disables globalization. -# curl: the entrypoint fetches the officecli binary at FIRST boot (image intentionally -# does NOT vendor the binary -> nothing to pre-run after clone, `docker compose up` is the whole entry). -RUN apt-get update -qq \ - && apt-get install -y -qq --no-install-recommends libssl3 ca-certificates curl \ - && rm -rf /var/lib/apt/lists/* - -WORKDIR /app - -# Zero npm deps: node shim (server.js + watch.js + gateway.js). -# scripts/entrypoint.sh downloads the pinned officecli into /opt/officecli (named volume -# `officecli-bin`, cached across restarts; sha256 verified every boot, GitHub -> gh-proxy fallback) -# then execs CMD. /opt/officecli goes first in PATH so the shim still spawns bare `officecli`. -COPY package.json server.js watch.js gateway.js ./ -COPY scripts/entrypoint.sh /app/scripts/entrypoint.sh -RUN chmod +x /app/scripts/entrypoint.sh - -ENV PATH=/opt/officecli:${PATH} -ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 -ENV OFFICE_WORKSPACE=/workspace/tasks -ENV PORT=3000 - -EXPOSE 3000 - -ENTRYPOINT ["/app/scripts/entrypoint.sh"] -CMD ["node", "server.js"] diff --git a/mcp/officecli/README.md b/mcp/officecli/README.md deleted file mode 100644 index 231362e..0000000 --- a/mcp/officecli/README.md +++ /dev/null @@ -1,120 +0,0 @@ -# officecli - -Office 文档(.docx / .xlsx / .pptx)创建、检视、修改 + 浏览器实时预览的 MCP 服务。 - -上游开源 CLI:[officecli](https://d.officecli.ai)(.NET self-contained 单文件二进制,**不进 git 也不进镜像**;容器首次启动由 `scripts/entrypoint.sh` 拉取到命名卷缓存,pin 版本 + 每次启动 sha256 校验)。 -本目录是一个**零 npm 依赖**的 node shim:把 officecli 自带的 stdio 形态 MCP 桥成 -Streamable HTTP,外加一个按任务路径路由的预览网关。 - -- 协议:MCP **Streamable HTTP**,端点 `POST /`(任何路径都收) -- 鉴权:**无服务端鉴权**,只挂 `agent-mcp-net`(公网必须经 agent-core 登录门禁反代进来),永远不要映射出去 -- 端口:`3000`(MCP)+ `3100`(预览网关,单入口);`26315..26318` 是 watch 进程内部回环端口,不出容器 - -## 结构 - -| 文件 | 职责 | -| --- | --- | -| `server.js` | 入口(容器 PID1):常驻 `officecli mcp` stdio 子进程 + JSON-RPC id 重映射;命令治理(绝对化 / 隐去命令 / 扩展命令 / help 对齐,见下);save/close 附交付取件链、文件缺失附同步教学;桥级失败自动换子进程 | -| `watch.js` | 预览槽位管理:spawn `officecli watch`(只绑 127.0.0.1,vendor 限制),url 按任务组织,槽位号不出容器;`/f/` 交付能力链签发与取件;scratch 过期清理 | -| `gateway.js` | 预览网关(:3100):按路径把请求路由到槽位 watch;Referer 兜底 vendor 页面硬编码的根绝对 API;Host/Origin 成对改写回环自源 + 头白名单 | -| `scripts/entrypoint.sh` | 容器入口(ENTRYPOINT):确保二进制就位(`/opt/officecli`,compose 挂命名卷 `officecli-bin` 缓存;pin 在本文件,镜像升级=版本升级;源链 GitHub → gh-proxy 备源,可 `OFFICECLI_URL`/`OFFICECLI_MIRROR` 加源)→ exec 服务命令;拉不到 fail fast 教手动动作 | - -## 工具面与命令治理 - -只有**一个工具** `officecli`(command 字符串或 argv 数组,原样交给 CLI;schema 查询 `{"command":"help docx paragraph"}`)。 -模型看到的描述 = vendor 原文 + 一句扩展命令能力陈述;**行为约束全部代码化,不写教条**: - -| 机制 | 行为 | -| --- | --- | -| 相对路径自动绝对化 | 调用方(agent-core)每请求带 `X-Session-Dir`,裸文件名/相对路径自动补全会话目录(`key=value` 属性值亦可,如 `src=a.png`;AI 无感,与 terminal 直觉一致);`--type picture` 的 `path=` 属性自动别名为 vendor 真名 `src=` | -| 隐去命令(报原生风格 `Unrecognized command or argument 'X'.`,help 清单同步对齐:删隐去行、补录扩展行) | `mcp`(自锁死)、`skills` / `install` / `plugins`(装环境类);`watch` 的 mark/unmark/marks/goto 子命令同理 | -| `view` 渲染族屏蔽 | 其它模式(outline/stats/issues/text/annotated)照常透传;仅渲染族 `view html` / `screenshot` / `svg` / `pdf` / `forms`(需无头浏览器/导出插件)拦截,返回 `view is disabled by environment policy. Use 'view outline' or 'view issues' for structural/semantic checks.` | -| 回包文案 | `create` / `open` / `push` 成功只回 `Created/Opened/Imported: <相对会话目录文件名>`;预览链接不随回包出现(固定格式 `<公网前缀>/preview/<会话id>/<相对路径>/`,前端自己拼,AI 面不需要知道);`save` / `close` 成功附 `download url:`(限时取件链,同文件复用同一链接);失败文案剥掉工作区路径前缀与 vendor 异常包装,只留文件名 | -| 桥内拦截(对 AI 不公示) | `watch` / `unwatch ` 仅本会话目录(必须拦截:vendor 原生 watch 会占死 stdio;help 里同步不显示);`unwatch --session [--purge]` 校验 id==X-Session-Dir 尾段,core 会话清理钩子专用 [--purge 杀槽外连带删会话目录副本,幂等];`get-pos ` 改写原生 `get … selected --json`;`push ` 外链拉入(http(s) only、100MB、非覆盖需 `--force`;读不到外链时报「读取文件失败」而非「下载失败」——AI 视角是上传) | -| 用法指引投递 | `load_skill office-preview` 只讲:get-pos / 两份盘同步;不出现 watch、不出现预览 url | - -`get` / `query` / `set` 等短命令照常透传(与槽位 watch 进程同容器 IPC 直达);`get-pos` 即桥内改写的 `get … selected --json`。 - -## 预览链路(为什么 watch 必须待在本容器) - -刷新信号 = officecli watch 进程内的 IPC,所以 watch 只能与 officecli 同容器; -槽位进程由shim(容器 PID1)托管才能跨 MCP 调用存活。浏览器不直连本容器, -必须经 agent-core 的通用预览反代(登录 cookie 即门禁,对外依旧只开 core 一个端口): - -``` -用户浏览器(已登录 agent) - │ https:///preview/<会话id>/<文档相对路径>/... - ▼ -agent-core routes/preview-proxy.js(注册表驱动,信任模型同 data-page) - │ 头白名单转发(Referer 兜底 vendor 页面的根绝对 /api/*、/events) - ▼ -mcp_officecli:3100 gateway.js ——按路径找槽位、改写 Host/Origin 回环自源──► 127.0.0.1:26315+N officecli watch -``` - -- url 按任务组织:文档必须在会话目录下(`/<会话id>/…`,任务根下不可预览);重启换槽不影响链接含义。 -- 预览 url 不由本服务下发:链接按固定格式 `<公网前缀>/preview/<会话id>/<文档相对路径>/` 由前端自拼;`X-Public-Base` 仅供桥内 watch 状态/日志用,对 AI 的回包里 `url`/`path` 字段已被剥掉。 -- 回包可附通用 UI 卡片块 `{type:'ui_card', action, arg, title?, note?}`(非 text:core 的 MCP 层剥离后不进模型面,整块经 SSE `ui_card` 转前端,动作注册表驱动渲染)。当前动作 `open_preview`:arg=相对会话目录的文件路径,聊天流出可点卡片直接开预览窗(无需等文件回任务盘);create/open/push 成功自动附带(文案由产生方给)。卡片为实时事件不落库,刷新后从任务文件列表进入。 -- 槽位数 `OFFICE_SLOTS`(默认 4);满了优先踢「无活动连接且最久未用」;闲置超 `OFFICE_IDLE_MS`(默认 6h)回收,挂着活动连接的槽不回收;预览每一帧回传与 AI 命令都会续命。 -- 槽位是缓存不是承诺:预览链接按任务路径寻址,被回收/挤占后页面再访问由网关就地复活(一次冷启动)。 -- AI 面不公示 watch/unwatch(也没有 watch ls / --all 这类跨会话动作):预览完全由前端拼链接、网关按需复活槽位 + LRU 管理;core 删会话时经校验的 `unwatch --session --purge` 清槽并删工作区目录副本(不等 scratch TTL)。 -- 同一文件同时只允许一个 watch(vendor 限制;同文件并发 watch 已合并为一次启动)。 - -## 两份盘与同步(push / download url) - -容器工作区与 `agent/tasks/<会话id>/` 是两份盘;桥负责在响应里教会 AI 换盘动线(拦截即教学,不设协议): - -| 方向 | 动线 | 执行者 | -| --- | --- | --- | -| 任务目录 → 工作区 | `mint_public_link` 签发外链 → `officecli push ` | 桥拉入(护栏:WORKSPACE 内、白名单扩展名(office/图片/常见数据)、100MB、非覆盖需 --force) | -| 工作区 → 任务目录 | `save ` / `close ` 回包尾附 `download url` → AI 在自己终端下载 | AI(executor 的会话 jail 天然框住写路径,core 零改动零新 API) | - -- 每次改动命令返回前落盘(compose 置 `OFFICECLI_RESIDENT_FLUSH=each`):编辑即自动保存,save/close 的主要作用只是签发取件链。 -- 成功/失败文案只带相对文件名,不出现工作区绝对路径:工作区与任务目录同名不同盘,全路径极易让 AI 误判文件落点。 - -- 取件链 `GET /f/<随机id>`:与 core `/p/` 同款能力链(随机不可猜 + TTL + 只吐 guard 过的路径),只在内部网络可达(core 反代只转 `/preview`,公网够不着)。同一文件重复 save/close 复用原 token(滑动 TTL,链接永远指向盘上最新内容)。过期 404 文案提示重新 save。 -- vendor 命令报"文件不存在"且引用路径确实缺失时,桥在错误尾附 push/交付动线提示;`X-Session-Dir` 首次出现时桥顺手 mkdir 会话目录。 -- core 会话删除时 `engine.deleteSession` 尽力打一发 `unwatch --session <会话id> --purge`(`mcp.notifyTool`,失败只记日志):桥端杀预览槽 + 删 `tasks/<会话id>` 工作区副本,幂等。 - -## 请求头契约(调用方 → 本服务) - -| 头 | 说明 | -| --- | --- | -| `X-Public-Base` | core 公网前缀(已归一),仅供桥内 watch 状态展示;预览 url 不再下发给 AI,缺省也无影响 | -| `X-Session-Dir` | 本次调用的会话工作目录,用于裸文件名/相对路径补全;core 的 mcp.js 从工具执行 ctx 自动注入,其它 MCP 服务忽略即可 | - -## 环境变量 - -| 变量 | 默认 | 说明 | -| --- | --- | --- | -| `OFFICE_WORKSPACE` | `/workspace/tasks` | 容器内工作区根(独立 scratch 卷,布局同构 `/<会话id>/...`;与 core 的 tasks 不同盘,数据交换只走 push / save 交付链) | -| `OFFICE_SLOTS` | `4` | 预览槽位数(内部端口段宽度) | -| `OFFICE_IDLE_MS` | `21600000`(6h) | 槽位闲置回收阈值;有活动预览连接的槽不回收,链接再访问自动复活 | -| `OFFICE_PREVIEW_PORT` | `3100` | 预览网关端口(与 core 注册表对齐) | -| `OFFICE_PREVIEW_PREFIX` | `/preview` | 预览 url 的路径前缀(与 core 注册表 prefix 一致) | -| `OFFICECLI_TIMEOUT_MS` | `120000` | 单次 MCP 请求等 officecli 回包的上限,超时 换子进程 | -| `OFFICE_DL_BASE` | `http://mcp_officecli:3100` | download url 的前缀(executor 可达的内网地址;改服务名时覆盖) | -| `OFFICE_DL_TTL_MS` | `1800000`(30min) | 取件链有效期,过期 404 并提示重新 save | -| `OFFICE_SCRATCH_TTL_MS` | `604800000`(7d) | scratch 会话目录闲置清理阈值(每小时一次 + 启动后 10s 首扫;槽位占用的目录不碰;0=关) | -| `OFFICE_SCRATCH_MAX_BYTES` | `2147483648`(2G) | scratch 容量水位:总量超限时按目录 mtime 从旧到新删非 busy 目录,删到 80% 为止(0=关) | -| `OFFICECLI_NO_AUTO_RESIDENT` | compose 置 `1` | 关 vendor 自动 resident:实测时延零增益,消掉 file_locked 冲突与常驻进程堆积(vendor 未公开变量,help 只写 `OFFICECLI_RESIDENT_FLUSH`) | -| `OFFICECLI_RESIDENT_FLUSH` | compose 置 `each` | 每次改动命令返回前落盘(含 open 起的 resident):编辑即自动保存,save/close 只为签发取件链 | - -## 部署与调试 - -`docker-compose.yml` 中的 `mcp_officecli` 服务构建本目录;工作区用独立命名卷 `office-scratch`, -**刻意不挂 `../agent/tasks`**:容器对会话数据盲视,泄漏面归零;容器内路径仍同构 `/workspace/tasks/<会话id>/...`,AI 无感。 - -二进制不进库也不进镜像:首次启动 entrypoint 自动拉取到命名卷 `officecli-bin`(容器重建不重拉;每次启动 sha256 秒级校验;版本 pin 在 `scripts/entrypoint.sh`,改版本=改文件重新 build)。GitHub 不通自动落 gh-proxy 备源;都失败则启动 fail fast(日志教手动动作,`unless-stopped` 重启即重试);`down -v` 清卷后下次启动自动重拉。 - -**离线放置**:GitHub 与备源都不可达的机器,把同名二进制放进挂载目录即可(sha256 对上就认):`docker cp mcp_officecli:/opt/officecli/officecli` 后 restart,或把 compose 里 `officecli-bin` 卷换成 bind 挂载。 - -```bash -docker compose up -d --build mcp_officecli # clone 后即可直接起;首启多一次二进制下载(仅首次) -# MCP 健康检查(含预览槽位列表) -docker exec mcp_officecli node -e "fetch('http://localhost:3000/').then(r=>r.json()).then(j=>console.log(JSON.stringify(j)))" -#预览网关健康检查 -docker exec mcp_officecli node -e "fetch('http://localhost:3100/gateway-healthz').then(r=>r.text()).then(console.log)" -``` - -agent 侧两处登记(缺一不可):`config.yml` 的 `mcp_servers: [{name: officecli, url: "http://mcp_officecli:3000/"}]`; -core 预览注册表默认已含 officecli(`routes/preview-proxy.js`,改 config.yml 后重启 core 生效)。 diff --git a/mcp/officecli/gateway.js b/mcp/officecli/gateway.js deleted file mode 100644 index 278d816..0000000 --- a/mcp/officecli/gateway.js +++ /dev/null @@ -1,89 +0,0 @@ -// 预览网关:单入口端口(:OFFICE_PREVIEW_PORT,默认 3100)按路径路由到槽位 watch —— 槽位号不出容器。 -// 主路由:/<会话id>/<文档相对路径>/** → 槽位注册表最长前缀匹配 → 转发该槽位 watch。 -// 自愈:路由未命中但请求路径本身是存在的会话文档 → 就地复活 watch(watch.revive)—— -// 槽位只是缓存不是承诺,闲置回收/被别的会话挤掉后,页面再访问 = 正常冷启动。 -// 兜底:vendor 预览页把交互 API 硬编码成根绝对路径(/api/selection、/events…)→ 按 Referer 找回槽位,原样转发。 -// masquerade:头白名单 + Host/Origin 成对改写为目标回环自源(watch 自带 DNS-rebinding/跨源防护); -// 凭据永不转发(core 那层已过滤,这里是容器内第二道防线)。 -'use strict'; -const http = require('node:http'); -const watch = require('./watch'); - -const PREFIX = watch.PREFIX; -// 上游(watch)确实用得到的头;cookie/authorization/referer/sec-fetch/user-agent 等一律不进 -const PASS = new Set(['accept', 'accept-encoding', 'cache-control', 'pragma', 'content-type', 'content-length', 'last-event-id', 'if-modified-since', 'if-none-match']); - -function forwardTo(entry, req, res, innerPath) { // innerPath:页面内相对路径(主路由剥前缀)或根绝对原路径(Referer 兜底),不再二次加工 - const selfHost = '127.0.0.1:' + entry.port; - const fwd = { host: selfHost }; - for (const k of Object.keys(req.headers)) if (PASS.has(k)) fwd[k] = req.headers[k]; - if (req.headers.origin) fwd.origin = 'http://' + selfHost; - const qpos = req.url.indexOf('?'); - const search = qpos >= 0 ? req.url.slice(qpos) : ''; - const inner = innerPath.startsWith('/') ? innerPath : '/' + innerPath; - // 槽位续命信号:建连即续,此后每帧回传再续(SSE 是长连接,只在建连那刻续会把长驻页面误判成闲置)。 - // conns 记「正在回传」的请求数:conns>0 = 有人正开着预览页,闲置回收/槽位挤占都绕着它走。 - entry.lastUsed = Date.now(); - entry.conns = (entry.conns || 0) + 1; - let released = false; - const release = () => { if (!released) { released = true; entry.conns = Math.max(0, entry.conns - 1); } }; - res.once('close', release); - res.once('finish', release); - const upstream = http.request( - { host: '127.0.0.1', port: entry.port, path: encodeURI(inner) + search, method: req.method, headers: fwd }, - (up) => { - const h = Object.assign({}, up.headers); - if (String(h['content-type'] || '').includes('text/event-stream')) { h['cache-control'] = 'no-cache'; h['x-accel-buffering'] = 'no'; } - res.writeHead(up.statusCode, h); - up.on('data', () => { entry.lastUsed = Date.now(); }); // 含 SSE 心跳/事件帧:任何回传 = 上游活着 - up.pipe(res); - }); - upstream.on('error', () => { - if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }).end('预览槽位不可达(可能刚停止或已到期回收)'); - else res.destroy(); - release(); // 上面两条终结路径各自触发 close/finish 前,这里幂等兜底 - }); - req.pipe(upstream); -} - -function matchReferer(req) { - const ref = req.headers.referer || req.headers.referrer || ''; - if (!ref) return null; - try { - const rp = decodeURIComponent(new URL(ref).pathname); - if (!rp.startsWith(PREFIX + '/')) return null; - return watch.matchPage(rp.slice(PREFIX.length)); - } catch (_) { return null; } -} - -function start(port, host) { - return http.createServer((req, res) => { - route(req, res).catch(() => { if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' }).end('预览网关内部错误'); }); - }).listen(port, host); -} - -async function route(req, res) { - let u; - try { u = decodeURIComponent((req.url || '/').split('?')[0]); } catch (_) { res.writeHead(400).end('bad path'); return; } - if (req.method === 'GET' && u === '/gateway-healthz') { - const body = JSON.stringify({ ok: true, prefix: PREFIX, slots: watch.status('').length }); - res.writeHead(200, { 'content-type': 'application/json' }).end(body); - return; - } - if (req.method === 'GET' && u.startsWith('/f/')) return watch.serveDl(decodeURIComponent(u.slice(3)), req, res); // 交付取件口:URL 即能力,只在内部网络可达(core 反代只转 /preview) - if (u === PREFIX + '/' || u.startsWith(PREFIX + '/')) { - const rel = u.slice(PREFIX.length) || '/'; - let m = watch.matchPage(rel); - if (!m) m = await watch.revive(rel); // 槽=缓存:页面重开/冷槽就地复活 - if (m) { - if (m.exact && !u.endsWith('/')) { res.writeHead(301, { location: (req.url || u) + '/' }).end(); return; } // 相对路径资源解析需要尾斜杠 - const cut = PREFIX.length + m.entry.pageDec.length; // 剥掉「前缀+页面路径」才是 watch 的内层路径 - return forwardTo(m.entry, req, res, u.length > cut ? u.slice(cut) : '/'); - } - } - const viaRef = matchReferer(req); // vendor 页面的根绝对 API:Referer 找回来源槽位,原路径原样转发(不剥页面前缀!) - if (viaRef) return forwardTo(viaRef.entry, req, res, u); - res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('无匹配预览(文档不存在/不在会话目录下,或不是 .docx/.xlsx/.pptx;若文档在任务目录里,先 officecli push 进来)'); -} - -module.exports = { start }; diff --git a/mcp/officecli/package.json b/mcp/officecli/package.json deleted file mode 100644 index 8179d05..0000000 --- a/mcp/officecli/package.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "name": "officecli-mcp", - "version": "0.1.0", - "private": true, - "description": "Streamable-HTTP MCP shim bridging officecli mcp (stdio) + live preview slots", - "main": "server.js", - "scripts": { "start": "node server.js" } -} diff --git a/mcp/officecli/scripts/entrypoint.sh b/mcp/officecli/scripts/entrypoint.sh deleted file mode 100755 index da4d08b..0000000 --- a/mcp/officecli/scripts/entrypoint.sh +++ /dev/null @@ -1,74 +0,0 @@ -#!/usr/bin/env bash -# 容器入口:确保 officecli 二进制就位(命名卷缓存)→ exec 真正的服务命令。 -# -# - 二进制不进 git 也不进镜像:首次启动下载到 /opt/officecli(compose 挂命名卷 officecli-bin), -# 之后每次启动只做 sha256 秒级校验,容器重建不重复下载;卷删了(down -v)下次启动自动重拉。 -# - 信任锚是镜像里的 pin(本脚本写死版本+sha256;镜像升级=版本升级): -# 缓存有效性 = 实际 sha256 与 pin 一致——换版本后旧缓存自动作废,无需额外标记文件。 -# - 源链(依次尝试,产物一律过 sha256):OFFICECLI_URL 整URL覆盖 → GitHub → gh-proxy 备源 → OFFICECLI_MIRROR 前缀。 -# - 离线兜底:往挂载目录放一份同名二进制即可(sha 对上就认),见 README「离线放置」。 -# - 拉取失败:fail fast 非零退出(unless-stopped 重启即重试),日志教手动动作。 -set -euo pipefail - -VERSION="${OFFICECLI_VERSION:-v1.0.157}" -SHA256="${OFFICECLI_SHA256:-f8eefe88dbfa7464bee421e5421efe57fc26bc3180b30e56eef58594c8245c94}" -ASSET="officecli-linux-x64" -GH_URL="https://github.com/iOfficeAI/OfficeCLI/releases/download/${VERSION}/${ASSET}" - -BIN_DIR="${OFFICECLI_DIR:-/opt/officecli}" -BIN="${BIN_DIR}/officecli" - -log() { echo "[officecli-fetch] $*"; } - -sha_ok() { printf '%s %s\n' "${SHA256}" "$1" | sha256sum -c --status - >/dev/null 2>&1; } - -# 缓存命中 = 可执行 + sha256 与镜像内 pin 一致(顺带覆盖 docker cp / 手工放置的兜底场景) -if [ -x "${BIN}" ] && sha_ok "${BIN}"; then - log "officecli ${VERSION} in place (${BIN}); skip fetch" - exec "$@" -fi - -urls=() -if [ -n "${OFFICECLI_URL:-}" ]; then urls+=("${OFFICECLI_URL}"); fi -urls+=( "${GH_URL}" "https://gh-proxy.com/${GH_URL}" ) -if [ -n "${OFFICECLI_MIRROR:-}" ]; then - p="${OFFICECLI_MIRROR}"; case "${p}" in */) ;; *) p="${p}/";; esac - urls+=( "${p}${GH_URL}" ) -fi - -mkdir -p "${BIN_DIR}" -rm -f "${BIN_DIR}"/.dl.* 2>/dev/null || true # 清理上次被中断的半成品 -tmp="$(mktemp "${BIN_DIR}/.dl.XXXXXX")" # 与目标同目录:最后 mv 原子就位,中断永远不会留下残缺拷贝 -trap 'rm -f "${tmp}"' EXIT - -for url in "${urls[@]}"; do - log "trying ${url} (connect<=10s, speed>=10KB/s, max 300s)" - t0=$(date +%s) - if curl -fL \ - --connect-timeout 10 \ - --max-time 300 \ - --speed-limit 102400 \ - --speed-time 20 \ - --retry 1 \ - --progress-bar \ - -o "${tmp}" "${url}"; then - got="$(sha256sum "${tmp}" | awk '{print $1}')" - if [ "${got}" = "${SHA256}" ]; then - chmod +x "${tmp}" - mv -f "${tmp}" "${BIN}" - log "officecli ${VERSION} installed -> ${BIN} ($(( $(date +%s) - t0 ))s)" - exec "$@" - fi - log "sha256 mismatch (got ${got}), trying next source" - else - log "failed after $(( $(date +%s) - t0 ))s: ${url}" - fi - rm -f "${tmp}" -done - -log "FATAL: officecli ${VERSION} 所有源都拉不到(或校验不过)。" -log " asset: ${GH_URL}" -log " sha256: ${SHA256}" -log " 手动放置(sha 对上就认):docker cp <本地二进制> mcp_officecli:${BIN} && docker compose restart mcp_officecli" -log " 或把 compose 里 officecli-bin 卷换成 bind 挂载(./某目录:${BIN_DIR})离线放置,再 up -d。" -exit 1 diff --git a/mcp/officecli/server.js b/mcp/officecli/server.js deleted file mode 100644 index 9788ed7..0000000 --- a/mcp/officecli/server.js +++ /dev/null @@ -1,567 +0,0 @@ -// officecli MCP 服务 shim —— Streamable HTTP(:3000) ⇄ officecli mcp(stdio) 桥。 -// -// 为什么需要这么一层:officecli 的 MCP 只有 stdio 形态;且 watch(预览)必须与 -// officecli 同容器(刷新信号=进程内 IPC)、与 shim 同父(躲开任何命令级进程回收)。 -// 本进程是容器 PID1:常驻 officecli mcp 子进程 + watch.js 管槽位 watch 子进程。 -// -// 工具面:单工具 officecli(command 字符串透传 + 桥内命令治理):create/open/push 成功只回文件名确认, -// 预览链接固定格式由前端自拼(AI 面不出现 url);save/close 自带 download url,点选回读 get-pos;watch/unwatch 桥内拦截但不向 AI 公示 -//(必须拦截:vendor 原生 watch 会占死 stdio;且仅开放本会话目录);隐去命令报原生风格 Unrecognized, -// help 同步对齐可见面;用法指引走 load_skill office-preview(见 DEPLOY_SKILL),零教条。 -// 环境变量:OFFICE_WORKSPACE(= /workspace/tasks)、OFFICE_SLOTS(=4)、OFFICE_PREVIEW_PORT(=3100)。 -// 公网 url 前缀不配置在这里:调用方(agent-core)每请求用 X-Public-Base 头注入(真相只在 core 一处), -// 会话工作目录同理经 X-Session-Dir 头注入(裸文件名自动补全会话目录,AI 无感)。 -'use strict'; -const http = require('node:http'); -const { createServer } = http; -const fs = require('node:fs'); -const path = require('node:path'); -const { spawn } = require('node:child_process'); - -// 启动自检:officecli 缺失/不可执行不在首个 MCP 请求时以诡异超时现身——PID1 直接 fail fast 并教部署动作。 -if (!(process.env.PATH || '').split(':').some((d) => { try { fs.accessSync(path.join(d, 'officecli'), fs.constants.X_OK); return true; } catch (_) { return false; } })) { - console.error("[bridge] FATAL: officecli binary not found in PATH (expected /opt/officecli/officecli,由 entrypoint 拉取就位)。" - + "查 [officecli-fetch] 启动日志;离线放置见 officecli/README「离线放置」(sha256 对上就认)。"); - process.exit(1); -} - -const watch = require('./watch'); -const gateway = require('./gateway'); - -const PORT = Number(process.env.PORT || 3000); -const PREVIEW_PORT = Number(process.env.OFFICE_PREVIEW_PORT || 3100); -const HOST = process.env.HOST || '0.0.0.0'; -const CALL_TIMEOUT_MS = Number(process.env.OFFICECLI_TIMEOUT_MS || 120000); -const SERVER_NAME = 'officecli-mcp'; - -// ---------- stdio 桥:单条常驻 officecli mcp 子进程 ---------- -let child = null; -let ready = false; // officecli 子进程是否已完成 initialize 握手 -let buf = ''; -let seq = 0; -const pending = new Map(); // bridge id -> {res 回调, timer:http 等待方} - -function resetChild() { - for (const [, p] of pending) { clearTimeout(p.timer); p.reject(new Error('officecli process exited, retry')); } - pending.clear(); buf = ''; child = null; ready = false; -} - -function ensureChild() { - if (child) return child; - // cwd 进共享卷:否则相对路径产物落在容器根 fs(/app),core/executor 都看不见 - child = spawn('officecli', ['mcp'], { stdio: ['pipe', 'pipe', 'inherit'], cwd: watch.WORKSPACE }); - const me = child; // 身份守卫:只有当前子进程的 exit 才重置桥(换新后的旧进程迟到的 exit 不得误伤) - child.stdout.on('data', (d) => { - buf += d; let i; - while ((i = buf.indexOf('\n')) >= 0) { - const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1); - if (!line) continue; - let msg; try { msg = JSON.parse(line); } catch (_) { continue; } - if (msg.id !== undefined && pending.has(msg.id)) { - const p = pending.get(msg.id); pending.delete(msg.id); - clearTimeout(p.timer); p.resolve(msg); - } else if (msg.method) { - console.log('[bridge] officecli 通知:', msg.method); // 桥接侧暂无需处理 - } - } - }); - me.on('exit', (code) => { console.log('[bridge] officecli mcp 退出', code); if (child === me) resetChild(); }); - return child; -} -// 向 officecli 子进程发一条 JSON-RPC 请求并等回包(id 重映射,多 HTTP 请求并发安全) -function rpc(method, params) { - return new Promise((resolve, reject) => { - const c = ensureChild(); - const id = ++seq; - const timer = setTimeout(() => { - if (!pending.has(id)) return; - pending.delete(id); reject(new Error('Timeout waiting for officecli response: ' + method)); - }, CALL_TIMEOUT_MS); - pending.set(id, { resolve, reject, timer }); - c.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); - }); -} - -function sendNotify(method, params) { - const c = ensureChild(); - c.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); -} - -// 桥自己补一次 initialize 握手(兜底:子进程重建后,客户端还没发过 initialize 就来请求) -async function selfInit() { - await rpc('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'officecli-mcp-shim', version: '0' } }); - sendNotify('notifications/initialized', {}); -} - -// 会话 id 从预览 url 拷回来时可能是百分号编码形态;解不动就用原样(id 字符集本不需编码) -function decSafe(s) { try { return decodeURIComponent(s); } catch (_) { return s; } } - -// ---------- 部署面治理:隐藏命令报原生风格 unrecognized,help 同步对齐(AI 眼里 = 原生 CLI)---------- -const unrecognized = (v) => "Unrecognized command or argument '" + v + "'."; -const HIDDEN_SUBS = new Set(['mark', 'unmark', 'marks', 'goto']); // 标注/滚动族:本部署只保留 watch / watch ls / unwatch / get-pos -const HIDDEN_VERBS = 'mcp|skills|install|plugins'; // 与 handle 里的 mblk 黑名单同步(view 已放开,只拦 html/screenshot 渲染模式) -const HIDDEN_LINE = /^ {2}(?:mcp|skills|install|plugins)\b/; // 注意:绝不能用字符串拼 RegExp,'\b' 在 JS 字符串里是退格符 -const HELP_STRIP = /^ {2}(?:watch|unwatch)\b/; // 预览已自动化(create/open/push 附链接):help 也不出示 watch/unwatch,防 AI 想起没用过的命令 -const VIEW_BLOCKED = new Set(['html', 'screenshot', 'svg', 'pdf', 'forms']); // view 渲染族:需无头浏览器/导出插件,本环境一律屏蔽 - -// push 护栏:目标必须落在 WORKSPACE 内且是白名单扩展名(office + 资源图 + 常见数据;目标可以尚不存在,故不复用 watch.guard)。 -// 裸相对名以会话目录为基准(absolutize 只处理 office/图片,其余允许类型若按 WORKSPACE 根解会落到会话外,与回执/files 列表不一致); -// 显式绝对路径仍可指向工作区任意位置(既有设计)。pushTarget(p, base):base 越界时退回 WORKSPACE。 -function pushTarget(p, base) { - const wsRoot = path.resolve(watch.WORKSPACE); - const root = base && path.resolve(base).startsWith(wsRoot + path.sep) ? path.resolve(base) : wsRoot; - const abs = path.resolve(root, String(p || '')); - const rel = path.relative(wsRoot, abs); - if (!rel || rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) throw new Error('Target must be inside the workspace (' + watch.WORKSPACE + '): ' + p); - if (!PUSH_EXT_RE.test(abs)) throw new Error('Unsupported file type: ' + p + '. Allowed: office (.docx/.xlsx/.pptx), images (png/jpg/jpeg/gif/webp/bmp/tiff), pdf/csv/txt/json/md'); - return abs; -} -const PUSH_TIMEOUT_MS = 60000; -const PUSH_MAX_BYTES = 100 * 1024 * 1024; - -// 交付取件链接前缀:executor 与本源同网,AI 终端里的 curl 直接用它(改名部署时用 env 覆盖) -const DL_BASE = (process.env.OFFICE_DL_BASE || 'http://mcp_officecli:' + PREVIEW_PORT).replace(/\/+$/, ''); -const SYNC_TEACH = 'Your task directory and the officecli workspace are two separate disks. To edit a file that already ' - + 'exists in your task directory: sign a link for it with mint_public_link, then run officecli push ' - + 'to sync it in. When done editing, save the file and download the returned download url back into your task directory.'; - -// help 照透传,但文本过一道:隐去的命令行删掉、桥扩展命令补进 Commands 清单(可见面 = 可调用面) -const HELP_ADD = [ - ' get-pos Read what the user selected in the live preview (returns JSON).', - ' push Download an http(s) URL into the workspace as .', - ' files List files under the current workspace directory (server-side).', -]; -function alignHelp(reply) { - const items = reply && reply.result && Array.isArray(reply.result.content) ? reply.result.content : []; - for (const it of items) { - if (!it || typeof it.text !== 'string' || !it.text.includes('Commands:')) continue; - const text = it.text.replace(/ ?Subcommands \(mark\/unmark\/marks\/goto\) operate on the running preview\./g, ''); - const out = []; - let added = false; - for (const ln of text.split('\n')) { - if (HIDDEN_LINE.test(ln) || HELP_STRIP.test(ln)) continue; - out.push(ln); - if (!added && /^ {2}help\s/.test(ln)) { out.push(...HELP_ADD); added = true; } - } - if (!added) out.push(...HELP_ADD); - it.text = out.join('\n'); - } -} - -// 成功回执三词式:vendor 原文带工作区绝对路径(与 AI 任务目录同名不同盘,极易误判落点),统一替换成 -// "Created/Opened: <相对会话目录文件名>"。预览链接是固定格式(<公网前缀>/preview/<会话id>/<相对路径>/), -// 调用方自拼,不再随回包附带。 -function ackNote(cmd, reply, sessDir) { - const verb = /^create\b/.test(cmd) ? 'Created' : /^open\b/.test(cmd) ? 'Opened' : ''; - if (!verb) return; - const res = reply && reply.result; - if (!res || res.isError || !Array.isArray(res.content)) return; - const first = res.content.find((c) => c && typeof c.text === 'string'); - if (!first) return; - const t = (tokenizeCmd(cmd) || []).find((x) => x.startsWith(watch.WORKSPACE + '/') && OFFICE_EXT_RE.test(x)); - if (!t) return; - const jail = sessDir && sessDir.startsWith('/') ? path.resolve(sessDir) : ''; - const jailRel = jail && t.startsWith(jail + '/') ? path.relative(jail, t) : ''; - first.text = verb + ': ' + (jailRel || path.basename(t)); - if (jailRel) attachPreviewCard(res, verb === 'Created' ? 'created' : 'opened', jailRel); -} - -// 失败文案整形:剥掉工作区路径前缀只留文件名(与任务目录同名不同盘,全路径只会诱发误判); -// 顺带拆掉 vendor resident 异常包装("Resident process exited. Unhandled exception: X.CliException: …")只留内层真错 -const WS_PATH_RE = new RegExp(watch.WORKSPACE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/(?:[^\\s\'"`,;:()()]+/)*', 'g'); -function scrubErr(reply) { - const res = reply && reply.result; - if (!res || !res.isError || !Array.isArray(res.content)) return; - for (const c of res.content) { - if (!c || typeof c.text !== 'string') continue; - c.text = c.text - .replace(/Resident process exited\.\s*Unhandled exception:\s*[\w.]*Exception:\s*/g, '') - .replace(WS_PATH_RE, ''); - } -} - -// 透传报错误且引用的工作区路径确实不存在:十有八九是文件只在任务目录里 —— 拦截即教学(push 方向) -function teachOnMiss(cmd, reply) { - const res = reply && reply.result; - if (!res || !res.isError) return; - const txt = (res.content || []).map((c) => (c && c.text) || '').join(' '); - if (/unrecognized/i.test(txt)) return; - const toks = tokenizeCmd(cmd) || []; - // key=value 属性里的路径同样检查(如 src=/workspace/…):缺失才附同步教学 Hint - if (!toks.some((x) => { const v = x.includes('=') && !x.slice(0, x.indexOf('=')).includes('/') ? x.slice(x.indexOf('=') + 1) : x; return v.startsWith(watch.WORKSPACE + '/') && !fs.existsSync(v); })) return; - const first = (res.content || []).find((c) => c && typeof c.text === 'string'); - if (first) first.text += '\nHint: ' + SYNC_TEACH; -} - -// save/close 是 AI 的原生收尾仪式:成功时附限时取件链接(同 core /p/:URL 即能力),下载回任务目录的动作留给 AI -function deliverNote(cmd, reply) { - if (!/^(save|close)\b/.test(cmd)) return; - const res = reply && reply.result; - if (!res || res.isError || !Array.isArray(res.content)) return; - const toks = (tokenizeCmd(cmd) || []).filter((t) => t.startsWith(watch.WORKSPACE + '/') && OFFICE_EXT_RE.test(t) && fs.existsSync(t)); - if (!toks.length) return; - const first = res.content.find((c) => c && typeof c.text === 'string'); - if (!first) return; - first.text += toks.map((t) => '\ndownload url: ' + DL_BASE + '/f/' + watch.dlMint(t)).join(''); -} - -// ---------- 预览伪命令(桥内拦截,不落 vendor 进程)---------- -// watch 族命令不走透传(常驻服务占死 stdio 会挂满超时):从命令尾取文件参数,跳过旗标,支持引号 -function watchArg(rest) { - let s = String(rest || '').trim(); - s = s.replace(/^--port(?:\s*=|\s+)\S+\s*/, ''); - s = s.replace(/\s+--port(?:\s*=|\s+)\S+/, ''); - const m = /^"([^"]*)"|^'([^']*)'|^(\S+)/.exec(s); - return m ? (m[1] !== undefined ? m[1] : m[2] !== undefined ? m[2] : m[3]) : ''; -} - -// ---------- 命令治理:路径自动绝对化 / 黑名单 / 部署技能(能用代码处理的绝不写成提示词) ---------- -const quoteArg = (s) => (/[\s"'\\]/.test(s) ? "'" + s.replace(/'/g, "'\\''") + "'" : s); - -// 引号感知分词;引号不闭合返回 null(调用方放弃改写,不动原命令) -function tokenizeCmd(s) { - const out = []; let cur = null, q = null; - for (const c of s) { - if (q) { if (c === q) q = null; else cur += c; continue; } - if (c === '"' || c === "'") { if (cur === null) cur = ''; q = c; continue; } - if (/\s/.test(c)) { if (cur !== null) { out.push(cur); cur = null; } continue; } - if (cur === null) cur = ''; - cur += c; - } - if (q !== null) return null; - if (cur !== null) out.push(cur); - return out; -} - -const OFFICE_EXT_RE = /\.(?:docx|xlsx|pptx)$/i; -// 资源图(插图命令的参数)也要绝对化:vendor cwd 是工作区根而非会话目录,裸 logo.png 会错解到 /workspace/logo.png -const RESOURCE_EXT_RE = /\.(?:png|jpe?g|gif|webp|bmp|tiff?)$/i; -// --input 类数据文件同样要绝对化:原生 cwd 是工作区根而非会话目录,裸名永远碰不到会话目录里的文件 -const DATA_EXT_RE = /\.(?:json|csv|tsv|txt|md)$/i; -// push 目标类型白名单:office + 资源图 + 常见数据;服务端不落盘执行任何内容,风险主要是工作区积灰,白名单聊胜于无 -const PUSH_EXT_RE = /\.(?:docx|xlsx|pptx|pdf|csv|txt|json|md|png|jpe?g|gif|webp|bmp|tiff?)$/i; -function absToken(t, sess) { - if (!t || t.startsWith('-') || t.startsWith('/') || /:\/\//.test(t)) return t; - // key=value 属性(如 src=a.png):只对值部分绝对化再拼回 key= 前缀;整体拼会把 src= 也吃进路径 - let key = ''; - let val = t; - const eq = t.indexOf('='); - if (eq > 0 && !t.slice(0, eq).includes('/')) { key = t.slice(0, eq + 1); val = t.slice(eq + 1); } - if (!val || val.startsWith('-') || val.startsWith('/') || /:\/\//.test(val)) return t; - const core = val.replace(/^(?:\.\.?\/)+/, ''); - if (!OFFICE_EXT_RE.test(core) && !RESOURCE_EXT_RE.test(core) && !DATA_EXT_RE.test(core)) return t; - return key + sess + '/' + core; -} -// 裸文件名/相对路径 → 会话目录绝对路径(X-Session-Dir);没有实际改动时原样返回,最小侵入 vendor 解析 -function absolutize(cmd, sessDir) { - if (!sessDir || !sessDir.startsWith('/')) return cmd; - const sess = sessDir.replace(/\/+$/, ''); - const toks = tokenizeCmd(cmd); - if (!toks) return cmd; - let changed = false; - const out = toks.map((t) => { const a = absToken(t, sess); if (a !== t) changed = true; return a; }); - return changed ? out.map(quoteArg).join(' ') : cmd; -} - -// 用法指引:只讲 AI 用得上的(预览链接是固定格式、前端自拼,AI 面不出现 url;也从不要求 AI 主动 watch) -const DEPLOY_SKILL = `# office-preview usage - -## Read back the user's selection -get-pos -Returns the structured node the user selected in the live preview. The @id= in its path stays stable across later edits; use it directly with set / get to target the change. - -## Sync: your task directory and the workspace are two separate disks -Check: files lists what the workspace (server side) already holds. -Pull in: to edit a file that already exists in your task directory, sign its link with mint_public_link first, then push . -Hand back: every edit is flushed to disk automatically. Before delivery, save to get the download url and download it into your task directory; if you edit again afterwards, save and download again. close does the same.`; - -// tools/list 时追加的唯一一句:能力 + 指针,零教条(规矩全在代码与错误文案里) -const DESC_PATCH = '\n\nExtensions: push pulls a URL file into the workspace; files lists the files already inside the workspace (server side); get-pos reads back what the user selected in the live preview; every edit is auto-saved to disk; before delivery run save and download the returned download url into your task directory. Full usage: load_skill office-preview.'; -// ---------- Streamable HTTP 入口 ---------- -// vendor 的 picture 类型收图片属性名为 src,AI 惯写 path=(会被报 'src' property is required): -// --type picture/image 时把属性键 path= 别名成 src=(token 层替换,不碰值) -// --commands 内联 JSON 保护:分词器按 POSIX 规则吞词中引号,绝对化触发整行重组后 -// JSON 会被剥光双引号(原生报 invalid start of property name)。在分词前从原始串 -// 扫描出配平的 JSON,单引号包裹后放回(原生认单引号包裹,含内部双引号/空格)。 -// 但原生不认 POSIX 的单引号转义 '\'':JSON 内含 ' 时改写会话目录点文件走 --input -// (绝对路径通道已实测可靠;点文件对 files 隐藏,随会话 purge/TTL 回收)。 -// 解析不了就原样放行,桥不装懂。 -function quoteInlineJson(cmd, sessDir) { - const m = /(^|\s)--commands(?:=|[ \t]+)/.exec(cmd); - if (!m) return cmd; - const head = cmd.slice(0, m.index) + m[1]; - const valStart = m.index + m[0].length; - const rest = cmd.slice(valStart); - const lead = /^\s*/.exec(rest)[0]; - const body = rest.slice(lead.length); - if (body[0] === "'" || body[0] === '"') return cmd; // 已自带外层引号,交给现有分词管线 - const json = scanBalancedJson(body); - if (!json) return cmd; - const tail = body.slice(json.length).replace(/^\s+/, ''); - let flag = '--commands', val; - if (!json.includes("'")) val = quoteArg(json); - else if (sessDir && sessDir.startsWith('/')) { - const fp = sessDir.replace(/\/+$/, '') + '/.batch-inline-' + Date.now().toString(36) + '.json'; - try { fs.writeFileSync(fp, json); flag = '--input'; val = quoteArg(fp); } catch (_) { return cmd; } - } else return cmd; - return head + flag + ' ' + val + (tail ? ' ' + tail : ''); -} - -// 从首个 [ / { 起扫描 balanced JSON 片段(处理 "..." 字符串与 \ 转义); -// 配平后再 JSON.parse 验真,不成 = 返回 null 放弃改写 -function scanBalancedJson(s) { - if (s[0] !== '[' && s[0] !== '{') return null; - let depth = 0, inStr = false, esc = false; - for (let i = 0; i < s.length; i++) { - const c = s[i]; - if (inStr) { if (esc) esc = false; else if (c === '\\') esc = true; else if (c === '"') inStr = false; continue; } - if (c === '"') inStr = true; - else if (c === '[' || c === '{') depth++; - else if (c === ']' || c === '}') { - depth--; - if (depth === 0) { - const frag = s.slice(0, i + 1); - try { JSON.parse(frag); return frag; } catch (_) { return null; } - } - } - } - return null; -} - -function pictureSrcAlias(cmd) { - if (!/(?:^|\s)--type\s+(?:picture|image)(?:\s|$)/.test(cmd)) return cmd; - const toks = tokenizeCmd(cmd); - if (!toks) return cmd; - let changed = false; - const out = toks.map((t) => { if (!/^path=/.test(t)) return t; changed = true; return 'src=' + t.slice(5); }); - return changed ? out.map(quoteArg).join(' ') : cmd; -} - -function json(res, code, obj) { - const body = JSON.stringify(obj); - res.writeHead(code, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) }); - res.end(body); -} - -function toolText(resObj) { - return { content: [{ type: 'text', text: typeof resObj === 'string' ? resObj : JSON.stringify(resObj, null, 2) }], isError: false }; -} -function toolErr(msg) { - return { content: [{ type: 'text', text: 'Error: ' + (msg && msg.message || String(msg)) }], isError: true }; -} - - -// create/open/push 成功附带一个通用 ui_card 块(action=open_preview):core 的 MCP 层剥离后不进模型面, -// 经 SSE ui_card 转聊天流可点卡片。后续其它命令/其它服务出卡片走同一协议: -// {type:'ui_card', action, arg, title?, note?}。arg 相对会话目录(前端 openFilePreview 拼预览链接 -// 正好用);组不出会话目录则不附。卡片的展示文案由产生方负责(前端只做动作分发)。 -const CARD_NOTE = { created: '已创建', opened: '已打开', imported: '已导入' }; -function attachPreviewCard(res, op, rel) { - if (!res || !Array.isArray(res.content)) return; - if (!rel || rel === '.' || rel.startsWith('..')) return; - res.content.push({ type: 'ui_card', action: 'open_preview', arg: rel, title: rel, note: CARD_NOTE[op] || '' }); -} - -async function handle(msg, pubBase, sessDir) { // pubBase/sessDir:调用方每请求注入(X-Public-Base / X-Session-Dir) - const isReq = msg.id !== undefined && msg.id !== null; - let helpCmd = false; // 本次调用是否为 help 族:透传后要把文本对齐可调用面 - // 通知(含 notifications/initialized):透传不等回包 - if (!isReq) { sendNotify(msg.method, msg.params || {}); return null; } - - if (msg.method === 'tools/call') { - const args = msg.params && msg.params.arguments || {}; - // 命令归一:argv 数组 → 命令串;相对路径自动绝对化(会话目录由调用方头注入) - let cmd = Array.isArray(args.command) ? args.command.map((a) => quoteArg(String(a))).join(' ') : String(args.command || ''); - cmd = absolutize(pictureSrcAlias(quoteInlineJson(cmd, sessDir)), sessDir).trim(); - args.command = cmd; - // 会话目录在 scratch 卷里可能尚不存在(首建):顺手补齐,create/push 才有落点(仅工作区内); - // 但 unwatch(含 --purge)是清理命令,不得反向重建刚删的目录 - if (sessDir && !/^unwatch\b/.test(cmd)) { - const sd = path.resolve(sessDir); - if (sd.startsWith(watch.WORKSPACE + '/')) { try { fs.mkdirSync(sd, { recursive: true }); } catch (_) {} } - } - - // 本部署不合适的命令(装自己/装环境那族):报原生风格 unrecognized,不露壳; - // help 清单里的这些行同步在 alignHelp 删除,可见面 = 可调用面。 - const mblk = /^(mcp|skills|install|plugins)(?:\s|$)/.exec(cmd) || /^help\s+(mcp|skills|install|plugins)(?:\s|$)/.exec(cmd); - if (mblk) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized(mblk[1])) }; - helpCmd = /^help(?:\s|$)/.test(cmd) || /(?:^|\s)(?:--help|-h)(?:\s|$)/.test(cmd); - // view 放开结构/语义模式(outline/stats/issues/text/annotated),只拦渲染族(需无头浏览器/导出插件,本环境没有); - // 给模型指明替代路径,别让它抱着文档里的强制渲染门反复试错。 - if (!helpCmd && /^view(?:\s|$)/.test(cmd)) { - const vpos = (tokenizeCmd(cmd) || []).slice(1).filter((t) => !t.startsWith('-')); // [file, mode, ...] - const vmode = String(vpos[1] || '').toLowerCase(); - if (VIEW_BLOCKED.has(vmode)) { - return { jsonrpc: '2.0', id: msg.id, result: toolErr( - "view " + vmode + " is disabled by environment policy. Use 'view outline' or 'view issues' for structural/semantic checks.") }; - } - } - // 部署技能:伪装进 vendor 的 load_skill 机制;无名/vendor 已知名照旧透传(清单/其它技能) - const ms = /^load_skill\b\s*([\s\S]*)$/.exec(cmd); - if (ms && /^(?:office[-_]?preview|preview)$/.test(ms[1].trim().replace(/^["']|["']$/g, ''))) { - return { jsonrpc: '2.0', id: msg.id, result: toolText(DEPLOY_SKILL) }; - } - // files(桥扩展):列当前会话目录(工作区侧)下的文件,AI 据此判断哪些文件已同步进来; - // 只报相对文件名,隐藏文件/目录略去,深度与条数封顶。 - if (!helpCmd && /^files(?:\s|$)/.test(cmd)) { - const root = sessDir ? path.resolve(sessDir) : ''; - if (!root.startsWith(watch.WORKSPACE + '/')) return { jsonrpc: '2.0', id: msg.id, result: toolErr('files: no workspace session directory for this request') }; - const names = []; - (function walk(dir, depth) { - if (depth > 4 || names.length >= 500) return; - let ents; - try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; } - for (const e of ents) { - if (e.name.startsWith('.')) continue; - const p = path.join(dir, e.name); - if (e.isDirectory()) walk(p, depth + 1); - else if (names.length < 500) names.push(path.relative(root, p)); - } - })(root, 0); - return { jsonrpc: '2.0', id: msg.id, result: toolText('# Workspace (server-side):\n' + (names.length ? names.join('\n') : '(no files)')) }; - } - // 桥内拦截(不占 vendor stdio;对 AI 不公示,见 DEPLOY_SKILL):watch/unwatch 仅本会话目录, - // unwatch --session <本会话id> 供 core 会话清理钩子,get-pos 改写原生回读,push 外链拉入 - const mr = /^(watch|unwatch|get-pos|push)\b([\s\S]*)$/.exec(cmd); - if (mr) { - const rest = String(mr[2] || '').trim(); - const file = watchArg(rest.replace(/(?:^|\s)--session(?:\s*=|\s+)\S+/g, ' ')); - const jail = sessDir ? path.resolve(sessDir) : watch.WORKSPACE; - const inJail = (x) => x && path.resolve(x).startsWith(jail + '/'); - try { - if (mr[1] !== 'push' && HIDDEN_SUBS.has(file)) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized(file)) }; - if (mr[1] === 'push') { - const toks = tokenizeCmd(rest) || []; - const url = String(toks[0] || ''); - const dest = toks[1] || ''; - if (!/^https?:\/\//i.test(url) || !dest) throw new Error('Usage: push (url is typically a link signed by mint_public_link)'); - const abs = pushTarget(dest, jail); - // 成功/失败文案只带相对文件名:工作区绝对路径对 AI 是干扰项(与任务目录同名不同盘) - let name = path.relative(jail, abs); if (name.startsWith('..')) name = path.basename(abs); - if (fs.existsSync(abs) && !/(?:^|\s)--force\b/.test(rest)) throw new Error('File already exists: ' + name + '. Use --force to overwrite.'); - // AI 视角是把文件「上传」进工作区,不说 download - let r; - try { r = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(PUSH_TIMEOUT_MS) }); } - catch (e) { throw new Error('Failed to read file: ' + String(e && e.message || e).slice(0, 120) + ' (link expired or unreachable? re-sign with mint_public_link and retry)'); } - if (!r.ok) throw new Error('Failed to read file: HTTP ' + r.status + ' (link expired? re-sign with mint_public_link and retry)'); - const data = Buffer.from(await r.arrayBuffer()); - if (data.length > PUSH_MAX_BYTES) throw new Error('File too large: limit is ' + Math.floor(PUSH_MAX_BYTES / 1048576) + ' MB'); - fs.mkdirSync(path.dirname(abs), { recursive: true }); - fs.writeFileSync(abs, data); - const pushRes = { jsonrpc: '2.0', id: msg.id, result: toolText('Imported: ' + name) }; - if (sessDir) attachPreviewCard(pushRes.result, 'imported', path.relative(path.resolve(sessDir), abs)); - return pushRes; - } - if (mr[1] === 'watch') { - if (!file) throw new Error('Usage: watch '); - if (!inJail(file)) throw new Error('Preview is only available for documents inside the current session directory: ' + file); - // 预览链接是固定格式、前端自拼:url/path 不透给 AI 面 - const winfo = Object.assign({}, await watch.start(file, pubBase)); - delete winfo.url; delete winfo.path; - return { jsonrpc: '2.0', id: msg.id, result: toolText(winfo) }; - } - if (mr[1] === 'get-pos') { - if (!file) throw new Error('Usage: get-pos (works once the user opens the preview and selects something)'); - // 文件不存在:vendor 风格失败信封 {success:false, message},只报相对文件名,顺手带上两盘同步指引 - if (!fs.existsSync(path.resolve(file))) { - let nm = path.relative(jail, path.resolve(file)); if (nm.startsWith('..')) nm = path.basename(file); - return { jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: JSON.stringify({ - success: false, - message: 'File not found: ' + nm + '. If it lives in your task directory, sign a link with mint_public_link and pull it in with push .' - }, null, 2) }], isError: true } }; - } - // 没有预览槽在跑 = 没有选区来源:直接回空结果(信封与 vendor 一致:{success, data})。 - // watch 与否不需要 AI 关心,别把这事抛回给模型。 - if (![...watch.slots.values()].some((s) => s.file === path.resolve(file))) { - return { jsonrpc: '2.0', id: msg.id, result: toolText({ success: true, data: { matches: 0, results: [] } }) }; - } - cmd = 'get ' + quoteArg(file) + ' selected --json'; // 语义糖:改写为原生命令走原生回读实现 - args.command = cmd; - } else { - const msess = /(?:^|\s)--session(?:\s*=|\s+)(\S+)/.exec(rest); // core 会话清理专用:会话号必须等于本次请求的会话目录 - if (msess) { - const sid = decSafe(msess[1]); - // --purge(资源篮/core 删会话专用):杀槽之外连带删会话目录副本(幂等) - const purge = /(?:^|\s)--purge(?:\s|$)/.test(rest); - if (sid && sid === path.basename(jail)) return { jsonrpc: '2.0', id: msg.id, result: toolText(watch.stopSession(sid, purge)) }; - return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized('unwatch')) }; - } - if (!file) throw new Error('Usage: unwatch '); - if (!inJail(file)) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized('unwatch')) }; - return { jsonrpc: '2.0', id: msg.id, result: toolText(watch.stopOne(file)) }; - } - } catch (e) { - const t = String(e && e.message || e); - return { jsonrpc: '2.0', id: msg.id, result: toolErr(/文件不存在|not found/i.test(t) ? t + ' Hint: ' + SYNC_TEACH : t) }; - } - } - watch.touch(cmd); // 命中的预览槽位续命 - } - - try { - if (msg.method === 'initialize') { - if (!ready) { - // 子进程新鲜:客户端握手就是它的真握手(顺序天然正确) - const fresh = await rpc('initialize', msg.params || {}); - sendNotify('notifications/initialized', {}); - ready = true; fresh.id = msg.id; - return fresh; - } - // 子进程已被桥自举初始化:.NET SDK 不容二次握手、officecli 又单实例不容换新 —— 桥层合成应答 - return { jsonrpc: '2.0', id: msg.id, result: { - protocolVersion: (msg.params && msg.params.protocolVersion) || '2024-11-05', - capabilities: { tools: {} }, - serverInfo: { name: 'officecli', version: '1.0' } } }; - } - if (!ready) { await selfInit(); ready = true; } - const reply = await rpc(msg.method, msg.params || {}); - if (msg.method === 'tools/list' && reply.result && Array.isArray(reply.result.tools)) { - for (const t of reply.result.tools) { - if (t) t.description = String(t.description || '') + DESC_PATCH; // 部署侧须知随描述发给模型 - } - } - if (helpCmd) alignHelp(reply); // help 文本对齐可调用面:隐去命令删行,扩展命令补录 - if (msg.method === 'tools/call' && sessDir) { // 两份盘的教学与交付链都附在响应里(cmd 作用域仅限 tools/call 块,这里从参数重建) - const c = String((msg.params && msg.params.arguments || {}).command || ''); - teachOnMiss(c, reply); deliverNote(c, reply); ackNote(c, reply, sessDir); scrubErr(reply); - } - reply.id = msg.id; // 桥接 id 换回调用方 id - return reply; - } catch (e) { - try { if (child) child.kill(); } catch (_) {} - resetChild(); // 桥级失败(超时/进程死):换掉子进程,下次请求从干净状态重建 - return { jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: String(e && e.message || e) } }; - } -} - -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')) { - return json(res, 200, { name: SERVER_NAME, transport: 'streamable-http->stdio', preview: { port: PREVIEW_PORT, prefix: watch.PREFIX }, preview_slots: watch.status('') }); - } - if (req.method !== 'POST') return json(res, 404, { error: 'POST / only' }); - let body = ''; - req.on('data', (c) => { body += c; }); - req.on('end', () => { - let msg; try { msg = JSON.parse(body); } catch (_) { return json(res, 400, { error: 'bad json' }); } - handle(msg, String(req.headers['x-public-base'] || '').replace(/\/+$/, ''), String(req.headers['x-session-dir'] || '')).then((r) => { if (r === null) { res.writeHead(202).end(); return; } json(res, 200, r); }) - .catch((e) => json(res, 500, { error: String(e && e.message || e) })); - }); -}); - -// ---------- 优雅退出(容器 PID1 惯例,同 web_search) ---------- -function shutdown(sig) { - console.log(`[${SERVER_NAME}] 收到 ${sig},停止服务`); - try { if (child) child.kill(); } catch (_) {} - try { previewServer.close(); } catch (_) {} - server.close(() => process.exit(0)); - setTimeout(() => process.exit(0), 3000).unref(); -} -process.on('SIGTERM', () => shutdown('SIGTERM')); -process.on('SIGINT', () => shutdown('SIGINT')); - -const previewServer = gateway.start(PREVIEW_PORT, HOST); // 预览网关:单入口按任务路径路由,槽位号不出容器 - -server.listen(PORT, HOST, () => { - console.log(`${SERVER_NAME} HTTP listening on http://${HOST}:${PORT} (officecli mcp bridge, workspace=${watch.WORKSPACE}, slots=${process.env.OFFICE_SLOTS || 4}, preview=:${PREVIEW_PORT}${watch.PREFIX}/…)`); -}); diff --git a/mcp/officecli/watch.js b/mcp/officecli/watch.js deleted file mode 100644 index 53b7a07..0000000 --- a/mcp/officecli/watch.js +++ /dev/null @@ -1,328 +0,0 @@ -// watch 槽位管理:officecli watch 只绑 127.0.0.1(实测),且 watch 进程必须与 -// officecli MCP 子进程同容器(刷新信号 = 进程内 IPC,跨容器收不到)。 -// 本模块在 shim(容器 PID1)里 spawn watch 子进程 → 跨命令存活。 -// 不再开对外 TCP 转发口:预览路由交给 gateway.js —— url 按任务身份组织 -// (/preview/<会话id>/<文档相对路径>/),槽位号不出容器。 -// 槽位语义 = 可再生缓存而非承诺:链接按任务路径寻址,被回收/被别人挤掉后 -// 页面再访问由 gateway 就地复活(revive)。因此闲置阈值可以放心激进,AI 忘了 -// unwatch 不再有实质危害。 -'use strict'; -const net = require('node:net'); -const fs = require('node:fs'); -const path = require('node:path'); -const crypto = require('node:crypto'); -const { spawn } = require('node:child_process'); - -const WORKSPACE = process.env.OFFICE_WORKSPACE || '/workspace/tasks'; -const SLOTS = Number(process.env.OFFICE_SLOTS || 4); -const WATCH_BASE = Number(process.env.OFFICE_WATCH_BASE || 26315); // watch 自身端口(+slot),仅容器内回环 -const PREFIX = (process.env.OFFICE_PREVIEW_PREFIX || '/preview').replace(/\/+$/, ''); -const IDLE_MS = Number(process.env.OFFICE_IDLE_MS || 6 * 3600 * 1000); // 闲置回收阈值(默认 6h;槽=缓存,链接自愈,激进无副作用) -const EXTS = new Set(['.docx', '.xlsx', '.pptx']); - -const slots = new Map(); // slot -> {file, task, rel, port, watch, lastUsed, conns, pageDec, pageEnc} -const starting = new Map(); // 文件绝对路径 -> Promise:同文件并发 watch 合并为一次 spawn(watch 启动需秒级,窗口不窄) - -function log(...a) { console.log('[watch]', ...a); } - -// 路径护栏:限定 WORKSPACE 下的办公文档,禁止穿越 -function guard(p) { - const abs = path.resolve(WORKSPACE, String(p || '')); - const rel = path.relative(path.resolve(WORKSPACE), abs); - if (rel.startsWith('..') || path.isAbsolute(rel)) throw new Error('Path must be inside ' + WORKSPACE + ': ' + p); - if (!EXTS.has(path.extname(abs).toLowerCase())) throw new Error('Only .docx/.xlsx/.pptx files are supported: ' + p); - if (!fs.existsSync(abs)) throw new Error('File not found: ' + p); - return abs; -} - -// 文件 → 预览页前缀:WORKSPACE/<会话>/ → /<会话>/(另有分段编码形态供 url 用)。 -// 任务根下的文件没有预览页(url 必须挂在会话身份下,才能鉴权/稳定),要求至少两层。 -function pageOf(abs) { - const segs = path.relative(path.resolve(WORKSPACE), abs).split(path.sep).filter(Boolean); - if (segs.length < 2) throw new Error('Preview only supports files under a session directory (<' + WORKSPACE + '//...>): ' + abs); - return { - task: segs[0], - rel: segs.slice(1).join('/'), - pageDec: '/' + segs.join('/'), - pageEnc: '/' + segs.map((s) => encodeURIComponent(s)).join('/'), - }; -} - -function portUp(port, tries = 40) { - return new Promise((res, rej) => { - let n = 0; - (function probe() { - const s = net.connect(port, '127.0.0.1'); - s.on('connect', () => { s.destroy(); res(); }); - s.on('error', () => { s.destroy(); if (++n >= tries) return rej(new Error('watch server did not come up')); setTimeout(probe, 250); }); - })(); - }); -} - -async function start(file, publicBase) { - const abs = guard(file); - for (const [slot, s] of slots) if (s.file === abs) { s.lastUsed = Date.now(); return info(slot, publicBase); } - if (starting.has(abs)) { // vendor 限制同文件只许一个 watch:并发调用共享在飞的启动结果 - try { await starting.get(abs); } catch (_) {} - for (const [slot, s] of slots) if (s.file === abs) return info(slot, publicBase); - throw new Error('Failed to start watch (concurrent start for the same file); retry'); - } - const p = spawnWatch(abs, publicBase).finally(() => starting.delete(abs)); - starting.set(abs, p); - return p; -} - -async function spawnWatch(abs, publicBase) { - const page = pageOf(abs); // 先验证 url 可组织,再占坑 - let slot = -1; - for (let i = 0; i < SLOTS; i++) if (!slots.has(i)) { slot = i; break; } - if (slot < 0) { // 槽位满:优先踢「没有在看且最久未用」;全都有活动连接(= 页面开着)才抢最冷的活跃槽 - const ent = [...slots.entries()]; - const idle = ent.filter(([, s]) => !s.conns); - slot = (idle.length ? idle : ent).sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0][0]; - stop(slot); - } - const wp = WATCH_BASE + slot; - const child = spawn('officecli', ['watch', abs, '--port', String(wp)], { stdio: 'ignore' }); - child.on('exit', () => { if (slots.get(slot)?.watch === child) stop(slot); }); - const entry = { file: abs, task: page.task, rel: page.rel, port: wp, watch: child, lastUsed: Date.now(), conns: 0, pageDec: page.pageDec, pageEnc: page.pageEnc }; - slots.set(slot, entry); // 同步占坑:等端口就绪期间也不给并发 spawn 踩同一槽 - try { - await portUp(wp); - } catch (e) { - child.kill(); - if (slots.get(slot) === entry) slots.delete(slot); - throw new Error('Failed to start watch (only one watch per file is allowed): ' + e.message); - } - log(`slot${slot} ${abs} watch:${wp} page=${PREFIX}${page.pageDec}`); - return info(slot, publicBase); -} - -function stop(slot) { - const s = slots.get(slot); - if (!s) return false; - try { s.watch.kill(); } catch (_) {} - slots.delete(slot); - log(`slot${slot} 已停止`); - return true; -} - -function stopOne(file) { - const abs = guard(file); - for (const [slot, s] of slots) if (s.file === abs) { stop(slot); return { stopped: abs }; } - throw new Error('No watch running for this file: ' + abs); -} - -// command 透传时顺带给命中的槽位续命(AI 活跃 = 预览还有人关心) -function touch(command) { - for (const s of slots.values()) if (String(command || '').includes(s.file)) s.lastUsed = Date.now(); -} - -function info(slot, publicBase) { - const s = slots.get(slot); - return { - slot: slot, file: s.file, - path: PREFIX + s.pageEnc + '/', - url: (publicBase || '') + PREFIX + s.pageEnc + '/', - idle_min: Math.round((Date.now() - s.lastUsed) / 60000), // 闲置分钟(watch ls 给模型/用户看活性) - conns: s.conns || 0, // 正在回传的预览请求数(SSE 在场 = 页面开着) - }; -} - -// gateway 路由用:rel = 已解码、剥掉 PREFIX 的请求路径(以 / 开头); -// exact = 正好是页面本身(缺尾斜杠由 gateway 补 301),prefix = 页面下的资源/端点。最长前缀优先。 -function matchPage(rel) { - if (!rel) return null; - const rr = rel.startsWith('/') ? rel : '/' + rel; - let best = null; - for (const s of slots.values()) { - if (rr === s.pageDec) return { entry: s, exact: true }; - if (rr.startsWith(s.pageDec + '/')) { - if (!best || s.pageDec.length > best.entry.pageDec.length) best = { entry: s, exact: false }; - } - } - return best; -} - -function status(publicBase) { - return [...slots.keys()].map((slot) => info(slot, publicBase)); -} - -// 会话结束批量清理:core 删会话时经桥打一发 unwatch --session <会话id> [--purge]。 -// --purge:连带删除该会话在本工作区的目录副本(任务真相在 core/executor 侧,这里只是可再生 scratch); -// purge 语义下幂等:无槽/目录不存在都不报错,只在会话号非法时拒(防穿越)。 -function stopSession(taskId, purge) { - const t = String(taskId || ''); - const stopped = []; - for (const [slot, s] of slots) if (s.task === t) { stop(slot); stopped.push(s.file); } - let purged = false; - if (purge) { - if (!t || t === '.' || t === '..' || /[/\\]/.test(t) || t.includes('\0')) throw new Error('Invalid session id.'); - const dir = path.join(path.resolve(WORKSPACE), t); - if (path.relative(path.resolve(WORKSPACE), dir) !== t) throw new Error('Invalid session id.'); - if (fs.existsSync(dir)) { try { fs.rmSync(dir, { recursive: true, force: true }); purged = true; log('会话 purge:', t); } catch (_) {} } - } - if (!stopped.length && !purge) throw new Error('No watch running for this session: ' + t); - return { session: t, stopped, purged }; -} - -// gateway 未命中兜底:请求路径本身就是一个存在的会话文档 → 回收/被挤掉后就地复活。 -// 只接受整体形如办公文档的路径(扩展名把关);/api/… 等资源路径无扩展名 → null,404 语义不变。 -async function revive(rel) { - const rr = (rel || '').replace(/\/+$/, ''); - if (!rr || rr === '/') return null; - try { - await start(path.join(WORKSPACE, rr)); // guard/pageOf 复核越界、存在性、会话层级;不行 = 维持原 404 - return matchPage(rr); - } catch (_) { return null; } -} - -// 纯路径推导预览页地址(无需 watch 在场;布局不满足——越界/任务根下——返回 null) -function pageUrl(abs, publicBase) { - const rel = path.relative(path.resolve(WORKSPACE), abs); - if (!rel || rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) return null; - let page; - try { page = pageOf(abs); } catch (_) { return null; } - const p = PREFIX + page.pageEnc + '/'; - return { path: p, url: (publicBase || '') + p }; -} - -// ---------- /f/ 交付能力链:save/close 成功时签发(同 core /p/ 的设计:随机 id + TTL,URL 即能力)---------- -const DL_TTL_MS = Number(process.env.OFFICE_DL_TTL_MS || 30 * 60 * 1000); -const DL_MAX = 512; -const dls = new Map(); // token -> { abs, exp } -const MIME = { - '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', - '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', - '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation', -}; - -function dlMint(abs) { - const now = Date.now(); - for (const [k, v] of dls) if (v.exp <= now) dls.delete(k); - // 同一文件重复 save/close 复用原 token(滑动 TTL):serveDl 实时读盘,链接永远指向盘上最新内容,AI 改完重新下载原链即可 - for (const [k, v] of dls) if (v.abs === abs) { v.exp = now + DL_TTL_MS; return k; } - while (dls.size >= DL_MAX) dls.delete(dls.keys().next().value); - const token = crypto.randomBytes(16).toString('base64url'); - dls.set(token, { abs, exp: now + DL_TTL_MS }); - return token; -} - -function serveDl(token, req, res) { - const e = token ? dls.get(token) : null; - if (!e || e.exp <= Date.now()) { - if (e) dls.delete(token); - res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('Link not found or expired. Run save on the file again to issue a new link.'); - return; - } - let st; - try { st = fs.statSync(e.abs); } catch (_) { - dls.delete(token); - res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('File is no longer in the workspace; save or push it again first'); - return; - } - if (!st.isFile()) { res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('File is no longer in the workspace; save or push it again first'); return; } - const base = path.basename(e.abs); - const ascii = base.replace(/[^\x20-\x7e]|["\\]/g, '_') || 'document'; - res.writeHead(200, { - 'content-type': MIME[path.extname(base).toLowerCase()] || 'application/octet-stream', - 'content-length': String(st.size), - 'content-disposition': 'attachment; filename="' + ascii + '"; filename*=UTF-8\'\'' + encodeURIComponent(base), - 'cache-control': 'no-store', - }); - fs.createReadStream(e.abs).pipe(res); -} - -// ---------- scratch 卫生:这份盘只是工作副本(交付真相在 core 的 tasks),两道闸:闲置 TTL + 容量水位 ---------- -const SCRATCH_TTL_MS = Number(process.env.OFFICE_SCRATCH_TTL_MS || 7 * 24 * 3600 * 1000); -// 容量水位:总量(含 busy)超上限时,按目录最新 mtime 从旧到新删非 busy 目录,删到低水位为止。 -// busy(正开预览)永不触碰,宁可短时超水位也不打扰活跃会话;编辑即落盘会把 mtime 刷新,活跃会话天然排最后。 -const SCRATCH_MAX_BYTES = Number(process.env.OFFICE_SCRATCH_MAX_BYTES || 2 * 1073741824); // 0 = 关 -const SCRATCH_LOW_RATIO = 0.8; - -function newestMtime(dir, budget) { // 目录树最新 mtime;budget 封顶防巨目录卡住定时器 - let best = 0; - try { best = fs.statSync(dir).mtimeMs; } catch (_) { return 0; } - const stack = [dir]; - while (stack.length && budget.n > 0) { - const d = stack.pop(); - let ents; - try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { continue; } - for (const en of ents) { - if (budget.n-- <= 0) break; - const p = path.join(d, en.name); - if (en.isSymbolicLink()) continue; - if (en.isDirectory()) { stack.push(p); continue; } - try { const m = fs.statSync(p).mtimeMs; if (m > best) best = m; } catch (_) {} - } - } - return best; -} - -function dirSize(dir, budget) { // 目录树总字节;budget 封顶,截断时偏小(水位是粗粒度启发式,可接受) - let total = 0; - const stack = [dir]; - while (stack.length && budget.n > 0) { - const d = stack.pop(); - let ents; - try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { continue; } - for (const en of ents) { - if (budget.n-- <= 0) break; - const p = path.join(d, en.name); - if (en.isSymbolicLink()) continue; - if (en.isDirectory()) { stack.push(p); continue; } - try { total += fs.statSync(p).size; } catch (_) {} - } - } - return total; -} - -function pruneScratch() { - if (!(SCRATCH_TTL_MS > 0) && !(SCRATCH_MAX_BYTES > 0)) return []; - const now = Date.now(); - const busy = new Set([...slots.values()].map((s) => path.relative(WORKSPACE, s.file).split(path.sep)[0])); - let tops; - try { tops = fs.readdirSync(WORKSPACE, { withFileTypes: true }); } catch (_) { return []; } - const removed = []; - // 道闸一:闲置 TTL(整目录最新 mtime 超时即回收) - if (SCRATCH_TTL_MS > 0) { - for (const en of tops) { - if (!en.isDirectory() || en.isSymbolicLink() || busy.has(en.name)) continue; - const dir = path.join(WORKSPACE, en.name); - const m = newestMtime(dir, { n: 800 }); - if (m && now - m > SCRATCH_TTL_MS) { - try { fs.rmSync(dir, { recursive: true, force: true }); removed.push(en.name); } catch (_) {} - } - } - } - // 道闸二:容量水位总量超限则从旧到新删非 busy 目录,删到低水位或候选耗尽 - if (SCRATCH_MAX_BYTES > 0) { - const infos = []; - let total = 0; - for (const en of tops) { - if (!en.isDirectory() || en.isSymbolicLink()) continue; - const dir = path.join(WORKSPACE, en.name); - const size = dirSize(dir, { n: 4000 }); - total += size; - if (!busy.has(en.name) && !removed.includes(en.name)) infos.push({ name: en.name, dir, size, m: newestMtime(dir, { n: 800 }) }); - } - infos.sort((a, b) => a.m - b.m); - const lowLimit = SCRATCH_MAX_BYTES * SCRATCH_LOW_RATIO; - for (const it of infos) { - if (total <= lowLimit) break; - try { fs.rmSync(it.dir, { recursive: true, force: true }); total -= it.size; removed.push(it.name); } catch (_) {} - } - } - if (removed.length) log('scratch 清理:', removed.join(', ')); - return removed; -} -setInterval(pruneScratch, 3600 * 1000).unref(); -setTimeout(pruneScratch, 10000).unref(); // 重启后不等整点,早扫一轮 - -setInterval(() => { - const now = Date.now(); - // 有活动连接的槽 = 有人正开着页面,永不闲置回收(槽满时它最后被抢,见 spawnWatch) - for (const [slot, s] of slots) if (!s.conns && now - s.lastUsed > IDLE_MS) { log(`slot${slot} 闲置回收`); stop(slot); } -}, 60000).unref(); - -module.exports = { start, stop, stopOne, stopSession, touch, status, guard, slots, IDLE_MS, matchPage, revive, pageUrl, dlMint, serveDl, pruneScratch, DL_TTL_MS, WORKSPACE, PREFIX }; From e9ba44a96417c44a9c6e87a42f8a18709e4b41dd Mon Sep 17 00:00:00 2001 From: kicer Date: Mon, 19 Oct 2026 11:29:55 +0800 Subject: [PATCH 41/41] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20compose=EF=BC=9A?= =?UTF-8?q?=E6=91=98=E9=99=A4=E5=8D=B7=E5=90=8E=E9=81=97=E7=95=99=E7=9A=84?= =?UTF-8?q?=E7=A9=BA=20volumes:=20=E9=94=AE=EF=BC=88config=20=E6=A0=A1?= =?UTF-8?q?=E9=AA=8C=E4=B8=8D=E8=BF=87=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mcp/docker-compose.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index 7c1c7ef..e503405 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -37,5 +37,3 @@ networks: # 这里声明为 external 直接加入。agent-core / agent-executor 按容器名访问这些服务。 agent-mcp-net: external: true - -volumes: