@infimind/video-mcp-cli 1.0.5 → 1.0.6

package/README.md

@@ -50,7 +50,7 @@ Add the following to your Claude Desktop configuration file:
       "command": "sora-mcp",
       "args": ["--token=YOUR_TOKEN_HERE"],
       "env": {
-        "SORA_API_URL": "https://your-api-domain.com/api/trpc"
+        "SORA_API_URL": "https://your-api-domain.com/api"
       }
     }
   }
@@ -59,7 +59,7 @@ Add the following to your Claude Desktop configuration file:
 
 #### Environment Variables
 
-- `SORA_API_URL` (optional): Your API base URL. Defaults to `http://localhost:3000/api/trpc`
+- `SORA_API_URL` (optional): Your API base URL. Defaults to `http://localhost:3000/api`
 
 ### 3. Restart Claude Desktop
 
@@ -76,6 +76,159 @@ Get information about the authenticated user.
 Get my user information for the video generator
 ```
 
+### `create_video_task`
+
+Create a video generation task.
+
+Supported engines:
+
+- `S2`: 极睿Sa专业版
+- `S5`: 极睿Sd专业版 (VIP only)
+- `S6`: 极睿Ha专业版 (VIP only)
+
+Parameter applicability:
+
+| Parameter | S2 极睿Sa专业版 | S5 极睿Sd专业版 | S6 极睿Ha专业版 |
+| --- | --- | --- | --- |
+| `sourceImage` | Optional single image | Not recommended | Standard mode single image |
+| `sourceImages` | Not supported | allinone / firstlast images | reference / edit reference images |
+| `sourceVideos` | Not supported | allinone reference videos | edit input videos |
+| `sourceAudios` | Not supported | allinone reference audio | Not supported |
+| `taskMode` | Not needed | `allinone` / `firstlast` | `standard` / `reference` / `edit` |
+| `resolution` | Not supported | `480p` / `720p` / `1080p` | `720p` / `1080p` |
+| `inputDurationTier` | Not supported | `short` / `medium` / `long` | edit mode only |
+| `ratio` | Not supported | Not supported | reference or text-to-video standard mode |
+| `generateAudio` | Not supported | Optional | Not supported |
+| `webSearchEnabled` | Not supported | Optional | Not supported |
+| `dryRun` | Optional preflight | Optional preflight | Optional preflight |
+
+Local file paths and public URLs are both supported. Local files are converted to base64 by the MCP server before being sent to the API.
+
+Use `dryRun: true` to validate parameters, VIP access, estimated credits, and media rules without creating a task or deducting credits. The result includes `success`, `dryRun`, `route`, `engineName`, `taskMode`, `estimatedCredits`, `remainingCredits`, and `validationWarnings`.
+
+#### Dry run before creating a task
+
+```json
+{
+  "prompt": "@图片1 作为角色参考，生成自然的走秀镜头",
+  "route": "S6",
+  "taskMode": "reference",
+  "sourceImages": ["/path/to/character.jpg"],
+  "seconds": 10,
+  "ratio": "9:16",
+  "resolution": "720p",
+  "dryRun": true
+}
+```
+
+#### 极睿Sa专业版 - 标准生成
+
+```json
+{
+  "prompt": "一个高质感的产品展示视频，柔和布光，镜头缓慢推进",
+  "route": "S2",
+  "sourceImage": "/path/to/product.jpg",
+  "seconds": 10,
+  "size": "720x1280",
+  "language": "zh-CN",
+  "count": 1
+}
+```
+
+#### 极睿Sd专业版 - 全能参考
+
+```json
+{
+  "prompt": "根据参考素材生成一个高质感产品展示视频",
+  "route": "S5",
+  "taskMode": "allinone",
+  "sourceImages": ["/path/to/reference.jpg"],
+  "sourceVideos": ["/path/to/reference.mp4"],
+  "sourceAudios": ["/path/to/music.mp3"],
+  "seconds": 10,
+  "size": "720x1280",
+  "resolution": "720p",
+  "inputDurationTier": "medium",
+  "generateAudio": true,
+  "webSearchEnabled": false
+}
+```
+
+#### 极睿Sd专业版 - 首尾帧
+
+```json
+{
+  "prompt": "从首帧自然过渡到尾帧，保持产品主体一致",
+  "route": "S5",
+  "taskMode": "firstlast",
+  "sourceImages": ["/path/to/first-frame.jpg", "/path/to/end-frame.jpg"],
+  "seconds": 5,
+  "size": "1280x720",
+  "resolution": "720p"
+}
+```
+
+#### 极睿Ha专业版 - 标准模式
+
+Text-to-video:
+
+```json
+{
+  "prompt": "一段电影感城市夜景镜头，雨后街道反光，霓虹灯闪烁",
+  "route": "S6",
+  "taskMode": "standard",
+  "seconds": 5,
+  "size": "1280x720",
+  "ratio": "16:9",
+  "resolution": "720p"
+}
+```
+
+Image-to-video:
+
+```json
+{
+  "prompt": "让参考图中的商品在干净摄影棚中缓慢旋转展示",
+  "route": "S6",
+  "taskMode": "standard",
+  "sourceImage": "/path/to/product.jpg",
+  "seconds": 5,
+  "size": "720x1280",
+  "resolution": "720p"
+}
+```
+
+#### 极睿Ha专业版 - 图片参考
+
+```json
+{
+  "prompt": "@图片1 和 @图片2 作为角色参考，生成自然的走秀镜头",
+  "route": "S6",
+  "taskMode": "reference",
+  "sourceImages": ["/path/to/character-1.jpg", "/path/to/character-2.jpg"],
+  "seconds": 10,
+  "size": "720x1280",
+  "ratio": "9:16",
+  "resolution": "720p"
+}
+```
+
+#### 极睿Ha专业版 - 视频编辑
+
+```json
+{
+  "prompt": "增强视频的电影感光影，保持人物和商品一致",
+  "route": "S6",
+  "taskMode": "edit",
+  "sourceVideos": ["/path/to/input.mp4"],
+  "sourceImages": ["/path/to/reference.jpg"],
+  "resolution": "720p",
+  "inputDurationTier": "medium"
+}
+```
+
+After creating a task, use `get_video_status` with the returned `taskId` to query progress and video links.
+
 ## Development
 
 ```bash
@@ -89,10 +242,65 @@ npm install
 # Build
 npm run build
 
+# Run MCP smoke tests
+npm run test:smoke
+
 # Run in development mode
 node dist/index.js --token=YOUR_TOKEN
 ```
 
+### Local MCP testing
+
+#### MCP Inspector
+
+```bash
+cd mcp-server
+npm run build
+npx @modelcontextprotocol/inspector node dist/index.js --token=YOUR_TOKEN
+```
+
+Set `SORA_API_URL=http://localhost:3000/api` when testing against a local app server.
+
+#### Claude Desktop with local build
+
+```json
+{
+  "mcpServers": {
+    "sora-video-generator-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/sora_video_generator/mcp-server/dist/index.js", "--token=YOUR_TOKEN"],
+      "env": {
+        "SORA_API_URL": "http://localhost:3000/api"
+      }
+    }
+  }
+}
+```
+
+#### npx against the published package
+
+```json
+{
+  "mcpServers": {
+    "sora-video-generator": {
+      "command": "npx",
+      "args": ["-y", "@infimind/video-mcp-cli", "--token=YOUR_TOKEN"],
+      "env": {
+        "SORA_API_URL": "https://your-api-domain.com/api"
+      }
+    }
+  }
+}
+```
+
+### Troubleshooting
+
+- If a client reports schema mismatch, run `npm run build` and `npm run test:smoke` in `mcp-server`.
+- If `get_video_status` cannot connect, verify `SORA_API_URL` includes `/api`, for example `http://localhost:3000/api`.
+- If S5/S6 returns VIP errors, confirm the MCP token belongs to a VIP user.
+- If S6 reference/edit prompts contain `@图片N`, keep the original markers; those modes skip prompt translation to preserve image references.
+- If local file inputs fail, use absolute paths and supported media types: jpg/png/webp/gif, mp4/mov/avi/mkv, mp3/wav/m4a/aac/ogg.
+
 ## Publishing
 
 ```bash

package/dist/server.js

@@ -8,13 +8,26 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { readFileSync, existsSync } from "fs";
 import { extname, basename } from "path";
+import { MCP_SERVER_VERSION, getMcpDefaultTaskMode, getMcpEngineName, getMcpVideoStatusHint, isMcpRoute, isValidMcpTaskMode, } from "./videoRules.js";
+class McpToolError extends Error {
+    code;
+    route;
+    engineName;
+    constructor(message, code = "BAD_REQUEST", route) {
+        super(message);
+        this.name = "McpToolError";
+        this.code = code;
+        this.route = route;
+        this.engineName = route ? getMcpEngineName(route) : undefined;
+    }
+}
 /**
  * Create and configure the MCP Server
  */
 export function createServer(token, apiBaseUrl) {
     const server = new Server({
         name: "sora-video-generator-mcp",
-        version: "1.0.0",
+        version: MCP_SERVER_VERSION,
     }, {
         capabilities: {
             tools: {},
@@ -27,15 +40,34 @@ export function createServer(token, apiBaseUrl) {
         const tools = [
             {
                 name: "get_user_info",
+                title: "获取用户信息",
                 description: "获取当前用户的信息，包括用户名、姓名、邮箱、角色、积分和 VIP 状态",
                 inputSchema: {
                     type: "object",
                     properties: {},
                 },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        success: { type: "boolean" },
+                        id: { type: "number" },
+                        username: { type: "string" },
+                        name: { type: ["string", "null"] },
+                        email: { type: ["string", "null"] },
+                        role: { type: "string" },
+                        credits: { type: "number" },
+                        isVip: { type: "boolean" },
+                        code: { type: "string" },
+                        message: { type: "string" },
+                    },
+                    required: ["success"],
+                },
             },
             {
                 name: "create_video_task",
+                title: "创建视频生成任务",
                 description: "创建视频生成任务。支持本地文件路径或公网 URL 作为参考图片。" +
+                    "支持极睿Sd专业版和极睿Ha专业版的多模态素材输入。" +
                     "提示词会根据目标语言自动翻译和优化。",
                 inputSchema: {
                     type: "object",
@@ -46,16 +78,31 @@ export function createServer(token, apiBaseUrl) {
                         },
                         sourceImage: {
                             type: "string",
-                            description: "可选的参考图片 - 可以是本地文件路径（如 /path/to/image.jpg）或公网 URL。本地文件会被自动转换为 base64",
+                            description: "可选的单张参考图片。S2 使用此字段；S6 标准模式可用作单图图生视频。可以是本地文件路径或公网 URL，本地文件会被自动转换为 base64",
+                        },
+                        sourceImages: {
+                            type: "array",
+                            description: "S5/S6 多张参考图片。本地文件路径或公网 URL 数组；本地文件会被自动转换为 base64。S5 首尾帧模式下第1张为首帧、第2张为尾帧；S6 reference/edit 模式作为参考图",
+                            items: { type: "string" },
+                        },
+                        sourceVideos: {
+                            type: "array",
+                            description: "S5 全能参考或 S6 视频编辑模式的视频素材。本地文件路径或公网 URL 数组；本地文件会被自动转换为 base64",
+                            items: { type: "string" },
+                        },
+                        sourceAudios: {
+                            type: "array",
+                            description: "S5 全能参考模式的音频素材。本地文件路径或公网 URL 数组；本地文件会被自动转换为 base64",
+                            items: { type: "string" },
                         },
                         size: {
                             type: "string",
-                            description: "视频分辨率（默认：1280x720）",
-                            enum: ["1280x720", "720x1280"],
+                            description: "视频方向/比例。S2 支持横竖屏；S5/S6 还支持正方形、4:3、3:4（默认：1280x720）",
+                            enum: ["1280x720", "720x1280", "1024x1024", "1024x768", "768x1024"],
                         },
                         seconds: {
                             type: "number",
-                            description: "视频时长（秒）。S2路线: 10或15秒；S5路线: 5、10或15秒",
+                            description: "视频时长（秒）。S2=10或15秒；S5极睿Sd专业版=5、10或15秒；S6极睿Ha专业版 standard/reference=5、10或15秒，edit 模式由输入视频决定",
                             enum: [5, 10, 15],
                         },
                         language: {
@@ -71,15 +118,70 @@ export function createServer(token, apiBaseUrl) {
                         },
                         route: {
                             type: "string",
-                            description: "使用的 API 线路：S2=sora（默认）或 S5=seedance。注意：S5 (Seedance) 仅限 VIP 用户使用",
-                            enum: ["S2", "S5"],
+                            description: "使用的生成引擎：S2=极睿Sa专业版（默认）、S5=极睿Sd专业版、S6=极睿Ha专业版。注意：S5、S6 仅限 VIP 用户使用",
+                            enum: ["S2", "S5", "S6"],
+                        },
+                        taskMode: {
+                            type: "string",
+                            description: "引擎模式。S5: allinone=全能参考、firstlast=首尾帧；S6: standard=标准模式、reference=图片参考、edit=视频编辑",
+                            enum: ["allinone", "firstlast", "standard", "reference", "edit"],
+                        },
+                        resolution: {
+                            type: "string",
+                            description: "S5/S6 输出清晰度（默认：720p）",
+                            enum: ["480p", "720p", "1080p"],
+                        },
+                        inputDurationTier: {
+                            type: "string",
+                            description: "S5 或 S6 edit 模式的输入素材时长档位：short=0-4秒、medium=5-10秒、long=11-15秒（默认：short）",
+                            enum: ["short", "medium", "long"],
+                        },
+                        ratio: {
+                            type: "string",
+                            description: "S6 图片参考或标准文生视频模式的宽高比，例如 9:16、16:9、1:1、4:3、3:4",
+                            enum: ["16:9", "9:16", "1:1", "4:3", "3:4"],
+                        },
+                        generateAudio: {
+                            type: "boolean",
+                            description: "S5 极睿Sd专业版是否生成音频（默认：true）",
+                        },
+                        webSearchEnabled: {
+                            type: "boolean",
+                            description: "S5 极睿Sd专业版是否启用 Agent 增强（默认：false）",
+                        },
+                        dryRun: {
+                            type: "boolean",
+                            description: "仅执行参数、素材、权限和积分预检，不创建任务、不扣费。适合在正式创建前确认 S5/S6 参数是否可用",
                         },
                     },
                     required: ["prompt"],
                 },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        success: { type: "boolean" },
+                        taskId: { type: "number" },
+                        route: { type: "string" },
+                        engineName: { type: "string" },
+                        taskMode: { type: "string" },
+                        videoCount: { type: "number" },
+                        dryRun: { type: "boolean" },
+                        estimatedCredits: { type: "number" },
+                        remainingCredits: { type: "number" },
+                        statusHint: { type: "string" },
+                        validationWarnings: {
+                            type: "array",
+                            items: { type: "string" },
+                        },
+                        code: { type: "string" },
+                        message: { type: "string" },
+                    },
+                    required: ["success"],
+                },
             },
             {
                 name: "get_video_status",
+                title: "查询视频生成状态",
                 description: "获取视频生成任务的状态，包括进度和视频 URL",
                 inputSchema: {
                     type: "object",
@@ -91,9 +193,40 @@ export function createServer(token, apiBaseUrl) {
                     },
                     required: ["taskId"],
                 },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        success: { type: "boolean" },
+                        taskId: { type: "number" },
+                        status: { type: "string" },
+                        progress: { type: "number" },
+                        totalVideos: { type: "number" },
+                        completedVideos: { type: "number" },
+                        code: { type: "string" },
+                        message: { type: "string" },
+                        route: { type: "string" },
+                        engineName: { type: "string" },
+                        videos: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    id: { type: "number" },
+                                    status: { type: "string" },
+                                    videoUrl: { type: ["string", "null"] },
+                                    thumbnailUrl: { type: ["string", "null"] },
+                                    errorMessage: { type: ["string", "null"] },
+                                },
+                                required: ["id", "status", "videoUrl", "thumbnailUrl", "errorMessage"],
+                            },
+                        },
+                    },
+                    required: ["success"],
+                },
             },
             {
                 name: "create_video_analysis_task",
+                title: "创建视频拆解任务",
                 description: "创建视频拆解任务，将视频拆解为脚本、风格、卖点话术、爆款公式，并生成用于视频创作的提示词。" +
                     "支持本地文件路径或公网 URL 作为视频文件。本地文件会被自动转换为 base64。",
                 inputSchema: {
@@ -106,9 +239,23 @@ export function createServer(token, apiBaseUrl) {
                     },
                     required: ["videoFile"],
                 },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        success: { type: "boolean" },
+                        analysisId: { type: "number" },
+                        creditsUsed: { type: "number" },
+                        remainingCredits: { type: "number" },
+                        statusHint: { type: "string" },
+                        code: { type: "string" },
+                        message: { type: "string" },
+                    },
+                    required: ["success"],
+                },
             },
             {
                 name: "get_video_analysis_status",
+                title: "查询视频拆解状态",
                 description: "获取视频拆解任务的状态和结果",
                 inputSchema: {
                     type: "object",
@@ -120,6 +267,26 @@ export function createServer(token, apiBaseUrl) {
                     },
                     required: ["analysisId"],
                 },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        success: { type: "boolean" },
+                        analysisId: { type: "number" },
+                        status: { type: "string" },
+                        conversionProgress: { type: ["number", "null"] },
+                        script: { type: ["string", "null"] },
+                        style: { type: ["string", "null"] },
+                        sellingPoints: { type: ["string", "null"] },
+                        viralFormula: { type: ["string", "null"] },
+                        generatedPrompt: { type: ["string", "null"] },
+                        errorMessage: { type: ["string", "null"] },
+                        originalVideoUrl: { type: ["string", "null"] },
+                        videoFileName: { type: ["string", "null"] },
+                        code: { type: "string" },
+                        message: { type: "string" },
+                    },
+                    required: ["success"],
+                },
             },
         ];
         return { tools };
@@ -147,6 +314,7 @@ export function createServer(token, apiBaseUrl) {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
+            const toolError = error instanceof McpToolError ? error : undefined;
             return {
                 content: [
                     {
@@ -154,6 +322,13 @@ export function createServer(token, apiBaseUrl) {
                         text: `错误：${errorMessage}`,
                     },
                 ],
+                structuredContent: {
+                    success: false,
+                    code: toolError?.code || "INTERNAL_ERROR",
+                    message: errorMessage,
+                    route: toolError?.route,
+                    engineName: toolError?.engineName,
+                },
                 isError: true,
             };
         }
@@ -182,13 +357,23 @@ async function handleGetUserInfo(apiBaseUrl, token) {
                 text: userInfo,
             },
         ],
+        structuredContent: {
+            success: true,
+            id: response.id,
+            username: response.username,
+            name: response.name,
+            email: response.email,
+            role: response.role,
+            credits: response.credits,
+            isVip: Boolean(response.isVip),
+        },
     };
 }
 /**
  * 处理文件输入：支持本地文件路径或公网 URL
  * 对于本地文件，读取并转换为 base64
  */
-async function processFileInput(fileInput) {
+async function processFileInput(fileInput, expectedType) {
     // 检查是否是公网 URL
     if (fileInput.startsWith("http://") || fileInput.startsWith("https://")) {
         return {
@@ -202,7 +387,7 @@ async function processFileInput(fileInput) {
     const filePath = fileInput;
     // 检查文件是否存在
     if (!existsSync(filePath)) {
-        throw new Error(`文件不存在: ${filePath}`);
+        throw new McpToolError(`文件不存在: ${filePath}`, "FILE_NOT_FOUND");
     }
     // 读取文件
     const buffer = readFileSync(filePath);
@@ -219,9 +404,18 @@ async function processFileInput(fileInput) {
         ".mov": "video/quicktime",
         ".avi": "video/x-msvideo",
         ".mkv": "video/x-matroska",
+        ".mp3": "audio/mpeg",
+        ".wav": "audio/wav",
+        ".m4a": "audio/mp4",
+        ".aac": "audio/aac",
+        ".ogg": "audio/ogg",
     };
-    if (ext in mimeTypes) {
-        mimeType = mimeTypes[ext];
+    if (!(ext in mimeTypes)) {
+        throw new McpToolError(`不支持的文件类型：${ext || "无扩展名"}。请使用 jpg/png/webp/gif 图片、mp4/mov/avi/mkv 视频或 mp3/wav/m4a/aac/ogg 音频。`, "UNSUPPORTED_FILE_TYPE");
+    }
+    mimeType = mimeTypes[ext];
+    if (expectedType && !mimeType.startsWith(`${expectedType}/`)) {
+        throw new McpToolError(`文件 ${basename(filePath)} 类型不匹配：当前是 ${mimeType}，但该字段需要 ${expectedType} 文件。`, "INVALID_FILE_TYPE");
     }
     // 转换为 base64
     const base64 = `data:${mimeType};base64,${buffer.toString("base64")}`;
@@ -232,38 +426,191 @@ async function processFileInput(fileInput) {
         isUrl: false,
     };
 }
+async function processFileInputs(fileInputs, expectedType) {
+    if (!Array.isArray(fileInputs) || fileInputs.length === 0) {
+        return undefined;
+    }
+    const processed = await Promise.all(fileInputs
+        .filter((fileInput) => typeof fileInput === "string" && fileInput.length > 0)
+        .map(async (fileInput) => (await processFileInput(fileInput, expectedType)).data));
+    return processed.length > 0 ? processed : undefined;
+}
+function hasItems(value) {
+    return Array.isArray(value) && value.some((item) => typeof item === "string" && item.length > 0);
+}
+function normalizeRoute(value) {
+    const route = typeof value === "string" ? value : "S2";
+    if (!isMcpRoute(route)) {
+        throw new McpToolError("route 只能是 S2、S5 或 S6。S2=极睿Sa专业版，S5=极睿Sd专业版，S6=极睿Ha专业版。", "INVALID_ROUTE");
+    }
+    return route;
+}
+function normalizeTaskMode(route, value) {
+    const mode = typeof value === "string" ? value : getMcpDefaultTaskMode(route);
+    if (route === "S2") {
+        if (value !== undefined) {
+            throw new McpToolError("taskMode 仅适用于极睿Sd专业版或极睿Ha专业版；S2 极睿Sa专业版无需传 taskMode。", "UNSUPPORTED_FIELD", route);
+        }
+        return getMcpDefaultTaskMode(route);
+    }
+    if (!isValidMcpTaskMode(route, mode)) {
+        const allowedModes = route === "S5" ? "allinone 或 firstlast" : "standard、reference 或 edit";
+        throw new McpToolError(`${getMcpEngineName(route)} 的 taskMode 只能是 ${allowedModes}。`, "INVALID_TASK_MODE", route);
+    }
+    return mode;
+}
+function normalizeInputDurationTier(value) {
+    const tier = (typeof value === "string" ? value : "short");
+    if (!["short", "medium", "long"].includes(tier)) {
+        throw new McpToolError("inputDurationTier 只能是 short、medium 或 long。");
+    }
+    return tier;
+}
+function validateCreateVideoArgs(args) {
+    if (!args || typeof args !== "object") {
+        throw new McpToolError("请提供视频生成参数。");
+    }
+    if (!args.prompt || typeof args.prompt !== "string" || !args.prompt.trim()) {
+        throw new McpToolError("prompt 不能为空。");
+    }
+    const route = normalizeRoute(args.route);
+    const taskMode = normalizeTaskMode(route, args.taskMode);
+    const inputDurationTier = normalizeInputDurationTier(args.inputDurationTier);
+    const resolution = typeof args.resolution === "string" ? args.resolution : "720p";
+    const dryRun = args.dryRun === true;
+    if (route === "S2" && args.seconds === 5) {
+        throw new McpToolError("极睿Sa专业版不支持 5 秒视频，请使用 10 或 15 秒。", "INVALID_SECONDS", route);
+    }
+    if (route === "S2") {
+        const unsupported = [
+            hasItems(args.sourceImages) ? "sourceImages" : undefined,
+            hasItems(args.sourceVideos) ? "sourceVideos" : undefined,
+            hasItems(args.sourceAudios) ? "sourceAudios" : undefined,
+            args.resolution !== undefined ? "resolution" : undefined,
+            args.inputDurationTier !== undefined ? "inputDurationTier" : undefined,
+            args.ratio !== undefined ? "ratio" : undefined,
+            args.generateAudio !== undefined ? "generateAudio" : undefined,
+            args.webSearchEnabled !== undefined ? "webSearchEnabled" : undefined,
+        ].filter(Boolean);
+        if (unsupported.length > 0) {
+            throw new McpToolError(`这些字段不适用于极睿Sa专业版：${unsupported.join("、")}。S2 单图请使用 sourceImage。`, "UNSUPPORTED_FIELD", route);
+        }
+    }
+    if (route === "S5") {
+        if (args.sourceImage !== undefined) {
+            throw new McpToolError("sourceImage 不适用于极睿Sd专业版；请使用 sourceImages 传参考图或首尾帧。", "UNSUPPORTED_FIELD", route);
+        }
+        if (args.ratio !== undefined) {
+            throw new McpToolError("ratio 仅适用于极睿Ha专业版；极睿Sd专业版请使用 size 控制画面比例。", "UNSUPPORTED_FIELD", route);
+        }
+        if (taskMode === "firstlast" && !hasItems(args.sourceImages)) {
+            throw new McpToolError("极睿Sd专业版首尾帧模式需要在 sourceImages 中提供至少 1 张首帧图片。", "MISSING_SOURCE_IMAGE", route);
+        }
+        if (taskMode === "firstlast" && (hasItems(args.sourceVideos) || hasItems(args.sourceAudios))) {
+            throw new McpToolError("sourceVideos/sourceAudios 仅适用于极睿Sd专业版全能参考模式；首尾帧模式只使用 sourceImages。", "UNSUPPORTED_FIELD", route);
+        }
+    }
+    if (route === "S6") {
+        const unsupported = [
+            hasItems(args.sourceAudios) ? "sourceAudios" : undefined,
+            args.generateAudio !== undefined ? "generateAudio" : undefined,
+            args.webSearchEnabled !== undefined ? "webSearchEnabled" : undefined,
+        ].filter(Boolean);
+        if (unsupported.length > 0) {
+            throw new McpToolError(`这些字段仅适用于极睿Sd专业版，不能用于极睿Ha专业版：${unsupported.join("、")}。`, "UNSUPPORTED_FIELD", route);
+        }
+        if (taskMode === "standard" && (hasItems(args.sourceImages) || hasItems(args.sourceVideos))) {
+            throw new McpToolError("极睿Ha专业版标准模式只支持 sourceImage 作为单图输入；多图请使用 reference 模式，视频请使用 edit 模式。", "UNSUPPORTED_FIELD", route);
+        }
+        if ((taskMode === "reference" || taskMode === "edit") && args.sourceImage !== undefined) {
+            throw new McpToolError("sourceImage 仅适用于极睿Ha专业版标准模式；reference/edit 模式请使用 sourceImages。", "UNSUPPORTED_FIELD", route);
+        }
+        if (taskMode === "reference" && !hasItems(args.sourceImages)) {
+            throw new McpToolError("极睿Ha专业版图片参考模式需要在 sourceImages 中提供至少 1 张参考图片。", "MISSING_SOURCE_IMAGE", route);
+        }
+        if (taskMode === "edit" && !hasItems(args.sourceVideos)) {
+            throw new McpToolError("极睿Ha专业版视频编辑模式需要在 sourceVideos 中提供至少 1 个参考视频。", "MISSING_SOURCE_VIDEO", route);
+        }
+    }
+    return {
+        route,
+        taskMode,
+        resolution,
+        inputDurationTier,
+        dryRun,
+        statusHint: getMcpVideoStatusHint(dryRun),
+    };
+}
 /**
  * Handle create_video_task tool call
  */
 async function handleCreateVideoTask(apiBaseUrl, token, args) {
+    const normalized = validateCreateVideoArgs(args);
     const response = await callRestApi(apiBaseUrl, "/mcp/video/create", {
         token,
         prompt: args.prompt,
-        sourceImage: args.sourceImage ? (await processFileInput(args.sourceImage)).data : undefined,
+        sourceImage: args.sourceImage ? (await processFileInput(args.sourceImage, "image")).data : undefined,
+        sourceImages: await processFileInputs(args.sourceImages, "image"),
+        sourceVideos: await processFileInputs(args.sourceVideos, "video"),
+        sourceAudios: await processFileInputs(args.sourceAudios, "audio"),
         size: args.size || "1280x720",
         seconds: args.seconds || 10,
         language: args.language || "zh-CN",
         count: args.count || 1,
-        route: args.route || "S2",
+        route: normalized.route,
+        taskMode: normalized.taskMode,
+        isFirstLastMode: normalized.taskMode === "firstlast",
+        resolution: normalized.resolution,
+        inputDurationTier: normalized.inputDurationTier,
+        ratio: args.ratio || undefined,
+        generateAudio: args.generateAudio,
+        webSearchEnabled: args.webSearchEnabled,
+        dryRun: normalized.dryRun,
     }, "POST");
+    const route = response.route || normalized.route;
+    const engineName = response.engineName || getMcpEngineName(route);
+    const taskMode = response.taskMode || normalized.taskMode;
+    const estimatedCredits = response.estimatedCredits ?? response.creditsUsed;
+    const dryRun = response.dryRun === true || normalized.dryRun;
+    const statusHint = response.statusHint || normalized.statusHint;
     const result = [
-        `# 视频生成任务已创建`,
+        dryRun ? `# 视频生成参数预检通过` : `# 视频生成任务已创建`,
         ``,
-        `- **任务 ID**: ${response.taskId}`,
+        `- **生成引擎**: ${engineName}`,
+        `- **模式**: ${taskMode}`,
         `- **消息**: ${response.message}`,
         `- **生成视频数量**: ${response.videoCount}`,
-        `- **消耗积分**: ${response.creditsUsed}`,
-        `- **剩余积分**: ${response.remainingCredits}`,
-        ``,
-        `使用任务 ID ${response.taskId} 调用 \`get_video_status\` 查看进度。`,
-    ].join("\n");
+        `- **预估积分**: ${estimatedCredits ?? "N/A"}（视频完成后按成功扣费）`,
+        `- **当前积分**: ${response.remainingCredits}`,
+    ];
+    if (!dryRun && response.taskId !== undefined) {
+        result.splice(4, 0, `- **任务 ID**: ${response.taskId}`);
+    }
+    if (response.validationWarnings?.length) {
+        result.push(`- **预检提示**: ${response.validationWarnings.join("；")}`);
+    }
+    result.push(``, statusHint);
     return {
         content: [
             {
                 type: "text",
-                text: result,
+                text: result.join("\n"),
             },
         ],
+        structuredContent: {
+            success: response.success,
+            taskId: response.taskId,
+            route,
+            engineName,
+            taskMode,
+            videoCount: response.videoCount,
+            dryRun,
+            estimatedCredits,
+            remainingCredits: response.remainingCredits,
+            statusHint,
+            validationWarnings: response.validationWarnings || [],
+            message: response.message,
+        },
     };
 }
 /**
@@ -308,6 +655,15 @@ async function handleGetVideoStatus(apiBaseUrl, token, args) {
                 text: result.join("\n"),
             },
         ],
+        structuredContent: {
+            success: true,
+            taskId: response.taskId,
+            status: response.status,
+            progress: response.progress,
+            totalVideos: response.totalVideos,
+            completedVideos: response.completedVideos,
+            videos: response.videos || [],
+        },
     };
 }
 /**
@@ -316,7 +672,7 @@ async function handleGetVideoStatus(apiBaseUrl, token, args) {
 async function handleCreateVideoAnalysisTask(apiBaseUrl, token, args) {
     const response = await callRestApi(apiBaseUrl, "/mcp/video-analysis/create", {
         token,
-        videoFile: (await processFileInput(args.videoFile)).data,
+        videoFile: (await processFileInput(args.videoFile, "video")).data,
     }, "POST");
     const result = [
         `# 视频拆解任务已创建`,
@@ -335,6 +691,14 @@ async function handleCreateVideoAnalysisTask(apiBaseUrl, token, args) {
                 text: result,
             },
         ],
+        structuredContent: {
+            success: response.success,
+            analysisId: response.analysisId,
+            message: response.message,
+            creditsUsed: response.creditsUsed,
+            remainingCredits: response.remainingCredits,
+            statusHint: `使用分析 ID ${response.analysisId} 调用 get_video_analysis_status 查看进度。`,
+        },
     };
 }
 /**
@@ -402,6 +766,20 @@ async function handleGetVideoAnalysisStatus(apiBaseUrl, token, args) {
                 text: result.join("\n"),
             },
         ],
+        structuredContent: {
+            success: true,
+            analysisId: response.analysisId,
+            status: response.status,
+            conversionProgress: response.conversionProgress,
+            script: response.script,
+            style: response.style,
+            sellingPoints: response.sellingPoints,
+            viralFormula: response.viralFormula,
+            generatedPrompt: response.generatedPrompt,
+            errorMessage: response.errorMessage,
+            originalVideoUrl: response.originalVideoUrl,
+            videoFileName: response.videoFileName,
+        },
     };
 }
 /**
@@ -432,6 +810,22 @@ async function callRestApi(apiBaseUrl, path, params, method = "GET") {
     });
     if (!response.ok) {
         const errorText = await response.text();
+        try {
+            const parsed = JSON.parse(errorText);
+            const apiError = parsed?.error;
+            if (apiError?.message) {
+                const toolError = new McpToolError(apiError.message, apiError.code || `HTTP_${response.status}`, apiError.route);
+                if (apiError.engineName) {
+                    toolError.engineName = apiError.engineName;
+                }
+                throw toolError;
+            }
+        }
+        catch (error) {
+            if (error instanceof McpToolError) {
+                throw error;
+            }
+        }
         throw new Error(`API 请求失败，状态码 ${response.status}: ${errorText}`);
     }
     const data = await response.json();

package/dist/videoRules.d.ts

@@ -0,0 +1,17 @@
+export type McpRoute = "S2" | "S5" | "S6";
+export type McpTaskMode = "allinone" | "firstlast" | "standard" | "reference" | "edit";
+export declare const MCP_SERVER_VERSION = "1.0.5";
+export declare const MCP_VIDEO_STATUS_HINT = "\u4EFB\u52A1\u5DF2\u521B\u5EFA\u540E\uFF0C\u4F7F\u7528 get_video_status \u5E76\u4F20\u5165 taskId \u67E5\u8BE2\u751F\u6210\u8FDB\u5EA6\u548C\u89C6\u9891\u94FE\u63A5\u3002";
+export declare const MCP_VIDEO_DRY_RUN_HINT = "dryRun \u4EC5\u5B8C\u6210\u53C2\u6570\u3001\u6743\u9650\u3001\u79EF\u5206\u548C\u7D20\u6750\u89C4\u5219\u9884\u68C0\uFF0C\u4E0D\u4F1A\u521B\u5EFA\u4EFB\u52A1\u6216\u6263\u8D39\u3002";
+export declare const MCP_VIDEO_ENGINES: Record<McpRoute, {
+    engineName: string;
+    model: string;
+    defaultTaskMode: McpTaskMode;
+    taskModes: McpTaskMode[];
+}>;
+export declare function isMcpRoute(value: string): value is McpRoute;
+export declare function getMcpEngineName(route: string): string;
+export declare function getMcpTaskModel(route: McpRoute): string;
+export declare function getMcpDefaultTaskMode(route: McpRoute, isFirstLastMode?: boolean): McpTaskMode;
+export declare function isValidMcpTaskMode(route: McpRoute, taskMode: string): taskMode is McpTaskMode;
+export declare function getMcpVideoStatusHint(dryRun?: boolean): string;

package/dist/videoRules.js

@@ -0,0 +1,44 @@
+export const MCP_SERVER_VERSION = "1.0.5";
+export const MCP_VIDEO_STATUS_HINT = "任务已创建后，使用 get_video_status 并传入 taskId 查询生成进度和视频链接。";
+export const MCP_VIDEO_DRY_RUN_HINT = "dryRun 仅完成参数、权限、积分和素材规则预检，不会创建任务或扣费。";
+export const MCP_VIDEO_ENGINES = {
+    S2: {
+        engineName: "极睿Sa专业版",
+        model: "sora-2",
+        defaultTaskMode: "standard",
+        taskModes: ["standard"],
+    },
+    S5: {
+        engineName: "极睿Sd专业版",
+        model: "doubao-seedance-2-0-260128",
+        defaultTaskMode: "allinone",
+        taskModes: ["allinone", "firstlast"],
+    },
+    S6: {
+        engineName: "极睿Ha专业版",
+        model: "happyhorse-1.0",
+        defaultTaskMode: "standard",
+        taskModes: ["standard", "reference", "edit"],
+    },
+};
+export function isMcpRoute(value) {
+    return value === "S2" || value === "S5" || value === "S6";
+}
+export function getMcpEngineName(route) {
+    return isMcpRoute(route) ? MCP_VIDEO_ENGINES[route].engineName : MCP_VIDEO_ENGINES.S2.engineName;
+}
+export function getMcpTaskModel(route) {
+    return MCP_VIDEO_ENGINES[route].model;
+}
+export function getMcpDefaultTaskMode(route, isFirstLastMode) {
+    if (route === "S5" && isFirstLastMode === true) {
+        return "firstlast";
+    }
+    return MCP_VIDEO_ENGINES[route].defaultTaskMode;
+}
+export function isValidMcpTaskMode(route, taskMode) {
+    return MCP_VIDEO_ENGINES[route].taskModes.includes(taskMode);
+}
+export function getMcpVideoStatusHint(dryRun) {
+    return dryRun ? MCP_VIDEO_DRY_RUN_HINT : MCP_VIDEO_STATUS_HINT;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infimind/video-mcp-cli",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "MCP Server for Sora AI Video Generator - Access video generation features through Claude Desktop",
   "type": "module",
   "main": "dist/index.js",
@@ -14,6 +14,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "test:smoke": "node scripts/smoke-test.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [