dungeondraft-mcp

dungeondraft-mcp

一个 MCP 服务，可让 Claude（或任何 MCP 客户端）读取、编辑和导出 Dungeondraft 地图。它直接处理 .dungeondraft_map 文件，因此无需运行 Dungeondraft。它还可将 Universal VTT 导出文件（.dd2vtt）转换为 Foundry VTT v13 场景。

你可以提出诸如 “在我的十字路口地图东北角建一间小酒馆”、“把这张地图改成夜景版本” 或 “把这个 dd2vtt 转成 Foundry 场景” 这样的请求。

与 Dungeondraft 或 Megasploot 无关。若要在运行中的 Dungeondraft 内实时编辑，请参阅 battlemap-mcp。两者搭配使用效果很好。

工具

工具	功能
list-maps	在已配置的文件夹中查找 .dungeondraft_map 文件
inspect-map	概要信息：大小、层级、元素计数、地形、资源包和最常用素材。可按类型和区域列出元素（节点 ID、素材、网格位置）
list-assets	按词语、类别、标签或资源包搜索内置素材和已安装的素材包
add-objects	在网格位置放置道具（旋转、缩放、镜像、图层、阴影、色调）
add-walls	添加墙体折线或封闭房间，并设置门窗；也可为现有墙体添加门
add-floors	在矩形或多边形区域铺设地板图案（木板、鹅卵石、瓷砖）
build-room	一步建成封闭墙体、匹配的地板和门
add-lights	添加点光源（范围以格为单位、颜色、强度）
add-paths	沿网格点添加路径素材
set-terrain	设置地形槽纹理（1–8）、填充一个层级，或以柔和边缘绘制矩形、圆形和线条
set-environment	设置环境光（预设：白天、阴天、黄昏、夜晚、黑暗），用于创建昼夜变体
remove-elements	删除区域内按类型筛选的元素，或按节点 ID 删除（支持 dry_run）
duplicate-map	复制地图以创建变体
export-dd2vtt	根据地图的墙体、门和光源，以及从 Dungeondraft 导出的图像，生成 .dd2vtt
dd2vtt-to-foundry-scene	将 .dd2vtt 转换为 Foundry v13 场景 JSON（网格、墙体、门、光源），并提取图像

每个编辑工具都接受 level（键、索引或标签；默认为第一个层级）和 dry_run。

坐标

所有工具都使用网格方格作为单位，从地图左上角开始测量，x 向右、y 向下。(3, 4) 是一个网格交点，而 (3.5, 4.5) 是第 3 列、第 4 行方格的中心。坐标可以是小数。Dungeondraft 内部将每个方格存储为 256 px，服务会为你完成换算。物体的位置指其中心点。旋转角度以顺时针度数表示。光源范围、路径宽度和地形羽化范围均以方格为单位。

安全

• 仅限允许的文件夹。 仅在 DD_MCP_ROOTS 指定的文件夹中读取和写入地图，该变量默认指向你的 Documents 文件夹。.. 路径和指向外部的链接会被拒绝。Dungeondraft 安装文件夹和素材文件夹为只读。
• 先备份。 每次更改前，都会将原文件复制为 <map>.bak-YYYYMMDD-HHMMSS（UTC）。
• 验证写入。 新地图会先写入临时文件，再重新解析并检查：必须逐字节往返一致；元素数量必须与编辑所添加或移除的数量相符；编辑未声明更改的每个部分都必须与之前逐字节完全相同。只有通过所有检查后，才会将临时文件重命名并覆盖原文件。如果任何检查失败，则不会写入任何内容。
• 冲突检查。 如果文件在读取后发生了磁盘更改（例如 Dungeondraft 保存了该文件），编辑会被拒绝。
• 在此处编辑前，请先在 Dungeondraft 中关闭地图，或在编辑后重新打开地图，但不要保存。否则，Dungeondraft 下次保存时会覆盖这些更改。
• 素材包许可。 不会读取任何素材包中的图像数据。对于 pack.json 中 allow_3rd_party_mapping_software_to_read: false 的素材包，只会列出其名称：不会索引其内容，且只会读取 pack.json，以便在使用这些素材包时填充地图的素材清单。

安装

需要 Node.js 20 或更高版本。

Claude Code

claude mcp add dungeondraft -s user -e DD_MCP_ROOTS="/path/to/your/maps" -- npx -y dungeondraft-mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config），然后重启 Claude Desktop：

{
  "mcpServers": {
    "dungeondraft": {
      "command": "npx",
      "args": ["-y", "dungeondraft-mcp"],
      "env": {
        "DD_MCP_ROOTS": "C:\\Users\\you\\Documents\\Dungeondraft"
      }
    }
  }
}

在 Windows 上，如果 Node 不在你的 PATH 中，请使用完整路径，例如 "command": "C:\\Program Files\\nodejs\\npx.cmd"。

从源代码安装

git clone https://github.com/casancam/Dungeondraft-MCP.git && cd Dungeondraft-MCP
npm install && npm run build
claude mcp add dungeondraft -s user -e DD_MCP_ROOTS="/path/to/maps" -- node "$PWD/dist/index.js"

配置

变量	默认值	含义
DD_MCP_ROOTS	你的 Documents 文件夹	服务可在其中读取和写入地图的文件夹，以 ; 分隔
DUNGEONDRAFT_DIR	自动检测（见下文）	Dungeondraft 安装文件夹（包含 Dungeondraft.pck 的文件夹），用于列出和验证内置素材
DD_ASSET_DIRS	无	包含 *.dungeondraft_pack 文件的 Dungeondraft 素材文件夹，以 ; 分隔。设置此变量以使用自定义素材包

DUNGEONDRAFT_DIR 会自动在 C:\Program Files\Dungeondraft 处检测（已验证），也会在 /opt/Dungeondraft 和 /Applications/Dungeondraft.app/Contents/Resources 处检测（两者均未验证）。未设置此变量时，服务仍可运行，但写入前不会检查内置素材名称。

Dungeondraft → Foundry VTT

1. 在 Dungeondraft 中：选择 File → Export → Universal VTT，并将文件保存到已配置的文件夹。
2. 对其运行 dd2vtt-to-foundry-scene。将 image_src 设置为图像在 Foundry 中的路径，例如 maps/tomb.png。
3. 将提取出的图像上传到 Foundry（或 The Forge Assets Library）中的该路径。
4. 在 Foundry 中创建场景，右键单击该场景，选择 Import Data，然后选择 <name>.foundry-scene.json。

光源半径使用 dim = range × grid distance 和 bright = dim / 2。Dungeondraft 会将光照烘焙到图像中，因此如果 Foundry 中的光照看起来重复，请传入 include_lights: false。窗户会导出为门，因为 .dd2vtt 不会区分窗户和门。

如果你在导出后更改了墙壁、门或光源，请使用 export-dd2vtt。渲染地图图像需要 Dungeondraft，因此请从 Dungeondraft 导出整张地图的 PNG/WEBP，并将工具指向该文件。docs/foundry-import.md 介绍了在 Foundry 中实现实时导入器所需的内容。

已知限制

• 水体、洞穴、涂绘材质、屋顶和文本会保留，但无法编辑。文本和地面图案可以列出并移除。
• 地面图案会绘制在地形上方。如果笔画被地面图案遮挡，set-terrain 会发出警告。
• export-dd2vtt 不会写入 objects_line_of_sight。
• 已在 Windows 上使用 Dungeondraft 0.9.4 至 1.2.0.1 的地图文件（格式 2 和 3）进行测试。

开发

npm install
npm run fixtures       # download public sample maps used by some tests (not redistributed)
npm test               # vitest
npm run build
node scripts/smoke.mjs # end-to-end over MCP stdio on a temp copy of the test map

测试使用真实的 Dungeondraft 1.2.0.1 地图（test/fixtures/mcp_test.dungeondraft_map）、公开的示例地图（格式 2 和 3，最大 14 MB、包含 4 个图层）以及合成资源包。测试会检查：

• 往返转换后字节完全一致
• 在所有示例地图中验证门的位置
• 每次编辑后未修改的部分保持不变
• 地图 → UVTT 几何数据与 Dungeondraft 自带的 .dd2vtt 导出结果一致
• 资源包列表、验证和退出选项

需要安装 Dungeondraft 或下载示例地图的测试，在缺少这些内容时会跳过。文件格式说明以及各项结论的验证方式见 docs/research.md。

鸣谢

• 格式研究基于 Ryex/Dungeondraft-GoPackager（资源包格式）和 Arkenforge Universal VTT 说明。
• 测试用示例地图来自 GitHub 上的 Akesari12、pleonr、watermelonwolverine 和 lordhaywire。测试时会下载这些地图，不会将其随项目附带。

许可证

MIT