内容
# godot-mcp-x
**English** · [简体中文](README.zh.md)
> **❤️ 支持 / 赞赏支持** — 如果 godot-mcp-x 为您节省了时间，请小额赞赏，非常感谢！ 🙏
> **PayPal**: [paypal.me/koboling](https://paypal.me/koboling) · **微信赞赏** ↓
>
> <img src="docs/wechat-reward.jpg" alt="微信赞赏二维码" width="220">
下一代 **高效令牌** MCP 服务器，用于 AI 驱动的 **Godot 4.7** 开发。干净的核心 + 久经考验的命令逻辑，从一开始就围绕 AI 代理的两个重要事项设计：**快速、小、正确的响应** 和 **全面的编辑器 + 运行时控制**。
> 状态：**功能完整且端到端验证** — **28 个组中的 168 个工具**：项目、场景、节点、脚本、编辑器、分析、资源、文件系统、UI、输入映射、动画、动画树、物理、导航、3D 构建器、网格图、骨骼、着色器、粒子、音频、图块地图、主题、批处理、性能分析、导出、完整的 **运行时** （实时游戏）通道和 **自动游戏测试** （断言、场景、监视器）。针对实时 4.7 稳定版本进行验证（**167/167 往返调用绿色**，以及 **23 个单元测试**，包括 MCP 标准输入测试）。
## 为什么存在（与 godot-mcp-pro 相比）
它最初是作为对成熟的 `godot-mcp-pro` （172 个工具）的研究。该工具有效，但有两个问题严重影响 AI 使用，并在设计上得到解决：
| 原始问题 | godot-mcp-x 中的修复 |
|---|---|
| 场景树打印 **完整的编辑器路径** （`/root/@EditorNode@…/SubViewport/Main/…`）→ 中型场景 = **73K 字符**，超出令牌限制 | 从 **编辑场景根节点** 开始；发出 **场景相对路径** （`Player/Camera3D`）。同一个场景 → 几百个字符。 |
| 没有分页/限制 — `read_script` 一次性转储 60K 字符 | **源侧分页** everywhere: `offset`/`limit` on scripts & scene files, `max_depth` on trees, paging on lists, + a TS-side budget clamp |
| `get_node_properties` 返回所有内容 | 默认情况下仅返回 **更改的（非默认）** 属性；选择加入 `include_defaults` 或特定于项目的 `names[]` |
| 170+ 个工具重复相同的 try/catch + JSON.stringify | **声明式工具注册表**：统一的错误/预算信封，工具是纯数据→数据处理器 |
| 通过线上的 base64 截图 | 保存 PNG，返回宿主可以直接读取的 **绝对文件路径** |
| （新功能） | **实时 ClassDB 反射** （`list_classes`/`describe_class` 具有完整的方法签名） — 正确代码生成的 4.7 API 的真实依据 |
| （新功能） | **“你是否想到了…”** — 输入错误的 type/property/method 名称 **和节点路径** （编辑器 **和** 运行时）返回字符串相似性建议，减少代理重试往返次数 |
| （新功能） | **编辑器状态停靠** + `get_status` 工具 — 连接的端口、命令计数和播放状态的实时视图 |
| （新功能） | **可撤销编辑** — 节点添加/删除/重命名/移动/复制和属性集在 `EditorUndoRedoManager` 中注册，以便人类可以 **Ctrl+Z** AI 更改（+ `undo`/`redo` 工具） |
MCP 服务器是一个薄的 JSON-RPC 代理；真正的性能在于 **有效载荷大小** 和 **编辑器端序列化** ，这是工作重点。
## 架构
```
Claude / MCP 客户端 ──stdio──> godot-mcp-x 服务器 (Node/TS)
│ 127.0.0.1:6605-6609 上的 WebSocket 服务器
│ JSON-RPC 2.0 · 心跳 · 多会话
│ 双角色路由（hello → 编辑器 | 运行时）
┌─────────────┴──────────────┐
编辑器连接 │ │ 运行时连接（仅在播放时）
▼ ▼
Godot 编辑器 + godot_mcp_x 插件 运行游戏 + runtime_bridge 自动加载
ws_client → 路由器 → commands/*.gd 直接 WS → live get_tree()
编辑器接口 · ClassDB · 场景 场景树 · 属性 · 输入 · 帧
```
逆向拓扑结构（服务器绑定，编辑器拨号）允许多个会话驱动一个编辑器。**端口 6605-6609** 与 godot-mcp-pro 的 6505-6514 故意不同，因此两者可以并行运行。
## 安装
1. **构建服务器**
```bash
cd server
npm install
npm run build
```
2. **安装插件** — 将 `addons/godot_mcp_x/` 复制到您的项目的 `res://addons/godot_mcp_x/`，然后启用 **项目 → 项目设置 → 插件 → Godot MCP X**。（参见 [INSTALL.md](INSTALL.md)。）
3. **使用客户端注册 MCP 服务器**。包含了一个现成的 [.mcp.json](.mcp.json)：
```json
{ "mcpServers": { "godot-mcp-x": { "command": "node",
"args": ["D:/GodotProjects/godot-mcp-x/server/build/index.js"] } } }
```
4. 打开编辑器。插件将拨打服务器；现在工具调用将击中您的实时编辑器。可选的环境变量 `GODOT_MCP_X_PORT` 固定一个端口。
### 一键客户端设置
在 `npm run build` 之后，将服务器自动注册到您的 MCP 客户端（s）中 - 无需手动编辑配置文件：
```bash
node build/cli.js install --list # 检测到的客户端 + 它们的配置文件路径
node build/cli.js install claude-desktop # 配置一个
node build/cli.js install all # 配置每个检测到的客户端
```
支持：**Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), Zed, Codex** — 每个客户端都获取正确的配置文件路径 + 架构，现有条目被保留。添加 `--scope project` （项目本地配置）、 `--name` 或 `--mode 3d`。
## CLI（不需要 MCP 客户端）
在 `npm run build` 之后，直接从 shell 驱动编辑器 - 方便用于脚本或保存上下文。 与 MCP 服务器（可作为 `godot-x` 安装）相同的处理程序 + 传输。
```bash
node build/cli.js list [filter] # 列出工具（可选过滤）
node build/cli.js <tool> --help # 显示工具的参数
node build/cli.js get_project_info
node build/cli.js add_node --type Sprite2D --name Hero --parent_path .
node build/cli.js set_node_property --path Hero --property position --value "Vector2(100,200)"
node build/cli.js get_scene_tree --max_depth 2
node build/cli.js batch_add_nodes --nodes '[{"type":"Node3D","name":"Lights"}]'
```
值自动输入（数字/布尔值和 JSON `{...}`/`[...]` 被解析；其他内容保持字符串）和针对每个工具的 Zod 架构进行验证，因此输入错误和缺少必需参数快速失败并显示清晰的消息。需要启用编辑器插件。
### 守护进程 — 暖连接（推荐）
单个 CLI 调用重新绑定 WebSocket 并等待 Godot 重新连接（~1-2 秒）。启动 **守护进程** 一次以保持连接温暖；后续命令通过本地 HTTP 路由到它并在 ~150 毫秒内返回（≈5-10 倍更快）：
```bash
node build/cli.js daemon # 长寿命：WS 6605-6609 + IPC 6610. 让它运行。
node build/cli.js status # { daemon: true, ws_port, editor, runtime }
node build/cli.js get_game_info # 自动路由到守护进程
node build/cli.js stop-daemon
```
`godot-x <tool>` 自动检测正在运行的守护进程；如果没有，则回退到一次性，这样脚本无论哪种方式都有效。 使用 `GODOT_MCP_X_DAEMON_PORT` 覆盖 IPC 端口。`status` 还报告 `concurrent_replaces` — 非零意味着两个 Godot 实例正在争夺端口（仅保留一个）。参见 **[WALKTHROUGH.md](WALKTHROUGH.md)** 以获取完整的构建游戏循环。
### 无编辑器的运行时工具
运行时工具（`get_game_screenshot`, `get_game_info`, `simulate_key`, `execute_game_script`, …）针对 **独立运行的游戏** 工作 - 不需要编辑器。游戏的 `McpXRuntime` 自动加载对接，CLI/守护进程接受编辑器 **或** 运行时连接。因此，您可以 `godot --path .` 您的游戏并直接截图/驱动它。要捕获短暂效果，请调用：`get_game_screenshot --run 'player._fire_nova()' --after 0.1` （或 `--count 8` 进行突发）。
### 无头资产导入
要导入新添加的资产（新 `.png` 等）而不打开 GUI：`godot --headless --import path/to/project.godot`。**注意：** `--editor --quit` *不* 可靠地写入 `.import` 边车，因此 `load()` 在运行时返回 null - 使用 `--import`。
## 工具模式（缩小上下文）
完整的服务器注册了 168 个工具，而工具列表本身会消耗上下文。对于专注的会话，仅加载您需要的组，使用 `--mode` （或 env `GODOT_MCP_X_MODE`），以及 `--tools` / `--exclude`：
| 模式 | 工具 | 组 |
|---|--:|---|
| `full` （默认） | 168 | 所有内容 |
| `minimal` | 48 | 项目、场景、节点、脚本、编辑器 |
| `3d` | 151 | 常用 + 物理、导航、节点 3D、着色器、粒子、音频、动画树、网格图、骨骼、MP |
| `2d` | 121 | 常用 + 物理、图块地图、主题、MP |
| `ui` | 78 | 最小 + 资源、主题、批处理、运行时、UI |
| `test` | 72 | 最小 + 运行时、测试、性能分析 |
（常用 = 最小 + 分析、资源、文件系统、UI、输入、动画、批处理、运行时、测试）
```jsonc
// .mcp.json - 只加载 3D 工具
{ "mcpServers": { "godot-mcp-x": { "command": "node",
"args": ["D:/GodotProjects/godot-mcp-x/server/build/index.js", "--mode", "3d"] } } }
```
或者显式选择组： `--tools project,scene,node,shader` / `--exclude export,profiling`。预览任意模式：`node build/cli.js list --mode 3d`.
## 工具（当前 - 168）
- **项目** （9）：`get_project_info`, `get_project_settings`, `set_project_setting`, `get_filesystem_tree`, `list_autoloads`, `add_autoload`, `remove_autoload`, `uid_to_path`, `path_to_uid`
- **场景** （7）：`get_scene_tree`, `get_current_scene`, `open_scene`, `save_scene`, `create_scene`, `get_scene_file_content`, `instance_scene`
- **节点** （14）：`add_node`, `delete_node`, `rename_node`, `move_node`, `duplicate_node`, `get_node_properties`, `set_node_property`, `set_node_properties`, `get_node_signals`, `connect_signal`, `set_node_groups`, `find_nodes`, `call_node_method`, `build_tree` （声明式子树，一次可撤销操作 - 内联资源 + 信号）
- **脚本** （7）：`read_script`, `create_script`, `write_script`, `edit_script`, `attach_script`, `validate_script`, `list_scripts`
- **编辑器** （11）：`execute_editor_script`, `get_editor_errors`, `get_output_log`, `clear_output`, `get_editor_screenshot`, `reload_scripts`, `list_classes`, `describe_class`, `undo`, `redo`, `get_status`
- **分析** （5）：`search_files`, `search_in_files`, `find_script_references`, `get_scene_dependencies`, `analyze_scene_complexity`
- **资源** （3）：`create_resource`, `read_resource`, `edit_resource`
- **文件系统** （4）：`create_folder`, `rename_path`, `delete_path`, `duplicate_path`
- **UI** （2）：`add_virtual_joystick` （4.7 触摸摇杆 → 输入操作），`set_anchor_preset`
- **输入映射** （4）：`list_input_actions`, `add_input_action`, `remove_input_action`, `add_input_event`
- **动画** （5）：`list_animations`, `get_animation_info`, `create_animation`, `add_animation_track`, `set_animation_keyframe`
- **物理** （5）：`get_physics_layers`, `set_physics_layer_name`, `set_collision_layers`, `get_collision_info`, `setup_collision_shape`
- **3D** （5）：`add_mesh_instance`, `setup_light` （定向/全/点/ **区域** = 4.7 区域光源）， `setup_camera`, `set_material`, `setup_environment`
- **运行时** （15）：`play_scene`, `stop_scene`, `is_game_running`, `get_game_info`, `get_game_scene_tree`, `get_game_node_properties`, `set_game_node_property`, `execute_game_script`, `get_game_screenshot`, `reload_game_script`, `simulate_action`, `simulate_key`, `get_autoload`, `find_game_nodes`, `call_game_method`
- **着色器** （6）：`create_shader`, `read_shader`, `edit_shader`, `assign_shader`, `set_shader_param`, `list_shader_uniforms`
- **音频** （5）：`add_audio_player`, `list_audio_buses`, `add_audio_bus`, `set_bus_volume`, `add_bus_effect`
- **粒子** （3）：`create_particles`, `set_particle_process`, `get_particle_info`
- **导航** （4）：`setup_navigation_region`, `setup_navigation_agent`, `bake_navigation_mesh`, `get_navigation_info`
- **图块地图** （7, TileMapLayer-native）：`tilemap_get_info`, `tilemap_set_cell`, `tilemap_get_cell`, `tilemap_erase_cell`, `tilemap_fill_rect`, `tilemap_clear`, `tilemap_get_used_cells`
- **主题** （7）：`create_theme`, `set_theme_color`, `set_theme_constant`, `set_theme_font_size`, `set_theme_stylebox`, `get_theme_info`, `tilemap_set_cell`, `tilemap_get_cell`, `tilemap_erase_cell`, `tilemap_fill_rect`, `tilemap_clear`, `tilemap_get_used_cells`
- **主题** （7）：`create_theme`, `set_theme_color`, `set_theme_constant`, `set_theme_font_size`, `set_theme_stylebox`, `get_theme_info`, `apply_theme`
- **动画树** （6）：`create_animation_tree`, `setup_state_machine`, `add_state`, `add_transition`, `get_animation_tree_info`, `set_tree_param`
- **批处理** （3）：`batch_add_nodes`, `batch_set_properties`, `batch_get_properties`
- **性能分析** （1）：`get_performance_monitors`
- **导出** （2）：`list_export_presets`, `get_export_info`
- **测试** （8, 运行时）：`assert_property`, `assert_node_exists`, `assert_screen_text`, `wait_for_node`, `monitor_property`, `record_frames`, `run_test_scenario`, `get_test_report` - 自动游戏回归测试（通过/失败报告；故意失败验证）
- **网格图** （6）：`add_gridmap`, `gridmap_set_cell`, `gridmap_get_cell`, `gridmap_clear`, `gridmap_get_used_cells`, `gridmap_get_info`
- **骨骼** （9）：`get_skeleton_info`, `list_bones`, `add_bone`, `set_bone_pose`, `reset_bone_poses`, `add_bone_attachment`, `add_skeleton_modifier`, `setup_look_at_modifier`, `list_skeleton_modifiers`
- IK & 骨骼约束通过 SkeletonModifier3D 系统（TwoBoneIK3D, FABRIK3D, CCDIK3D, LookAtModifier3D, SpringBoneSimulator3D, …）
- **MP** （5）：`add_multiplayer_spawner`, `add_multiplayer_synchronizer`
（编辑器 - 构建 MultiplayerSpawner + MultiplayerSynchronizer 及其 SceneReplicationConfig，可撤销）,`setup_multiplayer_peer`, `get_multiplayer_info`, `set_game_authority` （运行时）- 高级网络搭建 + 实时对等/权限控制
## 路线图
- [x] 运行时 IPC：用直接游戏→服务器 WebSocket 替换原始的每帧文件轮询（实时场景树，属性获取/设置，输入模拟，帧捕获，游戏内脚本执行）- 双角色编辑器/运行时路由
- [x] 移植：分析、资源、输入映射、动画、物理、3D 构建器、着色器、音频、粒子、导航、图块地图（TileMapLayer-native）、主题、动画树、批处理、性能分析、导出 - **所有主要领域均已覆盖**
- [x] CLI 模式（不需要 MCP 客户端）- `godot-x <tool> --k v`，自动输入 + 架构验证；**暖连接守护进程** (`godot-x daemon`, ~150 ms/call vs ~1-2 s 一次性）
- [x] 每模式工具过滤（完整/最小/2d/3d/ui/测试 + --tools/--exclude）
- [x] 细分工具：网格图（3D 块构建），骨骼（骨骼/姿势/附件）
- [x] 质量检查：核心效率单元测试；`describe_class` 方法签名；`call_node_method` / `call_game_method`；文件系统组
- [x] AI 人机工程学：输入错误的 type/property/method 名称 **和** 节点路径的“你是否想到了…”建议
- [x] 撤销重做：节点/属性编辑在编辑器中可撤销（Ctrl+Z）+ `undo`/`redo` 工具；还修复了 `create_scene` 以干净地覆盖已打开的场景
- [x] 运行时“你是否想到了…”和 closest-node-path 建议的对等功能；编辑器状态停靠 + `get_status`；修复了 unfocused 窗口上的 `get_editor_screenshot` 挂起
- [x] 骨骼 - IK & 骨骼修改器（SkeletonModifier3D：TwoBoneIK3D/FABRIK3D/…）
- [x] 更深入的知识库（11 个文档）：渲染/材质/照明，物理/碰撞，资源/导出，骨骼 - IK
- [ ] 可选剩余：Android 部署（需要 Android SDK + 导出模板）
- [x] 基准测试量化令牌胜利 vs. 原始 - 参见 [BENCHMARK.md](BENCHMARK.md) （场景树输出 **−80%** on a real 137-node 场景）
- [x] 大型项目扩展：流媒体搜索，缓存 + 背景预热 `find_script_references` 索引，迭代场景遍历 (`max_nodes`)，统一分页 - 参见 BENCHMARK §6（find-refs ~1.9× 更快，bounded 内存/输出 on a 7,700-file / 8,000-node 压力项目）
- [x] 多人游戏（`mp` 组）：MultiplayerSpawner / Synchronizer + SceneReplicationConfig 搭建（可撤销）+ 运行时对等/权限/状态 - 验证（配置构建 + 撤销，服务器对等回环）
- [x] 一键多客户端安装 (`godot-x install <client|all>`) 用于 Claude Code/Desktop, Cursor, Windsurf, VS Code, Zed, Codex（正确的客户端特定架构，保留现有条目）
## 知识库
[knowledge/](knowledge/) - 一个可重复使用的，面向 AI 的 Godot 4.7 引用（20 个文档），在开发此工具时建立并 **针对实时引擎进行验证**：4.7 新增功能，GDScript 基础知识，编辑器自动化食谱，API 易错点，godot-mcp-x 工作流程，游戏模式，渲染/材质/照明，物理/碰撞，资源 & @export，SkeletonModifier3D IK 系统，深入的 4.7 变更日志（VirtualJoystick, DrawableTexture2D, 光线追踪基础，HDR, Jolt SoftBody, GUI/输入/编辑器/Android 更改）- 以及 UI/Control, 着色器（Godot Shading Language），XR/OpenXR，性能 & 优化，多人游戏/联网，音频和导航指南 - 引擎的每个主要子系统。
## 开发/验证
`test_project/` 是一个用于解析检查插件的丢弃 Godot 项目：
```bash
# 解析每个插件脚本（通过插件.gd 传递依赖图）
"D:/Godot/Godot_v4.7-stable_win64.exe" --headless --path test_project --check-only \
--script res://addons/godot_mcp_x/plugin.gd
# 完整的端到端往返（服务器 + 实时编辑器 + 命令）
cd server && node test/handshake.js # 编辑器运行时
```
## 许可证
MIT. 部分内容改编自 godot-mcp-pro（MIT）。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器