企业官网建设流程全解析

Godot-MCP 开发者指南：如何为自己的项目扩展自定义 MCP 命令

【免费下载链接】Godot-MCPAn MCP for Godot that lets you create and edit games in the Godot game engine with tools like Claude项目地址: https://gitcode.com/gh_mirrors/god/Godot-MCP

Godot-MCP 是一个让 AI 助手（如 Claude）直接操控 Godot 引擎的 MCP（Model Context Protocol）集成方案。本文面向希望扩展Godot MCP 命令的开发者，手把手教你为 Godot-MCP 添加自定义命令，让你的 AI 助手获得全新能力。

为什么需要扩展自定义 MCP 命令？

Godot-MCP 内置了五大类命令：节点、脚本、场景、项目和编辑器操作（详见 docs/command-reference.md）。但每个游戏项目都有自己的特殊需求——比如"切换昼夜循环"、"重新生成关卡"、"导出指定资源"。

通过扩展自定义 MCP 命令，你只需对 AI 说一句话，就能触发这些项目专属操作。💡

理解 Godot-MCP 的双端架构

在动手之前，先搞清楚命令的完整链路（完整设计见 docs/architecture.md）：

1. Claude（AI 端）：通过 MCP 协议发起工具调用
2. MCP Server（Node.js 端）：位于 server/，用 FastMCP 定义工具，通过 WebSocket 转发命令
3. Godot Addon（引擎端）：位于 addons/godot_mcp/，WebSocket 服务器接收命令并执行引擎 API

也就是说，添加一条自定义命令需要改两个地方：

第一步：在 Godot Addon 端实现命令处理

1. 创建命令处理器

所有命令处理器都继承自 MCPBaseCommandProcessor，它提供了：

• _send_success()/_send_error()：统一的成功/错误响应格式
• _get_editor_node()：按路径查找场景节点
• _mark_scene_modified()：修改场景后标记为已更改
• _parse_property_value()：把字符串解析为 Godot 类型（如Vector2、Color）

你可以参考现有的 node_commands.gd：在process_command中用match匹配命令类型，命中则执行逻辑并返回true，不处理则返回false。

2. 注册到你的项目

打开 command_handler.gd，在_initialize_command_processors()中做三件事（以现有的MCPNodeCommands为模板）：

var my_commands = MCPMyCommands.new() my_commands._websocket_server = _websocket_server _command_processors.append(my_commands) add_child(my_commands)

MCPCommandHandler会依次遍历所有处理器，直到某个处理器认领命令为止，所以你的新处理器不会与内置命令冲突。

第二步：在 MCP Server 端注册工具

AI 只能"看到"MCP Server 注册的工具。以 node_tools.ts 为例，每个工具包含四部分：

export const myTools: MCPTool[] = [ { name: 'my_command', description: '用自然语言描述这个命令做什么', parameters: z.object({ /* zod 参数校验 */ }), execute: async (args) => { const godot = getGodotConnection(); const result = await godot.sendCommand('my_command', args); return `操作完成：${JSON.stringify(result)}`; }, }, ];

注意sendCommand的第一个参数必须与 Addon 端match的命令类型完全一致。

然后回到 server/src/index.ts，把新工具数组加入注册列表：

[...nodeTools, ...scriptTools, ...sceneTools, ...editorTools, ...myTools].forEach(tool => { server.addTool(tool); });

工具类型定义见 utils/types.ts 中的MCPTool接口。

遵循消息协议：让命令可靠可追溯

Godot 端与 Server 端通过 JSON 消息通信（格式见 docs/architecture.md）：

• 请求：{ "type": "命令名", "params": {...}, "commandId": "cmd_123" }
• 成功响应：{ "status": "success", "result": {...}, "commandId": "cmd_123" }
• 错误响应：{ "status": "error", "message": "错误详情", "commandId": "cmd_123" }

编写自定义命令时的最佳实践：

• ✅ 执行前先校验参数（例如节点类型是否存在），无效时尽早返回错误
• ✅ 错误信息要带上上下文（如"Parent node not found: /root/Main"），方便 AI 自我修正
• ✅ 修改场景后调用_mark_scene_modified()，让编辑器正确标记未保存状态
• ❌ 不要让异常直接崩溃编辑器，所有错误都应走_send_error返回

第三步：重建 Server 并测试

修改 Server 端后需要重新构建（构建产物位于server/dist/）：

cd server npm install npm run build

然后重启 Claude Desktop，在 Godot 中打开你的项目（确保 project.godot 已启用插件），对 AI 说：

"帮我执行 my_command，参数是 xxx"

观察 Godot 控制台输出的Processing command: my_command，确认命令成功流转。若提示Unknown command，说明 Addon 端注册有误；若 AI 不识别工具，则是 Server 端未注册或未重启。

扩展思路清单 🚀

掌握这套流程后，你可以为自己的项目添加：

• 项目专属操作：一键切换昼夜循环、重置玩家存档
• 调试辅助：批量导出场景截图、打印关键节点状态
• 资源工作流：批量重命名纹理、检查未使用资源
• 关卡工具：程序化生成地形、校验碰撞层配置

完整的命令参考文档见 docs/command-reference.md，快速上手指南见 docs/getting-started.md。

小结

扩展 Godot-MCP 自定义命令的核心就三步：Addon 端继承MCPBaseCommandProcessor实现执行逻辑 → 在command_handler.gd注册 → Server 端用 zod 定义工具并注册到index.ts。遵循统一的消息协议、做好参数校验，你的 AI 助手就能丝滑地驱动 Godot 项目中的任何自定义能力。🎮

【免费下载链接】Godot-MCPAn MCP for Godot that lets you create and edit games in the Godot game engine with tools like Claude项目地址: https://gitcode.com/gh_mirrors/god/Godot-MCP