infinite-canvas/canvas-agent

Infinite Canvas Agent

本地 Canvas Agent 用来连接线上画布网页和用户电脑上的 Codex / Claude Code。

启动

npx -y @basketikun/canvas-agent

本仓库开发时也可以直接运行：

cd canvas-agent
npm install
npm run build
node dist/index.js

启动后会输出本机地址和 token：

Local URL: http://127.0.0.1:17371
Connect token: xxxxxx

在画布右上角点击 Agent，填入地址和 token 后连接。

Canvas Agent 默认只监听 127.0.0.1。网页第一次带正确 token 连接后，Canvas Agent 会记录该网页 Origin；之后其他 Origin 不能复用这个本地 Agent，除非用户清理 ~/.infinite-canvas/canvas-agent.json 里的 origins。

发布

canvas-agent 使用自己的 package.json 版本号，不跟仓库根目录 VERSION 绑定。推送到 main 后，GitHub Actions 会检查 npm 上是否已经存在当前包版本；不存在时才发布 @basketikun/canvas-agent。

发布前需要在 GitHub 仓库 Secrets 中配置 NPM_TOKEN。

Codex MCP

如果希望 Codex 终端能直接操作画布，需要先把 Canvas Agent 注册成 Codex MCP。

Canvas Agent 启动后，给 Codex 添加 MCP：

codex mcp add infinite-canvas -- npx -y @basketikun/canvas-agent mcp

本仓库开发时可以改成，实际使用建议替换为本机绝对路径：

codex mcp add infinite-canvas -- node /path/to/infinite-canvas/canvas-agent/dist/index.js mcp

Canvas Agent 源码使用 TypeScript 编写，MCP 协议层使用官方 @modelcontextprotocol/sdk，工具入参使用 zod 描述。

如果希望终端里的 Codex 不被 MCP 审批卡住，可以在 ~/.codex/config.toml 里给这个 MCP 设置自动放行：

[mcp_servers.infinite-canvas]
command = "npx"
args = ["-y", "@basketikun/canvas-agent", "mcp"]
default_tools_approval_mode = "approve"

可用工具：

• canvas_get_state
• canvas_get_selection
• canvas_export_snapshot
• canvas_apply_ops
• canvas_create_text_node
• canvas_create_image_prompt_flow

canvas_apply_ops 示例：

{
  "ops": [
    {
      "type": "add_node",
      "nodeType": "text",
      "title": "标题",
      "position": { "x": 0, "y": 0 },
      "metadata": { "content": "文本内容" }
    }
  ]
}

侧边栏 Codex

本地面板会把提示词发送给 Canvas Agent。Canvas Agent 使用官方 @openai/codex CLI 的 codex app-server --stdio 启动并复用同一个 Codex thread，启动时会注入 infinite-canvas MCP 配置并自动放行 MCP 审批，真正执行画布修改前仍由网页侧边栏二次确认。

侧边栏会展示 Codex 返回的 thread.started、turn.started、item.*、turn.completed 等结构化事件；收到 app-server 的 item/agentMessage/delta 时，Canvas Agent 会转成 item.updated，网页会用同一条消息做真实流式更新，并把工具细节收进运行日志。

侧边栏上传或粘贴的图片会先发到本机 Canvas Agent，再由 Canvas Agent 临时写入本机文件并作为 app-server localImage 输入传给 Codex；前端会提示附件体积，单次请求体限制为 30MB。

Claude Code

Claude Code Adapter 代码暂时保留，但当前网页侧边栏只开放 Codex。后续开放 Claude 入口时，Canvas Agent 会调用本机 claude -p --output-format stream-json 并把流式 JSON 事件转发到侧边栏。

如果希望 Claude Code 也能操作画布，需要给 Claude Code 添加同一个 MCP。建议用 user scope，避免 Canvas Agent 从不同目录启动时找不到配置：

claude mcp add --scope user --transport stdio infinite-canvas -- npx -y @basketikun/canvas-agent mcp

本仓库开发时可以改成：

claude mcp add --scope user --transport stdio infinite-canvas -- node /path/to/infinite-canvas/canvas-agent/dist/index.js mcp

Canvas Agent 调用 Claude Code 时会默认带上 --allowedTools mcp__infinite-canvas__*，画布写操作仍由网页侧边栏确认。