BlueRose/BlueRoseNote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cc082fc505c6978e4423330a5be5809e4cf02bbb
BlueRoseNote/07-Other/AI/AI Agent/UnrealEngine/UnrealMcp/UE5.8 MCP.md

363 lines
18 KiB
Markdown
Raw Normal View History

vault backup: 2026-06-01 15:06:44
2026-06-01 15:06:44 +08:00
# UE5.8 MCP Toolsets 完整分析
## 总体架构
所有Toolset都位于 `Engine\Plugins\Experimental\Toolsets`，共18个插件。它们通过 `ToolsetRegistry` 插件（核心基础设施）将 AI-callable 工具暴露给 MCP 系统（如 UnrealMCP）。
vault backup: 2026-06-01 15:59:56
2026-06-01 15:59:56 +08:00
### MCP 服务器连接配置
- **服务器地址**: `http://localhost:8000/mcp`
- **协议版本**: `2025-11-25` (Streamable HTTP)
- **配置文件**: `Engine\Plugins\Experimental\Toolsets\.mcp.json`
- **状态**: 已连接，正常运行
```json
{
"mcpServers": {
"ue-mcp": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
```
### MCP 核心工具 (3个)
| 工具 | 功能 |
|------|------|
| `list_toolsets` | 列出所有可用工具集及其描述 |
| `describe_toolset` | 获取工具集的详细信息（工具名、描述、输入 schema）|
| `load_toolset` | 加载工具集，将其工具注册为原生 MCP 工具（下一轮生效）|
vault backup: 2026-06-01 15:06:44
2026-06-01 15:06:44 +08:00
### 核心概念
- **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 |
vault backup: 2026-06-01 15:59:56
2026-06-01 15:59:56 +08:00
---
## 六、MCP 运行时实际检测
**检测时间**: 2026/06/01
**连接状态**: 成功
**协议版本**: 2025-11-25
**Session ID**: 25ece1cd4985fb91e9041b97c47caa7d
### 当前注册的工具集（运行时 list_toolsets 结果）
共 **27 个工具集**已注册并可加载。注意：其中包括来自 `toolset_registry` 核心模块的 Python 工具集，以及部分未在上文 C++ 分析中列出的 Python 工具集。
#### 编辑器核心工具集 (ToolsetRegistry.*)
| 工具集 | 说明 |
|--------|------|
| `ToolsetRegistry.EditorAppToolset` | 编辑器状态查询/修改：控制台变量、资产成像、Actor/资产选择、视口相机、内容浏览器导航 |
| `ToolsetRegistry.AgentSkillToolset` | Agent Skill 的列表/读取/创建/更新 |
| `ToolsetRegistry.LogsToolset` | 读取 Unreal 输出日志，控制日志类别详细级别 |
#### 已实现的功能工具集 (C++ 插件)
| 工具集 | 来源插件 |
|--------|----------|
| `GameFeaturesToolset.GameFeaturesToolset` | GameFeaturesToolset |
| `GASToolsets.GameplayCueToolset` | GASToolsets |
| `GASToolsets.AttributeSetToolset` | GASToolsets |
| `GASToolsets.AbilitySystemInspectorToolset` | GASToolsets |
| `LiveCodingToolset.LiveCodingToolset` | LiveCodingToolset |
| `GameplayTagsToolset.GameplayTagsToolset` | GameplayTagsToolset |
| `NiagaraToolsets.NiagaraToolset_Info` | NiagaraToolsets |
| `NiagaraToolsets.NiagaraToolset_Component` | NiagaraToolsets |
| `NiagaraToolsets.NiagaraToolset_Blueprint` | NiagaraToolsets |
| `NiagaraToolsets.NiagaraToolset_System` | NiagaraToolsets |
| `SlateInspectorToolset.SlateInspectorToolset` | SlateInspectorToolset |
| `UMGToolSet.UMGToolSet` | UMGToolSet |
| `conversation_toolset.toolsets.conversation.ConversationTools` | ConversationToolset (Python 实现) |
#### 核心工具集 (toolset_registry Python 模块)
| 工具集 | 说明 |
|--------|------|
| `toolset_registry.toolsets.core.actor.ActorTools` | Actor 检查/修改（变换、标签、父子关系、组件）|
| `toolset_registry.toolsets.core.asset.AssetTools` | 资产和文件交互 |
| `toolset_registry.toolsets.core.blueprint.BlueprintTools` | Blueprint 操作 |
| `toolset_registry.toolsets.core.curve_table.CurveTableTools` | CurveTable 创建/编辑 |
| `toolset_registry.toolsets.core.data_asset.DataAssetTools` | DataAsset 操作 |
| `toolset_registry.toolsets.core.data_table.DataTableTools` | DataTable 创建/编辑 |
| `toolset_registry.toolsets.core.material.MaterialTools` | Material 创建/编辑及表达式图 |
| `toolset_registry.toolsets.core.material_instance.MaterialInstanceTools` | MaterialInstanceConstant 创建/修改 |
| `toolset_registry.toolsets.core.object.ObjectTools` | UObject/UClass 属性检查/修改及类发现 |
| `toolset_registry.toolsets.core.primitive.PrimitiveTools` | 图元几何组件添加 |
| `toolset_registry.toolsets.core.scene.SceneTools` | 关卡加载/放置/移除/相机/Outliner |
| `toolset_registry.toolsets.core.skeletal_mesh.SkeletalMeshTools` | 骨骼网格检查/修改 |
| `toolset_registry.toolsets.core.static_mesh.StaticMeshTools` | 静态网格检查/修改 |
| `toolset_registry.toolsets.core.string_table.StringTableTools` | StringTable 创建/编辑 |
| `toolset_registry.toolsets.core.programmatic.ProgrammaticToolset` | 沙盒 Python 脚本执行，可调用其他工具 |
| `toolset_registry.toolsets.core.texture.TextureTools` | Texture 资产操作 |
### 重要发现
1. **ConversationToolset 实际有 Python 实现**: 注册为 `conversation_toolset.toolsets.conversation.ConversationTools`，用于检查 Conversation Graph 对话资产，而非纯空壳
2. **toolset_registry 包含 16 个核心工具集**: 这些是 Python 实现的，不在 C++ 插件目录中，由 `toolset_registry` 插件自带的 Python 模块提供
3. **运行时工具集总数**: 27 个（远多于分析目录中看到的 C++ 工具集数量）
4. **加载机制**: 使用 `load_toolset` 按需加载，工具在下一个 turn 生效（不是同一响应中）
Reference in New Issue Copy Permalink