UE Project Intelligence

中文 | English

中文

项目概述

UE Project Intelligence（UEPI）是一个面向 Unreal Engine 5.3.2 的项目内编辑器插件和 Python stdio MCP Server。它将编辑器或 Commandlet 收集到的工程信息保存为 Snapshot，并通过 MCP 工具提供工程查询、实时编辑器读取和受控写入能力。

当前版本为 2.0.0-beta.6。Codex 是目前完成实机验证的 MCP 客户端示例；其他能够启动 stdio MCP Server 的客户端也可以按相同协议接入。

本项目是独立实现，不依赖 Epic UE5.8 的 ModelContextProtocol 插件。

功能范围

• 查询资产、蓝图图表、节点、Pin、动画、依赖关系、关卡、UI、AI、音频、材质和部分工程源码元数据。
• 编辑器打开时，通过项目本地 Bridge 读取当前工程状态，并按需刷新发生变化的目标资产。
• 编辑器关闭时，读取最近一次保存的 Snapshot，用于离线分析。
• 通过不可变 Preview、工程和会话绑定、权限策略、备份、验证、按涉及资产保存、差异报告及恢复标记执行写入。
• 使用可重建的 SQLite 缓存查询 Snapshot fragments。

UEPI 不提供任意 Python、Shell 或控制台执行，也不负责启用其他插件、提交源代码、全工程保存或不受范围约束的破坏性修改。PIE 控制只在 UEPI 创建并授权的 Runtime 验证流程内提供。

环境要求

• Unreal Engine 5.3.2。
• Python 3.11 或更高版本。
• 支持 stdio MCP Server 的客户端。
• 插件安装在工程内：__PROJECT_ROOT__/Plugins/UEProjectIntelligence。

EnhancedInput、GameplayAbilities、Niagara、PCG、CommonUI、StateTree、IKRig、ControlRig 和 MetaSound 等可选 Unreal 插件采用条件编译，普通工程不要求全部启用。

安装

将仓库复制或解压到：

__PROJECT_ROOT__/Plugins/UEProjectIntelligence

根据工程情况重新生成项目文件，然后编译 Editor Target：

& "__UE_ROOT__\Engine\Build\BatchFiles\Build.bat" `
  __PROJECT_NAME__Editor Win64 Development `
  "-Project=__PROJECT_ROOT__\__PROJECT_NAME__.uproject" `
  -WaitMutex -NoHotReloadFromIDE

打开工程。如果 Unreal 提示插件未启用，在插件管理器中启用 UEProjectIntelligence 并重启编辑器。

Snapshot 与在线状态

编辑器在线时，UEPI 会发布当前工程的本地 Bridge session。MCP Server 可以读取实时状态，并针对用户问题请求目标资产刷新，不要求每次连接都执行全工程扫描。

需要保留离线基线时，打开 Tools > UE Project Intelligence，点击 Run Snapshot Scan。数据写入：

__PROJECT_ROOT__/Saved/UEProjectIntelligence/store

也可以在编辑器关闭后执行目标 Commandlet 扫描：

& "__UE_ROOT__\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
  "__PROJECT_ROOT__\__PROJECT_NAME__.uproject" `
  -run=UEPIIndex -unattended -nop4 -nosplash -NullRHI `
  -UEPILevel=L2 `
  -UEPIAsset="/Game/Path/To/BP_Player.BP_Player" `
  -UEPIOutput="__PROJECT_ROOT__\Saved\UEProjectIntelligence\l2_scan.json"

数据状态说明：

• saved：读取最近发布的保存 Snapshot，编辑器可以关闭。
• live：编辑器在线，实时观察覆盖在保存基线上。
• refresh_requested：目标可能已变化，刷新请求已发送给编辑器。
• stale：目标可能已变化，但当前没有编辑器处理刷新。

SQLite 文件属于派生缓存，删除后可以从 Snapshot fragments 重建。

连接 MCP

以 Codex 为例，先预览配置，再写入工程本地配置：

python "__PROJECT_ROOT__/Plugins/UEProjectIntelligence/Tools/setup_codex.py" `
  --project "__PROJECT_ROOT__/__PROJECT_NAME__.uproject"

python "__PROJECT_ROOT__/Plugins/UEProjectIntelligence/Tools/setup_codex.py" `
  --project "__PROJECT_ROOT__/__PROJECT_NAME__.uproject" --apply

应用配置后重启 Codex，使 MCP 进程重新加载。也可以复制 Resources/codex-config.template.toml 并替换其中的占位符。

其他 MCP 客户端可以将以下命令配置为 stdio Server：

python -B "__PROJECT_ROOT__/Plugins/UEProjectIntelligence/Services/uepi/src/uepi/mcp_server.py" `
  --project "__PROJECT_ROOT__/__PROJECT_NAME__.uproject" `
  --tool-profile codex

MCP 客户端负责启动这个进程，不需要单独启动 daemon。编辑器在线时以对应的 Bridge session 作为当前工程；没有在线编辑器时，--project 指定离线 Snapshot 工程。

建议调用顺序

1. 调用 uepi_status，确认工程、Snapshot、编辑器 session 和恢复状态。
2. 使用 uepi_overview、uepi_search 或 uepi_context 缩小问题范围。
3. 使用蓝图、动画、资产、依赖或 World 等领域工具读取证据。
4. 收到 UEPI_REFRESH_REQUESTED 时，等待编辑器处理目标刷新后重试。
5. 收到 UEPI_SNAPSHOT_STALE 时，打开对应工程或执行 Snapshot/Commandlet 扫描。
6. 需要修改工程时，先发现操作并创建完整 Preview，再按返回的授权策略执行 Apply。

MCP 工具

类别	工具
状态与检索	uepi_status, uepi_overview, uepi_search, uepi_context
资产读取	uepi_asset, uepi_blueprint, uepi_blueprint_trace, uepi_animation, uepi_impact, uepi_diff
编辑器读取	uepi_editor, uepi_world, uepi_refresh, uepi_schema
Runtime 验证	uepi_runtime_preview, uepi_runtime_approve, uepi_runtime
恢复	uepi_recovery_inspect, uepi_recovery_finalize, uepi_recovery_discard, uepi_recovery_rollback
写入	uepi_edit_discover, uepi_edit_preview, uepi_edit_apply, uepi_edit_validate, uepi_edit_rollback

codex profile 同时暴露读取与写入工具，由客户端根据任务选择。codex_write_alpha 仅作为旧配置兼容别名保留。

uepi_context 支持 project_overview、gameplay_input_to_effect、input_to_gameplay、blueprint_behavior、animation_playback、ui_flow、asset_dependency_impact、data_driven_behavior、gas_ability_flow、ai_behavior_flow 和 network_replication_flow 等路由。

写入与恢复

写入要求编辑器 Bridge 与目标工程、Editor session 和 Preview 完全匹配。当前授权模式包括：

• ReviewEachPlan：不可变 Preview 需要一次用户确认。
• TrustedSession：当前 Editor session 内，符合策略的 Preview 可以自动授权。
• TrustedProject：绑定工程内，符合资产根目录、操作领域、风险和事务限制的 Preview 可以自动授权。

无论采用哪种模式，重复预检、备份、验证、按涉及资产保存、目标刷新、差异和执行报告仍会保留。未解决的 recovery marker 会阻止新的写入；应先使用 uepi_recovery_inspect 检查当前文件与备份，再选择 finalize、discard 或 rollback。Discard 和 rollback 都可能影响恢复选择，需要按工具返回的确认条件执行。

已知限制

• 当前发布验证目标为 UE5.3.2，其他引擎版本未声明兼容。
• 项目处于 Beta 阶段，写入操作范围小于读取范围，并受操作目录和策略限制。
• 动画工具可以读取静态摘要、驱动曲线、重建 profile 和可选的全姿态采样，但不会计算经过 AnimGraph、Control Rig、IK、物理和重定向后的最终运行时姿态。
• 更新 Snapshot 需要编辑器或 Commandlet；编辑器关闭时只能读取最近保存的数据。
• 读取结果是工程静态信息和受控运行时观察的组合，不等同于完整的游戏行为证明。

完整边界见 Docs/Known-Limitations.md。

检查与文档

运行环境检查：

python Tools/uepi_doctor.py --project "__PROJECT_ROOT__/__PROJECT_NAME__.uproject"

运行 Snapshot/MCP 回归：

python -B Tools/test_snapshot_mcp_v2.py

使用说明见 Docs/user-guide.md，故障排查见 Docs/troubleshooting.md，版本验证记录见 Docs/Releases。

许可证

本项目采用 MIT License，见 LICENSE。

English

Overview

UE Project Intelligence (UEPI) is a project-local Unreal Editor plugin and Python stdio MCP server for Unreal Engine 5.3.2. It stores project observations collected by the editor or commandlet as Snapshots and exposes MCP tools for project queries, live editor reads, and guarded writes.

The current version is 2.0.0-beta.6. Codex is the MCP client used for the current real-machine validation. Other clients that can launch a stdio MCP server can use the same protocol.

This project is an independent implementation and does not depend on Epic's UE5.8 ModelContextProtocol plugin.

Scope

• Query metadata for assets, Blueprint graphs, nodes, Pins, animations, dependencies, worlds, UI, AI, audio, materials, and selected project source information.
• Read the active project through a local Bridge and request targeted refreshes when the editor is open.
• Read the latest saved Snapshot for offline analysis when the editor is closed.
• Perform writes through immutable Preview plans, project and session binding, authorization policy, backups, validation, touched-package saving, diffs, and recovery markers.
• Query Snapshot fragments through a rebuildable SQLite cache.

UEPI does not expose arbitrary Python, shell, or console execution. It does not enable other plugins, submit source-control changes, save every project package, or provide unrestricted destructive edits. PIE control is limited to UEPI-owned and authorized Runtime verification flows.

Requirements

• Unreal Engine 5.3.2.
• Python 3.11 or later.
• An MCP client that supports stdio servers.
• A project-local installation at __PROJECT_ROOT__/Plugins/UEProjectIntelligence.

Optional Unreal plugins such as EnhancedInput, GameplayAbilities, Niagara, PCG, CommonUI, StateTree, IKRig, ControlRig, and MetaSound are compile-gated and are not all required for a normal project.

Installation

Copy or extract the repository to:

__PROJECT_ROOT__/Plugins/UEProjectIntelligence

Regenerate project files when required, then build the editor target:

& "__UE_ROOT__\Engine\Build\BatchFiles\Build.bat" `
  __PROJECT_NAME__Editor Win64 Development `
  "-Project=__PROJECT_ROOT__\__PROJECT_NAME__.uproject" `
  -WaitMutex -NoHotReloadFromIDE

Open the project. If Unreal reports that the plugin is disabled, enable UEProjectIntelligence in the plugin manager and restart the editor.

Snapshots And Online State

While the editor is open, UEPI publishes a local Bridge session for the active project. The MCP server can read live state and request refreshes for assets relevant to the current question. A full project scan is not required for every connection.

To retain an offline baseline, open Tools > UE Project Intelligence and select Run Snapshot Scan. Snapshot data is stored under:

__PROJECT_ROOT__/Saved/UEProjectIntelligence/store

A targeted commandlet scan can also run while the editor is closed:

& "__UE_ROOT__\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
  "__PROJECT_ROOT__\__PROJECT_NAME__.uproject" `
  -run=UEPIIndex -unattended -nop4 -nosplash -NullRHI `
  -UEPILevel=L2 `
  -UEPIAsset="/Game/Path/To/BP_Player.BP_Player" `
  -UEPIOutput="__PROJECT_ROOT__\Saved\UEProjectIntelligence\l2_scan.json"

Data states:

• saved: reads the latest published saved Snapshot; the editor may be closed.
• live: the editor is online and live observations overlay the saved baseline.
• refresh_requested: the target may have changed and a targeted editor refresh was requested.
• stale: the target may have changed, but no editor is available to process a refresh.

SQLite files are derived caches and can be rebuilt from Snapshot fragments.

MCP Connection

For Codex, preview the configuration first, then apply it to the project-local configuration:

python "__PROJECT_ROOT__/Plugins/UEProjectIntelligence/Tools/setup_codex.py" `
  --project "__PROJECT_ROOT__/__PROJECT_NAME__.uproject"

python "__PROJECT_ROOT__/Plugins/UEProjectIntelligence/Tools/setup_codex.py" `
  --project "__PROJECT_ROOT__/__PROJECT_NAME__.uproject" --apply

Restart Codex after applying the configuration so the MCP process reloads. Resources/codex-config.template.toml can also be copied and edited manually.

Other MCP clients can configure the following command as a stdio server:

python -B "__PROJECT_ROOT__/Plugins/UEProjectIntelligence/Services/uepi/src/uepi/mcp_server.py" `
  --project "__PROJECT_ROOT__/__PROJECT_NAME__.uproject" `
  --tool-profile codex

The MCP client starts this process; no separate daemon is required. An online editor Bridge session determines the active project. When no editor session is available, --project selects the offline Snapshot project.

Suggested Tool Flow

1. Call uepi_status to inspect the project, Snapshot, editor session, and recovery state.
2. Use uepi_overview, uepi_search, or uepi_context to narrow the scope.
3. Use a domain tool for Blueprint, animation, asset, dependency, or World evidence.
4. If UEPI_REFRESH_REQUESTED is returned, wait for the editor to process the targeted refresh and retry.
5. If UEPI_SNAPSHOT_STALE is returned, open the matching project or run a Snapshot/commandlet scan.
6. For a requested modification, discover operations and create one complete Preview before following the returned authorization decision.

MCP Tools

Category	Tools
Status and search	uepi_status, uepi_overview, uepi_search, uepi_context
Asset reads	uepi_asset, uepi_blueprint, uepi_blueprint_trace, uepi_animation, uepi_impact, uepi_diff
Editor reads	uepi_editor, uepi_world, uepi_refresh, uepi_schema
Runtime verification	uepi_runtime_preview, uepi_runtime_approve, uepi_runtime
Recovery	uepi_recovery_inspect, uepi_recovery_finalize, uepi_recovery_discard, uepi_recovery_rollback
Writes	uepi_edit_discover, uepi_edit_preview, uepi_edit_apply, uepi_edit_validate, uepi_edit_rollback

The codex profile exposes read and write tools together so the client can select tools for the task. codex_write_alpha remains only as a compatibility alias for older configurations.

uepi_context supports routes including project_overview, gameplay_input_to_effect, input_to_gameplay, blueprint_behavior, animation_playback, ui_flow, asset_dependency_impact, data_driven_behavior, gas_ability_flow, ai_behavior_flow, and network_replication_flow.

Writes And Recovery

Writes require the editor Bridge, target project, Editor session, and immutable Preview to match. Authorization modes are:

• ReviewEachPlan: the immutable Preview requires one user confirmation.
• TrustedSession: an in-policy Preview can be authorized automatically within the current Editor session.
• TrustedProject: an in-policy Preview can be authorized automatically for the bound project, subject to asset roots, operation domains, risk, and transaction limits.

Repeat preflight, backups, validation, touched-package saving, targeted refresh, diff generation, and action reports remain active in every mode. An unresolved recovery marker blocks new writes. Use uepi_recovery_inspect to compare current files and backups before selecting finalize, discard, or rollback. Discard and rollback affect the available recovery path and must follow the confirmation requirements returned by the tool.

Known Limitations

• The release-qualified engine target is UE5.3.2. Compatibility with other engine versions is not declared.
• The project is in Beta. The write surface is narrower than the read surface and is limited by the operation catalog and authorization policy.
• Animation tools can return static summaries, driver curves, reconstruction profiles, and optional full-pose samples, but they do not calculate the final runtime pose after AnimGraph, Control Rig, IK, physics, and retargeting layers.
• Snapshot updates require the editor or a commandlet. Editor-closed reads use the latest saved data.
• Read results combine static project evidence and controlled runtime observations; they are not a complete proof of game behavior.

See Docs/Known-Limitations.md for the full boundary.

Checks And Documentation

Run the environment check:

python Tools/uepi_doctor.py --project "__PROJECT_ROOT__/__PROJECT_NAME__.uproject"

Run the Snapshot/MCP regression:

python -B Tools/test_snapshot_mcp_v2.py

See Docs/user-guide.md for usage, Docs/troubleshooting.md for diagnostics, and Docs/Releases for recorded release checks.

License

This project is licensed under the MIT License. See LICENSE.