refactor(video_task): 改成通用 OpenAI 兼容形态,不绑定任何厂商

照 image_task 的口径:Base-Url / 模型 / 凭据全部由调用方每个请求用 header 带入
(X-Video-Task-Base-Url / X-Video-Task-Model / Authorization),服务端不存密钥、
不预设默认模型、不认任何厂商专有字段。

- 提交 POST {base}/videos/generations(wait=false,立刻回 task_id)
- 查询 GET  {base}/videos/{task_id}
- 缺 header 同步报错,不打上游
- 上游只需回 task_id/id 与 status(completed 时带 videos[].url)
- presets.json 与 README 同步改成通用描述
This commit is contained in:
2026-11-17 16:28:44 +08:00
parent c750393c81
commit 3139108838
4 changed files with 303 additions and 293 deletions
+11 -3
View File
@@ -95,7 +95,7 @@
{ {
"key": "video_task", "key": "video_task",
"label": "视频生成", "label": "视频生成",
"desc": "WorkBuddy 网关(minimax / kling)", "desc": "文生视频 / 图生视频",
"url": "http://mcp_video_task:3000/mcp", "url": "http://mcp_video_task:3000/mcp",
"mode": "skill", "mode": "skill",
"fields": [ "fields": [
@@ -105,12 +105,20 @@
"secret": true, "secret": true,
"prefix": "Bearer ", "prefix": "Bearer ",
"required": true, "required": true,
"placeholder": "wb.ai 的 API Key" "placeholder": "API Key"
},
{
"header": "X-Video-Task-Base-Url",
"label": "地址",
"required": true,
"placeholder": "https://<host>/v1",
"hint": "OpenAI 兼容 videos / generations"
}, },
{ {
"header": "X-Video-Task-Model", "header": "X-Video-Task-Model",
"label": "模型", "label": "模型",
"default": "cn:minimax-video-h3" "required": true,
"placeholder": "上游的模型 id"
} }
] ]
}, },
+4 -2
View File
@@ -6,7 +6,7 @@
|---|---|---|---|---| |---|---|---|---|---|
| `web_search/` | `mcp_web_search` | 网页搜索(默认免费 Parallel / Exa,可换成自建 `/search` 上游) | `3000` | `POST /` | | `web_search/` | `mcp_web_search` | 网页搜索(默认免费 Parallel / Exa,可换成自建 `/search` 上游) | `3000` | `POST /` |
| `image_task/` | `mcp_image_task` | 图片生成 / 编辑(文生图走 `/images/generations`,图生图走 `/images/edits`,单工具 op=create/get) | `3000` | `POST /mcp` | | `image_task/` | `mcp_image_task` | 图片生成 / 编辑(文生图走 `/images/generations`,图生图走 `/images/edits`,单工具 op=create/get) | `3000` | `POST /mcp` |
| `video_task/` | `mcp_video_task` | 视频生成(上游 WorkBuddy 网关 `/v1/videos`,异步,单工具 op=create/get) | `3000` | `POST /mcp` | | `video_task/` | `mcp_video_task` | 视频生成(任意 OpenAI 兼容 `/videos` 上游,异步,单工具 op=create/get) | `3000` | `POST /mcp` |
| `asr/` | `mcp_asr` | 语音转文字(上游 OpenAI 兼容 `/audio/transcriptions`),**额外带一个给输入框用的 `POST /transcribe`** | `3000` | `POST /mcp` | | `asr/` | `mcp_asr` | 语音转文字(上游 OpenAI 兼容 `/audio/transcriptions`),**额外带一个给输入框用的 `POST /transcribe`** | `3000` | `POST /mcp` |
**这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor` **这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor`
@@ -50,7 +50,9 @@ mcp_servers:
> 从旧的「agent + mcp 双仓库」部署升级:先在旧 mcp 仓库目录 `docker compose down`(只需一次,否则同名容器与网络会冲突),再 `up` 本栈。 > 从旧的「agent + mcp 双仓库」部署升级:先在旧 mcp 仓库目录 `docker compose down`(只需一次,否则同名容器与网络会冲突),再 `up` 本栈。
`image_task` / `video_task` 的 token **不由服务端保存**——每个请求从 `Authorization` header 读取 `image_task` / `video_task` 的 token **不由服务端保存**——每个请求从 `Authorization` header 读取
(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。`video_task` 用 wb.ai 网关的 API Key; (agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。`video_task` 走任意 OpenAI 兼容的 videos 上游:
提交 `/videos/generations`、查询 `/videos/{task_id}`,地址与模型由 `X-Video-Task-Base-Url` /
`X-Video-Task-Model` 指定(两者都必填);
`image_task` 走任意 OpenAI 兼容的 images 上游:文生图 `/images/generations`、图生图 `/images/edits`, `image_task` 走任意 OpenAI 兼容的 images 上游:文生图 `/images/generations`、图生图 `/images/edits`,
上游地址与模型分别由 `X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定(两者都必填)。 上游地址与模型分别由 `X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定(两者都必填)。
所以这两个服务不用配任何密钥。 所以这两个服务不用配任何密钥。
+111 -80
View File
@@ -1,13 +1,15 @@
# MCP Video Task # MCP Video Task
对接 **WorkBuddy 网关**(`wb.ai`)的 OpenAI 兼容视频接口。只有一个工具 `video_task`,用 `op` 区分提交与查询。 对接**任意 OpenAI 兼容的视频生成端点**:提交走 `POST {base}/videos/generations`,查询走
Server **不内部轮询**——AI 拿到 `task_id` 后自己决定什么时候复查。 `GET {base}/videos/{task_id}`。对外只有一个工具 `video_task`,用 `op` 区分动作:
- 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - `op=create` 提交任务,立刻回 `task_id`
- 上游:`POST /v1/videos/generations`(提交,`wait=false` 立刻回 `task_id`)、`GET /v1/videos/{task_id}`(查询) - `op=get` 按 `task_id` 单次查询,**Server 不内部轮询**
- 默认模型:`cn:minimax-video-h3`;可选 `cn:kling-video-v3`、`global:kling-video-v3`
- 端口:容器内 `3000`(MCP `/mcp` + `/health`,容器外不映射,只在 `agent-mcp-net` 内被 agent 访问) - 协议:MCP **Streamable HTTP**(单端点 `/mcp`)
- 鉴权:**无服务端密钥**,每次请求必须从 header 携带网关 API Key - 端口:容器内 `3000`(`/mcp` + `/health`)
- 鉴权:**服务端不存密钥**,每个请求从 header 读
- 上游:**不预设任何厂商**,Base-Url / 模型 / 凭据全部由调用方带入
--- ---
@@ -18,133 +20,162 @@ Server **不内部轮询**——AI 拿到 `task_id` 后自己决定什么时候
仓库根目录 `docker-compose.yml` 已包含本服务: 仓库根目录 `docker-compose.yml` 已包含本服务:
```bash ```bash
cd /root/workspace/tools/agent
docker compose up -d --build mcp_video_task docker compose up -d --build mcp_video_task
``` ```
容器名 `mcp_video_task`,不占宿主机端口,由 agent 走 `agent-mcp-net` 按容器名访问。
```bash ```bash
# 容器内健康检查(无需占端口) # 容器内健康检查
docker exec mcp_video_task node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)" docker exec mcp_video_task node -e "fetch('http://localhost:3000/health').then(r=>r.text()).then(console.log)"
# {"status":"ok","service":"video_task","upstream":"https://wb.ai.foresh.com","sessions":0} # {"status":"ok","service":"video_task","sessions":0}
``` ```
### MCP 客户端配置 ### MCP 客户端配置
```yaml ```jsonc
mcp_servers: {
- name: video_task "mcpServers": {
url: "http://mcp_video_task:3000/mcp" "video_task": {
mode: skill "type": "http",
headers: "url": "http://mcp_video_task:3000/mcp",
Authorization: Bearer <wb.ai 的 API Key> "headers": {
X-Video-Task-Model: cn:minimax-video-h3 # 可选,覆盖默认模型 "Authorization": "Bearer <上游 API Key>",
"X-Video-Task-Base-Url": "https://<host>/v1",
"X-Video-Task-Model": "<上游模型 id>"
}
}
}
}
``` ```
--- ---
## 工具:`video_task` ## 三个 header
| header | 必填 | 说明 |
|---|---|---|
| `Authorization` | 是 | `Bearer <token>`,原样转给上游 |
| `X-Video-Task-Base-Url` | 是 | 完整 http(s) 地址,填到 `/v1` 即可;直接填到 `/videos/generations` 或 `/videos` 也会被剥回 base |
| `X-Video-Task-Model` | 是 | 上游模型 id,原样透传;不猜缺省值 |
配置缺失或非法时,工具直接回 `isError` 并说明缺哪个 header,不会去打上游。
---
## 工具:video_task
### 参数(AI 可见) ### 参数(AI 可见)
| 参数 | 类型 | 说明 | | 参数 | 类型 | 说明 |
|---|---|---| |---|---|---|
| `op` | `create` \| `get` | 提交 / 查询,必填 | | `op` | `create` \| `get` | 必填 |
| `prompt` | string ≤ 2000 | `create` 必填。图生视频时描述画面如何运动 | | `prompt` | string | 视频描述,`create` 时与 `image_url` 至少给一个 |
| `image_url` | url | 图生视频的参考图,公网可访问的 png/jpeg/jpg | | `image_url` | string | 参考图(图生视频),公开可访问的 png/jpeg URL |
| `seconds` | 4–15 | 时长,默认 4。越长越慢越贵 | | `seconds` | int | 时长(秒),留空用上游默认 |
| `aspect_ratio` | string | `16:9` / `9:16` / `1:1`。上游不严格校验 | | `aspect_ratio` | string | 画幅,如 `16:9` / `9:16` / `1:1` |
| `resolution` | string | `768P` / `1080P`,留空用上游默认 | | `resolution` | string | 分辨率,如 `768P` / `1080P` |
| `negative_prompt` | string | 不希望出现的画面 | | `negative_prompt` | string | 不希望出现的画面 |
| `enable_audio` | boolean | 是否生成音频,默认 false(别名 `with_audio`) | | `enable_audio` | bool | 是否生成音频,默认 false(旧名 `with_audio` 同样接受) |
| `task_id` | string | `get` 必填,`create` 返回 | | `task_id` | string | `create` 返回的 id,`get` 时必填 |
### 返回(`op=create`) ### 返回(op=create)
``` ```
task_id: 1312831544-minimax_video_h3-5c12… task_id: <id>
model: cn:minimax-video-h3 model: <上游模型 id>
status: queued status: queued
提示:生成是异步的,用 op="get" + task_id 查结果。
Video generation is asynchronous. Call this tool again with op="get" and task_id="<id>" to fetch the result.
``` ```
### 返回(`op=get`) ### 返回(op=get)
任务完成:
``` ```
task_id: … task_id: <id>
model: cn:minimax-video-h3 model: <上游模型 id>
status: completed status: completed
Video URL: https://…mp4?q-signature=… Video URL: https://...
credit: 62.29 credit: 62.29
note: <上游附带的提示,如直链有效期>
注意:视频是签名直链,约 12 小时失效;要长期保存请立刻下载到本地。
``` ```
`status` 归一化为 `queued` / `in_progress` / `completed` / `failed`。 未完成 / 失败:回 `status` 与 `progress`,失败时附上游 `error` 原文,并置 `isError=true`。
`failed` 时返回 `isError: true` 并把上游原话带出来。
--- ---
## 模型与计费(2026-11-17 实测) ## 上游要求
| 模型 | 请求 | 实际扣费 | 出片耗时 | 分辨率 | 只要满足这两条,任何实现都能接(自建网关、云厂商、本地服务):
|---|---|---|---|---|
| `cn:minimax-video-h3` | 4s / 16:9 | **62.29** | **128 秒** | 768P |
| `cn:kling-video-v3` | 4s(实际出 5s) | 102.86 | ≈473 秒 | — |
- 扣费发生在**出片那一刻**,提交不扣;重复查询不重复计费 1. `POST {base}/videos/generations` 返回 `task_id` 或 `id`
- 上游 `usage` 只回一次,之后重复查询不带 `credit` 属正常 2. `GET {base}/videos/{task_id}` 返回 `status`;完成时带 `videos[].url` 或 `data[].url`
- `kling` 慢一个量级,客户端超时要给到 15 分钟以上
## 本地文件 → 公网 URL `status` 按小写比较:`completed` / `succeeded` / `success` 视为完成,`failed` / `error` /
`cancelled` 视为失败,其余按进行中处理。
本服务不搬字节:图生视频要的是**公网可访问的 URL**。本地文件先由 agent 内置的
「公开临时 URL」工具(`mint_public_link`)换一个短命链接,再把该链接作为 `image_url` 传进来。
--- ---
## 环境变量 ## 本地文件 → 公网 URL(本服务不搬字节)
| 变量 | 默认值 | 说明 | 图生视频要的是**公网可访问的 URL**,不是字节流。本地文件这样走:
|---|---|---|
| `WB_BASE_URL` | `https://wb.ai.foresh.com` | 网关地址,末尾斜杠自动去掉 |
## curl 调试 ```
AI ──调用 agent 内置的「公开临时 URL」工具(直接传文件路径)──► 拿到一条短命公网 URL
│
▼
AI 把 URL 当 image_url 交给 video_task:3000/mcp(转成上游的 image 字段)
│
▼
上游 ──匿名 GET──► agent 侧提供的公开临时 URL(文件始终躺在任务目录里,零拷贝)
```
链接短命:到期或 agent 重启后失效;上游只在提交任务那一刻拉一次图,够用。
---
## 用 curl 手工调试
```bash ```bash
# 1. initialize 拿 session id URL=http://127.0.0.1:3000/mcp # 容器内;宿主机调试需自行映射端口
curl -s -D - -X POST http://127.0.0.1:3000/mcp \ H=(-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream'
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -H 'Authorization: Bearer <token>'
-H "Authorization: Bearer $WB_KEY" \ -H 'X-Video-Task-Base-Url: https://<host>/v1'
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' -H 'X-Video-Task-Model: <model>')
# 响应头里的 mcp-session-id 后续要带上
# 2. 提交 # 1. initialize,从响应头取 mcp-session-id
curl -s -X POST http://127.0.0.1:3000/mcp \ curl -s -D - "${H[@]}" -X POST $URL \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}'
-H "mcp-session-id: $SID" -H "Authorization: Bearer $WB_KEY" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"video_task","arguments":{"op":"create","prompt":"一只橘猫在草地上奔跑","seconds":4}}}' # 2. 提交任务
curl -s "${H[@]}" -H 'mcp-session-id: <sid>' -X POST $URL \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"video_task","arguments":{"op":"create","prompt":"一只猫在草地上跑"}}}'
# 3. 查结果 # 3. 查结果
curl -s -X POST http://127.0.0.1:3000/mcp \ curl -s "${H[@]}" -H 'mcp-session-id: <sid>' -X POST $URL \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"video_task","arguments":{"op":"get","task_id":"<id>"}}}'
-H "mcp-session-id: $SID" -H "Authorization: Bearer $WB_KEY" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"video_task","arguments":{"op":"get","task_id":"<task_id>"}}}'
``` ```
响应是 SSE 帧(`event: message` + `data: {...}`),解析时取 `data:` 那一行。 响应是 SSE(`event: message` + `data: {...}`),取 `data:` 那行解析。
--- ---
## 架构与文件 ## 架构与文件
| 文件 | 作用 | ```
|---|---| mcp/video_task/
| `src/mcp-server.js` | 全部逻辑:Express + MCP SDK,`buildServer()` 注册工具,`startHttp()` 起 Streamable HTTP | ├── Dockerfile
| `Dockerfile` | node:22-alpine,`node src/mcp-server.js --http --port 3000` | ├── package.json
| `package.json` | `@modelcontextprotocol/sdk` + `express` + `zod` | ├── README.md
└── src/mcp-server.js # 全部逻辑:header 解析 / 上游调用 / MCP 服务
```
### 关键设计 ### 关键设计
- **服务端不轮询**:`create` 提交完立刻返回,`get` 只拉一次,由 AI 控制节奏 - **无状态**:不存密钥、不存任务,重启即忘。任务状态由上游持有,`task_id` 就是全部上下文。
- **状态归一化**:上游 `queued` / `in_progress` / `completed` / `failed` 统一成小写,AI 不用猜 - **不轮询**:`op=get` 只拉一次。轮询节奏由 AI 决定,避免服务端挂着长任务占资源。
- **错误透传**:上游 4xx/5xx 的原话进 `content[0].text`,模型能读到「模型不存在」这类可行动信息 - **配置错误不打上游**:缺 header 时同步返回 `isError`,省一次无意义的 400。
- **鉴权随请求走**:服务端不落任何密钥,多实例共用一份镜像也不串号 - **`wait=false` 提交**:立刻拿 `task_id`,不让工具调用被上游排队拖死。
+177 -208
View File
@@ -1,8 +1,4 @@
#!/usr/bin/env node #!/usr/bin/env node
// MCP 视频任务服务:对接 WorkBuddy 网关(wb.ai)的 OpenAI 兼容视频接口
// 提交 POST /v1/videos/generations(wait=false,立刻回 task_id)
// 查询 GET /v1/videos/{task_id}
// 只有一条工具 video_task,用 op 区分 create / get;服务端不轮询,AI 自己查。
import express from "express"; import express from "express";
import { randomUUID } from "node:crypto"; import { randomUUID } from "node:crypto";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -10,22 +6,13 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js"; import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod"; import { z } from "zod";
// 上游网关地址:容器内可用 WB_BASE_URL 覆盖 // 上游必须是 OpenAI 兼容的视频端点:提交 POST /videos/generations,查询 GET /videos/{task_id}。
const WB_BASE = (process.env.WB_BASE_URL || "https://wb.ai.foresh.com").replace(/\/+$/, ""); // Base-Url / 模型 / 凭据全部由调用方随每个请求用 header 带入(X-Video-Task-Base-Url /
const SUBMIT_URL = `${WB_BASE}/v1/videos/generations`; // X-Video-Task-Model / Authorization),服务自己不存、也不预设任何厂商。
const queryUrl = (id) => `${WB_BASE}/v1/videos/${encodeURIComponent(id)}`;
// 默认模型:minimax 出片约 2 分钟、扣 57 积分;kling 约 8 分钟、扣 103 积分 // 提交与查询都是快接口(wait=false 立刻回 task_id),卡住基本等于上游挂了。
const DEFAULT_MODEL = "cn:minimax-video-h3";
const DEFAULT_SECONDS = 4;
// 提交/查询都是快接口(wait=false 立刻返回),卡住基本等于上游挂了
const UPSTREAM_TIMEOUT_MS = 60_000; const UPSTREAM_TIMEOUT_MS = 60_000;
// 上游状态归一:命中终态才停轮询
const DONE = new Set(["completed", "succeeded", "success"]);
const FAILED = new Set(["failed", "error", "cancelled", "canceled"]);
// ── 优雅退出 ────────────────────────────────────────────────────────────── // ── 优雅退出 ──────────────────────────────────────────────────────────────
// 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 // 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认
// 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 // 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。
@@ -38,7 +25,7 @@ function shutdown(sig) {
shuttingDown = true; shuttingDown = true;
console.log(`[video] received ${sig}, shutting down`); console.log(`[video] received ${sig}, shutting down`);
closeAllSessions(); closeAllSessions();
if (!httpServer) process.exit(0); if (!httpServer) process.exit(0); // stdio 模式无监听,直接退
httpServer.close(() => process.exit(0)); httpServer.close(() => process.exit(0));
setTimeout(() => process.exit(0), 3000).unref(); setTimeout(() => process.exit(0), 3000).unref();
} }
@@ -56,65 +43,94 @@ function parseArgs(argv) {
return args; return args;
} }
// 鉴权:每个请求从 header 取 wb.ai 的 API Key,服务端不落盘 // 对外只有三个 header:Authorization / X-Video-Task-Base-Url / X-Video-Task-Model。
function pickToken(headers) { function pickAuthToken(headers) {
if (!headers) return null; if (!headers) return null;
const candidates = [ const s = String(headers["authorization"] || "").trim();
headers["x-video-task-token"], if (!s) return null;
headers["x-mcp-token"], if (/^Bearer\s+/i.test(s)) {
headers["authorization"], const t = s.replace(/^Bearer\s+/i, "").trim();
]; return t || null;
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; return s;
} }
function pickModel(headers) { function pickHeaderString(headers, name) {
if (!headers) return null; if (!headers) return null;
const v = headers["x-video-task-model"] || headers["x-mcp-model"] || headers["x-model"]; const v = headers[name];
if (!v) return null; if (v === undefined || v === null) return null;
const s = String(v).trim(); const s = String(v).trim();
return s || null; return s || null;
} }
// 网关的模型名一定带域前缀(cn: / global:)。旧配置里遗留的智谱模型名 function pickBaseUrl(headers) {
// (cogvideox-flash 之类)没有冒号,发上去会 400「route config not found」, return pickHeaderString(headers, "x-video-task-base-url");
// 统一回落到默认模型,老配置不用改也能用。
function normalizeModel(m) {
if (!m) return DEFAULT_MODEL;
return m.includes(":") ? m : DEFAULT_MODEL;
} }
async function callWb({ url, token, method = "POST", body }) { function pickModel(headers) {
return pickHeaderString(headers, "x-video-task-model");
}
// 解析 Base-Url:必须是完整 http(s) URL。允许调用方直接填到 /videos/generations
// 或 /videos(照抄文档的写法),统一剥回 base——否则查询会被拼成两条路径。
function resolveBaseUrl(rawBase) {
const base = String(rawBase || "").trim().replace(/\/+$/, "");
if (!base) {
throw new Error(
"Missing X-Video-Task-Base-Url: pass the upstream base URL (e.g. https://<host>/v1)."
);
}
if (!/^https?:\/\//i.test(base)) {
throw new Error(
`Invalid X-Video-Task-Base-Url "${base}": must be a full http(s) URL.`
);
}
return base.replace(/\/videos(\/generations)?$/i, "");
}
// 模型只由 header 决定,AI 看不到也填不了。不猜缺省值:猜错只会换来含义不明的 400。
function resolveModel(headers) {
const model = pickModel(headers);
if (!model) {
throw new Error("Missing X-Video-Task-Model: pass the upstream model name.");
}
return model;
}
// 一次解析出本次请求的上游、凭据、模型。配置问题同步抛错,直接回给调用方。
function resolveTarget(headers) {
const token = pickAuthToken(headers);
if (!token) {
throw new Error('Missing Authorization: use "Authorization: Bearer <token>".');
}
return {
base: resolveBaseUrl(pickBaseUrl(headers)),
token,
model: resolveModel(headers),
};
}
// 统一的上游请求:超时、错误体解析都在这层,提交与查询共用。
async function callUpstream({ url, token, method = "POST", body }) {
const init = { const init = {
method, method,
headers: { headers: { Authorization: `Bearer ${token}` },
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS), signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
}; };
if (body !== undefined) init.body = JSON.stringify(body); if (body !== undefined) {
init.headers["Content-Type"] = "application/json";
init.body = JSON.stringify(body);
}
let resp; let resp;
try { try {
resp = await fetch(url, init); resp = await fetch(url, init);
} catch (e) { } catch (e) {
// AbortSignal.timeout 中止时抛 TimeoutError/AbortError,转成明确的超时错误
if (e?.name === "TimeoutError" || e?.name === "AbortError") { if (e?.name === "TimeoutError" || e?.name === "AbortError") {
throw new Error(`上游 ${UPSTREAM_TIMEOUT_MS} ms 内没有响应`); throw new Error(`Upstream request timed out after ${UPSTREAM_TIMEOUT_MS} ms`);
} }
throw e; throw e;
} }
const text = await resp.text(); const text = await resp.text();
let data; let data;
try { try {
@@ -123,9 +139,7 @@ async function callWb({ url, token, method = "POST", body }) {
data = { raw: text }; data = { raw: text };
} }
if (!resp.ok) { if (!resp.ok) {
// 网关的错误体是 {error:{message}},取原话给模型看,便于自行纠错 const err = new Error(`Upstream error: ${resp.status} ${resp.statusText} - ${text}`);
const msg = data?.error?.message || data?.error?.code || text.slice(0, 300);
const err = new Error(`网关返回 ${resp.status}: ${msg}`);
err.status = resp.status; err.status = resp.status;
err.detail = data; err.detail = data;
throw err; throw err;
@@ -133,62 +147,74 @@ async function callWb({ url, token, method = "POST", body }) {
return data; return data;
} }
// ===== op=create:提交任务,wait=false 立刻返回 task_id ===== // ===== op=create:提交视频生成(wait=false,立刻返回 task_id)=====
async function submitVideo({ token, model, prompt, imageUrl, seconds, aspectRatio, resolution, negativePrompt, enableAudio }) { async function submitVideo({ base, token, model, prompt, image_url, seconds, aspect_ratio, resolution, negative_prompt, enable_audio }) {
const body = { model, prompt, wait: false }; const body = { model, wait: false };
if (imageUrl) body.image = imageUrl; if (prompt) body.prompt = prompt;
if (seconds) body.seconds = seconds; if (image_url) body.image = image_url; // OpenAI Videos 口径的参考图字段
if (aspectRatio) body.aspect_ratio = aspectRatio; if (seconds !== undefined) body.seconds = seconds;
if (aspect_ratio) body.aspect_ratio = aspect_ratio;
if (resolution) body.resolution = resolution; if (resolution) body.resolution = resolution;
if (negativePrompt) body.negative_prompt = negativePrompt; if (negative_prompt) body.negative_prompt = negative_prompt;
if (enableAudio !== undefined && enableAudio !== null) body.enable_audio = Boolean(enableAudio); if (enable_audio !== undefined) body.enable_audio = Boolean(enable_audio);
return await callWb({ url: SUBMIT_URL, token, body });
return await callUpstream({ url: base + "/videos/generations", token, body });
} }
// ===== op=get:查任务(单次拉取) ===== // ===== op=get:查询任务(单次拉取,不内部轮询)=====
async function queryVideo({ token, taskId }) { async function queryVideo({ base, token, taskId }) {
return await callWb({ url: queryUrl(taskId), token, method: "GET" }); return await callUpstream({
url: base + "/videos/" + encodeURIComponent(taskId),
token,
method: "GET",
});
} }
function normStatus(s) { const DONE = new Set(["completed", "succeeded", "success"]);
return String(s || "").trim().toLowerCase(); const FAILED = new Set(["failed", "error", "cancelled", "canceled"]);
function normalizeStatus(s) {
return String(s || "").toLowerCase();
} }
async function handleCreate({ args, headers, token }) { // ---------- op=create 的业务处理 ----------
async function handleCreate({ args, headers }) {
// 纯空白 prompt 等同没给:schema 只校验类型/长度,不校验内容。
const prompt = typeof args.prompt === "string" ? args.prompt.trim() : ""; const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
if (!prompt) { if (!prompt && !args.image_url) {
return { return {
isError: true, isError: true,
content: [{ type: "text", text: 'op=create 需要 "prompt"(视频描述,必填)。' }], content: [{ type: "text", text: 'op=create requires at least one of "prompt" or "image_url".' }],
}; };
} }
const model = normalizeModel(pickModel(headers)); let target;
const seconds = Number.isFinite(args.seconds) ? args.seconds : DEFAULT_SECONDS; try {
target = resolveTarget(headers);
} catch (e) {
return { isError: true, content: [{ type: "text", text: e.message }] };
}
try { try {
const data = await submitVideo({ const data = await submitVideo({
token, ...target,
model,
prompt, prompt,
imageUrl: args.image_url, image_url: args.image_url,
seconds, seconds: args.seconds,
aspectRatio: args.aspect_ratio, aspect_ratio: args.aspect_ratio,
resolution: args.resolution, resolution: args.resolution,
negativePrompt: args.negative_prompt, negative_prompt: args.negative_prompt,
// 兼容旧字段名 enable_audio: args.enable_audio ?? args.with_audio,
enableAudio: args.enable_audio ?? args.with_audio,
}); });
const taskId = data.task_id || data.id; const taskId = data.task_id || data.id;
const summary = const summary =
`model: ${data.model || model}\n` +
`task_id: ${taskId}\n` + `task_id: ${taskId}\n` +
`status: ${normStatus(data.status) || "queued"}\n` + `model: ${target.model}\n` +
`status: ${data.status || "queued"}\n` +
`\n` + `\n` +
`视频是异步生成(minimax 约 2 分钟,kling 约 8 分钟)。` + `Video generation is asynchronous. ` +
`之后用 op="get" 加 task_id="${taskId}" 查询,直到 status 变成 completed 或 failed。` + `Call this tool again with op="get" and task_id="${taskId}" to fetch the result.`;
`不要重复提交同一个任务。`;
return { content: [{ type: "text", text: summary }] }; return { content: [{ type: "text", text: summary }] };
} catch (e) { } catch (e) {
@@ -197,177 +223,131 @@ async function handleCreate({ args, headers, token }) {
content: [ content: [
{ {
type: "text", type: "text",
text: `提交视频任务失败:${e.message}`, text: `提交视频任务失败:${e.message}${e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : ""}`,
}, },
], ],
}; };
} }
} }
async function handleGet({ args, token }) { // ---------- op=get 的业务处理 ----------
async function handleGet({ args, headers }) {
// 纯空白 task_id 不能直接拼进上游路径,否则得到一条含编码后空白的报错。
const taskId = typeof args.task_id === "string" ? args.task_id.trim() : ""; const taskId = typeof args.task_id === "string" ? args.task_id.trim() : "";
if (!taskId) { if (!taskId) {
return { return { isError: true, content: [{ type: "text", text: 'op=get requires "task_id".' }] };
isError: true, }
content: [{ type: "text", text: 'op=get 需要 "task_id"。' }],
}; let target;
try {
target = resolveTarget(headers);
} catch (e) {
return { isError: true, content: [{ type: "text", text: e.message }] };
} }
try { try {
const data = await queryVideo({ token, taskId }); const data = await queryVideo({ ...target, taskId });
const status = normStatus(data.status) || "unknown"; const status = normalizeStatus(data.status);
if (DONE.has(status)) { if (DONE.has(status)) {
const url = (data.videos || [])[0]?.url; const url = (data.videos || [])[0]?.url || (data.data || [])[0]?.url;
if (!url) { if (!url) {
return { return {
isError: true, isError: true,
content: [ content: [{ type: "text", text: `任务已完成但没有视频地址。Raw: ${JSON.stringify(data).slice(0, 500)}` }],
{
type: "text",
text: `任务已完成但没有返回视频地址。原始响应:${JSON.stringify(data).slice(0, 500)}`,
},
],
}; };
} }
const credit = data.usage?.credit; const credit = data.usage?.credit;
const summary = const text =
`task_id: ${taskId}\n` + `task_id: ${taskId}\n` +
`model: ${data.model || "-"}\n` + `model: ${data.model || target.model}\n` +
`status: completed\n` + `status: completed\n` +
`Video URL: ${url}\n` + `Video URL: ${url}\n` +
(credit !== undefined ? `credit: ${credit}\n` : "") + (credit !== undefined ? `credit: ${credit}\n` : "") +
`\n注意:视频是签名直链,约 12 小时失效;要长期保存请立刻下载到本地。`; (data.hint ? `note: ${data.hint}\n` : "");
return { content: [{ type: "text", text: summary }] }; return { content: [{ type: "text", text }] };
} }
if (FAILED.has(status)) { const errBlock = data.error ? `\nerror: ${JSON.stringify(data.error)}` : "";
return { const progress = data.progress !== undefined ? `\nprogress: ${data.progress}` : "";
isError: true,
content: [
{
type: "text",
text:
`task_id: ${taskId}\n` +
`status: ${status}\n` +
(data.error ? `error: ${JSON.stringify(data.error)}\n` : "") +
`任务已失败,需要换提示词或模型重新提交。`,
},
],
};
}
// queued / in_progress:告诉模型继续等,别重复提交
const progress = data.progress;
return { return {
isError: FAILED.has(status),
content: [ content: [
{ {
type: "text", type: "text",
text: text: `task_id: ${taskId}\nmodel: ${data.model || target.model}\nstatus: ${data.status || "unknown"}${progress}${errBlock}`,
`task_id: ${taskId}\n` +
`model: ${data.model || "-"}\n` +
`status: ${status}` +
(progress !== undefined && progress !== null ? `(进度 ${progress}%)` : "") +
`\n还没出片,稍后再用 op="get" 查一次。`,
}, },
], ],
}; };
} catch (e) { } catch (e) {
return { return {
isError: true, isError: true,
content: [{ type: "text", text: `查询视频任务失败:${e.message}` }], content: [
{
type: "text",
text: `查询视频任务失败:${e.message}${e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : ""}`,
},
],
}; };
} }
} }
function buildServer() { function buildServer() {
const server = new McpServer( const server = new McpServer({ name: "video_task", version: "2.0.0" }, { capabilities: { tools: {} } });
{ name: "video_task", version: "2.0.0" },
{ capabilities: { tools: {} } }
);
server.tool( server.tool(
"video_task", "video_task",
`AI 视频生成任务(异步)。 `AI video generation task (async).
操作: Operations:
- \`create\`:提交视频生成,必须给 \`prompt\`。立刻返回 \`task_id\`,生成在后台跑。 - \`create\`: Start a new task. Requires at least one of \`prompt\` or \`image_url\`. Returns \`task_id\` immediately.
- \`get\`:用 \`task_id\` 查进度,出片后返回视频直链。 - \`get\`: Check a task by \`task_id\`. Returns status and, when completed, the video URL.
示例: Examples:
- 文生视频 → \`{"op":"create","prompt":"一只橘猫在阳光下的草地上奔跑,电影感"}\` - Text-to-video → \`{"op":"create","prompt":"A cat running in a garden"}\`
- 图生视频 → \`{"op":"create","prompt":"画面里的人缓缓转身","image_url":"https://..."}\` - Image-to-video → \`{"op":"create","image_url":"https://example.com/cat.jpg","prompt":"The cat runs forward"}\`
- 查任务 → \`{"op":"get","task_id":"<create 返回的 task_id>"}\` - Check task → \`{"op":"get","task_id":"<task_id from create>"}\`
工作流:\`create\` 调一次,然后反复用 \`get\` 查同一个 \`task_id\`,直到 status 变成 completed 或 failed。**不要为了看进度重复提交任务。** Workflow: call \`create\` once, then call \`get\` with the returned \`task_id\` until status is \`completed\` or \`failed\`. Never create duplicate tasks just to check status.`,
耗时参考:minimax 约 2 分钟(扣 57 积分),kling 约 8 分钟(扣 103 积分)。视频直链约 12 小时失效。`,
{ {
op: z op: z.enum(["create", "get"]).describe("create 提交生成;get 按 task_id 查结果。"),
.enum(["create", "get"])
.describe("create 提交生成;get 按 task_id 查结果。"),
prompt: z prompt: z
.string() .string()
.max(2000) .max(2000)
.optional() .optional()
.describe("视频描述,create 必填。图生视频时描述画面如何运动。"), .describe("视频描述,create 时 prompt 与 image_url 至少给一个。图生视频时描述画面如何运动。"),
image_url: z image_url: z
.string() .string()
.url() .url()
.optional() .optional()
.describe( .describe(
"图生视频的参考图,公网可访问的 png/jpeg URL。本地文件先用 mint_public_link 换成公网短链。" "参考图(图生视频):公开可访问的 png/jpeg URL。本地文件先用 agent 内置的公开临时 URL 工具换成短链。"
), ),
seconds: z seconds: z
.number() .number()
.min(4) .int()
.max(15)
.optional()
.describe("视频时长(秒),默认 4。越长越慢越贵。"),
aspect_ratio: z
.string()
.optional()
.describe("画幅,如 16:9 / 9:16 / 1:1。上游不严格校验,写合法值即可。"),
resolution: z
.string()
.optional()
.describe("分辨率,如 768P / 1080P。留空用上游默认。"),
negative_prompt: z
.string()
.optional()
.describe("不希望出现的画面描述。"),
enable_audio: z
.boolean()
.optional()
.describe("是否生成音频,默认 false。"),
with_audio: z
.boolean()
.optional()
.describe("旧字段名,等同 enable_audio。"),
task_id: z
.string()
.min(1) .min(1)
.max(60)
.optional() .optional()
.describe("create 返回的 task_id,get 时必填。"), .describe("视频时长(秒)。留空用上游默认;越长越慢越贵。"),
aspect_ratio: z.string().optional().describe("画幅,如 16:9 / 9:16 / 1:1。"),
resolution: z.string().optional().describe("分辨率,如 768P / 1080P。留空用上游默认。"),
negative_prompt: z.string().optional().describe("不希望出现的画面描述。"),
enable_audio: z.boolean().optional().describe("是否生成音频,默认 false。"),
with_audio: z.boolean().optional().describe("旧字段名,等同 enable_audio。"),
task_id: z.string().min(1).optional().describe("create 返回的 task_id,get 时必填。"),
}, },
async (args, extra) => { async (args, extra) => {
const headers = extra?.requestInfo?.headers; const headers = extra?.requestInfo?.headers;
const token = pickToken(headers);
if (!token) {
return {
isError: true,
content: [{ type: "text", text: "缺少鉴权:header 里要带 Authorization: Bearer <API Key>。" }],
};
}
switch (args.op) { switch (args.op) {
case "create": case "create":
return await handleCreate({ args, headers, token }); return await handleCreate({ args, headers });
case "get": case "get":
return await handleGet({ args, token }); return await handleGet({ args, headers });
default: default:
return { return {
isError: true, isError: true,
content: [{ type: "text", text: `未知 op "${args.op}"(可用:create、get)。` }], content: [{ type: "text", text: `Unknown op "${args.op}" (available: create, get).` }],
}; };
} }
} }
@@ -384,19 +364,15 @@ async function startHttp({ port, host }) {
closeAllSessions = () => { closeAllSessions = () => {
for (const { server, transport } of sessions.values()) { for (const { server, transport } of sessions.values()) {
try { try { transport.close(); } catch {}
transport.close(); try { server.close(); } catch {}
} catch {}
try {
server.close();
} catch {}
} }
sessions.clear(); sessions.clear();
httpServer?.closeAllConnections?.(); httpServer?.closeAllConnections?.();
}; };
app.get("/health", (_req, res) => { app.get("/health", (_req, res) => {
res.json({ status: "ok", service: "video_task", upstream: WB_BASE, sessions: sessions.size }); res.json({ status: "ok", service: "video_task", sessions: sessions.size });
}); });
async function handleSessionRequest(req, res) { async function handleSessionRequest(req, res) {
@@ -411,10 +387,7 @@ async function startHttp({ port, host }) {
if (!isInitializeRequest(req.body)) { if (!isInitializeRequest(req.body)) {
res.status(400).json({ res.status(400).json({
jsonrpc: "2.0", jsonrpc: "2.0",
error: { error: { code: -32000, message: "Bad Request: missing valid Mcp-Session-Id for non-initialize request" },
code: -32000,
message: "Bad Request: missing valid Mcp-Session-Id for non-initialize request",
},
id: req.body?.id ?? null, id: req.body?.id ?? null,
}); });
return; return;
@@ -424,15 +397,11 @@ async function startHttp({ port, host }) {
const server = buildServer(); const server = buildServer();
const transport = new StreamableHTTPServerTransport({ const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => newId, sessionIdGenerator: () => newId,
onsessioninitialized: (id) => { onsessioninitialized: (id) => { sessions.set(id, { server, transport }); },
sessions.set(id, { server, transport });
},
}); });
transport.onclose = () => { transport.onclose = () => {
if (transport.sessionId) { if (transport.sessionId) sessions.delete(transport.sessionId);
sessions.delete(transport.sessionId);
}
}; };
await server.connect(transport); await server.connect(transport);
@@ -454,7 +423,7 @@ async function startHttp({ port, host }) {
app.delete("/mcp", handleOther); app.delete("/mcp", handleOther);
httpServer = app.listen(port, host, () => { httpServer = app.listen(port, host, () => {
console.log(`[video] MCP HTTP server listening on http://${host}:${port}/mcp → ${WB_BASE}`); console.log(`[video] MCP HTTP server listening on http://${host}:${port}/mcp`);
}); });
} }