JSON Canvas MCP 服务器

根据官方规范实现的模型上下文协议（MCP）服务器，提供了处理 JSON Canvas 文件的工具。该服务器支持创建、修改和验证无限画布数据结构。

概览

JSON Canvas MCP 服务器实现了完整的 JSON Canvas 1.0 规范，支持以下功能：

• 创建和操作无限画布数据
• 支持所有节点类型（文本、文件、链接、组）
• 边缘连接及其样式和标签
• 根据规范进行验证
• 可配置的输出路径

组件

资源

服务器公开了以下资源：

• canvas://schema：用于验证画布文件的 JSON Schema
• canvas://examples：展示不同特性的示例画布文件
• canvas://templates：创建新画布的模板

工具

节点操作

• create_node

  • 创建任意支持类型的节点
  • 输入：
    • type (字符串)：节点类型 ("text", "file", "link", "group")
    • properties (对象)：节点特定属性
      • 公共属性：id, x, y, width, height, color
      • 类型特定属性：text, file, url 等
  • 返回：创建的节点对象

• update_node

  • 更新现有节点的属性
  • 输入：
    • id (字符串)：要更新的节点ID
    • properties (对象)：要更新的属性
  • 返回：更新后的节点对象

• delete_node

  • 删除节点及其连接的边缘
  • 输入：
    • id (字符串)：要删除的节点ID
  • 返回：成功确认

边缘操作

• create_edge

  • 在节点之间创建新的边缘
  • 输入：
    • id (字符串)：唯一的边缘标识符
    • fromNode (字符串)：源节点ID
    • toNode (字符串)：目标节点ID
    • fromSide (可选字符串)：起始边 ("top", "right", "bottom", "left")
    • toSide (可选字符串)：结束边
    • color (可选字符串)：边缘颜色
    • label (可选字符串)：边缘标签
  • 返回：创建的边缘对象

• update_edge

  • 更新现有边缘的属性
  • 输入：
    • id (字符串)：要更新的边缘ID
    • properties (对象)：要更新的属性
  • 返回：更新后的边缘对象

• delete_edge

  • 删除边缘
  • 输入：
    • id (字符串)：要删除的边缘ID
  • 返回：成功确认

画布操作

• validate_canvas

  • 验证画布是否符合规范
  • 输入：
    • canvas (对象)：要验证的画布数据
  • 返回：验证结果及任何错误

• export_canvas

  • 将画布导出到不同的格式
  • 输入：
    • format (字符串)：目标格式 ("json", "svg", "png")
    • canvas (对象)：要导出的画布数据
  • 返回：以请求格式导出的画布

使用与 Claude Desktop

Docker

在你的 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"
      }
    }
  }
}

配置

服务器可以通过环境变量进行配置：

• OUTPUT_PATH：画布文件保存的目录（默认："./output"）
• FORMAT：画布文件的默认输出格式（默认："json"）

构建

Docker 构建

docker build -t mcp/jsoncanvas .

本地构建

# 如果尚未安装，请安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境并安装依赖项
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
uv pip install -e .

# 运行测试
pytest

示例用法

创建一个画布

from jsoncanvas import Canvas, TextNode, Edge

# 创建节点
title = TextNode(
    id="title",
    x=100,
    y=100,
    width=400,
    height=100,
    text="# Hello Canvas\n\n这是一个演示。",
    color="#4285F4"
)

info = TextNode(
    id="info",
    x=600,
    y=100,
    width=300,
    height=100,
    text="这里有更多的信息",
    color="2"  # 使用预设颜色
)

# 创建画布
canvas = Canvas()
canvas.add_node(title)
canvas.add_node(info)

# 连接节点
edge = Edge(
    id="edge1",
    from_node="title",
    to_node="info",
    from_side="right",
    to_side="left",
    label="连接"
)
canvas.add_edge(edge)

# 保存画布
canvas.save("example.canvas")

许可证

此 MCP 服务器采用 MIT 许可证。这意味着你可以自由地使用、修改和分发软件，但需遵守 MIT 许可证中的条款和条件。更多详情，请参阅项目仓库中的 LICENSE 文件。