内容
# 主画布MCP服务器
**[主画布](https://github.com/wassermanproductions/master-canvas)** 的无头MCP（模型上下文协议）服务器，用于本地优先的AI视频规划、提示、资产和交接包预生产画布。通过连接此服务器，AI代理可以直接在磁盘上的项目JSON数据上读取和编辑主画布项目，并构建生成器就绪的交接包 **无需打开桌面应用程序**。
代理可以创建画布、添加场景/镜头/参考卡、编写提示和负面提示、设置相机和灯光备注、附加源图像和参考链接、排序镜头，并为ComfyUI/LTX、Kling、Veo或下游代理导出完整的交接包。
零依赖。节点≥18。单个文件。
## 它所操作的内容
主画布将每个画布存储为一个项目JSON文件（与应用程序导出为 **`master-canvas-project.json`** 的形状相同）： `{ title, continuity, assets[], nodes[] }`。一个 **卡片** 是一个节点；一个 **画布** 是一个项目文件。此服务器直接读取和写入该文件。
项目文件按以下顺序解析：
1. 工具调用时给定的 `projectPath` 参数（如果给出）；
2. `MASTER_CANVAS_PROJECT` 环境变量；
3. 默认应用程序数据位置 — `~/Library/Application Support/master-canvas/master-canvas-project.json` 在macOS上（`%APPDATA%\master-canvas\…` 在Windows上， `$XDG_CONFIG_HOME/master-canvas/…` 在Linux上）。
使用 `attach_asset` 附加的源文件会复制到项目旁边的一个 `<project>-assets/` 文件夹中，因此项目保持自包含和可移植。
## 要求
- **节点≥18.** 无构建步骤，无 `npm install` — 服务器仅使用节点内置模块。
- 主画布项目JSON文件（使用 `create_project` 创建一个，或指向从应用程序导出的 `master-canvas-project.json`）。
## 连接
### Hermes
将以下内容添加到 `~/.hermes/config.yaml`：
```yaml
mcp_servers:
master-canvas:
command: "node"
args: ["/absolute/path/to/master-canvas-mcp/master-canvas-mcp.mjs"]
env:
MASTER_CANVAS_PROJECT: "/absolute/path/to/your/master-canvas-project.json"
```
### Claude 代码
```bash
claude mcp add master-canvas \
--env MASTER_CANVAS_PROJECT=/absolute/path/to/your/master-canvas-project.json \
-- node /absolute/path/to/master-canvas-mcp/master-canvas-mcp.mjs
```
### Codex
将以下内容添加到您的Codex MCP配置（`~/.codex/config.toml`）：
```toml
[mcp_servers.master-canvas]
command = "node"
args = ["/absolute/path/to/master-canvas-mcp/master-canvas-mcp.mjs"]
env = { MASTER_CANVAS_PROJECT = "/absolute/path/to/your/master-canvas-project.json" }
```
### 任意MCP客户端（通用stdio配置）
```json
{
"mcpServers": {
"master-canvas": {
"command": "node",
"args": ["/absolute/path/to/master-canvas-mcp/master-canvas-mcp.mjs"],
"env": { "MASTER_CANVAS_PROJECT": "/absolute/path/to/your/master-canvas-project.json" }
}
}
}
```
## 工具（14）
首先调用 **`get_project`** — 其响应解释了数据约定（场景绑定、镜头顺序、卡片类型）。
| 工具 | 功能 |
| --- | --- |
| `get_project` | 读取项目并总结标题、连续性、卡片类型、场景键、镜头顺序和资产。从这里开始。 |
| `create_project` | 创建一个新的空项目JSON。 |
| `list_cards` | 列出卡片（节点），包含类型、标题、场景键、顺序标签和位置。 |
| `get_card` | 一个卡片的完整记录。 |
| `add_card` | 添加卡片：`media`（要生成的镜头）、`scene`/`section`/`shot`（场景头部）、`workflow`/`imageWorkflow`（生成步骤）、`styleRef`/`musicRef`（参考）、`placeholder`、`note`。 |
| `update_card` | 修改卡片字段（提示、负面提示、相机、灯光、提供者等）。 |
| `move_card` | 重新定位卡片。画布顺序驱动场景分组和镜头顺序。 |
| `delete_card` | 删除卡片。 |
| `set_shot_order` | 从有序的卡片ID列表中设置明确的镜头顺序。 |
| `attach_asset` | 注册文件（复制到项目中）或链接，并可选地将其链接到卡片槽。 |
| `set_continuity` | 更新连续性圣经（角色、服装、地点、道具、风格规则、永不改变）。 |
| `build_handoff_package` | 组装生成器就绪的包：`project_manifest.json`、复制的`assets/`、ComfyUI/LTX镜头清单和每镜头作业、Hermes作业、`timeline/`镜头顺序 + 场景箱、`deliverables/bin_plan.json` 和可读的`shot-package.md`。 |
| `inspect_package` | 总结现有的交接包（场景、镜头、资产、准备情况）。 |
| `comfy_plan` | 从包或清单中发出镜头-by-镜头ComfyUI/LTX执行计划。 |
`build_handoff_package`、`inspect_package` 和 `comfy_plan` 生成和读取相同的 `project_manifest.json` 合同（`schema: master-canvas-handoff-v1`），主画布应用程序的Hermes插件使用它，因此这里构建的包可以直接与现有的Hermes/ComfyUI工具链兼容。
一个典型的代理会话：`get_project` → `set_continuity` → `add_card`（场景）→ `add_card`（媒体镜头）→ `update_card`（提示/相机）→ `attach_asset`（源图像）→ `set_shot_order` → `build_handoff_package` → 将文件夹交给ComfyUI/LTX或Kling/Veo工作流。
## 安全
此服务器仅触及本地文件系统：它读取和写入主画布项目JSON，并复制您指向的资产文件到项目文件夹中。它不打开网络连接，也不向机器外部公开任何内容。请仅指向您信任的项目路径。
## 许可证和致谢
MIT — 请参见 [LICENSE](LICENSE)。根据 [NOTICE](NOTICE) 文件，请在使用、分支和重新分发时提及 **Sam Wasserman ([wassermanproductions.com](https://wassermanproductions.com))**。
