内容
# dungeondraft-mcp
一款让大型语言模型（LLM，如Claude Code、Claude Desktop等）驱动**正在运行的Dungeondraft实例**的MCP服务器 — 放置对象、绘制墙壁、检查地图 — 通过Dungeondraft的GDScript模组API。
Dungeondraft没有内置的服务器来通信，因此该项目分为**两部分**，通过本地套接字连接：
```
Claude / MCP 客户端
│ MCP (标准输入/输出)
▼
服务器/ ── Python MCP 服务器 (此仓库)
│ TCP上的换行符分隔JSON (127.0.0.1:8787)
▼
模组/ ── Dungeondraft 模组 (GDScript，在DD内运行)
│ 模组API调用
▼
打开的地图 (对象、墙壁、关卡、…)
```
模组在Dungeondraft内打开一个TCP服务器，并从`update(delta)`钩子每帧轮询它；Python端将每个功能作为MCP工具公开，并将调用转发为JSON。有关线路格式，请参见[PROTOCOL.md](PROTOCOL.md)。
> **状态：正常工作。** 已针对 **Godot 3.4.2** 上的Dungeondraft进行端到端确认 — 模组沙盒中的原始TCP有效，无需备用。39种工具，涵盖查询/创建/修改/地形/关卡/选择/捕获/相机/撤销（见下文）。
## AI可以执行的操作
- **检查：** `get_status`、`list_levels`、`list_elements`、`get_element`、`list_asset_categories`、`list_assets`（带有子字符串搜索）。
- **创建：** `place_object`、`draw_wall`、`draw_path`、`add_light`、`add_portal`、`add_roof`、`add_text`、`place_pattern`（瓷砖地板形状 — 木板、瓷砖、砖块 — 在对象下渲染）、`build_room`（一个墙环 + 一个共享路径上的匹配地板，如UI的组合跟踪）。
- **地形：** `set_terrain_slot`、`fill_terrain`（整个关卡）、`fill_region`（一个矩形/多边形，例如一个房间的地板）、`paint_terrain`（软笔刷）、`paint_path`（沿多边形路径的平滑连续笔画 — 道路/小径）。
- **洞穴：** `dig_cave`沿路径雕刻洞穴/隧道（洞穴笔刷 — 挖掘岩石中的地板，带有自动岩石墙壁 + 碎屑；`dig=false`填充回去；可选的地面/墙壁色调）、`clear_caves`清除整个洞穴层。
- **编辑：** `move_element`、`modify_object`、`duplicate_object`、`delete_element`、`select_elements`、`clear_selection`。
- **关卡：** `add_level`、`set_level`。
- **查看：** `screenshot`（当前窗口）和`export_map`（干净的全地图渲染）返回图像，以便模型可以查看自己的作品并迭代。
- **相机：** `get_camera`、`set_camera`、`focus_element`（聚焦在一个元素上）、`fit_elements`（框架一组）— 在`截图`之前指向视图，以检查特定位置，如墙上的门。
- **撤销：** 桥梁保留其自己的撤销/重做堆栈，用于创建/移动/修改/地形编辑，因此`undo` / `redo`让模型可靠地反转自己的更改（独立于Dungeondraft的Ctrl+Z；`delete_element`不可逆转）。
每个元素都由整数`id`引用；创建和列表调用返回id，您将其反馈到编辑调用中。坐标是woxel（像素）空间 — 调用`get_status`获取`map_center`。使用`list_assets`发现资产。
## 设置
**先决条件：** [Dungeondraft](https://dungeondraft.net/) （在Godot 3.4.2版本上测试）、Python **3.10+** 和MCP客户端（例如Claude Code或Claude Desktop）。在Windows上，`python`/`.venv\Scripts\`替换所示的`python3`/`.venv/bin/`路径。
### 1. 将模组安装到Dungeondraft中
1. 在Dungeondraft的标题屏幕上，打开**模组**并记下（或设置）您的模组文件夹。
2. 将`mod/dungeondraft-mcp-bridge/`复制到该文件夹中。
3. 在模组列表中启用**MCP Bridge**，然后打开或创建地图。
加载时，您应该在Dungeondraft日志中看到：
```
[mcp-bridge] 监听 127.0.0.1:8787 (协议 v6)
```
### 2. 安装MCP服务器
安装到专用虚拟环境中（大多数发行版的系统Python都是外部管理的，因此虚拟环境保持入口点清洁和稳定）。从仓库根目录运行：
```bash
python3 -m venv .venv
.venv/bin/pip install -e ./server
```
这安装了`dungeondraft_mcp`包并创建了入口点`.venv/bin/dungeondraft-mcp`。
### 3. 验证桥梁是否正常工作
打开DD并加载地图后，运行每个命令的验证器。它在地图中心附近构建一个小型临时场景，为每个命令打印PASS/FAIL，然后删除它创建的内容：
```bash
.venv/bin/python server/test_bridge.py
```
如果它无法连接 *并且* 您在DD的日志中从未看到`listening`行，则沙盒阻止了`TCP_Server` — 请参见[PROTOCOL.md](PROTOCOL.md)中的备用注释。
要*看到*某些内容被构建（一个小型家具房间保留在地图上，而不是自我清理测试），请运行`.venv/bin/python server/demo_build.py`。
### 4. 连接您的MCP客户端
通过其**绝对路径**注册入口点。对于**Claude Code**：
```bash
claude mcp add dungeondraft -s user -- "$PWD/.venv/bin/dungeondraft-mcp"
```
重启Claude Code以加载服务器（/mcp显示其状态和工具）。或添加到客户端配置（例如Claude Desktop `claude_desktop_config.json`），使用绝对路径：
```json
{
"mcpServers": {
"dungeondraft": {
"command": "/绝对路径/到/dungeondraft-mcp/.venv/bin/dungeondraft-mcp"
}
}
}
```
然后询问模型类似“我的Dungeondraft地图状态如何？”或“列出一些对象资产并在地图中心放置一把椅子。”
## 配置
这些环境变量配置**Python服务器**（在MCP客户端启动时设置它们）。默认设置与模组匹配，因此您只需在更改模组的`HOST` / `PORT`常量时使用它们 — 两半必须一致。
| 环境变量 | 默认值 | 目的 |
| --- | --- | --- |
| `DD_BRIDGE_HOST` | `127.0.0.1` | 服务器连接的主机 |
| `DD_BRIDGE_PORT` | `8787` | 服务器连接的端口（匹配模组的`PORT`） |
## 扩展
添加功能是对称的 — 每个侧面都有一个处理程序：
1. **模组** (`mod/.../scripts/tools/mcp_bridge.gd`)：在 `_safe_dispatch()` 中的 `match` 添加一个 `case`，并添加一个返回 `_ok(...)` / `_err(...)` 的 `_my_command(req)` 函数。
2. **服务器** (`server/dungeondraft_mcp/server.py`)：添加一个调用 `bridge.request("my_command", ...)` 的 `@mcp.tool()`。
良好的下一个目标：图案形状（地板）、区域范围的地形填充和将一批编辑操作组合成单个撤销步骤。
### 开发循环（在迭代模组之前阅读）
如果您不事先了解这两点，它们将会给您带来麻烦：
- **编辑模组和服务器有不同的重新加载路径。** `mcp_bridge.gd`中的GDScript更改在您**重新加载DD内的模组**（或重启DD）时生效。`server.py`中的新或更改的`@mcp.tool()`定义仅在**MCP服务器进程重启**后出现 — 在Claude Code中，这意味着`/mcp` → 重新连接`dungeondraft`（或重启客户端）。安装是可编辑的（`pip install -e`），因此您永远不需要重新安装；您只需循环该进程。添加*新工具*需要**两次**重新加载（模组用于处理程序，服务器用于工具注册）；更改*现有*处理程序的行为只需要重新加载模组。
- **没有实时的`eval`/内省命令，** 因此探测正在运行的节点的属性需要重新加载模组。当DD API表现不佳时（例如，设置器不生效），一种快速的诊断方法是**在响应中返回中间状态** — 在调试字段中存储前后值 — 因此一次重新加载显示值更改的位置。
## 布局
```
mod/dungeondraft-mcp-bridge/ Dungeondraft模组（复制到DD的模组文件夹中）
mcp_bridge.ddmod 清单文件
scripts/tools/mcp_bridge.gd TCP服务器 + 命令处理程序
服务器/ Python MCP服务器
dungeondraft_mcp/server.py MCP工具定义
dungeondraft_mcp/bridge_client.py TCP/JSON客户端
test_bridge.py 独立的每个命令冒烟测试
demo_build.py 构建一个可见的示例房间并保留它
PROTOCOL.md 线路协议 + 实现说明
```
## 致谢
基于 [Dungeondraft Modding API](https://megasploot.github.io/DungeondraftModdingAPI/) 构建。
引擎是Godot 3.4.2，因此GDScript使用Godot 3网络类名。
## 许可证
[MIT](LICENSE).
