codex-tldraw-mcp

codex-tldraw-mcp

編集可能なリポジトリ内の tldraw 図、ポータブルな SVG プレビュー、ドリフト検出機能付きの追跡可能なコードグラフを生成する、stdio MCP サーバーです。

クイックスタート

Codex にサーバーを追加します。

codex mcp add codex-tldraw -- npx -y codex-tldraw-mcp

次に、Codex に現在のリポジトリの図を作成するよう依頼します。

Use codex-tldraw to diagram this repo.

実行時のアーキテクチャをリバースエンジニアリングします。

Use codex-tldraw to show how this repo works across its main components.
Show the main flow first, keep short errors inside components, and label each interaction once.

または、図を直接作成するよう依頼します。

Use codex-tldraw to draw a password reset state machine.

追跡可能な JavaScript または TypeScript のモジュールグラフを作成します。

Use codex-tldraw to create a code graph for this repo.

コードを変更した後、保存したグラフと比較します。

Use codex-tldraw to preview code graph drift, then mark stale elements.

デフォルトの出力先は次のとおりです。

<repo>/boards/main.tldr
<repo>/boards/main.svg

.tldr ボードを tldraw 対応ビューアーで開いて編集します。任意の MCP ホスト、ブラウザー、ドキュメントシステム、コードレビューで .svg プレビューを直接表示できます。

プラグインの修正と検証の詳細については、v0.7.1 リリースノートを参照してください。

Codex プラグイン

このリポジトリでは、サーバーを Codex プラグインとしてもパッケージ化しています。既存の MCP ツールは引き続き .tldr ファイルと .svg ファイルを書き込みます。プラグインは .tldr ファイルハンドラーを追加し、埋め込みの React/tldraw アプリで編集可能なボードを開きます。

同じエディターを開く方法は 2 つあります。

図ツールパネル — draw_canvas、diagram_repo などのツールを実行すると、インライン MCP App がリポジトリスコープのサーバーリソース tldraw://repos/<encoded-repo-path>/boards/<name>/file からボードを読み込み、アプリ専用の save_board ツールで保存します。

.tldr ファイルのエントリーポイント — Codex がリポジトリのファイルを直接開くと、アプリはホストのファイルリソース API（open_tldraw_file）を使用します。書き込み可能なファイルは ETag による競合保護付きで保存されます。

サーバーと単一ファイルのアプリをビルドします。

bun install
bun run build

公開済みのプラグインを npm からインストールします（推奨）。

npm install -g codex-tldraw-mcp
codex plugin marketplace add "$(npm root -g)/codex-tldraw-mcp"
codex plugin add codex-tldraw@codex-tldraw-mcp

または、GitHub からインストールします。

codex plugin marketplace add jananadiw/codex-tldraw-mcp
codex plugin add codex-tldraw@codex-tldraw-mcp

このプラグインには Node.js 20.11 以降と、PATH 上の npm が必要です。GitHub からプラグインをダウンロードしても、ソースのビルドや依存関係のインストールは行われません。ランチャーは、ビルド済みのローカルコピーがあればそれを使用し、なければ対応する公開済み npm バージョンを npx 経由で実行します。初回のフォールバック起動にはレジストリへのアクセスが必要です。プラグインの使用に Bun のインストールは不要です。

このチェックアウトから開発する場合は、次の手順に従います。

bun run build
codex plugin marketplace add .
codex plugin add codex-tldraw@codex-tldraw-mcp

マーケットプレイスの記述ファイルは .agents/plugins/marketplace.json、プラグインマニフェストは .codex-plugin/plugin.json、MCP 設定は .mcp.json、バンドルされたアプリは dist/app.html です。アプリに対応していない MCP ホストでは、既存のテキスト結果、.tldr リソース、SVG プレビューを引き続き使用できます。

得られるもの

• 説明対象のプロジェクト内に保存されるリポジトリ内 .tldr ボードと、ポータブルな .svg プレビュー。
• パッケージのメタデータとソーステキストから推測される、ユーザー向け製品のワークフロー。
• リポジトリのスキャンに依存しない、ワークフロー、状態マシン、計画、アーキテクチャのスケッチを描画するための、プロンプト駆動のオフラインキャンバス API。
• まず主要なフローを示し、その下に関連サービスを配置するシンプルなアーキテクチャ図。
• ドリフト検出機能を備えた、追跡可能な JavaScript および TypeScript のモジュール／インポートグラフ。
• 古くなったノードとエッジを示す赤いマーカー、変更されたモジュールを示すオレンジのマーカー、および新しい要素のレポート。
• 左から右へ配置された tldraw のステップと矢印。
• 既存のボードを破壊しない更新。既存のボードには、次の図が右側に追加されます。
• ボードの一覧表示と概要の読み取りに使える MCP リソース。

手書きフォントアプリの場合、ワークフローは次のように推測されることがあります。

User writes alphabet on paper -> User takes a photo of the paper -> User uploads the image -> AI generates a font -> User downloads a .ttf file

手動設定

Codex の MCP 設定を直接編集する場合は、次の手順に従います。

[mcp_servers.codex-tldraw]
command = "npx"
args = ["-y", "codex-tldraw-mcp"]

ツール

• diagram_repo：リポジトリをスキャンし、製品のワークフロー図を<repo>/boards/<boardName>.tldrに追加します。
• draw_canvas：プロンプトで指定されたワークフロー、状態マシン、アーキテクチャの概略図、または計画を<repo>/boards/<boardName>.tldrに追加します。
• draw_architecture：メインフロー、サポートコンポーネント、アクション、呼び出し、エラーを含む、シンプルなコードベースのアーキテクチャ図を追加します。
• diagram_code_graph：リポジトリ内のJavaScriptおよびTypeScriptモジュールをスキャンし、追跡可能なインポートグラフを追加します。
• compare_code_graph：既存の追跡可能なコードグラフの差異をプレビューするか、変更された要素や古くなった要素をマークします。
• list_boards：リポジトリのboards/ディレクトリ内のボードを一覧表示します。
• read_board_summary：生成された図とシェイプの数を要約し、両方の成果物のパスを返します。

プラグインを使用する際は、リポジトリ関連のツールを呼び出すたびに、リポジトリの絶対パスをrepoPathとして渡してください。プラグインはチャットのワークスペースではなく、インストール先のディレクトリから実行されます。図がプラグインのキャッシュに書き込まれるのを防ぐため、パスがない場合や相対パスの場合は拒否されます。リモートリポジトリのURLを使う場合は、先にローカルにクローンしてから、チェックアウト先のパスを使用してください。

単独で使用するMCPツールでは、repoPathは省略可能です。相対パスは、MCP サーバーの作業ディレクトリを基準に解決されます。

図を書き込む各ツールは、両方の成果物を保存し、構造化出力でboardPathとsvgPathを返します。ツールのコンテンツには、編集可能なボードとSVGプレビューへのMCPリソースリンクも含まれます。SVGレンダラーは、このサーバーが生成するテキスト、四角形、矢印のシェイプに対応しており、ブラウザーのランタイムは不要です。

新しいボードのリソースリンクには、エンコードされたリポジトリの絶対パスが含まれます。サーバーを再起動した後や、別のリポジトリに対してツールを呼び出した後も、両方のリポジトリで同じボード名を使用している場合を含め、リンクは引き続き機能します。リソースの読み取り時には、引き続きTLDRAW_MCP_ALLOWED_ROOTSが適用されます。

従来のtldraw://boards/<name>/...リソースも、以前の単独クライアント向けに引き続き利用できます。これらは最後に選択されたリポジトリを使用します。図ツールを再実行すると、古いエディターリンクがリポジトリ別のリンクに置き換わります。

エディターは保存前に読み込み済みボードのETagを確認し、古い内容の保存をブロックします。競合が発生した場合は、変更を破棄して再読み込みを選択できます。無効なボードデータは、ファイルを置き換える前に拒否されます。図の書き込みにはボードごとのファイルシステムロックを使用するため、異なるサーバープロセスから同時に呼び出しても、両方の追記内容が保持されます。

コードグラフのドリフト

diagram_code_graph は、MCP が管理する図形メタデータに、リポジトリ内で変わらない相対パスの識別子とフィンガープリントを保存します。各ソースモジュールがノードになります。リポジトリ内のモジュール間にある静的インポート、動的インポート、再エクスポート、CommonJS の require 呼び出しはエッジになります。

リポジトリに変更を加えたら、compare_code_graph を実行してください。デフォルトはプレビューモードで、ボードへの書き込みは行いません。

Compare the current code with the newest code graph on boards/main.tldr.

ボードを更新するには、Codex にドリフトマーカーの適用を依頼するか、applyMarkers: true を渡してください。比較では次の 4 つの状態を使用します。

• unchanged：保存された識別子とフィンガープリントが引き続き一致しています。
• changed：モジュールは引き続き存在しますが、エクスポートまたはローカルのインポート関係が変化しています。
• stale：現在のコードグラフには存在しない要素がボードに含まれています。
• new：現在のコードグラフには、ボードに存在しない要素が含まれています。

古くなった要素は赤色の破線になります。変更されたモジュールはオレンジ色の破線になります。新しい要素はツールの結果に表示されます。v0.4.0 では、新しい要素の挿入や配置変更は行いません。コードが再び一致すると、比較を再実行することで元の生成スタイルに戻ります。

比較によって変更されるのは、MCP が生成したグラフのスタイルとメタデータのみです。位置、サイズ、ラベル、手動で作成した図形、ボード上のほかの図はそのまま保持され、ドリフトが解消されると各要素の元の色に戻ります。diagram_repo、draw_canvas、または旧バージョンで作成されたボードには、追跡可能なコードグラフのメタデータが含まれていません。ドリフトを比較する前に、diagram_code_graph でグラフを作成してください。

v0.4.0 のスキャナーは、.js、.jsx、.mjs、.cjs、.ts、.tsx、.mts、.cts の各モジュールに対応しています。解決できない相対インポートを報告し、外部パッケージは描画せずに外部インポート数を集計します。モデル化するのはモジュールとインポートの関係であり、実行時の呼び出しグラフではありません。

プロンプト駆動の図

draw_canvas はソースファイルをスキャンしません。生成されたボードの保存場所として、現在のリポジトリのみを使用します。

プロンプトの例：

Use codex-tldraw to draw the auth flow:
Visitor opens login -> chooses email or SSO -> completes MFA -> lands in dashboard.

Use codex-tldraw to make a state machine for password reset:
Idle -> Reset requested -> Email sent -> Token verified -> Password updated.

Use codex-tldraw to append an architecture diagram for this plan:
Web app calls API gateway, API gateway calls worker queue, worker writes generated files to object storage.

シンプルなアーキテクチャ

draw_architecture は、コードベース内で処理がどのように進むのかを、新しい読者が理解するのに役立ちます。Codex がまずコードを調査し、その後、簡潔なモデルをレンダラーに送ります。

• メインのユーザーフローは、ボックスを横一列に並べて表します。
• 補助サービスは、それを呼び出すコンポーネントの下に配置します。
• 各コンポーネントに表示する重要なアクションは最大 3 つ、短いエラーは最大 2 つです。
• 各やり取りには簡潔な矢印を 1 つ付け、リクエストとレスポンスを同じ矢印で表します。
• ソースの根拠は任意のメタデータであり、図を煩雑にしません。

ライブラリやヘルパーモジュールは、コンポーネントのアクション内に含めてください。たとえば、「Zod でレスポンスを検証する」は、独立した Zod コンポーネントにするのではなく、API コンポーネント内に記述します。意味のある矢印は、両端の図形にバインドされています。

分析の仕様と入力モデルについては、アーキテクチャ図を参照してください。

フィードバック

このプロジェクトはまだ初期段階にあるため、フィードバックを歓迎します。以下に該当する場合は、Issue を作成してください。

• 生成されたワークフローが、実際の製品フローを捉えていない。
• tldraw 互換ビューアーでボードを開けない。
• コードグラフのドリフト検出で、モジュールまたはインポートの関係が誤って報告される。
• PM とエンジニアがよりわかりやすい共通のマップを必要とする、複雑なリポジトリがある。

バグ、機能リクエスト、実際の使用例については、GitHub の Issue テンプレートを使用してください。

このプロジェクトの目的

このプロジェクトはスナップショット専用です。ライブブラウザーのキャンバスを操作したり、リアルタイムの共同作業を提供したりすることはありません。図示対象のリポジトリにボードファイルを書き込み、後から tldraw 互換ビューアーで開けるようにします。

公式の tldraw MCP App は、チャットのコンテキスト内にインタラクティブな tldraw キャンバスをレンダリングできるホスト向けに設計されています。テストでは、Codex Desktop でツールの検出に成功し、tldraw の search ツールから Editor API の詳細、図形の種類、ヘルパーが返されました。ライブの exec 経路は動作せず、現在のページにある図形の数を数える読み取り専用の呼び出しも含め、すべての呼び出しが 30 秒後にタイムアウトしました。

この失敗を受けて、当初はファイルベースの代替手段を用意しました。v0.7.0 プラグインには、独自の組み込み MCP App エディターが含まれるようになりました。また、生成される SVG プレビューは、App に対応していないホストでも引き続き利用できます。

このサーバーは、当初 Codex 向けの代替手段として開発されました。ライブキャンバスを操作するのではなく、通常の stdio MCP ツール呼び出しを通じて、ディスク上に .tldr スナップショットを生成します。stdio トランスポートと SVG プレビューにより、同じ出力をあらゆる MCP 対応ホストで利用できるようになりました。なお、ドキュメントで主に説明しているセットアップは引き続き Codex 向けです。

セキュリティ

これはローカルファイルシステム用のツールです。repoPath からソースファイルを読み取り、repoPath/boards の下に .tldr ファイルと .svg ファイルを書き込みます。

アクセスを特定のディレクトリに制限するには、パス区切り文字で区切った許可リストを TLDRAW_MCP_ALLOWED_ROOTS に設定します。

[mcp_servers.codex-tldraw]
command = "npx"
args = ["-y", "codex-tldraw-mcp"]
env = { TLDRAW_MCP_ALLOWED_ROOTS = "/Users/me/dev:/Users/me/work" }

許可リストを設定した場合、repoPath は許可されたルートのいずれかに解決される必要があります。

生成される .tldr ファイルの図形メタデータには、ローカルリポジトリの絶対パスは保存されません。追跡可能なコードグラフには、リポジトリからの相対パスでソースパスが保存されます。

ローカルでの開発

このリポジトリでは、開発に Bun を使用します。

bun install
bun run build
bun run smoke

ソースからサーバーを実行します。

bun run dev

Codex でローカルビルドを使用します。

[mcp_servers.codex-tldraw]
command = "node"
args = ["/absolute/path/to/codex-tldraw-mcp/dist/index.js"]

公開

パッケージのビルド、テスト、内容の確認を行います。

bun install --frozen-lockfile
bun run build
bun run smoke
bun run check:package
bun run check:plugin

GitHub Release が公開されると、.github/workflows/publish-npm.yml によって公開処理が実行されます。npm の信頼済みパブリッシャーでは、jananadiw/codex-tldraw-mcp とワークフロー publish-npm.yml を許可し、GitHub 環境を指定せずに公開アクションを有効にする必要があります。このワークフローでは GitHub OIDC を使用し、npm トークンは必要ありません。

ワークフローの dry_run ディスパッチオプションを使用すると、公開せずにリリースを検証できます。

このパッケージには MCP Registry のメタデータが含まれています。

• package.json で mcpName を宣言します。
• server.json で npm の stdio パッケージについて説明します。

ワークフローによる公開が完了し、npm パッケージのバージョンが利用可能になったら、認証して Registry のメタデータを公開します。

mcp-publisher login github
mcp-publisher publish

Registry のエントリーを確認します。

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jananadiw/codex-tldraw-mcp"