Godot Safe Change MCP 是一个面向 Agent 的 MCP Server：TypeScript 负责工具契约、预览计划、确认、任务编排和审计；Godot EditorPlugin 负责真实编辑器上下文、UndoRedo、运行控制和诊断采集。

它不把 Godot 暴露成任意 RPC，而是把一次变更约束成一条可验证的闭环：

读取上下文 → 生成 Diff → 用户确认 → 获取项目 Lease → 通过 Godot UndoRedo 应用 → 运行/验证 → 安全回滚

为什么使用它

• 面向意图，而不是任意 RPC：Agent 请求的是创建、移动、实例化、修改属性、运行和验证等受限操作。
• 每次写入都有证据：Preview Diff、expected revision、用户确认、operation ID、Godot UndoRedo 和 rollback report 串成完整记录。
• 适合多窗口协作：项目 Lease、heartbeat、TTL 接管和稳定的 PROJECT_BUSY 防止两个 MCP 进程互相覆盖。
• 真实 Godot 验证：GitHub Actions 在 Godot 4.5.1 与 4.7.2 上运行同一套 EditorPlugin fixture smoke。

Quick Start

环境要求

• Node.js 22.22.2 或更新版本
• Godot 4.x 编辑器；CI 当前验证 4.5.1 与 4.7.2
• 一个支持 MCP 的 Agent 客户端

1. 安装并启动 MCP Server

git clone https://github.com/LJH-snow/godot-safe-change-mcp.git
cd godot-safe-change-mcp
npm ci
npm run build
npm run dev

开发服务器提供：

• MCP endpoint：http://127.0.0.1:3000/mcp
• Inspector：http://127.0.0.1:3000/mcp/inspector
• Godot bridge：默认 http://127.0.0.1:8765

如需更换桥接地址，设置 GODOT_BRIDGE_URL：

GODOT_BRIDGE_URL=http://127.0.0.1:8765 npm run dev

2. 安装 Godot 插件

把本仓库的 godot-plugin 复制到目标项目：

your-godot-project/addons/godot-safe-change-bridge/

打开 Godot 后，在 Project → Project Settings → Plugins 中启用 Godot Safe Change Bridge。插件只监听 loopback 地址 127.0.0.1:8765，不会向公网暴露编辑器。

3. 连接 MCP 客户端

在客户端添加 Streamable HTTP MCP Server：

http://127.0.0.1:3000/mcp

也可以直接运行已构建的入口：

npm run build
node bin/mcp-server.mjs

使用 Inspector

Inspector 是 mcp-use 提供的本地 MCP 调试界面。执行 npm ci 或 npm install 时，mcp-use 会将锁定版本的 @mcp-use/inspector 安装到 node_modules；之后每次启动不会重复下载。

按以下步骤使用：

1. 启动 Godot 编辑器并启用 Godot Safe Change Bridge。
2. 在项目根目录运行 npm run dev；它会启动开发服务器并加载 Inspector。
3. 打开 http://127.0.0.1:3000/mcp/inspector，如果浏览器没有自动打开就手动访问。
4. 在 Tools 中先调用 editor_context，确认当前场景、完整节点树和连接状态。
5. 用 search_project 或 find_references 验证只读搜索。
6. 测试写入时严格执行 preview_scene_change → confirm_scene_change → apply_scene_change → rollback_scene_change。
7. 用 operation_history、task_status 和 task_timeline 查看审计、Lease 和恢复证据。

调试时可以禁止自动打开浏览器，或完全关闭 Inspector：

npm run dev -- --no-open
npm run dev -- --no-inspector

Inspector 只用于本地开发、手工验收和演示；CI 和生产入口不依赖它。默认只绑定 127.0.0.1，不要用公开地址运行开发 Inspector，也不要在工具表单中输入敏感凭据。

第一次尝试

连接成功后，可以从只读操作开始：

读取当前 Godot 编辑器上下文和完整场景树。
搜索项目中所有与 Player 或 PackedScene 相关的节点、脚本和资源。
查找哪些场景或脚本引用了 res://scripts/player.gd。

一个完整的安全写入流程如下：

1. 调用 preview_scene_change 生成计划和 Diff。
2. 检查 target、NodePath、属性变化和 expected revision。
3. 调用 confirm_scene_change 明确确认。
4. 调用 apply_scene_change，由插件通过 Godot UndoRedo 执行。
5. 调用 run_current_scene、verify_scene_state 或 verify_diagnostics 收集证据。
6. 需要撤销时调用 rollback_scene_change；revision 不一致时系统会拒绝覆盖用户修改。

工作流

flowchart LR
    A[Agent / MCP Client] --> B[Godot Safe Change MCP]
    B --> C[Read context and search]
    C --> D[Preview + Diff]
    D --> E[User confirmation]
    E --> F[Task lease + revision guard]
    F --> G[Loopback EditorPlugin]
    G --> H[Godot UndoRedo / bounded file change]
    H --> I[Run scene and collect diagnostics]
    I --> J[Verify state or diagnostics]
    J --> K[Rollback or continue]
    K --> F

能力地图

| 领域 | 能力 | 说明 | | --- | --- | --- | | 项目理解 | project_overview、search_project、find_references | 搜索场景、节点、脚本、资源、信号、输入和反向引用；编辑器离线时使用本地只读索引。 | | 编辑器上下文 | editor_context | 返回完整当前场景树（含节点分组）、选中节点安全属性、打开资源、运行状态和诊断。 | | 场景结构 | create、delete、reparent、rename、duplicate、reorder、instantiate、connect/disconnect signal、add/remove group | 所有 NodePath、名称、父子关系、实例源路径、兄弟索引、signal/method 和分组名都经过边界校验；连接、断开和分组变更通过 Godot UndoRedo apply/rollback。 | | 场景内容 | scene.set_property、scene.attach_script、scene.detach_script、scene.set_unique_name | 仅开放 visible、position、rotation_degrees、scale、size、text、color，以及项目内现有 GDScript 的挂载/卸载和场景唯一名 %Name 暴露。 | | 文件/设置 | resource reference、input action、script 创建与区间、autoload 注册、project.setting.set | 使用文件或 project.godot 完整字节 revision guard、独立磁盘读回、原子写入、按原始字节恢复，并在验证后支持受保护 rollback。 | | 运行诊断 | run_current_scene、run_scene | 返回 run ID、状态、输出、warning、error、source、line 和 NodePath。 | | 多步骤任务 | create/get/advance/pause/resume/cancel | 支持 verify_scene_state、verify_resource_state、verify_script_state、verify_diagnostics、诊断修复预览和 step-level operation ID。 | | 并发恢复 | acquire/renew/release task lease、task_status、task_timeline | Lease 持有期间 heartbeat 续租；进程崩溃后按 TTL 接管，并保留审计时间线。 |

安全模型

写操作生命周期

preview → confirm → lease/revision check → apply → verify → rollback (when needed)

明确禁止

• 任意 Agent 生成的 GDScript 执行
• shell、Python worker 或任意系统命令执行
• 任意 Godot RPC、方法名或对象反射
• 不受限制的文件系统写入
• 绕过 preview、confirm、revision、lease 或 rollback 的写入

这里记录的是受限实现和已有证据范围，不是完整的安全审计结论。

项目设置边界

project.setting.set 刻意不是通用 ProjectSettings setter，只允许三个 key：application/run/main_scene（必须是项目内已存在的 res:// .tscn，或由 Godot ResourceUID registry 解析到该场景的 uid:// 引用）、display/window/size/viewport_width 和 display/window/size/viewport_height（只能是 1..16384 的整数）。用户提供的主场景 path 或 uid 会按原始形式持久化，snapshot 也会原样返回。严格的 settingKey/value 对象会拒绝未知 key、额外字段、遍历路径、小数、非有限数值和不存在的场景。这是项目级生命周期：project.setting.set 的 preview、confirm、apply、rollback 不要求当前场景存在；/v1/project-settings/read 对未配置的 main scene 返回 exists: false、value: null。

revision 来自完整 project.godot 文件字节，并在 preview、confirm、apply、rollback 逐阶段检查。Godot 通过 ProjectSettings.save() 持久化，但桥接层另行从磁盘用 ConfigFile 读取并校验 typed value，内存中的 ProjectSettings 值不能单独视为成功读回。apply/rollback 都保存原始字节和尝试写入的字节；保存或读回失败时，通过临时文件加原子 rename 恢复原始字节，并再次核对字节和 revision。恢复失败会返回结构化的 recoveryRequired: true 和 phase（例如 save、verify、rollback、rollback-verify）；存在待恢复状态时，新的 project.setting.set apply 会被阻止，直到恢复完成。用户外部编辑会使 rollback 返回 REVISION_CONFLICT，保留当前文件，不覆盖用户内容。

并发行为

同一项目的短期 apply/rollback lease 和跨步骤 task lease 都存放在用户状态目录，不写入 Godot 项目。另一个窗口持有有效 lease 时，操作稳定返回 PROJECT_BUSY；owner 进程崩溃后，其他窗口只能在 TTL 到期后接管。

测试与 CI

本地质量门禁：

npm test
npm run typecheck
npm run build
npm run package:check
npm run release:check
git diff --check

本地有 Godot 编辑器时运行真实 bridge smoke：

GODOT_BIN=/path/to/Godot node tests/godot-runtime-smoke.mjs

GitHub Actions 对每个推送运行四个 job：

• check：Node.js typecheck、回归测试和 build
• npm package boundary：验证实际发布 tarball 不包含源码、测试和内部文档
• Godot 4.5.1 runtime：真实 EditorPlugin fixture smoke
• Godot 4.7.2 runtime：同一 fixture 的第二版本验证

Smoke 覆盖 search、context、场景属性/结构/实例化/脚本 apply-rollback、资源和输入设置、受限 project.setting.set 的持久化/读回/rollback 与外部编辑冲突保护、diagnostics、task lease、双 MCP 进程并发和 TTL 接管。项目设置证据还覆盖三个 key 的白名单、无当前场景时的项目级操作、未配置 main scene 的 snapshot、完整文件 revision 和恢复状态；这些内容不是完整的安全审计。

开发者入口

npm ci
npm run dev          # Inspector + MCP endpoint
npm run typecheck
npm test
npm run build
npm run package:check
npm run release:check

推荐先阅读：

• 贡献指南
• 贡献任务清单
• 行为准则
• 安全策略
• 隐私政策
• 增长与社区采用计划
• 长期采用路线图
• Agent 示例
• 客户端配置
• 验证证据索引
• 反馈指南
• 常见问题
• 60 秒演示脚本
• 社区发布文案
• Starter fixture
• 更新记录
• 发布清单
• 测试边界与 Godot 手工验收
• 完整产品计划
• Godot 插件说明
• 英文 README

License

MIT