内容
<p align="center">
<img src="assets/logo.png" alt="Defold MCP" width="520" />
</p>
# Defold MCP 服务器
一个 [MCP](https://modelcontextprotocol.io) 服务器，为 AI 编程代理提供一流的访问 [Defold](https://defold.com) 游戏引擎的能力：检查和编辑项目，构建和打包，使用 bob，本地运行游戏，热重载代码到正在运行的游戏，驱动正在运行的引擎，搜索官方 API 参考。
所有操作都在后台进行 — 不需要 Defold 编辑器。一个 [桌面应用程序](desktop) 管理服务器，将其活动流式传输到实时控制台，并自动配置 AI 代理。
## 功能
- **项目智能** — 解析 `game.project`、集合、游戏对象、GUI 场景、图集和任何其他文本格式的资源到结构化的 JSON；概述 Lua 脚本（函数、`go.property` 定义、需求、处理的 消息）；查找任何资产的引用，然后再重命名或删除它。
- **构建流水线** — 下载/缓存每个 Defold 版本的 `bob.jar`，编译并带有结构化错误诊断（资源、行、消息），为所有支持的平台打包，解析依赖项。
- **运行和调试循环** — 下载/缓存 `dmengine` 开发二进制文件，在后台启动游戏，增量读取其日志，优雅地停止它。
- **实时引擎控制** — 热重载更改的脚本/资源到正在运行的游戏（与编辑器使用的相同机制），切换 profiler 和物理调试，设置帧率上限和 vsync，录制游戏视频，重启或退出引擎，通过 TCP 流式传输引擎日志 — 包括从编辑器启动的游戏和网络上的设备。
- **视觉反馈** — 将正在运行的游戏截图为图像，代理可以直接查看，以验证渲染、布局和 UI（不仅仅是日志）。
- **API 文档** — 搜索和阅读构建的精确引擎版本的官方 Defold API 参考（go、gui、msg、sys、physics、render、编辑器脚本、原生扩展 SDK，...）。
## 要求
- **Node.js >= 18**
- **Java（JDK 17+，推荐 21+）** — 仅用于构建工具（`defold_build`、`defold_bundle`、`defold_resolve_dependencies`）。其他所有操作都无需 Java。从 [Adoptium](https://adoptium.net) 或 `brew install openjdk` 安装。
- 在首次使用 Defold 版本时，需要网络访问（从官方 Defold 服务器下载 `bob.jar`、`dmengine`、API 文档到 `~/.defold-mcp`）。
## 安装
```bash
git clone https://github.com/Fulviuus/defold-mcp.git && cd defold-mcp
npm install
npm run build # 生成 dist/index.js
npm test # 可选：46 个单元测试 + 端到端测试
```
## 桌面应用程序（推荐用于多代理设置）
一个 Tauri 应用程序在 [`desktop/`](desktop) 中为您管理服务器：一个实时控制台，显示服务器执行的所有操作（每次工具调用、构建输出、引擎日志），启动/停止并选择主机/端口，一键配置 AI 代理（Claude Code、Claude Desktop、Codex CLI、Cursor、Gemini CLI、VS Code Copilot、Windsurf、Cline、Zed）。
```bash
cd desktop
npm install
npm run dev # 运行应用程序（需要 Rust 工具链）
npm run build # 生成可分发的包（.app / .msi / .deb）
```
在应用程序中：选择主机/端口 → **启动服务器** → 从下拉菜单中选择一个代理 → **配置**。应用程序将 `defold` 条目合并到该代理自己的配置文件中（备份原始文件），指向 `http://127.0.0.1:<port>/mcp`。所有连接的代理都共享此服务器实例，其活动流式传输到控制台。
## 传输
服务器支持两种 MCP 传输：
- **stdio（默认）** — 客户端启动服务器本身：`node dist/index.js`
- **可流式 HTTP** — 一个长期运行的服务器，多个客户端连接：`node dist/index.js --transport http --host 127.0.0.1 --port 9810`（MCP 端点在 `/mcp`，状态在 `/health`）。这是桌面应用程序运行的内容。启用了环回绑定上的 DNS 重新绑定保护；绑定 `0.0.0.0` 可以用于 LAN 使用，但将端点暴露给您的网络 — 仅在受信任的网络上执行此操作。
### Claude Code
```bash
claude mcp add defold -- node /path/to/defold-mcp/dist/index.js
```
或在 `.mcp.json` 中：
```json
{
"mcpServers": {
"defold": {
"command": "node",
"args": ["/path/to/defold-mcp/dist/index.js"],
"env": { "DEFOLD_PROJECT_ROOT": "/path/to/your/game" }
}
}
}
```
### OpenAI Codex CLI
```bash
codex mcp add defold \
--env DEFOLD_PROJECT_ROOT=/path/to/your/game \
--env JAVA_HOME=/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home \
-- node /path/to/defold-mcp/dist/index.js
```
或在 `~/.codex/config.toml` 中：
```toml
[mcp_servers.defold]
command = "node"
args = ["/path/to/defold-mcp/dist/index.js"]
startup_timeout_sec = 30 # 默认 10
tool_timeout_sec = 600 # 默认 60 — 对于 defold_build/defold_bundle 来说太短了
[mcp_servers.defold.env]
DEFOLD_PROJECT_ROOT = "/path/to/your/game"
JAVA_HOME = "/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home"
```
两个 Codex 特有的注意事项：
- **提高 `tool_timeout_sec`**（默认 60 秒）：第一个构建下载平台包，可能需要几分钟；Codex 会杀死较慢的工具调用。
- **Codex 净化服务器环境**（只有 `HOME`、`PATH`、`USER` 等存活）。`JAVA_HOME` 和 `DEFOLD_PROJECT_ROOT` 不是从 shell 继承的 — 在 `env` 表中设置它们，或使用 `env_vars = ["JAVA_HOME"]` 白名单 shell 变量。
### Gemini CLI
```bash
gemini mcp add -s user \
-e DEFOLD_PROJECT_ROOT=/path/to/your/game \
-e JAVA_HOME=/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home \
defold node /path/to/defold-mcp/dist/index.js
```
（或相同的 `mcpServers` JSON 块在 `~/.gemini/settings.json` 中；注意 `gemini mcp add` 默认范围是 *项目* — `-s user` 使其成为全局的。每个服务器的 `"timeout"` 以毫秒为单位，默认 600000。）
### Cursor / Claude Desktop / Windsurf / Cline
所有这些都使用相同的 `mcpServers` JSON 形状 — 只有文件位置不同：
| 客户端 | 文件 |
|---|---|
| Cursor | `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局） |
| Claude Desktop | `claude_desktop_config.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Cline | Cline 面板 → MCP 服务器 → 配置（`cline_mcp_settings.json`） |
```json
{
"mcpServers": {
"defold": {
"command": "node",
"args": ["/path/to/defold-mcp/dist/index.js"],
"env": {
"DEFOLD_PROJECT_ROOT": "/path/to/your/game",
"JAVA_HOME": "/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home"
}
}
}
}
```
在 Cursor 中，`"DEFOLD_PROJECT_ROOT": "${workspaceFolder}"` 有效。Cursor 只会将大约 40 个工具转发给代理，跨所有服务器 — 如果达到上限，请禁用未使用的服务器。
### VS Code（GitHub Copilot 代理模式）
`.vscode/mcp.json` — 注意顶级键是 `servers`，而不是 `mcpServers`：
```json
{
"servers": {
"defold": {
"type": "stdio",
"command": "node",
"args": ["/path/to/defold-mcp/dist/index.js"],
"env": { "DEFOLD_PROJECT_ROOT": "${workspaceFolder}" }
}
}
}
```
### Zed
`~/.config/zed/settings.json` — Zed 称它们为 `context_servers`：
```json
{
"context_servers": {
"defold": {
"command": "node",
"args": ["/path/to/defold-mcp/dist/index.js"],
"env": { "DEFOLD_PROJECT_ROOT": "/path/to/your/game" }
}
}
}
```
### 任何其他 MCP 客户端
服务器是一个标准的 stdio MCP 服务器，因此任何支持 MCP 的客户端都可以使用。你只需要配置三个东西：
1. **启动**: `node /path/to/defold-mcp/dist/index.js`
2. **`DEFOLD_PROJECT_ROOT`**（可选）：如果代理的工作目录在游戏项目内，服务器通过向上搜索找到 `game.project`，因此不需要环境变量。
3. **`JAVA_HOME`**（可选）：仅在 `defold_build`/`defold_bundle`/`defold_resolve_dependencies` 需要 `java` 而且不在客户端给服务器的 PATH 上时需要。
如果客户端强制执行每个工具的超时，请为构建工具（第一次构建可能需要几分钟）增加超时时间。
### 环境变量
| 变量 | 用途 |
|---|---|
| `DEFOLD_PROJECT_ROOT` | 默认项目根目录（包含 `game.project` 的目录）。工具也接受显式的 `project_root` 参数，并从工作目录向上搜索作为后备。 |
| `DEFOLD_MCP_CACHE_DIR` | 工具链缓存目录（默认 `~/.defold-mcp`）。 |
| `JAVA_HOME` | 用于运行 bob.jar 的 JDK（否则使用 PATH 中的 `java`）。 |
| `DEFOLD_EMAIL` / `DEFOLD_AUTH` | 私有依赖主机 `bob resolve` 的默认设置。 |
## 工具
### 项目和设置
| 工具 | 描述 |
|---|---|
| `defold_project_info` | 项目概览：标题、主集合、显示、依赖项、资源计数。 |
| `defold_get_settings` | 读取 game.project（所有章节 / 单个章节 / 单个键）。 |
| `defold_set_setting` | 设置或删除 game.project 键，保留格式。自动追加受影响键的尾随 `c`（见下文）。 |
| `defold_list_dependencies` | 已声明的依赖项 + 本地解析的存档。 |
| `defold_add_dependency` / `defold_remove_dependency` | 管理依赖项 URL。 |
### 资源
| 工具 | 描述 |
|---|---|
| `defold_list_resources` | 按类型/名称分页列出项目文件。 |
| `defold_parse_resource` | 将任何资源解析为 JSON（集合、.go、.gui、图集...；脚本的 Lua 概要；game.project 的章节）。 |
| `defold_create_resource` | 从有效模板创建脚本 / gui_script / render_script / lua / go / collection / gui / atlas / input_binding。 |
| `defold_find_references` | 查找引用资产的文件（也适用于 Lua 模块的点式 `require` 形式）。 |
### 构建和工具链
| 工具 | 描述 |
|---|---|
| `defold_setup` | 为 Defold 版本安装/验证 Java、bob.jar、dmengine 和 API 文档（`stable`、`beta`、`alpha` 或 `1.12.4`）。 |
| `defold_build` | 带有结构化错误/警告诊断的 `bob build`。 |
| `defold_bundle` | 平台包（macOS/Windows/Linux/Android/iOS/HTML5）；通过 `extra_args` 进行签名标志。 |
| `defold_resolve_dependencies` | `bob resolve`。 |
| `defold_clean` | 删除构建输出。 |
| `defold_doctor` | 环境诊断（Java、缓存、项目根目录、正在运行的游戏）。 |
### 运行和实时引擎
| 工具 | 描述 |
|---|---|
| `defold_run` | 使用 dmengine 开发二进制文件构建并启动游戏（后台）。 |
| `defold_stop` | 停止启动的游戏。 |
| `defold_game_logs` | 增量读取捕获的 stdout/stderr（稳定偏移、过滤）。 |
| `defold_engine_info` | 运行引擎的 `/info` + ping（本地或设备）。 |
| `defold_hot_reload` | 将资源编译并热交换到正在运行的游戏中。 |
| `defold_engine_command` | `@system` 命令：toggle_profile、toggle_physics_debug、set_update_frequency、set_vsync、start/stop_record、reboot、exit 等。 |
| `defold_engine_logs` | 流式传输引擎 TCP 日志服务（也适用于编辑器启动的游戏和设备）。 |
| `defold_editor_logs` | 流式传输正在运行的 Defold 编辑器的控制台（构建 + 引擎输出）通过其 `/console/stream` HTTP 端点（Defold 1.13.0+）。 |
| `defold_screenshot` | 捕获正在运行的游戏的截图作为可查看的图像，以便代理可以直观地验证渲染/布局/UI（macOS；需要屏幕录制权限）。 |
### API 参考
| 工具 | 描述 |
|---|---|
| `defold_api_search` | 按给定引擎版本的完整 API 参考进行排名搜索。 |
| `defold_api_doc` | 元素的完整文档（`go.animate`）或命名空间索引（`go`），带有参数、返回和示例。 |
## 典型代理工作流程
```
defold_setup # 一次：验证 Java，获取 bob + 引擎 + 文档
defold_project_info # 定位
defold_parse_resource /main/main.collection
... 使用普通文件工具编辑文件 ...
defold_build # 结构化编译错误
defold_run # 启动
defold_hot_reload ["/main/player.script"] # 迭代而无需重启
defold_game_logs filter="ERROR" # 观察
defold_stop
```
## Defold 特有说明
- **尾随 `c` 约定**：`game.project` 存储了一些以编译形式存在的引导资源 — `bootstrap.main_collection = /main/main.collectionc`（注意 `c`）。`defold_set_setting` 自动为受影响的六个键追加它（`bootstrap.main_collection`、`bootstrap.render`、`bootstrap.debug_init_script`、`input.game_binding`、`input.gamepads`、`display.display_profiles`）。
- **热重载** 将源路径映射到构建路径（`.script` → `.scriptc`，`.atlas` → `.texturesetc`，图像 → `.texturec`，...），并将它们发布到引擎服务（`POST /post/@resource/reload`，二进制 protobuf）— 编辑器使用的相同协议。它需要一个 **调试** 构建，其 `build/default` 输出与正在运行的游戏同步。
- **引擎服务**：调试构建监听 8001 端口（`/info`、`/ping`、`/post/...`）。对于设备，请将设备 IP 地址设为主机。
- **原生扩展**：具有原生代码依赖项的项目在 bob 构建时通过 Defold 的云构建服务器编译；这会透明地发生，但需要网络访问。
## 安全说明
- 服务器是一个 **本地开发工具，通过 stdio**；它不监听任何网络端口。
- 文件写入工具解析路径以对抗项目根目录，并拒绝遍历目录之外。
- 工具链工件仅从 `d.defold.com` 和 `github.com/defold/defold` 版本下载并缓存在本地。
- `defold_engine_*` 工具与您指向的任何主机通信（默认为 `localhost`）；它们发送引擎控制消息，从不发送项目源。
## 开发
```bash
npm run dev # 从 TypeScript 源代码运行
npm test # 构建 + 单元测试和端到端测试（无需 Java/网络）
node test/live-smoke.mjs # 实时网络烟雾测试（下载工具链，查询真实文档）
node test/live-smoke.mjs --full # + 真实构建/运行/热重载循环（需要 Java）
```
测试布局：`test/fixture` 是一个最小的有效 Defold 项目；`test/server.test.mjs` 通过真正的 MCP stdio 客户端驱动服务器，并使用模拟的引擎 HTTP/TCP 服务代替正在运行的游戏。
## 许可证
MIT
