D2 MCP Server

D2 MCP サーバー

D2 ダイアグラムの生成と操作機能を提供する Model Context Protocol（MCP）サーバーです。

D2 は、テキストをダイアグラムに変換する最新のダイアグラムスクリプト言語です。この MCP サーバーを使うと、Claude などの AI アシスタントがプログラムから D2 ダイアグラムを作成、レンダリング、エクスポート、保存できます。

このサーバーは、ソース全体の作成、検証、レンダリング、組み込み D2 ガイダンス、Oracle による段階的な編集に対応する 16 個の MCP ツールを提供します。

新しい Oracle API 統合により、AI アシスタントはダイアグラムを段階的に作成・変更できるようになりました。次の用途に最適です。

• 会話をアーキテクチャ図に変換する
• 要件の話し合いに合わせて、フローチャートを段階的に作成する
• データベーススキーマからエンティティ関係図を作成する
• コード分析からシステム図を生成する
• 最初からやり直すことなく、ユーザーのフィードバックに基づいてダイアグラムを改良する

機能

ソース優先のダイアグラム操作

• d2_create - D2 ソース全体からダイアグラムを作成するか、空の状態から開始します
• d2_get_source - Oracle による編集も含む、正規のソースを取得します
• d2_update_source - 検証後、ソース全体をアトミックに置き換えます
• d2_format - 有効なソースを保存せずにフォーマットします
• d2_validate - 生または保存済みのソースを検証し、保守的な修正案を提示します
• d2_export - バンドルされた D2 v0.9 レンダラーでエクスポートします（SVG、PNG、PDF、PPTX、GIF、ASCII）
• d2_save - エクスポートを設定済みのワークスペースルート内に保存します
• d2_help - 組み込みの D2 v0.9 ガイダンスを検索または取得します
• d2_capabilities - バージョン管理された機能カタログを一覧表示します

Oracle API による段階的な編集

• d2_oracle_create - 図形と接続を段階的に作成します
• d2_oracle_set - 既存の要素の属性を設定します
• d2_oracle_delete - ダイアグラムから特定の要素を削除します
• d2_oracle_move - 図形をコンテナー間で移動します
• d2_oracle_rename - ダイアグラム要素の名前を変更します
• d2_oracle_get_info - 図形、接続、またはコンテナーの情報を取得します
• d2_oracle_serialize - ダイアグラムの現在の D2 テキスト表現を取得します

その他の機能

• バンドルされたレイアウト - Dagre、ELK、TALA
• 型指定されたレンダリング - レイアウト、テーマの上書き、バンドルされたフォント、スケール、パディング、スケッチ、アニメーション、ボード選択、出力範囲の制限オプション
• 20 種類のテーマ - すべての D2 テーマに対応（ライト 18 種類＋ダーク 2 種類）

プロジェクト構成

d2mcp/
├── cmd/                  # Application entry point
├── internal/
│   ├── domain/          # Business entities and interfaces
│   │   ├── entity/      # Domain entities
│   │   └── repository/  # Repository interfaces
│   ├── usecase/         # Business logic
│   ├── infrastructure/  # External implementations
│   │   ├── d2/          # D2 library integration
│   │   └── mcp/         # MCP server implementation
│   └── presentation/    # MCP handlers
│       └── handler/     # Tool handlers
└── pkg/                 # Public packages

前提条件

• Go 1.27 以降
• D2 v0.9.0（Go の依存関係として含まれています）

すべてのエクスポート形式でバンドルされた Go レンダラーを使用するため、rsvg-convert、ImageMagick、Chromium のインストールは不要です。

組み込みの機能カタログは、公式の D2 言語ツアー、D2 API ドキュメント、および D2 v0.9.0 リリースに基づいています。

インストール

ソースから

# Clone the repository
git clone https://github.com/recursivefunctions/d2mcp.git
cd d2mcp

# Build the binary
make build

# Or build for all platforms
make build-all

Go Install を使用

go install github.com/recursivefunctions/d2mcp/cmd@latest

Docker を使用

docker run --rm -i \
  --mount type=bind,src="$PWD",dst=/workspace \
  ghcr.io/recursivefunctions/d2mcp:0.5.0

イメージはデフォルトで STDIO トランスポートを使用し、ローカルインポート、アセット、エクスポートをマウントされた /workspace ディレクトリ内に制限します。コンテナーは非 root ユーザーとして実行されるため、エクスポートを保存する場合、マウントされたディレクトリはそのユーザーが書き込み可能である必要があります。

MCP レジストリ

リリースタグを使用して、サーバーは公式 MCP レジストリに io.github.RecursiveFunctions/d2mcp として公開されます。レジストリへの公開とエディターギャラリーへの登録は別々に行われるため、新たに公開されたバージョンがエディターの検索結果にすぐ表示されない場合があります。

互換性のあるクライアントは、このリポジトリにあるポータブルな .mcp.json 設定も使用できます。Docker が必要で、現在のワークスペースを /workspace にマウントします。

エディター連携

クライアントの設定はserver.jsonから生成されるため、常に同じ不変のコンテナバージョンが使用されます。

クライアント	インストール
VS Code	インストール URL、Official MCP Registry、またはコンパニオン拡張機能を使用します
VSCodium と Positron	Open VSX からRecursiveFunctions.d2mcpコンパニオン拡張機能をインストールします
Cursor	生成されたMCP 設定を使用します
Windsurf	生成されたMCP 設定を使用します
Trae	生成されたインストール URLまたはプロジェクト設定を使用します
Antigravity	生成されたMCP 設定を使用します
Zed	Zed が Official Registry との連携を完了するまで、生成された手動設定を使用します
Kilo Code	カタログの PR が承認された後に Kilo Marketplace からインストールするか、ポータブル設定を使用します
Cline	キュレーターの承認後に Cline Marketplace からインストールするか、上記の Docker 手順に従います

リリースメタデータを変更した後は、make generate-adaptersを実行してください。CI はmake verify-adaptersを実行し、古いクライアント設定を拒否します。

ビルド

# Simple build
make build

# Run directly
make run

# Cross-platform builds
make build-all

使い方

Claude Desktop での使用

Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json Linux：~/.config/Claude/claude_desktop_config.json

STDIO トランスポートの場合（Claude Desktop での使用を推奨）：

{
  "mcpServers": {
    "d2mcp": {
      "command": "/path/to/d2mcp",
      "args": ["-transport=stdio"]
    }
  }
}

SSE トランスポートの場合：

{
  "mcpServers": {
    "d2mcp": {
      "command": "/path/to/d2mcp",
      "args": ["-transport=sse", "-addr=:3000"]
    }
  }
}

/path/to/d2mcpを、ビルドしたバイナリの実際のパスに置き換えてください。

単体での使用

# Run the MCP server (stdio transport)
./d2mcp -transport=stdio

# Run with SSE transport (default)
./d2mcp
# or explicitly
./d2mcp -transport=sse

# Run with Streamable HTTP transport
./d2mcp -transport=streamable

トランスポートのオプション

d2mcp は複数のトランスポートプロトコルに対応するようになりました。

STDIO トランスポート

プロセス間の直接通信に使用する従来の stdio トランスポート：

./d2mcp -transport=stdio

SSE トランスポート（Server-Sent Events）

ネットワーク接続を可能にする HTTP ベースのトランスポート：

# Basic SSE mode (defaults to :3000)
./d2mcp -transport=sse

# Custom configuration
./d2mcp -transport=sse \
  -addr=:8080 \
  -base-url=http://localhost:8080 \
  -base-path=/mcp \
  -keep-alive=30

SSE の設定オプション：

• -addr：リッスンするアドレス（デフォルト：":3000"）
• -base-url：SSE エンドポイントのベース URL（指定されていない場合は自動生成）
• -base-path：SSE エンドポイントのベースパス（デフォルト："/mcp"）
• -keep-alive：キープアライブ間隔（秒）（デフォルト：30）

SSE エンドポイント： SSE モードで実行すると、次のエンドポイントを使用できます。

• SSE ストリーム：http://localhost:3000/mcp/sse
• メッセージエンドポイント：http://localhost:3000/mcp/message

Streamable HTTP トランスポート

双方向通信を簡素化する最新の HTTP ベースのトランスポート：

# Basic Streamable HTTP mode
./d2mcp -transport=streamable

# Custom configuration
./d2mcp -transport=streamable \
  -addr=:8080 \
  -endpoint-path=/mcp \
  -heartbeat-interval=30 \
  -stateless

Streamable HTTP の設定オプション：

• -addr：リッスンするアドレス（デフォルト：":3000"）
• -endpoint-path：Streamable HTTP のエンドポイントパス（デフォルト："/mcp"）
• -heartbeat-interval：ハートビート間隔（秒）（デフォルト：30）
• -stateless：ステートレスモードを有効にします（デフォルト：false）

Streamable HTTP エンドポイント： Streamable HTTP モードで実行すると、単一のエンドポイントですべての通信を処理します。

• エンドポイント：http://localhost:3000/mcp

ワークスペースとアセットのセキュリティ

サーバーはインポート、ローカル画像、保存ファイルを、名前付きワークスペースルート内に制限します。デフォルトのルートはサーバーの現在の作業ディレクトリです。

./d2mcp -transport=stdio \
  -workspace-root=docs=/workspace/docs \
  -workspace-root=diagrams=/workspace/diagrams \
  -remote-asset-max-bytes=10485760 \
  -remote-asset-timeout=30s

-workspace-rootは複数回指定できます。ローカルパスのトラバーサルとシンボリックリンクによる範囲外へのアクセスは拒否されます。リモートアセットには HTTPS が必要で、DNS/IP、リダイレクト、タイムアウト、MIME、レスポンスサイズのチェックが適用されます。ループバックアドレスとプライベートネットワークの宛先は拒否されます。

ツール

d2_create

任意の初期コンテンツを指定して新しい図を作成します（統合されたアプローチ）。

空の図（Oracle API ワークフロー向け）：

{
  "id": "my-diagram"
}

初期 D2 コンテンツと、インポート／アセット用の名前付きワークスペースを指定する場合：

{
  "id": "my-diagram",
  "content": "a -> b: Hello\nserver: {shape: cylinder}",
  "workspace_root": "diagrams"
}

d2_export

バンドルされたレンダラーとレイアウトエンジンを使って図をエクスポートします：

{
  "diagramId": "my-diagram",
  "format": "png",
  "layout": "tala",
  "themeId": 200,
  "scale": 1.5,
  "maxPixels": 33554432
}

形式は svg、png、pdf、pptx、gif、ascii（txt は別名）です。レイアウトは dagre、elk、tala です。型付きオプションでは、エンジンの間隔、テーマとオーバーライド、バンドルされたフォント、パディング、スケール、スケッチモード、アニメーション、ボードの選択、リソース制限を指定できます。

PDF、PPTX、GIF、およびオプションでアニメーション SVG は、範囲が制限された子孫ボードを合成します。PNG と ASCII は単一のボードを生成します。合成からボードを選択するには、boardPath を使用します。

d2_save

設定されたワークスペースルート内に図を保存します：

{
  "diagramId": "my-diagram",
  "format": "pdf",
  "workspace_root": "diagrams",
  "path": "exports/output.pdf"
}

path を省略すると、選択したルート内の d2mcp_output/ 以下に出力が書き込まれます。

d2_validate

D2 のソーステキスト、または保存済みの図の現在のソースを検証します。入力は必ず 1 つだけ指定してください：

{
  "content": "a: {\n  b"
}

{
  "diagram_id": "my-diagram"
}

無効な D2 に対しては、valid: false とコンパイラー診断を含む成功形式の構造化結果を返します。単純で曖昧さのない終端エラーには、repaired_content が含まれる場合もあります。検証によって保存済みの図が変更されることはありません。

d2_get_source and d2_update_source

D2 のソース全体が正規の表現であるため、専用の構造化ツールを待たずに、バンドルされた v0.9 の言語機能をすべて記述できます。

{"diagram_id": "my-diagram"}

{
  "diagram_id": "my-diagram",
  "content": "direction: right\nclient -> api -> database"
}

更新は最初にコンパイルされ、その後アトミックに置き換えられます。無効なドラフトは構造化された診断を返し、保存済みのソースは変更されません。

d2_format

{"content": "api:{db}"}

図を作成または変更せずに、フォーマット済みのソースを返します。

d2_help and d2_capabilities

{"query": "sequence diagrams", "limit": 5}

d2_help は埋め込みの v0.9.0 リファレンスを検索するか、ID で指定されたトピックをそのまま返します。d2_capabilities はカテゴリと MCP リソース URI の一覧を返します。埋め込みリソースでは、コア言語、接続、再利用可能な定義、ビジュアル、リッチテキスト、構造図／シーケンス図／グリッド図、合成、レイアウト、エクスポートを扱います。

Oracle API ツール

Oracle API ツールを使うと、図全体を再生成せずに段階的に図を操作できます。これらのツールは、図を一歩ずつ作成する場合や、必要箇所だけを編集する場合に最適です。

d2_oracle_create

新しいシェイプまたは接続を作成します：

{
  "diagram_id": "my-diagram",
  "key": "server"  // Creates a shape
}

{
  "diagram_id": "my-diagram", 
  "key": "server -> database"  // Creates a connection
}

d2_oracle_set

既存の要素に属性を設定します：

{
  "diagram_id": "my-diagram",
  "key": "server.shape",
  "value": "cylinder"
}

{
  "diagram_id": "my-diagram",
  "key": "server.style.fill",
  "value": "#f0f0f0"
}

d2_oracle_delete

図から要素を削除します：

{
  "diagram_id": "my-diagram",
  "key": "server"  // Deletes the server and its children
}

d2_oracle_move

要素をコンテナ間で移動します：

{
  "diagram_id": "my-diagram",
  "key": "server",
  "new_parent": "network.internal",  // Moves server into network.internal
  "include_descendants": "true"       // Also moves child elements
}

d2_oracle_rename

図の要素の名前を変更します：

{
  "diagram_id": "my-diagram",
  "key": "server",
  "new_name": "web_server"
}

d2_oracle_get_info

図の要素に関する情報を取得します：

{
  "diagram_id": "my-diagram",
  "key": "server",
  "info_type": "object"  // Options: "object", "edge", "children"
}

d2_oracle_serialize

図の現在の D2 テキスト表現を取得します：

{
  "diagram_id": "my-diagram"
}

Oracle API を通じて加えられたすべての変更を含む、図の D2 テキスト全体を返します。

シーケンス図の作成

D2 はシーケンス図を標準でサポートしています。適切な D2 シーケンス図の構文を使って d2_create を使用してください：

{
  "id": "api-flow",
  "content": "shape: sequence_diagram\n\nClient -> Server: HTTP Request\nServer -> Database: Query\nDatabase -> Server: Results\nServer -> Client: HTTP Response\n\n# Add styling\nClient -> Server.\"HTTP Request\": {style.stroke-dash: 3}\nDatabase -> Server.\"Results\": {style.stroke-dash: 3}"
}

アクターとグループ化を含む例：

{
  "id": "auth-flow",
  "content": "shape: sequence_diagram\n\ntitle: Authentication Flow {near: top-center}\n\n# Define actors\nClient: {shape: person}\nAuth Server: {shape: cloud}\nDatabase: {shape: cylinder}\n\n# Interactions\nClient -> Auth Server: Login Request\nAuth Server -> Database: Validate Credentials\nDatabase -> Auth Server: User Data\n\ngroup: Success Case {\n  Auth Server -> Client: Access Token\n  Client -> Auth Server: API Request + Token\n  Auth Server -> Client: API Response\n}\n\ngroup: Failure Case {\n  Auth Server -> Client: 401 Unauthorized\n}"
}

Oracle API ワークフローの例

ゼロから始める場合：

// 1. Create an empty diagram
d2_create({ id: "architecture" })

// 2. Add shapes incrementally
d2_oracle_create({ diagram_id: "architecture", key: "web" })
d2_oracle_create({ diagram_id: "architecture", key: "api" })
d2_oracle_create({ diagram_id: "architecture", key: "db" })

// 3. Set properties
d2_oracle_set({ diagram_id: "architecture", key: "db.shape", value: "cylinder" })
d2_oracle_set({ diagram_id: "architecture", key: "web.label", value: "Web Server" })

// 4. Create connections
d2_oracle_create({ diagram_id: "architecture", key: "web -> api" })
d2_oracle_create({ diagram_id: "architecture", key: "api -> db" })

// 5. Export final result
d2_export({ diagramId: "architecture", format: "svg" })

既存のコンテンツから始める場合（統一的な方法）：

// 1. Create diagram with initial content
d2_create({ 
  id: "architecture",
  content: "web -> api -> db\ndb: {shape: cylinder}"
})

// 2. Enhance incrementally using Oracle API
d2_oracle_set({ diagram_id: "architecture", key: "web.label", value: "Web Server" })
d2_oracle_create({ diagram_id: "architecture", key: "cache" })
d2_oracle_create({ diagram_id: "architecture", key: "api -> cache" })

// 3. Export final result
d2_export({ diagramId: "architecture", format: "svg" })

各ツールの使いどころ

• d2_create：保存するソースドキュメントを作成します。名前付きワークスペースルートへのバインドは任意です
• d2_update_source：D2 v0.9 ドキュメント全体を記述またはアトミックに置き換えます
• d2_oracle_*：便利な構造化編集を行います。各変更はコミット前に再検証されます
• d2_get_source：どちらの編集ワークフローの後でも、正規のソースを取得します
• d2_help / d2_capabilities：サポートされている構文、合成、レイアウト、エクスポートを確認します
• d2_export / d2_save：メモリ内でレンダリングするか、許可されたワークスペースルート内に保存します

開発

テストの実行

# Run all tests
make test

# Run with coverage
go test -cover ./...

# Run specific test
go test -v ./internal/presentation/handler

コード品質

# Format code
make fmt

# Run linter
make lint

# Clean build artifacts
make clean

新機能の追加

1. internal/domain/entity にエンティティを定義します
2. internal/domain/repository にリポジトリーインターフェイスを追加します
3. internal/usecase にビジネスロジックを実装します
4. インフラストラクチャの実装を追加します
5. internal/presentation/handler に MCP ハンドラーを作成します
6. cmd/main.go で依存関係を接続します

プロジェクト構成

• cmd/: アプリケーションのエントリーポイント
• internal/domain/: コアとなるビジネスロジックとエンティティ
• internal/infrastructure/: 外部サービスとの連携
• internal/presentation/: MCP プロトコルのハンドラー
• internal/usecase/: アプリケーションのビジネスロジック

トラブルシューティング

エクスポート上限のエラー

PNG、PDF、PPTX、GIF のエクスポートは、D2 にバンドルされた Go のラスター処理パイプラインで生成されます。図がリソース上限を超える場合は、スケールまたはボード数を減らすか、特定の boardPath を選択するか、許可された範囲内の maxWidth、maxHeight、maxPixels、maxFrames、または maxOutputBytes の値を設定してください。

MCP 接続の問題

1. バイナリに実行権限があることを確認します: chmod +x d2mcp
2. Claude Desktop のログでエラーメッセージを確認します
3. 設定内のパスが絶対パスであることを確認します

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

変更履歴

v0.5.0（最新版）

• ネットワーク接続に対応する SSE（Server-Sent Events）トランスポートを追加
• 最新の双方向通信に対応する Streamable HTTP トランスポートを追加
• トランスポート設定用のコマンドラインフラグを追加
• Streamable HTTP でステートフルモードとステートレスモードに対応
• stdio トランスポートとの後方互換性を維持
• 各トランスポートモードのエラー処理とログ記録を改善

v0.4.0

• すべての図の作成に対応する統合 API d2_create に API を簡素化
• AI アシスタントとの連携を向上させるため、ツールの説明を強化
• Oracle API のエラー処理と検証を改善
• API の対象範囲を 14 個のツールから 10 個に削減
• 重大な変更: d2_render、d2_render_to_file、d2_import、d2_from_text を削除しました。代わりに d2_create を使用してください

v0.3.0

• 現在の D2 テキスト表現を取得する d2_oracle_serialize ツールを追加

v0.2.0

• 増分的な図の操作に対応する D2 Oracle API 連携を追加
• 図の要素の作成、変更、照会を行う 6 個の新しい MCP ツール
• ステートフルな図編集セッションに対応

v0.1.0

• 基本的な D2 図操作に対応する初回リリース
• 図のレンダリング、作成、エクスポート、保存に対応
• 組み込みテーマ 20 種
• MCP プロトコルとの連携

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。