@starreel/mcp 0.1.238 → 0.1.240

package/SKILL.md

@@ -444,7 +444,14 @@ content that will be rejected.
    leave characters drifting across angle / lighting / wardrobe.
    `generate_portraits_and_sheets` does both (portraits first, then sheets).
    **`generate_videos` has no per-shot parameter** — it renders every shot of
-   the episode that still lacks a video, in one run. When a native-audio project
+   the episode that still lacks a video, in one run. Track that run with
+   `get_run_status` → `video_run` (shots with video / remaining; it survives a
+   server restart and is resumed automatically where enabled — `status=interrupted`
+   means re-quote and call `generate_videos` again, finished shots are skipped).
+   To stop that run, call `cancel_videos` only when the customer asks: shots
+   already sent to the vendor still finish and are still charged; the rest are
+   not dispatched (re-quote later to continue).
+   When a native-audio project
    needs one seed shot per speaking character before locking voices, render those
    seeds with the single-shot tools `quote_regenerate_shot_video` →
    `regenerate_shot_video` (they work on a shot that has no video yet), lock the

package/dist/tools/guide-data.js

@@ -272,7 +272,7 @@ export const PIPELINE = [
     },
     {
         step: '8 出视频',
-        tools: ['quote_videos', 'generate_videos', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities', 'get_repaint_capabilities', 'quote_repaint_shot_video', 'repaint_shot_video', 'quote_reskin_shot_video', 'reskin_shot_video', 'get_repaint_status', 'restore_repaint_original', 'get_av_anchors(定妆视频锚现况:挂锚的镜首尾帧不送)', 'clear_character_av_anchor(客户确认后摘锚·免费)'],
+        tools: ['quote_videos', 'generate_videos', 'cancel_videos(停整集出视频:已派的照常出完扣费,未派的不再派·免费)', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities', 'get_repaint_capabilities', 'quote_repaint_shot_video', 'repaint_shot_video', 'quote_reskin_shot_video', 'reskin_shot_video', 'get_repaint_status', 'restore_repaint_original', 'get_av_anchors(定妆视频锚现况:挂锚的镜首尾帧不送)', 'clear_character_av_anchor(客户确认后摘锚·免费)'],
         billing: '报价确认后扣点',
         note: 'video_engine 必须在出视频前定(写实真人剧 seedance-2.5 或降本 hailuo-3 / 动漫·风格化 seedance-2.5 或 wan3.0·wan 绝不用于写实真人;' + MODEL_AVAILABILITY_NOTE + ');切换不回溯已生成镜头。',
     },

package/dist/tools/produce.js

@@ -776,7 +776,13 @@ export function registerProduceTools(server, client) {
         '用法:发起后每 30~60 秒调一次。running:true = 还在跑,继续等,**千万不要重发**' +
         '(重发拆镜会替换整集分镜,已调好/已出图的全丢、要重花钱);' +
         'running:false = 那次已经结束,这时才去 get_storyboards / get_script 看产物有没有落库。\n' +
-        '⚠️ 服务重启会让在途登记归零,重启期间发起的运行也会显示为无在途。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/run-status`)));
+        '⚠️ 服务重启会让 agent 在途登记归零,重启期间发起的运行也会显示为无在途。\n' +
+        '★generate_videos 整集出视频的接力链看返回里的 video_run 段(它落库,重启不会凭空消失):' +
+        'shots_total / shots_with_video / shots_remaining = 共几镜、已出几镜、剩几镜;running:true = 链在跑,别重发 generate_videos;' +
+        'resumed_after_restart>0 = 中途服务重启过、已自动续跑(已出视频与中断前已派发的镜不重出不重扣);' +
+        'status=interrupted = 重启后没自动续跑(interrupt_reason 写原因),重新 quote_videos 后 generate_videos 会跳过已出的镜;' +
+        'shots_dispatched_without_video = 派发过但没出片的镜,用 get_jobs 看原因、regenerate_shot_video 单补;' +
+        'status=cancelling / cancelled = 客户用 cancel_videos 停了这条链,cancelled_shot_numbers 是没出没扣费的镜。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/run-status`)));
     // ---------- 分镜级 AI 操作:2 个免费质量闸 + 3 个 AI 增强(★都在出图前做)----------
     server.tool('run_precheck', '(★推荐·免费质量闸)出图/出视频前跑生成前预检,把会被拒的镜提前揪出。免费、不扣费。' +
         '强烈建议 generate_frames/generate_videos 前调,防白花钱被拒。\n' +
@@ -1132,6 +1138,12 @@ export function registerProduceTools(server, client) {
         quote_id: z.string().describe('来自 quote_videos'),
         ...REVIEW_ARGS,
     }, async ({ episode_id, quote_id, review_token, acknowledge_review, auto_acknowledge }) => jsonResult(await client.producePost(`/episodes/${episode_id}/videos/generate`, { quote_id, review_token, acknowledge_review, auto_acknowledge })));
+    // ---------- 取消整集出视频(免费) ----------
+    server.tool('cancel_videos', '(免费)停掉本集 generate_videos 发起的整集出视频接力链。语义:**已派给厂商的镜照常出完、照常扣费(不退)**;还没派的不再派、不扣费;' +
+        '取消后服务重启也不会自动续跑。回执里 in_flight_shot_numbers = 已派出、会照常出完扣费的镜;cancelled_shot_numbers = 被取消、没出没扣费的镜。' +
+        'status=cancelling 表示链会在当前镜之后停下,用 get_run_status 等 video_run.status 变成 cancelled。' +
+        '被取消的镜之后可以重新 quote_videos 再 generate_videos 接着做(会跳过已出视频的镜),或 quote_regenerate_shot_video / regenerate_shot_video 单镜补。' +
+        '★只在客户明确要停时调用。单镜在途的视频(regenerate_shot_video 等)不能中途取消;本集没有在跑的整批链会返回 409 NO_ACTIVE_VIDEO_RUN。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/videos/cancel`)));
     // ---------- 成片(compose/终拼) ----------
     server.tool('compose_episode', '把某一集所有镜头视频拼成一条成片(终拼)。**免费**(纯拼接,无需报价确认),后台异步。' +
         '发起前有终拼预检:缺视频的镜或仍在生成中的视频任务会 400 硬阻断并列出问题镜(blockers),' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.238",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.238 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.240",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.240 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -9329,7 +9329,7 @@
       "get": {
         "operationId": "get_run_status",
         "summary": "(★免费·长耗时操作后必用)查这一集当前有没有 agent 正在跑",
-        "description": "(★免费·长耗时操作后必用)查这一集当前有没有 agent 正在跑。rewrite_script / extract_assets / generate_storyboards 都是**分钟级**后台任务,它们只回一句 status:\"generating\",本工具是唯一能区分「还在跑」与「已经结束」的手段。\n★典型耗时(生产实测):改写 2~4 分钟、拆镜 5~10 分钟——**单次 LLM 调用就可能 3~7 分钟**。所以 60 秒内查不到结果是完全正常的,绝不是失败。\n用法:发起后每 30~60 秒调一次。running:true = 还在跑,继续等,**千万不要重发**(重发拆镜会替换整集分镜,已调好/已出图的全丢、要重花钱);running:false = 那次已经结束,这时才去 get_storyboards / get_script 看产物有没有落库。\n⚠️ 服务重启会让在途登记归零,重启期间发起的运行也会显示为无在途。",
+        "description": "(★免费·长耗时操作后必用)查这一集当前有没有 agent 正在跑。rewrite_script / extract_assets / generate_storyboards 都是**分钟级**后台任务,它们只回一句 status:\"generating\",本工具是唯一能区分「还在跑」与「已经结束」的手段。\n★典型耗时(生产实测):改写 2~4 分钟、拆镜 5~10 分钟——**单次 LLM 调用就可能 3~7 分钟**。所以 60 秒内查不到结果是完全正常的,绝不是失败。\n用法:发起后每 30~60 秒调一次。running:true = 还在跑,继续等,**千万不要重发**(重发拆镜会替换整集分镜,已调好/已出图的全丢、要重花钱);running:false = 那次已经结束,这时才去 get_storyboards / get_script 看产物有没有落库。\n⚠️ 服务重启会让 agent 在途登记归零,重启期间发起的运行也会显示为无在途。\n★generate_videos 整集出视频的接力链看返回里的 video_run 段(它落库,重启不会凭空消失):shots_total / shots_with_video / shots_remaining = 共几镜、已出几镜、剩几镜;running:true = 链在跑,别重发 generate_videos;resumed_after_restart>0 = 中途服务重启过、已自动续跑(已出视频与中断前已派发的镜不重出不重扣);status=interrupted = 重启后没自动续跑(interrupt_reason 写原因),重新 quote_videos 后 generate_videos 会跳过已出的镜;shots_dispatched_without_video = 派发过但没出片的镜,用 get_jobs 看原因、regenerate_shot_video 单补;status=cancelling / cancelled = 客户用 cancel_videos 停了这条链,cancelled_shot_numbers 是没出没扣费的镜。",
         "tags": [
           "episodes"
         ],
@@ -11110,6 +11110,53 @@
         }
       }
     },
+    "/episodes/{episode_id}/videos/cancel": {
+      "post": {
+        "operationId": "cancel_videos",
+        "summary": "(免费)停掉本集 generate_videos 发起的整集出视频接力链",
+        "description": "(免费)停掉本集 generate_videos 发起的整集出视频接力链。语义:**已派给厂商的镜照常出完、照常扣费(不退)**;还没派的不再派、不扣费;取消后服务重启也不会自动续跑。回执里 in_flight_shot_numbers = 已派出、会照常出完扣费的镜;cancelled_shot_numbers = 被取消、没出没扣费的镜。status=cancelling 表示链会在当前镜之后停下,用 get_run_status 等 video_run.status 变成 cancelled。被取消的镜之后可以重新 quote_videos 再 generate_videos 接着做(会跳过已出视频的镜),或 quote_regenerate_shot_video / regenerate_shot_video 单镜补。★只在客户明确要停时调用。单镜在途的视频(regenerate_shot_video 等)不能中途取消;本集没有在跑的整批链会返回 409 NO_ACTIVE_VIDEO_RUN。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/episodes/{episode_id}/videos/generate": {
       "post": {
         "operationId": "generate_videos",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.238",
+  "version": "0.1.240",
   "mcpName": "ai.starreel/starreel",
   "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
   "license": "MIT",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "ai.starreel/starreel",
   "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
-  "version": "0.1.238",
+  "version": "0.1.240",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.238",
+      "version": "0.1.240",
       "transport": {
         "type": "stdio"
       },