UEEditorMCP

基于 lilklon/UEBlueprintMCP 修改扩展。
原项目采用 MIT 协议，本插件在其基础上进行了大量重构与功能增强，同样遵循 MIT 协议发布。
感谢 @lilklon 提供的架构基础。

一个面向 AI 辅助开发的 MCP 插件，用于 Unreal Engine 5.7+ 蓝图操作。
对外暴露 7 个固定 MCP 工具，由后端 动作注册表（Action Registry） 驱动，支持 141 个动作，提供持久 TCP 连接、多客户端支持与自动保存。

同时包含一个可选的独立日志 MCP 服务器（ue-editor-mcp-logs），暴露 unreal.logs.get、unreal.asset_thumbnail.get 和 unreal.asset_diff.get 三个工具。

仅限编辑器 — C++ 模块类型为 Editor，在所有游戏打包构建（Shipping、Development Game 等）中完全排除，不会对运行时性能或打包产物产生任何影响。

功能特性

• 7 个固定 MCP 工具 — 单一 ue-editor-mcp 服务器，工具接口永远不变
• 141 个动作 — 蓝图、图节点、材质、UMG 控件、MVVM、增强输入、组件事件绑定、PIE 启停/状态查询、日志断言、Outliner 管理、资产缩略图提取、批量资产重命名及重定向修复、与版本控制仓库的差异对比 — 均可通过动作注册表动态发现
• 搜索 → 模式 → 执行 — AI 动态发现动作，无需记忆命令名
• 批量执行 — ue_batch 通过 C++ batch_execute 在单次 TCP 往返中执行最多 50 个动作
• 多客户端 TCP — 端口 55558，最多支持 8 路并发连接（每连接独立线程）
• 持久连接 — Socket 在命令间保持开启，支持心跳检测与自动重连
• 自动保存 — 每次成功操作后自动保存脏包
• 崩溃保护 — 动作执行管道启用了 SEH + C++ 异常防护
• 字符串解析 — 接受蓝图名称、资产路径或引擎类名
• 嵌入式文档 — ue_resources_read 将约定规范、错误码和补丁规范暴露给 AI

架构

VS Code / MCP 客户端（GitHub Copilot 等）
        │
        │  7 个 MCP 工具（stdio）
        ▼
  server_unified.py（动作注册表 + 分发器）
        │
        │  TCP/JSON（端口 55558，持久连接，长度前缀帧）
        ▼
  C++ 插件（FMCPServer → 每连接一个 FMCPClientHandler）
        │
        │  游戏线程分发
        ▼
  FEditorAction 子类（~150 个处理器）→ 校验 → 执行 → 自动保存
        │
        ▼
  Unreal Editor

单一 Python 服务器进程与 C++ 服务器建立持久 TCP 连接。C++ 侧为每个连接派生独立的 FMCPClientHandler 线程，所有编辑器变更均被序列化到游戏线程以保证线程安全。

对于日志上下文场景，第二个轻量服务器（server_unreal_logs.py）可并行运行，提供：

• unreal.logs.get（即使 UE 未运行也可通过 Saved/Logs 离线读取）
• unreal.asset_thumbnail.get（需要 UE 编辑器连接，以 PNG base64 格式返回资产缩略图）
• unreal.asset_diff.get（需要 UE 编辑器 + 源码控制连接，返回资产与仓库版本的结构化差异）

MCP 工具（7 个固定）

AI 工作流（快速路径 — 1 次往返）

# 当动作 ID 及参数已知时，直接跳过搜索/模式步骤：
ue_batch(actions=[
  {action_id: "blueprint.create", params: {name: "BP_Player", parent_class: "Character"}},
  {action_id: "variable.create", params: {blueprint_name: "BP_Player", variable_name: "Speed", variable_type: "Float"}},
  {action_id: "blueprint.compile", params: {blueprint_name: "BP_Player"}}
])
→ 所有动作在 1 次 TCP 往返中完成

AI 工作流（发现路径 — 3 次往返）

第 1 步：ue_actions_search(query="create blueprint")
  → [{id: "blueprint.create", desc: "..."}, ...]

第 2 步：ue_actions_schema(action_id="blueprint.create")
  → {input_schema: {required: ["name","parent_class"], ...}, examples: [...]}

第 3 步：ue_actions_run(action_id="blueprint.create", params={name: "BP_Player", parent_class: "Character"})
  → {success: true, blueprint_name: "BP_Player", path: "/Game/Blueprints/BP_Player"}

动作域（核心）

编译诊断（重要）

• blueprint.compile 返回状态及汇总计数（status、error_count、warning_count），但对某些 UMG/MVVM 编译失败可能不包含完整编译器文本。
• 如需详细诊断，请调用 editor.get_logs（或带 source="editor" 的 ue_logs_tail），并按 category="LogBlueprint" + min_verbosity="Error" 过滤。
• 推荐排查流程：
  1. blueprint.compile
  2. editor.get_logs(count=200, category="LogBlueprint", min_verbosity="Error")
  3. 如需进一步扩展，可将过滤类别改为 category="LogOutputDevice" 获取 Ensure/Fatal 上下文

材质编译诊断（Phase 5）

• material.compile 现已同步等待材质着色器编译完成，并返回真实编译诊断。
• 响应中包含 error_count、warning_count 以及 errors[] 列表。
• errors[] 的每一项包含：message、expression_name、expression_class、node_name（如可解析）。
• 推荐排查流程：
  1. material.compile
  2. 若有需要，再结合 ue_logs_tail(source="editor", category="LogMaterial", min_verbosity="Error") 查看上下文日志

蓝图编辑器自动布局命令

插件在蓝图编辑器菜单（编辑 → Auto Layout）中直接注册了自动布局命令，并提供默认快捷键：

• Auto Layout：Ctrl+Alt+L

行为：

• 若有节点被选中，对当前选中节点执行布局
• 若无选中，对整个焦点图执行布局

这些是编辑器命令，可在 Unreal Editor 快捷键设置中重映射。

材质编辑器自动布局菜单（Phase 5）

插件在材质编辑器菜单（Edit）中注册了 Auto Layout 菜单项。

行为：

• 对当前焦点材质的 UMaterialGraph 执行自动布局
• 与 material.auto_layout 动作配套，便于在编辑器内直接整理材质图

安装与配置

第 1 步：编译 C++ 插件

插件已位于 Plugins/UEEditorMCP/，编译编辑器目标：

Engine\Build\BatchFiles\Build.bat p110_2Editor Win64 Development ${workspaceFolder:p110_2}\p110_2.uproject -waitmutex

或使用 VS Code 任务：p110_2Editor Win64 Development Build。

第 2 步：一键 Python 环境配置（使用 UE 引擎内置 Python）

无需安装外部 Python。 配置脚本会自动找到 Unreal Engine 内置的 Python 3.11，创建虚拟环境并安装 MCP 包。

PowerShell（推荐）：

cd Plugins/UEEditorMCP
.\setup_mcp.ps1
# 或显式指定引擎路径：
.\setup_mcp.ps1 -EngineRoot "${workspaceFolder:UE5}"

命令提示符：

cd Plugins\UEEditorMCP
setup_mcp.bat

脚本将会：

1. 自动检测 UE 引擎内置 Python（Engine/Binaries/ThirdParty/Python3/Win64/python.exe）
2. 在 Python/.venv 创建虚拟环境
3. 安装 mcp 包
4. 在项目根目录生成 .vscode/mcp.json，并填入正确路径

cd Plugins/UEEditorMCP/Python
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt

{
  "servers": {
    "ue-editor-mcp": {
      "command": "./Plugins/UEEditorMCP/Python/.venv/Scripts/python.exe",
      "args": ["-m", "ue_editor_mcp.server_unified"],
      "env": {
        "PYTHONPATH": "./Plugins/UEEditorMCP/Python"
      }
    },
    "ue-editor-mcp-logs": {
      "command": "./Plugins/UEEditorMCP/Python/.venv/Scripts/python.exe",
      "args": ["-m", "ue_editor_mcp.server_unreal_logs"],
      "env": {
        "PYTHONPATH": "./Plugins/UEEditorMCP/Python"
      }
    }
  }
}

日志上下文工具（ue-editor-mcp-logs）

ue-editor-mcp-logs 暴露三个工具：

unreal.logs.get

• mode：auto|live|saved（默认 auto）
• tailLines：默认 200（范围 20..2000）
• maxBytes：默认 65536（范围 8192..1048576）
• cursor：增量游标（live:<seq> 或 file:<hash>:<offset>:<mtime_ns>:<size>）
• workspaceRoot：UE 不可达时的离线读取必填项

推荐用法：

1. 首次调用：mode=auto, tailLines=200, maxBytes=65536
2. 保存返回的 cursor
3. 后续调用传入 cursor，仅获取增量日志，避免 token 爆炸

行为说明：

• mode=auto：若日志在 2 秒内更新则优先读取实时环形缓冲区，否则回退到 Saved/Logs
• mode=live：仅读取内存中的实时环形缓冲区，无文件 IO
• mode=saved：使用反向块读取方式追踪最新 Saved/Logs 文件
• UE 不可达时：若提供 workspaceRoot 则从磁盘返回 offline_saved

unreal.asset_thumbnail.get

• assetPath：可选，单个资产完整路径
• assetPaths：可选，多个完整路径
• assetIds / ids：可选，路径数组别名（批量）
• size：可选，缩略图尺寸（默认 256，上限 1..256）
• 返回 thumbnails[]（每个输入对应一项），并保留首项兼容字段 image_base64
• 需要 UE 编辑器连接

unreal.asset_diff.get

• assetPath（必填）：完整资产路径（如 /Game/P110_2/Blueprints/BP_Foo）
• revision（可选）：指定版本号（默认最新版本）
• 返回结构化差异数据：hasDifferences、summary（新增/删除/修改/次要变更计数）、diffs[]（类型、分类、显示字符串、所属图、节点/引脚名称）
• 对于蓝图：逐图节点级别变更（NODE_ADDED、NODE_REMOVED、PIN_DEFAULT_VALUE、NODE_MOVED 等）
• 对于通用资产：属性级别差异（PropertyValueChanged、PropertyAddedToA/B）
• 包含 revisionInfo（版本号、日期、用户名、描述）
• 需要 UE 编辑器运行且源码控制（SVN/Perforce/Git）已连接

第 3 步：启动

1. 在编辑器中打开 Unreal 项目（插件自动在端口 55558 启动 TCP 服务器）
2. 打开 VS Code — ue-editor-mcp 服务器通过 stdio 启动并连接到端口 55558
3. 使用 GitHub Copilot Chat 或任意兼容 MCP 的客户端发出命令

新增动作

若要为插件扩展新能力：

第 1 步：C++ 侧 — 实现动作处理器

// Source/Public/Actions/MyActions.h
class FMyNewAction : public FBlueprintNodeAction
{
public:
    FMyNewAction() : FBlueprintNodeAction(TEXT("my_new_action")) {}
    FString Validate(const TSharedPtr<FJsonObject>& Params) override;
    TSharedPtr<FJsonObject> ExecuteInternal(const TSharedPtr<FJsonObject>& Params) override;
};

在 MCPBridge.cpp 中注册：

ActionHandlers.Add(TEXT("my_new_action"), MakeShared<FMyNewAction>());

第 2 步：Python 侧 — 添加 ActionDef

在 registry/actions.py 中添加动作定义：

ActionDef(
    id="domain.my_new_action",
    command="my_new_action",
    description="这个动作的用途说明",
    tags=["domain", "keyword1", "keyword2"],
    input_schema={
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "..."},
        },
        "required": ["param1"],
    },
    examples=[{"param1": "value"}],
)

第 3 步：编译与测试

Engine\Build\BatchFiles\Build.bat p110_2Editor Win64 Development ...

无需修改任何服务器代码 — ue_actions_search / ue_actions_run 将自动识别新动作。

编辑器专属安全保障

本插件通过三重机制保证永远不出现在打包构建中：

TCP 服务器、所有 MCP 工具以及所有蓝图操作代码仅存在于编辑器 DLL 中。

技术细节

C++ 服务器（FMCPServer）

• 监听 127.0.0.1:55558（仅限本地，不对网络暴露）
• Accept 循环为每个连接派生独立的 FMCPClientHandler（每个独立线程）
• ping 和 close 直接在客户端线程处理（无需游戏线程）
• 所有其他命令通过 AsyncTask + FEvent 同步分发到游戏线程
• 客户端超时：120 秒无活动后断开
• 启用 SO_REUSEADDR，避免编辑器重启时端口冲突

Python 服务器（server_unified.py）

• 对外暴露 7 个固定工具的单一 MCP 服务器
• 动作注册表含 141 个 ActionDef 条目，支持关键字搜索和模式自省
• UMG 控件类型通过内部组件类型映射分发（支持 24 种控件类型）
• ue_batch 批量执行（每次最多 50 个动作）
• 命令日志环形缓冲区，供 ue_logs_tail 使用
• 通过 ue_resources_read 暴露嵌入式资源文档

通信协议格式

[4 字节：消息长度（大端序）] [UTF-8 JSON 载荷]

请求：

{"type": "create_blueprint", "params": {"name": "BP_MyActor", "parent_class": "Actor"}}

响应：

{"success": true, "blueprint_name": "BP_MyActor", "path": "/Game/Blueprints/BP_MyActor"}

关键文件

环境要求

• Unreal Engine 5.7+（内置 Python 3.11，无需另行安装）
• Visual Studio 2022（插件编译所需）
• VS Code + GitHub Copilot（或任意兼容 MCP 的客户端）

开发路线

开发计划详见 DEVPLAN.md。当前状态：

阶段一：统一服务器 + 动作注册表 ✅

7 工具统一 MCP 服务器，动作注册表（141 个动作）、关键字搜索、批量执行、嵌入式文档和结构化日志——全部完成。

Phase 6: PIE / 日志断言 / Outliner ✅

Phase 5: 材质系统增强（续）✅

阶段二：C++ 增强 ✅

阶段三：补丁系统 ✅

Layout V2: Enhanced Auto-Layout ✅

• layout.auto_selected / layout.auto_subtree / layout.auto_blueprint 已完成 Enhanced Sugiyama 改造：最长路径分层、Barycenter 交叉优化、宽高感知间距、Pure Pin 对齐、周围节点避让、Comment 框调整。
• layer_spacing / row_spacing 语义：>0 固定间距，<=0 自动间距（默认自动）。
• 新参数（按动作范围）：horizontal_gap、vertical_gap、crossing_passes、pin_align_pure、avoid_surrounding、include_pure_deps、surrounding_margin、preserve_comments。

DevPlan 路径规则

• 插件开发计划唯一来源：Plugins/UEEditorMCP/DEVPLAN.md。
• 其他临时计划文档在需求完成后应合并回该文件并移除，避免多份计划口径冲突。

Phase 4: 材质系统增强 ✅

文档

• DEVPLAN.md — 详细开发计划（各阶段设计文档）

许可证

MIT

本项目基于 lilklon/UEBlueprintMCP（MIT 许可证）修改扩展。
原始代码版权归 @lilklon 所有。