在 AI Agent 中使用金河分镜

金河分镜桌面端内置 MCP（Model Context Protocol）server。开启后，Claude、Cursor、Codex、Kiro、Kimi 等 AI agent 可直接连上你本机的分镜项目——读取项目结构、新建段落 / 场景 / 镜头、一键生成整片草稿、批量改镜头、导出成片文档。AI 的改动会实时反映在桌面端界面上。

接入无需 token：你的 agent 配置里只有一行启动命令，由随桌面端分发的桥接程序自动完成鉴权与连接。

三步开启

开启 server：桌面端打开 设置 → MCP 接入，打开「启用 MCP server」。
复制配置：在同一页面选择你的工具，点「复制配置」。配置里没有 token，只有一行启动桥接的命令。
粘进你的工具：见下方各工具的落点。粘好即可，使用期间保持金河分镜处于打开状态。

MCP server 随桌面端进程运行；桥接需要本机装有 Node。下面示例里的 <桥接脚本路径> 一律替换为设置页生成的实际路径（直接用「复制配置」最省事）。

各工具接入

Claude Code（CLI / VS Code / JetBrains）

三端共用同一引擎，在终端运行一行命令即可注册：

claude mcp add jinhe-storyboard -- node <桥接脚本路径>

Claude Desktop

复制进 claude_desktop_config.json，保存后完全退出并重开 Claude Desktop：

{
  "mcpServers": {
    "jinhe-storyboard": {
      "command": "node",
      "args": ["<桥接脚本路径>"]
    }
  }
}

Codex CLI

加进 ~/.codex/config.toml：

[mcp_servers.jinhe-storyboard]
command = "node"
args = ["<桥接脚本路径>"]

Cursor

复制进 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "jinhe-storyboard": {
      "command": "node",
      "args": ["<桥接脚本路径>"]
    }
  }
}

Kiro

复制进 .kiro/settings/mcp.json（项目级）或 ~/.kiro/settings/mcp.json（全局）：

{
  "mcpServers": {
    "jinhe-storyboard": {
      "command": "node",
      "args": ["<桥接脚本路径>"],
      "disabled": false
    }
  }
}

Kimi Code CLI

在终端运行一行命令注册：

kimi mcp add jinhe-storyboard -- node <桥接脚本路径>

通用（Cline / Roo Code / Windsurf / Trae 等）

凡支持 mcpServers 配置的工具都通用，粘进其 MCP 设置即可：

{
  "mcpServers": {
    "jinhe-storyboard": {
      "command": "node",
      "args": ["<桥接脚本路径>"]
    }
  }
}

AI 能做什么

接入后，AI agent 可调用以下工具编排你的分镜：

项目总览

list_projects — 列出本机所有分镜项目。
open_project — 打开某个项目并设为当前活动项目。
get_project_overview — 项目信息 + 段落 / 场景 / 镜头树 + 计划 / 通告 / 任务。
list_entity_tree / get_entity — 读取结构树与单个实体详情。

结构编排

create_entity / update_entity — 新建、改写段落 / 场景 / 镜头。
move_entity — 跨场移动镜头。
delete_entity — 删除实体（破坏性，AI 会先与你确认）。
batch_update_shots — 按条件批量改镜头（如把所有「特写」改成「中景」）。

AI 创作

create_project_with_draft — 一句 brief 直接建项目并生成整片草稿。
submit_ai_task / wait_task / cancel_task — 提交、等待、取消异步 AI 任务。
regenerate_shots — 按指令批量重生成多个镜头。

导出

export_project — 导出当前项目为 PDF / CSV / Markdown 到指定路径。

常见问题

连不上 / 工具列表为空？

确认金河分镜桌面端正在运行，且设置里「启用 MCP server」已打开。MCP server 随应用进程存在，应用关闭即断开。桥接还要求本机装有 Node。

为什么不用填 token？

桌面端开启 MCP 时会把连接凭据写到本机一个只有你能读的文件，桥接启动时自动读取并完成鉴权。凭据不出现在你的 agent 配置里，也不会随配置外泄。

桥接路径在哪里看？

在 设置 → MCP 接入 页，每个工具的配置片段里已经填好了实际路径，直接「复制配置」即可。