godot-breakpoint-mcp

# 断点 MCP > 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，将 **Godot 游戏引擎** 引入 AI 助手的开发循环中 — 编写场景，编写类型检查的 GDScript，运行项目，调试实时游戏。与 **Claude** 开发和测试；MCP 是一个开放的协议，因此其他客户端也可以连接（参见 [兼容性](#兼容性)）。 > > **npm 1.13.0 · 插件 1.4.2 · 271 个工具 + 5 个 MCP 资源 · MIT.** 主机构建针对稳定的 `@modelcontextprotocol/sdk` 1.x API，并通过 367 测试套件和 Node 18/20/22 上的真实 Godot 集成作业进行测试。 断点 MCP 将兼容 MCP 的 AI 助手连接到正在运行的 Godot 编辑器和游戏。助手不仅可以搭建文件，还可以打开场景，添加和连接节点，带有完整的撤销/重做，编写带有类型感知补全和诊断的 GDScript，设置断点并逐步调试实时游戏。 它使用 Godot **自己的** 协议 — 编辑器插件的环回桥，Godot 内置的 **语言服务器（LSP）** 和 **调试适配器（DAP）** — 而不是重新实现它们，因此行为与您已经拥有的引擎保持一致。 ## 功能 断点 MCP 被组织成四个功能 **层**（271 个工具 + 5 个资源）： - **层 A — 实时编辑器桥**（~145 个工具：`editor_*`、`scene_*`、`node_*`、`signal_*`、`resource_*`、`filesystem_*`、`anim_*` 等）：Godot `EditorPlugin` 打开一个环回服务器，由主机驱动，进行场景/节点/资源 CRUD 操作，带有完整的 **撤销/重做**，项目设置，`ClassDB` 反射，选中项和编辑器截图。此层还包括原生多人创作（`mp_*`），后端 SDK 集成脚手架（`backend_*`、`leaderboard_scaffold`、`cloudsave_scaffold`、`auth_scaffold`），AI 资产生成（`asset_*`）和只读文档/代码查找系列。 - **层 B — 无头 CLI 和主机端工具**（`godot_*`、`vcs_*`，项目搜索）：启动编辑器，运行项目，导出，导入和运行无头脚本或测试 — 不需要编辑器窗口。长期运行的作业（`godot_export`、`godot_import`、`godot_run_headless_script`）在正式的 MCP **任务模型**（创建 → 轮询 → 等待 → 取消）上运行，而简单的客户端仍然获得阻塞结果。`godot_run_managed` / `godot_output` 捕获游戏的完整控制台。**版本控制（`vcs_*`）** 读取项目的 git 仓库（状态，日志，差异，显示，分支，污点）并执行安全的本地 git 操作（暂存，提交，恢复，stash，分支，切换）— 破坏性操作需要确认，并且不暴露网络操作（推送/拉取保持手动）。 - **层 C — 运行时桥**（`runtime_*`）：插件在每次运行中注册到一个自加载（`BreakpointRuntimeBridge`），在运行的游戏中打开一个环回服务器 — 实时 SceneTree，运行时属性获取/设置，方法调用，信号发射，输入注入用于游戏测试，性能监视器和游戏内帧捕获。在 Godot 4.5+ 上，它还捕获游戏的控制台（`print()`，警告，错误）而无需任何配置。 - **层 D — 语义和调试**（`gd_*`、`dbg_*`，以及 C# `cs_*` / `cs_dbg_*`）：主机作为客户端连接到 Godot 内置的 **GDScript 语言服务器**（端口 6005）和 **调试适配器**（端口 6006）— 补全，悬停，定义/引用，重命名，符号，签名帮助，诊断，以及实时调试：断点，逐步调试，堆栈/作用域/变量，监视表达式和表达式求值。并行 C# 层使用 OmniSharp（LSP）和 netcoredbg（DAP）。功能 **按引擎版本检测**，如果不支持，则会降低到清晰的“不支持”消息，而不是出错。 五个 **MCP 资源**（`godot://scene-tree`、`godot://editor-state`、`godot://runtime/tree`、`godot://runtime/log`、`godot://class/{name}`）公开按需拉取的上下文，客户端可以 **订阅** 以在编辑器选中项，编辑场景或实时 SceneTree 更改时推送更新。 ## 亮点 - **从构造上确保撤销安全性。** 每次编辑操作都包装在 `EditorUndoRedoManager` 中 — Ctrl-Z 可以撤销助手执行的所有操作。 - **确认门控破坏性工具。** 任何删除，覆盖或写入文件都需要事先确认（带有 `confirm: true` 覆盖，并且在客户端无法提示时进行安全阻止）。 - **强制执行输出模式。** 工具结果根据冻结的输出模式验证。 - **设计为本地。** 所有层都与 `127.0.0.1` 通信；截图渲染真实帧。 ``` ┌───────────────────── Claude（代码/桌面） ─────────────────────┐ │ MCP 通过 stdio │ └─────────────────────────────┬──────────────────────────────────────┘ 主机/（TypeScript MCP 服务器） ┌────────────┬──────────────┬──────────────┬────────────┬───────────┐ 启动 CLI TCP :9080 TCP :9081 TCP :6005 TCP :6006 （无头） 编辑器插件 游戏内 Godot LSP Godot DAP 场景/节点 自加载 补全， 断点， /撤销 实时 SceneTree 诊断 逐步调试，求值 /监视器/输入 ``` ## 要求 - **Node ≥ 18** （用于主机）。 - **Godot 4.2+** 用于编辑器插件（推荐 4.4+）。一些运行时功能使用 Godot 4.5+，并且一些语言服务器/调试适配器功能在较新的版本中启用。 ## 安装 ### 快速入门（推荐） 从您的 Godot 项目文件夹中，一条命令安装并启用编辑器插件，并打印您的 MCP 客户端配置： ```bash npx breakpoint-mcp init ``` 然后在 Godot 中打开项目，并验证所有内容是否已连接： ```bash npx breakpoint-mcp doctor ``` `init` 将插件复制到 `addons/breakpoint_mcp/`，在 `project.godot` 中启用它，并打印客户端配置代码段 — 将 `--client claude-desktop|cursor|windsurf|vscode` 传递给该命令，以直接写入该客户端的配置中，或者使用 `--client claude-code` 获取 `claude mcp add` 命令。默认情况下，`init` 安装包中捆绑的插件；添加 `--from-github [ref]` 以从 GitHub 获取它（例如 `--from-github main` 获取最新的，或者 `--from-github v1.3.0` 获取标签；`--repo <owner/repo>` 定位到一个分叉）。`doctor` 检查 Godot 二进制文件，插件和四个桥（添加 `--require-live` 以在编辑器打开后需要它们；`--json` 获取机器可读的报告）。下面的手动步骤通过手动完成相同的事情。 ### 1. 安装编辑器插件（手动） 这些手动步骤适用于从此存储库的检出开始，或者如果您想自己动手。如果您已从 npm 安装，`npx breakpoint-mcp init` 为您完成了所有这些操作 — 插件在包中捆绑，因此您不需要存储库。 将 `addons/breakpoint_mcp/` 复制到项目的 `addons/` 文件夹中，然后在 **项目 → 项目设置 → 插件 → 断点 MCP** 下启用它。启用后，它监听 `127.0.0.1:9080`（在启动 Godot 之前使用 `BREAKPOINT_BRIDGE_PORT` 覆盖）。 启用插件还会自动注册 **运行时自加载**（`BreakpointRuntimeBridge`），因此 `runtime_*` 工具在项目运行时立即生效（它监听游戏内的 `127.0.0.1:9081`）。无需手动自加载设置。 启用后，**断点 MCP** 停靠区出现在编辑器的右侧。它显示所有四个桥（编辑器/运行时/GDScript LSP/DAP）的实时运行状况，配置的端口和项目路径，以及一键 **复制 MCP 客户端配置** 按钮 — 编辑器中的双胞胎 `doctor` + `init`。它是状态/配置的唯一内容：助手仍然在您的 MCP 客户端中运行，而不是在编辑器中。 Godot 的 **语言服务器**（端口 6005）和 **调试适配器**（端口 6006）是内置的，并在编辑器打开时默认启用 — `gd_*` 和 `dbg_*` 工具直接使用它们，无需插件。端口可以在 **编辑器 → 编辑器设置 → 网络 → 语言服务器/调试适配器** 下配置。 ### 2. 获取主机 主机作为 **`breakpoint-mcp`** 发布到 npm： ```bash npx breakpoint-mcp # 按需运行 # 或 npm i -g breakpoint-mcp # 安装 `breakpoint-mcp` 命令 ``` 要从源代码构建： ```bash cd host npm install npm run build # tsc -> dist/ ``` ### 3. 注册到您的 MCP 客户端 Claude 是主要的，已测试的客户端。 **Claude 代码：** ```bash claude mcp add godot -- npx -y breakpoint-mcp ``` **Claude 桌面版**（`claude_desktop_config.json`）： ```json { "mcpServers": { "godot": { "command": "npx", "args": ["-y", "breakpoint-mcp"], "env": { "GODOT_BIN": "/abs/path/to/Godot", "GODOT_PROJECT": "/abs/path/to/your/project" } } } } ``` 使用不同的 MCP 客户端（Cursor，VS Code，Windsurf 等）？参见 [兼容性](#兼容性) 下文 — 命令相同，只有配置文件位置和包装器密钥不同。 ## 配置（环境变量） | 变量 | 默认值 | 含义 | |---|---|---| | `GODOT_BIN` | `godot` | Godot 编辑器二进制文件的路径 | | `GODOT_PROJECT` | cwd | 项目目录（包含 `project.godot`） | | `BREAKPOINT_BRIDGE_HOST` | `127.0.0.1` | 编辑器桥主机 | | `BREAKPOINT_BRIDGE_PORT` | `9080` | 编辑器桥端口（必须与插件匹配） | | `BREAKPOINT_BRIDGE_TIMEOUT_MS` | `15000` | 编辑器工具的每个请求超时 | | `GODOT_LSP_HOST` / `GODOT_LSP_PORT` | `127.0.0.1` / `6005` | GDScript 语言服务器 | | `GODOT_DAP_HOST` / `GODOT_DAP_PORT` | `127.0.0.1` / `6006` | 调试适配器 | | `GODOT_LSP_TIMEOUT_MS` / `GODOT_DAP_TIMEOUT_MS` | `15000` / `20000` | LSP / DAP 超时 | | `BREAKPOINT_RUNTIME_HOST` / `BREAKPOINT_RUNTIME_PORT` | `127.0.0.1` / `9081` | 游戏内运行时桥（必须与自加载匹配） | | `BREAKPOINT_RUNTIME_TIMEOUT_MS` | `15000` | 运行时请求超时 | > **从 `CLAUDE_*` 重新命名：** 上面的 `BREAKPOINT_*` 变量（加上 `BREAKPOINT_RESOURCE_COALESCE_MS`）在早期版本中命名为 `CLAUDE_*`。旧的 `CLAUDE_*` 名称被赋予了一次性弃用警告，在 `1.0.0` 中，并在 `1.1.0` 中删除 — 使用 `BREAKPOINT_*` 名称。`GODOT_*` 变量保持不变。 完整的，注解的配置参考在 [用户指南](docs/USER_GUIDE.md) 中。 ## 兼容性 断点 MCP 是一个标准的 MCP 服务器，通过 stdio 进行通信，因此原则上它与 **任何 MCP 兼容的客户端** 配合使用。然而，它是与 **Claude** （Claude 代码和 Claude 桌面版）一起开发和测试的 — 这是今天的支持路径。其他客户端，如 Cursor，VS Code（Copilot 代理模式）和 Windsurf 应该可以使用相同的命令和环境变量，但它们 **尚未与此服务器测试**。如果您尝试使用断点 MCP 与另一个客户端 — 或同一客户端后面的不同模型 — 我们非常希望听到您的反馈：请 [打开一个问题](https://github.com/jlivingston-Cipher/godot-breakpoint-mcp/issues)，描述您的客户端以及哪些内容有效或无效。 每个客户端都以相同的方式启动主机：`npx -y breakpoint-mcp` 命令和上面的环境变量。只有配置文件位置和包装器密钥不同。 | 客户端 | 配置文件 | 包装器密钥 | 备注 | |---|---|---|---| | **Claude 代码** | — | — | `claude mcp add godot -- npx -y breakpoint-mcp` | | **Claude 桌面版** | `claude_desktop_config.json` | `mcpServers` | 参见上面的示例 | | **Cursor** | `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目） | `mcpServers` | 与 Claude 桌面版相同 | | **VS Code**（Copilot 代理模式） | `.vscode/mcp.json` | `servers` | 每个条目还需要 `"type": "stdio"` | | **Windsurf**（Cascade） | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | 与 Claude 桌面版相同 | | **任何其他 MCP 客户端** | 根据其文档 | — | 将其指向 `npx -y breakpoint-mcp` 作为 stdio 服务器 + 传递 env vars | VS Code 使用略微不同的格式（`servers`，带有显式传输 `type`）： ```json { "servers": { "godot": { "type": "stdio", "command": "npx", "args": ["-y", "breakpoint-mcp"], "env": { "GODOT_BIN": "/abs/path/to/Godot", "GODOT_PROJECT": "/abs/path/to/your/project" } } } } ``` 由于工具描述是与 Claude 调整的，因此另一个模型可能会以不同的方式驱动工具；如果您注意到使用特定客户端或模型时有粗糙的边缘，带有详细信息的 issue 有助于我们为每个人改善体验。 ## 典型会话 1. `godot_launch_editor`（或您自己打开项目）。 2. `editor_ping` → 确认桥已激活。 3. `scene_get_tree`，`classdb_get_class` → 了解场景和 API。 4. `node_add`，`node_set_property`，… → 进行更改（均可撤销）。 5. `gd_completion` / `gd_diagnostics` → 编写带有类型感知功能的 GDScript 并在运行前捕获错误。 6. `screenshot_editor` → 让 Claude *看到* 结果。 7. `dbg_set_breakpoints` → `dbg_launch` → `dbg_stack_trace` / `dbg_variables` / `dbg_evaluate` → 从真实程序状态调试。 8. `godot_run_project` → `runtime_get_tree` / `runtime_set_property` / `runtime_inject_input` / `runtime_screenshot` → 驱动并观察正在运行的游戏。 9. `godot_run_headless_script` → 运行测试。 [用户指南](docs/USER_GUIDE.md) 逐步讲解了这个过程。 ## 安全性和信任模型 断点 MCP 是一个 **本地协同开发工具**，旨在让您保持控制： - 每次编辑操作都通过 `EditorUndoRedoManager` — **Ctrl-Z 恢复助手执行的所有操作** — 并且通过编辑器 API（保留 UID/引用），而不是原始文件写入。 - 所有套接字仅绑定到 **环回（`127.0.0.1`）**；处理程序在编辑器的 **主线程** 上运行，因此没有线程危险。 - **破坏性工具通过提示门控：** 主机在执行前要求客户端确认（例如 `node_delete`，`project_set_setting`，`scene_new`，带有应用的 `gd_rename`，文件/资源/脚本写入器，以及 `runtime_*` 变更器）。传递 `confirm: true` 以自动批准；如果客户端无法提示，工具会阻塞而不是沉默地操作。 - **更高信任的表面，如有明确说明：** `godot_run_headless_script` 和 `godot_run_managed` 执行 GDScript，可选的 `asset_generate` **命令**后端运行您配置的本地命令（通过 `BREAKPOINT_ASSETGEN_CMD` 或工具参数）。这些是可选的，并受门控 — 仅将它们指向您信任的代码。 安全策略和如何报告漏洞：参见 [SECURITY.md](SECURITY.md)。 ## 文档 - **[用户指南](docs/USER_GUIDE.md)** — 完整手册：安装、配置、概念、工作流程、故障排除和常见问题。 - **[工具目录](docs/TOOL_CATALOG.md)** — 每个工具及其输入和输出 JSON 模式。 - **[运行手册](docs/RUNBOOK.md)** — 分步实时验证检查清单。 - **[更新日志](CHANGELOG.md)** — 版本历史。 - **[贡献指南](CONTRIBUTING.md)** · **[安全](SECURITY.md)** · **[行为准则](CODE_OF_CONDUCT.md)** ## 开发 ```bash # 静态检查（不需要 Godot 或注册表进行一致性检查） python3 scripts/contract_check.py # host <-> addon <-> catalog 协议 cd host && npm ci && npm run build && npm run typecheck && npm test ``` CI 在 Node 18/20/22 上运行真正的构建和测试套件，并在真实的 Godot 引擎上测试 CLI、运行时、C# 和编辑器/调试平面。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以开始使用。 **SDK 注意：** 主机针对稳定的 `@modelcontextprotocol/sdk` **1.x** 高级 API（`server.registerTool(name, { title, description, inputSchema }, handler)`）。如果您更喜欢较新的 SDK v2 接口，请调整导入行并在 `z.object(...)` 中包装每个 `inputSchema`；工具逻辑保持不变。 ## 商标 Godot 和 Godot 标志是 Godot 基金会的商标。Claude 和 Anthropic 是 Anthropic, PBC 的商标。SilentWolf，Nakama（Heroic Labs），PlayFab（Microsoft），以及 Photon（Exit Games）是其各自所有者的商标。断点 MCP 是一个独立的、社区建设的项目，与它们没有任何关联、赞助或认可；它们的名字仅用于描述互操作性。 ## 许可 MIT — 参见 [LICENSE](LICENSE)。