Skip to content

README.zh-CN.md

Latest commit

 

History

History
217 lines (165 loc) · 9.04 KB

README.zh-CN.md

File metadata and controls

217 lines (165 loc) · 9.04 KB
Raw

UnrealEngineMCP

English → README.md 简体中文 ← 你在这里

面向 Unreal Engine 5 编辑器 的 MCP（Model Context Protocol）服务器插件。让 AI 编程助手（opencode、Claude Code 等）通过标准 MCP 工具检查并修改你的 UE 工程——蓝图、资产、Actor、UMG 控件以及任意编辑器状态。

核心设计： 以单个 run_python 工具（在编辑器内执行引擎 Python）作为万能入口，覆盖绝大多数编辑器操作；另配少量便捷读取工具。新增工具非常容易。

架构

AI 助手 (opencode / Claude Code)
        │  MCP stdio（始终在线）
        ▼
unreal-mcp wrapper  (Node.js, Tools/mcp-wrapper/)
        │  • 编辑器未启动时自动拉起
        │  • 发现多个编辑器实例，可指定操作目标
        │  • 把 MCP 调用翻译成极简 HTTP JSON 后端
        ▼
UnrealEngineMCP 插件  (C++，运行在编辑器内)
        │  GET  /api/health
        │  GET  /api/tools
        │  POST /api/tools/call
        ▼
    引擎 Python / 蓝图 / 资产 API

wrapper 是面向客户端的 MCP 服务器，无论编辑器状态如何都保持在线：若没有编辑器在运行，它会自动启动一个（通过工程的 EngineAssociation 注册表键解析引擎路径），等待其就绪后再处理工具调用。若开了多个编辑器，可用 list_instances / select_instance 选择操作对象。

安装

1. 把插件放入工程

把 Plugins/UnrealEngineMCP 复制到工程的 Plugins/ 目录，并在 YourProject.uproject 中启用：

"Plugins": [
  {
    "Name": "UnrealEngineMCP",
    "Enabled": true
  }
]

2. 安装 wrapper 依赖

cd Plugins/UnrealEngineMCP/Tools/mcp-wrapper
npm install

需要 Node.js 18+。若缺少 Node，wrapper 会输出明确提示并指向 https://nodejs.org。

3. 编译插件

编译你的编辑器目标（插件是 Editor-only，不影响打包版本）：

Build.bat YourProjectEditor Win64 Development -Project="D:\YourProject\YourProject.uproject"

4. 把 MCP 客户端指向 wrapper

工程根目录 .mcp.json（opencode 与 Claude Code 通用）：

{
  "mcpServers": {
    "unreal-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["D:\\YourProject\\Plugins\\UnrealEngineMCP\\Tools\\mcp-wrapper\\index.js"],
      "env": { "UE_PROJECT_DIR": "D:\\YourProject" }
    }
  }
}

opencode 全局配置（~/.config/opencode/opencode.json）：

{
  "mcp": {
    "unreal-mcp": {
      "type": "local",
      "command": ["node", "D:\\YourProject\\Plugins\\UnrealEngineMCP\\Tools\\mcp-wrapper\\index.js"],
      "environment": { "UE_PROJECT_DIR": "D:\\YourProject" },
      "enabled": true
    }
  }
}

UE_PROJECT_DIR 可选（wrapper 也能从自身位置向上找到 .uproject），但显式设置更稳妥。

使用

日常怎么用

  • 无需准备：直接调用工具即可。若编辑器没开，wrapper 会自动拉起（首次调用可能需等 1–3 分钟编辑器启动）。之后编辑器保持运行。
  • 多编辑器：开了多个编辑器实例时（如主编辑器 + 预览），wrapper 默认选第一个健康的。调用 list_instances 查看，用 select_instance（传 port 或 pid）切换，后续调用都作用于选中的实例。
  • 自动启动：编辑器启动后插件自动开启 HTTP 后端（端口 8000，冲突则自动顺延）。可在 项目设置 → Plugins → Unreal Engine MCP 关闭或配置。

手动控制服务器（可选）

编辑器控制台（~）：

UnrealEngineMCP.StartServer 8000
UnrealEngineMCP.StopServer

工具

run_python —— 万能入口（优先使用）

在编辑器内执行任意 Python（引擎 Python 插件）。import unreal 可访问一切：蓝图/资产/Actor/UMG 操作、编辑器状态等。用 print() 输出，结果会被捕获返回。

import unreal

# 加载并查看蓝图
bp = unreal.load_asset('/Game/UI/WBP_TipsTileView')
print(bp)

# 列出某目录下的资产
print(unreal.EditorAssetLibrary.list_assets('/Game/UI'))

# 查询关卡 Actor
actors = unreal.EditorLevelLibrary.get_all_level_actors()
print([a.get_actor_label() for a in actors])

便捷工具

工具 说明
list_blueprints 列出工程中的蓝图资产（可传 filter 子串过滤）
get_blueprint 读取蓝图结构：父类、变量（含类型）、函数（传 name 参数）
list_widget_tree 读取 UMG WidgetBlueprint 的控件树（布局层级）：控件名/类型/嵌套（传 name 参数）
get_widget_properties 读取 UMG 控件实例的属性值：类型+当前值，覆盖数值/字符串/枚举/颜色/向量/数组/对象引用等（传 name + 可选 widget）
exec_command 在编辑器所在机器执行 shell 命令：返回合并输出（stdout+stderr）与退出码，60s 超时自动终止（传 command + 可选 working_dir）
create_widget_blueprint 创建 UMG WidgetBlueprint：指定目录/名称/父类（默认 UAirUserWidget）/根控件（传 parent_path + name）
add_widget_to_tree 向 WBP 控件树添加控件：指定父控件/控件类型/名称/可选 slot 参数（传 blueprint + parent_widget + widget_type + name）
set_widget_properties 设置 WBP 控件实例的属性值：JSON 对象按类型反射写入（传 blueprint + widget + properties）
list_assets 列出某路径下的资产，可按 class 或名称子串过滤
list_actors 列出当前关卡的 Actor，可按 class 或标签子串过滤

实例管理工具（由 wrapper 提供）

工具 说明
list_instances 列出所有运行中的编辑器实例（pid/port/project），标注当前选中
select_instance 切换后续调用的目标实例（portOrPid）

项目设置

项目设置 → Plugins → Unreal Engine MCP：

设置 默认 说明
ServerUrlPath /mcp HTTP 路径前缀（内部使用，wrapper 不需要）
ServerPortNumber 8000 起始端口，冲突自动顺延
bAutoStartServer true 编辑器打开时自动启动后端
bListenOnLocalhostOnly true 拒绝非本机客户端（安全项；run_python 会执行任意代码）

新增工具

因为 wrapper 通过 GET /api/tools 自动发现工具并完整转换 JSON Schema → zod，新增工具只需改 C++ 一处，wrapper 无需改动。

  1. 在 Source/UnrealEngineMCPEditor/Private/Tools/ 添加实现 IMCPTool 的工具类： 
    class FMyTool : public IMCPTool
{
    virtual FString GetName() const override { return TEXT("my_tool"); }
    virtual FString GetDescription() const override { return TEXT("..."); }
    virtual TSharedPtr<FJsonObject> GetInputSchema() const override { /* JSON Schema */ }
    virtual FMCPToolResult Run(const TSharedPtr<FJsonObject>& Params) override { /* ... */ }
};
  2. 在 UnrealEngineMCPEditorModule::RegisterBuiltinTools() 注册。
  3. 重新编译。重启 wrapper（或等它的 10 秒重注册重试），工具即出现在 tools/list。

复杂参数 schema（嵌套对象、枚举、数组、数值范围）均由 wrapper 的 JSON Schema → zod 转换完整支持。

目录结构

Plugins/UnrealEngineMCP/
├── UnrealEngineMCP.uplugin
├── Source/
│   ├── UnrealEngineMCP/               # Runtime 模块：极简 HTTP 后端
│   │   ├── MCPServer.h/.cpp           #   /api/health, /api/tools, /api/tools/call + 端口顺延
│   │   ├── MCPTool.h/.cpp             #   IMCPTool 接口 + FMCPToolResult
│   │   ├── MCPToolRegistry.h/.cpp     #   工具注册表
│   │   └── MCPModule.h/.cpp           #   模块 + 控制台命令
│   └── UnrealEngineMCPEditor/         # Editor 模块：工具 + 实例注册
│       ├── UnrealEngineMCPSettings.h  #   项目设置
│       ├── MCPInstanceRegistry.h/.cpp #   Saved/MCP/instances.json
│       └── Private/Tools/             #   run_python, list_blueprints, get_blueprint, ...
└── Tools/mcp-wrapper/                 # Node.js MCP stdio server
    ├── index.js                       #   MCP server + 工具注册 + 代理
    └── lib/                           #   引擎启动器、实例管理、注册表

要求与说明

  • UE 5.7+（使用引擎 HTTPServer 模块；5.7 的 HTTPServer 不支持 SSE 流式，因此插件暴露纯 JSON 端点——MCP 协议/SSE 在 wrapper 中）。
  • Node.js 18+（wrapper 需要）。
  • PythonScriptPlugin 需在编辑器中启用（插件已声明依赖；如遇提示，在 项目设置 → Plugins → Python Script Plugin 启用）。
  • 插件是 Editor-only（Editor 模块类型），不影响打包的游戏版本。
  • 发送给所连 LLM 的数据即你的工程内容——请只运行你信任的 run_python 代码。

许可

工程内部使用。架构设计见 docs/2026-08-04-smart-launch-design.md。