wehub-resource-sync
140 lines
5.4 KiB
Markdown
140 lines
5.4 KiB
Markdown
# MCP for Unity - 开发者指南
|
||
|
||
| [English](README-DEV.md) | [简体中文](README-DEV-zh.md) |
|
||
|---------------------------|------------------------------|
|
||
|
||
## 贡献代码
|
||
|
||
**从 `beta` 分支创建 PR**。`main` 分支仅用于稳定版本发布。
|
||
|
||
在提出重大新功能之前，请先联系讨论——可能已有人在开发，或者该功能曾被讨论过。请通过 issue 或 discussion 进行协调。
|
||
|
||
## 本地开发环境设置
|
||
|
||
### 1. 将 Unity 指向本地 Server
|
||
|
||
开发 Python server 时，最快的迭代方式：
|
||
|
||
1. 打开 Unity，进入 **Window > MCP for Unity**
|
||
2. 打开 **Settings > Advanced Settings**
|
||
3. 将 **Server Source Override** 设置为本地 `Server/` 目录路径
|
||
4. 启用 **Dev Mode (Force fresh server install)** - 这会在 uvx 命令中添加 `--refresh`，确保每次启动 server 时都使用最新代码
|
||
|
||
### 2. 切换包源
|
||
|
||
使用 `mcp_source.py` 快速切换 Unity 项目的 MCP 包源：
|
||
|
||
```bash
|
||
python mcp_source.py
|
||
```
|
||
|
||
选项：
|
||
1. **Upstream main** - 稳定版本 (CoplayDev/unity-mcp)
|
||
2. **Upstream beta** - 开发分支 (CoplayDev/unity-mcp#beta)
|
||
3. **Remote branch** - 你的 fork 当前分支
|
||
4. **Local workspace** - 指向本地 MCPForUnity 文件夹的 file: URL
|
||
|
||
切换后，在 Unity 中打开 Package Manager 并 Refresh 以重新解析依赖。
|
||
|
||
## 工具选择与 Meta-Tool
|
||
|
||
MCP for Unity 将工具组织为**分组**（Core、VFX & Shaders、Animation、UI Toolkit、Scripting Extensions、Testing）。你可以选择性地启用或禁用工具，以控制哪些能力暴露给 AI 客户端——减少上下文窗口占用，让 AI 专注于相关工具。
|
||
|
||
### 使用编辑器中的 Tools 标签页
|
||
|
||
打开 **Window > MCP for Unity**，切换到 **Tools** 标签页。每个工具分组显示为可折叠面板，包含：
|
||
|
||
- **单个工具开关** — 点击单个工具的开关来启用或禁用。
|
||
- **分组复选框** — 每个分组折叠面板的标题旁内嵌一个复选框，可一次性启用或禁用该分组内所有工具，且不会触发折叠面板的展开或收起。
|
||
- **Enable All / Disable All** — 全局按钮，切换所有工具的启用状态。
|
||
- **Rescan** — 重新从程序集发现工具（在添加新的 `[McpForUnityTool]` 类后使用）。
|
||
- **Reconfigure Clients** — 一键重新注册工具到服务器并重新配置所有检测到的 MCP 客户端，无需返回 Clients 标签页即可应用更改。
|
||
|
||
### 更改如何传播
|
||
|
||
工具可见性的变更根据传输模式有所不同：
|
||
|
||
**HTTP 模式**（推荐）：
|
||
|
||
1. 切换工具会调用 `ReregisterToolsAsync()`，通过 WebSocket 将更新后的启用工具列表发送到 Python 服务器。
|
||
2. 服务器通过 `mcp.enable()`/`mcp.disable()` 按分组更新内部工具可见性。
|
||
3. 服务器向所有已连接的客户端会话发送 `tools/list_changed` MCP 通知。
|
||
4. 已连接的客户端（Claude Desktop、VS Code 等）自动接收更新后的工具列表。
|
||
|
||
**Stdio 模式**：
|
||
|
||
1. 开关状态在本地保存，但无法推送到服务器（没有 WebSocket 连接）。
|
||
2. 服务器启动时所有分组均启用。更改开关后，让 AI 执行 `manage_tools`，`action` 设为 `'sync'`——这会从 Unity 拉取当前工具状态并同步服务器可见性。
|
||
3. 也可以重启服务器来应用更改。
|
||
|
||
### `manage_tools` Meta-Tool
|
||
|
||
服务器暴露一个内置的 `manage_tools` 工具（始终可见，不受分组限制），AI 可以直接调用：
|
||
|
||
| Action | 描述 |
|
||
|--------|------|
|
||
| `list_groups` | 列出所有工具分组及其工具和启用/禁用状态 |
|
||
| `activate` | 按名称启用一个工具分组（例如 `group="vfx"`） |
|
||
| `deactivate` | 按名称禁用一个工具分组 |
|
||
| `sync` | 从 Unity 拉取当前工具状态并同步服务器可见性（stdio 模式必需） |
|
||
| `reset` | 恢复默认工具可见性 |
|
||
|
||
### 何时需要重新配置
|
||
|
||
切换工具启用/禁用后，MCP 客户端需要获知这些变更：
|
||
|
||
- **HTTP 模式**：变更通过 `tools/list_changed` 自动传播。大多数客户端会立即更新。如果客户端未更新，请在 Tools 标签页点击 **Reconfigure Clients**，或前往 Clients 标签页点击 Configure。
|
||
- **Stdio 模式**：服务器进程需要被告知变更。可以让 AI 调用 `manage_tools(action='sync')`，或重启 MCP 会话。点击 **Reconfigure Clients** 以使用更新后的配置重新注册所有客户端。
|
||
|
||
## 运行测试
|
||
|
||
所有新功能都应包含测试覆盖。
|
||
|
||
### Python 测试 (502 个测试)
|
||
|
||
位于 `Server/tests/`：
|
||
|
||
```bash
|
||
cd Server
|
||
uv run pytest tests/ -v
|
||
```
|
||
|
||
### Unity C# 测试 (605 个测试)
|
||
|
||
位于 `TestProjects/UnityMCPTests/Assets/Tests/`。
|
||
|
||
**使用 CLI**（需要 Unity 运行且 MCP bridge 已连接）：
|
||
|
||
```bash
|
||
cd Server
|
||
|
||
# 运行 EditMode 测试（默认）
|
||
uv run python -m cli.main editor tests
|
||
|
||
# 运行 PlayMode 测试
|
||
uv run python -m cli.main editor tests --mode PlayMode
|
||
|
||
# 异步运行并轮询结果（适用于长时间测试）
|
||
uv run python -m cli.main editor tests --async
|
||
uv run python -m cli.main editor poll-test <job_id> --wait 60
|
||
|
||
# 仅显示失败的测试
|
||
uv run python -m cli.main editor tests --failed-only
|
||
```
|
||
|
||
**直接使用 MCP 工具**（从任意 MCP 客户端）：
|
||
|
||
```
|
||
run_tests(mode="EditMode")
|
||
run_tests(mode="PlayMode", init_timeout=120000) # PlayMode 由于域重载可能需要更长的初始化时间
|
||
get_test_job(job_id="<id>", wait_timeout=60)
|
||
```
|
||
|
||
### 代码覆盖率
|
||
|
||
```bash
|
||
cd Server
|
||
uv run pytest tests/ --cov --cov-report=html
|
||
open htmlcov/index.html
|
||
```
|