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 文件。