DWG MCP Server

DWG MCP 服务

通过 MCP 让 AI 访问 DWG 和 DXF 文件格式。

将 DWG 和 DXF 文件连接到 Claude、ChatGPT、Codex、Cursor 等 MCP 客户端。 DWG MCP 服务提供对 DWG 数据的结构化访问，让 AI 能够理解并推理图纸内容。源文件始终保持只读；支持的实体属性可在内存中更改，以供检查和渲染。

快速开始

使用你选择的 MCP 客户端运行 DWG MCP 服务。 npm 包会在首次使用时从 GitHub Releases 下载匹配的原生构建版本，验证其 SHA-256 校验和，将其缓存，然后直接运行。 无需使用 Docker 或单独安装 Python。

原生安装程序

macOS Apple Silicon：

curl -fsSL https://raw.githubusercontent.com/dimitrovakulenko/dwg-mcp-server/main/scripts/install.sh | sh

Windows x64（PowerShell）：

irm https://raw.githubusercontent.com/dimitrovakulenko/dwg-mcp-server/main/scripts/install.ps1 | iex

这两个安装程序都会下载最新的原生发行版本，并在安装前验证其 SHA-256 校验和。

安装后，将 MCP 客户端指向已安装的可执行文件。在 macOS 上，先将 ~/.local/bin 添加到 PATH，或者使用安装程序报告的绝对路径：

claude mcp add --scope user --transport stdio dwg-mcp -- dwg-mcp-server

如果你的 MCP 客户端、AI Agent 或测试工具不支持 MCP roots，请将 DWG_MCP_ALLOWED_ROOTS 设置为允许访问的文件夹。

Codex

codex mcp add dwg-mcp \
  --env DWG_MCP_ALLOWED_ROOTS="$HOME" \
  -- npx -y @dmytro-prototypes/dwg-mcp-server

Codex 目前不会向 stdio MCP 服务提供 MCP 客户端 roots。请为包含图纸的文件夹配置明确的允许访问目录。

Claude

claude mcp add --scope user --transport stdio dwg-mcp -- npx -y @dmytro-prototypes/dwg-mcp-server

Claude Code 会提供 MCP roots，因此通常无需设置额外的路径变量。

Cursor

{
  "mcpServers": {
    "dwg-mcp": {
      "command": "npx",
      "args": ["-y", "@dmytro-prototypes/dwg-mcp-server"]
    }
  }
}

暴露的工具

工具	用途
dwg.list_roots	列出可用于访问 DWG 的文件夹。
dwg.open_file	从可用文件夹中打开 DWG 或 DXF，并返回 documentId。
dwg.close_file	关闭已打开的文档并释放其工作进程。
dwg.list_types	列出后端支持的所有 DWG 类型。
dwg.list_file_types	仅列出特定已打开 DWG 中包含的类型。
dwg.describe_type	描述受支持的类型，包括可读和可写属性及其默认投影。
dwg.get_objects	按句柄获取指定对象，保留请求顺序并报告缺失的句柄。
dwg.query_objects	使用筛选条件、范围、关系遍历、排序、投影和分页查询对象。
dwg.set_entity_properties	在内存中更改单个实体上标记为可写的属性。关闭文档时会丢弃这些更改。
dwg.list_render_views	列出可渲染的模型空间、图纸空间布局和布局视口。
dwg.render_view	将完整视图或选定的图纸区域渲染为 PNG 或 SVG。

典型流程如下：

1. 使用 dwg.list_roots 发现可用文件夹。
2. 使用 dwg.open_file 打开其中一个文件夹里的文件。
3. 使用 dwg.list_types、dwg.list_file_types 或 dwg.describe_type 检查受支持的类型或文件中的类型。
4. 使用 dwg.get_objects 获取已知句柄对应的对象，或使用 dwg.query_objects 搜索图纸。
5. 可选：使用 dwg.set_entity_properties 更改报告为可写的属性。
6. 使用 dwg.list_render_views 和 dwg.render_view 发现并渲染图纸视图。
7. 使用 dwg.close_file 关闭会话，并丢弃内存中的更改。

架构

运行时模型

在打包部署中，DWG MCP 服务是为宿主操作系统构建的独立原生应用程序。 Python 宿主提供 MCP 工具、验证文件访问权限并管理文档会话。

每次调用 dwg.open_file，都会为该 DWG 启动一个专用的 Rust dwg-worker 进程，并返回宿主端的 documentId。 后续所有针对文件的调用都会使用该文档 ID。 dwg.close_file 会终止该会话对应的工作进程。

工作进程和查询模型

Rust 工作进程通过 stdin 和 stdout 使用以换行符分隔的 JSON。 它通过 LibreDWG 打开 DWG 时，会先构建一个内存中的索引文档。 这一步预先建立索引是设计的核心：服务器在打开文件时一次性承担开销，之后针对索引处理请求，而不是每次都重新扫描 DWG。

索引模型存储对象句柄、种类、类型名称、通用类型、摘要和完整属性，以及派生出的块、布局和空间成员关系。 它还存储支持的类型元数据，例如别名、默认投影和属性定义。

请求完整对象记录时，响应还会在 extendedData 中包含派生的成员关系，其中包括已知时的容器块、布局以及模型空间或图纸空间。

dwg.get_objects 按句柄直接查找。 dwg.query_objects 会在句柄、类型、通用类型、种类、精确属性值、块、布局和空间的索引上运行，然后应用筛选条件、作用域、关系遍历、排序、投影和分页。 因此，在已打开的图纸上查询块、图层、布局、引用和相关对象变得切实可行。

dwg.set_entity_properties 会根据类型目录验证写入内容，更新 原生 LibreDWG 文档，重建索引，并使缓存的渲染场景失效。块引用 插入点使用 OCS 坐标，并强制执行块缩放规则；在能够安全转换 其所属属性之前，会拒绝带属性的块引用。该工具不会保存或 覆盖源文件。

工作进程会在首次调用渲染时延迟编译单独的渲染场景。 它会展开块引用和生成的标注块，绘制常见的 2D 几何图形、文本、MTEXT、填充边界和近似处理的点列表实体， 并通过视口合成图纸空间布局。SVG 是规范的 渲染输出；PNG 则从同一 SVG 在内存中栅格化生成。渲染响应 包含生成块回退和不支持的实体类型的覆盖诊断。自动适配会拒绝极端稀疏的范围，WIPEOUT 边界会遮挡较早绘制的几何图形，而显式区域则允许对密集视图进行有界渲染。有关协议和 渲染模型，请参阅 docs/rendering.md。

访问和打包

DWG 和 DXF 文件必须从 dwg.list_roots 列出的根目录打开。服务器首先 会向 MCP 客户端请求根目录。如果客户端、AI Agent 或测试框架不 支持 MCP 根目录，请配置明确允许的根目录：

python3 -m dwg_mcp_server --allowed-root "$HOME/Downloads"

或：

DWG_MCP_ALLOWED_ROOTS="$HOME/Downloads;$HOME/Documents/dwg" \
python3 -m dwg_mcp_server

DWG_MCP_ALLOWED_ROOTS 是为不支持根目录的客户端提供的授权回退机制。 它应为以分号分隔的绝对目录列表。

官方发行版包含独立的 MCP 主机、静态链接的 Rust 工作进程，以及运行时所需的 LibreDWG 架构文件。

原生平台

GitHub Actions 会在以下原生运行器上构建并测试这些发行产物：

系统	CPU	Rust 目标
macOS	Apple Silicon	aarch64-apple-darwin
Windows	64 位 Intel 或 AMD	x86_64-pc-windows-gnu
Linux	64 位 Intel 或 AMD	x86_64-unknown-linux-gnu
Linux	64 位 ARM	aarch64-unknown-linux-gnu

x64、x86_64 和 AMD64 指的是相同的 CPU 架构；Windows 和 Linux 产物均适用于 Intel 和 AMD 处理器。

从源代码构建和测试

默认情况下，本地源代码构建使用 vendored 的 third_party/libredwg 子模块。

先决条件

• Rust 工具链
• Python 3.11 或更高版本
• 在 macOS 或 Linux 上本地构建 LibreDWG 所需的 autotools（autoreconf、aclocal、automake、autoconf、make）

引导

git submodule update --init --recursive
bash scripts/build-libredwg.sh

构建和测试

cargo test --workspace
bash scripts/run-e2e-tests.sh

在本地运行 MCP 主机

Python 主机会在 target/release 或 target/debug 下查找 dwg-worker。 如果要显式构建 release 版本：

cargo build -p dwg-worker --release

然后运行 MCP 主机：

PYTHONPATH=server/src python3 -m dwg_mcp_server

如果工作程序二进制文件位于其他位置，请将 DWG_WORKER_BIN 设置为该可执行文件。

发布原生版本

1. 在 npm/package.json、server.json 和 Claude 扩展清单（如适用）中设置相同的版本。
2. 为 .github/workflows/native-release.yml 配置 npm 可信发布。
3. 推送匹配的 v<version> 标签。

Native Release 工作流会构建并测试所有四个平台，创建包含校验和文件的 GitHub Release，然后发布 npm 启动器。手动运行工作流可以构建一个选定平台或全部四个平台，并将其作为可下载的 Actions 构建产物，但不会发布。

清理并重新构建

移除本地 Rust 和 Python 构建产物：

bash scripts/clean-build-artifacts.sh

若要同时清除 third_party/libredwg 下主机的 LibreDWG 构建产物：

bash scripts/clean-build-artifacts.sh --with-libredwg

官方 MCP Registry

注册表元数据位于 server.json 中，使用经过 GitHub 身份验证的名称 io.github.dimitrovakulenko/dwg-mcp-server。

发布新的注册表版本前：

1. 从 npm/ 发布匹配的 npm 包版本。
2. 确认 npm/package.json 中的 mcpName 与 server.json 中的相同。
3. 运行手动的 Publish MCP Registry GitHub Actions 工作流，或运行：

mcp-publisher login github
mcp-publisher publish

注册表会验证已发布的 npm 包，因此 server.json 必须指向公共 npm 注册表中已存在的 npm 版本。

许可证

本项目采用 GNU 通用公共许可证第 3 版授权。 完整许可证文本请参见 LICENSE。