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

18 KiB
Raw Blame History

UE5.8 MCP Toolsets 完整分析

总体架构

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

MCP 服务器连接配置

  • 服务器地址: http://localhost:8000/mcp
  • 协议版本: 2025-11-25 (Streamable HTTP)
  • 配置文件: Engine\Plugins\Experimental\Toolsets\.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 实现 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

六、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 View Git Blame Copy Permalink