新增godot mcp github copilot
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Claude Dev Stack
|
||||
|
||||
WSL2 + Claude Code CLI + Unity MCP + Rust Token Killer **全栈一键部署方案**，适用于 Windows 11 开发环境。
|
||||
WSL2 + Claude Code CLI + GitHub Copilot CLI + Unity MCP + **Godot MCP Pro** + Rust Token Killer **全栈一键部署方案**，适用于 Windows 11 开发环境。
|
||||
|
||||
支持 **WSL2 镜像网络模式**（`autoProxy=true`），WSL2 自动继承 Windows 代理状态，无需脚本干预。
|
||||
|
||||
@@ -10,7 +10,9 @@ WSL2 + Claude Code CLI + Unity MCP + Rust Token Killer **全栈一键部署方
|
||||
|------|------|---------|
|
||||
| **WSL2** | Windows Subsystem for Linux 2 | Windows 功能 |
|
||||
| **Claude Code CLI** | `@anthropic-ai/claude-code` | WSL2 npm global |
|
||||
| **GitHub Copilot CLI** | `gh` + `github/gh-copilot` 扩展 | WSL2 apt + gh extension |
|
||||
| **Unity MCP Server** | `AnkleBreaker-Studio/unity-mcp-server` — Claude ↔ Unity Editor 双向集成 | WSL2 独立 Node.js 服务 + Unity Plugin |
|
||||
| **Godot MCP Pro** | 本地 ZIP 包（v1.14.1）— Claude ↔ Godot Editor 双向集成，170+ 工具 | `~/godot-mcp-pro/`（Win）+ `~/.mcp-servers/godot-mcp-pro/`（WSL2） |
|
||||
| **Rust** | rustup stable 工具链 | WSL2 `~/.cargo` |
|
||||
| **RTK** | Rust Token Killer (`rtk`) — LLM token 统计与上下文优化 | WSL2 cargo bin |
|
||||
|
||||
@@ -18,9 +20,13 @@ WSL2 + Claude Code CLI + Unity MCP + Rust Token Killer **全栈一键部署方
|
||||
|
||||
```
|
||||
claude-dev-stack/
|
||||
├── deploy.ps1 # Windows 一键部署（PowerShell 5.1+）
|
||||
├── wsl-setup.sh # WSL2 内部安装脚本（可单独运行）
|
||||
├── .env.example # 配置模板
|
||||
├── deploy.ps1 # Windows 一键部署（PowerShell 5.1+）
|
||||
├── wsl-setup.sh # WSL2 内部安装脚本（可单独运行）
|
||||
├── .env.example # 配置模板
|
||||
├── godot-mcp-pro-v1.14.1/ # Godot MCP Pro 本地包（付费，随仓库分发）
|
||||
│ ├── server/ # Node.js MCP Server（build/ 已预编译）
|
||||
│ ├── addons/godot_mcp/ # Godot 插件（手动复制到各项目）
|
||||
│ └── INSTALL.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
@@ -28,6 +34,16 @@ claude-dev-stack/
|
||||
|
||||
## 快速开始
|
||||
|
||||
### ℹ️ GitHub Copilot CLI 共存说明
|
||||
|
||||
本方案安装的是 **WSL2 Linux 原生 GitHub CLI + gh-copilot 扩展**。
|
||||
即使 Windows 已经安装了 GitHub Copilot CLI / GitHub CLI，也**不会覆盖 Windows 版本**。
|
||||
|
||||
- Windows 继续使用 Windows 自己的 `gh`
|
||||
- WSL2 继续使用 WSL2 自己的 `gh`
|
||||
- 两边各自维护独立的登录状态和配置，互不冲突
|
||||
- `deploy.ps1` 会额外写入 PowerShell 快捷命令 `gh-copilot-wsl`，用于**显式调用 WSL2 版本**，避免误用 Windows 侧命令
|
||||
|
||||
### ℹ️ WSL2 默认用户
|
||||
|
||||
本方案使用 **root** 作为 WSL2 默认用户（通过 `/etc/wsl.conf` 配置）。
|
||||
@@ -51,6 +67,15 @@ notepad .env
|
||||
pwsh .\deploy.ps1
|
||||
```
|
||||
|
||||
脚本会自动在 **WSL2 内** 安装以下组件：
|
||||
|
||||
1. Claude Code CLI
|
||||
2. GitHub CLI (`gh`)
|
||||
3. GitHub Copilot CLI 扩展 (`github/gh-copilot`)
|
||||
4. Unity MCP Server
|
||||
5. Godot MCP Pro（从本地 `godot-mcp-pro-v1.14.1/` 复制）
|
||||
6. Rust + RTK
|
||||
|
||||
首次安装 WSL2 特性后可能需要**重启系统**，重启后重新执行脚本。
|
||||
|
||||
### 场景二：已有 WSL2，跳过 WSL2 安装
|
||||
@@ -74,6 +99,8 @@ bash wsl-setup.sh
|
||||
|
||||
### WSL2 镜像模式自动继承 Windows 代理
|
||||
|
||||
> **注意**：镜像网络模式仅支持 **Windows 11 22H2（Build 22621）及以上版本**。Windows 10 用户脚本会自动跳过此配置，WSL2 使用默认 NAT 模式，需在 WSL2 内手动配置代理。
|
||||
|
||||
脚本自动配置 `~/.wslconfig` 启用 WSL2 镜像网络模式：
|
||||
|
||||
```ini
|
||||
@@ -360,6 +387,173 @@ npm config set registry https://registry.npmmirror.com
|
||||
|
||||
---
|
||||
|
||||
## Godot MCP Pro 完整安装教程
|
||||
|
||||
> **版本**：v1.14.1（付费本地包，随本仓库分发）
|
||||
> **要求**：Godot 4.x + Node.js 18+
|
||||
> **组成**：`server/`（Node.js MCP 服务端）+ `addons/godot_mcp/`（Godot 编辑器插件）
|
||||
|
||||
### 架构原理
|
||||
|
||||
```
|
||||
Claude Code CLI / Claude Desktop / Cursor / Windsurf / VS Code
|
||||
│ MCP 协议 (stdio)
|
||||
▼
|
||||
Node.js MCP Server ← deploy.ps1 自动安装
|
||||
(~/.mcp-servers/godot-mcp-pro/ ← WSL2 侧
|
||||
%USERPROFILE%\godot-mcp-pro\ ← Windows 侧（供非 WSL 客户端）
|
||||
server/build/index.js)
|
||||
│ WebSocket
|
||||
▼
|
||||
Godot Editor Plugin (GDScript) ← 手动复制到各 Godot 项目
|
||||
(addons/godot_mcp/ ← 须在 Project Settings → Plugins 启用)
|
||||
│
|
||||
▼
|
||||
Godot 场景 / 节点 / 脚本 / 运行时测试...
|
||||
```
|
||||
|
||||
> ⚠️ **端口说明**：MCP 服务端自动扫描 **6505–6509** 寻找可用端口，**不要**在配置中固定 `GODOT_MCP_PORT`，让 Godot 插件自动连接所有候选端口即可。
|
||||
|
||||
---
|
||||
|
||||
### Step 1：运行部署脚本（自动安装服务端）
|
||||
|
||||
```powershell
|
||||
pwsh .\deploy.ps1
|
||||
```
|
||||
|
||||
脚本会自动：
|
||||
1. 将 `godot-mcp-pro-v1.14.1/server/` 同步到 `%USERPROFILE%\godot-mcp-pro\`（Windows）
|
||||
2. 将 `server/` 复制到 WSL2 `~/.mcp-servers/godot-mcp-pro/`
|
||||
3. 在两侧执行 `npm install` 安装依赖（`build/` 目录已预编译，无需编译步骤）
|
||||
4. 将 `godot-mcp-pro` 条目写入 Claude Desktop / Cursor / Windsurf / VS Code / Claude Code CLI
|
||||
|
||||
---
|
||||
|
||||
### Step 2：在 Godot 项目中安装插件（每个项目一次）
|
||||
|
||||
部署脚本**不会**自动安装 Godot 插件，因为它需要逐项目手动操作：
|
||||
|
||||
1. 打开文件管理器，进入本仓库目录：
|
||||
```
|
||||
claude-dev-stack\godot-mcp-pro-v1.14.1\addons\
|
||||
```
|
||||
2. 将 `godot_mcp/` 目录整体复制到你的 **Godot 项目根目录** 下的 `addons/` 中：
|
||||
```
|
||||
你的Godot项目/
|
||||
└── addons/
|
||||
└── godot_mcp/ ← 从 godot-mcp-pro-v1.14.1\addons\godot_mcp\ 复制过来
|
||||
```
|
||||
3. 在 Godot 编辑器中：**Project → Project Settings → Plugins**，找到 **Godot MCP Pro** 并勾选 **Enable**
|
||||
4. 插件启用后，状态栏显示连接端口（如 `MCP listening on :6505`）
|
||||
|
||||
---
|
||||
|
||||
### Step 3：确认 MCP 配置
|
||||
|
||||
部署脚本已自动写入各客户端配置。Windows 侧确认：
|
||||
|
||||
```powershell
|
||||
cat "$env:APPDATA\Claude\claude_desktop_config.json"
|
||||
```
|
||||
|
||||
应包含（Windows 侧条目，供 Claude Desktop / Cursor / Windsurf / VS Code）：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"godot-mcp-pro": {
|
||||
"command": "node",
|
||||
"args": ["C:/Users/YourName/godot-mcp-pro/build/index.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
WSL2 内的条目（供 Claude Code CLI）：
|
||||
|
||||
```bash
|
||||
claude mcp list --scope user
|
||||
# 应包含: godot-mcp-pro node /root/.mcp-servers/godot-mcp-pro/build/index.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4：在 Claude Code 中使用 Godot MCP Pro
|
||||
|
||||
> ⚠️ **重要区分**：Editor 工具（场景/节点/脚本操作）**随时可用**；Runtime 工具（游戏运行时状态/截图/输入模拟）**必须先调用 `play_scene` 启动游戏**。
|
||||
|
||||
```bash
|
||||
# 启动 Claude Code（WSL2 内）
|
||||
claude
|
||||
|
||||
# 验证 Godot MCP 连接
|
||||
> /mcp
|
||||
# 应看到 godot-mcp-pro 及其工具列表
|
||||
|
||||
# ── 示例：场景搭建 ──
|
||||
> 创建一个名为 Player 的 CharacterBody2D 节点，添加 CollisionShape2D 和 Sprite2D 子节点
|
||||
|
||||
# ── 示例：脚本操作 ──
|
||||
> 读取 res://scripts/player.gd，帮我添加跳跃逻辑
|
||||
|
||||
# ── 示例：运行测试 ──
|
||||
> play_scene 后截图，检查 Player 是否出现在屏幕中央
|
||||
|
||||
# ── 示例：批量修改 ──
|
||||
> 将场景中所有 Label 节点的字体大小统一改为 24
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 可用工具分类（170+ 工具）
|
||||
|
||||
| 分类 | 代表工具 | 说明 |
|
||||
|------|----------|------|
|
||||
| **项目/文件系统** | `get_project_info`, `get_filesystem_tree`, `search_files` | 项目概览与文件搜索 |
|
||||
| **场景** | `get_scene_tree`, `create_scene`, `open_scene`, `save_scene` | 场景生命周期 |
|
||||
| **节点** | `add_node`, `update_property`, `connect_signal`, `batch_set_property` | 节点增删改 |
|
||||
| **脚本** | `read_script`, `create_script`, `edit_script`, `validate_script` | GDScript 读写验证 |
|
||||
| **编辑器** | `get_editor_screenshot`, `get_editor_errors`, `get_output_log` | 编辑器状态截图 |
|
||||
| **3D** | `add_mesh_instance`, `setup_lighting`, `setup_camera_3d`, `setup_collision` | 3D 场景搭建 |
|
||||
| **动画** | `create_animation`, `add_animation_track`, `create_animation_tree` | 动画与状态机 |
|
||||
| **Audio** | `add_audio_bus`, `add_audio_player`, `get_audio_bus_layout` | 音频系统 |
|
||||
| **导航** | `setup_navigation_region`, `bake_navigation_mesh` | NavMesh 导航 |
|
||||
| **粒子** | `create_particles`, `apply_particle_preset` | 粒子特效 |
|
||||
| **Shader** | `create_shader`, `edit_shader`, `assign_shader_material` | 着色器编写 |
|
||||
| **Tilemap** | `tilemap_set_cell`, `tilemap_fill_rect` | 瓦片地图 |
|
||||
| **分析** | `analyze_scene_complexity`, `detect_circular_dependencies`, `find_unused_resources` | 项目分析 |
|
||||
| **运行时** | `play_scene`, `get_game_screenshot`, `simulate_key`, `run_test_scenario` | 运行时控制与测试 |
|
||||
|
||||
---
|
||||
|
||||
### 故障排查 — Godot MCP Pro
|
||||
|
||||
**问题：`/mcp` 中看不到 godot-mcp-pro**
|
||||
```
|
||||
解决：
|
||||
1. 重新运行 deploy.ps1（幂等，可多次执行）
|
||||
2. 检查 claude mcp list --scope user 是否有 godot-mcp-pro 条目
|
||||
3. 重启 Claude Code：exit → claude
|
||||
```
|
||||
|
||||
**问题：工具调用失败，Godot 插件未响应**
|
||||
```
|
||||
解决：
|
||||
1. 确认 Godot 编辑器已打开，且插件已在 Project Settings → Plugins 中启用
|
||||
2. 确认插件状态栏显示 "MCP listening on :650X"
|
||||
3. 不要设置 GODOT_MCP_PORT 环境变量；让服务端自动扫描
|
||||
```
|
||||
|
||||
**问题：WSL2 侧 npm install 超时**
|
||||
```bash
|
||||
# 设置国内镜像后重试
|
||||
npm config set registry https://registry.npmmirror.com
|
||||
cd ~/.mcp-servers/godot-mcp-pro && npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用方式
|
||||
|
||||
### Claude Code CLI
|
||||
@@ -375,6 +569,43 @@ claude
|
||||
claude-wsl
|
||||
```
|
||||
|
||||
### GitHub Copilot CLI（WSL2 原生）
|
||||
|
||||
首次使用前，需要在 **WSL2 内单独登录 GitHub**：
|
||||
|
||||
```bash
|
||||
gh auth login
|
||||
```
|
||||
|
||||
验证 gh-copilot 扩展已安装：
|
||||
|
||||
```bash
|
||||
gh extension list | grep gh-copilot
|
||||
```
|
||||
|
||||
常用命令：
|
||||
|
||||
```bash
|
||||
# 命令建议
|
||||
gh copilot suggest "写一个 bash 脚本，递归统计当前目录下最大的 20 个文件"
|
||||
|
||||
# 命令解释
|
||||
gh copilot explain "find . -type f -name '*.log' -mtime +7 -delete"
|
||||
```
|
||||
|
||||
如果你人在 Windows PowerShell 中，但想**强制调用 WSL2 版本**，使用部署脚本写入的快捷函数：
|
||||
|
||||
```powershell
|
||||
gh-copilot-wsl suggest "生成一个 bash 命令，列出 Git 仓库中最近修改的 10 个文件"
|
||||
gh-copilot-wsl explain "tar -czf backup.tar.gz ~/project --exclude node_modules"
|
||||
```
|
||||
|
||||
这两个入口的职责建议固定：
|
||||
|
||||
- 在 Windows PowerShell 里直接输入 `gh ...`，默认走 Windows 版本
|
||||
- 在 Windows PowerShell 里输入 `gh-copilot-wsl ...`，明确走 WSL2 版本
|
||||
- 在 WSL2 终端里输入 `gh ...`，明确走 WSL2 版本
|
||||
|
||||
### RTK (Rust Token Killer)
|
||||
|
||||
RTK 作为 Claude Code 的 **PreToolUse hook** 运行，自动将 bash 命令重写为 `rtk` 等效命令，过滤噪音、压缩输出，减少 60–90% token 消耗。
|
||||
|
||||
Reference in New Issue
Block a user