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

package/CHANGELOG.md

@@ -13,6 +13,169 @@ _Nothing yet._
 
 ---
 
+## 🏷️ [0.6.1-beta-b] - 2026-11-08
+
+> [!NOTE]
+> **Beta.** Published as a semver prerelease (`0.6.1-beta-b`) 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.1-beta-a` tag, written from the code diff.
+
+<details>
+<summary><b>🔄 Changed</b></summary>
+
+- **Inputs are held to their contract**: execute refuses a string or object key past its `maxLength`, or past the 1023 characters an FName holds where none is set (code, scripts and prose parameters take more); a vector or color sent as an array must hold exactly the type's numbers; `add_keyframe` requires `property`.
+
+</details>
+
+<details>
+<summary><b>🔧 Fixed</b></summary>
+
+- **Builds**: the plugin builds on macOS again and on UE 5.0 and 5.1, and a source check in CI keeps those compiler traps out.
+- **Crashes**: an overlong tag, name or key and an `add_keyframe` with no `property` no longer close the editor.
+- **Vectors and colors**: Niagara parameters, effect and skeleton `scale`, light, debug shape and texture colors, material vector defaults, blackboard vector and rotator keys and actor location, rotation and scale no longer pad, cut or zero an array that is not exactly their numbers and answer success.
+- **Sequence keys**: an `add_keyframe` Transform whose value keys nothing is refused `INVALID_ARGUMENT` naming the value instead of reading as an unsupported property, a value that wraps `property` or `value` is refused, and every refusal shows a key's whole params (the old example put `property` inside `value`).
+
+</details>
+
+<details>
+<summary><b>⚠️ Migration</b></summary>
+
+- **Long text**: a string over 1023 characters, or over a parameter's own `maxLength`, is refused `OUT_OF_RANGE`; send long text only in the parameters that take it (code, scripts, descriptions, comments, subtitles, widget text).
+- **Vector and color arrays**: send exactly the type's numbers (three for a vector, three or four for a color), or the object form.
+- **Sequence keys**: send `property` beside `value` in `add_keyframe`; a Transform whose value keys nothing answers `INVALID_ARGUMENT`, not `UNSUPPORTED_PROPERTY`.
+
+</details>
+
+<details>
+<summary><b>🔄 Dependencies</b></summary>
+
+- **GitHub Actions**: `github/codeql-action` (init, autobuild, analyze) 4.39.0 → 4.39.2. No npm package changed, and the package still has no runtime dependencies.
+
+</details>
+
+<details>
+<summary><b>📊 Change Statistics</b></summary>
+
+| Metric | Count |
+|--------|-------|
+| Diff range | `v0.6.1-beta-a..v0.6.1-beta-b` |
+| Commits | 12, the version bump and the release cut included |
+| Files changed | 80 (65 hand-written, not counting generated files or line-ending-only changes) |
+| Insertions / deletions | 2,035 / 540 (hand-written: 889 / 101) |
+| Capability records | 489 |
+| Callable `{tool, action}` pairs | 1,658 |
+| C++ domain directories | 58 |
+
+</details>
+
+---
+
+## 🏷️ [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>🔄 Changed</b></summary>
+
+- **Movie Render Queue, Takes and MetaSound are required plugins**: EngineWire links their modules, so enabling it turns them on (left off in a Blueprint-only project, EngineWire did not load on Windows and the editor crashed at startup on macOS).
+- **Write replies pass on only lint errors**: the warnings (unreachable nodes, heavy Tick work) stay in Validate Assets, saves and `validate_assets`, so a graph built one node at a time is not told its newest node never runs.
+- **No-op and mid-compile edits are refused**: an edit that changes nothing is refused instead of answered done, and so is any edit while a Live Coding compile runs.
+- **Scopes follow what a call writes**: `export_level` needs `write`, and `export_mesh` `outputPath`, `screenshot` `path` and `get_transform` (`sample_motion`) `inputs` raise a call to `write`.
+
+</details>
+
+<details>
+<summary><b>🛡️ Security</b></summary>
+
+- **Native `/mcp` binds to loopback only**, whatever **Allow Non Loopback** says: it has no TLS, so a token would cross the network in clear text. A WebSocket listener on a LAN address needs the capability token and TLS.
+- **The stdio proxy sends its token only to a loopback upstream** unless `UNREAL_MCP_ALLOW_REMOTE_TOKEN=1`, and `doctor` follows the same rule.
+- **A path-restricted token's prefixes hold everywhere**: saves, deletes, reflection reads, searches and listings run as the request's principal, and a file the caller places is written through a handle checked inside the project.
+- **Inputs and consent**: script, search and list inputs are bounded, and a consent grant comes back only when no handler ran.
+
+</details>
+
+<details>
+<summary><b>🔧 Fixed</b></summary>
+
+- **Plugin loading**: geometry and skinning actions refuse with `GEOMETRYSCRIPTING_PLUGIN_NOT_ENABLED` while GeometryScripting is off instead of crashing, and 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.
+- **Input**: simulated game keys stay out of the editor's panels.
+- **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; logpoints read an unwired input's own value; the tool says how to get a fresh consent grant.
+- **Undo**: asset edits are one step each (notifies, sockets, physics bodies, blackboard keys, Behavior Trees and more), 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**: `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>
+
+<details>
+<summary><b>⚠️ Migration</b></summary>
+
+- **A client on another machine**: the native server no longer binds to a LAN address. Tunnel to it (`ssh -L 3000:127.0.0.1:3000 <user>@<editor machine>`) and keep `UNREAL_MCP_URL` at `http://127.0.0.1:3000/mcp`; a stdio proxy pointed at another machine sends no token unless `UNREAL_MCP_ALLOW_REMOTE_TOKEN=1`. A WebSocket listener on a LAN address also needs **Enable Tls**.
+- **Scoped tokens**: a token without `write` no longer runs `export_level`, nor `export_mesh` with `outputPath`, `screenshot` with `path` or `get_transform` with `inputs`.
+- **Projects that turned off Movie Render Queue, Takes or MetaSound**: enabling EngineWire turns them on again.
+- **Lint warnings after a write**: read them with `lint_blueprint` or `validate_assets`; write replies carry only lint errors.
+
+</details>
+
+<details>
+<summary><b>🔄 Dependencies</b></summary>
+
+- None: no npm package and no GitHub Action changed, and the package still has no runtime dependencies.
+
+</details>
+
+<details>
+<summary><b>👥 Contributors</b></summary>
+
+- @SoloGorilla for keeping a created Niagara emitter's requested name (#669), and for reporting the crash when a key was tapped with no play session (#685) and simulated keys reaching editor panels, `sample_motion` inputs included (#686).
+- @claudemlandry for reporting the macOS startup crash on UE 5.7.4 (#705).
+
+</details>
+
+<details>
+<summary><b>📊 Change Statistics</b></summary>
+
+| Metric | Count |
+|--------|-------|
+| Diff range | `v0.6.0..v0.6.1-beta-a` |
+| Commits | 164, the version bump and the release cut included |
+| Files changed | 767 (741 hand-written, not counting generated files or line-ending-only changes) |
+| Insertions / deletions | 43,428 / 5,766 (hand-written: 29,413 / 3,729) |
+| Capability records | 489 |
+| Callable `{tool, action}` pairs | 1,658 |
+| C++ domain directories | 58 |
+
+</details>
+
+---
+
 ## 🏷️ [0.6.0] - 2026-10-27
 
 > [!NOTE]
@@ -83,7 +246,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-b`). 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-b",
   "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-b",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "unreal-engine-mcp-server",
-      "version": "0.6.0",
+      "version": "0.6.1-beta-b",
       "transport": {
         "type": "stdio"
       },