D2mcp

🚀 D2 MCP Server

D2 MCP Serverは、D2ダイアグラムの生成と操作機能を提供するModel Context Protocol (MCP) サーバーです。D2はテキストをダイアグラムに変換する現代的なダイアグラム記述言語です。このMCPサーバーにより、ClaudeなどのAIアシスタントがプログラムによってD2ダイアグラムの作成、レンダリング、エクスポート、保存を行うことができます。

このサーバーは、MCPプロトコルを通じて10のツールを提供し、AIアシスタントとの最適な統合のために説明が強化されています。Oracle APIを使用することで、単純なダイアグラムのレンダリングから高度な漸進的ダイアグラムの構築まで対応しています。

新しいOracle APIの統合により、AIアシスタントはダイアグラムを漸進的に構築および変更することができ、以下の用途に最適です。

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

✨ 主な機能

基本的なダイアグラム操作

• d2_create - オプションで初期内容を指定して新しいダイアグラムを作成する（統一的なアプローチ）
• d2_export - ダイアグラムをさまざまな形式（SVG、PNG、PDF）にエクスポートする
• d2_save - 既存のダイアグラムをファイルに保存する

漸進的編集のための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テキスト表現を取得する

追加機能

• 20のテーマ - すべてのD2テーマ（18の明るいテーマ + 2の暗いテーマ）をサポートする

📦 インストール

ソースからのインストール

# リポジトリをクローンする
git clone https://github.com/i2y/d2mcp.git
cd d2mcp

# バイナリをビルドする
make build

# またはすべてのプラットフォーム向けにビルドする
make build-all

Go Installを使用する

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

💻 使用例

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 を実際にビルドしたバイナリのパスに置き換えてください。

スタンドアローンでの使用

# MCPサーバーを実行する（stdioトランスポート）
./d2mcp -transport=stdio

# SSEトランスポートで実行する（デフォルト）
./d2mcp
# または明示的に指定する
./d2mcp -transport=sse

# Streamable HTTPトランスポートで実行する
./d2mcp -transport=streamable

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

d2mcpは現在、複数のトランスポートプロトコルをサポートしています。

STDIOトランスポート

直接のプロセス通信のための従来のstdioトランスポート:

./d2mcp -transport=stdio

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

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

# 基本的なSSEモード（デフォルトで:3000）
./d2mcp -transport=sse

# カスタム設定
./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ベースのトランスポート:

# 基本的なStreamable HTTPモード
./d2mcp -transport=streamable

# カスタム設定
./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

ツールの使用方法

d2_create

オプションで初期内容を指定して新しいダイアグラムを作成する（統一的なアプローチ）:

空のダイアグラム（Oracle APIワークフロー用）:

{
  "id": "my-diagram"
}

初期D2内容を指定する場合:

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

d2_export

ダイアグラムを特定の形式にエクスポートする:

{
  "diagramId": "my-diagram",
  "format": "png"  // オプション: "svg", "png", "pdf"
}

d2_save

ダイアグラムをファイルに保存する:

{
  "diagramId": "my-diagram",
  "format": "pdf",
  "path": "/path/to/output.pdf"  // オプション、デフォルトは一時ディレクトリ
}

Oracle APIツール

Oracle APIツールは、ダイアグラム全体を再生成することなく漸進的なダイアグラム操作を可能にします。これらのツールは、ステップバイステップでダイアグラムを構築する場合や、細かい編集を行う場合に最適です。

d2_oracle_create

新しい形状または接続を作成する:

{
  "diagram_id": "my-diagram",
  "key": "server"  // 形状を作成する
}

{
  "diagram_id": "my-diagram", 
  "key": "server -> database"  // 接続を作成する
}

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"  // サーバーとその子要素を削除する
}

d2_oracle_move

コンテナ間で要素を移動する:

{
  "diagram_id": "my-diagram",
  "key": "server",
  "new_parent": "network.internal",  // サーバーをnetwork.internalに移動する
  "include_descendants": "true"       // 子要素も移動する
}

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"  // オプション: "object", "edge", "children"
}

d2_oracle_serialize

ダイアグラムの現在のD2テキスト表現を取得する:

{
  "diagram_id": "my-diagram"
}

Oracle APIを通じて行われたすべての変更を含むダイアグラムの完全なD2テキストを返します。

シーケンスダイアグラムの作成

D2はシーケンスダイアグラムをサポートしています。d2_createを適切なD2シーケンスダイアグラム構文で使用します。

{
  "id": "api-flow",
  "content": "shape: sequence_diagram\n\nClient -> Server: HTTP Request\nServer -> Database: Query\nDatabase -> Server: Results\nServer -> Client: HTTP Response\n\n# スタイリングを追加する\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# アクターを定義する\nClient: {shape: person}\nAuth Server: {shape: cloud}\nDatabase: {shape: cylinder}\n\n# 相互作用\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. 空のダイアグラムを作成する
d2_create({ id: "architecture" })

// 2. 漸進的に形状を追加する
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. プロパティを設定する
d2_oracle_set({ diagram_id: "architecture", key: "db.shape", value: "cylinder" })
d2_oracle_set({ diagram_id: "architecture", key: "web.label", value: "Web Server" })

// 4. 接続を作成する
d2_oracle_create({ diagram_id: "architecture", key: "web -> api" })
d2_oracle_create({ diagram_id: "architecture", key: "api -> db" })

// 5. 最終結果をエクスポートする
d2_export({ diagramId: "architecture", format: "svg" })

既存の内容から始める場合（統一的なアプローチ）:

// 1. 初期内容を指定してダイアグラムを作成する
d2_create({ 
  id: "architecture",
  content: "web -> api -> db\ndb: {shape: cylinder}"
})

// 2. 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. 最終結果をエクスポートする
d2_export({ diagramId: "architecture", format: "svg" })

各ツールの使用タイミング

• d2_create: 新しいダイアグラムの作成に常に使用します。空のダイアグラム（漸進的な構築用）と初期D2内容を指定する場合の両方に対応しています。
• d2_oracle_*: d2_createで作成された任意のダイアグラムに対する漸進的な変更に使用します。
• d2_export: 最終的なダイアグラムを希望の形式でレンダリングするために使用します。

開発に関する情報

テストの実行

# すべてのテストを実行する
make test

# カバレッジを含めて実行する
go test -cover ./...

# 特定のテストを実行する
go test -v ./internal/presentation/handler

コード品質の管理

# コードをフォーマットする
make fmt

# リンターを実行する
make lint

# ビルドアーティファクトをクリーンアップする
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エクスポートが機能しない場合

PNGまたはPDF形式にエクスポートする際にエラーが発生する場合は、以下のツールのいずれかをインストールしてください。

macOS:

# Homebrewを使用する
brew install librsvg
# または
brew install imagemagick

Ubuntu/Debian:

sudo apt-get install librsvg2-bin
# または
sudo apt-get install imagemagick

Windows: 公式ウェブサイトからImageMagickをダウンロードしてインストールしてください。

MCP接続に問題がある場合

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

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。

変更履歴

v0.5.0 (最新)

• ネットワーク接続のためのSSE（Server-Sent Events）トランスポートサポートを追加した
• 現代的な双方向通信のためのStreamable HTTPトランスポートサポートを追加した
• トランスポート設定のための新しいコマンドラインフラグを追加した
• Streamable HTTPでのステートフルおよびステートレスモードのサポートを追加した
• stdioトランスポートとの下位互換性を維持した
• 異なるトランスポートモードのエラーハンドリングとロギングを改善した

v0.4.0

• すべてのダイアグラム作成ニーズに対応する統一的な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ファイルを参照してください。