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

### 功能维度总览
#### 核心编辑器操作

| Toolset                                                                        | 核心功能                                     |
| ------------------------------------------------------------------------------ | ---------------------------------------- |
| [[#11. SlateInspectorToolset —— UI 自动化（Playwright 风格）\|SlateInspectorToolset]] | Playwright 风格 UI 自动化：点击、输入、截图、widget 树快照 |
| [[#六、MCP 运行时实际检测\|EditorAppToolset]]                                           | 控制台变量、资产成像、Actor/资产选择、视口相机、内容浏览器导航       |
| [[#六、MCP 运行时实际检测\|LogsToolset]]                                                | 输出日志读取、日志类别详细级别控制                        |
| [[#六、MCP 运行时实际检测\|SceneTools]]                                                 | 关卡加载/放置/移除 Actor、相机、Outliner 文件夹管理       |
| [[#六、MCP 运行时实际检测\|PrimitiveTools]]                                             | 图元几何组件（球体、立方体等）添加                        |
| [[#6. LiveCodingToolset —— 热编译\|LiveCodingToolset]]                            | 编辑器运行时 C++ 热编译                           |

#### 资产与资源管理

| Toolset | 核心功能 |
|---------|----------|
| [[#六、MCP 运行时实际检测\|AssetTools]] | 资产搜索/加载/保存/删除/移动/复制，文件读写 |
| [[#六、MCP 运行时实际检测\|ObjectTools]] | UObject / UClass 属性检查/修改，子类发现 |
| [[#六、MCP 运行时实际检测\|BlueprintTools]] | Blueprint 蓝图操作 |
| [[#六、MCP 运行时实际检测\|MaterialTools]] | Material 创建/编辑及表达式图 |
| [[#六、MCP 运行时实际检测\|MaterialInstanceTools]] | MaterialInstanceConstant 创建/修改 |
| [[#六、MCP 运行时实际检测\|TextureTools]] | Texture 资产操作 |
| [[#六、MCP 运行时实际检测\|StaticMeshTools]] | 静态网格检查与修改 |
| [[#六、MCP 运行时实际检测\|SkeletalMeshTools]] | 骨骼网格检查与修改（网格/材质/骨骼/插槽） |
| [[#六、MCP 运行时实际检测\|CurveTableTools]] | CurveTable 创建/编辑 |
| [[#六、MCP 运行时实际检测\|DataTableTools]] | DataTable 创建/编辑 |
| [[#六、MCP 运行时实际检测\|DataAssetTools]] | DataAsset 操作 |
| [[#六、MCP 运行时实际检测\|StringTableTools]] | StringTable 创建/编辑 |
| [[#12. UMGToolSet —— UMG Widget 蓝图\|UMGToolSet]] | UMG Widget Blueprint 创建/修改/编译 |

#### Gameplay

| Toolset | 核心功能 |
|---------|----------|
| [[#4. GASToolsets —— Gameplay Ability System 工具集 (3合1)\|GASToolsets]] | GAS 运行时检测 + AttributeSet 发现 + GameplayCue 管理 |
| [[#5. GameplayTagsToolset —— GameplayTag 管理\|GameplayTagsToolset]] | GameplayTag 增删改查 + 引用者搜索 |
| [[#13. WorldConditionsToolset —— 世界条件检查\|WorldConditionsToolset]] | 世界条件查询/条件描述 |
| [[#六、MCP 运行时实际检测\|ActorTools]] | Actor 变换/标签/父子关系/组件检查修改 |
| [[#9. PhysicsToolsets —— 物理资产\|PhysicsToolsets]] | 物理资产：碰撞体、形状、约束创建/编辑 |
| [[#16. ConversationToolset\|ConversationToolset]] | 对话图资产检查（Python 实现） |
| [[#17. StateTreeToolset\|StateTreeToolset]] | StateTree 结构检查与导航（Python 实现） |

#### Sequence

| Toolset | 核心功能 |
|---------|----------|
| [[#10. SequencerAnimMixerToolset —— Sequencer 动画混合器\|SequencerAnimMixerToolset]] | Sequencer 动画混合器：层/动画内容/过渡/装饰 |

#### 动画系统

| Toolset | 核心功能 |
|---------|----------|
| [[#15. AnimationAssistantToolset\|AnimationAssistantToolset]] | Control Rig + Sequencer 全套动画工具（超大 Python 实现，8 类 100+ 工具） |

#### 特效系统 (Niagara)

| Toolset | 核心功能 |
|---------|----------|
| [[#8. NiagaraToolsets —— Niagara 粒子系统 (4合1)\|NiagaraToolsets]] | Niagara 系统/发射器/模块/渲染器 CRUD + 编译诊断 + 组件操作 |

#### PCG

| Toolset | 核心功能 |
|---------|----------|
| [[#2. DataflowAgent —— Dataflow 图编辑\|DataflowAgent]] | Dataflow 图编辑（Geometry Collection 破坏系统） |

#### 测试与配置

| Toolset | 核心功能 |
|---------|----------|
| [[#1. AutomationTestToolset —— 自动化测试\|AutomationTestToolset]] | 自动化测试框架：发现、列出、运行、结果获取 |

#### 插件与功能管理

| Toolset | 核心功能 |
|---------|----------|
| [[#3. GameFeaturesToolset —— 游戏功能插件管理\|GameFeaturesToolset]] | GameFeature 插件列出/检查/创建 |
| [[#7. MCPClientToolset —— MCP 客户端桥接\|MCPClientToolset]] | 外部 MCP 服务器桥接（SSE/StreamableHTTP/OAuth） |

#### 其他工具

| Toolset | 核心功能 |
|---------|----------|
| [[#六、MCP 运行时实际检测\|ProgrammaticToolset]] | 沙盒 Python 脚本执行，可编排调用其他工具 |
| [[#六、MCP 运行时实际检测\|AgentSkillToolset]] | Agent Skill 的列表/读取/创建/更新 |
| [[#14. AIModuleToolset\|AIModuleToolset]] | 行为树检查与导航（Python 实现） |


> 以上 3 个工具集均有 Python 实现，C++ 模块仅负责加载插件，实际逻辑和工具注册均在 Python 侧完成。

### MCP 服务器连接配置
```json
{
  "mcpServers": {
    "ue-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

### MCP 核心工具 (3个)

| 工具 | 功能 |
|------|------|
| `list_toolsets` | 列出所有可用工具集及其描述 |
| `describe_toolset` | 获取工具集的详细信息（工具名、描述、输入 schema）|
| `load_toolset` | 加载工具集，将其工具注册为原生 MCP 工具（下一轮生效）|

### 核心概念

- **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 实现 (C++ 模块仅作加载器)** | AIModuleToolset, AnimationAssistant, ConversationToolset, StateTreeToolset |
| **Python + C++ 混合实现** | SequencerAnimMixerToolset (仅 Python), NiagaraToolsets (C++ + Python 注册)

---

## 一、已完整实现的 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)` - 条件描述

---

## 二、Python 实现的 Toolset（C++ 模块仅为加载器）

### 14. AIModuleToolset —— 行为树 AI 工具
- **功能**: 行为树检查和导航（Python 实现）
- **C++ 模块**: `AIModuleToolset` (Editor, PostEngineInit) — 空 `StartupModule`，仅负责加载插件
- **Python 实现**: `Content/Python/aimodule_toolset/toolsets/behavior_tree.py`
- **注册方式**: `Registration([BehaviorTreeTools])`
- **AI 工具 (7个)**:
  - `get_blackboard(behavior_tree)` - 获取 BlackboardData 资产
  - `get_root_decorators(behavior_tree)` - 根级 BTDecorator
  - `list_nodes(behavior_tree)` - DFS 遍历所有 BTNode
  - `get_node_depth(behavior_tree, node_index)` - 节点在树中的深度
  - `get_node_depths(behavior_tree)` - 所有节点深度
  - `get_children(composite)` - Composite 节点的直接子节点
  - `get_subtree(node)` - RunBehavior 任务引用的子 BT

### 15. AnimationAssistantToolset —— 动画与 Sequencer 工具集（超大型 Python 实现）
- **功能**: 最庞大的工具集，覆盖 Control Rig、Sequencer、关键帧、大纲、条件、自定义绑定、导入导出
- **C++ 模块**: `AnimationAssistantToolset` (Editor, PostEngineInit) — 空 `StartupModule`
- **Python 实现**: `Content/Python/animation_toolset/toolsets/` (21 个文件，~5000+ 行代码)
- **注册方式**: `init_unreal.py` 直接调用 `register_toolset_class()` 注册 8 个类
- **8 个子工具集**:

| 类 | 领域 | 工具数 |
|----|------|--------|
| `ControlRigTools` | 层级管理、图操作、节点/Pin 管理、变量 | 30+ |
| `SequencerTools` | Level Sequence 生命周期、回放、绑定、轨道、段、文件夹、复制粘贴、标签、烘焙 | 70+ |
| `SequencerKeyframingTools` | 关键帧增删、float/bool/int/string 通道、插值、默认值 | |
| `SequencerControlRigTools` | Sequencer 中 CR 控制值读写、关键帧、烘焙、空间切换 | |
| `SequencerOutlinerTools` | 大纲树检查、选择、折叠/展开、静音/独奏/锁定 | |
| `SequencerConditionTools` | 轨道/段运行时条件（平台/蓝图/组条件） | |
| `SequencerCustomBindingTools` | 转换 possessable/spawnable/自定义绑定，修改 Actor 模板类 | |
| `SequencerImportExportTools` | FBX 导入/导出、AnimSequence 导出 | |

### 16. ConversationToolset —— 对话图检查
- **功能**: 检查 Conversation Graph (UConversationDatabase) 对话资产（Python 实现）
- **C++ 模块**: `ConversationToolset` (Editor, PostEngineInit) — 空 `StartupModule`
- **Python 实现**: `Content/Python/conversation_toolset/toolsets/conversation.py`
- **注册方式**: `Registration([ConversationTools])`
- **AI 工具 (7个)**:
  - `list_entry_points(conversation)` - 入口点列表
  - `list_speakers(conversation)` - 说话者/参与者信息
  - `get_all_nodes(conversation)` - 所有可达 ConversationNode
  - `get_node_guids(conversation)` - 所有节点 GUID
  - `get_node_by_guid(conversation, guid)` - 按 GUID 查找节点
  - `get_node_connections(node)` - 输出连接 GUID (需要 ConversationNodeWithLinks)
  - `get_sub_nodes(node)` - 任务节点的子节点

### 17. StateTreeToolset —— 状态树检查
- **功能**: StateTree 状态树结构检查和导航（Python 实现）
- **C++ 模块**: `StateTreeToolset` (Editor, PostEngineInit) — 空 `StartupModule`
- **Python 实现**: `Content/Python/state_tree_toolset/toolsets/state_tree.py`
- **注册方式**: `Registration([StateTreeTools])`
- **AI 工具 (8个)**:
  - `get_editor_data(state_tree)` - 获取 StateTreeEditorData
  - `get_root_states(state_tree)` - 顶级状态
  - `get_children(state)` - 状态子节点
  - `get_tasks(state)` - 状态上的任务
  - `get_enter_conditions(state)` - 进入条件
  - `get_transitions(state)` - 状态转换
  - `get_global_tasks(state_tree)` - 全局任务
  - `get_evaluators(state_tree)` - 全局求值器
  - `get_node_description(state_tree, node)` - 节点可读描述

---

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

根据实际需求选择：

| 场景                      | 需要的工具集                    |
| ----------------------- | ------------------------- |
| 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           |
| Sequencer + Control Rig | AnimationAssistantToolset |
| 对话系统                    | ConversationToolset       |
| 状态树                     | StateTreeToolset          |

---
# 第三方 MCP 比较

## 概述

调研了 8 个第三方 Unreal MCP 开源仓库，均为 GitHub 社区项目。它们与官方 UE5.8 ToolsetRegistry 在架构理念、传输协议和实现方式上有本质差异。

## 各仓库速览

| 仓库 | 连接方式 | 需要插件? | 传输 | 语言 | 工具数 | UE 版本 | 核心定位 |
|------|---------|----------|------|------|--------|---------|---------|
| appleweed_UnrealMCPBridge | TCP | C++ 插件 | TCP :9000 | Python | ~35 | 5.5+ | 编辑器自动化 + Insights 性能追踪 |
| ChiR24_Unreal_mcp | HTTP 原生 / TCP | C++ 插件 (超大) | HTTP :3000 或 TCP :8091 | TS 或纯 C++ | 23 父工具(数百子动作) | 5.0-5.8 | **第三方中最全面** |
| chongdashu_unreal-mcp | TCP | C++ 插件 | TCP :55557 | Python | ~25 | 5.5+ | Blueprint + Actor 开发 |
| mcpanalyzer_UnrealMCP | **不连接 UE** | **无** | stdio | Python | 41 | 不限 | C++ 源码静态分析 |
| prajwalshettydev_UnrealGenAISupport | TCP | C++ 插件 | TCP :9877 | Python | ~25 | 5.4-5.7+ | LLM API 集成(主) + MCP(辅) |
| runeape-sats_unreal-mcp | HTTP | **无** (用 Remote Control API) | HTTP :30010 | Python | ~15 | 5.3 | 场景搭建 + TLA+ 形式化验证 |
| runreal_unreal-mcp | UDP + TCP | **无** (用 Python Remote Exec) | UDP 多播 + TCP | TypeScript | 19 | 5.4+ | 最快迭代，零插件 |
| winyunq_UnrealMotionGraphicsMCP | TCP 异步 | C++ UMG 插件 | TCP 异步 | Python | ~30 | 5.6+ | UMG / Material / Sequencer 设计 |

## 架构差异

### 第三方主流模式：外部进程 + TCP 桥接
```
Claude Desktop → Python MCP Server (FastMCP) → TCP Socket → C++ Plugin (UE 内部)
```

6/8 的仓库都采用此模式（appleweed、ChiR24 (Option B)、chongdashu、prajwalshettydev、winyunq）。外部进程运行 MCP 协议，通过自定义 JSON 帧协议将命令转发到 UE 内部的 C++ TCP 服务器。
- 特例
	- **runeape-sats**：直接 HTTP 调用 UE 内置的 Remote Control API (`/remote/object/call`)，无需任何 C++ 代码
	- **runreal**：通过 UE 内置的 Python Remote Execution (UDP 发现 + TCP 命令)，所有工具本质是生成 Python 代码字符串在编辑器内执行
	- **mcpanalyzer**：完全不连接运行中的编辑器，静态索引 C++ 源代码文件，提供 `ue_search_class`、`ue_parse_ufunction`、`ue_compile_project` 等代码分析工具

### 官方模式：引擎内原生 HTTP
```
Claude Desktop → JSON-RPC over HTTP/SSE → UE 引擎内部 MCP Server (C++)
```
TLS/SSE、会话管理、反射 Schema 生成全部在引擎进程内完成，无外部依赖。

## 架构对比表

| 维度 | 第三方主流方案 | 官方 UE5.8 ToolsetRegistry |
|------|--------------|--------------------------|
| **运行位置** | 外部 Python/Node.js 进程 + C++ 插件 | 所有逻辑在引擎进程内 |
| **传输协议** | 自定义 JSON-over-TCP（各仓库自造轮子） | JSON-RPC 2.0 over Streamable HTTP (MCP 标准) |
| **类型安全** | Python type hints 或 Zod，手动校验 | C++ USTRUCT 反射自动生成 JSON Schema |
| **工具发现** | 装饰器或硬编码注册 | `UToolsetRegistry` 自动扫描注册 |
| **会话管理** | 单会话为主（仅 ChiR24 支持多会话） | 原生多会话 + SSE 流式推送 |
| **错误处理** | 各仓库不一致 (`status:error` vs `success:false`) | 标准 JSON-RPC 错误码 |
| **流式传输** | 无（全为请求-响应模式） | SSE 实时推送长时间操作进度 |
| **生命周期** | 外部进程需独立启动/停止 | 编辑器启动即自动运行 |

## 技术优势对比
-  第三方方案优势
	1. **开发速度快**：Python 工具可在数分钟内添加，无需 C++ 编译
	2. **零插件可选**：runreal 和 runeape-sats 只需启用内置引擎插件即可工作
	3. **Python 生态**：可引入任意 Python 库（requests、mss 截图等）
	4. **独立演化**：MCP Server 和 UE 插件可独立更新，不受引擎版本约束
	5. **入门门槛低**：Python/TypeScript 开发者即可贡献，无需 C++ 知识
- 第三方方案劣势
	1. **协议脆弱**：每个仓库都自己实现 TCP 帧协议，缓冲区处理和断线重连无标准
	2. **双进程管理**：外部进程 + UE 插件需要同时监控，调试困难
	3. **无类型安全**：参数以原始字典/字符串传递，手动校验，Schema 漂移风险高
	4. **无标准工具发现**：工具列表硬编码在源码中，运行时无动态注册机制
	5. **线程安全脆弱**：多数通过 `register_slate_post_tick_callback` 切回主线程
-  官方方案优势
	1. **工程级集成**：引擎内运行，零 IPC 开销，无外部进程管理
	2. **反射驱动类型安全**：C++ USTRUCT 自动生成 JSON Schema，始终与实现同步
	3. **插件化可扩展**：第三方可通过发布 UE 插件注册自定义 Toolset
	4. **原生多会话**：SSE 流式推送 + Session ID 管理，支持并发 AI 客户端
	5. **标准协议**：符合 MCP 规范的 JSON-RPC 2.0，任何 MCP 客户端可直接连接
- 官方方案劣势
	1. **高入门门槛**：需要 C++ 知识创建新 Toolset
	2. **编译周期长**：任何工具变更需要 C++ 重编译
	3. **生态受限**：不能直接使用 Python 第三方库
	4. **版本锁定**：紧耦合引擎版本

---

## 功能缺口分析：第三方有而官方没有 / 官方有而第三方没有
### 第三方 MCP 有，官方 UE5.8 MCP 没有

| 功能                       | 来源仓库                 | 说明                                                                                     |
| ------------------------ | -------------------- | -------------------------------------------------------------------------------------- |
| **C++ 源码静态分析**           | mcpanalyzer          | 搜索 UCLASS/USTRUCT/UFUNCTION、反射解析、AST 分析、Build 编译、最佳实践检查——完全不需要运行编辑器                    |
| **Unreal Insights 性能追踪** | appleweed            | 启动/停止/分析 Unreal Insights trace、CSV profiling                                           |
| **战斗/背包/网络/AI 系统**       | ChiR24               | `manage_combat`、`manage_inventory`、`manage_networking`、`manage_ai`——GaAS 层面的完整系统管理     |
| **PCG 管理**               | ChiR24               | `manage_pcg`——程序化生成工具                                                                  |
| **音频管理**                 | ChiR24               | `manage_audio`——SoundCue/Metasound 操作                                                  |
| **HLSL 代码编辑**            | winyunq              | `hlsl_set_target`、`hlsl_get`、`hlsl_set`、`hlsl_compile`——直接在 MCP 中编辑 Material 的 HLSL 节点 |
| **HTML 转 UMG**           | winyunq              | 将 HTML 结构自动转换为 UMG Widget 树                                                            |
| **LLM API 内置集成**         | prajwalshettydev     | 在 UE 编辑器内直接调用 OpenAI/Anthropic/DeepSeek API（主功能，MCP 为副）                                |
| **TLA+ 形式化验证**           | runeape-sats         | 城堡搭建工作流的 TLA+ 形式化规格                                                                    |
| **OS 级截图**               | prajwalshettydev     | 使用 Python `mss` 库截取整个屏幕，用于 AI 看图理解编辑器状态                                                |
| **Blueprint 图节点级编辑**     | appleweed/chongdashu | 获取 Blueprint 节点 ID、Pin 详情、连接 Pin、添加事件/函数节点——粒度比官方 BlueprintTools 更细                    |
| **Arbitrary Python 执行**  | runreal              | `editor_run_python`——在编辑器内执行任意 Python 代码，给了 AI 无限的引擎 API 访问能力                          |
| **系统控制**                 | ChiR24               | `system_control`——编辑器进程层面的控制（重启、退出等）                                                   |
| **环境搭建**                 | ChiR24               | `build_environment`——构建环境管理                                                            |

### 官方 UE5.8 MCP 有，第三方 MCP 没有

| 功能 | 来源 Toolset | 说明 |
|------|-------------|------|
| **Slate UI 自动化 (Playwright 风格)** | SlateInspectorToolset | 快照、观察者、截图、点击/拖拽/Hover/输入/表单填充——以 AI Agent 视角驱动编辑器 UI |
| **Dataflow 图编辑** | DataflowAgent | Geometry Collection 破坏系统的节点图完整编辑（17 个工具） |
| **GAS 运行时检测** | GASToolsets | 实时检测 AbilitySystemComponent 的属性值、活跃效果、技能、标签 |
| **GameplayCue 管理** | GASToolsets | GameplayCue 标签增删、通知资产创建、缺少通知资产的标签发现 |
| **GameplayTag 管理** | GameplayTagsToolset | 完整的增删改查 + 资产引用者搜索 |
| **Live Coding 热编译** | LiveCodingToolset | 触发编译 + 收集 MSVC 诊断 + 线程安全日志捕获 |
| **MCP 客户端桥接** | MCPClientToolset | 接入外部 MCP 服务器（SSE/StreamableHTTP/OAuth+PKCE），聚合第三方工具 |
| **GameFeature 插件创建** | GameFeaturesToolset | 完整的 GFP 创建流程（目录→.uplugin→挂载→资产→保存），带 ON_SCOPE_EXIT 回滚 |
| **WorldConditions 检查** | WorldConditionsToolset | 查询/条件描述 + 自定义 JSON 转换器 |
| **Conversation Graph 检查** | ConversationToolset | 对话资产节点遍历、入口点、说话者、GUID 查找 |
| **StateTree 检查** | StateTreeToolset | 状态树结构导航、任务/条件/转换/求值器查询 |
| **CurveTable / DataTable / StringTable** | Core Python 模块 | 专门的表格数据资产创建/编辑工具 |
| **ProgrammaticToolset** | Core Python 模块 | 沙盒 Python 脚本编排——在同一脚本中调用多个 MCP 工具并编写自定义逻辑 |
| **AgentSkill 系统** | AgentSkillToolset | Agent Skill 的列表/读取/创建/更新——AI Agent 的 prompt 上下文管理 |
| **EditorAppToolset** | Core Python 模块 | 控制台变量管理、资产缩略图成像、内容浏览器导航 |
| **LogsToolset** | Core Python 模块 | 输出日志类别动态控制、日志读取 |
| **C++ JSON Schema 自动生成** | 架构层 | 从 USTRUCT 反射自动生成工具参数 Schema，永远与实现同步 |
| **原生多会话 SSE 流式推送** | 架构层 | 支持多个 AI 客户端同时连接，长时间操作进度实时推送 |
| **插件化 Toolset 扩展** | 架构层 | 第三方只需发布 UE 插件并注册 UToolsetDefinition，无需适配任何外部进程 |
| **标准 JSON-RPC 2.0** | 架构层 | 完全符合 MCP 协议规范，任何 MCP 客户端可直连 |

### 差距总结

| 对比维度 | 第三方领先 | 官方领先 |
|---------|-----------|---------|
| **代码分析** | mcpanalyzer 独有 | — |
| **性能分析** | appleweed 的 Insights 集成 | — |
| **Gameplay 高级系统** | ChiR24 的 combat/inventory/AI/PCG/audio | GAS 运行时检测 + GameplayCue 官方更深入 |
| **UI 自动化** | — | SlateInspectorToolset 独有 |
| **资产表格** | — | CurveTable/DataTable/StringTable 独有 |
| **容器/编排** | runreal 的任意 Python 执行 | ProgrammaticToolset 沙盒编排 |
| **工程架构** | — | 反射 Schema、多会话 SSE、插件化扩展、标准协议 |
| **部署复杂度** | runreal/runeape-sats 零 C++ 即可用 | 需引擎编译，但启动即运行 |

**核心结论**：第三方 MCP 在**广度**上占优（覆盖了更多非编辑器核心的领域），官方 MCP 在**深度和工程品质**上占优（单个领域的工具细粒度、类型安全、协议标准、可扩展性）。两者并非替代关系——各有独特优势，可以互补使用。

---

# UAgentSkill 子系统分析

## 概述

`UAgentSkill` 是 UE5.8 ToolsetRegistry 中的一个子系统，用于为 AI Agent 提供**上下文和提示词增强**（prompt enrichment），而非功能性的执行工具。它类似于 Claude Code 的 Skill 系统——两者都在 prompt 层面为 AI 提供领域知识和操作指引。

核心文件位置：
- 头文件：`ToolsetRegistry\Public\ToolsetRegistry\AgentSkill.h`
- 实现：`ToolsetRegistry\Private\ToolsetRegistry\AgentSkill.cpp`
- 测试：`ToolsetRegistry\Private\Tests\AgentSkillsTest.cpp` + `AgentSkillsTest.h`
- Niagara 示例：`NiagaraToolsets\Private\NiagaraToolset_Info.h` + `.cpp`

## 类体系

```
UObject
├── UAgentSkill                          (AgentSkill.h)
│   ├── UAgentSkillBestPractices         (AgentSkill.h)  — 追加技能编写最佳实践
│   ├── UAgentSkill_NiagaraBase          (NiagaraToolset_Info.h) — 追加 Niagara 概述 + 资产发现
│   └── UAgentSkillCustomPrompt          (AgentSkillsTest.h) — 测试用子类
│
├── UToolsetDefinition
│   └── UAgentSkillToolset               (AgentSkill.h)  — MCP CRUD 工具暴露
│
└── FAgentSkillDetails                   (AgentSkill.h)  — DTO 数据结构
```

## 核心数据结构

### FAgentSkillDetails（返回给 AI 的 DTO）

```cpp
USTRUCT(BlueprintType)
struct FAgentSkillDetails
{
    TArray<FString> Toolsets;   // 技能依赖的 toolset 完整名称
    FString Instructions;       // 经过 GeneratePrompt 处理后的最终指令
};
```

### UAgentSkill 关键属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `Description` | `FString` | 简短描述，用于 ListSkills 的摘要 |
| `Instructions` | `FString` | 详细指令（原始），会被 GeneratePrompt 处理 |
| `Toolsets` | `TArray<TSoftClassPtr<UToolsetDefinition>>` | 依赖的工具集软引用 |

## 关键方法解析

### GetDetails() — `AgentSkill.cpp:21`

```cpp
FAgentSkillDetails UAgentSkill::GetDetails() const
{
    FAgentSkillDetails SkillDetails;
    SkillDetails.Instructions = GeneratePrompt(Instructions);  // 🔑 调用可重写的生成方法
    for (const auto& Toolset : Toolsets)
    {
        UClass* ToolsetClass = Toolset.Get();
        FString ToolsetName = FFunctionLibraryToolset::GetToolsetClassName(ToolsetClass);
        SkillDetails.Toolsets.Add(ToolsetName);  // 转换为字符串形式
    }
    return SkillDetails;
}
```

**关键点**：`GetDetails` 不是简单返回存储的值，而是通过 `GeneratePrompt(Instructions)` 对指令进行**动态处理**后才返回。这允许子类在运行时注入额外上下文。

### GeneratePrompt() — `AgentSkill.h:47`

```cpp
UFUNCTION(BlueprintNativeEvent)
FString GeneratePrompt(const FString& InitialInstructions) const;

// 默认实现：原样返回
virtual FString GeneratePrompt_Implementation(const FString& InitialInstructions) const
{
    return InitialInstructions;
}
```

这是一个 **Template Method 模式**的核心。基类提供默认的直通实现，子类通过重写来丰富 prompt。

### 子类 Prompt 生成对比

**UAgentSkillBestPractices** — 追加编写规范 (`AgentSkill.cpp:42`)：
```cpp
return InitialInstructions + TEXT(
    "- Skills should focus on providing essential info the LLM doesn't know...\n"
    "- Skills should be written like a brief to a colleague...\n"
    "- Shorter skills are more context efficient...\n"
    // ... 共6条最佳实践
);
```

**UAgentSkill_NiagaraBase** — 前置 Niagara 知识 (`NiagaraToolset_Info.cpp:128`)：
```cpp
TStringBuilder<16384> PromptBuilder;
PromptBuilder << NiagaraOverview;  // ~100 行的 Niagara 概念概述

// 遍历依赖的 toolsets，调用 GetToolsetPrompt() 获取其专属提示
for (const auto& SoftToolset : Toolsets) {
    if (UFunction* PromptFunction = ToolsetClass->FindFunctionByName(TEXT("GetToolsetPrompt")))
        PromptBuilder << /* result */;
}

PromptBuilder << InitialInstructions;  // 原始指令放在后面

// 附加资产发现信息
for (const auto& Group : AssetDiscoveryGroups)
    PromptBuilder << Group.Description << Group.Paths;
```

**UAgentSkillCustomPrompt**（测试）— 后缀追加 (`AgentSkillsTest.h:17`)：
```cpp
return InitialInstructions + FString(TEXT("BishBosh"));  // 测试验证用
```

## UAgentSkillToolset — MCP CRUD 操作

这是暴露给 AI 的 4 个工具：

### ListSkills() — `AgentSkill.cpp:53`
- 通过 `UToolsetLibrary::GetDerivedClasses(UAgentSkill::StaticClass())` 发现所有派生类（包括 C++ 和 Blueprint）
- 加载每个类的 CDO，收集 `Description`
- 返回 `TMap<FString, FString>` — **路径 → 描述**

### GetSkills(SkillPaths) — `AgentSkill.cpp:76`
- 按路径列表批量加载 UAgentSkill 类
- 调用 `GetDetails()` 获取经过 prompt 生成的详细信息
- 返回 `TMap<FString, FAgentSkillDetails>` — **路径 → 详情**

### CreateSkill(...) — `AgentSkill.cpp:94`
完整流程：
1. 校验 `FolderPath` 和 `AssetName`
2. 使用 `UBlueprintFactory` 以 `UAgentSkill` 为父类创建 Blueprint 资产
3. 调用 `UpdateSkill` 设置描述、指令和工具集依赖
4. 如果 UpdateSkill 失败，回滚删除已创建的 Blueprint
5. 返回生成的类路径（如 `/Game/Skills/MySkill.MySkill_C`）

### UpdateSkill(...) — `AgentSkill.cpp:139`
1. 加载并校验类必须是 `UAgentSkill` 子类
2. 通过 `ToolsetRegistrySubsystem->ToolsetRegistry.Find(ToolsetName)` 校验所有依赖的 toolset 名称有效
3. 更新 `Description`、`Instructions`、`Toolsets`
4. `Modify()` + `MarkPackageDirty()` 标记保存

## 测试覆盖 — `AgentSkillsTest.cpp`

| 测试用例 | 验证内容 |
|---------|---------|
| Can create skills | 创建后 CDO 的 Description/Instructions/Toolsets 正确 |
| Won't create when given bad folder paths | 空路径、空名称、不存在路径均返回空 |
| Can update skills | 更新后 Description/Instructions/Toolsets 正确覆盖 |
| Won't update when class does not exist | 不存在路径返回 false |
| Won't update when class is not a skill | 非 UAgentSkill 类返回 false |
| Won't update when given bad tools | 无效 toolset 名称返回 false，原有属性不变（原子性） |
| List skill summaries | 同时发现 C++ 原生和 BP 派生的 AgentSkill |
| Get skill details | GetDetails 返回内容与原始属性一致 |
| Can't load non-existant skills | 不存在路径返回空 map |
| Can customize prompt generation | 子类重写 GeneratePrompt 确实生效 |

## 与 ToolsetRegistry 生态的关系

```
                   ToolsetRegistry (核心注册表)
                        │
          ┌─────────────┼─────────────┐
          │             │             │
   UToolsetDefinition  UAgentSkill   FToolset (运行时)
   (功能工具集基类)     (上下文/技能)   (工具集实例)
          │                             │
   Static AICallable ──────────→ 由 FToolset 包装注册
   UFUNCTIONs                    到 ToolsetRegistry
          │
   UAgentSkill.Toolsets ──→ 声明依赖关系，告诉系统
   (TSoftClassPtr)           加载 skill 时需同时加载哪些 toolset
```

**核心区别**：
- `UToolsetDefinition` 提供**可调用的工具函数**（AICallable UFUNCTIONs）
- `UAgentSkill` 提供**给 AI 的上下文知识**（prompt 增强），并声明"使用我时需要哪些 toolset"
- 加载一个 skill 时，系统会根据其 `Toolsets` 字段自动加载对应的 functional toolsets

## 设计模式总结

| 模式 | 应用 |
|------|------|
| **Template Method** | `GeneratePrompt()` — 基类定义框架，子类丰富内容 |
| **CDO as Template** | Skill 的 Description/Instructions 存在 CDO 中，运行时通过 GetDefaultObject 读取 |
| **Soft Reference** | `TSoftClassPtr<UToolsetDefinition>` 避免硬加载依赖 |
| **Factory Pattern** | `CreateSkill` 内部使用 `UBlueprintFactory` |
| **DTO** | `FAgentSkillDetails` 作为 AI ↔ 引擎的数据传输对象 |
| **Atomic Update** | `UpdateSkill` 先校验所有 toolset 名称再修改，失败时原有属性不变 |

## 与 Claude Code Skill 系统的类比

| 维度 | UE5.8 UAgentSkill | Claude Code Skill |
|------|-------------------|-------------------|
| **存储方式** | Blueprint 资产 / CDO 属性 | Markdown 文件 |
| **加载机制** | `GetDerivedClasses` + `GetDefaultObject` | 文件系统读取 |
| **prompt 生成** | `GeneratePrompt()` 虚函数动态生成 | 静态 Markdown 内容 |
| **依赖声明** | `Toolsets` 属性显式声明 | 无（skill 间独立） |
| **创建方式** | AI 通过 MCP 工具调用 `CreateSkill` | 文件写入 |
| **分发** | 作为 UE 插件内容分发 | 作为文件/插件分发 |
| **核心目的** | 为 AI 提供领域上下文 + 绑定 toolset | 为 AI 提供任务工作流指引 |