# UE5.8 MCP Toolsets 完整分析

## 总体架构

所有Toolset都位于 `Engine\Plugins\Experimental\Toolsets`，共18个插件。它们通过 `ToolsetRegistry` 插件（核心基础设施）将 AI-callable 工具暴露给 MCP 系统（如 UnrealMCP）。

### 核心概念

- **UToolsetDefinition**: 所有工具集的基类，定义了一组 AI-callable 工具的接口
- **meta=(AICallable)**: UFUNCTION 标记，被 ToolsetRegistry 识别并暴露为 MCP 工具
- **UToolsetRegistry::RegisterToolsetClass**: 运行时注册工具集
- **FToolsetJsonConverter**: 自定义 JSON 序列化/反序列化器，用于非标准类型
- **UAgentSkill**: 为 AI 提供 prompt 上下文的辅助类
- **UToolCallAsyncResult** / **UToolCallAsyncResultString**: 长时间异步操作的结果包装

### 实现模式分类

| 模式 | 使用方 |
|------|--------|
| **UToolsetDefinition + 静态 AICallable 函数** | 几乎所有已实现的工具集 |
| **EditorSubsystem 生命周期管理** | AutomationTest, LiveCoding, SlateInspector, MCPClient |
| **多工具集模块注册** | GASToolsets (3个), NiagaraToolsets (4个) |
| **ON_SCOPE_EXIT 回滚保护** | GameFeaturesToolset |
| **纯 Python 实现** | SequencerAnimMixerToolset |
| **聚合器（描述符仅含依赖）** | AllToolsets |
| **空壳/占位符** | AIModuleToolset, AnimationAssistant, Conversation, StateTree |

---

## 一、已完整实现的 Toolset

### 1. AutomationTestToolset —— 自动化测试
- **功能**: 暴露 UE5 自动化测试框架，发现、列出、过滤、运行测试，获取结果
- **模块**: `AutomationTestToolset` + `AutomationTestToolsetTests`
- **架构**: `UAutomationTestToolset` (静态工具类) + `UAutomationTestToolsetSubsystem` (EditorSubsystem 管理 IAutomationControllerManager 生命周期)
- **AI 工具 (6个)**:
  - `DiscoverTests()` - 初始化 worker 发现 (异步)
  - `ListTests(NameFilter, TagFilter, Limit)` - 列出测试路径 JSON
  - `RunTests(TestNames)` - 运行指定测试 (异步)
  - `GetTestResults()` - 获取结果 JSON (状态/耗时/错误/警告)
  - `GetTestStatus()` - 轻量状态查询
  - `StopTests()` - 停止当前运行
- **关键实现**: 订阅 `OnTestsRefreshed` delegate，60秒发现超时，递归收集报告树叶子节点

### 2. DataflowAgent —— Dataflow 图编辑
- **功能**: 完整的 Dataflow 图（用于破坏/模拟，如 Geometry Collection）编辑，18个 MCP 工具
- **模块**: `DataflowAgent` (Editor)
- **架构**: `UDataflowAgentToolset` + `UDataflowGraphEditingSkill` (AgentSkill)
- **AI 工具 (17个)**:
  - **图**: `CreateGraph`, `GetGraphStructure`
  - **节点类型**: `ListNodeTypes`, `GetNodeTypeSchema`
  - **节点操作**: `AddNode`, `UpdateNode`, `GetNodeInfo`, `RepositionNode`, `RemoveNode`
  - **连接**: `ConnectNodePins`, `DisconnectNodePins`
  - **变量**: `ListVariables`, `AddVariable`, `RemoveVariable`, `SetVariable`
  - **注释**: `AddCommentBox`, `RemoveCommentBox`
- **关键实现**: `FScopedTransaction` 撤销支持，`FJsonObjectConverter::JsonValueToUProperty` 类型转换，变量类型系统支持基础类型/结构体/对象

### 3. GameFeaturesToolset —— 游戏功能插件管理
- **功能**: 列出、检查、创建 Game Feature 插件
- **模块**: `GameFeaturesToolset` (Editor)
- **架构**: `UGameFeaturesToolset` (静态工具类)
- **AI 工具 (5个)**:
  - `ListGameFeatures()` - 列出所有 GFP
  - `FindGameFeatureData(PluginName)` - 加载 UGameFeatureData 资产
  - `GetPluginName(Data)` - 获取插件名
  - `GetActions(Data)` - 获取所有 UGameFeatureAction
  - `CreateGameFeaturePlugin(PluginName, Description)` - 完整创建流程
- **关键实现**: `ON_SCOPE_EXIT` + `bCommitted` 标志的回滚模式（7步：目录→.uplugin→挂载→资产→保存），验证仅允许字母数字和下划线

### 4. GASToolsets —— Gameplay Ability System 工具集 (3合1)
- **功能**: GAS 运行时检测 + 属性集发现 + GameplayCue 完整生命周期管理
- **模块**: `GASToolsets` (Editor)，包含3个独立工具集
- **架构**: 模块注册三个 UToolsetDefinition 子类

#### 4a. UAbilitySystemInspectorToolset (4个工具)
- `GetAttributeValues(Actor)` - 获取所有属性的 Base/Current 值
- `GetActiveEffects(Actor)` - 活跃效果 (堆栈/持续时间/剩余/标签)
- `GetGrantedAbilities(Actor)` - 已授予的技能
- `GetActiveTags(Actor)` - 拥有的 GameplayTag

#### 4b. UAttributeSetToolset (2个工具)
- `FindAttributeSetClasses()` - 发现所有 AttributeSet 子类及其属性
- `ListAttributes(ClassName)` - 列出特定类的属性

#### 4c. UGameplayCueToolset (8个工具)
- `ListCues(ParentTag)` - 列出派生 Cue 标签
- `GetCueInfo(CueTag)` - 获取通知资产路径
- `ExecuteCueOnSelectedActor(...)` - 在选中 Actor 上触发 Cue
- `FindCueNotifyAssets(ParentTag)` - 查找通知资产
- `CreateCueNotifyAsset(...)` - 创建 Blueprint GCN 资产
- `AddCueTag(CueTag, Comment)` - 添加 Cue 标签到 INI
- `RemoveCueTag(CueTag)` - 移除标签
- `FindCueTagsWithoutNotifies()` - 查找缺少通知资产的标签

### 5. GameplayTagsToolset —— GameplayTag 管理
- **功能**: 完整的 GameplayTag 管理（增删改查 + 引用者搜索）
- **模块**: `GameplayTagsToolset` (Editor)
- **AI 工具 (6个)**:
  - `ListTags(ParentTag)` - BFS 遍历子标签
  - `GetTagInfo(TagName)` - 注释/来源/子标签
  - `AddTag`, `RemoveTag`, `RenameTag` - 需用户权限确认
  - `FindReferencersByTag(TagName)` - 资产引用搜索

### 6. LiveCodingToolset —— 热编译
- **功能**: 触发 Live Coding 编译，收集编译日志和错误
- **模块**: `LiveCodingToolset` (Editor)
- **AI 工具 (1个)**:
  - `CompileLiveCoding()` - 触发编译并返回结果 + MSVC 诊断
- **关键实现**: 线程安全日志捕获 (`FLiveCodingOutputCollector` 实现 `FOutputDevice`)，时间戳检测 UBT Log.txt，`#if WITH_LIVE_CODING` 守卫

### 7. MCPClientToolset —— MCP 客户端桥接
- **功能**: 将 Unreal Editor 连接到外部 MCP 服务器，将其工具呈现给 AI
- **模块**: `MCPClientToolset` (Editor)
- **架构**: `FMCPClientToolset` (FToolset 子类) + `UMCPClientToolsetSubsystem` + `UMCPToolsetSettings` (DeveloperSettings)
- **AI 工具**: 动态，取决于连接的外部 MCP 服务器
- **传输协议**:
  - Legacy SSE: GET `/sse` + POST `/message`
  - Streamable HTTP: 单一 POST 端点
  - OAuth 2.0 + PKCE: 完整 OAuth 流程
- **关键实现**: SPSC 队列跨线程流式传输，JSON-RPC 2.0 与 TPromise/TFuture，SHA-256 实现用于 PKCE

### 8. NiagaraToolsets —— Niagara 粒子系统 (4合1)
- **功能**: Niagara 系统/发射器/模块/渲染器的完整 CRUD + 运行时组件操作 + 编译诊断
- **模块**: `NiagaraToolsets` (Editor)
- **架构**: 基类 `UNiagaraToolset` + 4个专用子工具集 + 2个 JSON 转换器 + 1个 AgentSkill

#### 8a. UNiagaraToolset_Info
- `UEnum_Info` - 枚举查找
- `GetAssetDiscoveryInfo` - 资产发现路径
- `UAgentSkill_NiagaraBase` - AI prompt 增强

#### 8b. UNiagaraToolset_System (最大的工具集)
- **Schema**: GetSystemSchema, GetEmitterSchema, GetRendererSchema, GetDataInterfaceSchema, GetStackInputSchema, GetModuleSchema, GetDynamicInputSchema (+ 基于资产的变体)
- **Topology**: GetSystemTopology, GetScriptStackTopology, GetEmitterTopology, GetModuleTopology, GetStackInputTopology
- **Data**: GetUserVariables, GetSystemData, GetEmitterData, GetRendererData, GetStackInputData
- **Edit**: SetSystemData, SetEmitterData, SetRendererData, AddUserVariables, RemoveUserVariables, AddEmitter, RemoveEmitter, AddRenderer, RemoveRenderer, AddModule, RemoveModule, SetModuleEnabled, AddSetParametersModule, AddSetParameterEntry, RemoveSetParameterEntry, SetStackInputData
- **Diagnostics**: GetSystemCompileState, GetStackIssues, ApplyStackIssueFix (全部异步)

#### 8c. UNiagaraToolset_Component
- `SetSystem`, `GetUserVariables`, `SetVariable`, `GetVariable`

#### 8d. UNiagaraToolset_Blueprint
- `ConstructNiagaraBPWrapperFromSystem`, `ConstructNiagaraBPWrapperFromComponent`

### 9. PhysicsToolsets —— 物理资产
- **功能**: 创建和操作物理资产（碰撞体、形状、约束）
- **模块**: `PhysicsToolsets` (Editor)
- **架构**: `UPhysicsAssetToolset`
- **AI 工具 (14个)**:
  - **形状**: SetSphere, SetCapsule, SetBox, RemoveShape (upsert 模式)
  - **体 CRUD**: AddBody, RemoveBody, GetBodyNames
  - **体属性**: Get/SetBodyPhysicsMode, Get/SetBodyMassScale
  - **约束**: GetConstraints, AddConstraint, SetConstraintLimits, RemoveConstraint
  - **创建**: CreateFromMesh
- **关键实现**: 使用 Chaos 物理引擎类型，Modify() 撤销支持，RemoveBody 级联删除约束

### 10. SequencerAnimMixerToolset —— Sequencer 动画混合器
- **功能**: Sequencer 动画混合器轨道管理（唯一纯 Python 实现的工具集）
- **模块**: 无 C++ 模块，纯 Python (`Content/Python/`)
- **架构**: Python 类 `SequencerAnimMixerTools` 装饰为 `unreal.ToolsetDefinition`
- **AI 工具 (20个)**:
  - **Layers & Content (11个)**: get_mixer_layers, get_mixer_layer_count, add_mixer_layer, insert_mixer_layer, add_animation_to_mixer, add_child_track_to_layer, get/set_layer_name, get_layer_sections, get_layer_index, is_layer_empty
  - **Transitions (5个)**: get_transitions_for_section, get_transition_between, get_transition_info, change_transition_type, get_transition_name
  - **Decorations (5个)**: get_compatible_decorations, get_decorations, find_decoration, add_decoration, remove_decoration

### 11. SlateInspectorToolset —— UI 自动化（Playwright 风格）
- **功能**: Slate UI 检查和自动化，AI 可驱动编辑器界面的点击/输入/截图
- **模块**: `SlateInspectorToolset` (Editor) + `SlateInspectorToolsetTests`
- **架构**: `USlateInspectorToolset` + 3个支持系统:
  - **RefCache**: SWidget ↔ ref string 双向映射，按角色前缀计数器分配 (如 "b1", "b2")
  - **SnapshotRenderer**: DFS 遍历 widget 树，缩进文本快照，结构容器省略
  - **ObserverManager**: ~100ms 间隔连续子树观察，缓存快照
- **AI 工具 (14个)**:
  - **检查**: Snapshot, Observe/Unobserve/ListObservers, Screenshot, WaitFor
  - **交互**: Click (左右中/修饰符/双击), Hover, Type (逐字符+提交), PressKey (组合键), SelectOption (下拉选择), Drag (鼠标拖动), FillForm (批量表单)
  - **窗口**: Windows (列表/选择/关闭)
- **关键实现**: 使用直接 Slate 事件 API 而非 AutomationDriver（避免死锁），SelectOption 打开下拉→Tick两次→搜索文本→点击

### 12. UMGToolSet —— UMG Widget 蓝图
- **功能**: 通过反射创建和操作 UMG Widget Blueprint
- **模块**: `UMGToolSet` (EditorNoCommandlet)
- **架构**: `UUMGToolSet`
- **AI 工具 (11个)**:
  - **创建**: CreateWidgetBlueprint, AddWidget, SetNamedSlotContent
  - **查询**: GetWidgets (深度优先树), GetNamedSlots, ListWidgetBlueprints, ListWidgetClasses
  - **修改**: MoveWidget, RemoveWidget, RenameWidget, SetWidgetAsVariable, ReparentWidgetBlueprint
  - **生命周期**: CompileWidgetBlueprint
- **关键实现**: BindWidget 属性验证，ContentWidget 单子容器检测，GUID 管理，编译错误收集（图节点 + MessageLog），类路径解析

### 13. WorldConditionsToolset —— 世界条件检查
- **功能**: 获取世界条件查询和人可读描述
- **模块**: `WorldConditionsToolset` (Editor)
- **架构**: `UWorldConditionTools` + `FWorldConditionQueryConverter` (JSON 转换器)
- **AI 工具 (2个)**:
  - `GetQueryDescription(FWorldConditionQueryDefinition)` - 查询描述
  - `GetConditionDescription(FInstancedStruct)` - 条件描述

---

## 二、空壳/占位符 Toolset（模块存在但无功能）

### 14. AIModuleToolset
- 描述: "AI module toolset"
- 状态: `StartupModule()` 空，未注册任何工具
- 依赖: Core

### 15. AnimationAssistantToolset
- 描述: 意图为动画系统（Control Rig, Sequencer）
- 状态: 空实现，仅占位注释
- 依赖: ControlRig, LevelSequenceEditor, SequencerScripting

### 16. ConversationToolset
- 描述: 意图为 CommonConversation 对话树/编辑器工具
- 状态: 空实现
- 依赖: CommonConversation

### 17. StateTreeToolset
- 描述: "StateTree Inspection"
- 状态: 最简模块，仅日志类别和空 StartupModule
- 依赖: StateTree

---

## 三、聚合器

### 18. AllToolsets
- **类型**: "元插件" / 聚合器，无源代码
- **功能**: 依赖所有其他工具集，一次启用全部
- **架构**: 描述符仅含依赖列表 (14个插件)
- **Source 目录**: 不存在

---

## 四、启用工具集的建议配置

根据实际需求选择：

| 场景 | 需要的工具集 |
|------|-------------|
| C++ 编译辅助 | LiveCodingToolset |
| 自动化测试 | AutomationTestToolset |
| Gameplay Ability System | GASToolsets |
| Gameplay 标签管理 | GameplayTagsToolset |
| Niagara 粒子/特效 | NiagaraToolsets |
| 物理资产 | PhysicsToolsets |
| Dataflow/破坏系统 | DataflowAgent |
| UMG UI 构建 | UMGToolSet |
| Sequencer 动画混合 | SequencerAnimMixerToolset |
| 编辑器 UI 自动化 | SlateInspectorToolset |
| 外部 MCP 服务器 | MCPClientToolset |
| GameFeature 插件 | GameFeaturesToolset |
| 世界条件 | WorldConditionsToolset |
| （占位）AI 模块 | AIModuleToolset |
| （占位）动画辅助 | AnimationAssistantToolset |
| （占位）对话系统 | ConversationToolset |
| （占位）状态树 | StateTreeToolset |
| 全部启用 | AllToolsets |

---

## 五、统计总览

| 类别 | 数量 |
|------|------|
| 完全实现的功能工具集 | 13 (含子工具集) |
| 空壳占位符 | 4 |
| 聚合器 | 1 |
| **总 AI 工具数** | **~120+** |
| C++ 实现 | 16 |
| Python 实现 | 1 |
| 纯描述符 | 1 |