Content
# 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](https://jsoncanvas.org/spec/1.0/). 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`:
```json
{
"mcpServers": {
"jsoncanvas": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"canvas-data:/data",
"mcp/jsoncanvas"
],
"env": {
"OUTPUT_PATH": "/data/output"
}
}
}
}
```
### UV
```json
{
"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
```bash
docker build -t mcp/jsoncanvas .
```
### Local Build
```bash
# 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
```python
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.
MCP Store
