JSON Canvas MCP Server

JSON Canvas MCP 服务

这是一个 Model Context Protocol（MCP）服务，用于处理 JSON Canvas 文件——一种由 Obsidian 使用的开放式无限画布格式。它允许 MCP 客户端创建、验证、读取和列出 .canvas 文件。

基于官方 mcp Python SDK（>=1.27）构建，该 SDK 协商使用 2025-11-25 版 MCP 协议。默认通过 stdio 运行，也可选择使用 Streamable HTTP 传输方式。

支持 MCP Apps UI 扩展的宿主会在读取或创建画布时内嵌呈现交互式画布查看器，用于预览节点和边，风格类似 Obsidian，并支持平移和缩放。纯文本客户端不受影响，仍会接收文本／结构化输出形式的画布。

组件

工具

• create_canvas — 根据 nodes（以及可选的 edges）创建画布，并将其写入 OUTPUT_PATH 下带日期前缀的 .canvas 文件。
  • 输入：nodes（JSON Canvas 节点对象数组）、filename（字符串，不含扩展名）、edges（可选的边对象数组）。
  • 返回（结构化）：{ path, node_count, edge_count }。
• validate_canvas — 根据 JSON Canvas 1.0 规范验证画布数据。
  • 输入：canvas（包含可选 nodes 和 edges 的对象）。
  • 返回（结构化）：{ valid, error }。
• read_canvas — 读取已存储的 .canvas 文件，并返回其中的节点和边。
  • 输入：filename（字符串，可带或不带 .canvas 扩展名）。
  • 返回（结构化）：{ nodes, edges }（同时由画布查看器呈现；文本回退形式为画布 JSON）。
• list_canvases — 列出 OUTPUT_PATH 中可用的 .canvas 文件。
  • 返回：文件名数组。
• edit_canvas — 在一次原子写入中，对已存储的画布添加、更新和／或移除节点和边（操作失败时文件保持不变）。
  • 输入：filename，以及可选的 add_nodes、update_nodes（局部更新，必须包含 id）、remove_node_ids（级联移除相连的边）、add_edges、update_edges、remove_edge_ids。
  • 返回（结构化）：{ path, node_count, edge_count, canvas } — 更新后的画布，因此支持 UI 的宿主会在页面内重新呈现画布。
• export_canvas — 将已存储的画布导出为其他格式。
  • 输入：filename、format（markdown | svg）。
  • 返回（结构化）：{ format, mime_type, content }。Markdown 是按边排序的大纲；SVG 是独立的矢量图像（仅包含节点标题行，纯 SVG 无法呈现 Markdown）。
• search_canvases — 在已存储的画布中进行不区分大小写的子字符串搜索。
  • 输入：query，以及可选的 filename，用于将搜索范围限定在一个画布中。
  • 返回（结构化）：{ matches: [{ filename, kind, id, field, snippet }] }。

create_canvas、read_canvas 和 edit_canvas 通过 _meta.ui.resourceUri 与画布查看器关联，因此支持 UI 的宿主会在页面内呈现结果。

节点对象采用 JSON Canvas 结构：id、type（text | file | link | group）、x、y、width、height、可选的 color，以及各类型专属字段（text、file/subpath、url、label/background/backgroundStyle）。边对象包含 id、fromNode、toNode，以及可选的 fromSide/toSide/fromEnd/toEnd/color/label。

资源

• canvas://schema — 用于验证画布文件的 JSON Schema。
• canvas://examples/basic — 一个简单的示例画布（两个文本节点由一条边连接）。
• ui://canvas/viewer.html — 交互式画布查看器（MCP Apps UI），以 MIME 类型 text/html;profile=mcp-app 提供。由 create_canvas 和 read_canvas 引用。

交互式画布查看器（MCP Apps UI）

查看器是一个独立的 HTML 包，由 ui/ 源码通过 Vite 和官方 @modelcontextprotocol/ext-apps 客户端构建而成。它会在平移和缩放视图中渲染节点（含 Markdown、颜色和分组）以及边（含边的位置、箭头和标签），并通过宿主的 CSS 变量设置主题。

构建后的包已提交至 jsoncanvas/_ui/viewer.html，并随软件包一起发布，因此运行服务只需要 Python。更改 ui/ 后，请重新构建：

make build-ui     # cd ui && npm install && npm run build  (requires Node.js)

若要单独预览渲染器（无需 MCP 宿主），运行 cd ui && npm run dev，然后打开 /preview.html。

在 Claude Desktop 中使用

Docker（stdio）

docker build -t mcp/jsoncanvas .

将以下内容添加到你的 claude_desktop_config.json：

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

uv（stdio）

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

Streamable HTTP 传输

若要通过 Streamable HTTP 而非 stdio 提供服务：

mcp-server-jsoncanvas --transport streamable-http --host 127.0.0.1 --port 8000

此时 MCP 端点为 http://127.0.0.1:8000/mcp。传输绑定到 localhost，并根据 2025-11-25 规范启用 DNS 重绑定防护，对 Origin 标头进行验证（默认仅允许 localhost 来源）。若要接受来自宿主外部的连接（例如通过 HTTP 运行容器时），请绑定 --host 0.0.0.0，并相应配置允许的来源。

基于浏览器的 MCP 宿主（即会渲染画布查看器的宿主）会跨源连接，并且必须读取 mcp-session-id 响应标头，因此 Streamable HTTP 传输会提供宽松的 CORS 标头。使用 MCP_CORS_ORIGINS 限制允许的来源（逗号分隔；默认值为 *）。

安全说明。 HTTP 传输未经身份验证——任何能够访问该端口的人，都可以读取和写入 OUTPUT_PATH 下的 .canvas 文件。该服务旨在本地使用；请将其绑定到 127.0.0.1（默认值）。启动时会将 DNS 重绑定防护和 Origin 防护固定为仅允许 localhost 来源和主机，因此绑定 --host 0.0.0.0 虽会将端口暴露在网络上，但仍会拒绝非 localhost 的 Host/Origin 标头。若要安全地远程公开服务，请在其前方部署经过身份验证的反向代理，而不要直接发布服务，并将 MCP_CORS_ORIGINS 设置为你信任的特定来源（切勿使用 *）。

配置

环境变量：

• OUTPUT_PATH — 写入/读取 .canvas 文件的目录（默认值为 ./output）。
• MCP_TRANSPORT — stdio（默认值）或 streamable-http。
• MCP_HOST / MCP_PORT — Streamable HTTP 传输的主机/端口（默认值为 127.0.0.1:8000）。
• MCP_CORS_ORIGINS — HTTP 传输允许的 CORS 来源，以逗号分隔（默认值为 *）。

开发

# Install uv: https://docs.astral.sh/uv/getting-started/installation/
make setup        # uv venv && uv sync --extra dev
make build-ui     # rebuild the canvas viewer bundle (requires Node.js)
make test         # run the test suite
make lint         # ruff check + format check
make audit        # scan dependencies for known vulnerabilities (pip-audit)
make run          # run the server over stdio

运行打包的库示例：

make example      # writes example.canvas to OUTPUT_PATH (default ./output)

库示例

也可以直接使用 jsoncanvas 包：

from jsoncanvas import Canvas, TextNode, Edge

title = TextNode(id="title", x=100, y=100, width=400, height=100,
                 text="# Hello Canvas", color="#4285F4")
info = TextNode(id="info", x=600, y=100, width=300, height=100,
                text="More information here", color="2")  # preset color

canvas = Canvas()
canvas.add_node(title)
canvas.add_node(info)
canvas.add_edge(Edge(id="edge1", from_node="title", to_node="info",
                     from_side="right", to_side="left", label="Connection"))

import json
print(json.dumps(canvas.to_dict(), indent=2))

许可证

MIT。请参阅 LICENSE。