unreal-engine-mcp-server 0.6.0 → 0.6.1-beta-a

package/CHANGELOG.md

@@ -13,6 +13,55 @@ _Nothing yet._
 
 ---
 
+## 🏷️ [0.6.1-beta-a] - 2026-11-06
+
+> [!NOTE]
+> **Beta.** Published as a semver prerelease (`0.6.1-beta-a`) under the npm `beta` dist-tag, so `npm install` keeps serving the newest stable release, **`0.6.0`**. This section is everything on `dev` since the `v0.6.0` tag, written from the code diff.
+
+<details>
+<summary><b>✨ Added</b></summary>
+
+- **Engine versions**: a capability an older engine cannot run reads `unavailable` and is refused `ENGINE_VERSION_UNSUPPORTED` (Geometry Script 5.1, MetaSound graph reads and skinning 5.5, retargeting 5.8).
+- **Search and execute**: a typo is read as the word meant (`corrected`), `options.aggregate` counts a long list by group, and an alias sent as tool + action resolves.
+- **Blueprints**: `lint_blueprint` follows values (a divisor that can be 0, an index past the end, a Set outside a Value Range, `==` on computed floats, a decided Branch, an endless While); `fuzz_blueprint` calls a Blueprint's functions in Play with edge-case inputs and names each error's node; MVVM viewmodels (UE 5.4+); `add_variable` `exposeToCinematics`.
+- **Graph as code**: `read_graph_as_code` `entry` and `codeOnly`; `write_graph_from_code` reads back only what it wrote.
+- **Views and cameras**: `camera` looks through a camera actor (`screenshot`, `describe_view`, `analyze_view`, `audit_materials`); `pause` and `list_track_keys` name each cut's camera; `screenshot` `renderSize` and `pathTraced` (a denoised path-traced image); `fov` on every view read.
+- **Plugins and project**: `get_plugin_info`, `create_plugin` / `remove_plugin`, game features (UE 5.1+), data registries, an unused-asset report, `set_project_thumbnail`, `get_console_variables`, `remove_cpp_class`.
+- **Editor**: `read_editor_ui`, `configure_editor` `close_tab`, `set_selected_actors`, viewport `show_flags`, `reimport` without a dialog, `set_current_level`, `console_command` `filter`.
+- **Actors**: snap to grid, distribute, align, lock, group, randomize, replace, convert to a Blueprint, move to a level, numbered rename, copies along a spline, `place_decals`; `list` `bounds` and `find` locations; `sample_motion` `feel` (jump, run, key latency, camera jerk).
+- **Sequences**: `add_actors` `rebind` points a sequence copied with its level at the new level's actors; `add_behaviour` `sequence_trigger` plays one when the player walks in.
+- **Geometry**: `append_tubes`, `append_polygons` `repeat` and `bake_vertex_colors` `coarseShare`.
+- **Look and sound**: material `color` / `glow`, light `flicker`, a first-person view, `sound_trigger`, subtitles, sound volume and looping, footsteps, animation play rate, `massKg`.
+- **Scripts and sheets**: `run_script` takes `(if cond a b)` as a value and waits within `deadlineMs` for a call that answers later; contact and thumbnail sheets take `keepFile: false`.
+- **Frame budget**: `fit_frame_budget` finds which lights' shadows and far small meshes to turn down to meet a GPU frame time at the least change to the picture, and keeps them as one undo step.
+- **Proxy CLI**: `init <client>` writes a client's MCP config; `doctor` checks the setup (the token is never shown).
+
+</details>
+
+<details>
+<summary><b>🔧 Fixed</b></summary>
+
+- **Security**: hardening across the transports (native `/mcp` never binds off loopback; a LAN WebSocket bind needs the token and TLS), the path model (a path-restricted token's prefixes hold in every save, delete, search and listing), scopes and request inputs; a consent grant comes back only when nothing ran; the proxy sends its token only to a loopback upstream.
+- **Plugin loading**: Movie Render Queue, Takes and MetaSound are required plugin references (left off in a Blueprint-only project, EngineWire did not load on Windows and the editor crashed at startup on macOS); geometry and skinning actions refuse with `GEOMETRYSCRIPTING_PLUGIN_NOT_ENABLED` while GeometryScripting is off instead of crashing; the game features module compiles on UE 5.6 and 5.7.
+- **Crashes**: a glTF or GLB export and a key tapped with no Play session no longer take the editor down.
+- **Search**: about 250 more plain requests find their capability, and an alias a family member declared runs that member.
+- **Replies**: long lists page and aggregate from the reply's `data`; console replies stay short; a script step still running at the deadline says so; write replies pass on only lint errors; logpoints read an unwired input's own value; the tool says how to get a fresh consent grant.
+- **Input**: simulated game keys stay out of the editor, and `sample_motion` inputs need the write scope.
+- **Undo**: asset edits are one step each, an edit that changes nothing is refused instead of answered done, enum undo no longer crashes UE 5.7+, and a script's rollback undoes only its own steps.
+- **Graph as code**: `%`, `==` on text, calls used as values, ids with underscores, custom event calls, other classes' variables, expose-on-spawn inputs, calls on the Blueprint itself and events bound to a delegate write as `read_graph_as_code` prints them.
+- **Placement**: props in a room built as one mesh read as they are; a support with no collision is named; `fix_coplanar` checks each move against the others.
+- **Views**: frame readers warn while shaders, meshes or textures still build; `contact_sheet` draws beside water and titles small sheets in full.
+- **Geometry**: `bevel` and `chamfer` cut whole parts, and material and PolyGroup edits are their own undo steps.
+- **Assets**: `check_mesh` finds parts wound inside out, on skeletal meshes too; FBX imports open no Message Log window and convert units with options; material instances draw their parent; morph targets and skin weight profiles survive rebuilds; output files reach captures, exports and thumbnails.
+- **Editor state**: edits are refused during a Live Coding compile; `save_all` saves streaming sublevels; dry runs no longer compile or save; Blueprint compiles leave placed skeletal meshes posed; Behavior Trees build from their Root.
+- **Niagara**: a created emitter keeps the name it was asked for.
+- **Game framework and materials**: `default_pawn_class` takes `None`, and material pins connect by the short names the material editor shows.
+- **Sequence sections**: a sound section plays in the editor and the game, and adding one is one undo step.
+
+</details>
+
+---
+
 ## 🏷️ [0.6.0] - 2026-10-27
 
 > [!NOTE]
@@ -83,7 +132,7 @@ _Nothing yet._
 - **`manage_effect cleanup`** needs destructive consent and a `filter`, is one undo step and refuses Play; debug shapes clear through `debug_shape`.
 - **Object paths** work in `open_level`, `load` and `add_sublevel`; relative `.t3d` exports land in the project.
 - **Git**: any commit message is safe (a quote could inject options); checkout and submit list skipped paths.
-- **`/mcp` discovery**: search rows, `describe` by domain and family, `cursor` and param `suggestions`.
+- **`/mcp` discovery**: search rows, `describe` by domain and family, `cursor` and param `suggestions`; plain requests ("delete all cubes", "make it rain", "measure distance between actors") reach the capability that answers them.
 - **A disabled tool's `nextCall` turns it back on** (`configure` `enable_tools`).
 
 </details>

package/README.md

@@ -34,7 +34,7 @@
   <a href="https://github.com/ChiR24/Unreal_mcp/discussions"><b>💬 Discussions</b></a>
 </p>
 
-> 📌 **Which version is this?** This README describes **0.6.0**, the stable release: npm `unreal-engine-mcp-server` (`latest`) and the plugin on the [Releases page](https://github.com/ChiR24/Unreal_mcp/releases) and on [Fab](https://www.fab.com/listings/9407137f-14b3-44a8-af0e-e9c6a9c9f6fc). The previous release, **0.5.30**, exposes 23 separate tools instead of one; see [Upgrading from 0.5.x](https://github.com/ChiR24/Unreal_mcp/wiki/Upgrading).
+> 📌 **Which version is this?** This README describes **0.6.0**, the stable release: the plugin on [Fab](https://www.fab.com/listings/9407137f-14b3-44a8-af0e-e9c6a9c9f6fc) and on the [Releases page](https://github.com/ChiR24/Unreal_mcp/releases), and npm `unreal-engine-mcp-server` (`latest`). The previous release, **0.5.30**, exposes 23 separate tools instead of one; staying on a 0.5.30 plugin means pinning `unreal-engine-mcp-server@0.5.30`. See [Upgrading from 0.5.x](https://github.com/ChiR24/Unreal_mcp/wiki/Upgrading).
 
 **Contents** · [What it does](#what-it-does) · [How it works](#how-it-works) · [Quick start](#quick-start) · [The `unreal` tool](#the-unreal-tool) · [Configuration](#configuration) · [Security](#security) · [Engine plugins](#engine-plugins) · [Docker](#docker) · [Documentation](#documentation) · [Development](#development) · [Community](#community)
 
@@ -85,7 +85,7 @@ Run Play-In-Editor with synthetic input, take screenshots the model can see, rea
 </tr>
 </table>
 
-Nearly 400 capabilities in all, behind a single MCP tool. The assistant finds them by searching in plain words, so nobody has to learn their names. The full list is the generated [Action Reference](https://github.com/ChiR24/Unreal_mcp/blob/dev/docs/action-reference.generated.md).
+Over 450 capabilities in all, behind a single MCP tool. The assistant finds them by searching in plain words, so nobody has to learn their names. The full list is the generated [Action Reference](https://github.com/ChiR24/Unreal_mcp/blob/dev/docs/action-reference.generated.md).
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/wiki/ChiR24/Unreal_mcp/assets/screenshots/editor.webp" alt="Unreal Editor 5.8 showing a platformer level built with the MCP; the status bar reads MCP :3000 (1)" width="100%">
@@ -116,7 +116,7 @@ The [Quick Start](https://github.com/ChiR24/Unreal_mcp/wiki/Quick-Start) page wa
 
 ### 1. Add the plugin
 
-**From Fab (no compiler needed).** Get [EngineWire on Fab](https://www.fab.com/listings/9407137f-14b3-44a8-af0e-e9c6a9c9f6fc). In the Epic Games Launcher, open **Unreal Engine › Library › Fab Library**, find **EngineWire** and click **Install to Engine** for your engine version. Open your project, enable **EngineWire** in **Edit › Plugins** and restart the editor. The Fab build ships with the native server off: turn on **Enable Native MCP Server** in **Edit › Project Settings › Plugins › EngineWire › Native MCP** and restart once more. Fab updates follow Epic's review, so the Fab build can trail the newest release here.
+**From Fab (no compiler needed).** Get [EngineWire on Fab](https://www.fab.com/listings/9407137f-14b3-44a8-af0e-e9c6a9c9f6fc). In the Epic Games Launcher, open **Unreal Engine › Library › Fab Library**, find **EngineWire** and click **Install to Engine** for your engine version. Open your project, enable **EngineWire** in **Edit › Plugins** and restart the editor. Fab's 0.6.0 build ships with the native server off: if the status bar reads **`MCP off`**, turn on **Enable Native MCP Server** in **Edit › Project Settings › Plugins › EngineWire › Native MCP** and restart once more. Fab updates follow Epic's review, so the Fab build can trail the newest release here.
 
 **From a release.** Download `EngineWire-plugin-<version>.zip` from the newest release on the [Releases page](https://github.com/ChiR24/Unreal_mcp/releases), and copy the `EngineWire` folder it contains into your project:
 
@@ -141,7 +141,7 @@ Build the plugin once on a machine with the engine and a compiler, then hand out
 node scripts/package-plugin.mjs "C:/Program Files/Epic Games/UE_5.7"
 ```
 
-This writes `build/EngineWire-v<version>-UE5.7-<Platform>.zip`, where `<version>` is the `package.json` version (currently `0.6.0`). Unzip it into `YourProject/Plugins/`. Binaries only work with the engine minor and platform they were built for: a 5.6 build won't load in 5.5, 5.7 or 5.8.
+This writes `build/EngineWire-v<version>-UE5.7-<Platform>.zip`, where `<version>` is the `package.json` version (currently `0.6.1-beta-a`). Unzip it into `YourProject/Plugins/`. Binaries only work with the engine minor and platform they were built for: a 5.6 build won't load in 5.5, 5.7 or 5.8.
 
 </details>
 
@@ -149,7 +149,7 @@ This writes `build/EngineWire-v<version>-UE5.7-<Platform>.zip`, where `<version>
 
 **Route A · Native HTTP (no Node.js)**
 
-1. **Enable Native MCP Server** is on by default (**Edit › Project Settings › Plugins › EngineWire**, port `3000`); the Fab build ships with it off. A project where it is off needs it on and an editor restart.
+1. **Enable Native MCP Server** is on by default (**Edit › Project Settings › Plugins › EngineWire**, port `3000`); Fab's 0.6.0 build ships with it off. A project where it is off needs it on and an editor restart.
 
    <img src="https://raw.githubusercontent.com/wiki/ChiR24/Unreal_mcp/assets/screenshots/settings-native-mcp.png" alt="The Native MCP section of the plugin settings, with Enable Native MCP Server ticked" width="520">
 
@@ -200,6 +200,8 @@ Add this to your client's MCP configuration, for example Claude Desktop's `claud
 }
 ```
 
+Or let the package write it (0.6.1-beta-a and later, so `@beta` until 0.6.1 is the stable release): `npx unreal-engine-mcp-server@beta init claude --project C:/Path/To/YourProject` shows the entry for Claude Code's `.mcp.json` (also `cursor`, `vscode`, `gemini` and `codex`), keeping the file's other servers, and `--write` saves it. `npx unreal-engine-mcp-server@beta doctor` checks Node, the token (never shown), the editor's answer and that both sides run the same version.
+
 `UE_PROJECT_PATH` (the project folder or its `.uproject`) is how the proxy finds the capability token (`MCP_AUTOMATION_CAPABILITY_TOKEN` overrides it). `UNREAL_MCP_URL` points it at another endpoint (default `http://127.0.0.1:3000/mcp`). Pair it with a 0.6 plugin; a 0.5.x plugin serves its 23 separate tools instead of the `unreal` gateway.
 
 ### 3. Try it
@@ -241,7 +243,7 @@ A typical exchange:
 ```
 
 - **Parameters are strict.** An undeclared name is refused with `UNDECLARED_PARAMETER` and the list of allowed names; every error carries an executable `nextCall`.
-- **Deletes need consent.** 62 capabilities (all destructive ones, plus some writes) only run with the `consentGrant` from `describe`, passed back as a top-level `consent` field.
+- **Deletes need consent.** Every destructive capability, plus some risky writes, only runs with the `consentGrant` from `describe`, passed back as a top-level `consent` field.
 - **Names.** A call names the `tool` + `action` pair or a capability id, such as `"capability": "control_actor.spawn"`.
 
 Full reference with real replies: [Using the Gateway](https://github.com/ChiR24/Unreal_mcp/wiki/Using-the-Gateway).
@@ -314,7 +316,7 @@ Most setups touch one setting: `UE_PROJECT_PATH` for Route B; Route A needs none
 
 ## Security
 
-- **Local by default.** Both routes listen on `127.0.0.1` only. LAN access needs **Allow Non Loopback**, and the native server refuses to bind off-loopback unless **Require Capability Token** is on.
+- **Local by default.** Both routes listen on `127.0.0.1` only. The native server never binds off-loopback: it has no TLS, so reach it from another machine through an SSH tunnel (`ssh -L 3000:127.0.0.1:3000`) or a TLS proxy. The WebSocket bridge binds a LAN address only with **Allow Non Loopback**, **Require Capability Token** and **Enable Tls** all on. The proxy sends the token to another machine only with `UNREAL_MCP_ALLOW_REMOTE_TOKEN=1`.
 - **Capability token.** Generated per project at `<Project>/Saved/MCP/capability-token` (a value typed into **Capability Token** overrides it) and compared in constant time. Delete the file and restart the editor to rotate it.
 - **Consent for destructive work.** Deletes and some other writes need a per-call consent grant, which the plugin checks itself.
 - **Guard rails.** Asset paths are limited to `/Game`, `/Engine`, `/Script`, `/Temp` and `/Niagara`, and a content path may also sit under a mount the connected editor reports; arguments the server treats as files (such as `filePath`, and `outputPath` even where it names an asset) never use the reported mounts; console commands that chain or quit the editor are blocked; the plugin's own settings are out of reach of automation.
@@ -337,6 +339,8 @@ The bridge declares its engine-plugin dependencies, so Unreal enables them toget
 | **Niagara** | Visual effects |
 | **Gameplay Abilities** | `manage_gas` |
 | **Smart Objects** | AI smart objects |
+| **Movie Render Pipeline**, **Movie Pipeline Mask Render Pass**, **Takes** | `manage_sequence`: Movie Render Queue and Take Recorder |
+| **MetaSound** | `manage_audio`: MetaSound authoring |
 
 </details>
 
@@ -347,14 +351,16 @@ The bridge declares its engine-plugin dependencies, so Unreal enables them toget
 
 | Plugin | Used for |
 | --- | --- |
-| **Level Sequence Editor**, **Takes**, **Movie Render Pipeline**, **Movie Pipeline Mask Render Pass**, **Electra Player** | `manage_sequence`: Sequencer, Take Recorder, Movie Render Queue, media playback |
+| **Level Sequence Editor**, **Electra Player** | `manage_sequence`: Sequencer, media playback |
 | **Control Rig**, **RigVM**, **IK Rig**, **Animation Data** | `animation_physics`: Control Rig and IK |
 | **Chaos Vehicles**, **Chaos Cloth** | `animation_physics`: vehicles and cloth |
 | **Niagara Editor** | `manage_effect`: Niagara authoring |
 | **Behavior Tree Editor**, **Environment Query Editor**, **StateTree**, **Mass Gameplay** | `manage_ai` |
 | **Geometry Scripting**, **Geometry Processing**, **Mesh Modeling Toolset**, **Procedural Mesh Component** | `manage_geometry` (Catmull-Clark, Loop and bilinear subdivision need Mesh Modeling Toolset) |
 | **PCG** | `manage_pcg`, compiled in only when the project itself enables the PCG plugin |
-| **MetaSound**, **Synthesis** | `manage_audio`: MetaSound authoring |
+| **Game Features** | `system_control`: game feature plugins (listed, activated, made with `create_plugin`) through the `EngineWireGameFeatures` module, loaded only when the project itself enables Game Features (EngineWire never turns it on) |
+| **Data Registry** | `manage_asset`: data registries listed, read and made over data tables, by reflection when the project itself enables Data Registry (EngineWire never turns it on) |
+| **Synthesis** | `manage_audio`: source effect presets |
 | **Enhanced Input**, **Online Subsystem**, **Online Subsystem Utils** | `manage_networking`: input mappings, sessions |
 | **Interchange**, **Interchange OpenUSD**, **Data Validation**, **StructUtils** | Import/export, validation, struct helpers |
 | **Fab**, **Bridge** | Fab asset library access (optional `EngineWireFab` module) |

package/dist/cli.js

@@ -1,5 +1,18 @@
 #!/usr/bin/env node
+import { runDoctor } from './proxy/doctor.js';
+import { runInit } from './proxy/init.js';
 import { startNativeProxy } from './proxy/native-proxy.js';
-startNativeProxy();
-process.stdin.once('end', () => process.exit(0));
+const [command, ...rest] = process.argv.slice(2);
+if (command === 'doctor') {
+    process.exitCode = await runDoctor();
+}
+else if (command === 'init') {
+    const result = runInit(rest);
+    process.stdout.write(`${result.content ? `${result.file}\n\n${result.content}\n` : ''}${result.message}\n`);
+    process.exitCode = result.ok ? 0 : 1;
+}
+else {
+    startNativeProxy();
+    process.stdin.once('end', () => process.exit(0));
+}
 //# sourceMappingURL=cli.js.map

package/dist/proxy/doctor.js

@@ -0,0 +1,94 @@
+import { existsSync } from 'node:fs';
+import { request } from 'node:http';
+import { join } from 'node:path';
+import { PACKAGE } from '../constants.js';
+import { projectRootFromEnv } from '../utils/config/ini-reader.js';
+import { oneLine } from '../utils/logging/logger.js';
+import { readCapabilityToken, sendsTokenTo } from './native-proxy.js';
+const NODE_FLOOR = [20, 19];
+export function nodeLine(version = process.versions.node) {
+    const [major = 0, minor = 0] = version.split('.').map(Number);
+    const fits = major > NODE_FLOOR[0] || (major === NODE_FLOOR[0] && minor >= NODE_FLOOR[1]);
+    return fits ? { level: 'ok', text: `Node ${version}` }
+        : { level: 'FAIL', text: `Node ${version} is older than ${NODE_FLOOR.join('.')}: install Node ${NODE_FLOOR.join('.')} or later` };
+}
+export function tokenLine(token) {
+    if (process.env.MCP_AUTOMATION_CAPABILITY_TOKEN) {
+        return { level: 'ok', text: 'Capability token from MCP_AUTOMATION_CAPABILITY_TOKEN (its value is not shown)' };
+    }
+    const root = projectRootFromEnv();
+    if (!root)
+        return { level: 'warn', text: 'No capability token: set UE_PROJECT_PATH to the project folder (or MCP_AUTOMATION_CAPABILITY_TOKEN)' };
+    if (!existsSync(root))
+        return { level: 'warn', text: `UE_PROJECT_PATH names ${root}, which does not exist` };
+    const file = join(root, 'Saved', 'MCP', 'capability-token');
+    return token ? { level: 'ok', text: `Capability token found in ${file} (its value is not shown)` }
+        : { level: 'warn', text: `No valid token in ${file}: open the project in the editor once, so the plugin writes it` };
+}
+function send(url, method, headers, body = '') {
+    return new Promise((resolve, reject) => {
+        const sent = request(url, { method, agent: false, timeout: 5000, headers: { Connection: 'close', ...headers } }, (reply) => {
+            let text = '';
+            reply.setEncoding('utf8');
+            reply.on('data', (chunk) => { text += chunk; });
+            reply.on('end', () => resolve({ status: reply.statusCode ?? 0, headers: reply.headers, text }));
+            reply.on('error', reject);
+        });
+        sent.on('timeout', () => sent.destroy(new Error('no answer within 5 s')));
+        sent.on('error', reject);
+        sent.end(body);
+    });
+}
+function initializeAnswer(text) {
+    const json = text.trimStart().startsWith('{') ? text : text.split(/\r?\n/u).find((line) => line.startsWith('data:'))?.slice(5) ?? '';
+    try {
+        return JSON.parse(json) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function doctorLines(url = process.env.UNREAL_MCP_URL ?? 'http://127.0.0.1:3000/mcp') {
+    const found = await readCapabilityToken();
+    const lines = [nodeLine(), tokenLine(found)];
+    const token = sendsTokenTo(url) ? found : undefined;
+    if (found && !token) {
+        lines.push({ level: 'warn', text: `${url} is not this machine, so the token is not sent over plain HTTP; set UNREAL_MCP_ALLOW_REMOTE_TOKEN=1 to send it anyway` });
+    }
+    const auth = token ? { 'X-MCP-Capability-Token': token } : {};
+    const body = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-11-25',
+            capabilities: {}, clientInfo: { name: `${PACKAGE.name} doctor`, version: PACKAGE.version } } });
+    let hello;
+    try {
+        hello = await send(url, 'POST', { ...auth, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream',
+            'Content-Length': Buffer.byteLength(body) }, body);
+    }
+    catch (error) {
+        lines.push({ level: 'FAIL', text: `Nothing answers at ${url} (${error instanceof Error ? error.message : String(error)}): start the `
+                + 'editor; if it runs, turn on Project Settings > Plugins > EngineWire > Enable Native MCP Server, or set UNREAL_MCP_URL' });
+        return lines;
+    }
+    const session = hello.headers['mcp-session-id'];
+    if (typeof session === 'string')
+        await send(url, 'DELETE', { ...auth, 'Mcp-Session-Id': session }).catch(() => undefined);
+    const { result, error } = initializeAnswer(hello.text);
+    const server = result?.serverInfo;
+    if (hello.status === 401 || hello.status === 403) {
+        lines.push({ level: 'FAIL', text: `The editor at ${url} refused this client (HTTP ${hello.status}): the token is missing or not this project's` });
+    }
+    else if (!server?.version) {
+        lines.push({ level: 'FAIL', text: `${url} answered HTTP ${hello.status}, ${error?.message ? `refusing: ${oneLine(error.message)}` : 'not an MCP initialize reply'}` });
+    }
+    else {
+        lines.push({ level: 'ok', text: `Editor answers at ${url}: ${oneLine(server.name ?? 'server')} ${oneLine(server.version)}, protocol ${oneLine(result?.protocolVersion ?? '?')}` });
+        lines.push(server.version === PACKAGE.version ? { level: 'ok', text: `Proxy and plugin are both ${PACKAGE.version}` }
+            : { level: 'warn', text: `Proxy ${PACKAGE.version} and plugin ${oneLine(server.version)} differ: update the older one` });
+    }
+    return lines;
+}
+export async function runDoctor(write = (text) => { process.stdout.write(text); }) {
+    const lines = await doctorLines();
+    write(`${PACKAGE.name} ${PACKAGE.version} doctor\n${lines.map((line) => `${line.level.padEnd(4)} ${line.text}`).join('\n')}\n`);
+    return lines.some((line) => line.level === 'FAIL') ? 1 : 0;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/proxy/init.js

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { PACKAGE } from '../constants.js';
+export const CLIENTS = {
+    claude: { file: '.mcp.json', key: 'mcpServers' },
+    cursor: { file: '.cursor/mcp.json', key: 'mcpServers' },
+    vscode: { file: '.vscode/mcp.json', key: 'servers', type: 'stdio' },
+    gemini: { file: '.gemini/settings.json', key: 'mcpServers' },
+    codex: { file: '.codex/config.toml', home: true, toml: true },
+};
+const NAME = 'unreal-engine';
+export function projectFor(argument, cwd, env) {
+    const named = argument ?? env.UE_PROJECT_PATH;
+    if (named)
+        return (isAbsolute(named) ? named : resolve(cwd, named)).replace(/\\/gu, '/');
+    return readdirSync(cwd).some((file) => file.toLowerCase().endsWith('.uproject')) ? cwd.replace(/\\/gu, '/') : undefined;
+}
+export function launch(platform) {
+    const npx = ['-y', PACKAGE.name];
+    return platform === 'win32' ? { command: 'cmd', args: ['/c', 'npx', ...npx] } : { command: 'npx', args: npx };
+}
+export function serverEntry(client, project, platform) {
+    return { ...(client.type ? { type: client.type } : {}), ...launch(platform), ...(project ? { env: { UE_PROJECT_PATH: project } } : {}) };
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export function mergeJson(existing, client, entry) {
+    const text = existing?.replace(/^\uFEFF/u, '').trim();
+    const config = text ? JSON.parse(text) : {};
+    const key = client.key ?? 'mcpServers';
+    const servers = isObject(config) ? config[key] ?? {} : undefined;
+    if (!isObject(config) || !isObject(servers))
+        throw new Error(`not an object with "${key}"`);
+    config[key] = { ...servers, [NAME]: entry };
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+export function tomlBlock(project, platform) {
+    const { command, args } = launch(platform);
+    return `[mcp_servers.${NAME}]\ncommand = ${JSON.stringify(command)}\nargs = [${args.map((arg) => JSON.stringify(arg)).join(', ')}]\n`
+        + (project ? `\n[mcp_servers.${NAME}.env]\nUE_PROJECT_PATH = ${JSON.stringify(project)}\n` : '');
+}
+export function runInit(argv, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    let name;
+    let projectArg;
+    for (let index = 0; index < argv.length; index++) {
+        if (argv[index] === '--project')
+            projectArg = argv[++index];
+        else if (!argv[index].startsWith('--'))
+            name ??= argv[index];
+    }
+    const client = name ? CLIENTS[name] : undefined;
+    if (!client) {
+        return { ok: false, file: '', content: '', written: false, message: `usage: ${PACKAGE.name} init <${Object.keys(CLIENTS).join('|')}> `
+                + '[--project <folder>] [--write]' };
+    }
+    const project = projectFor(projectArg, cwd, env);
+    const file = join(client.home ? options.home ?? homedir() : cwd, client.file);
+    const existing = existsSync(file) ? readFileSync(file, 'utf8') : undefined;
+    let content;
+    if (client.toml) {
+        if (existing && /^\s*\[\s*mcp_servers\s*\.\s*"?unreal-engine"?\s*[\].]/mu.test(existing)) {
+            return { ok: false, file, content: tomlBlock(project, platform), written: false,
+                message: `${file} already has [mcp_servers.${NAME}]; it is left as it is, so edit it to read as above` };
+        }
+        content = `${existing?.trim() ? `${existing.trimEnd()}\n\n` : ''}${tomlBlock(project, platform)}`;
+    }
+    else {
+        try {
+            content = mergeJson(existing, client, serverEntry(client, project, platform));
+        }
+        catch {
+            return { ok: false, file, content: '', written: false,
+                message: `${file} is not a plain JSON object with "${client.key}" (comments?): add the "${NAME}" entry by hand` };
+        }
+    }
+    const write = argv.includes('--write');
+    if (write) {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, content);
+    }
+    const noProject = project ? '' : ' No project folder was found, so UE_PROJECT_PATH is left out: pass --project <folder>.';
+    return { ok: true, file, content, written: write,
+        message: (write ? `Written to ${file}.` : `Not written: run again with --write to save it to ${file}.`) + noProject };
+}
+//# sourceMappingURL=init.js.map

package/dist/proxy/native-proxy.js

@@ -44,6 +44,10 @@ export async function readCapabilityToken() {
         return undefined;
     }
 }
+export function sendsTokenTo(upstream) {
+    const host = new URL(upstream).hostname.replace(/^\[|\]$/gu, '');
+    return /^(localhost|127(\.\d{1,3}){3}|::1)$/u.test(host) || process.env.UNREAL_MCP_ALLOW_REMOTE_TOKEN === '1';
+}
 export function startNativeProxy(options = {}) {
     const upstream = options.upstream ?? process.env.UNREAL_MCP_URL ?? 'http://127.0.0.1:3000/mcp';
     const cacheFile = options.cacheFile ?? process.env.UNREAL_MCP_PROXY_CACHE
@@ -51,6 +55,9 @@ export function startNativeProxy(options = {}) {
     const output = options.output ?? process.stdout;
     const log = new Logger('NativeProxy');
     const token = options.token ?? readCapabilityToken;
+    const sendsToken = sendsTokenTo(upstream);
+    if (!sendsToken)
+        log.warn(`${upstream} is not this machine, so the capability token is not sent over plain HTTP; set UNREAL_MCP_ALLOW_REMOTE_TOKEN=1 to send it anyway.`);
     const notConnected = `NOT_CONNECTED: the Unreal Editor is not running (nothing answers at ${upstream}). `
         + 'Start the editor and call again; this server stays connected, no reconnect is needed. If the editor is '
         + 'running, turn on Project Settings > EngineWire > Enable Native MCP Server and restart it.';
@@ -86,7 +93,7 @@ export function startNativeProxy(options = {}) {
             'Content-Length': Buffer.byteLength(payload),
             ...modern
         };
-        const capabilityToken = await token();
+        const capabilityToken = sendsToken ? await token() : undefined;
         if (capabilityToken)
             headers['X-MCP-Capability-Token'] = capabilityToken;
         if (current) {
@@ -99,6 +106,7 @@ export function startNativeProxy(options = {}) {
                 let reply;
                 let text = '';
                 let pending = '';
+                let scanned = 0;
                 const take = (message) => {
                     if (message.id !== undefined && message.id === body.id && ('result' in message || 'error' in message))
                         reply = message;
@@ -122,10 +130,11 @@ export function startNativeProxy(options = {}) {
                     if (text.length < 2000)
                         text += chunk;
                     pending += chunk.replace(/\r/g, '');
-                    for (let cut = pending.indexOf('\n\n'); cut >= 0; cut = pending.indexOf('\n\n')) {
+                    for (let cut = pending.indexOf('\n\n', scanned); cut >= 0; cut = pending.indexOf('\n\n')) {
                         takeEvent(pending.slice(0, cut));
                         pending = pending.slice(cut + 2);
                     }
+                    scanned = Math.max(0, pending.length - 1);
                 });
                 res.on('end', () => {
                     if (sse && pending.trim())

package/dist/utils/logging/logger.js

@@ -8,6 +8,12 @@ function normalizeLogLevel(value, fallback) {
     const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
     return Object.hasOwn(LOG_LEVEL_ORDER, normalized) ? normalized : fallback;
 }
+export function oneLine(text) {
+    return Array.from(text, (c) => {
+        const code = c.charCodeAt(0);
+        return (code < 0x20 && c !== '\t') || code === 0x7f ? `\\u${code.toString(16).padStart(4, '0')}` : c;
+    }).join('');
+}
 export class Logger {
     scope;
     level;
@@ -20,7 +26,7 @@ export class Logger {
     }
     write(level, args) {
         if (this.isEnabled(level))
-            console.error(`[${this.scope}]`, ...args);
+            console.error(`[${this.scope}]`, ...args.map((arg) => typeof arg === 'string' ? oneLine(arg) : arg));
     }
     debug(...args) { this.write('debug', args); }
     info(...args) { this.write('info', args); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unreal-engine-mcp-server",
-  "version": "0.6.0",
+  "version": "0.6.1-beta-a",
   "mcpName": "io.github.ChiR24/unreal-engine-mcp",
   "description": "EngineWire: an MCP server and Unreal Editor plugin that let AI assistants build in Unreal Engine 5.0-5.8: levels, Blueprints, UI, materials, effects and more.",
   "homepage": "https://enginewire.dev",

package/server.json

@@ -3,13 +3,13 @@
   "name": "io.github.ChiR24/unreal-engine-mcp",
   "description": "EngineWire: drive the Unreal Editor (UE 5.0-5.8): levels, Blueprints, UI, materials, VFX and more.",
   "websiteUrl": "https://enginewire.dev",
-  "version": "0.6.0",
+  "version": "0.6.1-beta-a",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "unreal-engine-mcp-server",
-      "version": "0.6.0",
+      "version": "0.6.1-beta-a",
       "transport": {
         "type": "stdio"
       },