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 +}