内容
# d2-mcp-rs
[](https://github.com/Stranmor/d2-mcp-rs/actions/workflows/ci.yml)
[](LICENSE)
[](rust-toolchain.toml)
[](https://modelcontextprotocol.io/)
[](https://d2lang.com/)
无需给予代理任意 shell 访问权限，即可从 MCP 客户端渲染、验证和格式化 D2 图表。
`d2-mcp-rs` 是一个小型 Rust MCP 服务器，它封装了官方 D2 CLI，提供类型化的工具、有界文件输出、结构化工件报告和默认关闭的远程资产获取。它适用于需要重复创建架构图、 安全、且以人类可以直接打开的格式呈现的 AI 代理。
## 功能特点
| 工具 | 目的 | 副作用 |
| --- | --- | --- |
| `d2_status` | 报告 D2 可用性、服务器限制、支持的输出格式和安全策略。 | 无 |
| `d2_layouts` | 列出配置的 D2 CLI 中可用的布局引擎。 | 无 |
| `d2_themes` | 列出配置的 D2 CLI 中可用的主题。 | 无 |
| `d2_validate` | 验证 D2 源文本并返回结构化诊断信息。 | 无 |
| `d2_format` | 格式化 D2 源文本并返回格式化后的源文本。 | 无 |
| `d2_render` | 将 D2 源文本渲染为 SVG 或 PNG，并返回输出路径、哈希值、字节、诊断信息和可选的内联 SVG。 | 仅写入 `D2_MCP_WORKDIR` |
## 为什么存在
AI 代理可以草拟图表，但原始 shell 执行是重复图表工作的错误接口。代理需要一个狭窄的契约：
- 没有直通 shell 命令工具；
- 每个输入和输出的 JSON 模式；
- 一个配置的输出目录；
- 路径遍历拒绝；
- 源和渲染大小限制；
- 进程超时；
- 默认阻止远程 `http://` 和 `https://` 资产，除非显式请求；
- 真实的 D2 渲染行为，因为官方 `d2` 二进制文件仍然是渲染器。
## 快速开始
首先安装 D2：
```bash
curl -fsSL https://d2lang.com/install.sh | sh -s --
d2 --version
```
从 GitHub 安装 MCP 服务器：
```bash
cargo install --git https://github.com/Stranmor/d2-mcp-rs.git d2-mcp
```
创建输出目录：
```bash
mkdir -p "$HOME/d2-mcp-output"
```
将其添加到您的 MCP 客户端：
```json
{
"mcpServers": {
"d2": {
"command": "d2-mcp",
"env": {
"D2_MCP_WORKDIR": "/home/you/d2-mcp-output"
}
}
}
}
```
然后要求您的 MCP 客户端渲染图表：
```json
{
"source": "client -> d2_mcp -> d2_cli -> svg",
"format": "svg",
"output_path": "architecture/current.svg",
"overwrite": true,
"inline_svg": true
}
```
有关绝对路径设置的示例，请参见 [客户端配置示例](docs/client-configs.md)。
## 示例图表源
```d2
user: 用户请求
agent: MCP 客户端
server: d2-mcp-rs
d2: 官方 D2 CLI
artifact: SVG 或 PNG 工件
user -> agent: 请求图表
agent -> server: 调用 d2_validate / d2_render
server -> d2: 调用有界 D2 命令
d2 -> server: 渲染工件
server -> agent: 结构化报告
agent -> user: 分享最终图表
```
## 工具详情
主要工具文档在 [docs/tools.md](docs/tools.md) 中。简要版本：
- 在渲染之前使用 `d2_status` 以确认 D2 二进制文件和限制；
- 使用 `d2_layouts` 和 `d2_themes` 在不访问 shell 的情况下选择有效的渲染选项；
- 在源自模型的最终渲染之前使用 `d2_validate`；
- 在存储生成的 D2 源时使用 `d2_format`；
- 对于最终 SVG/PNG 输出，使用 `d2_render`。
## 配置
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `D2_MCP_D2_BIN` | `d2` | D2 可执行文件路径或命令名称。 |
| `D2_MCP_WORKDIR` | 当前进程目录 | 渲染文件可以写入的唯一目录。 |
| `D2_MCP_MAX_SOURCE_BYTES` | `1048576` | 最大 D2 源输入大小。 |
| `D2_MCP_MAX_RENDER_BYTES` | `16777216` | 最大渲染工件大小。 |
`d2_render` 中的 `output_path` 必须相对路径。绝对路径和 `..` 组件被拒绝。
## 安全模型
`d2-mcp-rs` 限制了 MCP 客户端可以执行的操作。它并不声称自己可以隔离 D2 渲染器本身。
服务器：
- 从 MCP 调用中接受 D2 源文本；
- 从不暴露通用 shell 命令；
- 从不读取任意用户文件作为工具功能；
- 仅在 `D2_MCP_WORKDIR` 内写入渲染工件；
- 拒绝绝对路径和父目录遍历；
- 默认阻止远程资产；
- 使用显式参数调用配置的 D2 二进制文件；
- 在超时时间超过时终止 D2 进程。
如果您故意需要远程图标或图像：
```json
{
"allow_remote_assets": true
}
```
仅在工作区策略允许在渲染过程中进行网络获取时使用。请参阅 [docs/security-model.md](docs/security-model.md) 以了解完整的边界。
## 开发
```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
```
集成烟雾测试在内存中启动 MCP 服务器，列出工具，检查结构化输出模式，调用只读发现工具，在安装 D2 时渲染真实的 SVG，并验证路径遍历拒绝。
## 项目状态
当前目标是一个可靠、 小巧、 适合代理的安全 D2 MCP 服务器，而不是一个完整的图表管理系统。 文件读取工具、 项目范围的图表发现和图表资产库应仅作为具有自己路径策略的单独狭窄范围的工具添加。
## 许可证
MIT
