Godot MCP Native 项目全面解读

一、项目概述

项目名称：Godot MCP Native (Model Context Protocol)

核心定位：一个 Godot Engine 编辑器插件，通过 Model Context Protocol (MCP) 将 AI 助手（如 Claude、Cursor 等）与 Godot 编辑器深度集成，让 AI 能够直接理解和操作 Godot 项目。

核心特点：

• 🦀 完全原生实现：纯 GDScript 编写，无需 Node.js 等外部依赖
• 🔧 154 个 MCP 工具：30 个核心工具 + 124 个补充工具
• 🌐 双传输模式：支持 HTTP（SSE）和 Stdio（开发中）
• 🔇 Vibe Coding 模式：免打扰模式，避免 AI 操作干扰用户工作流
• 🌍 国际化支持：完整的英文/中文双语支持

二、项目结构

c:\GitHub\Godot-MCP-Native\
├── addons\godot_mcp\           # 插件主目录
│   ├── mcp_server_native.gd    # 插件入口 (EditorPlugin)
│   ├── native_mcp\            # 核心 MCP 实现
│   ├── tools\                 # 154 个工具实现
│   ├── runtime\               # 运行时探针
│   ├── ui\                    # 编辑器 UI 面板
│   └── utils\                 # 工具类
├── docs\                      # 完整文档体系
├── test\                      # 测试体系（单元 + 集成）
├── project.godot              # Godot 项目配置
└── README.md / AGENTS.md      # 项目文档

三、架构设计

3.1 三层架构

┌─────────────────────────────────┐
│     AI Client (Claude, etc.)   │  ← JSON-RPC 2.0 请求
└──────────────┬──────────────────┘
               │ HTTP / Stdio
┌──────────────▼──────────────────┐
│      Godot Native MCP Server    │  ← 工具注册、请求路由、认证
└──────────────┬──────────────────┘
               │ Godot Editor API
┌──────────────▼──────────────────┐
│         Godot Editor            │  ← 场景、脚本、节点操作
└─────────────────────────────────┘

3.2 核心模块

四、MCP 工具体系（154 个）

4.1 工具分类

4.2 工具注册方式

每个工具通过 8 个参数注册：

server_core.register_tool(
    "tool_name",                    # 1. 工具名称
    "Description...",               # 2. 描述
    input_schema,                   # 3. 输入 JSON Schema
    Callable(self, "_tool_..."),   # 4. 回调函数
    output_schema,                 # 5. 输出 JSON Schema
    annotations_dict,              # 6. 注解（readOnlyHint 等）
    "core",                        # 7. 类别
    "Group-Name"                   # 8. 分组
)

4.3 工具执行流程

AI 请求 → 传输层接收 → 参数验证(JSON Schema) 
  → 权限检查 → 调用工具实现 → 执行 Godot API 
  → 返回结果 → 发送给 AI

五、运行时探针（Runtime Probe）

这是项目的特色功能，允许 AI 在游戏运行时获取和操控游戏状态。

架构

MCP Server ←→ EngineDebugger ←→ MCPRuntimeProbe (注入到游戏场景)

实现机制

通过 EngineDebugger.register_message_capture() 注册消息捕获，实现编辑器与运行时的通信：

func _ready() -> void:
    EngineDebugger.register_message_capture(CAPTURE_PREFIX, 
        Callable(self, "_capture_mcp_message"))

func _capture_mcp_message(message: String, data: Array) -> bool:
    match message:
        "get_runtime_info":
            EngineDebugger.send_message("mcp:runtime_info", [_get_runtime_info()])
        "get_scene_tree":
            EngineDebugger.send_message("mcp:scene_tree", [...])
        # ...更多消息处理

支持的运行时操作

• 获取运行时场景树
• 检查节点属性和方法
• 调用节点方法
• 计算表达式
• 模拟输入事件
• 控制动画播放
• 获取性能快照

六、测试体系

6.1 测试结构

test\
├── unit\                 # 单元测试 (GUT 框架)
│   ├── test_mcp_*.gd    # 核心模块测试
│   └── tools\           # 工具测试
└── integration\         # 集成测试 (Python)
    └── test_*_flow.py   # 端到端流程测试

6.2 测试规模

• 单元测试：19 个测试脚本，295 个测试用例，521 个断言
• 测试框架：GUT (Godot Unit Test) 9.6.0
• 运行命令：

  & "Godot.exe" --headless --path "..." -s addons/gut/gut_cmdln.gd `
    -gdir=res://test/unit/ -ginclude_subdirs -gexit
  

6.3 测试规范（强制）

• 每次修改代码必须更新对应测试用例
• 必须覆盖：正常路径 + 边界条件 + 错误处理
• 禁止提交无测试更新的 commit

七、安全设计

认证机制

• Token-based 认证（仅 HTTP 模式）
• 时序安全比较防止时序攻击
• Token 长度要求 ≥ 16 字符

速率限制

• 每 IP 每 60 秒最多 100 个请求

路径遍历保护

func is_path_safe(path: String) -> bool:
    if not path.begins_with("res://") and not path.begins_with("user://"):
        return false
    if path.contains(".."):
        return false
    return true

八、文档体系

核心文档：

• tools-reference.md（127 KB）— 最详细的工具参考手册
• architecture.md（17.6 KB）— 架构设计文档
• testing-guide.md（16.4 KB）— 测试指南

九、技术亮点

1. 完全原生实现 — 不依赖 Node.js，纯 GDScript
2. 线程安全 — 使用 call_deferred() 和 Mutex
3. 调试器深度集成 — 通过 EngineDebugger API
4. 运行时探针 — 独特的游戏运行时 AI 交互能力
5. 完善的 i18n — 英文/中文完整支持
6. 全面的测试覆盖 — 单元 + 集成测试

十、配置项

总结

Godot MCP Native 是一个架构清晰、模块化、可扩展性强的 Godot 插件。它通过 MCP 协议将 AI 助手深度集成到游戏开发工作流，154 个工具覆盖了从场景编辑、脚本管理到调试和项目配置的各个方面。特别是运行时探针的设计，为 AI 辅助游戏开发提供了独特的能力，是该项目最大的技术亮点。