Godot MCP Integration

### 核心能力
- **场景管理** - 创建、打开、保存场景
- **节点操作** - 添加、删除、移动、修改节点
- **脚本编辑** - 创建和修改 GDScript 脚本
- **资源管理** - 加载和创建游戏资源
- **文件系统** - 浏览项目、读写文件
- **编辑器控制** - 选中对象、撤销重做
- **调试工具** - 查看日志、运行时信息

---

## 安装配置

### 1. 安装插件

```bash
# 克隆仓库
git clone https://github.com/DaxianLee/godot-mcp.git

# 复制到项目
cp -r godot-mcp/addons/godot_mcp /path/to/your/project/addons/
```

### 2. 启用插件

在 Godot 编辑器中：
1. `项目 -> 项目设置 -> 插件`
2. 找到 **Godot MCP Server**
3. 点击启用

### 3. 配置 MCP 服务器

默认配置：
- **端口**: 3000
- **地址**: `http://127.0.0.1:3000/mcp`
- **自动启动**: 开启

在 GodotMCP 面板中可以：
- 查看服务器状态
- 管理可用工具
- 配置 AI 客户端

---

## AI 客户端配置

### IDE 编辑器（一键配置）

#### Trae CN
```bash
# 配置文件位置
# macOS: ~/Library/Application Support/Trae CN/User/mcp.json
# Windows: %APPDATA%\Trae CN\User\mcp.json
# Linux: ~/.config/Trae CN/User/mcp.json

# 在 GodotMCP 面板中点击「一键配置」即可
```

#### Cursor
```bash
# 配置文件位置
~/.cursor/mcp.json

# 在 GodotMCP 面板中点击「一键配置」即可
```

#### Windsurf
```bash
# 配置文件位置
~/.codeium/windsurf/mcp_config.json

# 在 GodotMCP 面板中点击「一键配置」即可
```

### CLI 工具（命令配置）

#### Claude CLI (Claude Code)
```bash
# 用户级配置（全局）
claude mcp add --scope user --transport http godot-mcp http://127.0.0.1:3000/mcp

# 项目级配置（当前项目）
claude mcp add --scope project --transport http godot-mcp http://127.0.0.1:3000/mcp
```

#### Codex CLI
```bash
# 用户级
codex mcp add --scope user --transport http godot-mcp http://127.0.0.1:3000/mcp

# 项目级
codex mcp add --scope project --transport http godot-mcp http://127.0.0.1:3000/mcp
```

#### Gemini CLI
```bash
# 用户级
gemini mcp add --scope user --transport http godot-mcp http://127.0.0.1:3000/mcp

# 项目级
gemini mcp add --scope project --transport http godot-mcp http://127.0.0.1:3000/mcp
```

---

## 工具分类

### 核心工具

#### 场景工具 (Scene)
```
scene_create        - 创建新场景
scene_open          - 打开指定场景
scene_save          - 保存当前场景
scene_get_tree      - 获取场景树结构
scene_get_current   - 获取当前场景信息
```

**使用示例**：
```
用户: 创建一个新场景，命名为 "Level1"
AI: [调用 scene_create {"name": "Level1"}]
    已创建场景 Level1

用户: 添加一个 Sprite2D 节点
AI: [调用 node_add {"type": "Sprite2D", "name": "Player"}]
    已添加 Sprite2D 节点到场景
```

#### 节点工具 (Node)
```
node_add            - 添加新节点
node_delete         - 删除节点
node_get            - 获取节点信息
node_set_property   - 设置节点属性
node_get_property   - 获取节点属性
node_move           - 移动节点位置
node_rename         - 重命名节点
node_duplicate      - 复制节点
node_find           - 查找节点
```

**使用示例**：
```
用户: 将 Player 节点的位置设置为 (100, 200)
AI: [调用 node_set_property {
       "node": "Player",
       "property": "position",
       "value": {"x": 100, "y": 200}
     }]
    已设置 Player 位置为 (100, 200)
```

#### 脚本工具 (Script)
```
script_create       - 创建新脚本
script_read         - 读取脚本内容
script_write        - 写入脚本内容
script_attach       - 附加脚本到节点
```

**使用示例**：
```
用户: 为 Player 节点创建一个脚本
AI: [调用 script_create {
       "name": "player.gd",
       "template": "CharacterBody2D"
     }]
    [调用 script_attach {
       "node": "Player",
       "script": "res://scripts/player.gd"
     }]
    已创建并附加脚本
```

#### 资源工具 (Resource)
```
resource_load       - 加载资源
resource_create     - 创建资源
resource_save       - 保存资源
```

#### 文件系统工具 (Filesystem)
```
filesystem_list     - 列出目录内容
filesystem_read     - 读取文件
filesystem_write    - 写入文件
filesystem_delete   - 删除文件
```

#### 项目工具 (Project)
```
project_get_info        - 获取项目信息
project_get_settings    - 获取项目设置
```

#### 编辑器工具 (Editor)
```
editor_get_selection    - 获取当前选中
editor_select_node      - 选中指定节点
editor_undo_redo        - 撤销/重做操作
```

#### 调试工具 (Debug)
```
debug_get_logs      - 获取调试日志
```

### 视觉工具

#### 材质工具 (Material)
```
material            - 创建和配置材质
```

**使用示例**：
```
用户: 创建一个发光材质
AI: [调用 material {
       "type": "StandardMaterial3D",
       "emission": {"enabled": true, "color": "#00FF00"}
     }]
    已创建发光材质
```

#### 着色器工具 (Shader)
```
shader              - 着色器参数管理
```

#### 灯光工具 (Lighting)
```
lighting            - 场景灯光配置
```

#### 粒子工具 (Particle)
```
particle            - 粒子效果创建
```

### 2D 工具

#### 瓦片地图工具 (TileMap)
```
tilemap             - TileMap 编辑
```

**使用示例**：
```
用户: 创建一个 TileMap 并设置瓷砖
AI: [调用 node_add {"type": "TileMap", "name": "Ground"}]
    [调用 tilemap {
       "action": "set_cell",
       "coords": [(0, 0), (1, 0), (2, 0)],
       "tile_id": 1
     }]
    已创建 TileMap 并铺设瓷砖
```

#### 几何体工具 (Geometry)
```
geometry            - 2D 几何图形
```

### 游戏玩法工具

#### 物理工具 (Physics)
```
physics             - 物理体和碰撞配置
```

**使用示例**：
```
用户: 为 Player 添加碰撞形状
AI: [调用 node_add {
       "type": "CollisionShape2D",
       "parent": "Player"
     }]
    [调用 physics {
       "node": "Player/CollisionShape2D",
       "shape": "CapsuleShape2D",
       "radius": 10,
       "height": 20
     }]
    已添加碰撞形状
```

#### 导航工具 (Navigation)
```
navigation          - 导航网格和寻路
```

#### 音频工具 (Audio)
```
audio               - 音频播放和配置
```

### 实用工具

#### UI 工具
```
ui                  - 用户界面组件
```

#### 信号工具 (Signal)
```
signal              - 信号连接管理
```

#### 分组工具 (Group)
```
group               - 节点分组管理
```

---

## 工作流程示例

### 示例 1: 创建完整场景

```
用户: 创建一个包含玩家、敌人和地形的场景

AI 执行步骤:
1. [scene_create {"name": "GameScene"}]
2. [node_add {"type": "Node2D", "name": "Entities"}]
3. [node_add {"type": "CharacterBody2D", "name": "Player", "parent": "Entities"}]
4. [node_add {"type": "Sprite2D", "name": "Sprite", "parent": "Player"}]
5. [script_create {"name": "player.gd"}]
6. [script_attach {"node": "Player", "script": "res://player.gd"}]
7. [node_add {"type": "CharacterBody2D", "name": "Enemy", "parent": "Entities"}]
8. [node_add {"type": "TileMap", "name": "Ground"}]
9. [scene_save]

完成！已创建包含玩家、敌人和地形的场景。
```

### 示例 2: 配置玩家物理

```
用户: 为玩家添加物理和碰撞检测

AI 执行步骤:
1. [node_add {"type": "CollisionShape2D", "parent": "Player"}]
2. [physics {
     "node": "Player/CollisionShape2D",
     "shape": "CapsuleShape2D",
     "radius": 10,
     "height": 30
   }]
3. [script_write {
     "path": "res://player.gd",
     "content": "extends CharacterBody2D\n\nconst SPEED = 300.0\nconst JUMP_VELOCITY = -400.0\n\nvar gravity = ProjectSettings.get_setting(\"physics/2d/default_gravity\")\n\nfunc _physics_process(delta):\n    # Add the gravity.\n    if not is_on_floor():\n        velocity.y += gravity * delta\n    \n    # Handle Jump.\n    if Input.is_action_just_pressed(\"ui_accept\") and is_on_floor():\n        velocity.y = JUMP_VELOCITY\n    \n    # Get the input direction and handle the movement/deceleration.\n    var direction = Input.get_axis(\"ui_left\", \"ui_right\")\n    if direction:\n        velocity.x = direction * SPEED\n    else:\n        velocity.x = move_toward(velocity.x, 0, SPEED)\n    \n    move_and_slide()"
   }]

完成！已为玩家配置物理系统。
```

### 示例 3: 批量创建敌人

```
用户: 在场景中放置 5 个敌人

AI 执行步骤:
1. [scene_open {"path": "res://scenes/game.tscn"}]
2. [node_add {"type": "Node2D", "name": "Enemies"}]
3. [node_duplicate {"node": "Enemy", "count": 4}]
4. [node_set_property {"node": "Enemy2", "property": "position", "value": {"x": 200, "y": 0}}]
5. [node_set_property {"node": "Enemy3", "property": "position", "value": {"x": 400, "y": 0}}]
6. [node_set_property {"node": "Enemy4", "property": "position", "value": {"x": 600, "y": 0}}]
7. [node_set_property {"node": "Enemy5", "property": "position", "value": {"x": 800, "y": 0}}]
8. [scene_save]

完成！已创建 5 个敌人并放置在场景中。
```

---

## 高级用法

### 1. 自动化测试

```bash
# 创建测试场景
用户: 创建一个测试场景，包含多个物理对象

AI: [创建场景和物理对象]
    [配置物理参数]
    [添加调试可视化]
    测试场景已就绪
```

### 2. 资源批处理

```bash
# 批量处理资源
用户: 将所有纹理的 filter 模式改为 Nearest

AI: [filesystem_list {"path": "res://textures"}]
    [循环每个纹理]
    [resource_load]
    [修改 filter_mode]
    [resource_save]
    已更新所有纹理设置
```

### 3. 代码生成

```bash
# 生成游戏代码
用户: 为所有敌人节点生成 AI 脚本

AI: [node_find {"pattern": "Enemy*"}]
    [为每个敌人创建脚本]
    [根据类型生成 AI 逻辑]
    [附加脚本]
    已生成所有 AI 脚本
```

---

## 故障排除

### 服务器无法启动
```
检查:
1. 端口 3000 是否被占用
2. 防火墙是否阻止
3. Godot 版本是否兼容

解决:
- 更改端口号
- 关闭防火墙或添加例外
- 升级到 Godot 4.x
```

### AI 客户端无法连接
```
检查:
1. MCP 服务器是否运行（绿色状态）
2. 配置文件中的端口号是否正确
3. AI 客户端是否重启

解决:
- 重启 MCP 服务器
- 检查配置文件
- 重启 AI 客户端
```

### 工具调用失败
```
检查:
1. 节点路径是否正确
2. 属性名是否正确
3. 参数类型是否匹配

解决:
- 使用 scene_get_tree 查看场景结构
- 使用 node_get 查看可用属性
- 检查文档中的参数格式
```

---

## 最佳实践

### 1. 场景组织
```
推荐结构:
Scene
├── Entities
│   ├── Player
│   └── Enemies
├── Environment
│   ├── TileMaps
│   └── Props
└── UI
    └── HUD
```

### 2. 命名规范
```
- 节点名: PascalCase (Player, Enemy)
- 脚本名: snake_case (player.gd, enemy_ai.gd)
- 场景名: snake_case (level_1.tscn, main_menu.tscn)
```

### 3. 批量操作
```
优先使用批量工具:
- node_duplicate (批量复制)
- tilemap (批量铺设)
- filesystem_list (批量文件操作)
```

### 4. 错误处理
```
始终检查操作结果:
1. scene_get_tree (验证场景结构)
2. node_get (验证节点存在)
3. debug_get_logs (查看错误日志)
```

---

## 多语言支持

插件支持 9 种语言：
- English
- 简体中文
- 繁體中文
- 日本語
- Русский
- Français
- Português
- Español
- Deutsch

在 GodotMCP 面板的「服务器」标签中切换语言。

---

## 参考资源

- **MCP 协议**: [references/mcp-protocol.md](references/mcp-protocol.md)
- **API 文档**: [references/api-reference.md](references/api-reference.md)
- **示例代码**: [references/examples.md](references/examples.md)
- **故障排除**: [references/troubleshooting.md](references/troubleshooting.md)

---

## 许可证

**非商业使用许可证**

允许:
- 个人学习和研究
- 非商业开源项目
- 教育和教学

禁止:
- 商业用途
- 未经授权的再分发

商业使用请联系作者: LIDAXIAN (微信: lidaxian-AI)

---

## 贡献

欢迎提交 Issue 和 Pull Request！

GitHub: https://github.com/DaxianLee/godot-mcp