For CLI agents给命令行 Agent 用

Direct the scene
from your terminal 在终端里指挥 FlashStory

FLASHSTORY-MCP · WORKS WITH CLAUDE CODE AND ANY MCP CLIENT · EXTENSION ≥ 0.9.0 FLASHSTORY-MCP · 适配 CLAUDE CODE 及任意 MCP 客户端 · 需扩展 ≥ 0.9.0

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 听，它替你排——就排在你眼前那个编辑器标签页里，随时可以接手、可以撤销。下面是我们自己测试时的真实片段：

claude — a real session claude — 实测片段

▸ 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安装

One command on the terminal side, one switch on the editor side. 终端侧一条命令，编辑器侧一个开关。

terminal 终端

  claude mcp add -s user flashstory -- npx -y flashstory-mcp

-s user is the part people miss. Without it claude mcp add defaults to local scope, which files the server under whichever directory you happened to be standing in. Start Claude Code from anywhere else and FlashStory is simply not there — which reads exactly like the install did not stick. -s user registers it once for every project on the machine. (Disabling a server in /mcp does not delete it either; it just adds the name to a disabled list, so re-enabling it needs no reinstall.) -s user 是最容易漏的一截。不加的话 claude mcp add 默认是 local 作用域，只把服务器记在你当时所在的那个目录下。换个目录启动 Claude Code，FlashStory 就凭空消失了——看起来就像根本没装上。-s user 一次注册，本机所有项目都能用。（另外，在 /mcp 里禁用某个服务器并不会删掉它，只是把名字加进禁用列表，重新启用不需要再装一遍。）

Nothing else is needed to get going: the MCP process spawns the bridge from its own package directory on the first tool call, using the same Node it is running under. You will want the bridge command on your PATH before long, though — see the bridge. 开跑不需要别的了：MCP 进程会在第一次工具调用时，用它自己那个 Node、从自己的包目录里把 bridge 拉起来。不过你迟早会想把 bridge 命令放进 PATH——见下面这节。

Then, 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它是怎么接起来的

all on 127.0.0.1 — nothing leaves your machine 全部走 127.0.0.1 — 不出你的机器

  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. 编辑器标签页主动拨出去连一个本地守护进程——扩展页面自己没法监听端口。守护进程和 MCP 进程分开，是为了让 CLI 会话随开随关而编辑器的连接不抖，也让两个终端可以同时操作一个场景。它校验来源 Origin、只接受本机连接，闲置十分钟自动退出。

Keeping the bridge around让 bridge 一直在

The bridge exits after ten idle minutes — that is deliberate, so a machine you have stopped working on is not left holding a port. Come back the next day and it is gone. The next tool call spawns it again, and the editor tab redials on its own, but that redial backs off to once every 30 seconds, so the first call after a long gap can still land before the tab is back and fail with no editor connected. bridge 闲置十分钟就会自己退出——这是故意的，免得你早就不干活了还占着端口。第二天回来，它已经没了。下一次工具调用会把它重新拉起来，编辑器标签页也会自己重连，但重连是退避的、最慢 30 秒一次，所以隔了很久之后的第一次调用仍可能赶在标签页回来之前，报「没有编辑器连接」。

So install the package globally and start the bridge yourself when you sit down. start is idempotent — running it when the bridge is already up does nothing. 所以把包装到全局，坐下来先自己把 bridge 起上。start 是幂等的，已经在跑就什么都不做。

terminal 终端

  npm install -g flashstory-mcp
  flashstory-bridge start

The global install is what puts flashstory-bridge on your PATH, and there is no npx shortcut worth typing: the command is flashstory-bridge while the package is flashstory-mcp, so a bare npx flashstory-bridge hunts for a package by that name and finds nothing. Without the global install you are stuck writing npx -y -p flashstory-mcp flashstory-bridge start every time. 全局安装的作用就是把 flashstory-bridge 放进 PATH，而 npx 这边没有值得敲的简写：命令叫 flashstory-bridge，包叫 flashstory-mcp，直接 npx flashstory-bridge 会去找一个同名的包然后找不到。不装全局，就得每次都写 npx -y -p flashstory-mcp flashstory-bridge start。

The same command covers the rest of it — status, stop, set-port, logs, prune-exports. When a tool call reports no editor, flashstory-bridge status is the first thing to run: it tells you whether the bridge is up and how many editor tabs are attached. 其余子命令也是同一个命令——status、stop、set-port、logs、prune-exports。工具调用报「没有编辑器」时，第一件事就是跑 flashstory-bridge status：它会告诉你 bridge 在不在、挂了几个编辑器标签页。

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_batch pair 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/ 之下、文件名由编辑器生成——工具调用无法指定你磁盘上的任意路径。