excalidraw-skill

Excalidraw スキル

ステップ 0：接続モードを判定する

作業を始める前に、利用可能なモードを確認してください。次のチェックを順番に実行します。

チェック 1：MCP サーバー（一番快適）

mcp-cli tools | grep excalidraw

excalidraw/batch_create_elements のようなツールが表示された場合 → MCP モードを使用します。MCP ツールを直接呼び出してください。

チェック 2：REST API（フォールバック — MCP サーバーなしで動作）

curl -s http://localhost:3000/health

{"status":"ok"} が返された場合 → REST API モードを使用します。チートシートに記載されている HTTP エンドポイント（curl / fetch）を使用してください。

チェック 3：どちらも動作しない場合 → インストール方法を案内する

どちらも動作しない場合は、ユーザーに次のように伝えてください。

Excalidraw キャンバスサーバーが起動していません。セットアップするには：

1. クローンします：git clone https://github.com/yctimlin/mcp_excalidraw && cd mcp_excalidraw
2. ビルドします：npm ci && npm run build
3. キャンバスを起動します：HOST=0.0.0.0 PORT=3000 npm run canvas
4. ブラウザーで http://localhost:3000 を開きます
5. （推奨）最高の操作性を得るために、MCP サーバーをインストールします：

   claude mcp add excalidraw -s user -e EXPRESS_SERVER_URL=http://localhost:3000 -- node /path/to/mcp_excalidraw/dist/index.js
   

MCP と REST API のクイックリファレンス

操作	MCP ツール	REST API の同等機能
要素を作成	batch_create_elements	{"elements": [...]} を指定して POST /api/elements/batch
すべての要素を取得	query_elements	GET /api/elements
1 つの要素を取得	get_element	GET /api/elements/:id
要素を更新	update_element	PUT /api/elements/:id
要素を削除	delete_element	DELETE /api/elements/:id
キャンバスをクリア	clear_canvas	DELETE /api/elements/clear
シーンを説明	describe_scene	GET /api/elements（手動で解析）
シーンをエクスポート	export_scene	GET /api/elements（ファイルに保存）
シーンをインポート	import_scene	{"elements": [...]} を指定して POST /api/elements/sync
スナップショットを作成	snapshot_scene	{"name": "..."} を指定して POST /api/snapshots
スナップショットを復元	restore_snapshot	GET /api/snapshots/:name の後に POST /api/elements/sync
スクリーンショット	get_canvas_screenshot	MCP 経由のみ（ブラウザーが必要）
デザインガイド	read_diagram_guide	利用不可 — ガイドラインはチートシートを参照
ビューポート	set_viewport	POST /api/viewport（ブラウザーが必要）
画像をエクスポート	export_to_image	POST /api/export/image（ブラウザーが必要）
URL をエクスポート	export_to_excalidraw_url	MCP 経由のみ

REST API の注意点（重要 — REST API を使う前に読む）

1. ラベル：「"text": "My Label"」（"text": "My Label" ではありません）ではなく、「"label": {"text": "My Label"}」を使用します。MCP ツールは自動変換しますが、REST API は変換しません。
2. 矢印のバインド：「"startElementId"／"endElementId"」ではなく、「"start": {"id": "svc-a"}, "end": {"id": "svc-b"}」を使用します。MCP ツールは startElementId を受け付けて変換しますが、REST API では start／end オブジェクト形式を直接指定する必要があります。
3. fontFamily：文字列（例：「"1"」）で指定するか、省略する必要があります。「1」のような数値は渡さないでください。
4. ラベルの更新：PUT /api/elements/:id で図形を更新する際は、ラベルを保持できるよう、更新本文に完全な label を含めます。更新から label を省略しても削除されませんが、再送信することで正しく描画されます。
5. REST モードでのスクリーンショット：POST /api/export/image は {"data": "<base64>"} を返します。ファイルに保存して、見た目を確認するために読み戻してください。ブラウザーを開いておく必要があります。

品質ゲート（必須 — 図を作成する前に読む）

反復のたびに（要素の各バッチを追加した後）、次に進む前に必ず品質チェックを実行してください。すべてのチェックに合格するまで、「見栄えが良い」と絶対に言わないでください。

品質チェックリスト — 要素を追加する前にすべて確認してください：

1. テキストの切れ：テキストはすべて完全に表示されていますか？ラベルは図形内に収めてください。テキストが切れている、または不自然に折り返されている場合は、width および／または height を大きくしてください。
2. 重なり：要素同士が重なっていませんか？長方形、楕円、テキスト要素が同じスペースを共有していないことを確認してください。背景ゾーンは、余白を確保したうえで子要素を完全に内包する必要があります。
3. 矢印の交差：矢印が無関係な要素の上を通ったり、テキストラベルと重なったりしていませんか？その場合は、障害物を避けるように経由点を指定し、曲線または折れ曲がった矢印を使用してください（「矢印の経路設定」セクションを参照）。矢印が交差したままにしないでください。
4. 矢印とテキストの重なり：矢印ラベル（「charge」、「event」など）が図形と重なっていませんか？矢印ラベルは中点に配置されます。重なる場合は、ラベルを削除するか、短くするか、矢印の経路を調整してください。
5. 間隔：要素間に 40px 以上の間隔がありますか？詰め込みすぎると読みづらくなります。
6. 読みやすさ：通常のズーム倍率ですべてのラベルを読めますか？本文のフォントサイズは 16 以上、タイトルは 20 以上にしてください。

問題が見つかった場合：

• 新しい要素の追加を中止する
• まず問題を修正する（サイズ変更、位置の調整、削除して再作成）
• 新しいスクリーンショットで再確認する
• すべてのチェックに合格してから、次の反復に進む

サイズ設定ルール（テキストの切れを防ぐ）：

• 図形の幅：max(160, labelTextLength * 9) ピクセル。複数語のラベル（「API Gateway (Kong)」など）は、すべての文字数を数えてください。
• 図形の高さ：1 行なら 60px、2 行なら 80px、3 行なら 100px。
• 背景ゾーン：内包する要素の周囲すべてに 50px の余白を設けてください。
• 要素間隔：階層間は垂直方向に 60px、同じ階層の要素間は水平方向に 40px の間隔を設けてください。
• サイドパネル：メイン図の要素から少なくとも 80px 離して配置してください。
• 矢印ラベル：ラベルは短く（1～2 語）してください。長い矢印ラベルは他の要素と重なります。

レイアウト計画（重なりを防ぐ）：

要素を作成する前に、まず紙の上で座標グリッドを計画してください。

• 第 1 階層（y=50-130）：クライアントアプリ
• 第 2 階層（y=200-280）：ゲートウェイ／エッジ
• 第 3 階層（y=350-440）：サービス（横方向に広く配置し、各サービス間を約 180px 離す）
• 第 4 階層（y=510-590）：データストア
• サイドパネル：x < 0（左側）または x > メイン図の右端 + 80（右側）

サイドパネル（オブザーバビリティ、外部 API など）をメイン図と同じ x 範囲に配置しないでください。必ず重なります。

クイックスタート

1. 接続モードを検出するため、上記のステップ 0を実行します。
2. キャンバスの URL をブラウザーで開きます（画像のエクスポート／スクリーンショットに必要です）。
3. MCP モード：すべての操作に MCP ツールを使用します。REST モード：チートシートの HTTP エンドポイントを使用します。
4. ツール／エンドポイントの詳細については、references/cheatsheet.mdをお読みください。

ワークフロー：図を描く

MCP モード

1. デザインのベストプラクティスを読み込むため、まず**read_diagram_guideを呼び出します**。
2. JSON を作成する前に、座標グリッドを計画します（「品質ゲート」→「レイアウト計画」を参照）。
3. 任意：新しく始める場合は、clear_canvasを実行します。
4. batch_create_elementsを使用して、図形と矢印を 1 回の呼び出しで作成します。
5. 図形にはカスタム idを割り当てます（例："id": "auth-svc"）。図形のラベルはtextフィールドに設定します。
6. テキストに合わせて図形のサイズを設定します — width: max(160, textLength * 9)を使用します。
7. startElementId／endElementIdを使用して矢印をバインドします — 矢印の経路は自動的に設定されます。
8. set_viewportでscrollToContent: trueを指定し、図に自動的に合わせます。
9. 品質チェックリストを実行します — get_canvas_screenshotを使用して厳しく評価します。次に進む前に問題を修正してください。

REST API モード

1. 設計ガイドラインについては、references/cheatsheet.md をお読みください。
2. JSON を作成する前に、座標グリッドを計画してください（「品質ゲート → レイアウト計画」を参照）。
3. 任意：curl -X DELETE http://localhost:3000/api/elements/clear
4. 1 回の呼び出しで要素を作成します（大きなペイロードには @file.json を使用します）。

   curl -X POST http://localhost:3000/api/elements/batch \
     -H "Content-Type: application/json" \
     -d '{"elements": [
       {"id": "svc-a", "type": "rectangle", "x": 0, "y": 0, "width": 160, "height": 60, "label": {"text": "Service A"}},
       {"id": "svc-b", "type": "rectangle", "x": 0, "y": 200, "width": 160, "height": 60, "label": {"text": "Service B"}},
       {"type": "arrow", "x": 0, "y": 0, "start": {"id": "svc-a"}, "end": {"id": "svc-b"}}
     ]}'
   

5. 図形のラベルには "label": {"text": "..."} を使用してください（"text": "..." ではありません）。
6. 矢印は "start": {"id": "..."} / "end": {"id": "..."} でバインドしてください。エッジはサーバーによって自動的にルーティングされます。
7. テキストに合わせて図形のサイズを調整してください。width: max(160, labelTextLength * 9) を使用します。
8. 品質チェックリストを実行します。スクリーンショットを撮って、厳しく評価してください。要素を追加する前に問題を修正します。

矢印のバインド（推奨）

自動ルーティングされるエッジにするには、矢印を図形にバインドします。形式は MCP と REST API で異なります。

MCP モード — startElementId / endElementId を使用します。

{"elements": [
  {"id": "svc-a", "type": "rectangle", "x": 0, "y": 0, "width": 120, "height": 60, "text": "Service A"},
  {"id": "svc-b", "type": "rectangle", "x": 0, "y": 200, "width": 120, "height": 60, "text": "Service B"},
  {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-a", "endElementId": "svc-b", "text": "calls"}
]}

REST API モード — start: {id} / end: {id} および label: {text} を使用します。

{"elements": [
  {"id": "svc-a", "type": "rectangle", "x": 0, "y": 0, "width": 120, "height": 60, "label": {"text": "Service A"}},
  {"id": "svc-b", "type": "rectangle", "x": 0, "y": 200, "width": 120, "height": 60, "label": {"text": "Service B"}},
  {"type": "arrow", "x": 0, "y": 0, "start": {"id": "svc-a"}, "end": {"id": "svc-b"}, "label": {"text": "calls"}}
]}

バインドされていない矢印では、手動の x、y、points 座標を使用します。

矢印のルーティング — 重なりを避ける（複雑な図では特に重要）

直線の矢印（2 点）は、複雑な図では交差や重なりの原因になります。代わりに、曲線またはエルボー型の矢印を使用してください。

オプション 1：曲線の矢印 — 中間ウェイポイントと roundness を追加します。

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": {"type": 2},
  "strokeColor": "#1971c2"
}

ウェイポイント [50, -40] は矢印を上方向に押し上げ、要素の上を通るようにします。roundness: {type: 2} にすると、滑らかな曲線になります。

オプション 2：エルボー型の矢印 — 直角にルーティングします（L 字型または Z 字型）。

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true,
  "strokeColor": "#1971c2"
}

使い分け：

• 分岐する矢印（1 つのソース → 複数のターゲット）：互いに重ならないよう、ウェイポイントを縦方向に分散した曲線の矢印を使用します。
• レーン間の矢印（サイドパネルへの接続）：メインの図を迂回するエルボー型の矢印を使用します。まず上へ、次に横へ、最後に下へ進むようにします。
• サービス間の矢印（水平方向の接続）：隣接する要素を通過しないよう、わずかな垂直オフセットを付けた曲線の矢印を使用します。

目安： 矢印が無関係な要素を通過する場合は、ウェイポイントを追加して迂回させます。矢印の交差は決して許容せず、必ず修正してください。

ワークフロー：反復的な調整（主な差別化要素）

このフィードバックループが、このスキル独自の特徴です。各反復では、必ず品質チェックを行ってください。

MCP モード（完全なフィードバックループ）

1. 要素を追加します（batch_create_elements、create_element）。
2. scrollToContent: true を指定して set_viewport を実行します。
3. get_canvas_screenshot を実行し、品質チェックリストに照らして厳しく評価します。
4. 問題が見つかった場合 → 修正します（update_element、delete_element、サイズ変更、位置変更）。
5. 再度 get_canvas_screenshot を実行し、修正を再確認します。
6. すべての品質チェックに合格した場合のみ、次の反復に進みます。

REST API モード（部分的なフィードバックループ）

1. POST /api/elements/batch で要素を追加します。
2. {"scrollToContent": true} を指定して POST /api/viewport を実行します。
3. スクリーンショットを撮ります。POST /api/export/image を実行して PNG として保存し、品質チェックリストに照らして厳しく評価します。
4. 問題が見つかった場合 → PUT /api/elements/:id で修正するか、削除して作り直します。
5. 再度スクリーンショットを撮り、修正を再確認します。
6. すべての品質チェックに合格した場合のみ、次の反復に進みます。

スクリーンショットを厳しく評価する方法：

• すべてのラベルを確認します。テキストが切れていたり、コンテナーからはみ出したりしていませんか？
• すべての矢印を確認します。無関係な要素を通過する矢印はありませんか？
• すべての要素の組み合わせを確認します。重なったり、接触したりしていませんか？
• 間隔を確認します。何かが詰め込まれていませんか？
• 正直に評価してください。 問題が少しでもあれば、「[問題] が見つかりました。修正します」と伝え、「素晴らしいです」とは言わないでください。

例（MCP）：

batch_create_elements → get_canvas_screenshot → "text truncated on 2 shapes"
→ update_element (increase widths) → get_canvas_screenshot → "overlap between X and Y"
→ update_element (reposition) → get_canvas_screenshot → "all checks pass"
→ proceed to next iteration

ワークフロー：既存の図を調整する

1. describe_scene を実行して、現在の状態を把握します。
2. ID、種類、またはラベルテキストで対象を特定します（x/y 座標ではありません）。
3. 移動、サイズ変更、色変更には update_element を、削除には delete_element を使用します。
4. get_canvas_screenshot を実行して、変更を視覚的に確認します。
5. 更新に失敗した場合：要素 ID が存在すること（get_element）と、要素がロックされていないこと（unlock_elements）を確認します。

ワークフロー：ファイル入出力（コードとしての図）

• .excalidraw 形式でエクスポート：export_scene に任意の filePath を指定します。
• .excalidraw からインポート：mode: "replace" または "merge" を指定して import_scene を実行します。
• 画像にエクスポート：format: "png" または "svg" を指定して export_to_image を実行します（ブラウザーを開いておく必要があります）。
• CLI でエクスポート：node scripts/export-elements.cjs --out diagram.elements.json
• CLI でインポート：node scripts/import-elements.cjs --in diagram.elements.json --mode batch|sync

ワークフロー：スナップショット（キャンバスの状態を保存／復元）

1. 変更を加える前に、名前を指定して snapshot_scene を実行します。
2. 変更を加え、describe_scene／get_canvas_screenshot で確認します。
3. 必要に応じて restore_snapshot でロールバックします。

ワークフロー：複製

• elementIds と任意の offsetX／offsetY を指定して duplicate_elements を実行します（デフォルトは 20,20 です）。
• 繰り返しパターンの作成や、既存のレイアウトのコピーに便利です。

矢印／線の points 形式

points フィールドは、次の両方の形式に対応しています。

• タプル：[[0, 0], [100, 50]]
• オブジェクト：[{"x": 0, "y": 0}, {"x": 100, "y": 50}]

どちらも自動的にタプル形式に正規化されます。

ワークフロー：図を共有する（excalidraw.com URL）

1. 上記のいずれかのワークフローを使って図を作成します。
2. export_to_excalidraw_url を実行すると、暗号化されたシーンがアップロードされ、共有可能な URL が返されます。
3. URL を共有すると、誰でも excalidraw.com で開いて表示・編集できます。

ワークフロー：ビューポートの制御

• scrollToContent: true を指定して set_viewport を実行すると、すべての要素に合わせて自動調整されます（全体表示）。
• scrollToElementId: "my-element" を指定して set_viewport を実行すると、特定の要素が画面の中央に表示されます。
• zoom: 1.5, offsetX: 100, offsetY: 200 を指定して set_viewport を実行すると、カメラを手動で制御できます。

参考資料

• references/cheatsheet.md：MCP ツール一覧（26 個）、REST API エンドポイント、ペイロードの形式を網羅しています。

関連スキル

• こちらもご覧ください：figure-generation、algorithm-design、slide-generation