io.github.wgt19861219/godot-mcp-enhanced MCP Server

Godot MCP Enhanced

免费 · 开源 · 安全 —— Godot MCP 赛道里少见提供 「系统化安全防护 + 三层架构 + 运行时控制」的开源方案。

给 AI(Claude Code、Cursor、CodeBuddy 等 MCP 客户端)一个能真正读、写、跑、验证 Godot 项目的 工具层:43 个 MCP 工具(merged,共 241 个 action;完整清单见 capability-matrix)覆盖场景/脚本/UI/动画/物理/粒子/导航/音频/测试/导出/3D 参数化资产(asset:11 shape + 路径阵列 + batch 原子 undo),三层架构 (headless + editor + game bridge)+ 路径白名单 / 注入防御 / sandbox 安全体系。

English · 工具描述为简体中文,服务中文 Godot 开发者社区;欢迎 i18n PR。

与同类方案对比

本项目不追求"工具数量第一"。 赛道里,godot-mcp-pro 有 175 个工具但闭源收 $15; 免费的 Coding-Solo 仅 13 个。真正稀缺的不是工具数量,而是「免费 + 开源 + 系统化安全防护」——安全维度在赛道内几乎无人设防。 数据截至 2026-06-27(stars / 工具数 / 价格均可能变化,详见各项目仓库)。

维度	本项目	godot-mcp-pro	GDAI MCP	Coding-Solo/godot-mcp
价格	免费	$15 买断 1	$19 买断 2	免费 3
开源	✅ MIT	❌ server 预编译闭源 1	❌ 2	✅ 3
工具数	43 (matrix)	175 1	~30 1	13 1
安全特性	✅ 路径白名单 / 注入防御 / sandbox / 确认令牌 / 输出防伪	—	—	—
架构	三层 headless + editor + bridge	单 editor WS 1	stdio 1	headless CLI 1
运行时控制（engine-level）	✅ game bridge：读运行时状态 / 输入模拟 / 录制回放 / frame-verify	❌ 仅文件·编辑器层	❌	❌
Godot 4.5–4.7 兼容矩阵	✅	—	—	—
中文工具描述	✅	—	—	❌

"—" 表示该项目公开 README 未披露相应能力,不代表必然缺失;欢迎 PR 修正。

不只是文件级 bridge,而是 engine-level 运行时控制。 赛道里多数方案(含闭源商业 SaaS)只能让 AI 读写项目文件,看不到、控不了一个正在运行的游戏。 本项目的 Game Bridge 通过 TCP 连接运行中的游戏:读运行时节点树与属性、GPU viewport 真实截图、属性采样、信号监听、输入模拟、录制回放,外加 frame-verify 反作弊验证——让 AI 真正闭环「改 → 跑 → 验证」,而非停在改文件。

从 Coding-Solo/godot-mcp 升级? 见 迁移指南 —— 核心能力零丢失,获得三层架构 / 安全 / 验证门禁 / 跨版本矩阵增强。

安全体系

截至 2026-06-27 调研,Godot MCP 赛道内少见提供系统化安全特性的方案。本项目内置多层防护, 适合对可信边界有要求的开发场景:

• 路径访问控制 — ALLOWED_PROJECT_PATHS 白名单(deny-by-default),防 junction / 符号链接绕过
• Godot 二进制白名单 — GODOT_MCP_ALLOWED_GODOT_PATHS（分号分隔,realpath 归一）在 godot --version 签名校验之上加硬隔离,防 AI 可控的 godot_path 工具参数/项目 override/env 指向任意二进制被 spawn(任意代码执行)。空 env = back-compat 放行(本地信任场景,签名校验仍兜底);多用户/不可信环境显式列可信路径
• GDScript 注入防御 — 危险 API 模式扫描 + 字符串拼接绕过检测
• 危险操作确认令牌 — 删节点等操作需显式确认
• 输出标记防伪造 — 每次执行随机标记,防 GDScript 伪造 MCP 输出
• 本地运行 — 无远程暴露,无第三方数据上传(注:启动时 update-checker 会查 npm registry,详见下方「匿名遥测」段)

<details> <summary><b>⚠️ 诚实的边界(展开必读)</b></summary>

以上是防误操作层,不是不可绕过的安全边界。GDScript 拥有完整系统访问权限, 沙箱可被间接方式绕过(call() 动态分派、多步变量构造 API 名、字符串拼接构造 API 名(如 "cu"+"rl"、str("OS")+".execute()")等)。

• 需真正隔离:容器 / VM + GODOT_MCP_ALLOW_UNSAFE=false
• 关闭扫描:GODOT_MCP_SANDBOX=disabled(仅开发)
• 本工具仅限本地可信环境,不提供远程认证或加密

</details>

匿名遥测（默认关闭）

opt-in,默认零外传。仅当显式设 GODOT_MCP_TELEMETRY=true 时启用,且阶段 0 endpoint 默认空 = 不发任何数据出进程。

• 收集什么:tool 名 + success bool + duration_ms + 错误分类(经白名单脱敏,非原始文本)+ 加盐 sha256 项目 hash(不可逆推原路径)
• 绝不收集:源码 / 场景内容 / 文件路径 / 项目名 / editor 日志 / 邮箱 IP 账号
• install UUID 存哪:~/.godot-mcp/telemetry-uuid.txt(POSIX 0o600)
• CI 强制关闭:CI=true 时即使 opt-in 也忽略,防 CI 触发合成事件

⚠️ 诚实披露 update-checker 外传点:本仓库每次 MCP server 启动时,src/core/update-checker.ts 的 fetch(REGISTRY_URL) 会被动 fetch https://registry.npmjs.org/godot-mcp-enhanced/latest(24h 缓存)。此行为与遥测无关但涉及「数据离开本机」。v0.25.7 起支持 GODOT_MCP_UPDATE_CHECK=false(或 0/no/off,大小写不敏感)关闭启动外传;self_update check action 经 force:true 短路此门控,且 risk='read' 不经确认令牌,AI 可自主调用触发外传(IP/UA 泄漏 npmjs.org)。严格零外传需防火墙、NO_PROXY=registry.npmjs.org 或 readOnly 模式拒整工具。详见 docs/telemetry.md。

代理环境变量:update-checker 的 npm registry fetch 遵守 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 环境变量（Node 默认 trustEnv）。企业代理环境下请求经代理；完全阻断可设 NO_PROXY=registry.npmjs.org 或防火墙规则。刻意不设 trustEnv: false——那会切断合法企业代理用户的更新检查。

⚠️ 诚实披露 vision-router 外传点: screenshot analyze action 设 vision_route=true + GODOT_MCP_VISION_KEY 时，截图 base64+prompt 外传到 https://api.groq.com（groq 视觉模型）。双重 opt-in 默认零外传（不传 vision_route 或不设 key → fallback 本地 detail 分层，零外传）。可设 GODOT_MCP_VISION_BASE_URL 指向自建/ollama/国内中转避免外传到 groq。详见 docs/telemetry.md。

Blender 建模（execute_bpy）安全模型

execute_bpy 通过 headless blender --background 跑 AI 写的 bpy 片段。bpy 是全功能 Python， 无语言层沙箱，威胁面 = 宿主 RCE（读/删任意文件、执行任意命令、网络）——高于 execute_gdscript 的 GDScript 沙箱一个量级（GDScript 语言层有约束，逃逸才到宿主）。

诚实边界：

1. glb 导出落点硬约束：export_path 经 resolveWithinRoot，仅约束 godot-mcp 注入的 export 行 filepath，不约束 bpy 代码内部的 open()/os.remove()/os.system()。
2. 本地单用户信任模型 + 响应附 [SECURITY] warning。
3. 不做 bpy 语法沙箱（正则防不住动态构造 = 假绿），列 backlog。

对比 BlenderMCP：不是"我们防住了它们没防住的"，而是"我们显式声明 fail-model + glb 落点硬约束 + 本地信任模型，BlenderMCP 既无约束也无声明"。

核心能力

三层架构 — 静态编辑 / 实时调试 / 运行时验证

不是单一连接,而是按场景分工的三层(自动检测,互不冲突):

层	连接方式	适用场景
Headless CLI	独立 Godot 进程	文件读写、批量创建、一次性验证(默认)
Editor WebSocket	连接运行中的编辑器	实时操作当前场景、Undo、场景树同步
Game Bridge	TCP 连接运行中的游戏	E2E 测试、运行时调试、输入模拟、状态验证

动态 GDScript 执行

execute_gdscript 让 AI 在 headless 模式执行任意 GDScript:代码片段模式(自动包装 extends SceneTree)、结构化输出(_mcp_output)、超时控制、Autoload 上下文(load_autoloads=true)、结构化错误(类型/文件/行号/修复建议)。

AI 开发闭环 — 不只是工具堆砌

read_scene / read_script → 理解结构 → write_script / edit_script
→ run_and_verify(错误分析)→ validate_scripts → verify_delivery(交付门禁)

• verify_delivery — 端到端交付门禁:场景树完整性 + 脚本健康 + 性能 + 自定义断言
• validate_scripts — 触发 Godot 完整编译(含跨文件依赖),捕获 headless 遗漏的 Parse Error
• dev_loop — 执行 → 验证 → 截图一体化,支持 acceptance 验收标准

闭环示例:AI 用 read_scene 理解 → write_script 改 → run_and_verify(capture_tree=true) 跑+分析 → validate_project 查资源 → batch_add_nodes 批建 → import_resources 注册 → 有问题回到改脚本。

批量操作与资源管理

• batch_add_nodes — 一次调用添加多个节点,只在最后做一次 pack+save,避免每个节点启停 headless Godot
• validate_project — 静态扫描缺失资源、无效 preload()/load() 路径、孤立 .import 文件
• import_resources — 扫描目录批量注册资源(图片/音频/字体/3D 模型),自动生成 .import

结构化开发流程（带 checklist）

对标 agentic skills 方法论（如 obra/superpowers），本项目不止堆工具，还提供 AI 可遵循的结构化开发流程（setup_project_rules 生成到 .claude/rules/godot-mcp-workflow-*.md）：

• Bridge E2E 流程 — install → run(wait_for_bridge) → ping → 操作+wait → 截图/frame-verify 留证
• 改→跑→验证闭环 — read → edit → run_and_verify → validate_scripts → verify_delivery
• 安全编辑流 — search_and_replace 优先 / 改后 validate / 防覆盖 / 确认令牌

每个流程带 checklist + 常见偏离提示，让 AI 少踩坑、按纪律走。

工具一览

共 43 个 MCP 工具(merged tool definition,共 241 个 action),以下按 action 逐项展开全部操作;权威清单见 capability-matrix。

关于「工具数」:本项目用 merged tool 架构——每个顶层 MCP 工具(如 scene)聚合多个 action(如 read_scene/add_node/save_scene)。顶层工具数:43(tools/list 返回条目数,与 capability-matrix 一致);action 总数:241(matrix 的 risk 聚合 read 120+write 95+destructive 10+process 16)。对比竞品统一用「顶层工具数」口径。两个数字均由 npm run build-matrix 从代码自动生成,CI 漂移检测守护。

执行工具

工具	说明
launch_editor	启动 Godot 编辑器 GUI
run_project	以调试模式运行项目（自动超时）
stop_project	停止运行中的项目，返回结构化输出
get_debug_output	获取分类调试输出（错误/警告/打印）
capture_screenshot	截取游戏画面（Windows 默认窗口模式，Linux/macOS 自动降级）
analyze_screenshot	AI 分析截图内容（元素识别、缺陷检测）
run_tests	运行 GUT 单元测试并解析结果
get_godot_version	获取 Godot 引擎版本

验证工具

工具	说明
run_and_verify	一键 headless 运行并返回结构化错误/警告分析。支持 capture_tree 选项同时获取场景树快照。自动检测版本不一致和脚本语法错误。
analyze_error	重新分析 Godot 输出文本，提供修复建议
validate_scripts	对每个脚本执行 Godot load() 编译验证（触发完整编译，含跨文件依赖解析），检测 headless 运行可能遗漏的 Parse Error

动态执行工具

工具	说明
execute_gdscript	在 headless 模式下执行任意 GDScript 代码。支持代码片段模式（自动包装）和完整类模式。设置 load_autoloads=true 可在完整 Autoload 上下文中运行（DataRegistry、PlayerData 等）。
query_scene_tree	加载场景并查询运行时节点树，返回解析后的实际属性值。
inspect_node	深度检查节点：所有属性、信号连接、子节点，支持递归深度控制。

项目工具

工具	说明
list_projects	搜索目录中的 Godot 项目
get_project_info	项目元数据 + 文件统计
list_files	列出文件（支持扩展名/子目录过滤）
read_project_config	解析 project.godot 为结构化 JSON
create_project	创建完整 Godot 项目结构
setup_project_rules	一键配置项目规则（hooks + CLAUDE.md），建议首次使用时运行
validate_project	检查缺失资源、无效脚本引用、孤立 .import 文件
import_resources	扫描目录批量生成 .import 文件（图片/音频/字体/3D模型）

场景工具

工具	说明
read_scene	解析 .tscn 为节点树 JSON，含属性类型解析（ExtResource/Color/Vector2/Vector3/NodePath/数组/字典/数字/字符串）
create_scene	创建新场景
add_node	向场景添加节点
batch_add_nodes	一次调用添加多个节点（比重复 add_node 快得多）
save_scene	保存场景更改
load_sprite	加载纹理到精灵节点
edit_node	编辑节点属性（位置/缩放/旋转/自定义属性）
remove_node	从场景移除节点（需确认令牌）
quick_scene	快速创建场景 + 可选脚本（一步到位）
instance_scene	实例化 .tscn 场景到目标父节点
detach_instance	从场景树分离实例节点
diff_scenes	比较两个 .tscn 场景文件差异
merge_scene	.tscn 冲突解决（三方合并，ExtResource/SubResource ID 重映射）

脚本工具

工具	说明
read_script	读取 .gd/.cs 文件（含元数据）
write_script	写入/覆盖 .gd 文件
edit_script	按行范围编辑 .gd 文件。支持 raw/smart 缩进模式、内容验证、变更前后对比。
generate_test	分析 .gd 文件并生成 GUT 测试脚本
create_test_scene	创建 GUT 测试运行器场景
project_replace	全项目批量搜索替换（CRLF 安全）

运行时操作工具

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。如需持久化场景修改，请使用 add_node + save_scene。

工具	说明
signal_connect	连接两个节点的信号。仅影响当前执行上下文。
signal_disconnect	断开信号连接。仅影响当前执行上下文。
signal_emit	发射节点信号，参数仅支持基础类型（string/number/bool/null）。仅影响当前执行上下文。
signal_list	列出节点上可用的信号。
physics_raycast	执行 3D 射线检测，返回碰撞点、法线、碰撞体信息。
physics_body_info	获取物理体的碰撞形状、AABB、碰撞层/掩码信息。
node_create_3d	运行时创建 3D 节点（支持 16 种白名单类型）。headless 创建不持久化。
nav_query_path	查询 3D 导航路径，支持指定 NavigationRegion3D 或自动回退。

音频播放控制工具（运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
audio_play	播放音频资源。支持 AudioStreamPlayer、AudioStreamPlayer2D、AudioStreamPlayer3D 三种节点类型。
audio_stop	停止指定音频播放器的播放。
audio_set_param	设置音频参数：音量 dB、音调缩放、总线路由。
audio_query	查询播放状态（播放中/暂停/停止）、当前播放位置、总线信息。
diagnose_physics	诊断物理体碰撞状态（含 ConcavePolygonShape3D 陷阱检测）。
query_spatial	空间区域查询：碰撞体距离排序，支持碰撞掩码过滤。
collision_overlay	创建碰撞形状彩色线框叠加（StaticBody=蓝/CharacterBody=绿/RigidBody=红/Area=黄）。

TileMap 编辑工具（运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。如需持久化 TileMap 修改，请使用 execute_gdscript 写入 .tscn 或在编辑器中操作。同时支持 TileMap（旧版）和 TileMapLayer（Godot 4.3+ 新版）两种节点类型。

工具	说明
tilemap_read	读取 TileMap/TileMapLayer 的 cell 数据，返回指定区域内的 tile 坐标、source_id、atlas_coords、alternative_tile。
tilemap_set_cell	设置单个 tile 的源图集和坐标。
tilemap_erase_cell	擦除单个 tile（设为空）。
tilemap_fill_rect	批量填充矩形区域内的所有 tile。
tilemap_clear	清空 TileMap/TileMapLayer 的所有 tile。
tilemap_copy	复制指定区域为模板（内部缓存），用于后续粘贴。
tilemap_paste	将已复制的模板粘贴到目标位置。
tilemap_set_transform	设置 tile 的翻转/旋转变换（水平翻转、垂直翻转、Transpose）。

所有运行时工具支持可选 load_autoloads 参数（默认 true），可在完整 Autoload 上下文中执行。

API 文档工具

工具	说明
get_class_info	获取类的方法、属性、信号、常量
search_classes	按名称/描述搜索类
find_method	查找方法详情（含继承链）
get_inheritance	获取完整继承链

材质与着色器工具（运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
material_read	读取节点材质属性和 shader uniform 列表
material_write	设置材质参数、创建/附加/保存材质（.tres）
shader_edit	读写着色器代码、加载 .gdshader、应用模板、编译诊断

Game Bridge 工具

工具	说明
game_bridge_install	安装 MCP Bridge autoload 到项目（WebSocket 服务端）
game_bridge_uninstall	卸载 MCP Bridge autoload
game_query	查询运行中游戏状态（场景树/节点属性/性能/视口）
game_input	向运行中游戏发送输入事件（键盘/鼠标/文本）
game_wait	在 timeout 窗口内轮询等待游戏状态条件（节点出现/属性值变化），支持 interval_ms 探测间隔。条件成立立即返回，超时返回 timed_out

工作流工具

工具	说明
dev_loop	开发循环：执行 GDScript → 验证 → 捕获输出，支持 save_state 文件即记忆
scene_snapshot	场景树快照，用于前后对比检测变更
batch_validate	批量验证多个 GDScript 文件

动画工具（运行时）

工具	说明
animation	查询、播放、编辑动画。支持 list_players、get_info、get_details、get_keyframes、play、stop、seek、create、delete、update_props、add/remove_track、add/remove/update_keyframe 等子操作

性能分析工具（运行时）

工具	说明
profiler	性能分析：快照（FPS/内存/绘制调用/物理统计）、采样分析、活跃进程检测、信号连接审计

3D 空间工具

工具	说明
spatial_info	获取 Node3D 空间信息：transform、AABB、bounds、区域查找

测试与导出工具

工具	说明
test_assert	断言场景树状态：node_exists、property_equals、signal_connected、node_count
test_stress	压力测试：重复创建/销毁节点检测内存泄漏
export_list_presets	列出项目导出预设
export_get_preset	获取导出预设详情
export_build	执行导出构建

粒子系统工具（运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
particles_create	创建 GPU 粒子节点（GPUParticles2D / GPUParticles3D）
particles_set_emission	设置发射参数：形状（point/sphere/box/ring）、半径、方向、扩散
particles_set_process	设置处理参数：重力、速度、爆炸性、生命周期、阻尼
particles_load_preset	加载预设效果：fire / smoke / rain / snow / sparkle / explosion
particles_set_material	创建或重置 ParticleProcessMaterial

导航工具（运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
nav_create_region	创建 NavigationRegion3D 并可选烘焙导航网格
nav_bake_mesh	烘焙导航网格（长时间操作）
nav_create_agent	创建 NavigationAgent3D 并设置寻路参数
nav_set_params	设置导航代理参数（10 个可配置字段：radius、height、max_speed 等）
nav_create_link	创建 NavigationLink3D 连接点（支持双向）

AnimationTree 工具（运行时）

注意： 运行时操作仅在 headless 执行上下文中生效，不持久化到 .tscn 文件。

工具	说明
animtree_create	创建 AnimationTree 节点（支持 AnimationNodeStateMachine / BlendTree / BlendSpace2D）
animtree_add_state	向状态机添加动画状态（AnimationNodeAnimation）
animtree_add_transition	在状态间添加转换（含交叉淡入淡出时间和条件）
animtree_set_blend	设置混合参数（float 用于 BlendTree，Vector2 用于 BlendSpace）
animtree_play	切换到目标状态（通过 playback.travel）

IK 框架工具（运行时）

工具	说明
ik_modifier_create	创建 IK 修改器节点（TwoBoneIK3D / FABRIK3D / CCDIK3D / SplineIK3D / JacobianIK3D）
ik_modifier_get	读取 IK 修改器属性
ik_modifier_set	设置 IK 参数（active、influence、bone_name、target、magnet）
ik_list_bones	列出 Skeleton3D 骨骼

验证交付工具

工具	说明
verify_delivery	端到端交付验证：场景树完整性 + 脚本健康 + 性能 + 自定义断言 + GDD 标准合规

游戏设计工具

工具	说明
validate_gdd	验证游戏设计文档是否符合 8 章节标准（概述、玩家幻想、详细规则、公式、边界情况、依赖、调优旋钮、验收标准）
chain_verify	Chain-of-Verification 自我质疑引擎：对审查结论生成 5 个挑战性问题，防止盲点和过度自信

代码模板工具

工具	说明
list_templates	列出可用代码模板（内置 + 用户自定义）
apply_template	应用代码模板到指定脚本（支持变量替换）

UI 布局工具（运行时）

工具	说明
ui_create_control	创建 UI Control 节点
ui_build_layout	CSS Flexbox/Grid 翻译层，从声明式布局描述构建 Godot Container 树
ui_set_layout	设置 Control 节点布局属性（锚点/偏移/最小尺寸）
ui_get_layout	查询 Control 节点布局信息
ui_anchor_preset	应用锚点预设（full_rect/center/top_wide 等 16 种）
ui_set_theme	设置/创建/保存/加载 Theme
ui_container_add	向 Container 添加子 Control 节点
ui_draw_recipe	声明式绘图操作（rect/circle/line/arc/polygon/string）
theme_create	创建空 Theme 或从节点提取 Theme
theme_set_property	设置 Theme 属性（font/color/constant/stylebox）

录制工具

工具	说明
recording_start	开始录制输入事件（键盘/鼠标）
recording_stop	停止录制并返回事件数据
recording_save	保存录制到 JSON 文件
recording_load	加载录制文件
recording_play	回放录制的输入事件

编辑器同步工具

工具	说明
editor_sync_start	启动场景树实时监听（推送 node_added/node_removed 事件）
editor_sync_stop	停止场景树监听

⚠️ 运行时工具(物理 / 动画 / UI / 粒子 / TileMap / 材质等)仅在 headless 执行上下文生效, 不持久化到 .tscn;需持久化用 add_node + save_scene。

MCP 资源（Resources）

AI 客户端可通过 godot:// URI 方案发现和读取项目上下文，无需显式工具调用。

静态资源

URI	说明
godot://project/info	项目元数据 + 文件统计（JSON）
godot://project/config	原始 project.godot 文件

资源模板

URI 模式	说明
godot://scene/{path}	读取 .tscn 场景为节点树摘要
godot://script/{path}	读取 .gd 脚本文件
godot://file/{path}	读取项目中任意文本文件

安全限制

• 路径必须在项目根目录下（禁止 ../ 遍历）
• .godot/、.import/、node_modules/ 目录被阻止
• .import、.uid、.godot 文件扩展名被阻止

使用示例

Client: ListResources → 发现所有场景和脚本
Client: ReadResource("godot://project/info") → 项目配置 + 统计
Client: ReadResource("godot://scene/scenes/main.tscn") → 节点树摘要
Client: ReadResource("godot://script/scripts/player.gd") → GDScript 源码

快速开始

1 分钟配置（推荐）

Claude Code — 全局安装（所有 Godot 项目自动可用）

claude mcp add -s user godot -- npx -y godot-mcp-enhanced

为什么用 -s user？ Godot MCP 是个人开发工具，你会在多个 Godot 项目中使用它。-s user（user scope）将配置写入 ~/.claude.json 顶层，所有项目自动连接，无需每个项目重复安装。详见 Claude Code MCP 文档。

如果你只想在当前项目使用（不推荐，切项目会丢失）：

claude mcp add godot -- npx -y godot-mcp-enhanced  # local scope，仅当前项目

Cursor / Cline / Windsurf / 其他

在项目的 .cursor/mcp.json 或 MCP 配置中添加：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-enhanced"]
    }
  }
}

腾讯 CodeBuddy（国内用户）

CodeBuddy 文档（2026-06-27 实测）支持外部 stdio MCP Server：设置 → MCP 标签 → Add MCP，粘贴与上面相同的 json。也可从其 MCP Market 一键安装（上架后）。

✅ 端到端已验证（2026-07-01）：CodeBuddy IDE 内 read_scene 读 main_3d.tscn 成功（返回完整场景结构），stdio MCP 接入跑通。解锁 MCP Market 上架（#10）。

Warp

Warp 终端 原生支持 MCP。Settings → Agents → MCP servers → + Add → CLI Server，粘贴与上面相同的 json（command: npx、args: ["-y", "godot-mcp-enhanced"]）；也可写入 ~/.warp/.mcp.json，或开启「Auto-spawn servers from third-party agents」直接复用上面的 Claude Code 配置（零额外配置）。

✅ 协议层实测通过（43 工具全发现、inputSchema 完整、无 integer 参数兼容风险）；⚠️ Warp GUI 端到端待补（本机未装 Warp）。完整步骤、兼容性核对表、env / working_directory 说明见 使用指南-Warp。

ZCode（智谱 GLM-5.2 ADE）

ZCode 原生支持 MCP。设置 → MCP 服务器 → 新建（stdio，command: npx、args: ["-y", "godot-mcp-enhanced"]），或写入 <项目根>/.zcode/config.json / .agents/mcp.json。关键：ZCode 不读 CLAUDE.md，只读 workspace 根 AGENTS.md——运行 setup_project_rules（默认双写）生成 AGENTS.md 让 godot 规则生效。

完整步骤、三种配置方式、env / 权限矩阵 / AGENTS.md 注入说明见 使用指南-ZCode。

一键配置

npx godot-mcp-enhanced setup
# 自动检测：Godot 路径 + AI 客户端 + 写入配置

首次使用

连接 Godot 项目后，建议立即运行以下工具一键配置项目规则：

setup_project_rules(project_path="你的项目路径")

这会自动生成：

• .claude/settings.json：PostToolUse hook，每次编辑 .gd 文件后自动提醒 AI 运行 validate_scripts 验证语法
• CLAUDE.md：项目级规则，包含 GDScript 验证规则和发版门禁（verify_delivery 检查）

如果已有配置想更新，使用 force=true 覆盖。如只需其中一项，用 hooks=false 或 claude_md=false 跳过。

环境变量

变量	说明	默认值
GODOT_PATH	Godot 可执行文件路径	自动搜索（PATH/注册表/Scoop/Downloads）
GODOT_PROJECT_PATH	默认项目路径	自动检测 cwd（向上搜索 project.godot）
GODOT_MCP_SEARCH_PATHS	额外 Godot 搜索目录（分号分隔）	无
GODOT_MCP_ALLOWED_GODOT_PATHS	Godot 二进制路径白名单（分号分隔,realpath 归一）。空=放行(签名校验仍兜底,适用本地单用户);多用户/不可信环境显式列出可信 Godot 路径,防 godot_path 工具参数/项目 override/env 指向任意二进制被 spawn(任意代码执行)	空(放行)
DEBUG	启用详细日志	false
GODOT_MCP_BRIDGE_PORT	game bridge 起始监听端口（被占自动递增避让至 +9;多实例并存安全,实际端口写入实例 registry,ping 响应带 pid/project 指纹）	9081
GODOT_MCP_ALLOW_UNSAFE_CONFIRM	true=confirm 类写操作跳过 out-of-band 确认（⚠️ 削弱安全防线;生产环境设此值 server 拒绝启动,详见使用指南 12.12）	false
GODOT_MCP_TELEMETRY	匿名遥测 opt-in(默认关闭,详见 docs/telemetry.md)	false
GODOT_MCP_PROFILE	工具 profile(basic/lite/minimal/full/bridge_dev/3d_dev 或逗号组名)。默认 basic(BREAKING from full;lite 9 组省 ~60% context,RCE action 经 action-gate 默认 gated)。回退全量:GODOT_MCP_PROFILE=full 或 --profile=full	basic

⚠️ BREAKING(G7):默认 profile 从 full 改 basic(对齐 GoPeak compact,省 AI context window)。升级后 tools/list 只暴露 basic(lite 9 组:core/bridge/animation/audio/signal/visual/code/test/profiler)。回退全量 41 工具:GODOT_MCP_PROFILE=full;或 AI 运行时 manage_tools activate <groups> 动态扩容(无需重启)。RCE action(execute_gdscript 等)始终经 action-gate gated,需 GODOT_MCP_PRIVILEGED_GROUPS=code-execution 解锁。

注意： 项目路径有 30 秒缓存。切换项目后等待 30 秒或重启 MCP server 使新路径生效。

多版本 Godot 支持

如果你使用 godots 等版本管理器管理多个 Godot 版本，可以为每个项目单独指定 Godot 二进制路径。

优先级：工具参数 godot_path > 项目配置 > GODOT_PATH 环境变量 > PATH > 平台搜索

方式一：项目配置文件（推荐）

在项目目录下创建 .godot/mcp-godot.json：

{
  "version": 1,
  "godot_path": "/path/to/Godot_v4.6.3-stable_macos.arm64"
}

方式二：project.godot 配置段

在 project.godot 末尾添加：

[godot_mcp]
godot_path=/path/to/Godot_v4.6.3-stable_macos.arm64

方式三：工具参数

在 MCP 工具调用时传入 godot_path 参数（如 run_project、execute_gdscript 等 10 个核心工具均支持）。

方式四：godots 版本管理器自动检测

在项目根目录创建 .godot-version 文件（内容为版本号，如 4.6.3），MCP server 会自动在 ~/.godots/versions/ 中查找对应版本。

手动配置（高级用户）

<details> <summary>展开查看手动安装步骤</summary>

git clone https://github.com/wgt19861219/godot-mcp-enhanced.git
cd godot-mcp-enhanced
npm install && npm run build

在 MCP 配置中指向 build/index.js，并设置所需环境变量。

</details>

致谢

• godot-mcp — 原始项目，本项目基于其二次开发（Copyright (c) 2025 Solomon Elias，MIT，见 LICENSE）
• Hastur Operation Plugin — 动态 GDScript 执行和结构化输出的灵感来源
• Claude Code Game Studios — 借鉴了以下功能概念：
  • Hooks + Rules 体系 → setup_project_rules 自动生成 .claude/settings.json（PostToolUse hook 自动验证 GDScript）和 CLAUDE.md（项目编码标准）
  • Gate-check / verify → verify_delivery 端到端交付验证（场景树完整性 + 脚本健康 + 性能 + 自定义断言 + GDD 合规）
  • Workflow pipeline → dev_loop 执行→验证→截图一体化工作流，支持 acceptance 验收标准和 save_state 会话记忆
  • GDScript Lint → validate_scripts 内置的静态 lint 层（L015 行级扫描 + 字符串/注释过滤，独立于 load() 编译检查），对标 CCGS 的 validate-commit.sh
  • GDD 标准 → validate_gdd 8 章节游戏设计文档结构校验，对标 CCGS 的 design/gdd 路径规则
  • Chain-of-Verification → chain_verify 自我质疑引擎，防止审查盲点
  • 代码模板 → list_templates / apply_template 模板系统，对标 CCGS 的 41 个文档模板

系统要求

• Godot Engine 4.x（已测试 4.7；4.6/4.5 向后兼容）
• Node.js >= 18
• GUT 插件（用于 run_tests 工具）

<details> <summary><b>截图功能平台说明</b></summary>

capture_screenshot 工具根据平台使用不同的渲染策略：

平台	模式	说明
Windows	窗口模式（默认）	Headless 模式下 viewport 纹理返回 null，必须使用 GPU 上下文
Linux	Headless → 窗口模式降级	Headless + OpenGL3 取决于 GPU 驱动是否支持
macOS	Headless → 窗口模式降级	与 Linux 相同

内置 screenshot_capture.gd 使用 process_frame 信号模式和 call_deferred() 确保场景加载和帧捕获的可靠性。

测试提示： 仓库的 E2E 测试（test/e2e-*.test.ts）依赖真实 Godot 二进制。设置 GODOT_PATH 指向本地 Godot 以运行它们；未设置时这些测试被静默跳过（控制台打印 [E2E-SKIP] 告警），CI 默认不验证真实 Godot 集成——npm test 的"全部通过"仅覆盖 TS/GDScript 逻辑，不含真实 Godot 子进程行为。

</details>

许可证

MIT — 含上游 Coding-Solo/godot-mcp 版权（Copyright (c) 2025 Solomon Elias）。

路线图

项目方向与里程碑(M1 定位与声量 / M2 健壮性 P0 / M3 安全 P1 / M4 功能补齐 P2)见 ROADMAP.md。

更新日志

完整变更记录见 CHANGELOG.md。

版本	日期	要点
v0.32.6	2026-08-19	tilemap 可选 scene_path(外部贡献 PR#36,thefireKS):tilemap 八个 action 新增可选 scene_path——传入则 _mcp_load_scene() 加载指定场景并在其中解析节点(_mcp_get_scene_node() 自动剥 root/ 前缀与场景根名),省略则生成脚本逐字节不变(仍主场景);此前八生成器硬编码 application/run/main_scene,主场景是菜单的项目只能拿到误导性的 TILEMAP_NOT_FOUND。scene_path 经 resolveWithinRoot 白名单(越界 INVALID_PARAMS+负向测试);九处重复 preamble 收敛 scenePreamble;转义对齐 escapeForGdLiteral;作者真机 Godot 4.6.2 端到端验证(575 cells)。43 工具/241 action。
v0.32.5	2026-08-19	债务清理批收尾:screenshot_capture 空白检测采样退化修复(线性步进整除视口退化最左单列→10×10 网格分层采样,800×600 类视口不再误报 BLANK);gdEscape→escapeForGdLiteral 转义类闭类三批(纯字面量上下文含 % 路径/值不再被双写,唯一 % 格式串上下文维持 gdEscape);PR-4 终审 Minor 清账(M-1/M-2/M-5,M-4 executor timeout 30s 决策维持);README 口径三处修复+README.en 同款+check-tool-count 防复发(20→24 处);spec §10.5 两决策输入落答(flow FILL h=39 根因=float32 比例锚点残差+HBoxContainer FILL 子高度整数截断;flow 容差维持 2)。43 工具/241 action。
v0.32.4	2026-08-18	原型翻译层单 spawn 合成(PR-4):ui_import_prototype 内部链 build→persist→reload→measure 由两次 Godot spawn(~6s)合成单 spawn——reload 用 ResourceLoader.load(path, "", CACHE_MODE_IGNORE) 绕过 ResourceCache(同进程裸 load 二载命中缓存旧实例,spec §6 B-1),篡改磁盘断言证明 reload 真读磁盘;失败错误内嵌「build 已持久化,可重跑」恢复语义;规则双副本 3 处措辞精确化(PR-3 终审 M-1/M-2/M-7)。43 工具/241 action。
v0.32.3	2026-08-18	原型翻译层像素终验(ui_pixel_verify,PR-3):ui 工具新 action——对已构建场景(scene_path 必填,persist 产物)窗口模式截图(Windows 专属,headless dummy renderer 空白),每 bg 节点采样中心+四角内缩点(内缩 clamp min(borderRadius+border.width, 短边/2−2) 防圆角越界;半开区间角点右/下缘 −1,否则 inset=0 采到节点外背景假红)与目标色 0-255 RGB 欧氏距离判定(中心容差 20/角点 60,集成校准 css-card 真渲染 13 采样点 d=0.0 零底噪零偏移);采样跳过两类(半透明 bg 合成后不可直判;ProgressBar 系——fill+百分比文字覆盖 bg 渲染面,bg 槽依赖 style_verify),带 text 节点跳中心点仅采四角(居中排版必踩文字);BLANK 双条件拦截(stdout 提示+PNG 全图 8x8 网格均匀色,两证据独立一致才拦);PNG 中间产物失败路径也清理;定位终验(几何+style_verify 全绿后跑一次,窗口模式弹窗+秒级耗时)。附带 T5a border 暴露渠道措辞修正(style_verify 同源恒绿暴露不了,真暴露渠道是像素采样,4 处)/T5c 孙层由 layout_verify 近似覆盖措辞+七槽 TS/GD 互指注释(5 处)。43 工具/241 action。
v0.32.1	2026-08-18	原型翻译层 verify 层(style_verify + flow_verify,PR-2):ui_import_prototype 返回与 ui_measure_layout(expect_tree 时)新增 style_verify(逐节点逐槽位逐属性 diff——measure 脚本按需读回「期望清单 ∪ override 并集」的 get_theme_stylebox(slot) 生效值,非 StyleBoxFlat 以 type 红条目暴露,颜色容差 0.002、corner/border 宽度精确匹配)+ flow_verify(翻译层产出 flow_expect,flow 直接子节点期望视口 rect vs 容器排布实测 global rect 直接 diff,B-2 补偿防线从 screenshot diff 兜底升级为数字清单;孙层维持近似覆盖);validate 层补强(bg_color/border_color 四元数组对称校验、corner_radius 布尔/null/数组显式拒);fill-only 灰底 warning(透明壳被 fill 输入阻断时声明默认主题灰底);M-1 border 四边各异不单独 warning 双副本显式声明(生产者仅取 top;style_verify 同源恒绿暴露不了,真暴露渠道是像素采样——0.32.3 ui_pixel_verify)。43 工具/240 action。
v0.32.0	2026-08-17	原型翻译层 StyleBox 通道(StyleBox PR-1,bg 为 BREAKING):ui_import_prototype 样式翻译从 modulate 近似染色迁移到真 StyleBoxFlat——bg/fill/borderRadius/border 统一 override(经 add_theme_stylebox_override,落盘名 theme_override_styles/<slot>;槽位映射 Panel→panel、ProgressBar→background+fill、Button/Label→normal,其余 warning+忽略;bg 缺省而 border/radius 存在→draw_center=false);新增 fill/borderRadius/border 三字段(geometry schema);GD 生成器 _sb_N 构造块+draw_center 布尔校验(堵注入);规则 7 钳制预警恢复无条件(实测 h=16 全 override 组合仍被钳 23/27);evaluate 模板 toHex→toRgba([r,g,b,a] 保留 alpha)+borderRadius/border/fill 三件套采集;规则双副本 9 处镜像同步 STRICT 绿。43 工具/240 action。
v0.31.4	2026-08-17	QA 断言四件套 + 应用级异步长跑(QA 深化 PR-1a/PR-1b):qa 套件 +4 控制步骤(watch/monitor start
v0.31.3	2026-08-16	QA 编排收尾 + 双副本 STRICT 门禁 + 原型小修批：B qa nightly <spec-dir> CLI 夜间跑批（目录全量跑+每套件与上次同套件报告 diff+回归/修复汇总+退出码）+ record_on_failure 套件选项（失败自动留录制,落 qa-reports 与 recording_play 兼容）+ CLI audit 留痕（isAuditEnabled 开关对称）+ NIT-8 五分支测试补全;双副本内容一致性 CI 从 advisory 假接线升级 STRICT 阻断（历史 drift 8/9 文件清零,归一化收紧锚定版本行,bridge/recording 模板按 GD 权威产物纠正字段与路径形态）;原型翻译层遗留小修（显式 Panel 无 bg 灰底翻转 warning/parent_path 尾斜杠归一化）+ token budget warn 基线 80→90KB + CI Linux 平台债三根因修复（fixture globalSetup/pngjs 自生成/XAUTHORITY）。43 工具/238 action。
v0.31.2	2026-08-16	final review 修复波：规则 4 透明壳收窄——只对推断布局壳 Panel 设 self_modulate,自带视觉控件（ProgressBar/Button/任何显式 type）豁免,修复 HP 条被误设透明壳而 diff 假绿（集成补 HpBar 落盘断言+负例验证）;parent_path 根级参照系限制 schema 声明+非 root 时 build_warnings 提示;坏图可区分性实测证据（好图对 0.1762 vs 下半消失合成坏图 0.4797≈2.7 倍,双副本改基线口径）;screenshot threshold 显式 null 落默认 0.12 + action 提示补 diff;ui.md 双副本历史 drift 顺带归零。
v0.31.1	2026-08-16	原型翻译层 + 视觉验收：ui 工具族新 action ui_import_prototype（HTML 原型几何 JSON 一次调用 翻译→build(固定 persist)→measure→layout_verify;扁平视口坐标自动建树、strict schema 拒未知字段、12+1 翻译规则含 Label 垂直居中/透明壳 self_modulate/flow Holder 壳/ProgressBar 最小高 27 预警;返回 verify_coverage 覆盖率）+ screenshot(action=diff) 像素级双图对比（RGB 欧氏距离 threshold 默认 0.12,返回 diff_pixels/diff_ratio/bbox,可选红染差异图,零新依赖）+ 规则双副本登记（ui.md 用法+浏览器 evaluate 取数脚本模板含 textAlign→align 采集与 value 0-1 守卫、engine-quirks 4 条 UI 渲染陷阱）+ 双副本历史 drift 修复（set_anchors_preset 条目/frontmatter）。中间版 0.30.1-0.31.0 详见 CHANGELOG。43 工具/238 action。
v0.30.0	2026-08-15	AI QA 编排 + 理解层 + 协议债（方向拍板 B/C/D,零 GDScript 改动纯 TS 批次）：B qa 工具（结构化测试规范→自动装 bridge→起游戏→13 种步骤逐步执行/断言/确定性 playtest→聚合报告+回归 diff,报告落 ~/.godot-mcp/qa-reports,CLI npm run qa 夜间跑批;run=process 风险经 confirm+audit 一次覆盖）+ C analysis 工具（signal_map 全项目信号连接两来源全景 + impact_check 改信号/脚本/场景前列受影响面,免费开源版对标 GodotIQ Pro,纯静态零 Godot 依赖;tscn [connection] 补 flags/binds 解析）+ D ⚠️ MCP Roots 动态授权退役（Breaking,legacy+roots 客户端统一走 ALLOWED_PROJECT_PATHS env,modern era 零变化） + protocol-debt 决策文档（Logging 窗口内保持/Sampling 零使用/Tasks+MCP Apps defer）。43 工具/235 action。
v0.29.0	2026-08-15	2026-08-14 六批次审查 findings 全量修复（P0×1 + P1×10 + P2/P3,43 commits,双波终审）：P0 editor 重连链死修复（编辑器重启后自动恢复）+ 安全面（write_script 沙箱 4 旁路入口封堵/deny-list 拼写/load_skill 白名单/nonce symlink）+ audit 工具复活（生产 bug,0.28.3 特性此前不可见）+ playtest 六项（永久暂停/owner 互斥/paused 保存等）+ 属性写入 no-op 假成功三路对齐 + bridge 订阅断线恢复 + ⚠️ autoload 键名迁移（Breaking,旧项目重跑 game_bridge_install 自动迁移）+ debug/undo GD 修复 + 测试债（debug e2e 首跑/GD 套件/dispatcher 审计 9 场景）+ 披露对齐。发版门禁全绿（verify_delivery 3/3 + e2e L2 真跑 75 passed）。
v0.28.3	2026-08-13	战略批收尾（14 竞品路线图 G1/G3/G7）：G3 操作级审计日志（audit.jsonl appendFile 原子追加,危险操作可追溯/回放）+ G1 deterministic playtest control 层（freeze/unfreeze/step_until 结构化条件,规避 RCE）+ G7 能力 profile（basic=9 组/advanced/full,BREAKING：默认 profile 从 full 改 basic,schema 79KB→~30KB 省 ~60% context）。路线图全完成（G2/G3/G1/G7/G8 ✅,G6 实测已有移除）。
v0.28.2	2026-08-12	安全加固 + 威胁模型 + 可观测性 + 审查修复：G2 trace_id + 结构化错误分类 + PII 护栏（速赢批）+ S-1/S-2 bpy-sandbox 双 opt-in + spawn 清单 + S-3S-7 多实例 registry/editor-auth/http-server 加固 + G8 威胁模型文档（10 层防护实测声明）+ P0 animtree sub_action 死代码修复（F-6 CRITICAL）+ P1 data-import timeout 钳制（F-1/F-2）+ P2 工具层校验精确化（F-3F-8）+ CMP-13 generate-all-modules + Tier1 structuredContent/prompt + Tier2 skills/tscn parser + Vision Routing 双 opt-in。
v0.28.1	2026-08-11	安全加固批次 C + 测试质量：批次 C 安全加固（deny-list/symlink/path/debug.evaluate RCE 多点）+ instance_registry 目录权限 Linux 0o700（P2-4）+ 弱断言精确化与接线守护批次（P1-3~P1-5/P2-1/P2-2）+ MULTI_INSTANCE 接入 godot-matrix（P1-2）+ 全批次第三方审查文档。
v0.28.0	2026-08-09	CMP-14 debug Phase 2/3 + 后续批次：debug 工具组从 3 action 扩到 10（完整交互式调试器：栈帧/变量/表达式求值/step 控制/继续/暂停/热重载）+ 新建 EditorDebuggerPlugin 子类（debugger_bridge）+ handle_debug_async 异步路由 + 自动打开脚本（修 Phase 1 限制）+ CMP-16-B advanced-proxy 真动态化 + CMP-16-C drift 映射表扩到全 64 method + CMP-9 confirm gate 守护测试。
v0.27.0	2026-08-08	CMP-9 双通道通用方法调用 + CMP-16 live schema（竞品 regiellis/godot-mcp-go 深度对标）：CMP-9-A editor engine call_method（场景树节点实例方法调用,did-you-mean + 类型强转 + deny-list 护城河）+ CMP-9-B bridge _cmd_call_method 放宽（env 扩展写方法 + did-you-mean + 类型强转）+ CMP-16-A GD param docs metadata（13 文件 57 method docs + list_param_docs 聚合）+ CMP-16-B TS live schema（dynamic-schema.ts 从 addon 拉 docs 构建 MCP 工具 + 缓存/降级/刷新 + registerDynamicTools）+ CMP-16-C drift 检测 CI（debug+engine 7 method 校验）。4749 测试。
v0.26.0	2026-08-08	P1+P2 批次修复（18 项审查 finding 闭环）：GD-R1R10 GDScript 健壮性（nav status 同源/_ErrorCapture 复位重构/debug 注释/engine enum 补值+search 排序/错误诊断细化/export JSON 化/recording 路由清理）+ IPC-R1R6 可靠性（env→显式参数/删无效 gap 检测/长操作暂停 TS 心跳/重连 stale 通知/baseline 排除离群点）+ SEC-P1-1 write/edit 沙箱扫描（对齐 execute_gdscript）+ CMP-7 editor instance discovery（addon registry + pid liveness）。三次第三方审查全通过。4667 测试。
v0.25.11	2026-08-08	实时 ClassDB 内省：新增 engine 工具组（editor-only），class_info/search/get_inheritance 走 editor 层直调 ClassDB。让 AI 发现运行中引擎的实际可用类/方法/属性（补静态 docs 的 4.7 快照缺口，含第三方 addon/自定义类/版本差异）。
v0.25.10	2026-08-08	debug 组 Phase 1 断点管理：新增 debug 工具组（editor-only），set/clear/list breakpoint 走 CodeEdit gutter（gutter 可见 + game 命中 + 跨 run 同步）。从无到有的交互式调试能力。留 Phase 2 step/resume/pause + 栈帧读取。
v0.25.9	2026-08-08	竞品 godot-mcp-go 深度对标产出：CMP-1 editor 项目匹配检查（连接建立后校验 project_path，mismatch 拒绝降级，防跨项目误操作；覆盖首次连接 + rebuild + 自动重连三条路径 + junction realpath fallback）+ CMP-2 game bridge runtime error 捕获（_ErrorCapture Logger 子类 ring buffer 200，捕获全部 4 种错误类型 ERROR/SCRIPT/SHADER/WARNING，get_errors/clear_errors 两个新 method，since-seq 增量查询，re-entrancy guard 防 error storm）。两次第三方审查均 SHIPPED。4571 测试。
v0.25.8	2026-08-07	5 批审查修复闭环：批次1 GDScript 假成功（save_scene/load_sprite/screenshot 失败补 quit(1) + _cmd_playtest_restore Resource 反向转换 + _cleanup_peer_state 漏清 snapshot）+ 批次2 TS 可靠性（resetBridgeState 清 push 子系统 + STARTUP_CLEANUP.finally + health-monitor degraded 不被心跳过早清除 + playtest owner_pid 多 peer）+ 批次3 安全纵深（FileAccess READ 非 Godot 协议拦 + 网络回连 API 进沙箱 + stripLiterals 扩 user://）+ 批次4 测试缺口（P3-6 socket 竞态并发测试 + C# 回滚测试 + 4 CI 守门脚本）+ 批次5 文档收尾（update-checker 门控语义健壮化 + 文档漂移修正）。4534 测试。
v0.25.7	2026-08-06	P3 选做三批（审查 SHIPPED WITH NITS）：P3-1/P3-2 版本同步收口（server.json/Dockerfile 纳入 version-sync，根治分发产物漂移）+ P3-7 C# 阶段一收尾（project_replace 白名单/read using/edit 验证回滚）+ P3-6 subscriptions/listen（bridge 事件主动推送，watch/monitor push 模式三层改造）+ P2 第三方审查 B-1/I-2/I-3 修复。4517 测试。
v0.25.6	2026-08-06	P2 Wave2：P2-4 确定性 playtest 四原语（seed/fixed_delta/step/snapshot/restore）+ P2-5 SEP-2133 extensions 声明（runtime-bridge 发现性）。
v0.25.5	2026-08-06	P2 Wave1：P2-1 overrides 注入 autoload（启动前注入调试脚本）+ P2-6 recipe 验证闭环 + P2-2 validate_scripts autoload 纠偏 + P2-3 nodeType RCE 审计白名单收尾。
v0.25.4	2026-08-05	P0（6/6）+ P1（7/7）协议层升级：SDK v1→v2（@modelcontextprotocol/server 2.0）+ MRTR 双时代 + action 级 capability gate + runtime_assert/help 工具 + P1 全 7 项（SEP-2575 modern era/SEP-2549 cacheHints/SEP-2577 per-request logLevel/视觉成本层级/契约 CI/idempotentHint）+ 测试覆盖加固批次。
v0.25.3	2026-08-01	全天审查收尾（SHIPPED）：P2-12 二期 async 改造引入的 arena 前缀碰撞 BLOCKING 根治（方案 B _mcp_test_persistent meta opt-out，运行时对照实验闭环）+ NIT-3 抽 _runWithOpTimeout（含 return-await 隐藏 bug 修复）+ NIT-2 bpy-sandbox % 格式化构造检测 + NIT-1 删死代码。4381 测试。
v0.25.2	2026-08-01	P2-12 McpTestSuite 移植（editor 路线，关闭 P1-5）：AI 可写标准化 GDScript 测试套件（extends McpTestSuite），editor 模式 testing 工具执行 + 一期/二期 async coroutine 防 keepalive 饿死 + P1-2/P2 安全（execute_bpy 拼接检测/animation coerce/ui theme/export 白名单）+ P3 文档纠正（editor.exists 失真修复 7→0）。36 工具/205 action。
v0.25.1	2026-07-31	竞品对比批①-④ 落地（审查 SHIPPED WITH NITS）：工具数口径修正（21 处漂移 28/29/33/130+→35/203，含 rule-templates 独立副本同步防下游污染）+ check-tool-count.mjs CI 校验脚本根治漂移 + 进程生命周期 P0 周期 orphan 扫描/P1 启动清理（STARTUP_CLEANUP opt-in）+ command_helpers 纯函数行为测试（L2 none→partial）+ nav N1-fix（bake_mesh 末行 freed 守卫）。4293 测试 + verify_delivery 3/3 通过。
v0.25.0	2026-07-30	A-RCE 安全批次（headless instantiate_class 白名单堵 extends Node RCE + self_update 符号链接校验 + execute_bpy 危险 API 扫描 + profile 硬隔离 + godot_path 白名单）+ B 可靠性（nav bake 超时对齐/gdscript spawn orphan 清理/心跳降级区分 timeout-refused/HOL 预检/全系统扫跳过 --editor）+ C 正确性（adapter env 白名单合并/nav freed 守卫/doctor stripBom/update-cache 字节上限/updateAddon 原子化）+ Telemetry 骨架（opt-in 默认关，零外传）+ Nav bake 准确性（async-dispatch，bake_result 从乐观改 get_vertices 判据）+ 测试质量（e2e 清理 .godot 缓存防假绿 + 弱断言精确化 576 条）。
v0.24.1	2026-07-27	文档同步修复：rule-templates.ts 补齐 get_node_layout 同步（独立副本约束 drift，第三方审查发现）+ AGENTS.md 三段强制流程（.claude/rules/ 改后核查 / plan 落地后必出第三方审查文档 / 完成前必登 memory）+ 新增 docs/reviews/ 目录补 5 条 7 月断档链路审查文档
v0.24.0	2026-07-25	self-update 机制(Godot AI 追赶 3/3：npm 启动检查 + self_update MCP 工具 addon 检查/更新)+ 5 批审查全闭环(A 安全 RCE class_path/路径穿越/symlink + B 可靠性降级链路/资源写原子化17处 + C 正确性协议契约/undo/参数校验 + D 工具治理 asset/android TOOL_GROUPS + E 测试缺口加固10/10)+ batch F 测试覆盖深度(6 task 假绿修复/纯函数单测/安全动态断言/防回归契约/skip 可见化)+ CI Godot 4.6.3/4.7.1 版本矩阵 + ZCode 深度支持/AGENTS.md + orphan 扫描会话隔离 + editor key 多实例误删修复 + take_screenshot null guard，4030 测试
v0.23.0	2026-07-13	安全 CRITICAL(零确认 RCE 复合链 6406de4 + confirm_and_execute elicitation out-of-band gate 堵 AI 自确认 token 18ef867 + GODOT_MCP_ALLOW_UNSAFE_CONFIRM opt-in 降级)+ editor 路由解锁(editor-method-map 登记 animation_track/export/particles/nav/animtree/ui 21 action 356a061 + scene/node/open_scene/reconnecting)+ bug 修复(path_generator 死循环/scene vector3 coerce/asset color+count/data-import A1-A3)+ HealthMonitor editor stall 检测 85f5328 + 删 ReconnectionManager 死代码 410 行 f2773fb
v0.22.0	2026-07-08	asset 工具集新工具(11 shape + 路径阵列 discrete/continuous + batch 原子 undo + save 预制件 + 10 材质预设;方案 A 阻塞 continuous ramp 待上游)+ capability-matrix 33 + LICENSE 致谢 AssetForge/Tripo3D
v0.21.0	2026-07-06	csv_to_resources 新工具(CSV→Godot 资源批量导入,双轨 TS+GDScript)+ ToolAnnotations hints(actionRisks 派生 readOnly/destructive)+ 多轮独立审查核实修复(RCE/ipc/data-import/综合审查 editor 路由 -32601 回退+guard 接线+heartbeat 暂停语义)+ editor 4.7 兼容(EditorInterface/super() 回归/Safe save)+ capability reviewer 设施 + e2e L2 opt-in
v0.20.0	2026-06-30	cpp GDExtension 脚手架(scaffold_gdextension 生成 8 文件 C++ 工程骨架)+ 全工具验证靶子(real-project 三层 L1/L2/L3 自动化,28 工具正路径)+ 工具行为修复(default-null 统一/run_project isError/timeout race)+ R3/安全审查修复
v0.19.1	2026-06-27	版本元数据同步(manifest/plugin.cfg/README/使用指南)— 功能无变化,补 v0.19.0 npm 元数据漂移
v0.19.0	2026-06-27	R2 审查响应链 — editor 4 模块 undo_manager(nav/particle/animtree/ui Ctrl+Z 撤销) + super() IMP-4 + IMP-11 touch 双侧契约 + 安全同源 4 点(UI/audio/instance) + @748 detach 双 parent fix + 阶段1b 守卫,2894 测试
v0.18.2	2026-06-18	安全加固 — 沙箱绕过组 + 防御深度 + 注入收敛,2670 测试
v0.18.1	2026-06-14	功能验证审查 3 CRITICAL 修复 — parseTscn 属性/头部解析（read_scene 现正确返回结构化属性）+ game_wait 轮询等待（pollWaitCondition），2597 测试
v0.18.0	2026-06-10	工具合并（39→27 MCP 工具）+ LEGACY 兼容模式 + manage_tools 迁移 + notifyToolsChanged
v0.17.1	2026-06-08	五维审查 P0+P1 全量修复 — tscn 死代码删除 527 行 + core/tools 解耦 + animation-ops +38 测试 + EditorExecutor +16 测试 + 安全加固，2252 测试
v0.17.0	2026-06-07	审查修复 9 项（4C+5I/A）— tscn 编辑正确性 + 确认令牌截断保护 + 字符串 UID + 安全加固，2023 测试
v0.16.0	2026-05-31	审查驱动质量提升 — ToolDispatcher 提取 + 87 次提交 + merge_scene + 项目脚手架 + 智能类型转换 + 1638 测试
v0.15.1	2026-05-27	Godot 4.6 editor plugin 兼容性修复
v0.15.0	2026-05-27	6 代理并行审查（14 CRITICAL 修复）+ deny-by-default 安全 + Bridge 录制 + ESLint + 1509 测试
v0.14.0	2026-05-24	7 轴全维度审查（8 CRITICAL 修复）+ IK 框架 MVP + Vitest 迁移 1257 测试
v0.13.0	2026-05-23	Bridge 安全加固 20 项 + requestId 取模 + CSS Grid + EditorConnection 重连上限
v0.12.0	2026-05-23	迭代 URL 解码防路径遍历 + verify_delivery 4 维度验证 + dev_loop acceptance
v0.11.1	2026-05-22	Bridge TCP 绑定 127.0.0.1 + 密钥文件读后即删 + opsErrorResult isError 修复
v0.11.0	2026-05-22	CSS Flexbox 布局翻译层 + GDScript Lint 规则引擎 + 路径遍历防护增强
v0.10.1	2026-05-21	Bridge TCP 绑定本地地址 + 密钥文件生命周期管理 + opsErrorResult 修复
v0.10.0	2026-05-19	场景实例化 + 编辑器实时同步 + 代码优化重构（124 工具）
v0.9.0	2026-05-16	批量工具 + UI 工具 + 录制系统 + 确认令牌 + Read-Only/Lite 模式（118 工具）
v0.8.0	2026-05-13	双模式架构 + 测试框架 + 粒子/导航/AnimationTree（96 工具）
v0.7.0	2026-05-08	安全加固 + 输入转义 + 类型安全 + tscn-parser 修复
v0.6.0	2026-05-03	音频播放控制 4 工具 + TileMap 编辑 8 工具
v0.5.0	2026-05-02	信号控制 + 物理查询 + 3D 创建 + 导航寻路（8 工具）
v0.4.0	2026-05-01	版本检测 + validate_scripts + search_and_replace + 截图稳定性
v0.3.0	—	edit_script + batch_add_nodes + validate_project + import_resources
v0.2.0	—	read_scene + read/write_script + query_scene_tree + MCP Resources
v0.1.0	—	项目管理 + 场景操作 + 执行控制 + 截图 + execute_gdscript

Footnotes

1. https://github.com/youichi-uda/godot-mcp-pro README(含其自带竞品对比表),抓取 2026-06-27 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

2. GDAI MCP,数据转引自 godot-mcp-pro 对比表,2026-06-27 ↩ ↩²

3. https://github.com/Coding-Solo/godot-mcp,抓取 2026-06-27 ↩ ↩²