eba71c4ca8
Merge of the two project copies into one self-contained plugin (the superset: variable_op + variables.py, full pcg_op runtime/declarative/preset ops, the CreateWidgetFloatAnimation widget tool, and full Voxel graph authoring). Made fully project- and machine-agnostic — no hardcoded paths: - New src/projectPaths.js auto-detects the host .uproject (walk-up), project name, Editor build target, log file, and engine install (EngineAssociation via launcher manifest/registry, else installed-engine scan). All overridable via UE_* env vars. - Rewired buildOrchestrator/insights/launcher/insightsExporter/server.js and the Python workers (cpp_scaffold, live_coding, apply_graph, console) off the old C:/Github/ihy, IHY*, E:/UE_Versions and UE_5.7 literals onto the resolver. - Voxel made optional: Build.cs auto-detects the Voxel plugin (env UE_MCP_WITH_VOXEL override) and the C++ compiles to stubs under WITH_MCP_VOXEL, so the module builds in projects without Voxel; .uplugin marks Voxel optional. - De-branded the agent-gateway and docs; scrubbed a leaked API key; excluded node_modules/Binaries/Intermediate/__pycache__/secrets from the repo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# Unreal Engine MCP System Plugin
|
|
|
|
A drop-in Unreal Engine **editor plugin** that exposes the UE editor to an
|
|
[MCP](https://modelcontextprotocol.io) client (Claude Code, Cursor, etc.) as a
|
|
rich set of tools: Blueprint graph CRUD, UMG/Slate authoring with a screenshot
|
|
vision loop, materials, Niagara, PCG (incl. PCGEx), assets, member variables,
|
|
C++ scaffolding & rebuild, headless asset/scene capture, Unreal Insights
|
|
analysis, the Project Launcher, and more.
|
|
|
|
It has two halves that ship together:
|
|
|
|
| Part | Lives in | What it is |
|
|
|------|----------|------------|
|
|
| **C++ editor module** | `Source/UEBlueprintMCPEditor/` | `UEBlueprintMCPEditor` — Blueprint function libraries the Python workers call. |
|
|
| **MCP server** | `src/` (Node.js) + `ue_side/` (Python) | A stdio MCP server that drives the editor over Remote Control. |
|
|
|
|
> **Portable by design.** Nothing is hardcoded to a project, user, or machine.
|
|
> The server discovers the host `.uproject`, project name, Editor build target,
|
|
> log file, and engine install automatically from where the plugin sits on disk.
|
|
> Every value can still be overridden with an environment variable (below).
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
1. Clone (or submodule) this repo into your project's `Plugins/` folder. The
|
|
folder name doesn't matter to UE — the plugin is identified by
|
|
`UEBlueprintMCP.uplugin`:
|
|
|
|
```
|
|
<YourProject>/Plugins/UEBlueprintMCP/ <- this repo
|
|
```
|
|
|
|
2. Enable the engine plugins it builds against (most are on by default):
|
|
**Python Editor Script Plugin**, **Remote Control API**, **Niagara**.
|
|
*(Voxel is optional — see below.)*
|
|
|
|
3. Generate project files and build the editor (the plugin has a C++ module).
|
|
|
|
4. In the editor, enable **Remote Control** and start its web server
|
|
(`WebControl.StartServer`, or set `WebControl.EnableServerOnStartup=true`).
|
|
|
|
5. Install the MCP server deps:
|
|
|
|
```bash
|
|
cd Plugins/UEBlueprintMCP
|
|
npm install
|
|
```
|
|
|
|
6. Point your MCP client at `src/server.js`, e.g.:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ue-blueprint": {
|
|
"command": "node",
|
|
"args": ["<abs-path>/Plugins/UEBlueprintMCP/src/server.js"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Call `ping_ue` first to confirm the editor is reachable.
|
|
|
|
---
|
|
|
|
## Zero-config path resolution
|
|
|
|
`src/projectPaths.js` resolves everything from the plugin's location:
|
|
|
|
- **Project** — walks up from the plugin to the nearest `*.uproject`.
|
|
- **Project name / Editor target / log file** — derived from that `.uproject`
|
|
(`<Name>`, `<Name>Editor`, `Saved/Logs/<Name>.log`).
|
|
- **Engine** — read from the project's `EngineAssociation`, resolved via the
|
|
Epic launcher manifest / registry, falling back to a scan of installed
|
|
engines.
|
|
|
|
### Environment overrides
|
|
|
|
| Variable | Overrides |
|
|
|----------|-----------|
|
|
| `UE_PROJECT_DIR` | the `.uproject` parent folder |
|
|
| `UE_UPROJECT_NAME` | e.g. `MyGame.uproject` |
|
|
| `UE_BUILD_TARGET` | e.g. `MyGameEditor` |
|
|
| `UE_BUILD_CONFIG` | build config (default `Development`) |
|
|
| `UE_ENGINE_DIR` | engine root (the folder containing `/Engine`) |
|
|
| `UE_INSIGHTS_EXE` | full path to `UnrealInsights.exe` |
|
|
| `UE_REMOTE_CONTROL_URL` | Remote Control base URL (default `http://127.0.0.1:30010`) |
|
|
| `UE_MCP_WITH_VOXEL` | `1`/`0` to force the optional Voxel integration on/off |
|
|
|
|
---
|
|
|
|
## Optional: Voxel integration
|
|
|
|
The `voxel_graph_op` tool authors [Voxel Plugin](https://voxelplugin.com) graphs.
|
|
Voxel is heavy and most projects don't have it, so the plugin **compiles with or
|
|
without it**:
|
|
|
|
- The build auto-detects the Voxel plugin. If present, voxel support is enabled
|
|
(`WITH_MCP_VOXEL=1`); otherwise the C++ compiles to stubs and `voxel_graph_op`
|
|
returns a "Voxel not enabled" error.
|
|
- Force it with `UE_MCP_WITH_VOXEL=1` (errors if Voxel is missing) or disable
|
|
with `UE_MCP_WITH_VOXEL=0`.
|
|
|
|
---
|
|
|
|
## Optional: in-engine agent gateway
|
|
|
|
`agent-gateway/` is a small HTTP gateway that lets an in-engine WebBrowser widget
|
|
talk to the MCP server through the Claude Agent SDK. It is **not required** for
|
|
MCP clients — see `agent-gateway/README.md`. Copy `agent-gateway/auth.env.example`
|
|
to `agent-gateway/auth.env` and add your token; that file is git-ignored.
|
|
|
|
---
|
|
|
|
## Docs
|
|
|
|
- `UI_WORKFLOW.md` — the mandatory protocol for any UMG/UI work (theme tokens,
|
|
components, the screenshot vision loop).
|
|
- `FUTURE_MCP_TOOLS.md` — backlog of tool ideas.
|