bytespost-canvas

Local CLI + MCP server for the bytespost canvas — drive a running canvas tab from your terminal or any AI agent (Claude Code, Cursor, etc.).

What it is

bytespost-canvas runs a tiny localhost daemon (HTTP + WebSocket hub) that bridges your terminal / AI agent and a canvas tab open in your browser. Once the daemon is up and the canvas tab is connected:

• The CLI sends commands (draw a rectangle, capture a screenshot, query the document, set selection, …).
• The daemon relays them over WebSocket to the canvas page.
• The page executes them in the live editor and streams back results (node IDs, PNG bytes, JSON document state).

It also exposes an MCP (Model Context Protocol) stdio server so AI agents that speak MCP can talk to your canvas with no glue code.

Install

# Global install — gives you the `canvas` binary
npm install -g bytespost-canvas

# Or run without installing
npx bytespost-canvas --help

Three binaries ship, all aliasing the same CLI: canvas, canvas-bridge, canvasd.

Quick start

# 1. Start the daemon (it stays in the foreground)
canvas serve

# 2. In your browser, open https://app.bytespost.com and edit any project.
#    The page auto-connects to the daemon on http://127.0.0.1:7777.

# 3. From any other terminal, run commands
canvas ls                              # list connected tabs
canvas screenshot -o canvas.png        # capture the active tab
canvas draw rect --x 100 --y 100 --width 200 --height 120 --fill "#7c3aed"
canvas document get                    # dump the IR JSON
canvas select set --node-id <id>       # set selection

canvas <command> --help prints command-specific flags. canvas --json returns stable machine-readable JSON for any command — pipe straight into jq.

MCP mode (for Claude Code / Cursor / any MCP client)

canvas mcp     # speaks MCP over stdio

Register it in your AI agent's MCP config. Sample for Claude Code:

// ~/.claude/config.json
{
  "mcpServers": {
    "canvas": {
      "command": "canvas",
      "args": ["mcp"]
    }
  }
}

The agent then sees tools for every canvas command (canvas_draw_rect, canvas_screenshot, canvas_document_get, …) and can compose them autonomously.

Commands

| Command | What it does | |---|---| | serve / start | Run the daemon (foreground). | | mcp | Run an MCP stdio server. | | status / health | Daemon + connected-tab health. | | ls | List open canvas tabs. | | tab info | Show tab metadata. | | document get | Dump the full document IR. | | document nodes | List node IDs by type / filter. | | draw | Create a node from a JSON spec. | | draw rect / frame / text / line | Convenience helpers for the common shapes. | | node get / update / delete | Read or mutate a single node. | | select set / clear | Drive the selection. | | viewport screenshot / screenshot | PNG bytes of the active tab. | | viewport fit / zoom | Pan/zoom the camera. | | building | Building-3D plugin shortcuts (wall / slab / window / door / …). |

Configuration

• Daemon port: CANVAS_BRIDGE_PORT (default 7777).
• All commands accept --tab <id> when multiple canvas tabs are connected; with exactly one, it's optional.

Architecture (one sentence)

your CLI ──HTTP──> daemon ──WebSocket──> canvas tab in browser
                       │
                       └── MCP stdio (for AI agents)

License

MIT