For CLI agents给命令行 Agent 用
Direct the scene
from your terminal
在终端里指挥 FlashStory
In one line: flashstory-mcp connects a command-line AI to the FlashStory editor running in your browser. It can read the scene, block movement, pose characters, look at screenshots, and export the guide video to disk — through the exact same validation and undo history as clicking in the UI.
一句话：flashstory-mcp 把命令行里的 AI 接到浏览器里正在运行的 FlashStory 编辑器上。它能读场景、排走位、调关节、自己截图看构图、把参考视频导出到磁盘——而且每一步都走编辑器同一套校验和撤销历史，跟你在界面里点出来的没有区别。
Tell Claude Code what the shot is, and it does the staging for you — in a real editor tab you can watch, take over, and undo. This is a session from our own testing, verbatim: 把这场戏说给 Claude Code 听，它替你排——就排在你眼前那个编辑器标签页里，随时可以接手、可以撤销。下面是我们自己测试时的真实片段：
▸ Add a red character called Lao Zhang, then walk him
from (0,0,2) to (0,0,-1) over 3 seconds.
add_entity laozhang · red ✓
set_transform_keys t=0 (0,0,2) → t=3 (0,0,-1) ✓
set_pose_keys walk-ready ↔ walk loop, idle at t=3 ✓
screenshot t=1.5 · he's at z≈0.5, on path ✓
▸ Export the video and tell me where the file is.
export_video 240 frames ✓
get_export_status state: done
get_export_result ~/.flashstory/exports/scene-20260725/
guide_video.mp4 · 5.9 MB
▸ 加一个叫「老张」的红色角色，然后让他从 (0,0,2)
走到 (0,0,-1)，用 3 秒。
add_entity laozhang · red ✓
set_transform_keys t=0 (0,0,2) → t=3 (0,0,-1) ✓
set_pose_keys walk-ready ↔ walk 循环，t=3 收 idle ✓
screenshot t=1.5 · 人在 z≈0.5，在路径上 ✓
▸ 导出这个场景的视频，告诉我文件在哪。
export_video 240 帧 ✓
get_export_status state: done
get_export_result ~/.flashstory/exports/未命名场景-20260725/
guide_video.mp4 · 5.9 MB
Install安装
Two commands on the terminal side, one switch on the editor side. 终端侧两条命令，编辑器侧一个开关。
npm install -g flashstory-mcp
claude mcp add flashstory -- npx -y flashstory-mcpThen, in the FlashStory editor: Settings → CLI / MCP bridge → Allow CLI control. It is off by default — nothing can touch your scene until you turn it on. The bridge daemon starts by itself on the first tool call; requirements are Node ≥ 20 and an open editor tab (keep it visible while exporting or taking screenshots — browsers throttle WebGL in background tabs). 然后在 FlashStory 编辑器里打开：设置 → CLI / MCP 桥接 → 允许 CLI 控制。这个开关默认关闭——不打开，任何工具都碰不到你的场景。桥接守护进程会在第一次工具调用时自动启动；要求 Node ≥ 20，且编辑器标签页开着（导出和截图时别把它切到后台，浏览器会限流后台标签页的 WebGL）。
How it fits together它是怎么接起来的
Claude Code ──stdio──▸ flashstory-mcp ──ws──▸ flashstory-bridge ◂──ws── editor tab
(per session) (one daemon, port 18787)
The editor tab dials out to a local daemon, because an extension page cannot listen on a port. The daemon is separate from the MCP process so CLI sessions can come and go without the editor's connection flapping — and so two terminals can work on the same scene at once. It checks the connecting page's origin, accepts only local connections, and exits on its own after ten idle minutes. flashstory-bridge status / logs / set-port control it when you need to.
编辑器标签页主动拨出去连一个本地守护进程——扩展页面自己没法监听端口。守护进程和 MCP 进程分开，是为了让 CLI 会话随开随关而编辑器的连接不抖，也让两个终端可以同时操作一个场景。它校验来源 Origin、只接受本机连接，闲置十分钟自动退出。需要时用 flashstory-bridge status / logs / set-port 管它。
The tools工具一览
| Tool工具 | What it does用途 |
|---|---|
get_scene |
The whole scene as JSON, with the rev you pass back for optimistic concurrency整个场景的 JSON，含 rev，写入时可回传做乐观并发检查 |
add_entity · update_entity · remove_entity · place_entity |
Characters, primitives, image boards, models — and where they stand角色、图元、图片板、模型，以及它们站在哪 |
set_transform_keys · upsert_transform_key |
Position and orientation over time位移与朝向的关键帧 |
set_pose_keys · list_poses · define_pose · delete_pose |
The pose library: 20 built-ins plus your own姿势库：20 个内置加自定义 |
get_character_joints · set_character_joints · adjust_character_joints |
Joint angles in degrees at a given time, clamped to joint limits按时间点读写关节角（度），自动钳制在关节限位内 |
set_camera_keys · add_camera · set_camera_switches |
Camera work, including multi-camera cuts运镜，含多机位切换 |
add_dialogue_track · add_dialogue_cue · add_marker |
Dialogue lanes and timeline markers台词轴与时间轴标记 |
screenshot · pose_screenshot |
Let the agent look at the scene, with grid / label / path overlays让 Agent 亲眼看场景，可叠加网格 / 标签 / 路径 |
export_video · get_export_status · get_export_result |
Render the guide video and write the export bundle to disk渲染参考视频，把导出包写到磁盘 |
undo · redo · begin_batch · commit_batch |
History; a batch groups several calls into one undo entry历史操作；批次把多个调用合成一条撤销记录 |
list_editors · select_editor |
Pick which editor tab to act on when several are open开了多个编辑器时，选择要操作哪一个 |
Guardrails边界与保障
- Same rules as the UI. Every edit goes through the editor's own reducer — the six-colour cap, joint limits and keyframe ranges all apply, and a rejected edit comes back with the reason instead of silently corrupting the scene. 和界面同一套规则。所有编辑都过编辑器自己的 reducer——六色上限、关节限位、关键帧范围照常生效，被拒的编辑会带着原因返回，而不是悄悄写坏场景。
-
Undoable, always. Agent edits land in the same history as yours; Ctrl+Z takes them back. A
begin_batch…commit_batchpair collapses a whole task into one undo step. 永远可撤销。Agent 的编辑和你的落在同一条历史上，Ctrl+Z 就能收回；begin_batch…commit_batch能把一整个任务合成一步撤销。 -
Local only, off by default. Everything runs on 127.0.0.1 with an origin check; the bridge switch in the editor ships off. Files are only ever written under
~/.flashstory/exports/, with names the editor generates — a tool call cannot pick an arbitrary path on your disk. 只在本机，默认关闭。所有流量走 127.0.0.1 并校验来源；编辑器里的桥接开关出厂即关。落盘只发生在~/.flashstory/exports/之下、文件名由编辑器生成——工具调用无法指定你磁盘上的任意路径。