godot-mcp: Instructions file for Claude Code

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

架构概览

这是一个 Godot 引擎 + Claude AI 集成项目，使用模型上下文协议 (MCP)。项目采用 客户端-服务器架构：

• Godot 插件 (客户端): 位于 addons/godot_mcp/ - 作为 EditorPlugin 在 Godot 中运行
• MCP 服务器 (后端): 位于 server/ - 使用 FastMCP 的 Node.js/TypeScript 服务器

通信流程

Claude ↔ MCP 服务器 (FastMCP) ↔ WebSocket ↔ Godot 插件

Godot 插件创建 WebSocket 服务器（默认端口 9080），接受来自 MCP 服务器的连接。所有命令都通过此 WebSocket 连接使用 JSON 消息格式传输。

构建和运行命令

MCP 服务器开发

• 安装依赖: cd server && npm install
• 服务器构建: cd server && npm run build (将 TypeScript 编译到 dist/)
• 启动服务器: cd server && npm run start
• 开发模式: cd server && npm run dev (使用 nodemon 自动重建)
• 类型检查: cd server && npx tsc --noEmit (仅类型检查，不输出文件)

Godot 项目

• 打开项目: 在 Godot Editor 中打开 project.godot
• 插件位置: addons/godot_mcp/
• 启用插件: 项目设置 → 插件 → 启用 "Godot MCP"

测试连接

1. 启动 MCP 服务器: cd server && npm run dev
2. 在 Godot Editor 中打开项目（插件自动启动）
3. 检查 MCP 服务器日志，确认 WebSocket 连接到 ws://localhost:9080

核心组件

Godot 插件端 (addons/godot_mcp/)

• mcp_server.gd: 主 EditorPlugin，创建 WebSocket 服务器
• command_handler.gd: 将 JSON 命令路由到相应的处理器
• commands/: 命令处理器（node_commands.gd, script_commands.gd, scene_commands.gd 等）
• ui/mcp_panel.gd: 编辑器 UI 面板，显示连接状态和日志

MCP 服务器端 (server/src/)

• index.ts: FastMCP 服务器入口点，注册所有工具/资源
• utils/godot_connection.ts: WebSocket 连接管理，支持自动重连
• tools/: MCP 工具定义（node_tools.ts, script_tools.ts 等）
• resources/: MCP 资源提供器（scene_resources.ts, script_resources.ts 等）

开发模式

添加新命令

1. Godot 端: 在 addons/godot_mcp/commands/ 中创建新命令类

   • 继承基础命令模式
   • 在 command_handler.gd 中注册
   • 遵循 snake_case 命名规范

2. MCP 服务器端: 在 server/src/tools/ 中创建工具

   • 使用 FastMCP 工具构建器模式
   • 在 server/src/index.ts 中注册
   • 使用 Zod 进行参数验证

消息协议

命令格式 (MCP → Godot):

{
  "type": "command_name",
  "params": { /* 命令参数 */ },
  "commandId": "unique_id"
}

响应格式 (Godot → MCP):

{
  "status": "success|error",
  "result": { /* 响应数据 */ },
  "commandId": "matching_id"
}