Visual MCP

Model Context Protocol サーバーで、LLM に構造化された視覚レイヤーを提供します。「何が存在するか」を記述すると、クリーンで正確な SVG 図が返ってきます。ASCII アートではありません。

Visual MCP とは？

LLM に「アーキテクチャを描いて」と頼むと、こうなります：

+----------+      +---------+      +------------+
|  React   |----->| NestJS  |----->| PostgreSQL |
+----------+      +---------+      +------------+
                       |
                       +-----> Redis?

罫線文字は空間情報を伝えるのに適していません。配置が崩れ、矢印が届かず、後から編集できず、モデルは文字数の計算に推論力を浪費します。

明白な修正案 — 「モデルに SVG を書かせる」 — はさらに悪化します。viewBox、パスデータ、矢印の多角形、テキストのベースライン、境界線の交差を、すべて手動で、フィードバックなしに、ユーザーが小さな変更を求めるたびにゼロから計算し直さなければなりません。

Visual MCP はモデルの仕事から幾何学計算を取り除きます。 モデルはシーングラフを操作します：

{
  "title": "Service architecture",
  "elements": [
    { "id": "frontend", "type": "node",     "label": "React" },
    { "id": "backend",  "type": "node",     "label": "NestJS" },
    { "id": "db",       "type": "database", "label": "PostgreSQL" },
    { "id": "cache",    "type": "database", "label": "Redis" },

    { "id": "c1", "type": "connection", "from": "frontend", "to": "backend" },
    { "id": "c2", "type": "connection", "from": "backend",  "to": "db" },
    { "id": "c3", "type": "connection", "from": "backend",  "to": "cache" }
  ]
}

ここにないものに注目してください：座標、サイズ、線の端点、矢印、SVG は一切ありません。サーバーがすべてを計算します — ラベルからノードサイズ、接続グラフから位置、境界線に合うエッジ、矢印マーカー、テキストの折り返し、クリップしない viewBox を。

そして、シーンは安定した ID を持つグラフであるため、会話の次のターンは再描画ではなく一行の編集になります：

「Redis をバックエンドの上に、PostgreSQL をその下に置いて」 → update_element × 2、他はすべてそのまま。

「すべてのインフラを AWS というボックスの中に入れて」 → group_elements、何も移動しません。

Related MCP server: Mermaid MCP Server

アーキテクチャ

ChatGPT
   │  tool call: render_diagram / update_element / …
   ▼
MCP server            src/mcp/         (transport, tools, error shaping)
   │
   ▼
Scene graph           src/scene/       (Zod schemas, validation, store, mutations)
   │
   ├─▶ layout         src/layout/      (sizes and positions for elements with no coordinates)
   ├─▶ semantic       src/semantic/    (node/connection/axis/… ▸ primitives)
   │
   ▼
SvgNode tree          src/renderer/    (closed, allow-listed representation of an SVG document)
   │
   ├─▶ toSvgString()  ─────────────────▶  SVG returned by the MCP tools
   └─▶ <SceneRenderer> ────────────────▶  React, for the interactive UI

これを支える5つのアイデア

1. シーングラフが成果物であり、SVG は単なる出力形式です。 モデルが送信するものはすべて検証されて Scene として保存されます。レンダリングはそのシーンの純粋関数であるため、同じ図を後で別のテーマで、または別のバックエンドで、モデルを介さずに再レンダリングできます。

2. セマンティック要素はプリミティブにコンパイルされます。 database はパス、楕円、2つのテキストブロックになります。connection はマーカー付きのパスになります。レンダラーは10個のプリミティブのみを認識します。これによりレンダラーは小さく保たれ、後で neuron、decisionTree、functionPlot を追加する場合も、スキーマの共用体、レイアウトエンジン、レンダラーに変更を加えることなく、src/semantic/ に1つの展開ファイルを追加するだけで済みます。

3. 1つのジオメトリパイプライン、2つのバックエンド。 レンダラーの実際の出力は文字列ではなく SvgNode ツリーです。serialize() はそれを MCP ツール用のマークアップに変換し、<SceneRenderer> はそれを UI 用の React 要素にマッピングします。ドリフトする2つ目の実装はなく、プロジェクト内に dangerouslySetInnerHTML もありません。

4. エラーはログファイルではなく、モデル向けに書かれています。

{
  "success": false,
  "error": {
    "code": "ELEMENT_NOT_FOUND",
    "message": "Connection 'c1' points to 'router-2' (to), which does not exist in the scene.",
    "path": "c1.to",
    "hint": "Existing elements you can connect: pc, switch, router-1, server."
  }
}

分岐するためのコード、問題を特定する文、答えを含むヒント。スタックトレースは決してありません。

5. すべての変更はアトミックです。 拒否された編集は、保存されたシーンをバイト単位で元のままにします。これがなければ、1回の不正な呼び出しで、会話の残りの間、図が破損してしまいます。

当初スケッチされたレイアウトからの逸脱

• src/layout/ は独自のモジュールであり、src/semantic/ から分離されています。配置と意味から形状への展開は異なる問題であり、この分割により、後で Dagre や ELK を導入する場合も、1つのファイル（src/layout/flow.ts）の変更で済みます。その FlowItem in / centres out インターフェースは、これらのライブラリが公開する形状を意図的に模倣しています。

• SvgNode はレンダラーとその出力の間に位置します（上記のアイデア3）。これにより、React ビューが2つ目のレンダラーや安全でない HTML インジェクションなしで存在できるようになります。

• src/mcp/widget.ts は依存関係のないバニラビューアであり、src/ui/ の React アプリとは別のものです。ChatGPT の iframe リソースは、ビルドステップがなく、実行時に古くなったり欠落したりする可能性のない、単一の自己完結型 HTML 文字列でなければなりません。React アプリはローカルプレイグラウンドです。両者は同じ動作（ズーム/パン/フィット/コピー/エクスポート）と同一の許可リストを共有します。

• 自動フィットはデフォルトでオンになっているため、width/height はハードなキャンバスではなくヒントとして機能します。これにより、最も一般的な障害モード — モデルが小さすぎるキャンバスを選び、自身の図をクリップしてしまう — が排除されます。

インストール

git clone <this repo>
cd visual-mcp
npm install

Node 20 以上が必要です（Node 22/26 で開発）。

開発

npm run dev:http      # MCP server over Streamable HTTP on http://localhost:3333/mcp
npm run dev:stdio     # MCP server over stdio (Claude Desktop, MCP Inspector, tunnels)
npm run dev:ui        # React playground on http://localhost:5180
npm test              # 128 tests
npm run typecheck
npm run build         # server → dist/
npm run build:ui      # playground → dist-ui/
npm run examples      # render the reference scenes → examples/out/index.html

実行中のサーバーに対するクイックエンドツーエンドテスト：

npm run dev:http &
npx tsx scripts/smoke-mcp.ts

これはターゲットとなる会話全体を再生します — 座標なしで図を構築し、検査し、2つのノードを移動し、すべてをボックスで囲み — 各ステップで結果をアサートします。

利用可能な MCP ツール

すべてのツールの説明には、機能、使用タイミング、使用すべきでないタイミング、各プロパティの意味が記載されています。これは別のモデルがこれらを読み、自ら判断するためです。読み取り専用ツールは readOnlyHint: true を、破壊的なツールは destructiveHint: true を持ち、ホストはこれらを使用して確認が必要かどうかを判断します。

シーンスキーマ

interface Scene {
  id?: string;
  title?: string;
  subtitle?: string;
  width?: number;          // hint; autoFit grows the canvas so nothing is clipped
  height?: number;
  autoFit?: boolean;       // default true
  background?: string;
  theme?: "dark" | "light" | "blueprint" | "paper";
  themeOverrides?: Partial<Theme>;
  layout?: "auto" | "layered" | "horizontal" | "vertical" | "grid" | "manual";
  direction?: "right" | "down" | "left" | "up";
  gap?: number;
  padding?: number;
  legend?: boolean;
  elements: VisualElement[];
}

すべての要素は id と type を持ちます。ID は安定しており、会話型編集の基盤です。

プリミティブ — レンダラーが描画できるもの

circle · ellipse · rectangle · line · arrow · text · polygon · polyline · path · group

セマンティック要素 — モデルが実際に使用すべきもの

レイアウト

layout: "auto"（デフォルト）は、接続がある場合は接続グラフから階層的なフローを構築し、ない場合は行を構築します。明示的に x/y を持つ要素は決して移動されないため、モデルは他の要素を乱すことなく1つのノードを微調整できます。direction はフローの方向を制御します。

データフレーム

axis はデータ単位からピクセルへのマッピングを宣言します。frame: "<axis id>" を持つものはすべてデータ座標に配置され、y は期待通り上向きに増加します：

{ "id": "plot",  "type": "axis",    "x": 90, "y": 70, "width": 620, "height": 420,
  "xRange": [0, 10], "yRange": [0, 10], "xLabel": "Feature 1", "yLabel": "Feature 2" },
{ "id": "class-a", "type": "cluster", "frame": "plot", "x": 3.4, "y": 6.6,
  "count": 40, "spread": 0.8, "label": "Class A", "hull": true, "seed": 7 }

テーマ

4つの組み込みテーマ（dark、light、blueprint、paper）。それぞれが完全なパレットと、外部フォントを必要としないフォントスタックを持ちます。要素はハードコードされた色ではなくトークン（primary、surface、muted、danger）を参照するため、図全体のジオメトリに触れることなくスタイルを変更できます。themeOverrides は任意のトークンを変更できます。

ローカルでの実行

ライブラリとして（MCP なし）

import { renderScene } from "visual-mcp";

const svg = renderScene({
  title: "Request flow",
  elements: [
    { id: "client", type: "computer", label: "Client" },
    { id: "api", type: "server", label: "API" },
    { id: "c", type: "connection", from: "client", to: "api", label: "HTTPS" },
  ],
});

HTTP サーバーとして

npm run dev:http

サーバーはステートレスです。各リクエストは独自の McpServer とトランスポートを取得し、シーンストアのみが共有状態です。これにより、ロードバランサーの背後やサーバーレスプラットフォーム上でも安全に動作します。そこでは、1つの会話の2つのターンが同じプロセスに到達しない可能性があります。

stdio サーバーとして（MCP Inspector、Claude Desktop、Cursor）

npx @modelcontextprotocol/inspector npx tsx src/mcp/stdio.ts

{
  "mcpServers": {
    "visual-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/visual-mcp/dist/mcp/stdio.js"]
    }
  }
}

ChatGPT への接続

ChatGPT はリモート MCP サーバーに Streamable HTTP 経由でパブリックな HTTPS エンドポイント を通じて接続するため、サーバーはインターネットから到達可能である必要があります。2つの方法：

A. トンネルを使用したクイックテスト

npm run dev:http                  # http://localhost:3333/mcp
npx localtunnel --port 3333       # or: ngrok http 3333, or cloudflared tunnel

B. VPS に Docker でデプロイ

docker-compose.yml は、内部ポート4000で動作するMCPサーバー（インターネットには公開されません）と、その前でTLSを終端し、証明書を自動更新するCaddyの2つのコンテナを起動します。

このVPSには既に他のサービスがポート80と443で動作しているため、次の構成になります：

注意点： Let's EncryptはHTTP-01のために常にポート80に接続します（これはRFC 8555で固定されており、設定変更はできません）。TLS-ALPNも同様に443に固定されています。Caddyはポート90で待ち受けることはできますが、リクエストをそこに届ける何かが必要です。そのため、ポート80を既に使用している何らかのサーバーが、チャレンジ用のパスをCaddyに転送する必要があります。

1. 公開ホスト名を選ぶ。 ChatGPTはHTTPSを必要とし、ベアIPでは証明書を取得できません。独自のドメインがない場合は、sslip.ioを使用してください。これは<ip>.sslip.ioを登録不要でそのIPに解決し、Let's Encryptがそのドメインに対して証明書を発行します：

curl -4 ifconfig.me            # on the VPS -> e.g. 203.0.113.45
# hostname becomes: 203.0.113.45.sslip.io

2. ポート80サーバーからACMEチャレンジを転送する。 まず、そのサーバーを特定します：

sudo ss -lptn 'sport = :80'

nginx — server { listen 80; } ブロック内：

location /.well-known/acme-challenge/ {
    proxy_pass http://127.0.0.1:90;
    proxy_set_header Host $host;
}

Apache — <VirtualHost *:80> 内：

ProxyPreserveHost On
ProxyPass        /.well-known/acme-challenge/ http://127.0.0.1:90/.well-known/acme-challenge/
ProxyPassReverse /.well-known/acme-challenge/ http://127.0.0.1:90/.well-known/acme-challenge/

Caddy — ポート80を提供するサイトブロック内：

handle /.well-known/acme-challenge/* {
    reverse_proxy 127.0.0.1:90
}

301リダイレクトではなく、実際のプロキシを使用してください。Let's Encryptはリダイレクトをポート80と443にのみ追従するため、 :90へのリダイレクトは失敗します。

3. 設定して起動する：

cp .env.example .env
# MCP_DOMAIN=203.0.113.45.sslip.io
docker compose up -d --build

ポート80のサーバーがホスト上ではなく、それ自身のコンテナ内で実行されている場合、127.0.0.1:90 には到達できません。.env で MCP_HTTP_BIND=0.0.0.0 を設定し、プロキシをVPSの内部IP（または両方のコンテナを同じDockerネットワーク上に配置）に向けます。

4. 確認する（最初のリクエストは、証明書が発行される間に数秒かかることがあります）：

curl https://$MCP_DOMAIN:500/health       # {"status":"ok",...}
docker compose logs caddy | grep -i "certificate obtained"

MCP URLは https://<MCP_DOMAIN>:500/mcp となり、永続的です：restart: unless-stopped により再起動後も保持され、証明書は caddy_data ボリュームに保存されるため、docker compose down/up を実行しても更新は維持されます。docker compose down -v でのみ削除されます。チャレンジの転送設定は維持してください。約60日ごとの更新には、初回発行時と同様に転送が必要です。

PUBLIC_URL と ALLOWED_HOSTS は、Composeによって MCP_DOMAIN と MCP_HTTPS_PORT から派生します。両方にポートを含める必要があります：PUBLIC_URL は、そうしないと svgUrl リンクがポート443を指してしまうため、ALLOWED_HOSTS は、SDKが未加工の Host ヘッダー（標準以外のポートでは <domain>:500 となります）を正確な文字列として比較するためです。

ポート80のサーバーを操作できない場合、HTTP-01は全く利用できません。選択肢としては、DNS-01チャレンジ（対応するDNSプロバイダー上に実際のドメインが必要です — sslip.ioにはAPIがありません）、またはCloudflare Tunnelがあり、これはインバウンドポートを一切必要としません。

Composeを使用しない場合

docker build -t visual-mcp .
docker run -d --name visual-mcp --restart unless-stopped -p 127.0.0.1:4000:4000 \
  -e PUBLIC_URL=https://your-host -e ALLOWED_HOSTS=your-host visual-mcp

その後、任意のリバースプロキシを http://127.0.0.1:4000 に向けます。コンテナは非rootの node ユーザーとして実行され、/health HEALTHCHECKを出荷し、本番依存関係のみを含みます。管理対象プラットフォーム（Fly.io、Railway、Render、Cloud Run）でも動作します。これらは独自の PORT を注入し、サーバーはそれを尊重します。

その後、ChatGPTで

1. 開発者モードを有効にする。 ChatGPT Business、Enterprise、Edu（Web版）で利用可能です。管理者がワークスペース設定 → 権限とロール → 接続データ → 開発者モード / カスタムMCPコネクタの作成で有効にします。

2. 設定 → コネクタ → 作成 / 詳細設定 → 開発者モード → カスタムコネクタを追加。

3. 以下の項目を入力します：

   • 名前: Visual MCP

   • MCPサーバーURL: https://<your-host>/mcp

   • 認証: 認証なし（このサーバーは認証なしで出荷されます — セキュリティを参照）

4. 保存します。ChatGPTは直ちに tools/list を呼び出します。10個のツールがリスト表示されるはずです。

5. 新しいチャットで、コネクタを有効にして図を依頼します。

サーバーはまた、MCP Apps UIリソース（ui://visual-mcp/scene.html、text/html;profile=mcp-app）を登録し、レンダリングツールに _meta.ui.resourceUri とChatGPTエイリアス _meta["openai/outputTemplate"] を通じて添付します。これがサポートされている場合、図はズーム、パン、フィット、コピー、エクスポート機能を備えたインタラクティブフレームに表示されます。サポートされていない場合でも、ツールは structuredContent 内にSVGを返すため、サーバーは優雅に機能を低下させます。

例

npm run examples は5つすべてを examples/out/index.html にレンダリングし、list_examples はそれらをモデルに提供します。

1. ネットワーク — examples/out/network.svg

ドメインプリセットと自動の左から右へのレイアウト。computer → switch → router → server、リンク上にVLANキャプション。ソースシーンに座標は一切ありません。

2. LDA — examples/out/lda.svg

axis データフレーム、2つのシードされたソフトハルを持つcluster、破線の決定境界、LDA方向 — すべてデータ座標で、両方の線はプロットにクリップされます。

3. 回帰 — examples/out/regression.svg

軸、scatter 系列、extend: true を指定したフィッティングされた plotLine。ライトテーマ。

4. ソフトウェアアーキテクチャ — examples/out/architecture.svg

React → REST API → { Redis, PostgreSQL }。2つのストアは、「Data layer」というラベルの付いた group 内にあり、接続はその中にルーティングされます。

5. 二分木 — examples/out/tree.svg

7つの円形ノードと6つの接続。down に流れる階層レイアウトが木を生成します。

ChatGPTで試すプロンプト

Draw the architecture where React talks to NestJS, NestJS uses PostgreSQL and also queries Redis.
Now put Redis above the backend and the database below it.
Now put all the infrastructure inside a box called AWS.
Make PostgreSQL bigger and give it a purple border.

Explain Linear Discriminant Analysis visually.
Show me graphically how linear regression works.
Draw a network where a PC in VLAN 20 reaches a server in VLAN 10 through a switch and a router.
Draw a balanced binary tree with 7 nodes.
Explain the TCP three-way handshake as a diagram.
Diagram merge sort on [5, 2, 9, 1].

セキュリティ

脅威モデルはシンプルです：サーバーがレンダリングするものはすべて言語モデルから発信され、その出力自体にユーザーが他の場所から貼り付けたテキストが含まれている可能性があります。そのため、モデル由来のものは決してコードとして扱われません。

• 閉じられたスキーマ。 既知の24の要素タイプのみが解析されます。色は hex/rgb/hsl/keyword/token の文法と一致する必要があります — url(javascript:…) は検証時に拒否されます。パスデータはSVGパスコマンドと数値のみと一致する必要があり、それ以外は許可されません。

• 許可リスト化された出力。 レンダラーは src/renderer/svgNode.ts 内の2つの明示的なリストからのタグと属性のみを出力できます。on*、href、style、class、<foreignObject>、<script> は存在しません — モデルはそれらを表現できず、シリアライザーはそれらを破棄します。

• エスケープ。 テキストコンテンツと属性値は、出力時にXMLエスケープされます。

• プロジェクト全体に dangerouslySetInnerHTML、eval、new Function は一切ありません。 Reactビューは SvgNode ツリーから要素を構築します。ChatGPTウィジェットはSVGを解析し、同じ許可リストに対してノードごとに再構築します。そのため、サーバーが侵害されたとしても、スクリプトがそのフレームに入り込むことはできません。

• 入力に制限あり。 要素数、文字列長、ポイント数、パス長、保存されたシーンはすべて上限があり、シーンは最も古いものから削除されます。

• モデルへのスタックトレースはなし。 すべてのハンドラーはラップされており、予期しないものはすべて短いメッセージと共に INTERNAL_ERROR になります。

tests/security.test.tsx のテストは、これらの各項目をアサートします。

設計上、含まれていません： 認証。このサーバーはシークレットを公開せず、外部システムに触れませんが、パブリックなデプロイメントは公開されたシーンストアです。自分自身以外に公開する前に、プラットフォームの認証の背後に配置するか、SDKの認証ヘルパーを介してOAuthを追加してください。ALLOWED_HOSTS を設定して、ブラウザから到達可能な場合にDNSリバインディング保護を有効にします。

現在の制限事項

• テキストメトリクスは推定値であり、測定値ではありません — サーバーにフォントエンジンはありません。バンドルされたサンセリフスタックの幅は数パーセントの誤差範囲内であり、ボックスと折り返しには十分ですが、珍しいフォントや多くのCJK文字ではサイズが多少ずれる可能性があります。

• レイアウトエンジンは意図的に小規模です。 最長パスレイヤリングとランクセンタリングを使用します。交差最小化やオーバーラップ解決はないため、密なグラフ（おおよそ25ノード以上で多くのクロスリンクがある場合）では、本格的なエンジンが回避する交差が発生します。インターフェースはまさにこの理由でDagreの形状をしています。

• ツリーレイアウトは子中心ではありません。 親はその子の中間点の上ではなく、そのランクの中心に配置されます。

• render_diagram のJSON Schemaは約50 KB（約12kトークン）です。 これは要素の語彙全体を教えるためです。他の9つのツールは合計で約5 KBです。これは意図的なトレードオフです。モデルはフィールドごとのドキュメントを取得し、修正のためのラウンドトリップがほとんど必要なくなります。

• 自動レイアウトのグループ内では、子の明示的な x/y は無視されます — レイアウトが優先されます。子を自分で配置するには、グループに layout: "manual" を使用します。

• ストレージはインメモリです。 シーンは再起動後も保持されず、複数のレプリカがある場合、シーンは它を作成したインスタンス上にのみ存在します。SceneStore インターフェースは、このクラスを置き換えるために存在します。

• 静的出力。 アニメーション、3D、数式パーサーはまだありません — 以下を参照してください。

ロードマップ

次

• 永続的な SceneStore（まずはSQLite） — インターフェースは既に整っています。

• 元に戻す/やり直す。すべての変更は既に SceneMutation として記録されています。これは逆の操作を保存する問題です。

• 密なグラフのための、src/layout/flow.ts の背後にあるDagreまたはELK。小規模エンジンをデフォルトとします。

• 子中心のツリーレイアウト。

数式 — axis データフレームが基礎です。これらはそれぞれ src/semantic/ 内の1つのエクスパンダーであり、レンダラーの変更はありません： functionPlot（{ "expression": "x^2", "domain": [-5, 5] }）、vector、matrix、plane、distribution、projection、decisionBoundary、regressionLine（plotLine の名前付きエイリアスとして）。

図の語彙 — neuron、neuralNetwork、decisionTree、sequenceDiagram、stateMachine、gantt、swimlane。

アニメーション — 接続上の { "animation": { "type": "flow", "duration": 1200 } }。SVG SMILまたはCSSとして出力されるため、宣言的であり、ランタイムを必要としません。リンクに沿って移動するパケット、パイプラインを通過するリクエスト、構造をステップ実行するアルゴリズムなど。

その他のレンダラー — 解決パイプラインは、すでにバックエンドに依存しないツリーで終了します。kind: "3d" と { "type": "sphere", "position": [0, 1, 0] } を持つ Scene は、SVGバックエンドの代わりにThree.jsバックエンドを選択します。Canvasバックエンドは非常に大きな散布図を提供します。MCPレイヤーへの変更はありません。

ライセンス

MIT