Scenaloom MCP 工具参考

这里列出了 Scenaloom MCP 服务器向已连接的 AI 应用提供的每一个工具，以及每个工具需要的权限。工具名称和 AI 应用读取的说明都是英文，但应用会用你的语言回答你。连接应用的方法见把 Scenaloom 接入 AI 应用。

工具

工具	权限	作用
list_projects	读取项目	列出作者的项目，最新的排在前面，可以按搜索词或类型（剧本、小说、视频）筛选。
get_project	读取项目	返回项目的标题、简介、类型、作者的角色、各集及其场次数，以及角色、地点和未解决评论的数量。
read_script	读取项目	以带类型的块（场景标题、动作、角色、对白、括号提示、转场、镜头）或 Fountain 格式读取一集剧本，可按范围或逐场读取，并返回修改所需的修订版本和哈希值。
list_scenes	读取项目	按顺序列出一集的场次：场景标题、地点、出场角色、块范围和摘要。
list_entities	读取项目	列出项目的角色、地点或道具，包括详细资料、出场次数和人物关系。
get_story_structure	读取项目	返回节拍、项目大纲和本集大纲。
read_novel	读取项目	返回小说的章节列表，或按每页最多 40,000 个字符分页读取一章的正文，并附上修改所需的修订版本。
search_project	读取项目	在项目的剧本、小说、角色和地点、评论和节拍中查找一句台词、一个名字或一段文字。
list_comments	读取项目	列出项目中未解决或已解决的评论，包括锚点位置、作者和写下评论的应用。
list_generations	读取项目	列出图片、视频和音频生成任务及其状态和积分。
get_generation	读取项目	返回单个生成任务的状态、进度、已使用或已退还的积分，以及生成结果。
propose_script_edits	编辑剧本和小说	为一集剧本准备最多六处修改（插入动作、改写一行、替换文字、全部替换、添加节拍），并返回修改前后的预览；在调用 apply_script_edits 之前不会改动任何内容。
apply_script_edits	编辑剧本和小说	应用作者已批准的提议，与实时编辑合并，记入版本历史，并且可以撤销。
undo_script_edits	编辑剧本和小说	撤销一批已应用的修改，除非之后的修改与它冲突。
propose_novel_edits	编辑剧本和小说	为一个章节准备查找替换修改或在末尾追加一段文字，并返回预览；每个查找内容都必须恰好出现一次。
apply_novel_edits	编辑剧本和小说	应用已批准的小说提议，并与同时在该章节写作的其他人合并。
undo_novel_edits	编辑剧本和小说	把已应用的小说修改从章节中撤回，之后新写的内容都保留；若有人改过被修改的文字，则不撤销。
update_entity	编辑剧本和小说	修改人物、地点或道具的详细信息。读取后若有人改过该条目，会被拒绝。作者可在一天内从 AI 面板撤销。
undo_entity_update	编辑剧本和小说	撤销 update_entity 做出的修改；若这些字段之后又被改过，则不撤销。
create_project	编辑剧本和小说	在作者方案的上限之内，新建一个剧本或小说项目。
create_episode	编辑剧本和小说	为剧集添加一集。
add_comment	评论	在剧本的某个块上留下评论，并标明由已连接的应用撰写；只有作者确认后才会通知协作者。
resolve_comment	评论	把评论标为已解决，或重新打开。
get_credits	使用积分	返回作者的积分余额和方案、此应用的消费设置和每日上限，以及它今天已经花掉的积分。
quote_generation	使用积分	为图片、视频或音频生成报价，不消耗任何积分；返回一个只能使用一次、5 分钟内有效的报价。
start_generation	使用积分	在作者确认费用之后，扣除报价中的积分并启动生成。
cancel_generation	使用积分	取消正在进行的生成，积分按积分政策退还。

读取类工具不会改动任何内容。编辑类工具只能通过你批准过的提议修改作品，每一批已应用的修改都可以撤销。唯一会消耗积分的工具是 start_generation，而且必须在你确认报价之后。

一次修改是怎么完成的

AI 应用用 read_script 读取这场戏，拿到每个块的 id 和剧本当前的修订版本。
它调用 propose_script_edits，一次最多提交六处修改。Scenaloom 检查后，为每一处返回修改前后的预览；提议会保留 30 分钟，也会显示在编辑器的 AI 面板里。
AI 应用把预览给你看。你同意后，它调用 apply_script_edits。如果这期间有人改过剧本，这次应用会被拒绝，AI 应用需要重新读取。
返回结果里有这批修改的 batch id。用这个 id 调用 undo_script_edits 就能撤回整批修改；无论撤不撤回，版本历史都会保留之前的草稿。

小说的流程相同，用的是 read_novel、propose_novel_edits 和 apply_novel_edits：每段要替换的文字在章节里必须只出现一次，所以修改永远不会落错位置。

生成费用怎么支付

quote_generation 只报价、不扣费，返回的报价 5 分钟内有效，而且只能用一次。
AI 应用告诉你费用和扣除后的余额，你同意后才调用 start_generation。支持确认步骤的应用会显示 Scenaloom 自己的确认窗口；其他应用只能在你设定的每日上限内消费。
get_generation 报告进度和结果。如果报价之后价格变了，Scenaloom 会拒绝启动；生成失败的，按积分政策退还积分。

资源与提示词

支持浏览资源的应用，可以把一个项目、某一集的 Fountain 文本、一个小说章节，或者项目的故事设定集（角色、地点、道具、人物关系、节拍和大纲）附加到对话中。提示词用来快速开始常见任务：剧本医生诊断、节拍结构意见、改写一场戏、围读笔记，以及写 Logline 和梗概。提示词的标题会跟随你的 Scenaloom 界面语言。

应用可能报告的错误

提示	处理方法
提议之后剧本已被修改（The script changed after the proposal）	重新读取这场戏，再提议一次。
权限不足（Insufficient scope）	应用缺少某项权限。先在“已连接的应用”里断开它，再重新连接并勾选该权限。
未找到（Not found）	项目已被删除，或者你已经没有访问权限。
此应用无法确认消费（This app can't confirm spending）	为这个应用设置每日积分上限，或者直接在 Scenaloom 里启动生成。
请求过于频繁（Rate limited）	等待提示的秒数，然后重试。