企业官网建设流程全解析

Unity MCP Tool Groups 与 manage_tools：按会话按需启用工具分组的完整实战指南

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

导读

MCP for Unity 内置了数十个工具（Tool），如果把全部工具一次性暴露给 LLM，会显著膨胀每次调用的 prompt 并干扰工具路由决策。为此，项目引入了Tool Groups（工具分组）机制：工具按功能划分到不同分组，默认仅启用core核心组，其余分组由 AI 助手或用户在会话中通过manage_tools元工具按需激活。本文以官方指南 tool-groups.md 为骨架，结合仓库中 manage_tools.py、tool_registry.py 与 McpToolsSection.cs 等源码实现，系统讲解分组的构成、manage_tools五种动作的用法、服务端与会话两层状态模型的差异，以及 Unity 编辑器侧开关 UI 与sync同步的底层原理。读完本文，你将能在自己的 prompt 中熟练启用、停用、查询和重置工具分组，理解为什么"默认只开 core"是 prompt 经济、路由清晰与包卫生三重考量的结果。

为什么需要工具分组：47 个工具全量暴露的问题

MCP for Unity 默认携带 47 个工具，但一次性全部暴露给 LLM 会带来两个直接后果：prompt 膨胀（每个可见工具都会为每次助手调用贡献 token）与路由决策稀释（LLM 在 47 个工具中做选择时更容易选错）。因此项目将工具按功能域划分为若干分组（Group），每个工具在注册时通过装饰器声明所属分组，默认情况下只有core分组处于启用状态，其他分组保持隐藏，直到需要时再显式激活。

这一设计在服务端注册逻辑中有明确体现。在 tools/init.py 中，register_all_tools的 docstring 写道：注册完成后，非默认分组会在服务端层面被禁用，使得新会话默认只看到 core 工具（外加始终可见的元工具）；客户端可以随时通过manage_tools激活更多分组。

# Server/src/services/tools/__init__.py（节选） def register_all_tools(mcp: FastMCP, *, project_scoped_tools: bool = True): """ Auto-discover and register all tools in the tools/ directory. After registration, non-default tool groups are disabled at the server level so that new sessions only see the *core* tools (plus always-visible meta-tools). Clients can activate additional groups at any time via ``manage_tools``. """

分组全景：默认状态与分组含义

官方指南给出了 9 个分组。对照当前仓库源码，tool_registry.py 中的TOOL_GROUPS字典是分组定义的唯一事实来源（当前为 10 个分组，除指南列出的 9 个外还包含asset_gen）：

DEFAULT_ENABLED_GROUPS在 tool_registry.py 中被定义为{"core"}，这既是服务端启动时的默认可见集，也是manage_tools的reset动作要恢复的目标状态。

从源码结构看，分组体系建立在 FastMCP 的标签（tag）机制之上：每个工具通过mcp_for_unity_tool装饰器注册时，若声明了分组，装饰器会为其合并一个group:<name>标签（见 tool_registry.py），这个标签正是后续"按分组启用/禁用可见性"的挂钩点。C# 侧同样存在对应分组声明，Unity 编辑器窗口的 Tools 面板就按Group属性对工具分组展示（core 优先、其余按字母序），见 McpToolsSection.cs 及其中定义的分组显示名映射（如vfx→ "VFX & Shaders"、probuilder→ "ProBuilder — Experimental"）。

使用 manage_tools 启用分组

启用某个分组很简单：直接在你的 prompt 中要求助手调用manage_tools元工具。例如：

Activate thevfxgroup so we can author shaders.

助手会对应调用：

manage_tools(action="activate", group="vfx")

激活成功后，该分组的工具会出现在下一次工具列表中，并在整个会话的剩余时间内保持可用。

manage_tools的服务端实现位于 manage_tools.py，其action参数是一个字面量枚举，共五种取值：

对于activate/deactivate，group参数必须提供，且会经过小写归一化与合法性校验——未知分组名会返回错误并列出合法分组（见 manage_tools.py）。激活动作本质上是调用ctx.enable_components(tags={"group:<name>"}, components={"tool"})，停用则调用对应的disable_components，随后返回该分组下的工具清单：

# Server/src/services/tools/manage_tools.py（activate 分支节选） if action == "activate": tag = f"group:{group}" await ctx.info(f"Activating tool group: {group}") await ctx.enable_components(tags={tag}, components={"tool"}) return { "activated": group, "tools": get_group_tool_names().get(group, []), "message": f"Group '{group}' is now visible. Its tools will appear in tool listings.", }

分组与工具的映射由get_group_tool_names()从全局注册表实时聚合得出（见 tool_registry.py），因此activate返回的tools列表始终与当前注册的工具一致。

列出当前可用分组

manage_tools(action="list_groups")

该动作遍历所有分组，返回每个分组的名称、描述、当前启用状态、默认启用标记以及工具名称清单和数量。状态判定逻辑位于 manage_tools.py：它会读取会话的可见性规则（visibility rules），凡是带有group:<name>前缀标签的规则按"后写优先"的原则覆盖分组状态；没有会话规则时则回落到默认启用集合。返回值中还附有一条说明：group=None的服务端元工具（如set_active_instance、manage_tools自身）不受分组体系约束、始终可见。

停用分组：让助手保持专注

manage_tools(action="deactivate", group="vfx")

停用适合在某个分组的工具开始干扰助手判断时使用。官方指南给出了一个非常具体的场景：manage_shader与manage_material都以各自方式作用于材质，若同时暴露，LLM 可能选错工具；停用当前不需要的那一组，能显著降低误用率。

从实现看，deactivate与activate对称：调用ctx.disable_components(tags={"group:<name>"}, components={"tool"})后，该分组工具即从会话可见列表中移除，并返回被隐藏的工具清单。

其他动作：sync 与 reset

sync —— 从 Unity 编辑器开关状态刷新

manage_tools(action="sync")

sync用于在通过Window > MCP for Unity > Tools面板切换过工具开关后，把编辑器的逐工具开关状态拉取到当前会话，使两侧可见性保持一致。其服务端实现sync_tool_visibility_from_unity位于 tools/init.py，工作流程如下：

1. 通过旧版 TCP 桥接向 Unity 发送get_tool_states命令；
2. 若 Unity 包版本过旧（返回 "unknown"/"unsupported command"），则返回带unsupported标记的错误，提示升级 MCPForUnity 包，并建议先用activate/deactivate手动切换；
3. 过滤出enabled == True的工具，调用PluginHub._sync_server_tool_visibility更新服务端可见性；
4. 若响应包含扩展元数据（is_built_in字段），还会顺带把非内置的自定义工具注册为全局工具；
5. 最后通过_notify_mcp_tool_list_changed向已连接的 MCP 会话广播tools/list_changed，并返回启用/禁用分组清单与工具数量统计。

这一同步机制主要用于 stdio 传输模式——该模式下 Unity 无法主动推送register_tools消息，因此需要 Python 服务端反向查询编辑器的工具状态来完成桥接。

reset —— 恢复默认

manage_tools(action="reset")

reset调用ctx.reset_visibility()将会话可见性恢复为服务端默认值（即仅core启用），并返回默认分组列表。适合在会话状态混乱、助手被过多工具干扰时一键"归零"。

服务端状态与会话状态：两层可见性模型

官方指南强调了一个容易混淆的关键区别：

• Unity 编辑器侧维护的是逐工具的开关 UI（Window > MCP for Unity > Tools），它控制的是服务端层面的可见性——即哪些工具被注册进服务器；
• manage_tools元工具控制的是每个会话的可见性——即使面对同一个服务端，不同 MCP 会话可以各自看到不同的分组集合。

sync正是这两层模型的调和者：它把编辑器的开关状态拉入当前会话。该设计得益于 FastMCP 3.x 原生的**按会话可见性（per-session visibility）**能力，manage_tools的 docstring 明确指出它"通过 FastMCP 3.x native per-session visibility 在所有传输（stdio、HTTP、SSE）上工作"（见 manage_tools.py）。

此外，HTTP 模式与 stdio 模式在启动行为上存在差异：在 tools/init.py 中可以看到，HTTP 模式启动时会主动禁用全部非默认分组（mcp.disable(tags={"group:<name>"}, ...)），使新会话以精简状态起步；而 stdio 模式由于旧版 TCP 桥接没有register_tools消息，启动时所有分组均保持启用，待 Unity 连接后再通过工具状态同步来收敛。

为什么这样设计：三大核心理由

官方指南总结了三点，均可在源码与实践中得到印证：

1. Prompt 经济（Prompt economy）：每个可见工具都会为每次助手调用增加 token 消耗。隐藏不用的工具，在规模化使用中就是实实在在的成本节省。register_all_tools中"默认只开 core"的设计正是这一原则的实现。

2. 路由清晰（Routing clarity）：LLM 在 47 个工具中做选择，误选率会高于在精简后的 30 个核心工具中做选择。分组把"可能误用"的工具（如作用于材质的manage_shader与manage_material）按需隔离，降低错误路由概率。

3. 包卫生（Package hygiene）：probuilder分组中的工具仅在安装com.unity.probuilder包后才可用，默认隐藏它们可以避免 LLM 在缺包环境下调用产生令人困惑的报错。同理，asset_gen分组依赖自带 API Key，按需启用也避免了无凭据调用。

更多入口与参考

• 官方工具参考文档 manage_tools 完整说明：包含全部参数与返回类型（action为五种字面量枚举、group为可选字符串）；
• 资源tool_groups（URI：mcpforunity://tool-groups）的实现见 tool_groups.py：它把分组目录暴露为可发现的资源，供 LLM 查询分组清单、默认启用集合与用法提示；
• 分组定义与工具注册装饰器的源码见 tool_registry.py，Unity 编辑器侧分组开关 UI 的控制器见 McpToolsSection.cs；
• 服务端注册与同步流程见 tools/init.py。

实际使用中，一个推荐的工作流是：会话开始时先list_groups查看当前可用分组，按任务性质activate所需分组（如做特效就开vfx、做 UI 就开ui、跑测试就开testing），任务结束或工具开始干扰判断时deactivate，最后用reset回归"仅 core"的干净起点。

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