Repository navigation
UEMCP v0.1.5
中文
本版集中修复业务团队《UEMCP v0.1.4 复测缺陷单》确认的四条缺陷(D1–D4),不需要使用者改任何自己的代码:换上新插件包 + 新 server 包、重启编辑器即可。D5(screen-space UWidget 截图)经复核为引擎合成层边界,窗口截屏模式排入 0.1.6。
下载(Downloads)
UEMCPBridge-5.4.zip— Unreal Engine 5.4 插件包(实测 5.4.4)UEMCPBridge-5.7.zip— Unreal Engine 5.7 插件包(实测 5.7.4)uemcp-server-0.1.5.tgz— MCP Server 离线包(Node ≥ 20,未发布到 npm registry)SHA256SUMS.txt— 三个产物的 SHA-256 校验和(大小以SHA256SUMS.txt旁文件为准)
修复(Fixed,逐条对应缺陷单编号)
- D1:
ue_viewport_capture的activateWindow参数现在由 MCP 层原样透传到 Bridge(v0.1.4 的 Server schema 不认这个参数,会报INVALID_ARGUMENT: Unrecognized key,只有直连 Bridge 18778/rpc 才能用)。开启后置前并校验前台,成功返回带activation{requested, ok, editorPid, foregroundPid, hwnd, isIconic, alreadyForeground};失败仍立即EDITOR_UNSAFE_STATE(reason=window_not_foreground,details 带editorPid/foregroundPid/hwnd/isIconic/hint),不干等超时。注意activateWindow默认false(不传则不置前、不校验)。 - D2:
ue_log_query的级别判定兼容 UE 的隐式LogXxx:行:显式: Error:/: Warning:/: Display:/: Verbose:段优先;否则Log+首字母大写类别名(如LogMarker:)视为Log;都不匹配则level=null且不计入levels过滤,返回带unclassified计数。v0.1.4 中levels:["Log"]会静默漏掉全部隐式LogXxx:行("matched 0" 误判为没发生)。 - D3:
ue_reflect的target支持裸类名短名解析(如CustomDomainCmdHandler,含工程模块类):走派生类搜索 / 世界内实例搜索,不再必须写全路径(v0.1.4 只吃/Script/…全路径,裸类名直接NOT_FOUND);解析失败时错误details返回candidates候选全路径,照抄即可。 - D4:
ue_call_function新增captureLog:true(调用窗口日志旁路):调用期间在窗口内捕获日志,返回logLines[{lineNo, level, text}]——void函数不再只能拿到{"returned":null,"returnedVoid":true},业务结果(如 handler 打的 JSON 日志行)可直接随调用读回。
已知限制(Known limitations)
- 窗口截屏模式(
method:"window")尚未提供,已排入 0.1.6:ue_viewport_capture目前只能截引擎渲染的视口画面。 - UE 侧 screen-space
UWidgetComponent不进 hires 截图(缺陷单 D5 复核结论):这类 widget 属 Slate 合成层,由 UI pass 叠加在 scene renderer 输出之后,take_high_res_screenshot拿不到——这是引擎渲染管线行为,不是插件缺陷。需要带标记的画面时,请先用外部窗口截屏(Win32PrintWindow/桌面截图)对照验收,窗口截屏模式 0.1.6 提供。 object.call的函数名黑名单按子串拦截python/exec/eval/subprocess:名字里含这些子串的正常业务函数会被误拦(安全优先于便利)。函数命名请避开这些词;被拦时的错误信息会写明命中了黑名单。
升级提示(Upgrade notes)
- 从 v0.1.4 升级:整目录覆盖插件 +
npm install -g uemcp-server-0.1.5.tgz,重启编辑器;用/health的pluginVersion=0.1.5、buildHash变化、sourcePath指向当前工程Plugins/UEMCPBridge三项确认升级生效。 - 备份旧版时把
.uplugin一并改名(如UEMCPBridge.uplugin.bak)或移出Plugins/,否则备份会顶掉新版(second location will be ignored)。 - 验收
activateWindow前先确认 server 包确为 0.1.5:调用带"activateWindow": true若报Unrecognized key,说明包未含 D1 修复,请回传完整错误 JSON。
English
This release fixes the four defects (D1–D4) confirmed in the business team's v0.1.4 defect report. No changes are required on your side: swap in the new plugin and server packages and restart the editor. D5 (screen-space UWidget capture) was re-verified as an engine compositing boundary; a window-capture mode is scheduled for 0.1.6.
Downloads
UEMCPBridge-5.4.zip— Unreal Engine 5.4 plugin (tested 5.4.4)UEMCPBridge-5.7.zip— Unreal Engine 5.7 plugin (tested 5.7.4)uemcp-server-0.1.5.tgz— offline MCP server bundle (Node ≥ 20; not published to npm)SHA256SUMS.txt— SHA-256 checksums for all three (file sizes are whatever the sums file accompanies)
Fixed (per defect-report IDs)
- D1:
ue_viewport_capturenow passesactivateWindowthrough the MCP layer to the bridge (the 0.1.4 server schema rejected the key withINVALID_ARGUMENT: Unrecognized key, so it only worked when calling the bridge port 18778/rpc directly). When enabled, the window is restored and the foreground state verified; success returnsactivation{requested, ok, editorPid, foregroundPid, hwnd, isIconic, alreadyForeground}, failure returns immediately withEDITOR_UNSAFE_STATE(reason=window_not_foreground, details carryeditorPid/foregroundPid/hwnd/isIconic/hint). NoteactivateWindowdefaults tofalse(no activation/verification unless requested). - D2:
ue_log_querylevel inference now recognises UE's implicitLogXxx:lines: explicit: Error:/: Warning:/: Display:/: Verbose:segments win; otherwiseLog+ a capitalised category (e.g.LogMarker:) counts asLog; anything else keepslevel=null, is excluded fromlevelsfiltering, and is reported via anunclassifiedcount. In 0.1.4,levels:["Log"]silently missed every implicitLogXxx:line ("matched 0" was read as "never happened"). - D3:
ue_reflecttargetaccepts bare class names (e.g.CustomDomainCmdHandler, including project-module classes) via derived-class search / in-world instance search — a full/Script/…path is no longer required (0.1.4 returnedNOT_FOUNDfor bare names); on failure the errordetailscarrycandidateswith the resolved full paths. - D4:
ue_call_functionacceptscaptureLog:true(in-call log bypass): log lines captured inside the call window are returned aslogLines[{lineNo, level, text}]— avoidfunction no longer leaves the caller with only{"returned":null,"returnedVoid":true}; business results logged by your handler come back with the call itself.
Known limitations
- The window-capture mode (
method:"window") is not provided yet — scheduled for 0.1.6;ue_viewport_capturecurrently captures only the engine-rendered viewport. - Screen-space
UWidgetComponenton the UE side does not appear in hires screenshots (D5 re-verification): such widgets live in the Slate compositing layer, applied after the scene renderer output, sotake_high_res_screenshotcannot include them — an engine rendering-pipeline behaviour, not a plugin defect. For frames that must show the markers, use an external window screenshot (Win32PrintWindow/desktop capture) until the 0.1.6 window-capture mode ships. object.callname blacklist matches by substring onpython/exec/eval/subprocess: legitimate business functions whose names contain these substrings are blocked (safety over convenience). Avoid these substrings when naming functions; the error message names the matched blacklist term.
Upgrade notes
- From v0.1.4: overwrite the plugin directory and
npm install -g uemcp-server-0.1.5.tgz, restart the editor; confirm via/health—pluginVersion=0.1.5, a changedbuildHash, andsourcePathpointing at the project'sPlugins/UEMCPBridge. - When backing up the old version, rename its
.uplugin(e.g.UEMCPBridge.uplugin.bak) or move it out ofPlugins/, otherwise the backup shadows the new build (second location will be ignored). - Before acceptance-testing
activateWindow, make sure the server package is really 0.1.5: if a call with"activateWindow": truefails withUnrecognized key, the package predates the D1 fix — please send back the full error JSON.