godot-mcp-enhanced

Screenshot capture and image analysis handoff. capture: capture a Godot scene screenshot in headless mode (experimental). analyze: return the image as MCP image content (base64) for the client vision capability to examine — returns image data, NOT a text description.

启动编辑器、运行/停止项目、获取调试输出、运行测试、获取 Godot 版本。

搜索 Godot 项目、获取项目信息、列出文件、读取配置、创建项目、设置项目规则。

场景操作。读取/创建: read_scene, create_scene, quick_scene。节点: add_node, batch_add_nodes, edit_node, remove_node。保存/资源: save_scene, load_sprite。查询: query_scene_tree, inspect_node。实例: instance_scene, set_instance_property, detach_instance。

脚本操作。读写: read_script, write_script。编辑: edit_script（行号/search_and_replace）。执行: execute_gdscript（⚠️ 沙箱仅防误操作，不可用于不可信输入。高安全场景请用 ALLOW_EXECUTE_GDSCRIPT=false 或容器隔离）。⚠️ write_script/edit_script 写入 .gd 前也走沙箱扫描（防 @tool 脚本加载即执行等已知危险 API 模式（清单不列举，防沙箱边界被侦察）;与 execute_gdscript 同威胁面）。测试: generate_test, create_test_scene。批量替换: project_replace。💡 execute_gdscript 最佳实践:分步执行、每步验证（把复杂逻辑拆成小块逐一跑,每步用 read_script/edit_script 迭代,避免一次性大脚本出错难定位）。

运行验证、分析错误、验证项目/脚本、导入资源。一键 headless 运行 + 错误分析，或按需单项检查。

Query Godot class documentation: get_class_info, search_classes, find_method, get_inheritance.

音频操作。play: 播放（支持 AudioStreamPlayer/2D/3D）。stop: 停止。set_param: 设置参数（volume_db/pitch_scale/bus）。query: 查询播放状态。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

查询、控制和编辑动画。查询: list_players, get_info, get_details, get_keyframes。播放: play, stop, seek, blend。编辑: create, delete, update_props, add_track, remove_track, add_keyframe, remove_keyframe, update_keyframe。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

Material and shader operations. Read: read. Write: set_params, create, save, load. Shader: shader_read, shader_write, shader_load_file, shader_save_file, shader_list_templates, shader_apply_template. 运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

游戏桥接操作。安装/卸载: game_bridge_install, game_bridge_uninstall。P2-1 overrides 注入: install_override/uninstall_override (启动游戏前注入任意调试脚本到项目 autoload,如日志钩子/状态快照)。查询: game_query (ping, get_tree, find_nodes, get_node_properties, get_performance, get_viewport_info, take_screenshot)。写入: game_write (set_node_property, call_method)。输入: game_input (send_key, send_mouse_click, send_mouse_move, send_text, send_touch, send_drag, send_input_sequence 帧定时输入时间线)。等待: game_wait (wait_for_node, wait_for_property)。P2-4 确定性 playtest: game_playtest (playtest.seed 锁随机, playtest.fixed_delta 锁步长, playtest.step 单步推进, playtest.snapshot/restore 状态快照)。G1 control 层: playtest.freeze (冻结游戏循环,bridge 仍响应), playtest.unfreeze (解冻), playtest.step_until (条件满足/帧尽/wall 超时即停,结构化条件 {path,property,op,value}[] AND)。监控: monitor_start/stop/poll (属性时间线采样)。信号: watch_start/stop/poll (信号事件记录)。UI: find_ui_elements/click_button (UI元素发现+按钮点击)。

Development workflow tools. dev_loop: execute GDScript with optional validation, bridge queries, and state saving. scene_snapshot: capture structured scene tree snapshot. batch_validate: validate multiple GDScript files at once.

性能分析工具。snapshot: 快照（FPS/内存/绘制调用/物理统计）。start/stop: 开始/停止分析会话。get_data: 收集帧级数据，含多维度采样、p99百分位、趋势退化检测、内存趋势、渲染统计。get_active_processes: 遍历场景树查找有 _process/_physics_process 的节点。get_signal_connections: 列出子树所有信号连接。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

查询、控制和编辑 AnimationTree。支持创建节点、添加状态、添加转换、设置混合参数、播放状态、编辑状态属性。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

创建 GPUParticles2D/3D 节点、设置发射/处理参数、加载预设效果、设置粒子材质。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

信号操作。connect/disconnect: 连接/断开信号。emit: 发射信号（参数仅基本类型）。list: 列出节点可用信号。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

一次返回会话全景（模式/项目/连接/场景快照/最近调用统计/工具组/推荐 workflow/规则/性能），减少反复探路。headless 模式 scene=null。

动画轨道与关键帧操作。轨道: add_track, remove_track。关键帧: add_keyframe, remove_keyframe, update_keyframe。曲线: set_curve。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

从本地知识库(GodotPrompter/gd-agentic 等)按关键词检索 SKILL.md。两级检索:name/description 高精度→全文 fallback。返回带来源标注(source/path)和相关性 score 的匹配。缺失库进 missing_libraries 不报错。

GDExtension (C++) 脚手架生成。scaffold_gdextension: 在 project_path 下生成完整可编译的 godot-cpp GDExtension 工程骨架（src/类.cpp/.h + register_types + SConstruct + .gdextension + .gitignore + README），不联网/不编译，对齐 godot-cpp 官方 example。

运行时断言：在运行中的游戏上验证节点状态/场景结构/屏幕文本/性能/截图对比。agent 可任意时刻调用，不必走 workflow.dev_loop。全部依赖 game-bridge（需先 game_bridge_install + 游戏运行中）。

QA 测试套件编排：结构化测试规范 → 自动安装 bridge → 运行游戏 → 逐步执行 → 聚合报告 + 回归 diff。步骤类型：input/wait/wait_frames/freeze/unfreeze/step_until/snapshot/restore/set/call/watch_start|stop/monitor_start|stop/assert/screenshot/sleep；断言 8 种与各字段语义见 schema 字段 description。run 支持 mode:async 后台执行(qa status/cancel 管理)。报告落 ~/.godot-mcp/qa-reports/<run_id>.{json,md}。

Execute a previously blocked tool using a confirmation token. Use this when a tool returns a confirmation_token.

理解层静态分析（零 Godot 依赖）。action=signal_map 列全项目信号连接（.tscn [connection] 声明 + .gd 代码 connect/emit 引用，两来源分开标注）；action=impact_check 改动前影响面评估——改信号列出全部连接方/发射方/监听方，改脚本列出引用它的场景与节点，改场景列出其连接/脚本/被实例化处。盲区诚实标注：运行时动态信号名/autoload 间连接不可见。

获取任意工具的完整文档。可用工具名：analysis, android, animation, animation_track, animtree, asset, audio, audit, blender, confirm_and_execute, cpp, csv_to_resources, debug, docs, editor, engine, game, godot_advanced_tool, godot_get_context, godot_list_dynamic_routes, godot_list_instances, godot_select_instance, help, load_skill, manage_tools, material, nav, particles, physics, profiler, project, qa, runtime, runtime_assert, scene, screenshot, script, self_update, signal, testing, tilemap, translation, ui, uid, validation, workflow。传 tool_name 获取该工具的详细用法、参数、action 列表。拼写纠错自动提示最接近的工具名。

操作审计日志查询(G3)。action=get_log 读 {project}/.godot/mcp_audit.jsonl 统计回放(操作计数/风险高亮/最近条目/时间范围);action=suggest_rollback 对指定条目给诚实回滚建议(create 类可删/project.godot before_values/其余靠 Git)。write/destructive 操作经 audit after middleware 自动落盘(changed_files 为项目相对路径,PII 护栏)。