Canvas-MCP

An MCP server that renders hierarchical canvas diagrams as PNGs. Define your system as a hierarchy of networks, factories, machines, and nodes — Canvas-MCP handles layout, styling, and rendering.

Built with Python, Pillow, and the Model Context Protocol.

The Ontology

Canvas-MCP uses a four-level hierarchical ontology. Every diagram is a tree of nested containers, from the broadest scope down to the atomic unit:

Canvas
└── Network       ← system boundary
    └── Factory   ← functional domain
        └── Machine   ← pipeline
            └── Node      ← atomic operation

Why This Hierarchy?

Most diagramming tools give you boxes and arrows. Canvas-MCP gives you semantic containers — each level carries meaning about the scope and role of what it contains:

• Network — the broadest boundary. Think of it as a service, a deployment, or an entire subsystem. A complex architecture might have multiple networks.
• Factory — a functional domain within a network. "Data Ingestion", "Analysis", "Output Generation" — a factory groups the pipelines that serve a common purpose.
• Machine — a single pipeline or processing chain. A connected sequence of operations that transforms data from input to output.
• Node — the atomic unit. A single operation: an API call, a transformation, a decision gate, an AI inference step.

This isn't arbitrary nesting — it mirrors how real systems are organized. The hierarchy lets you express both the micro (individual operations) and the macro (system architecture) in one diagram.

Labeling

Every level of the ontology follows the same labeling pattern:

The rule is simple: `get_label()` returns the `label` if set, otherwise falls back to the `id`.

This keeps YAML recipes concise. You only need a label when you want a display name that differs from the id:

# No label needed — "preprocess" is clear enough
- id: preprocess
  type: process
  content: "Clean and normalize data"

# Label overrides the id for display
- id: llm-gpt4o-analysis
  type: ai
  label: "AI Analysis"
  content: "Run GPT-4o on cleaned data"

The same applies to containers:

machines:
  - id: machine-1        # Renders as "machine-1" (fine for auto-generated)
    nodes: [...]

  - id: src-pipeline      # Renders as "Data Sources"
    label: "Data Sources"
    nodes: [...]

Node Types

Nodes are the atomic units of the ontology. Each node has a type that determines its color and carries semantic meaning:

Node Anatomy

When rendered, each node displays:

1. Type bar — a colored stripe at the top matching the type's accent color
2. Label — bold text below the type bar (from get_label())
3. Content — word-wrapped body text describing what the node does
4. Type badge — small tag in the bottom-right corner showing the type name

Node Properties

- id: analyze              # Required. Globally unique identifier.
  type: ai                 # Optional. One of the 8 types above. Default: "default"
  label: "AI Analysis"     # Optional. Display name. Default: uses id
  content: "Run inference" # Optional. Body text describing the operation
  x: 800                   # Optional. Horizontal position. Default: 0 (auto-layout)
  y: 180                   # Optional. Vertical position. Default: 0 (auto-layout)
  width: 250               # Optional. Node width in pixels. Default: 250
  height: 120              # Optional. Node height in pixels. Default: 120
  inputs: [preprocess]     # Optional. IDs of upstream nodes
  outputs: [report]        # Optional. IDs of downstream nodes
  style:                   # Optional. Override default NodeStyle
    border_color: "#FF00FF"
    fill_color: "#1e1e2e"
    text_color: "#cdd6f4"
    label_color: "#FF00FF"
    corner_radius: 12

Container Styling

Machines and factories can be styled with ContainerStyle to customize their visual container:

machines:
  - id: my-pipeline
    label: "Custom Pipeline"
    style:
      border_color: "#89b4fa"    # Outline color
      fill_color: "#1e1e2e"      # Background fill
      label_color: "#89b4fa"     # Label text color
      alpha: 100                 # Fill opacity (0-255)
      corner_radius: 12          # Border radius
      border_width: 2            # Outline thickness

All ContainerStyle fields are optional — unset fields fall back to defaults:

Connections

Connections are declared on nodes via inputs and outputs — lists of other node IDs:

- id: source
  type: input
  outputs: [transform]     # "I feed into transform"

- id: transform
  type: process
  inputs: [source]         # "I receive from source"
  outputs: [result]

Connections are bidirectionally deduped — declaring a connection on either end is sufficient. Declaring both is harmless (and often clearer).

Smart Port Selection

Canvas-MCP automatically selects connection ports based on the spatial relationship between nodes:

• Horizontal flow (default): Connections exit from the right edge and enter from the left edge. This creates left-to-right diagrams.
• Vertical flow (automatic): When a target node sits significantly below or above its source (beyond a "horizon" threshold of 1.5x the source node's height), the connection switches to bottom/top ports. This creates vertical tree structures.

The switching is emergent from geometry — you don't configure it. Place nodes side by side and you get horizontal flow. Stack them vertically and you get vertical flow. Mix both and each connection picks the right ports independently.

Connection Rendering

Connections are drawn as smooth cubic bezier curves with:

• Directional S-bend control points (horizontal or vertical)
• Color derived from the source node's type (darkened to 70%)
• Arrowhead at the endpoint

YAML Formats

Canvas-MCP supports two YAML formats. Use whichever fits your needs.

Simplified Format

The simplified format is a flat list of nodes. Canvas-MCP auto-wraps them in the hierarchy (one network > one factory > auto-detected machines) and handles layout:

title: My Pipeline

nodes:
  - id: ingest
    type: input
    label: "Data Ingest"
    content: "Accept incoming data"
    outputs: [clean]

  - id: clean
    type: process
    label: "Clean"
    content: "Normalize and validate"
    inputs: [ingest]
    outputs: [analyze]

  - id: analyze
    type: ai
    label: "AI Analysis"
    content: "Run LLM inference"
    inputs: [clean]
    outputs: [report]

  - id: report
    type: output
    label: "Report"
    content: "Generated summary"
    inputs: [analyze]

Auto-layout: When all node coordinates are (0, 0) (or omitted), Canvas-MCP arranges them automatically. Use the organize flag for intelligent topological layout.

Auto-machines: Connected components of nodes are automatically grouped into machines.

Hierarchical Format

The full format gives you explicit control over the entire hierarchy:

canvas:
  version: "2.0"
  title: AI Pipeline

  networks:
    - id: main-system
      label: "Production System"

      factories:
        - id: ingestion
          label: "Data Ingestion"

          machines:
            - id: sources
              label: "Data Sources"
              nodes:
                - id: api-feed
                  type: source
                  x: 100
                  y: 100
                  label: "API Feed"
                  content: "External API data"
                  outputs: [preprocess]

                - id: db-source
                  type: source
                  x: 100
                  y: 260
                  label: "Database"
                  content: "Historical records"
                  outputs: [preprocess]

            - id: processing
              label: "Processing"
              nodes:
                - id: preprocess
                  type: process
                  x: 450
                  y: 180
                  label: "Preprocess"
                  content: "Clean and normalize"
                  inputs: [api-feed, db-source]
                  outputs: [analyze]

        - id: analysis
          label: "Analysis"

          machines:
            - id: ai-stage
              label: "AI Stage"
              nodes:
                - id: analyze
                  type: ai
                  x: 800
                  y: 180
                  label: "AI Analysis"
                  content: "Run LLM analysis"
                  inputs: [preprocess]
                  outputs: [output]

                - id: output
                  type: output
                  x: 1150
                  y: 180
                  label: "Report"
                  content: "Generated report"
                  inputs: [analyze]

Layout System

Canvas-MCP includes a built-in topological layout engine.

Auto-Layout

When all nodes have coordinates at (0, 0), the basic auto-layout arranges them:

• Left-to-right within machines (80px horizontal spacing)
• Top-to-bottom between machines (200px vertical spacing)
• Extra gap between factories (60px)

Organize Algorithm

Enable with organize: true for intelligent hierarchical layout:

1. Topological sort (Kahn's algorithm) assigns hierarchical levels
2. Parent-center alignment vertically centers children on their parents
3. Overlap prevention enforces minimum spacing
4. Cycle handling gracefully positions nodes in cyclic graphs
5. Grid fallback arranges disconnected components in a grid

Spacing Levels

Control breathing room with the spacing_level parameter:

Visual Theme

Canvas-MCP uses the Catppuccin Mocha dark theme:

MCP Tools

Canvas-MCP exposes four tools via the Model Context Protocol:

render_canvas

Render a YAML recipe string to PNG.

create_canvas

Create a diagram from structured input (title + nodes + optional machines).

Returns both a PNG and a saved YAML recipe.

list_templates

List available starter templates. Returns template names and file paths.

get_template

Retrieve the YAML content of a specific template by name.

Installation

As an MCP Server

Add to your MCP client configuration (e.g., .mcp.json):

{
  "mcpServers": {
    "canvas-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/Canvas-MCP",
        "canvas-mcp"
      ]
    }
  }
}

Running Directly

uv run canvas-mcp   # Starts the MCP stdio server

Testing

uv run python test_render.py   # Renders test PNGs to output/

Project Structure

Canvas-MCP/
├── src/canvas_mcp/
│   ├── models.py       # Ontology: Canvas > Network > Factory > Machine > Node
│   ├── parser.py       # YAML parser (simplified + hierarchical formats)
│   ├── renderer.py     # Pillow-based PNG renderer
│   ├── organize.py     # Hierarchical layout algorithm (topological sort)
│   └── server.py       # MCP server with 4 tools
├── templates/
│   ├── simple-flow.yaml      # 3-node linear pipeline
│   ├── decision-tree.yaml    # Branching decision flow
│   └── ai-pipeline.yaml      # Full hierarchical example
├── pyproject.toml
└── test_render.py

Output

PNGs are saved to ~/.rhode/canvas/ by default. Set the CANVAS_OUTPUT_DIR environment variable to change this.

License

MIT