JSON Canvas MCP Server

JSON Canvas MCP Server

A Model Context Protocol (MCP) server implementation that provides tools for working with JSON Canvas files according to the official specification. This server enables creating, modifying, and validating infinite canvas data structures.

Overview

The JSON Canvas MCP server provides a complete implementation of the JSON Canvas 1.0 specification, enabling:

• Creation and manipulation of infinite canvas data
• Support for all node types (text, file, link, group)
• Edge connections with styling and labels
• Validation against the specification
• Configurable output paths

Components

Resources

The server exposes the following resources:

• canvas://schema: JSON Schema for validating canvas files
• canvas://examples: Example canvas files demonstrating different features
• canvas://templates: Templates for creating new canvases

Tools

Node Operations

• create_node

  • Create a new node of any supported type
  • Input:
    • type (string): Node type ("text", "file", "link", "group")
    • properties (object): Node-specific properties
      • Common: id, x, y, width, height, color
      • Type-specific: text, file, url, etc.
  • Returns: Created node object

• update_node

  • Update an existing node's properties
  • Input:
    • id (string): Node ID to update
    • properties (object): Properties to update
  • Returns: Updated node object

• delete_node

  • Remove a node and its connected edges
  • Input:
    • id (string): Node ID to delete
  • Returns: Success confirmation

Edge Operations

• create_edge

  • Create a new edge between nodes
  • Input:
    • id (string): Unique edge identifier
    • fromNode (string): Source node ID
    • toNode (string): Target node ID
    • fromSide (optional string): Start side ("top", "right", "bottom", "left")
    • toSide (optional string): End side
    • color (optional string): Edge color
    • label (optional string): Edge label
  • Returns: Created edge object

• update_edge

  • Update an existing edge's properties
  • Input:
    • id (string): Edge ID to update
    • properties (object): Properties to update
  • Returns: Updated edge object

• delete_edge

  • Remove an edge
  • Input:
    • id (string): Edge ID to delete
  • Returns: Success confirmation

Canvas Operations

• validate_canvas

  • Validate a canvas against the specification
  • Input:
    • canvas (object): Canvas data to validate
  • Returns: Validation results with any errors

• export_canvas

  • Export canvas to different formats
  • Input:
    • format (string): Target format ("json", "svg", "png")
    • canvas (object): Canvas data to export
  • Returns: Exported canvas in requested format

Usage with Claude Desktop

Docker

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "jsoncanvas": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "canvas-data:/data",
        "mcp/jsoncanvas"
      ],
      "env": {
        "OUTPUT_PATH": "/data/output"
      }
    }
  }
}

UV

{
  "mcpServers": {
    "jsoncanvas": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/jsoncanvas",
        "run",
        "mcp-server-jsoncanvas"
      ],
      "env": {
        "OUTPUT_PATH": "./output"
      }
    }
  }
}

Configuration

The server can be configured using environment variables:

• OUTPUT_PATH: Directory where canvas files will be saved (default: "./output")
• FORMAT: Default output format for canvas files (default: "json")

Building

Docker Build

docker build -t mcp/jsoncanvas .

Local Build

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Run tests
pytest

Example Usage

Creating a Canvas

from jsoncanvas import Canvas, TextNode, Edge

# Create nodes
title = TextNode(
    id="title",
    x=100,
    y=100,
    width=400,
    height=100,
    text="# Hello Canvas\n\nThis is a demonstration.",
    color="#4285F4"
)

info = TextNode(
    id="info",
    x=600,
    y=100,
    width=300,
    height=100,
    text="More information here",
    color="2"  # Using preset color
)

# Create canvas
canvas = Canvas()
canvas.add_node(title)
canvas.add_node(info)

# Connect nodes
edge = Edge(
    id="edge1",
    from_node="title",
    to_node="info",
    from_side="right",
    to_side="left",
    label="Connection"
)
canvas.add_edge(edge)

# Save canvas
canvas.save("example.canvas")

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.