JSON Canvas MCP Server

JSON Canvas MCP サーバー

Obsidianで使用されているオープンな無限キャンバス形式であるJSON Canvasファイルを扱うための、Model Context Protocol（MCP）サーバーです。MCP クライアントから .canvas ファイルの作成、検証、読み取り、一覧表示ができます。

公式の mcp Python SDK（>=1.27）を基盤としており、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 — 保存済みのキャンバスに対して、ノードとエッジの追加、更新、削除を1回のアトミックな書き込みで行います（操作に失敗した場合、ファイルは変更されません）。
  • 入力：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、検索対象を1つのキャンバスに限定する省略可能な 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 — シンプルなキャンバスの例（2つのテキストノードがエッジで接続されています）。
• ui://canvas/viewer.html — インタラクティブなキャンバスビューア（MCP Apps UI）。MIME タイプ text/html;profile=mcp-app で提供されます。create_canvas と read_canvas から参照されます。

インタラクティブキャンバスビューアー（MCP Apps UI）

ビューアーは、Vite と公式の @modelcontextprotocol/ext-apps クライアントを使用して ui/ のソースからビルドされる、単独で動作する HTML バンドルです。ノード（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 トランスポート

stdio の代わりに Streamable HTTP 経由で提供するには、次のようにします。

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 の Origin のみ）。ホストの外部からの接続を許可するには（たとえば、HTTP を使ってコンテナを実行する場合）、--host 0.0.0.0 を指定してバインドし、許可する Origin を適切に設定します。

キャンバスビューアーを描画するブラウザーベースの MCP ホストは、クロスオリジンで接続し、mcp-session-id レスポンスヘッダーを読み取る必要があるため、Streamable HTTP トランスポートでは制限の緩い CORS ヘッダーを提供します。MCP_CORS_ORIGINS（カンマ区切り。デフォルトは *）を使って許可するオリジンを制限してください。

セキュリティに関する注意。 HTTP トランスポートには認証がありません。ポートにアクセスできる人は誰でも、OUTPUT_PATH 配下の .canvas ファイルを読み書きできます。このサーバーはローカルでの使用を想定しています。デフォルトの 127.0.0.1 にバインドしたままにしてください。DNS リバインディング／Origin 保護では、起動時に localhost の Origin と Host が固定されます。そのため、--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 を参照してください。