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

43 KiB
Raw Blame History

UE5.8 MCP Toolsets 分析

总体架构

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

功能维度总览

核心编辑器操作

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

资产与资源管理

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

Gameplay

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

Sequence

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

动画系统

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

特效系统 (Niagara)

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

PCG

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

测试与配置

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

插件与功能管理

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

其他工具

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

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

MCP 服务器连接配置

{
  "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）

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

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

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)：

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)：

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)：

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 提供任务工作流指引
Reference in New Issue View Git Blame Copy Permalink