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

14 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink