AI导哈

JSON画布服务器

一个基于Model Context Protocol (MCP)的服务器，用于创建、验证、读取和编辑JSON Canvas文件，支持交互式画布预览和多种操作功能。

  • by Cam10001110101
  • HTML
  • 混合部署
  • 15 星标
  • 更新于
在 GitHub 查看 Cam10001110101/mcp-server-obsidian-jsoncanvas

使用说明

JSON画布MCP服务器

A. 模型上下文协议 用于工作的（MCP）服务器 JSON画布 files——使用的开放无限画布格式 通过 黑曜石它允许MCP客户端创建、验证和执行数据， 读取并列出 .canvas 文件夹。

建立在官方 mcp Python SDK(>=1.27)，协商 2025-11-25 主控程序 协议修订。跑过 标准 默认情况下，也可以选择覆盖 流式HTTP 运输。

支持的主机 MCP应用程序 UI扩展渲染 交互式画布查看器 当你阅读或创建画布时，内联——平移/缩放， 节点和边的黑曜石风格预览。纯文本客户端不受影响并保持 接收画布作为文本/结构化输出。

组件

工具

  • create_canvas --从以下位置创建画布 nodes （可选 edges)并将其写入 日期前缀 .canvas 归档于 OUTPUT_PATH.
    • 输入： 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 --列出 .canvas 文件可用于 OUTPUT_PATH.
    • 返回：文件名数组。
  • 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的主机将其内联重新渲染。
  • 出口canvas --将存储的画布导出为其他格式。
    • 输入： filename, format (markdown | svg).
    • 回报（结构化）： { format, mime_type, content }Markdown是一种边缘有序的轮廓； SVG是一个独立的矢量图像（仅节点标题行——纯SVG无法渲染Markdown）。
  • 搜索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模式。
  • canvas://examples/basic --一个简单的示例画布（由边连接的两个文本节点）。
  • ui://canvas/viewer.html --交互式画布查看器（MCP Apps UI），提供MIME服务 类型 text/html;profile=mcp-app.引用人 create_canvas 和 read_canvas.

交互式画布查看器（MCP应用程序UI）

查看器是一个自包含的HTML包，由 ui/ 来源Vite 和官方 @modelcontextprotocol/ext-apps 客户。它渲染节点（带有标记、颜色和组）和边（边、箭头、标签） 在平移/缩放视图中，通过主机的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（标准操作系统）

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" }
    }
  }
}

紫外线（stdio）

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

可流式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，并且，per 2025-11-25规范验证了 Origin 启用DNS重新绑定保护的标头 （默认情况下仅限localhost Origins）。接受来自主机外部的连接（例如，当 使用HTTP运行容器），bind --host 0.0.0.0 并配置您允许的起源 因此。

基于浏览器的MCP主机（渲染画布查看器的那种）连接跨源，并且必须 阅读 mcp-session-id 响应标头，因此Streamable HTTP传输提供许可 CORS标头。限制允许的来源 MCP_CORS_ORIGINS （逗号分隔；默认值 *).

安全说明。 HTTP传输是 未认证的 --任何能到达港口的人 可以读写 .canvas 文件下 OUTPUT_PATH该服务器旨在供本地使用； 保持它的束缚 127.0.0.1 （默认设置）。DNS重新绑定/Origin 保护已固定 启动时的localhost起源和主机，因此绑定 --host 0.0.0.0 暴露上的端口 网络，但仍拒绝非本地主机 Host/Origin headers——为了安全地远程公开它， 使用身份验证反向代理对其进行前端处理，而不是直接发布，并设置 MCP_CORS_ORIGINS 到你信任的具体来源（永远不要 *).

配置

环境变量：

  • OUTPUT_PATH --目录在哪里 .canvas 文件被写入/读取（默认 ./output).
  • MCP_TRANSPORT — stdio （默认）或 streamable-http.
  • MCP_HOST / MCP_PORT --流式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。看 许可证.

相关 MCP