@starreel/mcp 0.1.9 → 0.1.11

package/README.md

@@ -5,6 +5,10 @@ StarReel 的 MCP 服务器 —— 把 AI 短剧**编排产线**暴露给 Claude
 
 完整接入文档:https://api.shortreelai.com/docs/mcp
 
+**给 AI agent 的操作 Skill 与纪律**:本包内 [`SKILL.md`](./SKILL.md) —— 一份平台无关的
+操作手册(完整产线顺序 + 十条接入纪律 + 失败处理决策)。支持 Skill 的客户端会自动加载;
+不能 npx 的平台(Coze / Dify / GPTs / 自研 agent)可把它整段贴进 system prompt。
+
 ## 接入
 
 1. 在 StarReel → 设置 → API Key 创建一把 `produce` scope 的 key(`srk_live_...`,只展示一次)。

package/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: starreel-drama-production
+description: >-
+  Operating skill for any AI agent driving the StarReel short-drama production
+  pipeline (script → rewrite → extract → portraits → storyboards → frames →
+  video → voiceover → final cut) over MCP or REST. Covers the ordered workflow,
+  the ten operating disciplines (prepaid billing, quote-before-spend, retryable
+  failure handling, content compliance, tenancy), and a failure playbook.
+license: MIT
+homepage: https://api.shortreelai.com/docs/mcp
+---
+
+# StarReel Drama Production — Agent Skill
+
+You are an agent driving **StarReel**, a prepaid AI short-drama production
+pipeline. You turn a raw script into a finished, downloadable episode by
+calling StarReel tools (over MCP) or endpoints (`/v1/produce/*` over REST). This
+skill tells you the workflow and the non-negotiable disciplines. Read it before
+you spend anything.
+
+Never invent character names, titles, dialogue, or genre from your own
+imagination and bake them into calls — the content comes from the user's script.
+All examples below use placeholders like `<raw script>` and `<drama title>`.
+
+## What you produce
+
+One episode, the **full** pipeline — nothing skipped:
+
+```
+create_drama → set_script(raw) → rewrite_script(AI draft, user may edit)
+  → extract_assets(cast/scenes/props) → generate_character_portraits(identity anchor)
+  → storyboards → frames → videos → generate_tts(voiceover) → compose_episode → final cut (.mp4 link)
+```
+
+`project_type` picks the flavor at `create_drama`: `drama` / `ad` / `mv` /
+`brand_film`. MV replaces `rewrite_script` with
+`set_mv_lyrics → generate_mv_story → generate_mv_script`, then rejoins the
+standard extract → storyboards → … flow. Call `list_project_options` first to
+show the user the real project types, aspect ratios, and resolutions.
+
+Free steps: `create_drama`, `set_script`, all `get_*`, edits, `compose_episode`.
+Metered text (post-paid): `rewrite_script`, `extract_assets`. Every image/video
+step is split into `quote_*` + `generate_*`.
+
+## The ten disciplines (hard rules)
+
+These are not suggestions. Violating them wastes the user's money or produces
+content that will be rejected.
+
+1. **Prepaid — never overdraft.** The account can never go negative. Before a
+   large spend, if unsure of balance, call `get_budget_status` /
+   `get_cost_estimate`. On `402 insufficient_credits` (carries `needed`), STOP
+   and tell the user to recharge. Never loop-retry a 402 — it will never
+   succeed and only spins.
+
+2. **Quote before you spend; the quote is the charge.** Every spending step is
+   `quote_*` then `generate_*`. Show the user the quoted cost and get an
+   explicit yes before calling `generate_*`. For video, quote == actual charge.
+   Do not auto-approve large spends on the user's behalf.
+
+3. **`retryable` decides retry-vs-change — never blind-retry.** On failure read
+   the structured `fail_reason` / `retryable` (from `get_storyboards`) or the
+   `message` / `error.type`. `retryable:false` (moderation, copyright, quota,
+   overdue) → change the content or stop; retrying is useless. `retryable:true`
+   (KYC-queuing, rate-limit, transient) → back off, then retry.
+
+4. **Content must be compliant.** Do not generate copyrighted characters,
+   trademarks, real-person likenesses, or sensitive content. On a moderation /
+   copyright rejection, rewrite toward **generic, original** imagery — do not
+   fight the gate by retrying the same prompt.
+
+5. **Voice cloning requires consent.** Only clone a voice from a sample the
+   user is authorized to use (their own voice, or a rights-holder's written
+   consent). `clone_voice` is billed per voice (auto-refunded on failure).
+   Never clone a public figure's or third party's voice without authorization.
+
+6. **Follow the pipeline order — do not skip.** `set_script` → `rewrite_script`
+   → `extract_assets` → portraits → storyboards → frames → videos. Always
+   generate frames **before** videos; skipping frames degrades video into
+   anchorless t2v — wasted money. Lock character portraits before video for
+   identity consistency.
+
+7. **Poll, don't block; don't hammer.** Long steps return immediately as
+   `status:generating`. Poll `get_pipeline_status` / `get_jobs` /
+   `get_storyboards` with a backoff (start ~5–10s, widen on no change). Stable
+   counts = done. Do not tight-loop the API.
+
+8. **Idempotency — don't double-charge.** A `quote_id` is one-time and expires
+   in ~15 min; never reuse it or call `generate_*` twice for the same intent.
+   Before regenerating an asset, read its current state first — don't re-pay for
+   something already produced.
+
+9. **Stay in your tenant.** You only ever see your own resources. Someone
+   else's id returns `404` by design (cross-tenant probes never leak
+   existence). Do not guess ids.
+
+10. **Be transparent; keep secrets safe.** Report the quote, the failure
+    reason, and what was actually spent — never fabricate success. Keep the API
+    key in an environment variable or secrets manager, never in code or logs.
+    The 15-min token auto-re-exchanges; a leaked key is revoked in Settings.
+
+## Failure playbook
+
+Failures surface as a human-readable `message` (MCP throws `Error(message)`;
+REST returns `{ code, message }`, or on `/v1/ai/*`:
+`{ error: { message, type, needed?, retryable? } }`). Per-shot, `get_storyboards`
+gives structured `frame_status` / `video_status` / `fail_reason` / `retryable` /
+`fail_hint`. Map the reason to an action:
+
+| fail_reason | retryable | What it means | Do |
+|---|---|---|---|
+| `sensitive` | false | Frame hit content moderation | Change the picture / swap reference, regenerate |
+| `text_sensitive` | false | The **prompt text** was flagged (no charge) | Reword the prompt (not the image), retry |
+| `copyright` | false | Copyright / trademark / real-person likeness | Switch to generic original imagery |
+| `face_mismatch` | false | Portrait ≠ the authorized person | Swap the portrait / confirm same person |
+| `account_overdue` | false | Upstream vendor account overdue (platform-level) | Not self-healable — tell the user; do **not** touch the prompt |
+| `quota_full` | false | Platform vendor-asset quota exhausted | Retry won't help — contact ops |
+| `insufficient_credits` | false | Balance too low for this call | Stop, prompt to recharge (402) |
+| `authorizing` | true | Face frame queuing for KYC (not a rejection) | Wait ~1 min, retry |
+| `transient` | true | BestOfN / quality-gate / rate-limit / network | Back off, retry |
+| `unknown` | false | Unclassified | Read `fail_hint`; don't auto-retry |
+
+Three action classes, one decision: **moderation / identity / copyright → change
+content**; **overdue / token → not self-healable (tell user / wait)**; **network
+/ timeout / transient → retry**. Failed spends are auto-refunded (pre-hold →
+refund on failure); you never compensate manually.
+
+## Quick tool reference
+
+- **Discover / create**: `list_project_options`, `create_drama`,
+  `update_project_settings`
+- **Script**: `set_script`, `rewrite_script`, `get_script`,
+  `edit_rewritten_script`, `extract_assets`
+- **Identity & consistency**: `generate_character_portraits`, `upload_image`,
+  `set_character_portrait`, `generate_character_sheet`, `extract_visual_lock`
+- **Shots → video**: `quote/generate_storyboards`, `get_storyboards`,
+  `quote/generate_frames`, `chain_frames`, `quote/generate_videos`
+- **Audio**: `generate_tts` (required before final cut), `clone_voice`,
+  `set_character_voice`, `list_voices`, `generate_bgm`, `replace_shot_dialogue`
+- **Finish**: `compose_episode`, `get_final_cut`, `get_export`,
+  `generate_episode_poster`, `generate_cover`
+- **Edit**: `edit_video_shot`, `regenerate_shot_video`, `split_shot`,
+  `trim_shot`, `rerender_episode`
+- **Read back (all free)**: `list_dramas`, `get_drama`, `get_characters`,
+  `get_scenes`, `get_assets`, `get_jobs`, `get_pipeline_status`,
+  `get_cost_estimate`, `get_budget_status`
+
+Full reference: https://api.shortreelai.com/docs/mcp

package/dist/tools/produce.js

@@ -314,4 +314,23 @@ export function registerProduceTools(server, client) {
         image_url: z.string().optional().describe('商品图 URL(先 upload_image 拿)'),
     }, async ({ drama_id, ...fields }) => jsonResult(await client.producePost(`/dramas/${drama_id}/products`, fields)));
     server.tool('list_products', '广告项目:列出商品库。免费。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/products`)));
+    // ========== AI 声音克隆(voice cloning)==========
+    server.tool('clone_voice', '从一段**已授权**的音频样本克隆音色,存入你的音色库,返回音色 id。' +
+        '⚠️ 样本必须是本人/持权人**同意授权**的声音(否则侵权,与真人/版权门同理)。' +
+        '按平台价计费(每个音色一口价);失败自动退款。之后 set_character_voice 绑到角色,generate_tts 即用它配音。', {
+        name: z.string().min(1).describe('音色命名(便于管理)'),
+        sample_file_path: z.string().optional().describe('本地授权音频样本路径(mp3/wav/m4a,自动上传;与 sample_url 二选一)'),
+        sample_url: z.string().optional().describe('已上传到 COS 的样本 URL(与 sample_file_path 二选一)'),
+        notes: z.string().optional().describe('备注(可选)'),
+    }, async ({ name, sample_file_path, sample_url, notes }) => {
+        let url = sample_url;
+        if (!url && sample_file_path)
+            url = await client.uploadLocalFile(sample_file_path, 'audio');
+        if (!url)
+            throw new Error('需要 sample_file_path(本地样本自动上传)或 sample_url(已上传的 URL)');
+        return jsonResult(await client.producePost('/voice-clones', notes ? { name, sample_url: url, notes } : { name, sample_url: url }));
+    });
+    server.tool('list_voices', '列出我音色库里的克隆音色(id/名字/状态)。免费。', {}, async () => jsonResult(await client.produceGet('/voice-clones')));
+    server.tool('delete_voice', '删除音色库里的一个克隆音色。免费。', { voice_clone_id: z.number().int().positive() }, async ({ voice_clone_id }) => jsonResult(await client.produceDelete(`/voice-clones/${voice_clone_id}`)));
+    server.tool('set_character_voice', '把克隆音色绑到某角色(voice_clone_id 来自 clone_voice/list_voices)。绑定后 generate_tts 用它给该角色配音。免费。', { character_id: z.number().int().positive(), voice_clone_id: z.number().int().positive().describe('音色库 id') }, async ({ character_id, voice_clone_id }) => jsonResult(await client.producePost(`/characters/${character_id}/voice`, { library_id: voice_clone_id })));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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",
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "README.md",
+    "SKILL.md",
     "server.json"
   ],
   "scripts": {

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.9",
+  "version": "0.1.10",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.9",
+      "version": "0.1.10",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         {