Unity MCP愿景
Unity MCP Vision是一款人工智能辅助的Unity编辑器副驾驶，它允许模型上下文协议（MCP）客户端（Claude Desktop、Cursor、VS Code）通过FastAPI桥和Unity editor插件执行撤销安全编辑器工具。该系统侧重于确定性JSON合约、多模式视觉支持和易于观察性，因此您可以使用自然语言指令对游戏内容进行原型制作。
主要特点
- 异步命令代理 –排队AI发布的任务，防止重复
requestId值，跟踪状态/持续时间，并将工作出租给具有冲突检测功能的Unity员工。 - 撤消安全Unity工具 –所有写入操作（对象创建、组件编辑、材质）都在编辑器内运行，具有自动撤消检查点和原子属性应用程序。
- 双模视觉流水线 –在外部HTTP多模式API之间切换或
claude_mcp环回模式，当API键不可用时，将场景视图捕获返回到桌面客户端。 - 可扩展+可观察 JSON工具目录反映了Unity处理程序、手动测试剧本文档有效载荷，pytest套件涵盖了服务器往返。
工具目录
| 域 | 命令 | 描述 |
|---|---|---|
| 游戏对象 | create_primitive | 使用自定义名称和变换创建立方体/球体/胶囊/平面对象。 |
set_transform | 有选择地更新位置、旋转或缩放字段。 | |
find_gameobject | 返回命名对象的层次结构路径和组件摘要。 | |
| 组件 | add_component | 通过简短的、完全限定的或装配限定的名称添加组件，并可选择 componentProperties. |
get_component_details | 检查组件元数据和序列化字段。 | |
| 材料 | create_material | 使用目标着色器生成材质（默认为URP Lit）。 |
set_material_color | 将十六进制颜色应用于暴露的属性。 | |
assign_material | 将现有材质实例绑定到渲染器。 | |
| 脚本 | create_script / read_script | 创建样板C#脚本或下载源代码内容以供审查。 |
| 场景和诊断 | get_scene_hierarchy | 快照当前场景图，对导航很有用。 |
read_console_errors | Stream Unity控制台错误（限制1-200）。 | |
undo, redo | 调用Unity的撤销堆栈以从错误中恢复。 | |
| 愿景 | describe_scene_view | 捕获活动场景视图并请求自然语言描述。 |
find_object_from_description | 使用HTTP或本地推理将文本描述与可见对象进行匹配。 |
其他测试有效载荷记录在 docs/manual_testing.md.
建筑一瞥
- Python快速API中间件(
server/) –暴露/command,/bridge/commands/next，以及/vision/*端点，验证模式，记录持续时间，并将数据路由到代理。 - 命令代理 –消除重复请求，通过长轮询将工作分配给Unity工作人员，并记录
CommandResult直到Unity确认完成。 - Unity编辑器插件(
unity/Assets/Editor/MCP/) –轮询中间件，执行工具处理程序，包装撤消检查点中的写入，并使用worker id报告结果/错误。 - 愿景客户 –用以下方式签署HTTP请求
MCP_VISION_API_KEY或短路claude_mcp该模式将屏幕截图/提示元数据直接返回给MCP客户端。
需求
- Unity 2021 LTS或更高版本（在2021.3+上测试）。
- Python 3.11+
venv支持。 - 适用于Claude Desktop或其他MCP兼容客户端的macOS 12+/Windows 10+。
- 可选：用于外部视觉提供者的多模式API密钥。
安装和设置
- 克隆存储库
git clone https://github.com/your-org/unity-mcp.git
cd unity-mcp- 准备Python中间件
cd server
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt- 配置环境变量
- 复制 .env.example 到 .env 并设置 MCP_VISION_API_KEY 如果使用HTTP视觉提供者。 - 覆盖默认值，如 MCP_ALLOWED_ORIGINS 或 MCP_VISION_MODE 根据需要。
- 运行FastAPI桥
uvicorn app.main:app --reloadAPI监听 http://localhost:8000。保持这个终端打开。
- 启动MCP stdio适配器 （新终端，相同的虚拟环境）
python -m mcp_server --base-url http://localhost:8000此过程通过JSON-RPC stdin/stdout将Unity工具暴露给MCP本机客户端。
- 打开Unity项目
- 启动Unity Hub并添加 unity/ 文件夹作为一个项目。 - 编译后，运行 MCP/Create Settings Asset 生成 McpSettings.asset 并设置服务器URL/工作者id/轮询间隔。 - 打开 MCP/Dashboard 实时状态窗口。
- 连接MCP客户端（例如Claude Desktop）
- 注册指向的本地stdio服务器 server/.venv/bin/python -m mcp_server --base-url http://localhost:8000 （根据操作系统调整路径）。 - 一旦克劳德展示了 running 徽章，发出自然语言请求，如“在｛x:0，y:0.5，z:0｝处创建一个名为TestCube的多维数据集。”
视觉模式
http（默认）：向外部多模式API发送base64截图+提示；需要MCP_VISION_API_KEY.claude_mcp：通过将屏幕截图、提示和对象元数据直接打包到MCP响应中，绕过外部API。Claude Desktop（或其他本地客户端）执行解释。- 切换模式
McpSettings在Unity中或通过设置MCP_VISION_MODE在.env.
测试和故障排除
- 跑
pytest在...之下server/验证命令/视觉端点和代理行为。 - 使用
docs/manual_testing.md用于覆盖每个工具的手动JSON有效载荷。 - 常见修复：
- MCP客户端无法连接 –确认FastAPI服务器和 mcp_server 进程正在运行，端口（8000）空闲。 - 命令被拒绝 –确保有效载荷符合要求 { "commandName", "arguments" } 形状和组件名称在不明确时是完全限定的。 - 视觉占位符响应 –表示缺少API密钥或 claude_mcp 没有连接客户端的模式。
进一步阅读
unity-mcp需求.md–功能要求和验收标准。unity-mcp技术方案.md–架构图、风险分析和里程碑。docs/–手动测试配方和其他文档。