Repository navigation
UEMCP 0.1.4 — generic primitives, PIE control, auditable builds
Pre-release
Pre-release
中文
这一版把业务两天试用里「必须写 Python 胶水代码」的最后几类场景也变成了一等公民工具:新增三条通用原语 ue_reflect / ue_call_function / ue_log_query——不需要使用者改自己的任何框架或代码,装上新包、重启编辑器即可在 MCP 客户端里直接调用。
下载(Downloads)
UEMCPBridge-5.4.zip— Unreal Engine 5.4 插件包(实测 5.4.4),158,583 BUEMCPBridge-5.7.zip— Unreal Engine 5.7 插件包(实测 5.7.4),158,583 Buemcp-server-0.1.4.tgz— MCP Server 离线包(Node ≥ 20,未发布到 npm registry),707,343 BSHA256SUMS.txt— 三个产物的 SHA-256 校验和
新增(Added)
- 三条通用原语(不需要使用者改自己的代码/框架):
ue_reflect(object.reflect):反射任意 UObject 的可调用函数清单(只读恒可见)。ue_call_function(object.call):调用对象函数——之前只能ue_python_exec硬凑的事现在是一等公民调用(写类原语:read-only策略下不注册,与ue_actor_edit同门;使用需standard/full策略)。ue_log_query(log.query):按正则/级别/时间过滤编辑器日志,返回命中行与行号;只读恒可见;Bridge 侧用 realpath 把可读范围严格限制在当前工程的Saved/Logs/目录内。
ue_pie_control(v0.1.3 引入,本版随包分发):start/stop/restart/status,可simulate。不需要--allow-exec就能点 Play——写动作只走allowWrite门,只读策略下收窄为status。ue_policy_explain(v0.1.3 引入,本版随包分发):列出每个工具在当前策略下「可见/不可见」及原因(server.policy/server.allowConsole/server.allowExec)。- 截图增强(v0.1.3 引入,本版随包分发):
activateWindow置前并校验;返回绝对路径 +sha256+mtime+bytes+stats{uniqueColors, nonZeroRatio, isBlack};超时后文件若在 500 ms 宽限内落盘,返回ok:true, partial:true。 /health可追溯字段(v0.1.3 引入,本版随包分发):buildHash(插件 Python 全量 sha256)、buildTime、sourcePath(实际加载的插件目录)、instanceId。升级后核对buildHash与sourcePath,可发现「备份目录顶替新版」的加载错误(详见 README「常见使用坑」第 2 条)。
修复(Fixed)
- 会话池加固(v0.1.3 引入,本版随包分发):满仓按 LRU 逐出最老会话(优先裸 POST 会话,不动正在推流的 SSE 会话);429 带
retryAfterMs;initialize响应带过期预告头Mcp-Session-Expires-In-Ms;404 -32001带hint: reinitialize,客户端重新initialize即自愈。 activateWindow快速失败:恢复窗口后若仍最小化或未置前,立即返回EDITOR_UNSAFE_STATE(window_not_foreground),不再干等到超时。
升级提示(Upgrade notes)
- 不需要使用者改任何代码:换上新插件包 + 新 server 包,重启编辑器即可。
- 升级备份请把
.uplugin一并改名(如UEMCPBridge.uplugin.bak)或移出Plugins/,否则旧备份可能顶掉新版(second location will be ignored)。 - 用
ue_call_function前确认策略不是read-only(可用ue_policy_explain自查)。
已知限制(Known limitations)
- 蓝图变量列表、每图节点数读不到(引擎 protected 属性,需 C++ 模块);父类/生成类/类型/已命名图可读。
- 基材质默认参数值读不到(引擎 API 边界);材质实例(MIC)正常。
- 蓝图节点级编辑、PIE 内 Actor 写操作、资产导入导出不支持。
- 截图需要编辑器窗口可渲染;
activateWindow=true时若窗口恢复后仍最小化/未置前会快速失败(EDITOR_UNSAFE_STATE)而不是干等。 delete的确认只在经 MCP Server 调用时强制;不要把 bridge 端口直接暴露给自定义客户端。ue_log_query只能读当前工程日志目录(<projectDir>/Saved/Logs/,realpath 约束)。
English
This release turns the last "write-your-own-Python-glue" scenarios from the two-day business trial into first-class tools: three universal primitives — ue_reflect, ue_call_function and ue_log_query — require no changes to your own framework or code. Install the new packages, restart the editor, and call them straight from your MCP client.
Downloads
UEMCPBridge-5.4.zip— Unreal Engine 5.4 plugin (tested 5.4.4), 158,583 BUEMCPBridge-5.7.zip— Unreal Engine 5.7 plugin (tested 5.7.4), 158,583 Buemcp-server-0.1.4.tgz— offline MCP server bundle (Node ≥ 20; not published to npm), 707,343 BSHA256SUMS.txt— SHA-256 checksums for all three
Added
- Three universal primitives (no changes needed on your side):
ue_reflect(object.reflect): list callable functions of any UObject (read-only, always visible).ue_call_function(object.call): call an object function — what previously requiredue_python_execworkarounds is now a first-class call (write-class primitive: not registered underread-only, same gate asue_actor_edit; requiresstandard/fullpolicy).ue_log_query(log.query): filter the editor log by regex/level/timestamp and get matching lines with line numbers; read-only, always visible; the bridge restricts reads to the current project'sSaved/Logs/directory via realpath.
ue_pie_control(introduced in v0.1.3, shipped in this package):start/stop/restart/status, optionalsimulate. Play-In-Editor no longer requires--allow-exec— write actions are gated byallowWriteonly, and read-only policy narrows the action tostatus.ue_policy_explain(introduced in v0.1.3, shipped in this package): per-tool visibility with the reason (server.policy/server.allowConsole/server.allowExec).- Capture improvements (introduced in v0.1.3, shipped in this package):
activateWindow(restore + verify foreground), absolutepathplussha256/mtime/bytes/stats{uniqueColors, nonZeroRatio, isBlack}; if the file lands within a 500 ms grace after a timeout, the call returnsok:true, partial:true. /healthbuild metadata (introduced in v0.1.3, shipped in this package):buildHash(sha256 over all plugin Python files),buildTime,sourcePath(the plugin directory actually loaded),instanceId. After upgrading, comparebuildHashandsourcePathto catch a backup directory shadowing the new build (see README "Common pitfalls" #2).
Fixed
- Session pool hardening (introduced in v0.1.3, shipped in this package): LRU eviction of the oldest session when full (bare-POST sessions first, active SSE streams kept);
retryAfterMson 429; session-expiry hint headerMcp-Session-Expires-In-Msoninitialize;hint: reinitializeon404 -32001— clients re-initialize and recover on their own. activateWindowfails fast: after restoring, if the window is still minimized or not foreground, it returnsEDITOR_UNSAFE_STATE(window_not_foreground)immediately instead of waiting for the timeout.
Upgrade notes
- No changes are needed on your side: swap in the new plugin + server packages and restart the editor.
- When backing up an old version, rename its
.uplugin(e.g.UEMCPBridge.uplugin.bak) or move it out ofPlugins/, otherwise the backup can shadow the new build (second location will be ignored). - Before using
ue_call_function, make sure the policy is notread-only(self-check withue_policy_explain).
Known limitations
- Blueprint variable lists and per-graph node counts are unreadable (protected engine properties; requires a C++ module). Parent class / generated class / type / named graphs are readable.
- Base-material default parameter values are unreadable (engine API boundary); material instances work.
- No blueprint node editing, PIE actor write operations, or asset import/export.
- Capture requires a renderable editor window; with
activateWindow=true, a window that is still minimized or not foreground after restoration fails fast (EDITOR_UNSAFE_STATE) instead of waiting. deleteconfirmation is enforced by the MCP server only; do not expose the bridge port to custom clients.ue_log_querycan only read the current project's log directory (<projectDir>/Saved/Logs/, realpath-constrained).