server-deploy/claude-dev-stack

Claude Dev Stack

WSL2 + Claude Code CLI + Unity MCP + Rust Token Killer 全栈一键部署方案，适用于 Windows 11 开发环境。

支持 v2rayN 代理自动检测、WSL2 代理透传、防火墙自动放行。

组件清单

组件	说明	安装位置
WSL2	Windows Subsystem for Linux 2	Windows 功能
Claude Code CLI	@anthropic-ai/claude-code	WSL2 npm global
Unity MCP Server	AnkleBreaker-Studio/unity-mcp-server — Claude ↔ Unity Editor 双向集成	WSL2 独立 Node.js 服务 + Unity Plugin
Rust	rustup stable 工具链	WSL2 ~/.cargo
RTK	Rust Token Killer (rtk) — LLM token 统计与上下文优化	WSL2 cargo bin

目录结构

claude-dev-stack/
├── deploy.ps1        # Windows 一键部署（PowerShell 5.1+）
├── wsl-setup.sh      # WSL2 内部安装脚本（可单独运行）
├── .env.example      # 配置模板
└── README.md

---

快速开始

ℹ️ WSL2 默认用户

本方案使用 root 作为 WSL2 默认用户（通过 /etc/wsl.conf 配置）。
WSL2 Ubuntu 首次启动若弹出用户创建提示，可直接跳过或按提示操作，deploy.ps1 会自动将默认用户切换为 root。

---

场景一：全新 Windows 系统（首次安装 WSL2）

需要管理员权限启用 WSL2 Windows 功能

# 1. 以管理员身份运行 PowerShell
cd path\to\claude-dev-stack

# 2. 复制配置文件，填写 ANTHROPIC_API_KEY
cp .env.example .env
notepad .env

# 3. 运行部署脚本（自动检测 v2rayN 代理）
pwsh .\deploy.ps1

# 手动指定代理端口
pwsh .\deploy.ps1 -ProxyPort 10809

# 不使用代理（直连）
pwsh .\deploy.ps1 -ProxyPort -1

首次安装 WSL2 特性后可能需要重启系统，重启后重新执行脚本。

场景二：已有 WSL2，跳过 WSL2 安装

pwsh .\deploy.ps1 -SkipWSL

场景三：仅在 WSL2 内安装（无 Windows 脚本）

# 在 WSL2 Ubuntu 终端中执行
cp .env.example .env
nano .env
# 如需代理（端口由 deploy.ps1 写入 ~/.mcp-proxy.env，或手动指定）
PROXY_PORT=10809 bash wsl-setup.sh

---

代理说明（v2rayN）

自动检测顺序

1. Windows 系统代理注册表（v2rayN「设为系统代理」时写入）
2. v2rayN 配置文件（%APPDATA%\v2rayN\guiNConfig.json）
3. 探测常用端口：10809, 10808, 7890, 1080, 8080

WSL2 代理透传原理

WSL2 Ubuntu
  → [Windows 主机 vEthernet(WSL) IP]:10809
  → v2rayN
  → 互联网

必须在 v2rayN 中开启：

参数设置 → 「允许来自局域网的连接」 ✅

脚本自动完成：

• 写入 WSL2 ~/.mcp-proxy.env（每次 shell 启动自动生效）
• 配置 WSL2 git + npm 代理
• apt-get 安装阶段同样走代理

代理覆盖范围

操作	是否走代理
Windows git clone / npm install	✅
WSL2 apt-get / git clone / npm install / cargo install	✅
MCP Server ↔ AI 客户端（stdio）	❌ 本地通信，无需代理
MCP Server ↔ Unity Plugin（localhost）	❌ 本地通信，无需代理

---

配置说明（.env）

变量	默认值	说明
ANTHROPIC_API_KEY	(空)	Anthropic API Key，从 console.anthropic.com 获取
ANTHROPIC_BASE_URL	https://api.anthropic.com	API 基础 URL；中转代理可改为 DeepSeek 等兼容接口
CLAUDE_MODEL	claude-opus-4-5	默认使用的模型
WSL_DISTRO	Ubuntu	WSL2 发行版名称
SKIP_WSL_INSTALL	false	true 跳过 WSL2 安装步骤

---

Unity MCP 完整安装教程

MCP Server 仓库：AnkleBreaker-Studio/unity-mcp-server
Unity Plugin 仓库：AnkleBreaker-Studio/unity-mcp-plugin
https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git 要求：Unity 2021.3+ + Node.js 18+

架构原理

Unity MCP 由两个独立仓库组成，各自独立安装：

Claude Code CLI
      │  MCP 协议 (stdio)
      ▼
Node.js MCP Server                    ← 克隆自 unity-mcp-server，WSL2 中运行
(~/.mcp-servers/unity-mcp-server/)    ← deploy.ps1 自动完成克隆 + npm install
      │  WebSocket / HTTP
      ▼
Unity Editor Plugin (C#)              ← Package Manager 安装 unity-mcp-plugin
      │
      ▼
Unity 场景 / 对象 / 脚本 / 测试...

• unity-mcp-server：独立 Node.js MCP 服务，部署脚本自动克隆并安装依赖
• unity-mcp-plugin：Unity C# 插件，需要手动通过 Package Manager 安装

---

Step 1：运行部署脚本（自动完成服务器安装）

pwsh .\deploy.ps1

脚本会自动：

1. 克隆 unity-mcp-server 到 WSL2 ~/.mcp-servers/unity-mcp-server/
2. 执行 npm install 安装依赖
3. 将 MCP Server 注册到 %USERPROFILE%\.claude\claude_desktop_config.json

---

Step 2：在 Unity Editor 安装 unity-mcp-plugin

1. 打开 Unity Editor
2. 菜单：Window → Package Manager
3. 点击左上角 "+" 按钮 → "Add package from git URL..."
4. 输入以下 URL，点击 Add：

   https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git
   

5. 等待包下载安装完成

安装完成后，菜单栏会出现 Tools → Unity MCP 选项。

---

Step 3：启动 Unity Editor 端 MCP 服务

每次使用 Claude Code 操作 Unity 之前，需要先在 Unity 中启动服务：

1. 打开 Unity Editor，确保项目已加载
2. 菜单：Tools → Unity MCP → Start Server（具体菜单项名称以插件实际为准）
3. 状态变为绿色 / Connected 表示服务就绪

---

Step 4：确认 MCP 配置

部署脚本已自动写入 Windows Claude Code 配置。确认内容：

cat "$env:USERPROFILE\.claude\claude_desktop_config.json"

应包含类似如下内容：

{
  "mcpServers": {
    "unity-mcp": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "--", "node", "/home/用户名/.mcp-servers/unity-mcp-server/src/index.js"]
    }
  }
}

WSL2 内的配置（~/.config/Claude/claude_desktop_config.json）直接使用 node：

{
  "mcpServers": {
    "unity-mcp": {
      "command": "node",
      "args": ["/home/用户名/.mcp-servers/unity-mcp-server/src/index.js"]
    }
  }
}

---

Step 5：在 Claude Code 中使用 Unity MCP

# 启动 Claude Code（WSL2 内）
claude

# 验证 Unity MCP 连接
> /mcp

# 示例：操作 Unity 场景
> 在场景中创建一个名为 Player 的空 GameObject
> 给 Player 添加 Rigidbody 组件，质量设为 5
> 创建一个新场景 Level1，保存到 Assets/Scenes/
> 运行所有 EditMode 测试

---

可用 MCP 工具列表

AnkleBreaker Unity MCP 采用两级工具架构，共 288 个工具：

• 核心工具（~70个）：直接暴露，无需中转
• 高级工具（200+）：通过 unity_advanced_tool 代理访问（避免 MCP 客户端工具过多失效）

核心工具（直接可用）

分类	工具名	功能
编辑器状态	unity_editor_ping / unity_editor_state / unity_project_info	检测连接、获取编辑器/项目状态
场景	unity_scene_info/open/save/new/hierarchy/stats	场景完整生命周期管理
GameObject	unity_gameobject_create/delete/info/set_transform/duplicate/set_active/reparent	对象增删改查
组件	unity_component_add/remove/get_properties/set_property/set_reference/batch_wire	组件与属性操作
资产	unity_asset_list/import/delete/create_prefab/instantiate_prefab	资产管理
脚本	unity_script_create/read/update + unity_execute_code	C# 脚本读写与运行时执行
材质	unity_material_create / unity_renderer_set_material	材质创建与赋值
构建/运行	unity_build / unity_play_mode	多平台构建、Play Mode 控制
控制台	unity_console_log/clear + unity_get_compilation_errors	日志读取与编译错误
编辑器操作	unity_execute_menu_item / unity_undo/redo/undo_history	菜单执行、撤销重做
选择/搜索	unity_selection_* / unity_search_by_* / unity_search_assets	对象查找与选中
截图	unity_screenshot_game/scene + unity_graphics_*_capture	场景/游戏视图截图
Prefab	unity_prefab_info / unity_set_object_reference	Prefab 信息与引用
包管理	unity_packages_list/add/remove/search/info	Package Manager 操作
Multi-Agent	unity_queue_info / unity_agents_list / unity_agent_log	多代理会话管理
高级工具代理	unity_list_advanced_tools / unity_advanced_tool	访问 200+ 高级工具
Unity Hub	unity_hub_list_editors/available_releases/install_editor/install_modules	Hub 版本管理
多实例	unity_list_instances / unity_select_instance	多 Unity 实例切换
项目上下文	unity_get_project_context	AI 代理项目文档注入

高级工具分类（通过 unity_advanced_tool 访问）

动画、Prefab 模式、物理、光照、音频、地形、导航网格、粒子、UI、标签与层、输入系统、Shader Graph、VFX Graph、Amplify Shader Editor、性能分析器、帧调试器、内存分析器、ScriptableObject、约束、LOD、MPPM 多人 PlayMode、UMA Avatar 等 30+ 分类。

# 列出所有高级工具
> 使用 unity_list_advanced_tools 查看所有高级工具

# 按分类过滤
> unity_list_advanced_tools { "category": "animation" }
> unity_list_advanced_tools { "category": "terrain" }

# 执行高级工具
> unity_advanced_tool { "tool": "unity_animation_create_controller", "params": {...} }

deploy.ps1 会自动将所有工具写入 ~/.claude/settings.json 的 allowedTools 白名单，无需每次手动确认。

---

防火墙放行（Bridge 端口）

deploy.ps1 会自动创建防火墙规则，放行 TCP 7890–7899（Bridge Port 范围）。

手动放行：

New-NetFirewallRule -DisplayName "Unity MCP Bridge Inbound" `
    -Direction Inbound -Protocol TCP -LocalPort 7890-7899 -Action Allow -Profile Any
New-NetFirewallRule -DisplayName "Unity MCP Bridge Outbound" `
    -Direction Outbound -Protocol TCP -LocalPort 7890-7899 -Action Allow -Profile Any

验证 Bridge 是否可用：

# Unity Editor 打开后
Invoke-WebRequest http://127.0.0.1:7890/api/ping
# 返回 200 OK 表示 Bridge 正常

---

故障排查

问题：Unity MCP 连接失败

解决：
1. 确认 Unity Editor 已打开，且 unity-mcp-plugin 已启动服务
2. 测试 Bridge: Invoke-WebRequest http://127.0.0.1:7890/api/ping
3. 确认防火墙 TCP 7890 已放行
4. 确认 MCP Server 进程正常：wsl -d Ubuntu -- node ~/.mcp-servers/unity-mcp-server/src/index.js
5. 重新执行 deploy.ps1 重新克隆并注册 MCP Server

问题：更新 unity-mcp-server 后连接失败

解决：
wsl -d Ubuntu -- bash -c "cd ~/.mcp-servers/unity-mcp-server && git pull && npm install"

问题：npm install 安装超时（国内网络）

# 方案一：通过 v2rayN 代理（推荐）
pwsh .\deploy.ps1 -ProxyPort 10809

# 方案二：WSL2 内配置镜像
npm config set registry https://registry.npmmirror.com

问题：WSL2 无法连接 v2rayN 代理

解决：
1. v2rayN → 参数设置 → 勾选「允许来自局域网的连接」
2. 确认防火墙未拦截 v2rayN 监听端口
3. WSL2 内测试：curl -I https://github.com --proxy http://$(ip route | grep default | awk '{print $3}'):10809

问题：Unity 版本兼容性

请参考 unity-mcp-plugin 仓库的 README 了解所需 Unity 最低版本要求

---

使用方式

Claude Code CLI

# 进入 WSL2
wsl -d Ubuntu

# 启动 Claude Code
claude

# 或从 PowerShell 快捷命令（由 deploy.ps1 写入 profile）
claude-wsl

RTK (Rust Token Killer)

RTK 作为 Claude Code 的 PreToolUse hook 运行，自动将 bash 命令重写为 rtk 等效命令，过滤噪音、压缩输出，减少 60–90% token 消耗。

deploy.ps1 会自动执行 rtk init -g 注册 hook，重启 Claude Code 后即生效。

# 验证 hook 安装状态
rtk init --show

# 查看 token 节省统计（需先在 Claude Code 中运行一些命令）
rtk gain
rtk gain --graph       # ASCII 图表
rtk gain --history     # 最近命令历史

# 手动使用（无需 hook）
rtk git status         # 压缩 git status 输出
rtk cargo test         # 只显示失败的测试
rtk grep "pattern" .   # 分组搜索结果

故障排查 — rtk 安装失败

# 手动安装
cargo install --git https://github.com/rtk-ai/rtk

# 手动初始化 hook
rtk init -g

---

环境检测逻辑

脚本对每个组件均先检测是否已安装，已安装则跳过，实现幂等执行：

WSL2         → wsl --list 检测发行版
Node.js      → node --version
Claude Code  → claude --version
Rust         → rustc --version
rtk          → rtk --version
Unity MCP    → 检测 ~/.mcp-servers/unity-mcp-server/

---

故障排查

WSL2 安装失败

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -NoRestart
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart
# 重启后
wsl --update
wsl --install -d Ubuntu

Rust/cargo 安装慢

在 .env 或 ~/.bashrc 中添加 RsProxy 镜像：

export RUSTUP_DIST_SERVER=https://rsproxy.cn
export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup