基础概念
什么是 MCP？
Model Context Protocol · 让 LLM 工具调用的标准协议
Server
我们的小马画布 MCP Server 暴露了 5 个工具（创建节点、连线、导出等），运行在 127.0.0.1:17371。
Client
Codex / Claude Code 作为 MCP Client，通过 stdio 或 HTTP 与 Server 通信，把你的自然语言翻译成工具调用。
效果
你说"反推 50 张图"，Codex 自动循环调用 50 次 canvas_create_image_node，你只需坐着等结果。
为什么选择 MCP 而不是 Function Call？
- ✓ 通用协议：Claude / Codex / Gemini CLI 都支持，一次接入多端通用
- ✓ 本地优先：stdio 模式零延迟，状态在你机器上
- ✓ 可观测：所有调用都进 mcp.log，调试方便
- ✓ 可中断：Ctrl-C 即停，状态回滚有 history 栈
- ✓ MIT 协议：不基于任何 AGPL 项目，商业可用
工具列表
5 个原子工具
组合使用可以完成 90% 的画布操作
canvas_get_state获取画布当前状态（节点 + 连线 + 选中节点）
无:void— 返回完整 state 快照canvas_apply_ops原子化应用操作：add/remove/update 节点与连线
ops:Op[]— 操作队列：add_node / remove_node / add_edge / update_nodecanvas_create_prompt_node创建提示词节点（自动定位 / 智能连线）
text:string— 提示词内容x?:number— 可选 X 坐标y?:number— 可选 Y 坐标canvas_create_image_node创建图片生成节点（自动触发 / 加入队列）
promptNodeId:string— 上游提示词节点 IDmodel?:string— 模型选择：sora / midjourney / flux 等canvas_export_snapshot导出画布快照（PNG / JSON / 压缩包）
format:'png' | 'json'— 导出格式Quick Start
5 分钟接入
三种客户端：Codex CLI / Claude Code / 任意 HTTP 客户端
方式一：Codex CLI（推荐）
bash
# 1. 安装 MCP server（小马画布）
codex mcp add xiaoma-canvas -- npx -y @xiaoma-ai/canvas-mcp mcp
# 2. 启动画布（确保 127.0.0.1:17371 可达）
cd mcp-server && node index.js
# 3. 在 Codex 中直接说人话
codex "在画布上创建一个反推节点，提示词是'海边日落'"
# 4. 或显式调用
codex /tool xiaoma-canvas:canvas_create_prompt_node --text "海边日落" --x 400 --y 300方式二：Claude Code
bash
claude mcp add --scope user --transport stdio xiaoma-canvas \
-- npx -y @xiaoma-ai/canvas-mcp mcp
# 然后在 Claude Code 里直接说
> "把当前画布所有节点导出成 JSON，路径 ./backup-{date}.json"方式三：HTTP 直调
bash
# 画布 MCP 同时提供 HTTP 接口（前端或脚本直接调）
curl -X POST http://127.0.0.1:17371/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "canvas_create_prompt_node",
"arguments": { "text": "海边日落", "x": 400, "y": 300 }
}
}'实战模板
3 个生产级工作流
复制提示词 → 粘贴到 Codex → 见证自动化
批量反推 + 生图流水线
上传 50 张产品图 → 反推提示词 → 套用模板批量生图
1.遍历输入目录，调用 canvas_create_image_node 创建反推节点
2.监听每个反推节点完成事件，调用 canvas_create_prompt_node 写回提示词
3.自动连线 prompt → generate 节点，触发批量生图
4.导出快照到 ./output/{date}/
提示词（直接发给 Codex）：
natural language
请在画布上创建 5 个图片反推任务，分别对应 ./input/ 下的 1.png ~ 5.png，
每个反推节点完成后再创建对应的提示词节点，提示词模板：
"专业产品摄影，{subject}，{background}，{lighting}，白底"
最后把每个反推节点和它对应的提示词节点用线连起来。提示词 → 视频 → 详情页
一条自然语言 → 多镜视频 → 落地页三件套
1.用户输入：「为夏季新品『海风椰子水』生成 3 段短视频 + 详情页」
2.Codex 解析意图，调用 canvas_apply_ops 创建 1 个 prompt 节点 + 3 个 image 节点
3.每个 image 节点配置 Sora 2 + 不同镜头（推/拉/摇）
4.完成后创建 1 个 detailPage 节点汇总视频 + 文案
提示词（直接发给 Codex）：
natural language
为新品"海风椰子水"在画布上创建：
- 1 个中央提示词节点，写入核心 brief
- 3 个 Sora 2 视频节点，分别用推/拉/摇镜头
- 1 个详情页节点，把 3 段视频拼成主图 + 文案
每个视频节点从中央提示词节点连线过来。A/B 变体批量生成
一个母版 → 100 个变体 → 自动化筛选
1.从母版提示词复制 100 份，注入随机变量（背景/光/角度/风格）
2.并行触发 100 个 generate 节点（每帧 10 个，避免压力）
3.采集所有变体的 result_url，写入 ./variants.csv
4.Codex 自动按 prompt 相似度聚类，输出 Top-10 供人工挑选
提示词（直接发给 Codex）：
natural language
基于画布上名为"主图模板"的提示词节点，
复制 100 份并随机替换：
- 背景（白/灰/木/大理石/户外）
- 光线（柔光/硬光/逆光/自然光）
- 角度（俯拍/平拍/45度）
- 风格（极简/国潮/赛博/复古）
每份独立连到一个 generate 节点，模型选 Flux。提示词库
可复用提示词模板
拷走就用，越用越顺手
反推节点 → 提示词节点
场景：上传一张参考图想要扩写为多张变体
natural language
读取画布中所有 image 节点（type=text），
为每个反推节点创建一个 prompt 节点，
提示词 = "{反推结果}，{用户给的风格修饰}，{用户给的画幅参数}"，
两个节点用 line 连起来。批量压缩画布
场景：画布塞满，需要归档
natural language
调用 canvas_export_snapshot 导出当前画布：
- format: json
- 同时调用 canvas_apply_ops 清空所有节点和边
- 但保留节点标题和最后更新时间到 archive.jsonCodex 内部 + 画布联动
场景：在 Codex 会话中操作画布
natural language
我现在要在画布上做一个分层渲染流程：
1. 创建 1 个 detail 节点写"椰子水详情页"
2. 创建 1 个 sketch 节点，连接到 detail
3. 在 sketch 节点上创建 4 个子节点：背景层、产品层、文字层、Logo 层
4. 每个子节点都连回 detail
每一步用 canvas_apply_ops 提交，不要直接改 state。一键快照发周报
场景：每周五自动把本周创作画布打包
natural language
执行画布快照：
1. canvas_get_state 检查节点总数
2. canvas_export_snapshot 输出 PNG + JSON 到 ./weekly/{日期}/
3. 把 PNG 上传到 imgur 或 COS，返回 URL
4. 把 URL 发到飞书 #ai-创作 周报频道架构
数据流
从自然语言到画布像素，完整链路
自然语言
「反推 50 张图」
Codex / Claude
解析意图
MCP Server
5 个原子工具
画布状态
in-memory + JSON
渲染输出
PNG / 视频 / HTML
Roadmap
路线图
v0.1（已上线）
5 个原子工具 + HTTP / stdio
基础 CRUD + 创建提示词/图片节点 + 导出快照
v0.2（计划中）
流式事件 + 进度回调
支持 SSE，Codex 可以实时显示每个节点的生成进度
v0.3（构想中）
多画布协同 + 权限
团队共享画布，Codex 按角色操作不同工作区