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 用户初始化

WSL2 Ubuntu 首次启动会弹出提示创建用户：

Provisioning the new WSL instance Ubuntu
Create a default Unix user account: <输入你的用户名，如 hornet>
New password: <输入密码>
Retype new password: <确认密码>

必须先完成用户创建，再运行 deploy.ps1，否则所有文件会安装到 root 用户下，部署后无法正常使用。

💡 如果已不小心在 OOBE 前运行了脚本，再次运行 deploy.ps1 即可自动用正确用户重新安装。

---

场景一：全新 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 工具列表

工具	功能
execute_menu_item	执行 Unity 菜单项
select_gameobject	选中场景中的 GameObject
update_gameobject	更新/创建 GameObject 属性
update_component	更新/添加组件
add_package	通过 Package Manager 安装包
run_tests	运行 Unity Test Runner 测试
add_asset_to_scene	将 Asset 添加到场景
create_prefab	创建 Prefab
create_scene / load_scene / delete_scene	场景管理
get_gameobject	获取 GameObject 详细信息
get_console_logs	读取 Unity Console 日志
recompile_scripts	重新编译脚本
create_material / assign_material	材质管理
move/rotate/scale_gameobject	Transform 操作
batch_execute	批量执行多个操作

---

防火墙放行（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)

# 统计文件 token 数
rtk myfile.txt

# 从管道统计
cat large_context.md | rtk

# 分析代码文件
find . -name "*.cs" | xargs cat | rtk

故障排查 — rtk 安装失败

cargo install --git https://github.com/rtk-ai/rtk

---

环境检测逻辑

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

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