D2 MCP Server

D2 MCP 服务

一个提供 D2 图表生成和编辑功能的模型上下文协议（MCP）服务。

D2 是一种现代图表脚本语言，可以将文本转换为图表。此 MCP 服务允许 Claude 等 AI 助手以编程方式创建、渲染、导出和保存 D2 图表。

该服务提供 16 个 MCP 工具，用于完整源码编写、验证、渲染、内置 D2 指引和增量 Oracle 编辑。

借助新的 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 安装

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 Registry

发布标签会将此服务发布到官方 MCP Registry，名称为 io.github.RecursiveFunctions/d2mcp。Registry 发布与编辑器图库索引彼此独立，因此新发布的版本可能不会立即出现在编辑器的搜索结果中。

兼容的客户端也可以使用此仓库中的便携式 .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 传输（服务器发送事件）

支持网络连接的基于 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 源码或已存储图表的当前源码。请准确提供一个输入：

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

{
  "diagram_id": "my-diagram"
}

对于无效的 D2，会返回成功的结构化结果，其中包含 valid: false 和编译器诊断。对于简单且明确的终止符错误，也可能包含 repaired_content；验证不会修改已存储的图表。

d2_get_source 和 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 和 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"
}

返回图表的完整 D2 文本，包括通过 Oracle API 进行的所有修改。

创建序列图

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# 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. 确认配置中的路径为绝对路径

贡献

欢迎贡献！请随时提交 Pull Request。

更新日志

v0.5.0（最新）

• 添加 SSE（Server-Sent Events）传输支持，实现网络连接
• 添加 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 文件。