diff --git a/README-DEV-zh.md b/README-DEV-zh.md new file mode 100644 index 0000000..1513cf9 --- /dev/null +++ b/README-DEV-zh.md @@ -0,0 +1,215 @@ +# MCP for Unity 开发工具 + +| [English](README-DEV.md) | [简体中文](README-DEV-zh.md) | +|---------------------------|------------------------------| + +欢迎来到 MCP for Unity 开发环境！此目录包含简化 MCP for Unity 核心开发的工具和实用程序。 + +## 🚀 可用开发功能 + +### ✅ 开发部署脚本 +用于 MCP for Unity 核心更改的快速部署和测试工具。 + +### 🔄 即将推出 +- **开发模式切换**：内置 Unity 编辑器开发功能 +- **热重载系统**：无需重启 Unity 的实时代码更新 +- **插件开发工具包**：用于创建自定义 MCP for Unity 扩展的工具 +- **自动化测试套件**：用于贡献的综合测试框架 +- **调试面板**：高级调试和监控工具 + +--- + +## 快速切换 MCP 包源 + +从 unity-mcp 仓库运行，而不是从游戏的根目录。使用 `mcp_source.py` 在不同的 MCP for Unity 包源之间快速切换： + +**用法:** +```bash +python mcp_source.py [--manifest /path/to/manifest.json] [--repo /path/to/unity-mcp] [--choice 1|2|3] +``` + +**选项:** +- **1** 上游主分支 (CoplayDev/unity-mcp) +- **2** 远程当前分支 (origin + branch) +- **3** 本地工作区 (file: UnityMcpBridge) + +切换后，打开包管理器并刷新以重新解析包。 + +## 开发部署脚本 + +这些部署脚本帮助您快速测试 MCP for Unity 核心代码的更改。 + +## 脚本 + +### `deploy-dev.bat` +将您的开发代码部署到实际安装位置进行测试。 + +**作用:** +1. 将原始文件备份到带时间戳的文件夹 +2. 将 Unity Bridge 代码复制到 Unity 的包缓存 +3. 将 Python 服务器代码复制到 MCP 安装文件夹 + +**用法:** +1. 运行 `deploy-dev.bat` +2. 输入 Unity 包缓存路径（提供示例） +3. 输入服务器路径（或使用默认：`%LOCALAPPDATA%\Programs\UnityMCP\UnityMcpServer\src`） +4. 输入备份位置（或使用默认：`%USERPROFILE%\Desktop\unity-mcp-backup`） + +**注意:** 开发部署跳过 `.venv`, `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.git`；减少变动并避免复制虚拟环境。 + +### `restore-dev.bat` +从备份恢复原始文件。 + +**作用:** +1. 列出可用的带时间戳的备份 +2. 允许您选择要恢复的备份 +3. 恢复 Unity Bridge 和 Python 服务器文件 + +### `prune_tool_results.py` +将对话 JSON 中的大型 `tool_result` 块压缩为简洁的单行摘要。 + +**用法:** +```bash +python3 prune_tool_results.py < reports/claude-execution-output.json > reports/claude-execution-output.pruned.json +``` + +脚本从 `stdin` 读取对话并将修剪版本写入 `stdout`，使日志更容易检查或存档。 + +这些默认设置在不影响基本信息的情况下大幅减少了令牌使用量。 + +## 查找 Unity 包缓存路径 + +Unity 将 Git 包存储在版本或哈希文件夹下。期望类似于： +``` +X:\UnityProject\Library\PackageCache\com.coplaydev.unity-mcp@ +``` +示例（哈希）： +``` +X:\UnityProject\Library\PackageCache\com.coplaydev.unity-mcp@272123cfd97e + +``` + +可靠找到它： +1. 打开 Unity 包管理器 +2. 选择"MCP for Unity"包 +3. 右键单击包并选择"在资源管理器中显示" +4. 这将打开 Unity 为您的项目使用的确切缓存文件夹 + +注意：在最新版本中，Python 服务器源代码也打包在包内的 `UnityMcpServer~/src` 下。这对于本地测试或将 MCP 客户端直接指向打包服务器很方便。 + +## MCP Bridge 压力测试 + +按需压力测试实用程序通过多个并发客户端测试 MCP bridge，同时通过立即脚本编辑触发真实脚本重载（无需菜单调用）。 + +### 脚本 +- `tools/stress_mcp.py` + +### 作用 +- 对 Unity MCP bridge 启动 N 个 TCP 客户端（默认端口从 `~/.unity-mcp/unity-mcp-status-*.json` 自动发现）。 +- 发送轻量级帧 `ping` 保活以维持并发。 +- 并行地，使用 `manage_script.apply_text_edits` 向目标 C# 文件追加唯一标记注释： + - `options.refresh = "immediate"` 立即强制导入/编译（触发域重载），以及 + - 从当前文件内容计算的 `precondition_sha256` 以避免漂移。 +- 使用 EOF 插入避免头部/`using` 保护编辑。 + +### 用法（本地） +```bash +# 推荐：使用测试项目中包含的大型脚本 +python3 tools/stress_mcp.py \ + --duration 60 \ + --clients 8 \ + --unity-file "TestProjects/UnityMCPTests/Assets/Scripts/LongUnityScriptClaudeTest.cs" +``` + +标志： +- `--project` Unity 项目路径（默认自动检测到包含的测试项目） +- `--unity-file` 要编辑的 C# 文件（默认为长测试脚本） +- `--clients` 并发客户端数量（默认 10） +- `--duration` 运行秒数（默认 60） + +### 预期结果 +- 重载过程中 Unity 编辑器不崩溃 +- 每次应用编辑后立即重载（无 `Assets/Refresh` 菜单调用） +- 域重载期间可能发生一些暂时断开连接或少数失败调用；工具会重试并继续 +- 最后打印 JSON 摘要，例如： + - `{"port": 6400, "stats": {"pings": 28566, "applies": 69, "disconnects": 0, "errors": 0}}` + +### 注意事项和故障排除 +- 立即 vs 防抖： + - 工具设置 `options.refresh = "immediate"` 使更改立即编译。如果您只需要变动（不需要每次编辑确认），切换到防抖以减少重载中失败。 +- 需要前置条件： + - `apply_text_edits` 在较大文件上需要 `precondition_sha256`。工具首先读取文件以计算 SHA。 +- 编辑位置： + - 为避免头部保护或复杂范围，工具在每个周期的 EOF 处追加单行标记。 +- 读取 API： + - bridge 当前支持 `manage_script.read` 进行文件读取。您可能看到弃用警告；对于此内部工具无害。 +- 暂时失败： + - 偶尔的 `apply_errors` 通常表示连接在回复过程中重载。编辑通常仍会应用；循环在下次迭代时继续。 + +### CI 指导 +- 由于 Unity/编辑器要求和运行时变化，将此排除在默认 PR CI 之外。 +- 可选择在具有 Unity 功能的运行器上作为手动工作流或夜间作业运行。 + +## CI 测试工作流（GitHub Actions） + +我们提供 CI 作业来对 Unity 测试项目运行自然语言编辑套件。它启动无头 Unity 容器并通过 MCP bridge 连接。要从您的 fork 运行，您需要以下 GitHub "secrets"：`ANTHROPIC_API_KEY` 和 Unity 凭据（通常是 `UNITY_EMAIL` + `UNITY_PASSWORD` 或 `UNITY_LICENSE` / `UNITY_SERIAL`）。这些在日志中被编辑所以永远不可见。 + +***运行方法*** + - 触发：在仓库的 GitHub "Actions" 中，触发 `workflow dispatch`（`Claude NL/T Full Suite (Unity live)`）。 + - 镜像：`UNITY_IMAGE`（UnityCI）按标签拉取；作业在运行时解析摘要。日志已清理。 + - 执行：单次通过，立即按测试片段发射（严格的每个文件单个 ``）。如果任何片段是裸 ID，占位符保护会快速失败。暂存（`reports/_staging`）被提升到 `reports/` 以减少部分写入。 + - 报告：JUnit 在 `reports/junit-nl-suite.xml`，Markdown 在 `reports/junit-nl-suite.md`。 + - 发布：JUnit 规范化为 `reports/junit-for-actions.xml` 并发布；工件上传 `reports/` 下的所有文件。 + +### 测试目标脚本 +- 仓库包含一个长的独立 C# 脚本，用于练习较大的编辑和窗口： + - `TestProjects/UnityMCPTests/Assets/Scripts/LongUnityScriptClaudeTest.cs` + 在本地和 CI 中使用此文件来验证多编辑批次、锚插入和大型脚本上的窗口读取。 + +### 调整测试/提示 +- 编辑 `.claude/prompts/nl-unity-suite-t.md` 来修改 NL/T 步骤。遵循约定：在 `reports/_results.xml` 下为每个测试发射一个 XML 片段，每个包含恰好一个以测试 ID 开头的 `name` 的 ``。无序言/尾声或代码围栏。 +- 保持编辑最小且可逆；包含简洁证据。 + +### 运行套件 +1) 推送您的分支，然后从 Actions 标签手动运行工作流。 +2) 作业将报告写入 `reports/` 并上传工件。 +3) "JUnit Test Report" 检查总结结果；打开作业摘要查看完整 markdown。 + +### 查看结果 +- 作业摘要：GitHub Actions 标签中运行的内联 markdown 摘要 +- 检查：PR/提交上的"JUnit Test Report"。 +- 工件：`claude-nl-suite-artifacts` 包含 XML 和 MD。 + +### MCP 连接调试 +- *在 Unity MCP 窗口（编辑器内）启用调试日志* 以查看连接状态、自动设置结果和 MCP 客户端路径。它显示： + - bridge 启动/端口、客户端连接、严格帧协商和解析的帧 + - 自动配置路径检测（Windows/macOS/Linux）、uv/claude 解析和显示的错误 +- 在 CI 中，如果启动失败，作业会尾随 Unity 日志（序列号/许可证/密码/令牌已编辑）并打印套接字/状态 JSON 诊断。 + +## 工作流程 + +1. **进行更改** 到此目录中的源代码 +2. **部署** 使用 `deploy-dev.bat` +3. **测试** 在 Unity 中（首先重启 Unity 编辑器） +4. **迭代** - 根据需要重复步骤 1-3 +5. **恢复** 完成后使用 `restore-dev.bat` 恢复原始文件 + +## 故障排除 + +### 运行 .bat 文件时出现"路径未找到"错误 +- 验证 Unity 包缓存路径是否正确 +- 检查是否实际安装了 MCP for Unity 包 +- 确保通过 MCP 客户端安装了服务器 + +### "权限被拒绝"错误 +- 以管理员身份运行 cmd +- 部署前关闭 Unity 编辑器 +- 部署前关闭任何 MCP 客户端 + +### "备份未找到"错误 +- 首先运行 `deploy-dev.bat` 创建初始备份 +- 检查备份目录权限 +- 验证备份目录路径是否正确 + +### Windows uv 路径问题 +- 在 Windows 上测试 GUI 客户端时，优先选择 WinGet Links `uv.exe`；如果存在多个 `uv.exe`，使用"Choose `uv` Install Location"来固定 Links shim。 \ No newline at end of file diff --git a/README-DEV.md b/README-DEV.md index 76b5937..e81b988 100644 --- a/README-DEV.md +++ b/README-DEV.md @@ -1,5 +1,9 @@ # MCP for Unity Development Tools +| [English](README-DEV.md) | [简体中文](README-DEV-zh.md) | +|---------------------------|------------------------------| + + Welcome to the MCP for Unity development environment! This directory contains tools and utilities to streamline MCP for Unity core development. ## 🚀 Available Development Features diff --git a/README-zh.md b/README-zh.md new file mode 100644 index 0000000..c5f0860 --- /dev/null +++ b/README-zh.md @@ -0,0 +1,353 @@ +MCP for Unity + +| [English](README.md) | [简体中文](README-zh.md) | +|----------------------|---------------------------------| + +#### 由 [Coplay](https://www.coplay.dev/?ref=unity-mcp) 荣誉赞助和维护 -- Unity 最好的 AI 助手。[在此阅读背景故事。](https://www.coplay.dev/blog/coplay-and-open-source-unity-mcp-join-forces) + +[![Discord](https://img.shields.io/badge/discord-join-red.svg?logo=discord&logoColor=white)](https://discord.gg/y4p8KfzrN4) +[![](https://img.shields.io/badge/Unity-000000?style=flat&logo=unity&logoColor=blue 'Unity')](https://unity.com/releases/editor/archive) +[![python](https://img.shields.io/badge/Python-3.12-3776AB.svg?style=flat&logo=python&logoColor=white)](https://www.python.org) +[![](https://badge.mcpx.dev?status=on 'MCP Enabled')](https://modelcontextprotocol.io/introduction) +![GitHub commit activity](https://img.shields.io/github/commit-activity/w/CoplayDev/unity-mcp) +![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/CoplayDev/unity-mcp) +[![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT) +[![](https://img.shields.io/badge/Sponsor-Coplay-red.svg 'Coplay')](https://www.coplay.dev/?ref=unity-mcp) + +**使用大语言模型创建您的 Unity 应用！** + +MCP for Unity 作为桥梁，允许 AI 助手（如 Claude、Cursor）通过本地 **MCP（模型上下文协议）客户端** 直接与您的 Unity 编辑器交互。为您的大语言模型提供管理资源、控制场景、编辑脚本和自动化 Unity 任务的工具。 + +--- + +### 💬 加入我们的 [Discord](https://discord.gg/y4p8KfzrN4) + +**获得帮助、分享想法，与其他 MCP for Unity 开发者协作！** + +--- + +## 主要功能 🚀 + +* **🗣️ 自然语言操控：** 指示您的大语言模型执行 Unity 任务。 +* **🛠️ 强大工具：** 管理资源、场景、材质、脚本和编辑器功能。 +* **🤖 自动化：** 自动化重复的 Unity 工作流程。 +* **🧩 可扩展：** 设计为与各种 MCP 客户端协作。 + +
+ 可用工具 + + 您的大语言模型可以使用以下功能： + + * `read_console`: 获取控制台消息或清除控制台。 + * `manage_script`: 管理 C# 脚本（创建、读取、更新、删除）。 + * `manage_editor`: 控制和查询编辑器的状态和设置。 + * `manage_scene`: 管理场景（加载、保存、创建、获取层次结构等）。 + * `manage_asset`: 执行资源操作（导入、创建、修改、删除等）。 + * `manage_shader`: 执行着色器 CRUD 操作（创建、读取、修改、删除）。 + * `manage_gameobject`: 管理游戏对象：创建、修改、删除、查找和组件操作。 + * `manage_menu_item`: 列出 Unity 编辑器菜单项；检查其存在性或执行它们（例如，执行"File/Save Project"）。 + * `apply_text_edits`: 具有前置条件哈希和原子多编辑批次的精确文本编辑。 + * `script_apply_edits`: 结构化 C# 方法/类编辑（插入/替换/删除），具有更安全的边界。 + * `validate_script`: 快速验证（基本/标准）以在写入前后捕获语法/结构问题。 +
+ +--- + +## 工作原理 + +MCP for Unity 使用两个组件连接您的工具： + +1. **MCP for Unity Bridge：** 在编辑器内运行的 Unity 包。（通过包管理器安装）。 +2. **MCP for Unity Server：** 本地运行的 Python 服务器，在 Unity Bridge 和您的 MCP 客户端之间进行通信。（首次运行时由包自动安装或通过自动设置；手动设置作为备选方案）。 + +image + +--- + +## 安装 ⚙️ + +### 前置要求 + +* **Python：** 版本 3.12 或更新。[下载 Python](https://www.python.org/downloads/) +* **Unity Hub 和编辑器：** 版本 2021.3 LTS 或更新。[下载 Unity](https://unity.com/download) +* **uv（Python 工具链管理器）：** + ```bash + # macOS / Linux + curl -LsSf https://astral.sh/uv/install.sh | sh + + # Windows (PowerShell) + winget install --id=astral-sh.uv -e + + # 文档: https://docs.astral.sh/uv/getting-started/installation/ + ``` + +* **MCP 客户端：** [Claude Desktop](https://claude.ai/download) | [Claude Code](https://github.com/anthropics/claude-code) | [Cursor](https://www.cursor.com/en/downloads) | [Visual Studio Code Copilot](https://code.visualstudio.com/docs/copilot/overview) | [Windsurf](https://windsurf.com) | 其他客户端可通过手动配置使用 + +*
[可选] Roslyn 用于高级脚本验证 + + 对于捕获未定义命名空间、类型和方法的**严格**验证级别： + + **方法 1：Unity 的 NuGet（推荐）** + 1. 安装 [NuGetForUnity](https://github.com/GlitchEnzo/NuGetForUnity) + 2. 前往 `Window > NuGet Package Manager` + 3. 搜索 `Microsoft.CodeAnalysis.CSharp`，选择版本 3.11.0 并安装包 + 5. 前往 `Player Settings > Scripting Define Symbols` + 6. 添加 `USE_ROSLYN` + 7. 重启 Unity + + **方法 2：手动 DLL 安装** + 1. 从 [NuGet](https://www.nuget.org/packages/Microsoft.CodeAnalysis.CSharp/) 下载 Microsoft.CodeAnalysis.CSharp.dll 和依赖项 + 2. 将 DLL 放置在 `Assets/Plugins/` 文件夹中 + 3. 确保 .NET 兼容性设置正确 + 4. 将 `USE_ROSLYN` 添加到脚本定义符号 + 5. 重启 Unity + + **注意：** 没有 Roslyn 时，脚本验证会回退到基本结构检查。Roslyn 启用完整的 C# 编译器诊断和精确错误报告。
+ +--- +### 🌟 步骤 1：安装 Unity 包 + +#### 通过 Git URL 安装 + +1. 打开您的 Unity 项目。 +2. 前往 `Window > Package Manager`。 +3. 点击 `+` -> `Add package from git URL...`。 +4. 输入： + ``` + https://github.com/CoplayDev/unity-mcp.git?path=/UnityMcpBridge + ``` +5. 点击 `Add`。 +6. MCP 服务器在首次运行时或通过自动设置由包自动安装。如果失败，请使用手动配置（如下）。 + +#### 通过 OpenUPM 安装 + +1. 安装 [OpenUPM CLI](https://openupm.com/docs/getting-started-cli.html) +2. 打开终端（PowerShell、Terminal 等）并导航到您的 Unity 项目目录 +3. 运行 `openupm add com.coplaydev.unity-mcp` + +**注意：** 如果您在 Coplay 维护之前安装了 MCP 服务器，您需要在重新安装新版本之前卸载旧包。 + +### 🛠️ 步骤 2：配置您的 MCP 客户端 +将您的 MCP 客户端（Claude、Cursor 等）连接到步骤 1（自动）设置的 Python 服务器或通过手动配置（如下）。 + +MCPForUnity-Readme-Image + +**选项 A：自动设置（推荐用于 Claude/Cursor/VSC Copilot）** + +1. 在 Unity 中，前往 `Window > MCP for Unity`。 +2. 点击 `Auto-Setup`。 +3. 寻找绿色状态指示器 🟢 和"Connected ✓"。*（这会尝试自动修改 MCP 客户端的配置文件）。* + +
客户端特定故障排除 + +- **VSCode**：使用 `Code/User/mcp.json` 和顶级 `servers.unityMCP` 以及 `"type": "stdio"`。在 Windows 上，MCP for Unity 写入绝对路径 `uv.exe`（优先选择 WinGet Links shim）以避免 PATH 问题。 +- **Cursor / Windsurf** [(**帮助链接**)](https://github.com/CoplayDev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode-&-Windsurf)：如果缺少 `uv`，MCP for Unity 窗口会显示"uv Not Found"和快速 [HELP] 链接以及"Choose `uv` Install Location"按钮。 +- **Claude Code** [(**帮助链接**)](https://github.com/CoplayDev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code)：如果找不到 `claude`，窗口会显示"Claude Not Found"和 [HELP] 以及"Choose Claude Location"按钮。注销现在会立即更新 UI。
+ +**选项 B：手动配置** + +如果自动设置失败或您使用不同的客户端： + +1. **找到您的 MCP 客户端配置文件。**（查看客户端文档）。 + * *Claude 示例（macOS）：* `~/Library/Application Support/Claude/claude_desktop_config.json` + * *Claude 示例（Windows）：* `%APPDATA%\Claude\claude_desktop_config.json` +2. **编辑文件** 以添加/更新 `mcpServers` 部分，使用步骤 1 中的*精确*路径。 + +
+点击查看客户端特定的 JSON 配置片段... + +--- +**Claude Code** + +如果您正在使用 Claude Code，您可以使用以下命令注册 MCP 服务器： +🚨**确保从您的 Unity 项目主目录运行这些命令**🚨 + +**macOS：** + +```bash +claude mcp add UnityMCP -- uv --directory /Users/USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src run server.py +``` + +**Windows：** + +```bash +claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py +``` +**VSCode（所有操作系统）** + +```json +{ + "servers": { + "unityMCP": { + "command": "uv", + "args": ["--directory","/UnityMcpServer/src","run","server.py"], + "type": "stdio" + } + } +} +``` + +在 Windows 上，将 `command` 设置为绝对 shim，例如 `C:\\Users\\YOU\\AppData\\Local\\Microsoft\\WinGet\\Links\\uv.exe`。 + +**Windows：** + +```json +{ + "mcpServers": { + "UnityMCP": { + "command": "uv", + "args": [ + "run", + "--directory", + "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\UnityMCP\\UnityMcpServer\\src", + "server.py" + ] + } + // ... 其他服务器可能在这里 ... + } +} +``` + +（记得替换 YOUR_USERNAME 并使用双反斜杠 \\） + +**macOS：** + +```json +{ + "mcpServers": { + "UnityMCP": { + "command": "uv", + "args": [ + "run", + "--directory", + "/Users/YOUR_USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src", + "server.py" + ] + } + // ... 其他服务器可能在这里 ... + } +} +``` + +（替换 YOUR_USERNAME。注意：AppSupport 是"Application Support"的符号链接，以避免引号问题） + +**Linux：** + +```json +{ + "mcpServers": { + "UnityMCP": { + "command": "uv", + "args": [ + "run", + "--directory", + "/home/YOUR_USERNAME/.local/share/UnityMCP/UnityMcpServer/src", + "server.py" + ] + } + // ... 其他服务器可能在这里 ... + } +} +``` + +（替换 YOUR_USERNAME） + +
+ +--- + +## 使用方法 ▶️ + +1. **打开您的 Unity 项目。** MCP for Unity 包应该自动连接。通过 Window > MCP for Unity 检查状态。 + +2. **启动您的 MCP 客户端**（Claude、Cursor 等）。它应该使用安装步骤 2 中的配置自动启动 MCP for Unity 服务器（Python）。 + +3. **交互！** Unity 工具现在应该在您的 MCP 客户端中可用。 + + 示例提示：`创建一个 3D 玩家控制器`，`创建一个 3D 井字游戏`，`创建一个酷炫的着色器并应用到立方体上`。 + +--- + +## 开发和贡献 🛠️ + +### 开发者 + +如果您正在为 MCP for Unity 做贡献或想要测试核心更改，我们有开发工具来简化您的工作流程： + +- **开发部署脚本**：快速部署和测试您对 MCP for Unity Bridge 和 Python 服务器的更改 +- **自动备份系统**：具有简单回滚功能的安全测试 +- **热重载工作流程**：核心开发的快速迭代周期 + +📖 **查看 [README-DEV.md](README-DEV.md)** 获取完整的开发设置和工作流程文档。 + +### 贡献 🤝 + +帮助改进 MCP for Unity！ + +1. **Fork** 主仓库。 +2. **创建分支**（`feature/your-idea` 或 `bugfix/your-fix`）。 +3. **进行更改。** +4. **提交**（feat: Add cool new feature）。 +5. **推送** 您的分支。 +6. **对主分支开启拉取请求**。 + +--- + +## 📊 遥测和隐私 + +Unity MCP 包含**注重隐私的匿名遥测**来帮助我们改进产品。我们收集使用分析和性能数据，但**绝不**收集您的代码、项目名称或个人信息。 + +- **🔒 匿名**：仅随机 UUID，无个人数据 +- **🚫 轻松退出**：设置 `DISABLE_TELEMETRY=true` 环境变量 +- **📖 透明**：查看 [TELEMETRY.md](TELEMETRY.md) 获取完整详情 + +您的隐私对我们很重要。所有遥测都是可选的，旨在尊重您的工作流程。 + +--- + +## 故障排除 ❓ + +
+点击查看常见问题和修复方法... + +- **Unity Bridge 未运行/连接：** + - 确保 Unity 编辑器已打开。 + - 检查状态窗口：Window > MCP for Unity。 + - 重启 Unity。 +- **MCP 客户端未连接/服务器未启动：** + - **验证服务器路径：** 双重检查您的 MCP 客户端 JSON 配置中的 --directory 路径。它必须完全匹配安装位置： + - **Windows：** `%USERPROFILE%\AppData\Local\UnityMCP\UnityMcpServer\src` + - **macOS：** `~/Library/AppSupport/UnityMCP/UnityMcpServer\src` + - **Linux：** `~/.local/share/UnityMCP/UnityMcpServer\src` + - **验证 uv：** 确保 `uv` 已安装并正常工作（`uv --version`）。 + - **手动运行：** 尝试直接从终端运行服务器以查看错误： + ```bash + cd /path/to/your/UnityMCP/UnityMcpServer/src + uv run server.py + ``` +- **自动配置失败：** + - 使用手动配置步骤。自动配置可能缺乏写入 MCP 客户端配置文件的权限。 + +
+ +仍然卡住？[开启问题](https://github.com/CoplayDev/unity-mcp/issues) 或 [加入 Discord](https://discord.gg/y4p8KfzrN4)！ + +--- + +## 许可证 📜 + +MIT 许可证。查看 [LICENSE](LICENSE) 文件。 + +--- + +## Star历史 + +[![Star History Chart](https://api.star-history.com/svg?repos=CoplayDev/unity-mcp&type=Date)](https://www.star-history.com/#CoplayDev/unity-mcp&Date) + +## 赞助 + +

+ + Coplay Logo + +

\ No newline at end of file diff --git a/README.md b/README.md index cac6a9b..f436122 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ MCP for Unity +| [English](README.md) | [简体中文](README-zh.md) | +|----------------------|---------------------------------| + #### Proudly sponsored and maintained by [Coplay](https://www.coplay.dev/?ref=unity-mcp) -- the best AI assistant for Unity. [Read the backstory here.](https://www.coplay.dev/blog/coplay-and-open-source-unity-mcp-join-forces) [![Discord](https://img.shields.io/badge/discord-join-red.svg?logo=discord&logoColor=white)](https://discord.gg/y4p8KfzrN4)