@infimind/video-mcp-cli 1.0.7 → 1.0.8

package/README.md

@@ -21,7 +21,10 @@ npm install -g @infimind/video-mcp-cli
   "mcpServers": {
     "sora-video-generator": {
       "command": "npx",
-      "args": ["-y", "@infimind/video-mcp-cli", "--token=YOUR_TOKEN"]
+      "args": ["-y", "@infimind/video-mcp-cli"],
+      "env": {
+        "SORA_MCP_TOKEN": "YOUR_TOKEN"
+      }
     }
   }
 }
@@ -48,8 +51,8 @@ Add the following to your Claude Desktop configuration file:
   "mcpServers": {
     "sora-video-generator": {
       "command": "sora-mcp",
-      "args": ["--token=YOUR_TOKEN_HERE"],
       "env": {
+        "SORA_MCP_TOKEN": "YOUR_TOKEN_HERE",
         "SORA_API_URL": "https://your-api-domain.com/api"
       }
     }
@@ -59,8 +62,11 @@ Add the following to your Claude Desktop configuration file:
 
 #### Environment Variables
 
+- `SORA_MCP_TOKEN` (recommended): Your MCP API token. This avoids exposing the token in process arguments.
 - `SORA_API_URL` (optional): Your API base URL. Defaults to `http://localhost:3000/api`
 
+`--token=YOUR_TOKEN` remains supported for backward compatibility. `--token-env=CUSTOM_ENV_NAME` can be used when the token is stored in a different environment variable.
+
 ### 3. Restart Claude Desktop
 
 After saving the configuration, restart Claude Desktop for the changes to take effect.
@@ -105,6 +111,23 @@ Local file paths and public URLs are both supported. Local files are converted t
 
 Video inputs support MP4/MOV. Audio inputs support MP3/WAV. The server validates media duration, size, count, resolution, and URL safety before estimating credits or creating tasks.
 
+Media limits:
+
+- Local video files: MP4/MOV, up to 50MB each, 2-15 seconds.
+- Local audio files: MP3/WAV, up to 15MB each, 2-15 seconds.
+- S5 allinone: up to 9 images, 3 videos, and 3 audio files.
+- S5 firstlast: up to 2 images; the first frame is required.
+- S6 reference: up to 9 images.
+- S6 edit: up to 1 video and 5 images.
+- `inputDurationTier` is not accepted from clients; the server calculates it from the media.
+
+URL safety rules:
+
+- Only `http` and `https` URLs are accepted.
+- `localhost`, `127.0.0.1`, private network addresses, reserved IP ranges, and `file:` URLs are rejected.
+- Redirect targets are revalidated.
+- Remote files that are too large, not media, or cannot be safely probed are rejected.
+
 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`. Specific credit tables are server-side only; use dry run to get the current estimated consumption.
 
 #### Dry run before creating a task
@@ -132,7 +155,8 @@ Use `dryRun: true` to validate parameters, VIP access, estimated credits, and me
   "seconds": 10,
   "size": "720x1280",
   "language": "zh-CN",
-  "count": 1
+  "count": 1,
+  "dryRun": true
 }
 ```
 
@@ -150,7 +174,8 @@ Use `dryRun: true` to validate parameters, VIP access, estimated credits, and me
   "size": "720x1280",
   "resolution": "720p",
   "generateAudio": true,
-  "webSearchEnabled": false
+  "webSearchEnabled": false,
+  "dryRun": true
 }
 ```
 
@@ -164,7 +189,8 @@ Use `dryRun: true` to validate parameters, VIP access, estimated credits, and me
   "sourceImages": ["/path/to/first-frame.jpg", "/path/to/end-frame.jpg"],
   "seconds": 5,
   "size": "1280x720",
-  "resolution": "720p"
+  "resolution": "720p",
+  "dryRun": true
 }
 ```
 
@@ -180,7 +206,8 @@ Text-to-video:
   "seconds": 5,
   "size": "1280x720",
   "ratio": "16:9",
-  "resolution": "720p"
+  "resolution": "720p",
+  "dryRun": true
 }
 ```
 
@@ -194,7 +221,8 @@ Image-to-video:
   "sourceImage": "/path/to/product.jpg",
   "seconds": 5,
   "size": "720x1280",
-  "resolution": "720p"
+  "resolution": "720p",
+  "dryRun": true
 }
 ```
 
@@ -209,7 +237,8 @@ Image-to-video:
   "seconds": 10,
   "size": "720x1280",
   "ratio": "9:16",
-  "resolution": "720p"
+  "resolution": "720p",
+  "dryRun": true
 }
 ```
 
@@ -222,11 +251,12 @@ Image-to-video:
   "taskMode": "edit",
   "sourceVideos": ["/path/to/input.mp4"],
   "sourceImages": ["/path/to/reference.jpg"],
-  "resolution": "720p"
+  "resolution": "720p",
+  "dryRun": true
 }
 ```
 
-After creating a task, use `get_video_status` with the returned `taskId` to query progress and video links.
+After dry run succeeds and `estimatedCredits` looks correct, remove `dryRun` or set it to `false` to create the real task. After creating a task, use `get_video_status` with the returned `taskId` to query progress and video links.
 
 ## Development
 
@@ -245,7 +275,7 @@ npm run build
 npm run test:smoke
 
 # Run in development mode
-node dist/index.js --token=YOUR_TOKEN
+SORA_MCP_TOKEN=YOUR_TOKEN node dist/index.js
 ```
 
 ### Local MCP testing
@@ -255,7 +285,7 @@ node dist/index.js --token=YOUR_TOKEN
 ```bash
 cd mcp-server
 npm run build
-npx @modelcontextprotocol/inspector node dist/index.js --token=YOUR_TOKEN
+SORA_MCP_TOKEN=YOUR_TOKEN npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
 Set `SORA_API_URL=http://localhost:3000/api` when testing against a local app server.
@@ -267,8 +297,9 @@ Set `SORA_API_URL=http://localhost:3000/api` when testing against a local app se
   "mcpServers": {
     "sora-video-generator-local": {
       "command": "node",
-      "args": ["/absolute/path/to/sora_video_generator/mcp-server/dist/index.js", "--token=YOUR_TOKEN"],
+      "args": ["/absolute/path/to/sora_video_generator/mcp-server/dist/index.js"],
       "env": {
+        "SORA_MCP_TOKEN": "YOUR_TOKEN",
         "SORA_API_URL": "http://localhost:3000/api"
       }
     }
@@ -283,8 +314,9 @@ Set `SORA_API_URL=http://localhost:3000/api` when testing against a local app se
   "mcpServers": {
     "sora-video-generator": {
       "command": "npx",
-      "args": ["-y", "@infimind/video-mcp-cli", "--token=YOUR_TOKEN"],
+      "args": ["-y", "@infimind/video-mcp-cli"],
       "env": {
+        "SORA_MCP_TOKEN": "YOUR_TOKEN",
         "SORA_API_URL": "https://your-api-domain.com/api"
       }
     }
@@ -298,16 +330,23 @@ Set `SORA_API_URL=http://localhost:3000/api` when testing against a local app se
 - 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.
+- If local file inputs fail, use absolute paths and supported media types: jpg/png/webp/gif, mp4/mov, mp3/wav.
 
 ## Publishing
 
 ```bash
-# Build the package
+# Build and verify local dist
 npm run build
+npm run test:smoke
+
+# Verify the package contents that npm will publish
+npm run test:smoke:package
 
 # Publish to npm
 npm publish --access public
+
+# Optional after publishing: verify latest through npx
+npm run test:smoke:published
 ```
 
 ## Security

package/dist/index.js

@@ -4,23 +4,28 @@ import { createServer } from "./server.js";
 /**
  * CLI Entry Point for Sora MCP Server
  *
- * Usage: sora-mcp --token=YOUR_TOKEN
+ * Usage: sora-mcp
  *
  * Environment Variables:
+ *   SORA_MCP_TOKEN - MCP API token
  *   SORA_API_URL - API base URL (default: http://localhost:3000/api)
  */
 async function main() {
     // Parse command line arguments
     const args = process.argv.slice(2);
     const tokenArg = args.find(arg => arg.startsWith("--token="));
-    if (!tokenArg) {
-        console.error("Error: --token argument is required");
-        console.error("Usage: sora-mcp --token=YOUR_TOKEN");
+    const tokenEnvArg = args.find(arg => arg.startsWith("--token-env="));
+    const explicitTokenEnvName = tokenEnvArg?.split("=")[1];
+    const tokenEnvName = explicitTokenEnvName || "SORA_MCP_TOKEN";
+    if (tokenEnvArg && !explicitTokenEnvName) {
+        console.error("Error: --token-env value is empty");
+        console.error("Usage: sora-mcp --token-env=SORA_MCP_TOKEN");
         process.exit(1);
     }
-    const token = tokenArg.split("=")[1];
+    const tokenFromEnv = process.env[tokenEnvName];
+    const token = tokenFromEnv || tokenArg?.split("=")[1];
     if (!token) {
-        console.error("Error: Token value is empty");
+        console.error(`Error: token is required. Set ${tokenEnvName} or pass --token=YOUR_TOKEN.`);
         process.exit(1);
     }
     // Get API URL from environment variable or use default

package/dist/server.js

@@ -198,6 +198,19 @@ export function createServer(token, apiBaseUrl) {
                         progress: { type: "number" },
                         totalVideos: { type: "number" },
                         completedVideos: { type: "number" },
+                        estimatedCredits: { type: "number" },
+                        chargedVideos: { type: "number" },
+                        actualRoute: { type: "string" },
+                        taskMode: { type: ["string", "null"] },
+                        retryCount: { type: "number" },
+                        statusHint: { type: "string" },
+                        createdAt: { type: ["string", "null"] },
+                        updatedAt: { type: ["string", "null"] },
+                        completedAt: { type: ["string", "null"] },
+                        errorMessage: { type: "string" },
+                        errorCode: { type: "string" },
+                        errorCategory: { type: "string" },
+                        retryable: { type: "boolean" },
                         code: { type: "string" },
                         message: { type: "string" },
                         route: { type: "string" },
@@ -212,6 +225,14 @@ export function createServer(token, apiBaseUrl) {
                                     videoUrl: { type: ["string", "null"] },
                                     thumbnailUrl: { type: ["string", "null"] },
                                     errorMessage: { type: ["string", "null"] },
+                                    errorCode: { type: ["string", "null"] },
+                                    errorCategory: { type: ["string", "null"] },
+                                    retryable: { type: ["boolean", "null"] },
+                                    actualRoute: { type: ["string", "null"] },
+                                    retryCount: { type: "number" },
+                                    creditsCharged: { type: "boolean" },
+                                    createdAt: { type: ["string", "null"] },
+                                    completedAt: { type: ["string", "null"] },
                                 },
                                 required: ["id", "status", "videoUrl", "thumbnailUrl", "errorMessage"],
                             },
@@ -650,8 +671,21 @@ async function handleGetVideoStatus(apiBaseUrl, token, args) {
         `- **任务 ID**: ${response.taskId}`,
         `- **状态**: ${statusText}`,
         `- **进度**: ${response.progress}% (${response.completedVideos}/${response.totalVideos} 个视频)`,
+        response.engineName ? `- **生成引擎**: ${response.engineName}` : undefined,
+        response.taskMode ? `- **模式**: ${response.taskMode}` : undefined,
+        response.actualRoute ? `- **实际线路**: ${response.actualRoute}` : undefined,
+        typeof response.estimatedCredits === "number" ? `- **预估积分**: ${response.estimatedCredits}` : undefined,
+        typeof response.chargedVideos === "number" ? `- **已扣费视频**: ${response.chargedVideos}/${response.totalVideos}` : undefined,
+        typeof response.retryCount === "number" ? `- **重试次数**: ${response.retryCount}` : undefined,
         ``,
-    ];
+    ].filter((line) => line !== undefined);
+    if (response.errorMessage) {
+        result.push(`- **错误**: ${response.errorMessage}`);
+        if (response.errorCode) {
+            result.push(`- **错误代码**: ${response.errorCode}`);
+        }
+        result.push(``);
+    }
     if (response.videos && response.videos.length > 0) {
         result.push(`## 视频列表:`);
         response.videos.forEach((video, index) => {
@@ -669,8 +703,23 @@ async function handleGetVideoStatus(apiBaseUrl, token, args) {
             if (video.errorMessage) {
                 result.push(`   ❌ 错误: ${video.errorMessage}`);
             }
+            if (video.errorCode) {
+                result.push(`   错误代码: ${video.errorCode}`);
+            }
+            if (video.actualRoute) {
+                result.push(`   实际线路: ${video.actualRoute}`);
+            }
+            if (typeof video.retryCount === "number" && video.retryCount > 0) {
+                result.push(`   重试次数: ${video.retryCount}`);
+            }
+            if (typeof video.creditsCharged === "boolean") {
+                result.push(`   已扣费: ${video.creditsCharged ? "是" : "否"}`);
+            }
         });
     }
+    if (response.statusHint) {
+        result.push(``, response.statusHint);
+    }
     return {
         content: [
             {
@@ -685,6 +734,21 @@ async function handleGetVideoStatus(apiBaseUrl, token, args) {
             progress: response.progress,
             totalVideos: response.totalVideos,
             completedVideos: response.completedVideos,
+            route: response.route,
+            engineName: response.engineName,
+            taskMode: response.taskMode,
+            actualRoute: response.actualRoute,
+            retryCount: response.retryCount,
+            chargedVideos: response.chargedVideos,
+            estimatedCredits: response.estimatedCredits,
+            statusHint: response.statusHint,
+            createdAt: response.createdAt,
+            updatedAt: response.updatedAt,
+            completedAt: response.completedAt,
+            errorMessage: response.errorMessage,
+            errorCode: response.errorCode,
+            errorCategory: response.errorCategory,
+            retryable: response.retryable,
             videos: response.videos || [],
         },
     };
@@ -854,7 +918,11 @@ async function callRestApi(apiBaseUrl, path, params, method = "GET") {
     const data = await response.json();
     // Check for error in response
     if (data.error) {
-        throw new Error(data.error.message || "API 返回错误");
+        const toolError = new McpToolError(data.error.message || "API 返回错误", data.error.code || "API_ERROR", data.error.route);
+        if (data.error.engineName) {
+            toolError.engineName = data.error.engineName;
+        }
+        throw toolError;
     }
     return data;
 }

package/package.json

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