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:<port>) 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
This commit is contained in:
+13
-12
@@ -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
|
||||
external: true
|
||||
|
||||
+96
-5
@@ -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` 都从当前请求读取。
|
||||
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`。外网访问不到。本机调试无所谓,生产请显式设置。
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -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:<port>
|
||||
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);
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user