D2mcp

🚀 D2 MCP 服務器

D2 MCP 服務器是一個模型上下文協議（MCP）服務器，提供 D2 圖表生成和操作功能。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 傳輸（服務器發送事件）

基於 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：用於以所需格式渲染最終圖表

📚 詳細文檔

項目結構

d2mcp/
├── cmd/                  # 應用程序入口點
├── internal/
│   ├── domain/          # 業務實體和接口
│   │   ├── entity/      # 領域實體
│   │   └── repository/  # 存儲庫接口
│   ├── usecase/         # 業務邏輯
│   ├── infrastructure/  # 外部實現
│   │   ├── d2/          # D2 庫集成
│   │   └── mcp/         # MCP 服務器實現
│   └── presentation/    # MCP 處理程序
│       └── handler/     # 工具處理程序
└── pkg/                 # 公共包

開發

運行測試

# 運行所有測試
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（服務器發送事件）傳輸支持，以實現網絡連接
• 增加了 Streamable HTTP 傳輸支持，用於現代雙向通信
• 新增用於傳輸配置的命令行標誌
• 支持 Streamable HTTP 中的有狀態和無狀態模式
• 保持與 stdio 傳輸的向後兼容性
• 改進了不同傳輸模式下的錯誤處理和日誌記錄

v0.4.0

• 簡化 API，統一使用 d2_create 滿足所有圖表創建需求
• 增強工具描述，以更好地集成 AI 助手
• 改進 Oracle API 錯誤處理和驗證
• 將 API 表面從 14 個工具減少到 10 個
• 重大變更：移除了 d2_render、d2_render_to_file、d2_import、d2_from_text，使用 d2_create 代替

v0.3.0

• 增加了 d2_oracle_serialize 工具，用於獲取圖表當前的 D2 文本表示

v0.2.0

• 增加了 D2 Oracle API 集成，用於增量式圖表操作
• 新增 6 個 MCP 工具，用於創建、修改和查詢圖表元素
• 支持有狀態的圖表編輯會話

v0.1.0

• 初始版本，具備基本的 D2 圖表操作
• 支持渲染、創建、導出和保存圖表
• 內置 20 種主題
• 集成 MCP 協議

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。