MCP for Unity 开发者指南本地开发环境搭建、工具分组机制与测试体系全解析【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp本文是 docs/development/README-DEV-zh.md 的深度展开版面向想要为 MCP for Unity 贡献代码、开发 Python Server 或理解工具可见性传播机制的开发者。你将掌握如何将 Unity 指向本地 Server 实现最快迭代、如何用mcp_source.py在四种包源间切换、工具分组Tool Groups如何通过manage_toolsMeta-Tool 在 HTTP/Stdio 两种传输模式下生效以及如何运行 Python 与 Unity 两侧的完整测试套件。一、项目双端架构与开发分支约定MCP for Unity 的代码库分为两大端理解这一点是后续开发的前提Python Server 端位于 Server/是一个基于 FastMCP 的 MCP 服务器负责把 Unity 编辑器的能力以标准 MCP 工具tool的形式暴露给 Claude、Codex、VS Code 等任意 MCP 客户端。工具通过装饰器自动注册见 tool_registry.py。Unity 编辑器端C# 包位于 MCPForUnity/以 UPM 包形式提供通过 HTTPWebSocket/ Stdio 两种传输与 Python Server 通信包含 Editor 窗口 UI、工具发现服务与各类业务工具实现。分支约定贡献代码时请从beta分支创建 PRmain分支仅用于稳定版本发布。在提出重大新功能之前建议先通过 issue 或 discussion 讨论协调——可能已有人在开发或该功能曾被讨论过。二、本地开发环境设置2.1 将 Unity 指向本地 Server最快迭代方式开发 Python Server 时最快的迭代路径是让 Unity 直接使用你本地工作区的Server/代码而非每次发布到远端仓库再拉取。操作步骤如下打开 Unity进入Window MCP for Unity打开Settings Advanced Settings将Server Source Override设置为本地Server/目录路径启用Dev Mode (Force fresh server install)——这会在 uvx 命令中添加--refresh确保每次启动 server 时都强制使用最新代码跳过缓存其中Server Source Override是开发者模式下最重要的开关它让 Unity 端启动 MCP server 时直接指向本地目录配合--refresh后你在Server/src/下改的每一行 Python 代码都会在下次启动时生效无需手动构建或复制产物。2.2 切换包源mcp_source.py当你同时维护上游、自己的 fork 和本地工作区时频繁手工编辑Packages/manifest.json很容易出错。仓库根目录的 mcp_source.py 提供了一键切换脚本python mcp_source.py脚本会交互式提供四个选项选项含义实际写入的依赖 URL1. Upstream main稳定版本https://github.com/CoplayDev/unity-mcp.git?path/MCPForUnity#main2. Upstream beta开发分支https://github.com/CoplayDev/unity-mcp.git?path/MCPForUnity#beta3. Remote branch你的 fork 当前分支从origin远端与当前分支推导如https://github.com/you/unity-mcp.git?path/MCPForUnity#branch4. Local workspace指向本地 MCPForUnity 文件夹的file:URLfile:repo_root/MCPForUnity从源码看其实现逻辑mcp_source.py脚本通过git remote get-url origin读取远端地址并会自动将 SSH 形式的 origin如gitgithub.com:...规范化为 https 形式见normalize_origin_to_https因为 Unity 的 UPM git 依赖只接受 https URL本地选项则直接拼接file:协议指向仓库内的MCPForUnity目录。写入目标由find_manifest从当前目录向上查找Packages/manifest.json自动定位也支持--manifest、--repo、--choice参数非交互式使用如 CI 场景。切换后在 Unity 中打开Package Manager并点击Refresh以重新解析依赖。三、工具分组与 Meta-ToolMCP for Unity 将数十个工具组织为分组Core、VFX Shaders、Animation、UI Toolkit、Scripting Extensions、Testing 等。你可以选择性地启用或禁用工具分组控制暴露给 AI 客户端的能力范围——这不仅减少了上下文窗口占用还能让 AI 聚焦在相关工具上避免无关工具干扰决策。3.1 分组定义源码级视角所有合法分组名在 tool_registry.py 的TOOL_GROUPS字典中集中定义分组名描述core场景、脚本、资源与编辑器核心工具默认始终开启docsUnity API 反射与文档查询vfx视觉特效——VFX Graph、Shader、程序化纹理animationAnimator 控制与 AnimationClip 创建uiUI ToolkitUXML、USS、UIDocumentscripting_extScriptableObject 管理testing测试运行器与异步测试任务probuilderProBuilder 3D 建模依赖com.unity.probuilder包profilingUnity Profiler 会话控制、计数器、内存快照与 Frame Debuggerasset_genAI 资源生成——3D 模型生成/导入、2D 图像生成与音频生成自带 Key其中DEFAULT_ENABLED_GROUPS {core}即默认只有 core 分组可见。工具通过mcp_for_unity_tool(groupvfx)这类装饰器参数归属分组装饰器会把tags{group:name}注入 FastMCP 的 tag 体系tool_registry.py驱动按会话per-session的可见性控制。groupNone的工具如manage_tools本身、set_active_instance永远可见不受分组开关影响。3.2 使用编辑器中的 Tools 标签页打开Window MCP for Unity切换到Tools标签页。每个工具分组显示为可折叠面板包含单个工具开关——点击单个工具的开关来启用或禁用分组复选框——每个分组折叠面板的标题旁内嵌一个复选框可一次性启用或禁用该分组内所有工具且不会触发折叠面板的展开或收起代码中通过ClickEvent.StopPropagation()防止事件冒泡见 McpToolsSection.csEnable All / Disable All——全局按钮一键切换所有工具的启用状态Rescan——重新从程序集发现工具添加新的[McpForUnityTool]类后使用内部会先InvalidateCache()清除工具发现缓存再刷新Reconfigure Clients——一键重新注册工具到服务器并重新配置所有检测到的 MCP 客户端无需返回 Clients 标签页即可应用更改。每个工具行还会展示若干标签例如「On by default / Off by default」「Structured output / Free-form」「Polling: xxx」以及参数签名摘要方便开发者快速判断工具行为。UI 实现可参考 McpToolsSection.cs其中HandleToggleChange在每次开关切换后都会调用ReregisterToolsAsync()触发工具重注册。3.3 更改如何传播HTTP 与 Stdio 的本质差异工具可见性的变更根据传输模式有两种完全不同的传播路径HTTP 模式推荐切换工具会调用ReregisterToolsAsync()WebSocketTransportClient.cs通过 WebSocket 将更新后的启用工具列表作为register_tools消息发送到 Python 服务器服务器通过mcp.enable()/mcp.disable()按分组更新内部工具可见性服务器向所有已连接的客户端会话发送tools/list_changedMCP 通知已连接的客户端Claude Desktop、VS Code 等自动接收更新后的工具列表。Stdio 模式开关状态在本地保存但无法推送到服务器没有 WebSocket 连接服务器启动时所有分组均启用更改开关后让 AI 执行manage_toolsaction设为sync——这会从 Unity 拉取当前工具状态并同步服务器可见性也可以重启服务器来应用更改。关于第 2 步的底层机制sync动作在服务端调用sync_tool_visibility_from_unity()Server/src/services/tools/init.py它通过 legacy TCP 连接向 Unity 发送get_tool_states命令取回工具的启用状态列表再交给PluginHub._sync_server_tool_visibility同步服务器可见性最后向客户端广播tools/list_changed。如果 Unity 包版本过旧不支持get_tool_states服务端会返回unsupported错误并提示升级 MCPForUnity 包。3.4manage_toolsMeta-Tool服务器暴露一个内置的manage_tools工具始终可见不受分组限制AI 可以直接调用。它基于 FastMCP 3.x 的原生按会话可见性系统实现manage_tools.pyAction描述关键参数list_groups列出所有工具分组及其工具和启用/禁用状态无activate按名称启用一个工具分组group如vfxdeactivate按名称禁用一个工具分组groupsync从 Unity 拉取当前工具状态并同步服务器可见性stdio 模式必需无reset恢复默认工具可见性回到DEFAULT_ENABLED_GROUPS无实现细节上activate/deactivate会调用ctx.enable_components(tags{group:name})与ctx.disable_components(...)list_groups会遍历TOOL_GROUPS并叠加当前会话的可见性规则返回每个分组的enabled、default_enabled、tools与tool_count字段方便 AI 据此决策。另外还有一个只读资源mcpforunity://tool-groupstool_groups.py可供客户端直接查询分组元数据。3.5 何时需要重新配置切换工具启用/禁用后MCP 客户端需要获知这些变更HTTP 模式变更通过tools/list_changed自动传播大多数客户端会立即更新。如果客户端未更新请在 Tools 标签页点击Reconfigure Clients或前往 Clients 标签页点击 Configure。Stdio 模式服务器进程需要被告知变更。可以让 AI 调用manage_tools(actionsync)或重启 MCP 会话。点击Reconfigure Clients会以更新后的配置重新注册所有客户端——从源码看该按钮对 CLI 型客户端如 Claude Code采用先注销再注册的两次调用策略对 JSON 文件型客户端则直接幂等重写配置McpToolsSection.cs。四、运行测试所有新功能都应包含测试覆盖。项目维护两套独立的测试体系。4.1 Python 测试Server 端测试位于 Server/tests/覆盖传输层、工具注册、参数归一化、会话隔离、鉴权、遥测、编辑器状态契约等大量维度。使用 uv 作为依赖与运行管理工具cd Server uv run pytest tests/ -v4.2 Unity C# 测试编辑器端C# 测试位于 TestProjects/UnityMCPTests/Assets/Tests/。有两种运行方式方式一使用 CLI需要 Unity 运行且 MCP bridge 已连接。CLI 入口定义在 Server/src/cli/main.py 的editor命令组下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 客户端例如 Claude Desktoprun_tests(modeEditMode) run_tests(modePlayMode, init_timeout120000) # PlayMode 由于域重载可能需要更长的初始化时间 get_test_job(job_idid, wait_timeout60)注意 PlayMode 测试因涉及域重载Domain Reload初始化耗时长建议调大init_timeout示例为 120000ms。4.3 代码覆盖率Python 侧支持 pytest-cov 覆盖率报告cd Server uv run pytest tests/ --cov --cov-reporthtml open htmlcov/index.html--cov-reporthtml会生成可交互浏览的 HTML 报告便于在本地确认新增测试是否覆盖了关键分支。五、开发相关资源导航项目主 README功能概览、快速开始、多实例路由、v10 迁移等README.md中文本地化 READMEdocs/i18n/README-zh.md包源切换脚本mcp_source.pyPython Server 源码Server/src/Unity 编辑器端源码MCPForUnity/Editor/Python 测试套件Server/tests/Unity C# 测试工程TestProjects/UnityMCPTests/Assets/Tests/开发速查改 Python Server → 用 Advanced Settings 的 Server Source Override Dev Mode 指向本地Server/改 Unity 端 → 用mcp_source.py选项 4 切到本地file:URL新增[McpForUnityTool]类 → Tools 标签页点 Rescan调整工具可见性 → HTTP 模式自动传播、Stdio 模式用manage_tools(actionsync)提交前 → 确保 Python 与 Unity 两侧测试全部通过并从beta分支发起 PR。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考