@starreel/mcp 0.1.41 → 0.1.43

package/README.md

@@ -1,51 +1,194 @@
-# @starreel/mcp
+# StarReel MCP
 
-StarReel 的 MCP 服务器 —— 把 AI 短剧**编排产线**暴露给 Claude Code / Cursor /
-任何 MCP 客户端:让 AI agent 一句话从**剧本跑到可下载的成片**。
+> Turn a script into a finished, downloadable short-drama episode — from Claude, Cursor, or any MCP client.
 
-完整接入文档:https://api.shortreelai.com/docs/mcp
+[![npm version](https://img.shields.io/npm/v/%40starreel%2Fmcp)](https://www.npmjs.com/package/@starreel/mcp)
+[![npm downloads](https://img.shields.io/npm/dm/%40starreel%2Fmcp)](https://www.npmjs.com/package/@starreel/mcp)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**给 AI agent 的操作 Skill 与纪律**:本包内 [`SKILL.md`](./SKILL.md) —— 一份平台无关的
-操作手册(完整产线顺序 + 十条接入纪律 + 失败处理决策)。支持 Skill 的客户端会自动加载;
-不能 npx 的平台(Coze / Dify / GPTs / 自研 agent)可把它整段贴进 system prompt。
+**StarReel** is a prepaid AI video-production pipeline. This MCP server exposes the
+whole factory — **80+ tools** covering every stage — so an AI agent can take a raw
+script all the way to a finished `.mp4`:
 
-## 接入
+```
+script → AI rewrite → cast / scenes / props extraction → character portraits & sheets
+       → storyboards → keyframes → video shots → voiceover (TTS) → final cut (.mp4 link)
+```
+
+It is a thin, open client: all the heavy lifting (character-consistency gates,
+frame chaining, best-of-N auditing, billing) runs server-side at
+[starreel.ai](https://starreel.ai).
+
+## Quick start
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=starreel&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzdGFycmVlbC9tY3AiXSwiZW52Ijp7IlNUQVJSRUVMX0FQSV9LRVkiOiJzcmtfbGl2ZV94eHgifX0=)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF)](https://vscode.dev/redirect/mcp/install?name=starreel&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40starreel%2Fmcp%22%5D%2C%22env%22%3A%7B%22STARREEL_API_KEY%22%3A%22srk_live_xxx%22%7D%7D)
 
-1. 在 StarReel → 设置 → API Key 创建一把 `produce` scope 的 key(`srk_live_...`,只展示一次)。
-2. Claude Code:
+1. Create an API key with `produce` scope in **StarReel → Settings → API Keys**
+   (`srk_live_...`, shown once).
+2. Add the server to Claude Code:
 
 ```bash
 claude mcp add starreel -e STARREEL_API_KEY=srk_live_xxx -- npx -y @starreel/mcp
 ```
 
-其他 MCP 客户端(Cursor 等)照各自配置格式填 `npx -y @starreel/mcp` + 环境变量即可。
+Or install the **Claude Code plugin** — MCP server + agent skill in one step
+(set `STARREEL_API_KEY` in your shell first):
+
+```text
+/plugin marketplace add waydaxp/starreel-mcp
+/plugin install starreel@starreel
+```
+
+3. Ask your agent: *"Take this script and produce a full episode: `<your script>`"* —
+   it will quote each paid stage first and only spend after you confirm.
+
+## Works with any MCP client
+
+Requires Node ≥ 18 (`npx`). The **standard config** below works as-is in
+**Cursor · Windsurf · Cline / Roo Code · Claude Desktop · Trae · Cherry Studio ·
+Chatbox · DeepChat** and any client that reads an `mcpServers` JSON block:
+
+```json
+{
+  "mcpServers": {
+    "starreel": {
+      "command": "npx",
+      "args": ["-y", "@starreel/mcp"],
+      "env": { "STARREEL_API_KEY": "srk_live_xxx" }
+    }
+  }
+}
+```
+
+Clients with their own format:
+
+<details>
+<summary><b>Codex CLI</b> — <code>~/.codex/config.toml</code></summary>
+
+```toml
+[mcp_servers.starreel]
+command = "npx"
+args = ["-y", "@starreel/mcp"]
+env = { "STARREEL_API_KEY" = "srk_live_xxx" }
+```
+</details>
+
+<details>
+<summary><b>VS Code (Copilot agent mode)</b> — <code>.vscode/mcp.json</code> or user <code>mcp.json</code></summary>
+
+```json
+{
+  "servers": {
+    "starreel": {
+      "command": "npx",
+      "args": ["-y", "@starreel/mcp"],
+      "env": { "STARREEL_API_KEY": "srk_live_xxx" }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Gemini CLI</b> — <code>~/.gemini/settings.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "starreel": {
+      "command": "npx",
+      "args": ["-y", "@starreel/mcp"],
+      "env": { "STARREEL_API_KEY": "srk_live_xxx" }
+    }
+  }
+}
+```
+</details>
 
-## 产线工具(从剧本到成片)
+<details>
+<summary><b>No Node / can't run npx?</b> (Coze, Dify, GPTs, custom agents)</summary>
 
-一集短剧的完整链路,每个花钱阶段先报价、你确认后才执行:
+Drive the same pipeline over REST (`/v1/produce/*`) and paste
+[`SKILL.md`](./SKILL.md) into your system prompt — it carries the full
+workflow order, billing disciplines, and failure playbook.
+See the [API docs](https://api.shortreelai.com/docs/mcp).
+</details>
 
-| 阶段 | 工具 |
+## What's inside
+
+| Stage | Tools (selection) |
 |---|---|
-| 建剧 | `create_drama`(建剧壳+自动建集,返回 episode_id) |
-| 灌本 | `set_script` |
-| 拆镜 | `quote_storyboards` → `generate_storyboards` → `get_storyboards`(审阅) |
-| 出首帧 | `quote_frames` → `generate_frames` |
-| 出视频 | `quote_videos` → `generate_videos`(大额,报价与扣费同函数) |
-| 成片 | `compose_episode`(免费终拼) → `get_final_cut`(拿 COS 下载链接) |
+| Project setup | `create_drama` · `update_project_settings` · `list_project_options` |
+| Script | `set_script` · AI rewrite · `edit_rewritten_script` |
+| Cast & world | asset extraction · `update_character` · `generate_world_concept` · `generate_art_bible` |
+| Identity anchors | `generate_portraits_and_sheets` (portraits + character sheets = the consistency anchor) |
+| Storyboards | `quote_storyboards` → `generate_storyboards` → `get_storyboards` |
+| Frames & video | `quote_frames` → `generate_frames` · `quote_videos` → `generate_videos` |
+| Audio | `generate_tts` · `generate_bgm` · `generate_sfx` · voice management |
+| Finishing | `compose_episode` (free) · `get_final_cut` · `render_multi_aspect` · posters & covers |
+| Localization | `translate_subtitles` · localization jobs |
+| Ads / MV modes | product library & product sheets · MV lyrics → story → script |
+
+Project types: `drama` / `ad` / `mv` / `brand_film`.
 
-**批量报价确认**:每个 `quote_*` 返回预估点数,agent 应把点数告诉你、你同意后才用返回的
-`quote_id` 调 `generate_*`。整集一次执行,不逐图打扰。长任务后台异步,用 `get_storyboards`/
-`get_final_cut` 轮询到完成。
+## Billing is agent-safe by design
 
-## 计费与安全
+- **Prepaid, never negative.** Costs are pre-authorized *before* any vendor call;
+  insufficient balance returns a clean `402` — nothing half-runs.
+- **Quote before spend.** Big-ticket stages are `quote_*` → show the user →
+  `generate_*` with the returned `quote_id`. For video, **quote == actual charge**
+  (same function computes both).
+- **Final cut is free.** Composition, transitions, SFX matching and deliverable
+  packaging don't bill.
+- API keys are stored hashed and exchanged for 15-minute short-lived tokens;
+  revoke in Settings at any time.
 
-- 预付制:必须有余额才能生成,账户**永不为负**;成本在调厂商**之前**预授权,不够返回 402。
-- 视频报价 == 实际扣费(同一函数);终拼(成片)免费。
-- API key 只存哈希;换取的是 15 分钟短期令牌;泄露在设置页吊销即失效,不影响网页登录。
+## Built for agents: the operating skill
+
+[`SKILL.md`](./SKILL.md) ships inside the package — a platform-agnostic operating
+manual (full pipeline order + ten operating disciplines + a failure playbook).
+Skill-aware clients load it automatically; on platforms that can't run `npx`
+(Coze / Dify / GPTs / custom agents) paste it into the system prompt and drive
+the same pipeline over REST (`/v1/produce/*`).
+
+Install it as a standalone agent skill (Claude Code, Codex, Cursor, OpenCode
+and [70+ agents](https://github.com/vercel-labs/skills#supported-agents)) via
+the [`skills`](https://skills.sh) CLI:
+
+```bash
+npx skills add waydaxp/starreel-mcp
+```
 
-## 环境变量
+## Environment variables
 
-| 变量 | 必填 | 默认 |
+| Variable | Required | Default |
 |---|---|---|
 | `STARREEL_API_KEY` | ✅ | — |
 | `STARREEL_AUTH_BASE` | | `https://api.shortreelai.com` |
+
+## REST API (OpenAPI)
+
+Prefer plain REST? The full production facade is described in
+[`openapi.json`](./openapi.json) (OpenAPI 3.1, 100+ operations — generated from
+this package's tool surface, so `operationId`s match MCP tool names 1:1).
+Browse it rendered at
+[waydaxp.github.io/starreel-mcp](https://waydaxp.github.io/starreel-mcp/), or
+generate a typed client for any language:
+
+```bash
+npx openapi-typescript https://raw.githubusercontent.com/waydaxp/starreel-mcp/main/openapi.json -o starreel.d.ts
+```
+
+## Links
+
+- Website: [starreel.ai](https://starreel.ai)
+- API reference (OpenAPI): [waydaxp.github.io/starreel-mcp](https://waydaxp.github.io/starreel-mcp/)
+- Full MCP / REST docs: [api.shortreelai.com/docs/mcp](https://api.shortreelai.com/docs/mcp)
+- npm: [@starreel/mcp](https://www.npmjs.com/package/@starreel/mcp)
+- 中文文档: [README.zh-CN.md](./README.zh-CN.md)
+
+## License
+
+[MIT](./LICENSE) — this client is open; the production pipeline is a hosted service.

package/README.zh-CN.md

@@ -0,0 +1,108 @@
+# @starreel/mcp
+
+StarReel 的 MCP 服务器 —— 把 AI 短剧**编排产线**暴露给 Claude Code / Cursor /
+任何 MCP 客户端:让 AI agent 一句话从**剧本跑到可下载的成片**。
+
+完整接入文档:https://api.shortreelai.com/docs/mcp
+
+**给 AI agent 的操作 Skill 与纪律**:本包内 [`SKILL.md`](./SKILL.md) —— 一份平台无关的
+操作手册(完整产线顺序 + 十条接入纪律 + 失败处理决策)。支持 Skill 的客户端会自动加载;
+不能 npx 的平台(Coze / Dify / GPTs / 自研 agent)可把它整段贴进 system prompt。
+
+也可用 [`skills`](https://skills.sh) CLI 一条命令装成独立 agent skill
+(Claude Code / Codex / Cursor / OpenCode 等 70+ 工具):
+
+```bash
+npx skills add waydaxp/starreel-mcp
+```
+
+## 接入
+
+1. 在 StarReel → 设置 → API Key 创建一把 `produce` scope 的 key(`srk_live_...`,只展示一次)。
+2. Claude Code:
+
+```bash
+claude mcp add starreel -e STARREEL_API_KEY=srk_live_xxx -- npx -y @starreel/mcp
+```
+
+也可装 **Claude Code 插件**——MCP server + agent skill 一步到位
+(先在 shell 里 `export STARREEL_API_KEY=srk_live_xxx`):
+
+```text
+/plugin marketplace add waydaxp/starreel-mcp
+/plugin install starreel@starreel
+```
+
+一键安装:
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=starreel&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzdGFycmVlbC9tY3AiXSwiZW52Ijp7IlNUQVJSRUVMX0FQSV9LRVkiOiJzcmtfbGl2ZV94eHgifX0=)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF)](https://vscode.dev/redirect/mcp/install?name=starreel&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40starreel%2Fmcp%22%5D%2C%22env%22%3A%7B%22STARREEL_API_KEY%22%3A%22srk_live_xxx%22%7D%7D)
+
+## 全客户端接入
+
+要求 Node ≥ 18(能跑 `npx`)。下面这段**标准配置**在
+**Cursor · Windsurf · Cline / Roo Code · Claude Desktop · Trae · Cherry Studio ·
+Chatbox · DeepChat** 及任何读 `mcpServers` JSON 的客户端里通用:
+
+```json
+{
+  "mcpServers": {
+    "starreel": {
+      "command": "npx",
+      "args": ["-y", "@starreel/mcp"],
+      "env": { "STARREEL_API_KEY": "srk_live_xxx" }
+    }
+  }
+}
+```
+
+格式不同的客户端:
+
+- **Codex CLI** — `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.starreel]
+command = "npx"
+args = ["-y", "@starreel/mcp"]
+env = { "STARREEL_API_KEY" = "srk_live_xxx" }
+```
+
+- **VS Code(Copilot agent 模式)** — `.vscode/mcp.json` 或用户级 `mcp.json`,外层键是 `servers` 而非 `mcpServers`,内容同标准配置。
+- **Gemini CLI** — `~/.gemini/settings.json`,直接放标准配置。
+- **跑不了 npx 的平台(扣子 Coze / Dify / GPTs / 自研 agent)** — 走 REST(`/v1/produce/*`)+ 把 [`SKILL.md`](./SKILL.md) 整段贴进 system prompt,见[接入文档](https://api.shortreelai.com/docs/mcp)。
+
+## 产线工具(从剧本到成片)
+
+一集短剧的完整链路,每个花钱阶段先报价、你确认后才执行:
+
+| 阶段 | 工具 |
+|---|---|
+| 建剧 | `create_drama`(建剧壳+自动建集,返回 episode_id) |
+| 灌本 | `set_script` |
+| 拆镜 | `quote_storyboards` → `generate_storyboards` → `get_storyboards`(审阅) |
+| 出首帧 | `quote_frames` → `generate_frames` |
+| 出视频 | `quote_videos` → `generate_videos`(大额,报价与扣费同函数) |
+| 成片 | `compose_episode`(免费终拼) → `get_final_cut`(拿 COS 下载链接) |
+
+**批量报价确认**:每个 `quote_*` 返回预估点数,agent 应把点数告诉你、你同意后才用返回的
+`quote_id` 调 `generate_*`。整集一次执行,不逐图打扰。长任务后台异步,用 `get_storyboards`/
+`get_final_cut` 轮询到完成。
+
+## 计费与安全
+
+- 预付制:必须有余额才能生成,账户**永不为负**;成本在调厂商**之前**预授权,不够返回 402。
+- 视频报价 == 实际扣费(同一函数);终拼(成片)免费。
+- API key 只存哈希;换取的是 15 分钟短期令牌;泄露在设置页吊销即失效,不影响网页登录。
+
+## REST API(OpenAPI)
+
+想直接裸调 REST?整个产线门面见 [`openapi.json`](./openapi.json)
+(OpenAPI 3.1,100+ 操作,从本包工具面生成,operationId 与 MCP 工具名一一对应)。
+在线渲染版:[waydaxp.github.io/starreel-mcp](https://waydaxp.github.io/starreel-mcp/);
+也可用它给任意语言生成带类型客户端(如 `npx openapi-typescript`)。
+
+## 环境变量
+
+| 变量 | 必填 | 默认 |
+|---|---|---|
+| `STARREEL_API_KEY` | ✅ | — |
+| `STARREEL_AUTH_BASE` | | `https://api.shortreelai.com` |

package/SKILL.md

@@ -147,6 +147,16 @@ content that will be rejected.
    `generate_frames` / `generate_shot_frame` may override per call. Options:
    `gemini-3-pro-image` (Nano Banana Pro, finer, pricier), `gemini-3.1-flash-lite-image`
    (Lite, cheap), `doubao-seedream-5-0-260128` (Seedream 5.0), `gpt-image-2`.
+   **Video engine**: videos use a drama-level engine, set via `create_drama` /
+   `update_project_settings` field `video_engine`. Two options — surface the
+   choice to the customer with the price gap and let them decide:
+   `seedance-2.5` (default; full capability: frame chain / scene groups /
+   in-place edit / extend / reference anchors; 720p ≈ 212 pts/s) or `hailuo-3`
+   (MiniMax H3, beta; ≈1/3 cost at 70 pts/s for 720p; native dialogue & SFX
+   baked into the clip; up to 2K; ~6 min per shot; in-place edit / extend /
+   keyframe groups not yet available). **Set it before generating any video**:
+   switching never re-renders existing shots, and mixing engines inside one
+   drama risks style/identity drift.
    **Images are slow** (tens of seconds to minutes each; a whole episode can take
    10+ min): poll `get_storyboards` and read `frame_status` — `pending` = still
    generating (keep waiting, NEVER re-call generate_frames — that double-charges),
@@ -283,6 +293,18 @@ refund on failure); you never compensate manually.
   `generate_bgm`, `replace_shot_dialogue`
 - **Finish**: `compose_episode`, `get_final_cut`, `get_export`,
   `generate_episode_poster`, `generate_cover`
+- **Assemble it yourself**: `export_handoff_pack`, `get_handoff_toolchain` —
+  download the per-shot raw clips, dialogue tracks, SFX, BGM and subtitles, then
+  decide transitions and assemble the cut on your own side. Use this instead of
+  `compose_episode` when you want to judge each seam yourself; use
+  `compose_episode` when you want the platform's finishing pipeline (pre-flight
+  checks, A/V duration parity, loudness mastering). Three facts that will bite you:
+  `audio_contract.mode="tts"` means the raw clips have **no voice** (dialogue ships
+  separately — skip it and the episode is silent); every shot must be cut to
+  `trim_head_ms`/`duration_ms` or you splice in frames the platform already QC'd out;
+  and all subtitle/dialogue/SFX offsets are relative to **each shot's own trimmed
+  start**, not to the final timeline — add whatever overlapping transitions you like
+  and let `compile_timeline.py` expand them, never hand-compute the shift.
 - **Edit**: `edit_video_shot`, `regenerate_shot_video`, `split_shot`,
   `trim_shot`, `rerender_episode`
 - **Read back (all free)**: `list_dramas`, `get_drama`, `get_characters`,