Diagrams MCP Server

diagrams-mcp-server

テクニカルプレビュー（V1 プレビュー、v0.7.0） — PlantUML および Mermaid の図を管理、レンダリング、共有し、コードベースとの整合性を確認して、コードから新しい図を作成できるローカルファーストの MCP サーバーです。

AI コーディングエージェントが、プロジェクトの PlantUML および Mermaid のアーキテクチャ図に構造化された形でアクセスできるようにする MCP（Model Context Protocol）サーバーです。図の一覧表示、読み取り、作成、更新、削除、レンダリングとエクスポート、コードベースとの整合性確認、2 つのバージョンの差分確認、コードまたはひな形からの新しい図の作成ができます。すべてローカルで動作し、明示的にオプトインしない限り、アカウントもネットワーク呼び出しも必要ありません。

stdio 経由で あらゆる MCP 対応クライアント と連携できます。Claude Code、Codex（Desktop および CLI）、Antigravity（IDE、2.0 および CLI）、OpenCode（Desktop および CLI）、Cursor、VS Code に対応しています。詳しくは、以下の クライアントのセットアップ をご覧ください。

開発の背景

ソフトウェア設計に AI を活用しているとき、同じ問題に何度も直面したことがきっかけで開発しました。図はある場所に、コードは別の場所にあり、会話にコンテキストを貼り付ける必要がありました。何度かやり取りするうちに、図が今もプロジェクトを正しく表しているのか判断しづらくなりました。図をプロジェクト内に保管し、エージェントが読み取って、必要に応じてコードと照合できる、小さなローカル MCP サーバーが欲しかったのです。

diagrams-mcp-server は、エージェントが同じワークフロー内で図を読み取り、照合できるよう、コードの隣にあるプロジェクト内で図を管理します。標準の stdio MCP トランスポートを使用し、クライアント固有のサーバーコードは必要ありません。

機能

4 つのグループに分かれた 12 個のツールを提供します。読み取り専用の作図ツール（diagrams_generate、diagrams_generate_sequence、diagrams_template、diagrams_export）はファイルに書き込みません。ソーステキストを返すため、diagrams_create を使って自分で保存してください。

図の管理

ツール	機能
diagrams_list	プロジェクト内のすべての PlantUML/Mermaid 図を、抽出したタイトルと明示的な offset／limit によるページネーション付きで一覧表示します
diagrams_get	図のソースをすべて、または明示的な offset／max_chars の範囲で読み取ります
diagrams_create	新しい図ファイルを作成します（上書きは拒否されます）
diagrams_update	既存の図の内容を置き換えます
diagrams_delete	図を削除します（明示的に実行され、destructiveHint としてマークされています）

レンダリングと共有

ツール	機能
diagrams_render	図を SVG/PNG にレンダリングします
diagrams_export	保存済みの図とレンダリングした SVG を、自己完結型の 1 つの HTML ファイルにまとめます — 完全にオフラインで動作し、外部リソースは使用せず、ディスクにも何も書き込みません

確認と比較

ツール	機能
diagrams_check_consistency	図内のクラス／インターフェース／コンポーネント名を実際のコードベースと比較し、古くなっている可能性がある項目を指摘します
diagrams_diff	2 つの図のソースを比較します。保存済みファイル同士、または保存済みファイルとインラインテキストを比較し、追加、削除、名前変更されたエンティティ名を報告します

新しい図を下書きする

ツール	機能
diagrams_generate	コードベースの一部からPlantUMLまたはMermaidのクラス図を下書きします。確認後、diagrams_createで保存できるソーステキストを返します
diagrams_generate_sequence	コードベースの一部におけるメッセージ呼び出しパターンからPlantUMLまたはMermaidのシーケンス図を下書きします。確認後、diagrams_createで保存できるソーステキストを返します
diagrams_template	PlantUMLまたはMermaidで、最小限かつ常に有効なひな形（クラス図、シーケンス図、またはC4コンテキスト図）を生成します。エンティティごとに宣言を1つだけ含み、推測や書き込みは行いません

ツールに関する補足

diagrams_check_consistency エンティティ名は、class／interface／enum／component宣言、エイリアス、名前空間、パッケージ、シーケンスの参加者、charge(card)などのメッセージ呼び出し、C4ブロック、サブグラフのグループ化から読み取られます。その後、JavaScript／TypeScript、Python、PHP、Javaには宣言パターンを使い、それ以外では単語全体の一致を使って、ソースファイルから該当する識別子を検索します。名前が変更または削除されたクラスや、未実装のコンポーネントなど、よくある不整合の検出に役立ちます。構造化出力には、抽出・一致・不一致のエンティティ、エンティティごとのファイル内の根拠、解析器の階層、明示的なヒューリスティック信頼度の警告が含まれます。スキャンの上限については、整合性スキャンの上限を参照してください。

diagrams_generate

diagrams_generateは、このチェックとは逆に図を生成します。プロジェクトルート配下のファイルまたはディレクトリから同じ宣言を読み取り、クラス図を下書きします。宣言された名前ごとに1つのボックスを作成し、TypeScriptコンパイラーで根拠を確認できる場合はextends／implementsのエッジも追加します。読み取り専用で、書き込みは一切行いません。ソーステキストは応答として返され、明示的にdiagrams_createを呼び出して保存するまでは、diagrams/に何も書き込まれません。これはヒューリスティックな処理（完全な型モデリングではなく、名前の抽出）です。メンバー一覧、ジェネリクス、名前空間のネスト、再エクスポートを介したファイル間の継承は対象外です。また、対象範囲にTypeScript系のファイルがない場合は、関連のないエンティティが返され、その理由を示すdialect_noteが含まれます。すべての結果にはconfidence: "heuristic"とheuristic_warningが付与され、上限に達した場合は必ず出力内で報告されます（entities_capped／entities_available／relations_capped／truncated）。そのため、上限で切り詰められた下書きが完全なものと誤認されることはありません。生成の上限については、生成の上限を参照してください。

diagrams_generate_sequence

diagrams_generate_sequenceは、図のもう半分を下書きします。ボックスではなく、エンティティ間の会話です。プロジェクトルート配下のファイルまたはディレクトリからメッセージ呼び出しパターンを読み取ります。スキャンしたファイルごとに参加者を1つ設定し、モジュール名で示します。そして、整合性チェッカーの呼び出しグラフがすでに抽出した呼び出し元から呼び出し先へのエッジをもとに、順序付きのfrom -> to : message行を出力します。静的な呼び出し箇所の順序は実行時の順序ではありません。結果には必ずその旨が示されます。コールバック、Promise、リスナー内の呼び出しはdeferred_countに含められ、会話内の実際の位置はソースから特定できないため、メッセージから除外されます。参加者の対応付けには、宣言された識別子との完全一致のみを使います。対象範囲内のどのファイルにも宣言されていない呼び出し先は、架空の参加者に割り当てず、unresolved_calleesに記載されます。どのクラスがメソッドを所有するかは型に関する問題であり、対象外のためです。diagrams_generateと同様に、読み取り専用で書き込みは一切行いません。明示的にdiagrams_createを呼び出して保存するまでは、diagrams/に何も書き込まれません。また、すべての結果にconfidence: "heuristic"とheuristic_warningが付与され、上限に達した場合は必ず出力内で報告されます（participants_capped／messages_capped／*_available／*_limit／truncated）。シーケンス図の上限については、シーケンス図の上限を参照してください。

diagrams_diff

diagrams_diff は、編集後のレビュー時に生じる「同じ図の2つのバージョンで何が変わったのか？」という問いに答えます。それぞれの側では、保存済みのパスかインラインテキストのどちらか一方だけを指定するため、ステージングされていない編集も、いったん保存せずに比較できます。また、両側で異なる方言を使用することもでき、それぞれ独自の構文で読み込まれます。added／removed／renamed のエンティティ名、unchanged リスト、およびシーケンス図側の participants_*／calls_* フィールドを報告します（クラス図では、これらのフィールドは常に [] であり、省略されません）。名前変更の検出では、区切り文字を取り除いて小文字にしたときに一致する場合に限り、削除された名前と追加された名前を組み合わせます。これは、整合性チェッカーがコードとの名前照合に使用するものと同じ共通ノーマライザーです。そのため、表記が異なる実際の名前変更は、単純な追加と削除として扱われ、各ペアには confidence: "heuristic" が付与されます。比較対象は宣言された名前のみです。メンバーリスト、レイアウト、スタイルは対象外で、パッチやマージは行わず、変更を報告するだけです。編集はご自身で行ってください。他の読み取り専用ツールと同様、ディスク上のファイルには一切触れません。不正なリクエストは、ファイルを読み込む前に拒否されます。

diagrams_template

diagrams_template は、他のすべてに先立つ白紙状態から始めるためのツールです。「種類、方言、エンティティ名を渡せば、すべての構文チェックをすでに通過する最小限のスケルトンが返されます。」定型コードには、@startuml／@enduml の境界や誤った開始キーワードがリポジトリに入り込む原因があります。そのため、上限を設けた決定論的な出力生成器で、この失敗の可能性をなくします。6種類のスケルトン（クラス図、シーケンス図、C4 コンテキスト図 × PlantUML、Mermaid）はソース内の固定テーブルで定義され、同じ入力からは、どのプロセスでもバイト単位で同一のソースが生成されます。これは純粋な処理であり、ファイルシステム、コードのスキャン、ヒューリスティック、状態は使用しません。そのため、diagrams_generate とは異なり、confidence フィールドはなく、不確実な要素もありません。各エンティティにつき宣言行を1行出力し、図を拡張する場所を示す TODO ヒントを添えるだけで、それ以上は何も出力しません。メンバーの本体、関係、スタイルは、保存後にご自身で記述してください。PlantUML の C4 コンテキストスケルトンは、プレーンな四角形を使って単独で動作します。実際の C4 形状には C4-PlantUML の標準ライブラリが必要ですが、このローカル優先サーバーはそれを取得しないためです。Mermaid のスケルトンでは、ネイティブの C4Context を使用します。ファイルに書き込まれることはありません。ソースはレスポンスで返され、明示的に diagrams_create を呼び出して保存するまで、diagrams/ には何も作成されません。テンプレートの上限はテンプレートの上限に記載されています。

diagrams_export

diagrams_export は共有用のツールであり、保存済みの図とレンダリング済み SVG を、どこでも（リポジトリ内外を問わず）開ける自己完結型の HTML ファイル1つにまとめて、一連の作業を締めくくります。これは、サーバーがすでに生成している2つの成果物、つまり保存済みソースとローカルでレンダリングされた SVG をパッケージ化するものです。そのため、新たな依存関係は追加されず（HTML は文字列の連結で生成されます）、書き込み先も増えません。ツールがファイルを書き込むことはなく、HTML はテキストとして返され、保存先はご自身で決められます。この成果物には外部要素が一切含まれません。src／href URL、@import、スクリプト、ウェブフォントはなく、スタイル設定にはインラインスタイルのみを使用します。また、SVG は base64 画像ではなく、ライブマークアップとしてインライン化されるため、選択可能な状態が保たれ、厳格なコンテンツセキュリティポリシーでも利用できます。ドキュメント内のパスは、図の POSIX relative_path のみです。include_source（デフォルト）を指定すると、JavaScript を必要としないネイティブの <details> 要素を使った折りたたみ可能なブロックにソースが埋め込まれます。ファイルをより軽量にするには、これを false に設定してください。レンダリングは、CLI の要件とオプトインのリモートフォールバックを含め、diagrams_render と完全に同じ動作です。rendered_with は、画像の生成に使用された方法（local-plantuml／remote-plantuml／mmdc）を示します。バイト数の上限を超えるバンドルは、切り詰めずに拒否されます。不完全にレンダリングされた成果物は、何もないよりも悪いため、truncated は常に false です。エクスポートの上限はエクスポートの上限に記載されています。

ページネーションとソースウィンドウ

ページネーションは明示的に指定するオプトイン方式です。サーバーが独自にページ分割や切り詰めを行うことはありません。

diagrams_list では、省略可能な offset（0 以上の整数、デフォルトは 0）と limit（1～500 の整数）を指定できます。どちらも省略すると、一致するすべての項目が返されます。レスポンスには常に count（このページの項目数）、total（ページ分割前の一致数）、有効な offset／limit、has_more（このページの後に項目が残っているかどうか）が含まれます。末尾を超える offset を指定すると、エラーではなく has_more: false の空のページが返されます。例：まず diagrams_list({ "type_filter": "all", "limit": 10 }) を実行し、has_more が true の場合は diagrams_list({ "type_filter": "all", "offset": 10, "limit": 10 }) を実行します。

diagrams_get では、省略可能な offset（0 起点の文字オフセット、デフォルトは 0）と max_chars（1～100000 の整数）を指定できます。どちらも省略すると、ソース全体が返されます。レスポンスには常に is_partial、有効な offset、total_chars、returned_chars、has_more が含まれます。テキストブロックは常に返された content と一致するため、ウィンドウの内容が通知なく切り詰められることはありません。ソースの末尾を超える offset を指定すると、空文字列ではなく isError の結果が返されます。例：diagrams_get({ "relative_path": "models/big.puml", "offset": 0, "max_chars": 2000 }) を実行し、続けて offset: 2000 を指定して再度実行します。

要件

• サーバーの実行には Node.js 18 以降が必要です（ランタイムの engines: >=18 — コンパイル済みの dist/ 出力、npm test、npm start は Node 18 で動作します）
• 開発ツールチェーンには Node.js >=20.19 が必要です（npm ci、npm run lint、npm run format:check、npm run build）— ESLint 10 のツールチェーンはこれより古い Node バージョンでは動作しません
• （任意、diagrams_render 用）Mermaid のレンダリングには @mermaid-js/mermaid-cli が必要です：npm install -g @mermaid-js/mermaid-cli
• （任意、diagrams_render 用）オフラインで PlantUML をレンダリングするには、ローカルの plantuml CLI が必要です。これがない場合、ALLOW_REMOTE_PLANTUML=true でリモートレンダリングを明示的に有効にしない限り、対処方法を示すエラーが発生します。有効にした場合は、HTTPS 経由で公開されている plantuml.com サーバーにフォールバックします。DISABLE_REMOTE_PLANTUML=true を設定すると、許可フラグが設定されていても常にフォールバックが無効になります。

インストール

必要なのは Node.js 18 以降 だけです。アカウントも API キーも、別途サービスも必要ありません。

1. パッケージを入手する（いずれかの方法を選択）

オプション A — インストール不要（最も手軽に試せる方法）

npx diagrams-mcp-server --help

npx は初回使用時にパッケージを取得してキャッシュします。永続的にインストールされるものはないため、サーバーを試す最も簡単な方法です。ただし、初回の実行にはインターネット接続が必要で、MCP クライアントはセッションごとにサーバーを新たに起動します。日常的に使用する場合は、オプション B をおすすめします。

オプション B — グローバルインストール（日常的な使用におすすめ）

npm install -g diagrams-mcp-server
diagrams-mcp-server --help   # prints the help text and exits 0

これにより、PATH に diagrams-mcp-server コマンドが追加され、どの MCP クライアントからでもサーバーを起動できるようになります。後で更新するには、同じコマンドを再実行するだけです。

オプション C — プロジェクトの依存関係（プロジェクトごとにバージョンを固定）

cd /path/to/your/project
npm install diagrams-mcp-server
npx diagrams-mcp-server --help

プロジェクトごとに異なるサーバーバージョンを使用する場合に選択してください。

2. クライアントに接続する

パッケージをインストールするだけでは不十分です。MCP クライアントにも、サーバーの起動方法を示す diagrams エントリーが必要です。ワンコマンドのセットアップを実行すれば、このエントリーが書き込まれるため、JSON を手動で編集する必要はありません。

npx diagrams-mcp-server setup            # interactive: pick client, then scope
npx diagrams-mcp-server setup --client codex --yes   # non-interactive
npx diagrams-mcp-server setup --client cursor --scope project --yes   # pin this project

セットアップでは、最初にクライアントを選び、次にスコープを選びます（どちらもフラグを指定すればスキップできます）。

• グローバル（推奨）： PROJECT_ROOT を含まないクリーンなエントリーを書き込みます — サーバーは、クライアントが起動されたディレクトリに接続します。多くのプロジェクトを横断して作業する場合に最適です。
• プロジェクト固有： プロジェクトのルートを尋ね、その値を設定に組み込みます （ファイルベースのクライアントでは "env": { "PROJECT_ROOT": "..." }、 claude／codex mcp add では --env PROJECT_ROOT=...）。常に特定のプロジェクトを参照する設定を使いたい場合に最適です。

ファイルベースのクライアント（Cursor、VS Code、Antigravity）では、 クライアントの設定ファイルにエントリーをマージします。Claude Code と Codex では、それぞれの mcp add コマンドを実行します。その CLI がインストールされていない場合、 セットアップによって自分で実行する正確なコマンドが表示されます。OpenCode では実行するコマンドが表示されます。 ファイルベースのクライアントでは、設定を反映するためにその後再起動してください。

セットアップはバージョンバナーを表示してから、事前チェックを自動的に実行します。 claude または codex CLI が見つからない場合は警告し （代わりに手動で実行するコマンドを表示）、プロジェクトスコープのパスを検証し （作成するかどうかを確認）、最後にクライアント、スコープ、 変更した設定、ステータスの概要を表示します。 対話型プロンプトでは矢印キーのピッカー（↑↓ + Enter、Esc でキャンセル）と Yes／No の切り替えを使用します。手動コマンドは枠付きの カードに表示され、ステータス出力は色で強調されます（パイプに出力する場合や NO_COLOR が設定されている場合はプレーンテキストになります）。対応するフラグを渡すと、各プロンプトはスキップされます。

3. 動作を確認する

クライアントを再起動してから、エージェントに「自分の図を一覧表示して」と尋ねます。エージェントが diagrams_list を呼び出すはずです。新しいプロジェクトで空のリストが返れば、すべて正しく接続されています。

ソースから（コントリビューター向け）

git clone https://github.com/mohammad-emad-dev/diagrams-mcp-server.git
cd diagrams-mcp-server
npm ci
npm run build
npm test

npm test は dist/ から一連のテスト（ユニットテスト、ゴールデンテスト、実際のサーバーを起動する live-stdio 統合テスト）を実行するため、必ず先にビルドしてください。PR を作成する前に、4 つのゲートすべてを実行してください：npm run build、npm test、npm run lint、 npm run format:check（最後の 2 つには Node >=20.19 が必要です）。

ファイルの場所

• グローバルインストール（npm install -g diagrams-mcp-server）：パッケージはグローバルな node_modules に配置されます（場所は npm root -g で確認できます。例： Windows では C:\Users\<you>\AppData\Roaming\npm\node_modules、 macOS／Linux では /usr/local/lib/node_modules）。起動用シムが PATH に追加されるため、 どこからでも diagrams-mcp-server を実行できます。
• プロジェクト依存関係（プロジェクト内で npm install diagrams-mcp-server を実行）： 同じ内容が <project>/node_modules/diagrams-mcp-server/ に配置され、 バイナリは <project>/node_modules/.bin/diagrams-mcp-server にリンクされます。
• npx diagrams-mcp-server：グローバルインストールがあればそれを使用し、なければローカルインストールを使用し、それもなければダウンロードしてキャッシュします。ファイルを手動で扱う必要はありません。

3 つとも同じエントリーポイント（dist/index.js）を実行するため、MCP クライアントは用途に合ったパスを使用できます。グローバルシム、プロジェクトの .bin バイナリ、または node <path>/dist/index.js の直接実行です。

Lint とフォーマット

npm run lint          # ESLint over src/ (TypeScript recommended rules, zero warnings allowed)
npm run format:check  # Prettier check over src/ (100-col, double quotes, semicolons, trailing commas)

どちらも、ビルドの前に CI（.github/workflows/ci.yml、Node 20.x／22.x のマトリックス）で実行されます。対象は src/ 以下のソースファイルとテストファイルのみです。dist/、node_modules/、 graphify-out/、パッケージ化された tarball は、eslint.config.mjs と .prettierignore によって除外されます。この 2 つのコマンドには開発用ツールチェーン（Node >=20.19）が必要ですが、サーバーの実行環境自体は引き続き Node >=18 をサポートします。.gitattributes によってすべてのテキストファイルの改行コードが LF に固定されているため、Windows と Linux のチェックアウトで改行コードが同一になり、どのプラットフォームでもフォーマットチェックの結果が一致します。

公開せずにローカルの tarball をインストールする

このテクニカルプレビューをローカルのパッケージファイルからインストールして実行するには、 tarball を作成し、別のコンシューマープロジェクトにインストールします。

npm pack   # runs the prepack build and writes diagrams-mcp-server-0.7.0.tgz
cd /path/to/your/project
npm init -y                       # if the consumer project has no package.json yet
npm install /path/to/diagrams-mcp-server-0.7.0.tgz
npx diagrams-mcp-server --help    # resolves the local install, exits 0

インストールされるのは公開用のペイロード（dist/ の実行時ファイル、README.md、 LICENSE）のみです。テスト、フィクスチャ、ローカル設定は含まれません。また、 コンシューマープロジェクト外には何も変更を加えません（グローバルパッケージのインストールも、 レジストリへの公開も行いません）。パッケージファイルはローカルにありますが、 インストール中に npm がレジストリからパッケージの依存関係をダウンロードする場合があります。stdio MCP クライアントは、 クライアントの設定の dist/index.js と同じ方法で、インストールされたバイナリ （node_modules/.bin/diagrams-mcp-server）を指定してください。

アンインストール

アンインストールには、サーバーをクライアントから切断することと、 パッケージを削除することの、独立した 2 つの手順があります。どちらか一方、または両方を実行してください。

1. クライアントから切断する

クライアントの設定から diagrams エントリーを削除し、 クライアントを再起動します。

クライアント	削除するもの
Cursor	~/.cursor/mcp.json または .cursor/mcp.json の "diagrams" ブロック
VS Code	.vscode/mcp.json の "diagrams" ブロック
Antigravity	~/.gemini/config/mcp_config.json（または .agents/mcp_config.json）の "diagrams" ブロック
Claude Code	claude mcp remove diagrams を実行します
Codex	~/.codex/config.toml の [mcp_servers.diagrams] セクション
OpenCode	opencode.jsonc の "diagrams" ブロック

2. パッケージを削除する

インストール方法に応じて操作してください。

npm uninstall -g diagrams-mcp-server   # global install (Option B)
npm uninstall diagrams-mcp-server      # project dependency (Option C, run inside the project)

npx（オプション A）しか使っていない場合、アンインストールするものはありません。 必要に応じて npx clear-npx-cache でダウンロードキャッシュを消去できます。

残るもの

アンインストールしても、図のファイルには一切手を加えません。プロジェクト内の diagrams/ フォルダーは ご自身の作業内容であり、そのまま残ります。図も削除したい場合に限り、 手動で削除してください。

クライアントの設定

diagrams-mcp-server はプレーンな stdio MCP を使用するため、MCP 対応クライアントであればどれでも動作します。以下に各クライアントの設定手順を示します。

すべての例では、サーバーを /absolute/path/to/diagrams-mcp-server にビルドし、 /absolute/path/to/your/project のプロジェクトに接続することを想定しています。両方のパスを独自のものに置き換えてください。レジストリからインストールした場合は、ビルドディレクトリの代わりにグローバルインストール先、またはプロジェクトの node_modules/.bin/diagrams-mcp-server を使用してください（ファイルの場所を参照）。

Claude Code

claude mcp add diagrams -- node /absolute/path/to/diagrams-mcp-server/dist/index.js

シェル環境で PROJECT_ROOT を設定するか、プロジェクトディレクトリ内から Claude Code を実行してください（デフォルトでは現在の作業ディレクトリが使用されます）。

Codex（デスクトップおよび CLI）

codex mcp add diagrams -- node /absolute/path/to/diagrams-mcp-server/dist/index.js

または、~/.codex/config.toml に直接追加します。

[mcp_servers.diagrams]
command = "node"
args = ["/absolute/path/to/diagrams-mcp-server/dist/index.js"]
env = { PROJECT_ROOT = "/absolute/path/to/your/project" }

Antigravity（IDE、2.0、CLI）

Antigravity IDE、Antigravity 2.0、Antigravity CLI は、同じ設定ファイル ~/.gemini/config/mcp_config.json（プロジェクト単位の場合は .agents/mcp_config.json）を共有します。次を追加してください。

{
  "mcpServers": {
    "diagrams": {
      "command": "node",
      "args": ["/absolute/path/to/diagrams-mcp-server/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

IDE から追加することもできます。エージェントパネル → ⋯ メニュー → MCP サーバー → MCP サーバーを管理 → 生の設定を表示を選択し、同じブロックを貼り付けてください。

OpenCode（デスクトップおよび CLI）

opencode mcp add

プロンプトが表示されたら、サーバーの種類として Local を選択し、次を入力してください。

node /absolute/path/to/diagrams-mcp-server/dist/index.js

または、opencode.jsonc を直接編集します。

{
  "mcp": {
    "diagrams": {
      "type": "local",
      "command": ["node", "/absolute/path/to/diagrams-mcp-server/dist/index.js"],
      "environment": {
        "PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Cursor（デスクトップおよび CLI）

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト単位）に追加してください。

{
  "mcpServers": {
    "diagrams": {
      "command": "node",
      "args": ["/absolute/path/to/diagrams-mcp-server/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

VS Code（GitHub Copilot を使用）

ワークスペース内の .vscode/mcp.json に追加してください。

{
  "servers": {
    "diagrams": {
      "command": "node",
      "args": ["/absolute/path/to/diagrams-mcp-server/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

または、コマンドパレットから **MCP: サーバーを追加 → コマンド（stdio）**を選択し、同じコマンドと引数を入力してください。

設定

環境変数	デフォルト	説明
PROJECT_ROOT	現在の作業ディレクトリ	このサーバーが接続されているコードベースのルートです（diagrams_check_consistency で使用）
DIAGRAMS_DIR	diagrams	図のファイルが格納されている場所です。絶対パスでない場合は PROJECT_ROOT からの相対パスです
PLANTUML_SERVER_URL	https://www.plantuml.com/plantuml	公開 PlantUML レンダリングへのフォールバック先を変更します（例：セルフホストインスタンスを指定する場合）
ALLOW_REMOTE_PLANTUML	未設定（リモートへのフォールバックは無効）	ローカルに plantuml CLI がインストールされていない場合に、リモートの PlantUML サーバーへのフォールバックを許可するには、値を正確に true に設定します。それ以外の値ではリモートレンダリングは無効のままです。Mermaid は常にローカルのみで動作し、影響を受けません
DISABLE_REMOTE_PLANTUML	未設定	ALLOW_REMOTE_PLANTUML=true が設定されていても、リモートの PlantUML サーバーを使用しないようにするには、値を正確に true に設定します。この場合、PlantUML のレンダリングにはローカルの plantuml CLI が必要です。Mermaid は常にローカルのみで動作し、影響を受けません

整合性スキャンの上限

diagrams_check_consistency の実行では、毎回次の上限が適用されます。

上限	値	確認方法
スキャン対象ファイル数	ソースファイル 5,000 件	結果には truncated、scan_limit、files_scanned、scan_warning が報告されるため、上限に達したスキャンを完全なスキャンと誤認することはありません。truncated が true の場合、一致しない結果は不完全である可能性があります
ファイルごとのサイズ	1,000,000 バイト	これより大きなファイル（通常は生成されたバンドル）は、通知なしでスキップされます
エンティティごとの証拠	一致ファイル 10 件	matched_files には上限がありますが、matched_file_count には全件数が報告されます
同時ファイル読み込み数	32	スキャン中に開かれるファイルハンドル数を制限します

生成の上限

diagrams_generate の実行では、毎回次の上限が適用されます。max_entities（1～60、デフォルトは 30）で出力する宣言数を制限します。以下はハード上限です。

上限	値	確認方法
出力するエンティティ数	宣言 60 件	entities_available に見つかった合計数が報告され、除外されたものがある場合は entities_capped が true になります。適用された上限は entity_limit に報告されます
出力するリレーション数	エッジ 60 件	relations_available に証拠のある合計数が報告されます。上限、または上限によって除外されたエンティティの影響で除外されたものがある場合は relations_capped が true になります。図が、宣言されていないボックスを参照することはありません
スキャン対象ファイル数	ソースファイル 5,000 件	結果には truncated、scan_limit、files_scanned、scan_warning が報告されるため、上限に達したスキャンを完全なスキャンと誤認することはありません。truncated が true の場合、生成されたエンティティは不完全である可能性があります
ファイルごとのサイズ	1,000,000 バイト	これより大きなファイル（通常は生成されたバンドル）はスキップされます
同時ファイル読み込み数	32	スキャン中に開かれるファイルハンドル数を制限します

TypeScript コンパイラーがインストールされていない場合（公開版のインストールには typescript 依存関係がありません）、ツールは失敗せずにその状態を明示して機能を縮退させます。エンティティは宣言パターンから引き続き取得されますが、relations は空になり、リレーションを利用できないことが dialect_note に示されます。

シーケンスの上限

diagrams_generate_sequence を実行するたびに、以下の上限が適用されます。max_participants（1～20、既定値は8）は宣言される参加者数を制限し、max_messages（1～50、既定値は20）は出力されるメッセージ数を制限します。以下の値はハード上限です。

上限	値	確認方法
宣言される参加者	20人の参加者	participants_available は見つかった参加者の合計を報告し、参加者が削除された場合は participants_capped が true になります。participant_limit は適用された上限を報告します
出力されるメッセージ	50件のメッセージ	messages_available は見つかったメッセージの合計を報告し、上限によって、または上限で削除された参加者によってメッセージが削除された場合は messages_capped が true になります。図で宣言されていないボックスにメッセージが送られることはありません。message_limit は適用された上限を報告します
保留中の呼び出し箇所	数はカウントされますが、シーケンス化されません	deferred_count は、コールバック、プロミス、またはリスナー内にある呼び出しの数を報告します。ソースから実行時の位置を特定できないため、これらは messages から除外されます
解決できない呼び出し先	報告されますが、推測されません	unresolved_callees には、スコープ内でどの参加者も宣言していない呼び出し先が一覧表示されます。呼び出し先の参加者を推測して作成することはありません
スキャン対象ファイル	ソースファイル5,000件	結果には truncated、scan_limit、files_scanned、scan_warning が含まれるため、上限に達したスキャンを完全なスキャンと誤認することはありません。truncated が true の場合、生成されるメッセージは不完全な可能性があります
ファイルごとのサイズ	1,000,000バイト	これを超えるファイル（通常は生成されたバンドル）はスキップされます
同時に読み込むファイル数	32	スキャン中に開かれるファイルハンドルの数を制限します

TypeScript コンパイラーがインストールされていない場合（公開済みのインストールには typescript の依存関係がありません）、ツールは失敗する代わりに、同じくオープンな方法で機能を縮小します。宣言された操作と呼び出しエッジは引き続きヒューリスティック抽出器から取得されるため、参加者とメッセージは引き続き出力されます。

差分の範囲

diagrams_diff は変更を報告し、黙って破棄することはありません。ただし、差分ツールで比較できる範囲よりも意図的に比較対象を絞っています。

比較するもの	比較しないもの
宣言されたクラス／インターフェース／列挙型／コンポーネント名、エイリアス、名前空間、参加者、メッセージ呼び出し	メンバー一覧、属性、メソッドシグネチャ
追加、削除、名前変更された名前（共通の名前正規化処理で名前変更を対応付けます）	レイアウト、位置、順序、スタイル、テーマ
方言ごとのシーケンス参加者とメッセージ呼び出し	ファイル間または図間の参照、解決済みの型

このツール自体に上限はありません。比較対象の両側は、比較する2つのソースによってすでに制限されているため、追加、削除、名前変更された名前はすべて漏れなく報告されます。図のルートの外部は読み込みません。また、入力形式のエラー（片側でパスとコンテンツの両方が指定されている、またはいずれも指定されていない場合、あるいはインラインコンテンツの方言が認識されない場合）は、ファイルを開く前に報告されます。

テンプレートの上限

すべての diagrams_template 呼び出しには、以下の上限が適用されます。引き上げたり引き下げたりするための max_* 引数はありません。スケルトンは固定された足場であり、以下の上限が取り得る唯一の形です。

上限	値	確認方法
スケルトンあたりのエンティティ数	20 個の名前（1～20）	entities_included は、指定順に実際に出力された件数を示します
エンティティ名の長さ	60 文字	各名前はクラス、参加者、または C4 エイリアスとしてそのまま出力されるため、有効な識別子である必要があります
タイトルの長さ	200 文字	それより長いタイトルは切り詰められずに拒否されます。空白のみのタイトルも、空のタイトル行を出力せずに拒否されます
テンプレートの種類	3 種類（class、sequence、c4_context）	ソース内で種類が固定されているため、4 種類目を追加するには値を渡すのではなく、スキーマを変更する必要があります

すべての名前は /^[A-Za-z_][A-Za-z0-9_]*$/ に一致し、重複してはなりません。重複すると同じボックスの宣言が 2 つ出力されるため、2 回目の出現はそのインデックスで拒否されます。拒否された場合は isError: true が返され、問題のある入力が示されます。出力されたソースは常に diagrams_create が適用するものと同じ構文チェックに合格するため、スケルトンはそのまま保存できます。

エクスポートの上限

すべての diagrams_export の実行では、完成した HTML ドキュメントに次の上限が適用されます。

上限	値	確認方法
バンドルサイズ	5,000,000 バイト	それを超えるバンドルは、図と上限を示して isError: true で拒否されます。truncated は常に false であり、部分的なファイルが返されたり保存されたりすることはありません

バンドル内の SVG のサイズは、レンダラーが生成した内容によって制限されます。また、そこに至るまでレンダラー独自の制限も適用されます。include_source はサイズを指定する引数ではなく、ブール値です。ソースブロックは全体を埋め込むか、省略するかのいずれかです。完全な図の横に途中で切れたソースがあると、読者に誤解を与えるためです。

例

diagrams/
└── models/
    └── user-class.puml

エージェントに尋ねます。

「ユーザークラス図は、コードと比べてまだ正確ですか？」

エージェントは diagrams_check_consistency を呼び出し、次の内容を報告します。

1 of 2 entities in 'models/user-class.puml' were NOT found in the codebase:
- Order: 'Order' appears in the diagram but no matching identifier was
  found in the scanned codebase. It may be renamed, removed, or not yet
  implemented.

プロジェクトの構成

src/
├── index.ts                       # Server entry point (stdio transport)
├── context.ts                     # Resolves PROJECT_ROOT / DIAGRAMS_DIR once at startup
├── constants.ts                   # Shared constants
├── types.ts                       # Shared TypeScript types
├── setup/                         # Guided client-setup wizard (scopes, pre-flight checks)
│   ├── index.ts                   # runSetup orchestrator
│   ├── clients.ts                 # Supported clients, arg parsing, config writers
│   ├── prompts.ts                 # Interactive pickers and confirmations
│   └── terminal.ts                # Banner, boxes, color
├── services/
│   ├── diagramStore.ts            # Safe filesystem CRUD (path-traversal protected)
│   ├── diagramValidator.ts        # PlantUML/Mermaid syntax checks and dialect detection
│   ├── nameNormalize.ts           # Shared lenient name normalizer (checker + diff)
│   ├── renderer.ts                # Mermaid/PlantUML -> SVG/PNG rendering
│   ├── scopeResolve.ts            # Bounds read-only tool scopes to PROJECT_ROOT
│   ├── consistencyChecker/        # Diagram <-> code drift detection
│   │   ├── index.ts               # checkConsistency orchestration (scan, match, report)
│   │   ├── entities.ts            # Entity names from diagram source
│   │   ├── codeAnalysis.ts        # Per-language declaration patterns
│   │   ├── scanning.ts            # Filesystem walk with scan limits
│   │   ├── sequence/              # Call-graph edges, participant mapping, message ordering
│   │   │   ├── callGraph.ts / operationIndex.ts / participantMapping.ts
│   │   │   ├── sequenceEntities.ts / sequenceMatch.ts / sequenceOrder.ts
│   │   │   └── sequenceGoldens.test.ts / sequenceOrderGoldens.test.ts
│   │   └── ts/                    # Optional TypeScript AST path (dynamic import only — never a static import, so published installs run without the compiler)
│   │       ├── tsParse.ts         # Compiler availability probe
│   │       ├── tsSymbols.ts       # Declared symbols + heritage collection
│   │       ├── tsIndex.ts / tsHeritage.ts  # Index and extends/implements edges
│   ├── diff/                      # diagrams_diff comparison
│   │   └── diffDiagram.ts         # Pure added/removed/renamed + sequence fields
│   ├── export/                    # diagrams_export bundle builder (pure, no filesystem)
│   │   ├── htmlBundle.ts          # One self-contained HTML string from SVG + source
│   │   └── exportGoldens.test.ts  # Exact wrapper structure locked per variant
│   ├── generate/                  # diagrams_generate entity collection and emitters
│   │   ├── collectEntities.ts     # Scan a scope into ordered entities + relations
│   │   ├── emitters.ts            # Pure PlantUML/Mermaid class-diagram emitters
│   │   ├── sequence.ts            # diagrams_generate_sequence orchestration (participants, messages, caps)
│   │   ├── sequenceEmitters.ts    # Pure PlantUML/Mermaid sequence emitters
│   │   └── scopeFiles.ts          # Scope walking shared by both generators
│   └── templates/                 # diagrams_template skeleton tables (no filesystem, no state)
│       ├── skeletons.ts           # Six pure emitters: kind x dialect
│       └── templateGoldens.test.ts # Exact emitted source per (template, format)
├── tools/                         # One MCP tool adapter per file (12 tools) + shared toolError/toolOutput
└── integration/
    └── mcpServer.test.ts          # End-to-end server surface tests

テストは、対象のソースの隣に配置します（*.test.ts）。テストは dist/ にコンパイルされ、そこから実行されます。npm test は package.json に記載されたファイル一覧を使用するため、新しいテストファイルは一覧に追加する必要があります。

セキュリティに関する注意事項

• すべてのファイル操作は、設定された diagrams ディレクトリ内に限定されます。外部（例：../..）への読み取り／書き込みは拒否されます。Windows 形式の \ 区切り文字はすべてのプラットフォームでパス区切り文字として機能するため、Linux でも ..\.. によるディレクトリ移動は拒否されます。
• diagrams_check_consistency、diagrams_generate、diagrams_generate_sequence はコードベースを読み取るだけで、コードや図を変更することはありません。両方の生成ツールは scope を PROJECT_ROOT に対して解決し、その範囲外になるパスは、何も読み取らずに拒否します。出力はソーステキストであり、diagrams_create を使って自分で保存します。
• diagrams_diff も読み取り専用です。保存済みの比較対象は、diagrams_get と同じディレクトリ移動保護付きのストアを通して読み取られ、インラインの比較対象はファイルシステムに一切アクセスしません。また、入力形式のエラーはファイルを開く前に報告されます。エラーやログに図のソースが含まれることはなく、報告対象の名前だけが記録されます。
• diagrams_template はファイルシステムに一切アクセスしません。プロジェクトルートも diagrams ディレクトリも使わず、呼び出し間で状態を保持しません。入出力はいずれも純粋なソーステキストであるため、制限すべきものも漏えいするものもありません。渡したエンティティ名だけがそのまま返されます。
• diagrams_export は diagrams_get と同じディレクトリ移動保護付きのストアを通して図を 1 つ読み取り、バンドルをテキストとして返します。書き込みは行わないため、ストアの拡張子許可リストが .html を許可することはありません。成果物は共有できるように作られており、外部リソースは一切含みません（src／href URL、@import、スクリプト、フォントは含まれません）。含まれるパスは、図の POSIX 形式の relative_path だけです。リモート PlantUML レンダリングを有効にした場合、図のソースは設定済みサーバーに送信されます。これは既存のレンダリング経路であり、変更されていません。
• どのツールでも認証情報や外部アカウントは必要ありません。PlantUML 用の diagrams_render は、ALLOW_REMOTE_PLANTUML=true を明示的に設定してリモートレンダリングを有効にしない限り、マシンの外部にデータを送信しません。また、優先される DISABLE_REMOTE_PLANTUML=true が設定されている場合は、リモートレンダリングを有効にしても送信されません。Mermaid のレンダリングでマシンの外部にデータが送信されることはありません。
• ローカルのレンダラープロセスにはタイムアウトが設定され、標準出力／標準エラー出力の取得には上限があります（ストリームごとに 1,000,000 文字。取得中に適用されます）。レンダラーが上限またはタイムアウト時間を超えると停止されます。出力パイプは閉じられ、プロセスは強制終了されます。レンダリングは、取得した出力、パス、環境変数の値を含まない、対処方法が明確なエラーで失敗します。タイムアウト時には、レンダラーの出力パイプを引き継いだ子孫プロセス（Windows の cmd.exe シムチェーンなど）がパイプを解放するのを待たずに、エラーがただちに返されます。

ロードマップ

v0.7.0 でリリース済み（RELEASE_NOTES.md を参照）：

• 整合性チェックにおける TypeScript AST の使用 — より厳密な照合に加え、コンパイラーが利用可能な場合は extends／implements のエッジを検出し、利用できない場合はオープンなヒューリスティックによるフォールバックを使用
• 双方向のシーケンス図対応：diagrams_generate_sequence は呼び出しグラフのエッジから下書きを生成し、チェッカーはメッセージの順序を比較（コールバックは遅延され、シーケンス化されません）
• 図の差分比較（diagrams_diff）、スターター用ひな形（diagrams_template）、自己完結型 HTML エクスポート（diagrams_export）

未対応：

• 図からのコードのひな形生成：図からクラスの骨組みを生成（diagrams_generate の逆方向）
• 需要に応じた、より多くの言語での AST に基づく精度向上
• エクスポートの強化に関する追加対応：バンドルされたマークアップ用の SVG サニタイザーの許可リスト（docs/next-features.md で追跡中）

貢献や課題の報告を歓迎します。

ライセンス

MIT — LICENSE を参照してください。