@starreel/mcp 0.1.58 → 0.1.59

package/SKILL.md

@@ -72,6 +72,7 @@ announces a condensed version as MCP `instructions` at connect time.
 | A finished **shot list** (per-shot seconds / shot size / camera move) | `get_storyboard_table_spec` (the contract: shot-size / camera-move vocabulary, body layout, text-card syntax, a prompt for the external AI) → `check_storyboard_table` (same parser as the import; clear `errors`, read every `warning` — a missing duration, an unrecognised shot size or an empty body all get imported as-is) → `import_storyboard_table` (defaults to `auto_complete`: one background batch fills the professional fields and expands every shot's platform-built base description into full image / video prompts — metered text, tell the customer first; `auto_complete: false` imports only) → `get_autofill_status` until `done` → `review_storyboards` | `rewrite_script` + `generate_storyboards` — strips every production parameter (measured: 8 shots / 36 s became 20 shots / 109 s); importing without the check; reviewing before the completion batch finishes (the token expires when shots change) |
 | **Structured data** — their own tool / spreadsheet export, or an external AI producing JSON (cast + scenes + shots in one go) | `get_bulk_import_spec` (contract + template + worked example + enums, same source as the validator) → `check_bulk_import` (same zod schema; unresolved character / scene references, dead shots and stage directions inside dialogue are surfaced) → `bulk_import_storyboards` (`mode: "replace"` only with the customer's explicit OK; defaults to `auto_complete`: professional fields for every shot, full image / video prompts only for shots that had no `image_prompt` — prompts you supply yourself are kept verbatim — metered text, tell the customer first) → `get_autofill_status` until `done` → `review_storyboards` | converting the JSON to text for `import_storyboard_table`; hand-building shots with `update_shot`; reviewing before the completion batch finishes |
 | Their own portraits / scene / prop / shot images | `upload_image` · `set_character_portrait` · `upload_scene_image` · `upload_prop_sheet` · `upload_shot_frame` | rendering a "fix" elsewhere and uploading it — use `generate_shot_frame` |
+| A scene plate that came out wrong (backdrop, era, light, layout) | `get_scene_prompt` → `update_scene` (`image_prompt`) → `regenerate_scene_image`; already-rendered shot frames still anchor on the old plate, so regenerate those shots too | re-running `generate_scene_images` (it only fills scenes that have **no** plate — it will not touch this one) |
 | A voice sample / a required voice | `clone_voice` → `speak_with_voice` → `set_character_voice` / `assign_voices` | cloning without the rights-holder's consent |
 | A song + lyrics | `create_drama` (`project_type: "mv"`) → `set_mv_lyrics` → `generate_mv_story` → `generate_mv_script` | `rewrite_script` (blocked for MV) |
 | A product / brand | `create_drama` (`project_type: "ad"` or `"brand_film"`) → `add_product` → `generate_product_sheet` | writing brand copy as dialogue (it gets spoken) |
@@ -410,6 +411,14 @@ is only the part you write: the platform still layers identity anchors and
 consistency constraints on top at generation time. Editing a prompt does not
 re-generate anything — regenerate the shot afterwards.
 
+The same applies one layer up, to the **scene plate** (the empty backdrop every
+shot in that scene anchors on): `get_scene_prompt` reads one scene's prompt body,
+`update_scene` writes it back as `image_prompt`, and `regenerate_scene_image`
+re-renders that one scene — overwriting whatever plate it had, including an
+uploaded one. Write the plate body as an environment with no people in it;
+characters enter at the shot-frame layer. Shot frames already rendered are not
+re-rendered with it: they still carry the old plate as their background anchor.
+
 ## Failure playbook
 
 Failures surface as a human-readable `message` (MCP throws `Error(message)`;

package/dist/tools/guide-data.js

@@ -188,6 +188,7 @@ export const PIPELINE = [
             'generate_world_concept(默认必做,仍走报价)', 'generate_motion_templates', 'generate_color_script',
             'generate_art_bible', 'extract_visual_lock', 'extract_setting_brief', 'generate_video_style',
             'quote_scene_images', 'generate_scene_images', 'generate_prop_sheet',
+            'get_scene_prompt(读某场空景图的提示词正文,免费)', 'update_scene(image_prompt 改正文)', 'regenerate_scene_image(单场重出)',
         ],
         billing: '报价确认后扣点',
         note: '分镜后建只给出场角色出图更省;动作模板本就必须分镜后。',
@@ -233,6 +234,7 @@ export const QA_TOOLS = [
     { symptom: '动作发生在裁剪窗口之外', run: 'recommend_trim_window', then: ['trim_shot'] },
     { symptom: '画面多出一个人 / 多出一件道具', run: 'get_storyboards(先看该镜实际用的首帧)', then: ['generate_shot_frame(首帧本身就有→重生首帧再重生视频)', 'split_shot(帧干净、片中长出来→拆成 3~5 秒短镜)'] },
     { symptom: '出图 / 出视频前想知道哪些镜会被厂商拒', run: 'run_precheck', then: ['update_shot', 'generate_shot_frame'] },
+    { symptom: '场景图(空景基板)不对 / 重出还是同一类图', run: 'get_scene_prompt', then: ['update_scene(改 image_prompt 正文——只改地点/时段是让平台重拼,拧不过来)', 'regenerate_scene_image(单场重出,覆盖旧图)', 'upload_scene_image(客户自有实拍/外部精修图)', 'generate_shot_frame(下游镜头帧不会自动跟着重出)'] },
     { symptom: '整集健康度 / 缺镜 / 进度', run: 'get_pipeline_status', then: ['get_health_report', 'review_all', 'get_storyboards', 'get_jobs', 'get_run_status', 'get_autofill_status(导入/一键填空的后台补全进度)'] },
     { symptom: '预算 / 余额', run: 'get_budget_status', then: ['get_cost_estimate'] },
 ];
@@ -241,7 +243,7 @@ export const OPTIONAL_BOOSTS = [
     { what: '美术圣经 / 视觉锁 / 世界观 Brief 抽取', tool: 'generate_art_bible', when: '建剧后;或 `extract_visual_lock` / `extract_setting_brief` 从剧本反推' },
     { what: '动作模板(统一全片运动语言)', tool: 'generate_motion_templates', when: '分镜后、出图前;漏了动作会散乱' },
     { what: '色彩脚本(统一色调)', tool: 'generate_color_script', when: '分镜后、出图前' },
-    { what: '场景图(空景基板)', tool: 'generate_scene_images', when: '出镜头图前;先 `quote_scene_images`' },
+    { what: '场景图(空景基板)', tool: 'generate_scene_images', when: '出镜头图前;先 `quote_scene_images`。出得不对:`get_scene_prompt` 读正文 → `update_scene` 改 image_prompt → `regenerate_scene_image` 单场重出' },
     { what: '场景组(同场景多镜一次成组出视频)', tool: 'generate_scene_groups', when: '先 `get_scene_group_plan` 看方案' },
     { what: '口型同步', tool: 'lipsync_episode', when: 'TTS 配音项目需要对口型时' },
     { what: '海报 / 封面', tool: 'generate_episode_poster', when: '成片后;`generate_drama_poster` / `generate_cover` 同族' },

package/dist/tools/produce.js

@@ -875,7 +875,10 @@ export function registerProduceTools(server, client) {
         profile_locked: z.number().int().min(0).max(1).optional().describe('1=锁定档案(AI 提取不再覆盖外貌/性格/描述,防定妆图换脸);0=解锁'),
     }, async ({ character_id, ...fields }) => jsonResult(await client.producePut(`/characters/${character_id}`, fields)));
     server.tool('delete_character', '删除一个角色(提取误建/合并时用)。免费。', { character_id: z.number().int().positive() }, async ({ character_id }) => jsonResult(await client.produceDelete(`/characters/${character_id}`)));
-    server.tool('update_scene', '改场景设定(名字/描述/地点/时段/氛围)。免费。', {
+    server.tool('update_scene', '改场景设定(名字/描述/地点/时段/氛围),以及**场景图的出图提示词正文**(image_prompt)。免费(纯文本写库)。' +
+        '★场景图不满意时,改 image_prompt 才是直接手段——只改地点/时段是让平台重拼,拧不过来;' +
+        '改前先用 get_scene_prompt 读现值,改完用 regenerate_scene_image 重出这一场的图。' +
+        '★场景图变了不会自动重出已生成的镜头帧:那些帧仍拿旧场景图当背景锚,要跟上得逐镜重出。', {
         scene_id: z.number().int().positive(),
         name: z.string().optional(),
         description: z.string().optional(),
@@ -883,7 +886,18 @@ export function registerProduceTools(server, client) {
         physical_location: z.string().optional(),
         time_of_day: z.string().optional(),
         mood: z.string().optional(),
+        image_prompt: z.string().optional()
+            .describe('这一场**空景图**的提示词正文(全量覆盖本场现值)。★先 get_scene_prompt 读现值再改;★写空景——这张是场景基板,画面里不该有人物(人物由镜头帧那层注入)。出图时平台会在正文之上再拼画风块、空景约束与时代锁,不必你写'),
     }, async ({ scene_id, ...fields }) => jsonResult(await client.producePut(`/scenes/${scene_id}`, fields)));
+    server.tool('get_scene_prompt', '读某一场**场景图(空景基板)**的提示词正文,供直接微调后用 update_scene 的 image_prompt 写回。免费。' +
+        '★逐场按需:改哪场读哪场(整集列表 get_scenes 是纯资产视图,不含提示词)。' +
+        '★这是场景表里的正文层;出图时平台还会在其上拼画风块、空景约束与时代锁(不在此处,也无需你写)。' +
+        '回执的 has_image 说明这一场是否已有图。', { scene_id: z.number().int().positive() }, async ({ scene_id }) => jsonResult(await client.produceGet(`/scenes/${scene_id}/prompt`)));
+    server.tool('regenerate_scene_image', '按当前提示词重出**这一场**的场景图(改完 image_prompt 让画面跟上)。图片步,按用量后付不欠费。' +
+        '★覆盖式:出好后本场旧图被换掉(要留档先 get_scene_prompt/资产列表拿旧图 URL)。' +
+        '★已生成的镜头帧不会自动跟着重出——它们仍拿旧场景图当背景锚,要跟上得逐镜重出。' +
+        '★与 generate_scene_images 的区别:那个是整剧批量、只补**缺图**的场景,已有图的一律跳过;' +
+        '这个是单场景强制重出。客户自己上传过的场景图也会被覆盖,先确认是不是要保留。', { scene_id: z.number().int().positive() }, async ({ scene_id }) => jsonResult(await client.producePost(`/scenes/${scene_id}/image/regenerate`)));
     server.tool('delete_scene', '删除一个场景。免费。', { scene_id: z.number().int().positive() }, async ({ scene_id }) => jsonResult(await client.produceDelete(`/scenes/${scene_id}`)));
     server.tool('generate_character_sheet', '给**单个**角色出三视图设定图(镜头一致性根锚,所有镜头帧都会引用;比定妆图更完整)。整集批量用 generate_character_sheets。' +
         '前置:该角色已有定妆图。图片步,按用量后付不欠费。', { character_id: z.number().int().positive(), episode_id: z.number().int().positive().optional() }, async ({ character_id, episode_id }) => jsonResult(await client.producePost(`/characters/${character_id}/sheet`, episode_id ? { episode_id } : {})));

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.58",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → 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). 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.58 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.59",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → 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). 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.59 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -5803,8 +5803,8 @@
     "/scenes/{scene_id}": {
       "put": {
         "operationId": "update_scene",
-        "summary": "改场景设定(名字/描述/地点/时段/氛围)",
-        "description": "改场景设定(名字/描述/地点/时段/氛围)。免费。",
+        "summary": "改场景设定(名字/描述/地点/时段/氛围),以及**场景图的出图提示词正文**(image_prompt)",
+        "description": "改场景设定(名字/描述/地点/时段/氛围),以及**场景图的出图提示词正文**(image_prompt)。免费(纯文本写库)。★场景图不满意时,改 image_prompt 才是直接手段——只改地点/时段是让平台重拼,拧不过来;改前先用 get_scene_prompt 读现值,改完用 regenerate_scene_image 重出这一场的图。★场景图变了不会自动重出已生成的镜头帧:那些帧仍拿旧场景图当背景锚,要跟上得逐镜重出。",
         "tags": [
           "scenes"
         ],
@@ -5843,6 +5843,9 @@
                   },
                   "mood": {
                     "type": "string"
+                  },
+                  "image_prompt": {
+                    "type": "string"
                   }
                 }
               }
@@ -5922,6 +5925,100 @@
         }
       }
     },
+    "/scenes/{scene_id}/image/regenerate": {
+      "post": {
+        "operationId": "regenerate_scene_image",
+        "summary": "按当前提示词重出**这一场**的场景图(改完 image_prompt 让画面跟上)",
+        "description": "按当前提示词重出**这一场**的场景图(改完 image_prompt 让画面跟上)。图片步,按用量后付不欠费。★覆盖式:出好后本场旧图被换掉(要留档先 get_scene_prompt/资产列表拿旧图 URL)。★已生成的镜头帧不会自动跟着重出——它们仍拿旧场景图当背景锚,要跟上得逐镜重出。★与 generate_scene_images 的区别:那个是整剧批量、只补**缺图**的场景,已有图的一律跳过;这个是单场景强制重出。客户自己上传过的场景图也会被覆盖,先确认是不是要保留。",
+        "tags": [
+          "scenes"
+        ],
+        "parameters": [
+          {
+            "name": "scene_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"
+          }
+        }
+      }
+    },
+    "/scenes/{scene_id}/prompt": {
+      "get": {
+        "operationId": "get_scene_prompt",
+        "summary": "读某一场**场景图(空景基板)**的提示词正文,供直接微调后用 update_scene 的 image_prompt 写回",
+        "description": "读某一场**场景图(空景基板)**的提示词正文,供直接微调后用 update_scene 的 image_prompt 写回。免费。★逐场按需:改哪场读哪场(整集列表 get_scenes 是纯资产视图,不含提示词)。★这是场景表里的正文层;出图时平台还会在其上拼画风块、空景约束与时代锁(不在此处,也无需你写)。回执的 has_image 说明这一场是否已有图。",
+        "tags": [
+          "scenes"
+        ],
+        "parameters": [
+          {
+            "name": "scene_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"
+          }
+        }
+      }
+    },
     "/script-format/lint": {
       "post": {
         "operationId": "check_script_format",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "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.58",
+  "version": "0.1.59",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.58",
+      "version": "0.1.59",
       "transport": {
         "type": "stdio"
       },