Files

BlueRose 07ca541d59 vault backup: 2026-06-01 20:40:23

2026-06-01 20:40:23 +08:00

22 KiB

Raw Blame History

UE5.8 MCP Toolsets 分析

使用方法

在UE5.8启用 UnrealMcp、MCP Client Toolset插件。 !UnrealMcp_EnableMcpPlugin.png 根据需求启用相关的Toolset插件。 !UnrealMcp_EnableToolsetPlugin.png 在ModelContextProtocol.StartServer !UnrealMcp_StartServer.png !UnrealMcp_EnableAutoStart.png

给AI添加MCP信息。

{
  "mcpServers": {
    "ue-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

总体架构

所有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 侧完成。

实现模式分类

模式	使用方
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 注册)

启用工具集的建议配置

场景	需要的工具集
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 开发
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 代码字符串在编辑器内执行

官方模式：引擎内原生 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 分析

1. 它是什么

UAgentSkill 是 UE5.8 MCP 的 AI prompt 增强机制，功能等价于 Claude Code 的 Skill：

	UE5.8 UAgentSkill	Claude Code Skill
载体	Blueprint 资产（UAgentSkill 子类）	Markdown 文件
作用	注入领域知识 + 指令到 AI 上下文	注入工作流指引到对话
依赖	Toolsets 字段声明需加载哪些 toolset	无
动态生成	GeneratePrompt() 虚函数可编程	静态内容
创建	AI 通过 MCP CreateSkill 创建	文件写入

2. 相关类

UAgentSkill：基类，核心属性 Description + Instructions + Toolsets，虚函数 GeneratePrompt()
UAgentSkillBestPractices：改写 GeneratePrompt，追加技能编写规范
UAgentSkill_NiagaraBase：改写 GeneratePrompt，前置 Niagara 概述 + 资产发现路径
UAgentSkillToolset：继承 UToolsetDefinition，暴露 MCP CRUD（ListSkills / GetSkills / CreateSkill / UpdateSkill）
FAgentSkillDetails：DTO，最终生成的 Instructions + 依赖 toolset 名列表

核心流程：GetDetails() → GeneratePrompt(Instructions) → FAgentSkillDetails → AI 拿到最终 prompt。

3. 编写一个基础 UAgentSkill

C++ 子类方式：

继承 UAgentSkill
设置 Description（简短摘要，ListSkills 返回它）
设置 Instructions（详细指令，会被 GeneratePrompt 处理）
在 Toolsets 中声明依赖的功能性 toolset（软引用，系统据此自动加载）
重写 GeneratePrompt_Implementation() 在指令前后注入额外上下文

Niagara Skill实现路径：前置概念概述 → 遍历 toolset 获取专属 prompt → 插入原始 Instructions → 追加资产发现路径。

MCP 运行时创建（AI 调用，需用户许可）： CreateSkill(/Game/Skills/, MySkill, "描述", {Instructions:"...", Toolsets:["/Script/..."]})，本质是创建以 UAgentSkill 为父类的 Blueprint 资产，写入 CDO 属性。

22 KiB Raw Blame History Unescape Escape