JSON Canvas

🚀 JSON Canvas MCP Server

This is a server implementing the Model Context Protocol (MCP), providing tools for processing JSON Canvas files according to the official specification. This server supports the creation, modification, and validation of infinite canvas data structures.

🚀 Quick Start

The JSON Canvas MCP Server fully implements the JSON Canvas 1.0 specification and supports the following features:

• Create and manipulate infinite canvas data.
• Support all node types (text, file, link, group).
• Edge connections with styles and labels.
• Specification validation.
• Configurable output paths.

✨ Features

Resources

The server exposes the following resources:

• canvas://schema: A JSON schema for validating canvas files.
• canvas://examples: Example canvas files demonstrating different functionalities.
• canvas://templates: Templates for creating new canvases.

Tools

Node Operations

• create_node

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

• update_node

  • Update the attributes of an existing node.
  • Input:
    • id (string): The ID of the node to be updated.
    • properties (object): The attributes to be updated.
  • Return: The updated node object.

• delete_node

  • Delete a node and its connected edges.
  • Input:
    • id (string): The ID of the node to be deleted.
  • Return: None.

Edge Operations

• create_edge

  • Create a new edge.
  • Input:
    • id (string): The unique identifier of the edge.
    • from_node (string): The ID of the starting node.
    • to_node (string): The ID of the target node.
    • label (string, optional): The label of the edge.
    • color (string, optional): The color of the edge, default is "#000000".
  • Return: The created edge object.

• update_edge

  • Update the attributes of an existing edge.
  • Input:
    • id (string): The ID of the edge to be updated.
    • properties (object): The attributes to be updated.
  • Return: None.

• delete_edge

  • Delete a specified edge.
  • Input:
    • id (string): The ID of the edge to be deleted.
  • Return: None.

💻 Usage Examples

Using Claude Desktop

Method 1: Through the Command-Line Tool

1. Install and start Claude Desktop.
2. Open a terminal and run the following command:

python3 -m jsoncanvas.example

3. Follow the prompts to operate.

Method 2: Directly Using the API

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"  # Use a preset color
)

# Create a 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 the canvas
canvas.save("example.canvas")

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"  # Use a preset color
)

# Create a 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 the canvas
canvas.save("example.canvas")

📚 Documentation

Configuration

Environment Variable Configuration

Set the following environment variables to customize the server behavior:

• JSONCANVAS_PORT: Specify the port the server listens on, default is 3000.
• JSONCANVAS_HOST: Specify the host address the server binds to, default is localhost.
• JSONCANVAS_LOG_LEVEL: Specify the log level, available values are debug, info, warning, error, default is info.

Configuration File

You can create a config.json file in the project root directory:

{
    "port": 3001,
    "host": "127.0.0.1",
    "log_level": "debug"
}

Build Instructions

Clone the Repository

Use Git to clone this project:

git clone https://github.com/your-username/jsoncanvas.git
cd jsoncanvas

Install Dependencies

Run the following command to install the required dependencies:

pip install -r requirements.txt

Run the Server

After installation, run the following command to start the server:

python3 -m jsoncanvas.server

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.