Playlet Canvas MCP

Playlet 无限画布的自研 MCP 服务。它只依赖官方 @modelcontextprotocol/sdk，支持 stdio 与 Streamable HTTP，并通过回环地址上的 WebSocket 与当前 Portal 画布通信。 任何写工具都只提交待确认计划，不能绕过项目权限、动作白名单和人工确认。

环境要求

• Node.js 18 或更高版本
• Portal 页面运行在允许的 Origin，默认是 http://127.0.0.1:3000 或 http://localhost:3000
• 同一时间只连接一个画布页面

安装与构建

从 npm 全局安装：

npm install --global @hlz-play/canvas-mcp

也可以直接交给 MCP 客户端通过 npx 按需启动：

npx --yes @hlz-play/canvas-mcp

仓库开发与本地构建：

cd E:\BusinessCode\20260226\code-1\playlet-portal\packages\playlet-canvas-mcp
pnpm install
pnpm run build

生成一个固定配对令牌，并同时填写到 MCP 客户端配置与 Portal 配对弹窗：

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"

令牌必须是 32–128 位 base64url 字符。不要把真实令牌提交到仓库。

stdio（推荐给 Codex / Claude Desktop）

全局安装后的客户端启动命令：

playlet-canvas-mcp

未全局安装时，也可以使用仓库构建产物：

node E:/BusinessCode/20260226/code-1/playlet-portal/packages/playlet-canvas-mcp/dist/cli.js

环境变量至少配置：

PLAYLET_CANVAS_MCP_TOKEN=<刚生成的令牌>
PLAYLET_CANVAS_ALLOWED_ORIGINS=http://127.0.0.1:3000,http://localhost:3000

Codex 的 config.toml 示例见 codex-config.toml，Claude Desktop 示例见 claude-desktop-config.json。示例中的 路径和令牌必须替换为本机真实值。

Streamable HTTP

$env:PLAYLET_CANVAS_MCP_TOKEN='<刚生成的令牌>'
node dist/cli.js --transport=http

• MCP URL：http://127.0.0.1:32190/mcp
• 请求头：Authorization: Bearer <配对令牌>
• 健康检查：http://127.0.0.1:32190/health

HTTP 与浏览器桥接共用端口，但都只监听 127.0.0.1。

Portal 配对

1. 打开某个项目的无限画布。
2. 展开右侧 Agent，点击“本机 Canvas MCP”。
3. 地址保持 ws://127.0.0.1:32190/bridge。
4. 粘贴与客户端环境变量相同的令牌并连接。
5. 状态变为“已连接”后即可调用读取工具；写工具会在 Agent 面板生成待确认计划。

配对令牌只保存在 sessionStorage，关闭标签页后自动清除。项目切换会断开旧握手并 以新项目重新连接。

工具

| 工具 | 类型 | 说明 | | --- | --- | --- | | canvas_get_current | 只读 | 当前画布安全摘要 | | canvas_get_selection | 只读 | 选中节点、必要上游和相关连线 | | canvas_get_viewport | 只读 | 缩放、世界中心和可见范围 | | canvas_export_safe_snapshot | 只读 | 可供 Agent 分析的安全快照 | | canvas_apply_actions | 待确认写入 | 提交最多 30 个白名单动作 | | canvas_create_text_node | 待确认写入 | 创建文本节点计划 | | canvas_create_generation_flow | 待确认写入 | 创建提示词、配置、输出和连线 | | canvas_trigger_generation | 待确认写入 | 将节点加入生成队列 |

所有写工具都要求 requestKey。相同请求键只会登记一次，避免客户端自动重试造成 重复节点或重复生成。

安全边界

• 服务固定监听 127.0.0.1，不提供绑定公网地址的配置。
• WebSocket 校验本地 Host、Origin 白名单、高熵令牌和协议版本。
• 单浏览器连接、1 MB 消息上限、16 个并发请求、15 秒请求超时、8 小时会话过期。
• 安全快照移除 Cookie、令牌、媒体 URL、缩略图 URL、本地绝对路径和内部任务字段。
• Portal 再次校验工具、节点类型、坐标、尺寸、动作数量和幂等键。
• 删除和生成动作仍必须由用户在 Portal 中确认。

常见问题

• 画布尚未连接本机 MCP 桥接：确认 MCP 进程已启动，并在 Agent 面板完成配对。
• Unauthorized：客户端与 Portal 使用的令牌不一致。
• Forbidden：当前 Portal Origin 不在 PLAYLET_CANVAS_ALLOWED_ORIGINS。
• EADDRINUSE：32190 端口已被其他进程使用；停止旧进程，或为服务和 Portal 同时 改用 PLAYLET_CANVAS_MCP_PORT 对应的新地址。