Godot-MCP-Native: Instructions file for Codex

AGENTS.md — Godot MCP 项目指南

项目简介

一个 Godot 4.6 EditorPlugin（位于 addons/godot_mcp/），在 Godot 内部原生实现了 MCP（Model Context Protocol）服务器，无需 Node.js 依赖。提供 154 个工具（30 核心 + 124 补充），分为 6 大类，供 AI 助手读取和修改项目。

• 插件入口：addons/godot_mcp/mcp_server_native.gd（继承 EditorPlugin）
• 作者：yurineko73 | 版本：1.0.7
• 许可证：MIT
• 渲染器：GL Compatibility

gdmcp CLI Skill

When using the shell-oriented gdmcp companion for Godot editor operations, read skills/gdmcp/SKILL.md first. Use the high-level bounded commands before progressive discovery with tools search, tools schema, and tool-call.

PowerShell 7.x 路径

系统 PowerShell 版本可能变化，每次会话请验证确切的版本号：

& "C:\Program Files\WindowsApps\Microsoft.PowerShell_*_x64__8wekyb3d8bbwe\pwsh.exe"

用 (Get-Command pwsh).Source 解析路径。如果 WindowsApps 路径不可用，回退到系统默认 PowerShell。

代码语言政策

• 任何代码文件中不得出现中文字符 — 注释、字符串、标识符全部使用英文。
• 中文仅允许出现在：AGENTS.md、README.zh.md 和 docs/（翻译/计划文档）。

命令

运行 Godot 项目

在 Godot 编辑器（4.6.x，GL Compatibility 渲染器）中打开 project.godot。

GUT 单元测试

& "F:\Godot\Godot_v4.6.1-stable_win64.exe" --headless --path "." -s addons/gut/gut_cmdln.gd -gdir=res://test/unit/ -ginclude_subdirs -gexit

配置：.gutconfig.json — dirs: res://test/unit/, log_level: 2, should_exit_on_finish: false。

集成测试（Python）

cd test/integration
python test_runtime_probe_flow.py

Python 测试会启动 Godot 4.6.2（C:\SourceCode\Godot_v4.6.2-stable_mono_win64\...），通过 HTTP MCP（端口 9080）进行通信。

架构

addons/godot_mcp/
├── mcp_server_native.gd       # EditorPlugin 入口 — 注册插件、管理生命周期
├── native_mcp/                 # 核心服务器引擎
│   ├── mcp_server_core.gd      # 中枢：工具注册、JSON-RPC 分发、信号总线
│   ├── mcp_transport_base.gd   # 传输层抽象基类
│   ├── mcp_http_server.gd      # HTTP/SSE 传输（默认端口 9080）
│   ├── mcp_stdio_server.gd     # stdio 传输（供 Claude Desktop 等使用）
│   ├── mcp_types.gd            # JSON-RPC 和 MCP 协议常量、MCPTool 数据类
│   ├── mcp_tool_classifier.gd  # 工具分类映射：{core/supplementary, group}（CORE_MAX_COUNT=30）
│   ├── mcp_resource_manager.gd # 资源读取/列表/订阅
│   ├── mcp_debugger_bridge.gd  # Godot 调试器 ↔ MCP 桥梁（断点、栈帧、变量）
│   ├── mcp_auth_manager.gd     # HTTP Bearer Token 认证
│   ├── config_manager.gd       # 插件配置读写
│   ├── settings_manager.gd     # 编辑器设置持久化
│   ├── tool_state_manager.gd   # 每个工具的状态管理
│   └── translation_manager.gd  # 国际化支持
├── runtime/
│   └── mcp_runtime_probe.gd    # Autoload 单例，用于运行时检查（动画、音频、着色器、瓦片地图、输入）
├── tools/                      # 工具实现（每个分类一个文件）
│   ├── node_tools_native.gd    # 20 个工具 — 创建/删除/更新/复制/移动/重命名节点、信号、分组、锚点预设、批量操作、场景审计
│   ├── script_tools_native.gd  # 14 个工具 — 读取/写入/创建/附加/分析/验证/执行脚本、符号索引、搜索
│   ├── scene_tools_native.gd   # 8 个工具 — 创建/保存/打开/关闭场景、结构查看、列表
│   ├── editor_tools_native.gd  # 16 个工具 — 运行/停止、状态、截图、信号、导出、选择、查看器
│   ├── debug_tools_native.gd   # 70 个工具 — 日志、断点、栈帧/变量、性能分析器、运行时探针、动画/音频/着色器/瓦片地图运行时控制
│   └── project_tools_native.gd # 26 个工具 — 项目信息/设置、资源、输入映射、自动加载、全局类、测试运行器、诊断
├── ui/
│   ├── mcp_panel_native.gd     # 主停靠面板（VBoxContainer）— 启动/停止、传输配置、日志查看、工具管理
│   ├── mcp_tool_item.gd        # 单个工具开关 UI
│   └── mcp_tool_group_item.gd  # 工具组折叠/展开 UI
└── utils/
    ├── node_utils.gd           # 节点查找辅助函数
    ├── path_validator.gd       # 路径验证
    ├── resource_utils.gd       # 资源 I/O 工具
    ├── script_utils.gd         # 脚本工具
    └── vibe_coding_policy.gd   # Vibe Coding 模式守卫（allow_ui_focus / allow_window）