unreal-engine-mcp-system-plugin/README.md

# 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. **Run the setup wizard** — it installs deps, confirms the auto-detected
   project/engine, checks the editor side, and prints the exact client-config
   snippet to paste:

   ```bash
   cd Plugins/UEBlueprintMCP
   npm run setup
   ```

   (Prefer to do it by hand? `npm install`, then point your client at
   `src/server.js` as below.)

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.

### In-editor setup wizard (Slate)

The C++ editor module adds a native wizard tab: **Tools → MCP Setup Wizard**. It
lets you, without leaving Unreal:

- see whether the Remote Control bridge (`:30010`) is up, and **start it** with one
  click (`WebControl.StartServer` + enable-on-startup);
- paste & save the agent-gateway API keys (Anthropic token, ElevenLabs) into the
  git-ignored `agent-gateway/` files;
- browse the list of MCP tools this server exposes (from `tools.json`).

Regenerate the tools list after changing the catalogue with `npm run dump-tools`.

### First-run check & `doctor`

The first time the server starts it prints a one-time environment check to its
stderr (visible in your client's MCP logs) and points you at `npm run setup` if
anything is off. You can re-run the checks any time:

- `npm run doctor` — print the diagnostics report in a terminal.
- the **`doctor`** MCP tool — same checks from inside a session, so the assistant
  can diagnose and guide you.

The wizard pins any overrides (project dir, engine dir, Remote Control URL, ...)
to a git-ignored `mcp.config.json`. Precedence everywhere is **env var > config >
auto-detect**.

---

## 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.