Typst D2 MCP

Typst D2集成

](https://github.com/dlouwers/typst-d2-mcp/releases/latest) ](https://go.dev/)   

渲染 D2图表 在 类型 文档有两个工具：

工具

1.typst-d2-prep（CLI预处理器）

• ✅ 零文件系统混乱 -无中间体 .svg 已创建的文件
• ✅ 完全支持D2功能 -所有布局（ELK、TALA、dagre）、主题、草图模式
• ✅ 内联语法 -D2代码直接嵌入 .typ 文件
• ✅ 简单的工作流程 -一个命令替换 typst compile

2.类型-d2-mcp（mcp服务器）

• 🤖 AI助手集成 -适用于Claude Desktop、Cline、OpenCode和其他MCP客户端
• 📝 鼓励使用可视化文档 -AI创建带有嵌入式D2图的Typst文档
• ✨ 单焦点工具: compile_typst_with_d2 -使用#d2\[…\]块编译Typst文档
• 🎯 最佳：生成技术文档、架构文档和插图指南

快速开始

CLI预处理器（类型-d2-rep）

安装

# Option 1: Homebrew (macOS/Linux)
brew install dlouwers/tap/typst-d2-prep

# Option 2: Download pre-built binary from GitHub Releases
# https://github.com/dlouwers/typst-d2-mcp/releases

# Option 3: Build from source
git clone https://github.com/dlouwers/typst-d2-mcp.git
cd typst-d2-mcp
go build -o typst-d2-prep ./cmd/typst-d2-prep

# Option 4: Install with go install
go install github.com/dlouwers/typst-d2-mcp/cmd/typst-d2-prep@latest

# Verify installation
typst-d2-prep version

# Verify D2 is installed
d2 --version
# If not: curl -fsSL https://d2lang.com/install.sh | sh -s --

用法

您的Typst文件（document.typ）：

= Architecture Diagram

#d2[
  client -> server -> database
]

#d2(layout: "elk", theme: "0")[
  user: User {shape: person}
  app: Application
  user -> app: Uses
]

编译：

typst-d2-prep compile document.typ
# ✅ Creates document.pdf with embedded diagrams

MCP服务器（类型-d2-MCP）

MCP服务器为AI助手提供了渲染D2图和编译Typst文档的工具。

安装

# Option 1: Homebrew (macOS/Linux)
brew install dlouwers/tap/typst-d2-mcp

# Option 2: Download pre-built binary from GitHub Releases
# https://github.com/dlouwers/typst-d2-mcp/releases

# Option 3: Build from source
git clone https://github.com/dlouwers/typst-d2-mcp.git
cd typst-d2-mcp
go build -o typst-d2-mcp ./cmd/typst-d2-mcp

# Option 4: Install with go install
go install github.com/dlouwers/typst-d2-mcp/cmd/typst-d2-mcp@latest

Claude桌面配置

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "typst-d2": {
      "command": "/opt/homebrew/bin/typst-d2-mcp"
    }
  }
}

注： 如果通过Homebrew安装，二进制文件位于 /opt/homebrew/bin/typst-d2-mcp （macOS ARM）或 /usr/local/bin/typst-d2-mcp （macOS英特尔/Linux）。如果从源构建，请调整路径。

可用工具

compile_typst_with_d2 -使用嵌入的D2图编译Typst文档

这是一个专注的工具，鼓励人工智能助手创建丰富的可视化文档。

输入：

• file_path （必填）：包含#d2\[…\]块的Typst源文件（.typ）的绝对路径

输出：

• 带有PDF路径的成功消息

该工具的描述指导AI助手：

• 使用D2图进行系统架构、流程图、ERD和技术说明
• 使用#d2\[…\]语法直接嵌入图表
• 支持所有D2功能（布局、主题、草图模式）
• 创建没有中间文件的干净文档

示例用法

User: "Create documentation for a microservices architecture"

AI assistant:
1. Creates Typst document with headings and content
2. Embeds D2 diagrams using #d2[...] blocks:
   - System architecture overview
   - Service interaction diagrams
   - Database schema (ERD)
3. Saves to .typ file
4. Calls compile_typst_with_d2 with file path
5. Returns PDF with embedded diagrams

User: "Document this API flow: client -> gateway -> auth -> service -> database"

AI assistant:
1. Creates Typst document explaining the API flow
2. Adds D2 diagram:
   #d2(layout: "elk")[
     client: Client {shape: person}
     gateway: API Gateway
     auth: Auth Service
     service: Business Service
     database: Database {shape: cylinder}
     
     client -> gateway: HTTPS
     gateway -> auth: Verify token
     auth -> service: Authorized request
     service -> database: Query
   ]
3. Saves and compiles

Result: Professional documentation with visual diagram

运作原理

1. 解析 -扫描您的 .typ 提交 #d2[...] 块
2. 提取 -从每个块中提取D2代码和选项
3. 渲染 -对于每个图表，调用 d2 - - （标准输入→stdout流媒体）
4. 编码 -将SVG转换为base64
5. 导入 -添加 #import "@preview/based:0.2.0": decode64 在顶端
6. 替换 -替代品 #d2[...] 随着 #image(decode64("..."), format: "svg")
7. 编译 -跑步 typst compile 关于已处理的文档
8. 清理 -删除临时 .typ 文件，仅保留您的原始+PDF

结果： 您的PDF包含嵌入式SVG，没有剩余文件，文件系统干净。

需求

• 转到1.23+ （用于从源构建，可选）
• D2 CLI 已安装并在PATH中：https://d2lang.com/tour/install
• 类型0.14.2+: https://github.com/typst/typst
• 类型 based 包裹：自动导入（无需手动设置）

语法参考

基本示意图

#d2[
  x -> y -> z
]

带选项

#d2(layout: "elk", theme: "0", sketch: "true")[
  direction: right
  
  user: User {
    shape: person
  }
  
  app: Application {
    ui: Web Interface
    api: REST API
  }
  
  user -> app.ui: Browse
]

可用选项

示例

看 example.typ 获取包含多个图表的完整演示，包括：

• 简单的连接
• 带有ELK布局、主题和草图模式的样式图
• 具有多级容器的复杂架构

编译它：

typst-d2-prep compile example.typ

技术细节

Base64编码 based 包裹

预处理器使用 based 用于解码base64编码SVG数据的包：

#import "@preview/based:0.2.0": decode64

#image(decode64("PD94bWwgdmVyc2lvbj0iMS4wIj..."), format: "svg")

这种方法：

• ✅ 避免原始SVG字符串的转义问题
• ✅ 与所有SVG内容可靠地工作
• ✅ 使用官方Typst包（无自定义代码）
• ✅ 正确处理二进制数据

看 实施.md 获取详细的技术文档。

与备选方案的比较

故障排除

“找不到d2命令”

安装D2：

curl -fsSL https://d2lang.com/install.sh | sh -s --

“未找到D2图表”

确保您正在使用 #d2[...] 语法（不是 #import "lib.typ").

发展

从源头构建

git clone https://github.com/dlouwers/typst-d2-mcp.git
cd typst-d2-mcp
go build -o typst-d2-prep ./cmd/typst-d2-prep

运行测试

go test -v ./...

使用Devcontainer

该项目包括一个预装了所有工具的devcontainer配置：

• 转到1.25
• D2 CLI
• Typst命令行界面
• 打毛工具（golangci lint、govulncheck等）

使用Dev Containers扩展在VS Code中打开以进行即时设置。

局限性

• 还没有手表模式 -目前仅支持单次编译
• 无增量构建 -每次编译都会重新渲染所有图表

未来改进

• \[\]智能缓存的观看模式
• \[\]增量渲染（仅更改图表）
• \[\]并行图渲染
• \[x\] 原生二进制文件（不依赖Python）- 完成
• \[\]Typst包集成

贡献

欢迎投稿！请打开问题或PR。

许可证

MIT许可证-请参阅 许可证 了解详情。

学分

• 第2页: https://github.com/terrastruct/d2
• 类型: https://github.com/typst/typst
• 基于包: https://github.com/EpicEricEE/typst-based

相关文档

• QUICKSTART.md -快速入门指南
• 实施.md -技术实施细节