企业官网建设流程全解析

Unity MCP 工具参考完全指南：基于 Python 工具注册表自动生成的 48 个 MCP 工具全景目录

【免费下载链接】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

本文以 Unity MCP 工具参考目录（website/docs/reference/tools/index.md）为核心骨架，结合仓库中的工具注册表源码、文档生成器与相关测试，系统梳理 Unity MCP 对外暴露的全部工具分组、每个工具的能力边界、分组可见性管理机制以及这套参考文档的自动生成流水线。读完本文，你将能熟练按分组检索 Unity MCP 的任一工具，理解"核心组默认开启、其余分组按需激活"的会话级可见性模型，并能用manage_tools元工具动态控制当前会话的工具清单。

Unity MCP 是 AI 助手与 Unity Editor 之间的桥梁，它把所有能力抽象为一组 MCP 工具（Tools）：管理资产、控制场景、编辑脚本、执行构建、运行测试等。这些工具并非手写文档维护，而是直接由 Python 侧的@mcp_for_unity_tool注册表自动生成参考文档。本文介绍的就是这份"工具总目录"本身：它包含多少个工具分组、每个分组下有哪些工具、每个工具能做什么、以及这套目录是如何被自动维护的。

一、文档的生成机制：Python 注册表是唯一事实来源

打开 website/docs/reference/tools/index.md 的顶部会看到一段醒目标注："Auto-generated from the Python tool registry. Do not hand-edit..."（自动生成自 Python 工具注册表，请勿手工编辑）。这揭示了一个关键架构决策：

• 唯一事实来源（Single Source of Truth）是Server/src/services/tools/目录下所有 Python 模块中的@mcp_for_unity_tool装饰器注册表；
• C# 侧属性只携带Name/Group/Description等基础元数据，而 Python 装饰器持有最丰富的类型信息（通过Annotated[...]描述参数文档），并且这正是 MCP 客户端在网络上实际看到的内容；
• 生成的产物包括：
  • 每个工具的独立页面website/docs/reference/tools/<group>/<tool-name>.md；
  • 每个分组的地页面website/docs/reference/tools/<group>/index.md；
  • 分组总目录website/docs/reference/tools/index.md；
  • 以及资源目录website/docs/reference/resources/index.md。

生成器的工作模式

生成器脚本是 tools/generate_docs_reference.py，支持两种模式：

生成过程的核心步骤在load_registries()中：脚本将Server/src加入sys.path，然后利用 module_discovery.py 中的discover_modules()遍历并导入services.tools与services.resources包下所有模块——装饰器的副作用（向全局注册表追加条目）在这一过程中被触发，注册表随即被填满。

值得注意的细节：--check模式（main()中的--check分支）仍会从已提交的规范位置读取手工编写的 examples 块，因此 CI 校验不会破坏示例内容。若校验失败，脚本会提示：

python tools/generate_docs_reference.py

然后提交改动。仓库中的 CI 运行方式（见脚本 docstring）：

cd Server && uv sync && cd .. && uv --project Server run python tools/generate_docs_reference.py --check

手工示例的保留机制

生成器通过<!-- examples:start -->与<!-- examples:end -->标记对来保护手工编写的示例：生成时会从既有文件中抽取这两个标记之间的内容并在重写后原样保留，未添加示例的页面则会写入占位提示。例如 manage_tools 工具页 当前的 Examples 段就是占位符：

<!-- examples:start --> *No examples yet. Add usage examples here — they will be preserved across regenerations.* <!-- examples:end -->

这意味着：任何工具页的 "Examples" 区域都允许社区手工补充，且不会被自动生成覆盖。

参数表如何生成

生成器通过inspect.signature与typing.get_type_hints(include_extras=True)对每个工具函数做内省（introspect_params()），从Annotated[T, "描述文本"]中提取参数说明，渲染为 Markdown 参数表：

同时，_render_type()负责把复杂注解（Annotated、Union、Literal、list[...]、dict[...]）渲染成简洁、Markdown 安全的类型字符串——这正是每个工具页参数表里类型列的来源。

二、分组总览：10 个领域分组、48 个工具

根据 总目录，Unity MCP 当前暴露10 个工具分组、共 48 个工具。分组的权威定义在 tool_registry.py 的TOOL_GROUPS字典中，与文档中逐个##小节一一对应：

TOOL_GROUPS中每个分组还带有供文档与manage_tools展示的 blurb（一句话描述）。此外，注册表接受特殊分组值None，表示该工具始终可见、不受分组开关影响——用于set_active_instance、manage_tools这类服务器元工具。

三、逐组工具清单与能力速查

3.1core核心组（30 个，默认开启）

这是最重要的分组，覆盖 AI 助手操作 Unity 的日常高频能力，见 core 分组页：

• 脚本编辑类：apply_text_edits（按 URI 对 C# 脚本做小范围文本编辑）、script_apply_edits（结构化 C# 编辑，支持方法/类级的安全边界，官方建议优先于裸文本编辑）、create_script、delete_script、get_sha（返回脚本 SHA256 与元数据但不返回文件内容）、validate_script（校验并返回诊断）、find_in_file（正则搜文件并返回行号与片段）；
• 场景与对象类：find_gameobjects（按名称、标签、层级、组件类型或路径搜索）、manage_gameobject（GameObject CRUD）、manage_components（增删组件与设置属性）、manage_scene（场景 CRUD）、manage_prefabs、manage_camera（Unity Camera + Cinemachine）；
• 资产与资源类：manage_asset（导入/创建/修改/删除等资产操作）、manage_material、manage_texture、manage_packages（查询/安装/移除/嵌入包与配置源）、manage_build（触发构建、切换平台、配置设置、管理构建场景与配置档、跨平台批量构建）；
• 编辑器控制类：manage_editor（控制并查询编辑器状态与设置）、execute_menu_item（按路径执行 Unity 菜单项）、read_console（读取或清空编辑器控制台）、refresh_unity（请求资源数据库刷新并可附带脚本编译）、debug_request_context（返回当前 FastMCP 请求上下文：client_id、session_id 与 meta dump）、batch_execute（单批执行多条 MCP 命令，显著提升性能）；
• 会话与兼容类：manage_tools（控制本会话可见的工具分组）、set_active_instance（设置本客户端/会话的活跃 Unity 实例）、execute_custom_tool（执行 Unity 注册的项目级自定义工具）、manage_script（旧版脚本操作的兼容路由）、manage_script_capabilities（查询 manage_script 支持的操作、限制与保护）、manage_graphics（体积雾、后处理、光照烘焙、渲染统计、渲染管线设置与 URP Renderer Feature）、manage_physics（物理设置、碰撞矩阵、材质、关节、查询与校验）。

3.2asset_genAI 资产生成组（5 个）

自带 API Key（bring-your-own-key）的 AI 生成能力，详见 asset_gen 分组页：

• generate_model— 用 AI 供应商（Tripo、Meshy）生成 3D 模型并导入 Unity 项目；
• generate_image— 用 AI 供应商（fal.ai、OpenRouter）生成 2D 图像并作为纹理/Sprite 导入；
• generate_audio— 用 fal.ai 模型生成音效与背景音乐并导入为 AudioClip；
• import_model— 从 Sketchfab 市场导入 3D 模型；
• import_model_file— 导入磁盘上已有的本地 3D 模型文件（如从 Blender 或其他 DCC 工具导出的 FBX/OBJ/glTF）。

3.3docs文档与反射组（2 个）

• unity_docs— 从 docs.unity3d.com 获取官方 Unity 文档；
• unity_reflect— 通过反射检视 Unity 实时的 C# API。

3.4vfx视觉特效组（3 个）

• manage_shader— 管理 Unity 中的 Shader 脚本（创建、读取、更新、删除）；
• manage_texture— Unity 程序化纹理生成；
• manage_vfx— 管理 VFX 组件（ParticleSystem、VisualEffect、LineRenderer、TrailRenderer）。

3.5scripting_ext脚本扩展组（2 个）

• execute_code— 在 Unity 编辑器内执行任意 C# 代码；
• manage_scriptable_object— 使用 UnitySerializedObject属性路径创建与修改 ScriptableObject 资产。

3.6testing测试组（2 个，异步模型）

• run_tests— 异步启动 Unity 测试运行，立即返回job_id；
• get_test_job— 用job_id轮询异步测试任务的进度与结果。

3.7 其余单工具分组

• animation/manage_animation— Animator 控制与 AnimationClip 创建；
• ui/manage_ui— 管理 UI Toolkit 元素（UXML 文档、USS 样式表、UIDocument 组件）；
• probuilder/manage_probuilder— ProBuilder 网格编辑，实现编辑器内 3D 建模（需安装com.unity.probuilder包）；
• profiling/manage_profiler— Profiler 会话控制、计数器读取、内存快照与 Frame Debugger。

四、分组可见性模型：为什么 core 默认开启、其余按需激活

目录页会告诉你"核心工具默认开启"，但底层机制是什么？答案在 tool_registry.py 与 tools/init.py 的register_all_tools()中：

1. 装饰器打标签：mcp_for_unity_tool(..., group="vfx")会把tags={"group:vfx"}合并进该工具传递给 FastMCP 的 kwargs。注册表维护DEFAULT_ENABLED_GROUPS = {"core"}，即仅 core 分组默认启用。
2. HTTP 模式启动即瘦身：register_all_tools()在 transport 为 HTTP 时，会把TOOL_GROUPS.keys() - DEFAULT_ENABLED_GROUPS中所有分组的 tool 组件disable掉，让新会话从精简的 core 工具集开始；Unity 连接后通过PluginHub._sync_server_tool_visibility重新按需启用。
3. Stdio 模式全量开启后同步：由于旧版 TCP 桥没有register_tools消息，stdio 模式启动时会话内全部分组可见，随后由sync_tool_visibility_from_unity()通过get_tool_states资源查询 Unity 的开关状态并回填可见性。
4. group=None豁免：set_active_instance与manage_tools属于服务器元工具（unity_target=None, group=None），永远可见、不受分组系统影响。

对验证该模型感兴趣的读者，可在仓库测试中看到相应断言，例如 Server/tests/test_tool_registry_metadata.py 与 Server/tests/test_tool_annotations.py。

五、实战：用manage_tools动态控制会话工具清单

manage_tools是理解分组模型后最值得立即上手的工具（其源码位于 manage_tools.py，工具页见 manage_tools.md）。它支持五种action：

典型对话式用法：

manage_tools(action="list_groups") manage_tools(action="activate", group="profiling") # 激活 Profiler 相关工具 manage_tools(action="deactivate", group="vfx") # 隐藏 VFX 工具 manage_tools(action="reset") # 恢复默认

从源码看，activate/deactivate分别调用 FastMCP 的ctx.enable_components/ctx.disable_components（按group:<name>标签作用于 tool 组件），基于 FastMCP 3.x 的会话级可见性，因此在 stdio、HTTP、SSE 所有传输上都生效；sync会调用上一节提到的sync_tool_visibility_from_unity(notify=True)，并在 Unity 包版本过旧（不支持get_tool_states）时给出明确的升级提示与降级建议。

六、配套使用：实例路由与批量执行

掌握目录后，有两个工具值得配套理解：

• set_active_instance（源码见 set_active_instance.py）：在多开 Unity 实例的场景下，通过Name@hash、哈希前缀（stdio 下还支持端口号）选定当前会话路由的目标实例；HTTP 远程托管模式下端口号定位不可用，需用Name@hash或哈希前缀，可先读取mcpforunity://instances资源确认可用实例。
• batch_execute：把多条 MCP 命令打包成一次调用执行，是 AI 助手连续操作场景下"戏剧性提升性能"的关键手段，适合脚本批量调整、批量资产操作等任务。

七、如何继续深入：文档分层与维护闭环

整个参考体系是分层、可追溯的：

1. 总目录（本文主题）→ 2.分组页（website/docs/reference/tools/<group>/index.md）→ 3.单工具页（website/docs/reference/tools/<group>/<tool>.md，含描述、参数表、返回说明与 Examples 区）→ 4.Python 源码（Server/src/services/tools/*.py中的装饰器函数）。

每一层都有对应的 Docusaurus 侧边栏配置（各分组目录下的_category_.json使侧边栏以可折叠分类呈现）。若你在浏览中发现问题或想补充某工具的示例，正确做法是：修改或补充对应工具 Python 模块中的描述与Annotated[...]参数注释，或向工具页的 examples 标记块内添加示例，然后重新运行生成器——切勿手工编辑自动生成区，否则会在 CI 的--check阶段产生漂移告警。

总结：这份工具参考目录是 Unity MCP 能力地图的入口。通过它，你可以按领域快速定位 48 个工具中的任意一个，理解"core 常驻、其他分组按需激活"的会话模型，并借助manage_tools、set_active_instance、batch_execute等元工具构建高效、可路由、可裁剪的 AI 驱动 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