unreal-engine-mcp-server 0.5.21 → 0.6.0-a

package/README.md

@@ -3,7 +3,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![NPM Package](https://img.shields.io/npm/v/unreal-engine-mcp-server)](https://www.npmjs.com/package/unreal-engine-mcp-server)
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-TypeScript-blue)](https://github.com/modelcontextprotocol/sdk)
-[![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.0--5.7-orange)](https://www.unrealengine.com/)
+[![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.0--5.8-orange)](https://www.unrealengine.com/)
 [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Published-green)](https://registry.modelcontextprotocol.io/)
 [![Project Board](https://img.shields.io/badge/Project-Roadmap-blueviolet?logo=github)](https://github.com/users/ChiR24/projects/3)
 [![Discussions](https://img.shields.io/badge/Discussions-Join-brightgreen?logo=github)](https://github.com/ChiR24/Unreal_mcp/discussions)
@@ -18,7 +18,6 @@ A comprehensive Model Context Protocol (MCP) server that enables AI assistants t
 - [Getting Started](#getting-started)
 - [Configuration](#configuration)
 - [Available Tools](#available-tools)
-- [GraphQL API](#graphql-api)
 - [Docker](#docker)
 - [Documentation](#documentation)
 - [Community](#community)
@@ -34,10 +33,10 @@ A comprehensive Model Context Protocol (MCP) server that enables AI assistants t
 | **Asset Management** | Browse, import, duplicate, rename, delete assets; create materials |
 | **Actor Control** | Spawn, delete, transform, physics, tags, components |
 | **Editor Control** | PIE sessions, camera, viewport, screenshots, bookmarks |
-| **Level Management** | Load/save levels, streaming, World Partition, data layers |
+| **Level Management** | Load/save levels, streaming, lighting |
 | **Animation & Physics** | Animation BPs, state machines, ragdolls, vehicles, constraints |
 | **Visual Effects** | Niagara particles, GPU simulations, procedural effects, debug shapes |
-| **Sequencer** | Cinematics, timeline control, camera animations, keyframes |
+| **Sequencer** | Cinematics, timeline control, Movie Render Queue, media, Take Recorder, replay |
 | **Graph Editing** | Blueprint, Niagara, Material, and Behavior Tree graph manipulation |
 | **Audio** | Sound cues, audio components, sound mixes, ambient sounds |
 | **System** | Console commands, UBT, tests, logs, project settings, CVars |
@@ -45,10 +44,12 @@ A comprehensive Model Context Protocol (MCP) server that enables AI assistants t
 ### Architecture
 
 - **Native C++ Automation** — All operations route through the MCP Automation Bridge plugin
+- **Dual Transport** — Native HTTP/SSE (no bridge needed) or WebSocket via TypeScript bridge
 - **Dynamic Type Discovery** — Runtime introspection for lights, debug shapes, and sequencer tracks
 - **Graceful Degradation** — Server starts even without an active Unreal connection
 - **On-Demand Connection** — Retries automation handshakes with exponential backoff
 - **Command Safety** — Blocks dangerous console commands with pattern-based validation
+- **Capability Token Auth** — On-by-default token authentication (auto-generated 32-byte secret at `<Project>/Saved/MCP/capability-token`) for both WS and HTTP transports; manual `CapabilityToken` in Project Settings overrides the file
 - **Asset Caching** — 10-second TTL for improved performance
 - **Metrics Rate Limiting** — Per-IP rate limiting (60 req/min) on Prometheus endpoint
 - **Centralized Configuration** — Unified class aliases and type definitions
@@ -59,17 +60,18 @@ A comprehensive Model Context Protocol (MCP) server that enables AI assistants t
 
 ### Prerequisites
 
-- **Node.js** 18+
-- **Unreal Engine** 5.0–5.7
+- **Node.js 20.19 or later** (Node.js 18 is not supported) — required for the TypeScript stdio bridge. Not needed for the native MCP transport.
 
-### Step 1: Install MCP Server
+### Step 1: Install MCP Server (Option B only — skip for Native MCP)
 
-**Option A: NPX (Recommended)**
+> Skip this step if using **Option A: Native MCP Transport** ([Step 4A](#option-a-native-mcp-transport-direct-http--no-bridge-needed) below).
+
+**NPX (Recommended):**
 ```bash
 npx unreal-engine-mcp-server
 ```
 
-**Option B: Clone & Build**
+**Clone & Build:**
 ```bash
 git clone https://github.com/ChiR24/Unreal_mcp.git
 cd Unreal_mcp
@@ -82,23 +84,51 @@ node dist/cli.js
 
 The MCP Automation Bridge plugin is included at `Unreal_mcp/plugins/McpAutomationBridge`.
 
+#### From source (requires a project with code target)
+
+Your project must have a code target (`.sln` or `.xcworkspace`).
+Blueprint-only projects cannot compile native plugins — to convert, add any class via **Tools > New C++ Class** in the editor.
+
 **Method 1: Copy Folder**
-```
+```text
 Copy:  Unreal_mcp/plugins/McpAutomationBridge/
 To:    YourUnrealProject/Plugins/McpAutomationBridge/
 ```
-Regenerate project files after copying.
 
-**Method 2: Add in Editor**
+**Method 2: External Plugin Directory (no copy needed)**
 1. Open Unreal Editor → **Edit → Plugins**
-2. Click **"Add"** → Browse to `Unreal_mcp/plugins/`
-3. Select the `McpAutomationBridge` folder
+2. Click **Plugin Directories** (bottom-left)
+3. In **Additional Plugin Directories**, add the path to `Unreal_mcp/plugins/`
+4. Restart the editor — the plugin will be picked up from the external location
+
+This saves the path in your `.uproject` file so the plugin stays linked without copying.
+
+The plugin compiles automatically when you open the project — UE detects the `.uplugin` + `Source/` and runs UnrealBuildTool.
 
 **Video Guide:**
 
 https://github.com/user-attachments/assets/d8b86ebc-4364-48c9-9781-de854bf3ef7d
 
-> ⚠️ **First-Time Project Open:** When opening the project directly (double-click `.uproject`) for the first time, UE will prompt *"Would you like to rebuild them now?"* for missing modules. Click **Yes** to rebuild. After the rebuild completes, you may still see: *"Plugin 'McpAutomationBridge' failed to load because module could not be loaded."* This is expected — UE rebuilds successfully but doesn't reload the plugin in the same session. **Simply close and reopen the project** and the plugin will load correctly. Alternatively, build via Visual Studio first to avoid this.
+> ⚠️ **First-Time Project Open:** UE may prompt *"Would you like to rebuild them now?"* — click **Yes**. If instead you see *"Missing Modules — McpAutomationBridge. Engine modules cannot be compiled at runtime. Please build through your IDE."* — open your project in **Visual Studio** (Win) or **Xcode** (Mac) and build from there. After that, the editor will open normally with the plugin loaded.
+
+#### Pre-built (works with any project, including Blueprint-only)
+
+Build the plugin once, then distribute the compiled binaries — no IDE or compilation needed on the target machine.
+
+**1. Build:**
+```bash
+# macOS / Linux
+./scripts/package-plugin.sh /path/to/UE_5.6
+
+# Windows
+scripts\package-plugin.bat C:\Path\To\UE_5.6
+```
+
+This produces a zip like `McpAutomationBridge-v0.5.30-UE5.7-Linux.zip`.
+
+**2. Install:** unzip into `YourProject/Plugins/` and open the project. That's it — no compilation step.
+
+> Note: pre-built binaries are tied to a specific UE version. A build for 5.6 won't work with 5.5, 5.7, or 5.8.
 
 ### Step 3: Enable Required Plugins
 
@@ -110,8 +140,11 @@ Enable via **Edit → Plugins**, then restart the editor.
 | Plugin | Required For |
 |--------|--------------|
 | **MCP Automation Bridge** | All automation operations |
+| **Python Editor Script Plugin** | Python-backed editor automation helpers |
 | **Editor Scripting Utilities** | Asset/Actor subsystem operations |
 | **Niagara** | Visual effects and particle systems |
+| **Gameplay Abilities** | `manage_gas` operations |
+| **Smart Objects** | AI smart object operations |
 
 </details>
 
@@ -121,19 +154,22 @@ Enable via **Edit → Plugins**, then restart the editor.
 | Plugin | Required For |
 |--------|--------------|
 | **Level Sequence Editor** | `manage_sequence` operations |
+| **Movie Render Pipeline** | `manage_sequence` Movie Render Queue operations |
+| **Movie Pipeline Mask Render Pass** | Object-ID render pass |
+| **Takes** | `manage_sequence` Take Recorder operations |
+| **Electra Player** | `manage_sequence` file-backed media playback |
 | **Control Rig** | `animation_physics` operations |
 | **GeometryScripting** | `manage_geometry` operations |
-| **Behavior Tree Editor** | `manage_behavior_tree` operations |
+| **Behavior Tree Editor** | `manage_ai` Behavior Tree operations |
 | **Niagara Editor** | Niagara authoring |
 | **Environment Query Editor** | AI/EQS operations |
-| **Gameplay Abilities** | `manage_gas` operations |
 | **MetaSound** | `manage_audio` MetaSound authoring |
 | **StateTree** | `manage_ai` State Tree operations |
-| **Smart Objects** | AI smart object operations |
-| **Enhanced Input** | `manage_input` operations |
+| **Enhanced Input** | `manage_networking` input mapping operations |
 | **Chaos Cloth** | Cloth simulation |
 | **Interchange** | Asset import/export |
 | **Data Validation** | Data validation |
+| **PCG** | `manage_pcg` graph authoring and execution when enabled for the build |
 | **Procedural Mesh Component** | Procedural geometry |
 | **OnlineSubsystem** | Session/networking operations |
 | **OnlineSubsystemUtils** | Session/networking operations |
@@ -141,9 +177,74 @@ Enable via **Edit → Plugins**, then restart the editor.
 </details>
 
 > 💡 Optional plugins are auto-enabled by the MCP Automation Bridge plugin when needed.
+> PCG support is compiled for source projects when the project explicitly enables PCG. Versioned release packages for UE 5.2+ include PCG support. All Unreal Engine versions from 5.0 to 5.8 are supported and working.
 
 ### Step 4: Configure MCP Client
 
+#### Option A: Native MCP Transport (Direct HTTP — no bridge needed)
+
+The plugin includes a built-in MCP Streamable HTTP server. AI clients connect directly to the plugin over HTTP — no TypeScript bridge, no Node.js, no npm.
+**Note:** the `bAllowNonLoopback` setting now applies to **both** the WebSocket bridge and the native MCP transport. Enabling it binds both surfaces to non-loopback addresses. If you only need LAN access for the WebSocket bridge, do not enable `bAllowNonLoopback` and instead expose the bridge via a reverse proxy. Capability token auth is on by default (0.5.30+) — both transports require authentication automatically. A manually configured `CapabilityToken` in Project Settings or the auto-generated token at `<Project>/Saved/MCP/capability-token` is used automatically.
+
+**Enable in Unreal:**
+1. **Edit > Project Settings > Plugins > MCP Automation Bridge**
+2. Check **Enable Native MCP**
+3. Set port (default: `3000`)
+4. Optionally set **Native MCP Instructions** for project-specific guidance
+5. Restart the editor
+
+**Configure your MCP client** to use Streamable HTTP transport at:
+```
+http://localhost:3000/mcp
+```
+
+**Claude Code:**
+```bash
+claude mcp add unreal-engine --transport http http://localhost:3000/mcp
+```
+
+Or manually in `~/.claude/settings.json` or project `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "unreal-engine": {
+      "type": "url",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "unreal-engine": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+**Verify it works:**
+- **Status bar** — look for `● MCP :3000 (2)` in the bottom-right of the editor. Green dot = server running, number in parens = active sessions. Click it to open settings.
+- **Output Log** — filter by `LogMcpNativeTransport` to see connections, tool calls, and session activity:
+  ```
+  LogMcpNativeTransport: Native MCP server started on http://localhost:3000/mcp
+  LogMcpNativeTransport: MCP session initialized: ... (client: claude-code 2.1.92, active sessions: 1)
+  LogMcpNativeTransport: tools/call: inspect (RequestId=...)
+  LogMcpNativeTransport: tools/call completed: ... (tool=inspect, success=true)
+  ```
+
+Features:
+- SSE streaming for real-time progress during long operations
+- Multiple concurrent sessions (Cursor + Claude Code + others simultaneously)
+- Dynamic tool management — core tools load by default, enable more via `manage_tools`
+- Python execution via `execute_python` action (inline code or .py files)
+- Capability token authentication — on by default (auto-generated secret at `<Project>/Saved/MCP/capability-token`; manual `CapabilityToken` in Project Settings overrides)
+
+#### Option B: TypeScript Bridge (stdio — classic setup)
+
 Add to your Claude Desktop / Cursor config file:
 
 **Using Clone/Build:**
@@ -200,9 +301,17 @@ MCP_AUTOMATION_ALLOW_NON_LOOPBACK=false
 LOG_LEVEL=info  # debug | info | warn | error
 
 # Optional
-MCP_AUTOMATION_REQUEST_TIMEOUT_MS=120000
+MCP_CONNECTION_TIMEOUT_MS=5000
+MCP_REQUEST_TIMEOUT_MS=120000
 ASSET_LIST_TTL_MS=10000
 
+# Optional Prometheus metrics endpoint
+# Loopback-only by default. Non-loopback metrics requires both explicit opt-in and a token.
+# MCP_METRICS_PORT=9100
+# MCP_METRICS_HOST=127.0.0.1
+# MCP_METRICS_ALLOW_NON_LOOPBACK=false
+# MCP_METRICS_TOKEN=change-me
+
 # Custom content mount points (comma-separated)
 # Plugins with CanContainContent register mount points beyond /Game/.
 # MCP_ADDITIONAL_PATH_PREFIXES=/ProjectObject/,/ProjectAnimation/
@@ -224,76 +333,93 @@ MCP_AUTOMATION_HOST=0.0.0.0
 3. Under **Connection**, set **"Listen Host"** to `0.0.0.0`
 4. Restart the editor
 
-⚠️ **Security Warning:** Enabling LAN access exposes the automation bridge to your local network. Only use on trusted networks with appropriate firewall rules.
+⚠️ **Security Warning:** Enabling LAN access exposes the automation bridge to your local network. Only use on trusted networks with appropriate firewall rules. **Enable capability token authentication** (`Require Capability Token` in project settings) to prevent unauthorized access when using LAN mode.
 
 ---
 
 ## Available Tools
 
-**36 MCP tools** with action-based dispatch for comprehensive Unreal Engine automation.
+The MCP server exposes a single **`unreal`** gateway tool. The 23 canonical parent tools are internal and reachable exclusively through the gateway's four operations: `search`, `describe`, `execute`, and `configure`.
 
-<details>
-<summary><b>Core Tools</b></summary>
+### Gateway Workflow
 
-| Tool | Description |
-|------|-------------|
-| `manage_asset` | Assets, Materials, Render Targets, Behavior Trees |
-| `control_actor` | Spawn, delete, transform, physics, tags |
-| `control_editor` | PIE, Camera, viewport, screenshots |
-| `manage_level` | Load/Save, World Partition, streaming |
-| `system_control` | UBT, Tests, Logs, Project Settings, CVars |
-| `inspect` | Object Introspection |
-| `manage_pipeline` | Build automation, UBT compilation, status checks |
-| `manage_tools` | Dynamic tool management (enable/disable at runtime) |
+1. **`search`** — discover available tools by keyword, category, or action name
+2. **`describe`** — get the exact contract (actions, parameters, schema) for a specific tool
+3. **`execute`** — run one validated action on a canonical tool
+4. **`configure`** — manage internal tool enable/disable state (wraps `manage_tools`)
 
-</details>
+Example call:
 
-<details>
-<summary><b>World Building</b></summary>
+```json
+{
+  "operation": "search",
+  "query": "asset"
+}
+```
 
-| Tool | Description |
-|------|-------------|
-| `manage_lighting` | Spawn lights, GI, shadows, build lighting, list_light_types |
-| `manage_level_structure` | Level creation, sublevels, World Partition, data layers, HLOD |
-| `manage_volumes` | Trigger volumes, blocking, physics, audio, navigation volumes |
-| `manage_navigation` | NavMesh settings, nav modifiers, nav links, smart links, pathfinding |
-| `build_environment` | Landscape, Foliage, Procedural |
-| `manage_splines` | Spline creation, spline mesh deformation |
+Then:
 
-</details>
+```json
+{
+  "operation": "describe",
+  "tool": "manage_asset",
+  "action": "import_asset"
+}
+```
 
-<details>
-<summary><b>Animation & Physics</b></summary>
+Then:
 
-| Tool | Description |
-|------|-------------|
-| `animation_physics` | Animation BPs, Vehicles, Ragdolls, Control Rig, IK, Blend Spaces |
-| `manage_skeleton` | Skeleton, sockets, physics assets, cloth binding |
-| `manage_geometry` | Procedural mesh creation (Geometry Script) |
+```json
+{
+  "operation": "execute",
+  "tool": "manage_asset",
+  "action": "import_asset",
+  "params": { "sourcePath": "/path/to/asset.fbx", "destinationPath": "/Game/Imported/asset" }
+}
+```
 
-</details>
+### Migration from direct tool calls
+
+The single `unreal` gateway is permanent on both transports; there is no opt-out and no legacy 23-tool listing to restore. A client that still calls a canonical tool name directly (`tools/call` with `name: "manage_asset"`, `name: "control_actor"`, etc.) receives a bounded, copy-paste-executable `DIRECT_TOOL_CALL_REMOVED` receipt instead of a routed call. The receipt carries a `nextCall` that drills exactly one level: `{ "operation": "search" }` for an unknown name, `{ "operation": "describe", "tool": "<tool>" }` when no action was supplied, or `{ "operation": "execute", "tool": "<tool>", "action": "<action>", "params": { ... } }` when the direct call already named an action. Run that `nextCall` through the `unreal` tool to finish the migration.
+
+### Gateway Protocol & Transport
+
+Both transports expose the same `unreal` gateway contract, but they are separate lifecycles. Do not route around their boundaries.
+
+- **TypeScript stdio transport** — `node dist/cli.js` talks to the Unreal plugin over a WebSocket bridge. It permanently exposes the single `unreal` gateway tool; there is no gateway-mode toggle.
+- **Native MCP transport** — the plugin's built-in Streamable HTTP/SSE server at `/mcp` (no Node.js, no bridge). The native MCP surface permanently exposes the same single `unreal` gateway tool; there is no gateway-mode toggle.
+
+Both surfaces negotiate the MCP protocol version at `initialize`; the supported set is intentionally asymmetric. The native `/mcp` transport supports exactly the three modern versions `2025-11-25`, `2025-06-18`, and `2025-03-26`, and deliberately does not implement the later `2026-07-28` RC. The TypeScript stdio server also accepts the two legacy versions `2024-11-05` and `2024-10-07`, so the native surface is intentionally stricter. Both negotiate down to the highest mutually supported version (`2025-11-25` is the latest). See [docs/protocol.md](docs/protocol.md) for the full negotiation and transport contract, including the `MCP-Protocol-Version` header guard (HTTP 400 on invalid), cancellation semantics, and `progressToken` handling.
+
+### Internal Canonical Tools (23)
+
+The gateway hides these 23 canonical parent tools. They are listed here for reference:
 
 <details>
-<summary><b>Visuals & Effects</b></summary>
+<summary><b>Core Tools</b></summary>
 
 | Tool | Description |
 |------|-------------|
-| `manage_effect` | Niagara, Particles, Debug Shapes, GPU simulations |
-| `manage_material_authoring` | Material creation, expressions, landscape layers |
-| `manage_texture` | Texture creation, modification, compression settings |
-| `manage_blueprint` | Create, SCS, Graph Editing, Node manipulation |
-| `manage_sequence` | Sequencer / Cinematics, list_track_types |
-| `manage_performance` | Profiling, optimization, scalability |
+| `manage_asset` | Assets, Materials, Render Targets, Behavior Trees, Blueprint Struct (UserDefinedStruct) authoring |
+| `manage_blueprint` | Blueprints, SCS components, graph editing, UMG widgets, layout, bindings, animations |
+| `control_actor` | Spawn, delete, transform, physics, tags |
+| `control_editor` | PIE, Camera, viewport, screenshots |
+| `manage_level` | Load/save, streaming, lighting |
+| `system_control` | UBT, Tests, Logs, Project Settings, CVars, Python Execution |
+| `inspect` | Object Introspection |
+| `manage_tools` | Dynamic tool management (enable/disable at runtime) |
 
 </details>
 
 <details>
-<summary><b>Audio & Input</b></summary>
+<summary><b>World Building</b></summary>
 
 | Tool | Description |
 |------|-------------|
-| `manage_audio` | Audio Assets, Components, Sound Cues, MetaSounds, Attenuation |
-| `manage_input` | Enhanced Input Actions & Contexts |
+| `build_environment` | Landscapes, foliage, procedural terrain, lighting, spline roads/rivers/fences |
+| `manage_level_structure` | Levels, sublevels, World Partition, streaming, data layers, HLOD, volumes |
+| `manage_geometry` | Procedural mesh creation and editing with Geometry Script |
+| `manage_pcg` | PCG graph assets, subgraphs, input/sampler/filter/spawner nodes, pin connections, execution, partition grid size, and node settings |
 
 </details>
 
@@ -302,25 +428,25 @@ MCP_AUTOMATION_HOST=0.0.0.0
 
 | Tool | Description |
 |------|-------------|
-| `manage_behavior_tree` | Behavior Tree Graph Editing |
-| `manage_ai` | AI controllers, EQS, perception, State Trees, Smart Objects |
+| `animation_physics` | Animation BPs, skeletons, sockets, physics assets, cloth, vehicles, ragdolls, Control Rig, IK |
+| `manage_effect` | Niagara, particles, debug shapes, GPU simulations |
 | `manage_gas` | Gameplay Ability System: abilities, effects, attributes |
 | `manage_character` | Character creation, movement, advanced locomotion |
 | `manage_combat` | Weapons, projectiles, damage, melee combat |
+| `manage_ai` | AI controllers, Behavior Trees, EQS, perception, State Trees, Smart Objects, NavMesh/pathfinding |
 | `manage_inventory` | Items, equipment, loot tables, crafting |
 | `manage_interaction` | Interactables, destructibles, triggers |
-| `manage_widget_authoring` | UMG widget creation, layout, styling, animations |
 
 </details>
 
 <details>
-<summary><b>Networking & Sessions</b></summary>
+<summary><b>Utility</b></summary>
 
 | Tool | Description |
 |------|-------------|
-| `manage_networking` | Replication, RPCs, network prediction |
-| `manage_game_framework` | Game modes, game states, player controllers, match flow |
-| `manage_sessions` | Sessions, split-screen, LAN, voice chat |
+| `manage_audio` | Audio Assets, Components, Sound Cues, MetaSounds, Attenuation |
+| `manage_sequence` | Sequencer, cinematics, Movie Render Queue, media playback, Take Recorder, and replay controls |
+| `manage_networking` | Replication, RPCs, network prediction, sessions, split-screen, LAN/voice, game framework, input mappings |
 
 </details>
 ### Supported Asset Types
@@ -329,19 +455,6 @@ Blueprints • Materials • Textures • Static Meshes • Skeletal Meshes •
 
 ---
 
-## GraphQL API
-
-Optional GraphQL endpoint for complex queries. **Disabled by default.**
-
-```env
-GRAPHQL_ENABLED=true
-GRAPHQL_PORT=4000
-```
-
-See [GraphQL API Documentation](docs/GraphQL-API.md).
-
----
-
 ## Docker
 
 ```bash
@@ -356,10 +469,9 @@ docker run -it --rm -e UE_PROJECT_PATH=/project unreal-mcp
 | Document | Description |
 |----------|-------------|
 | [Handler Mappings](docs/handler-mapping.md) | TypeScript to C++ routing |
-| [GraphQL API](docs/GraphQL-API.md) | Query and mutation reference |
 | [Plugin Extension](docs/editor-plugin-extension.md) | C++ plugin architecture |
 | [Testing Guide](docs/testing-guide.md) | How to run and write tests |
-| [Roadmap](docs/Roadmap.md) | Development phases |
+| [Roadmap](docs/Roadmap.md) | Development roadmap |
 
 
 ---
@@ -367,19 +479,38 @@ docker run -it --rm -e UE_PROJECT_PATH=/project unreal-mcp
 ## Development
 
 ```bash
-npm run build       # Build TypeScript
-npm run lint        # Run ESLint
-npm run test:unit   # Run unit tests
-npm run test:all    # Run all tests
+npm run build         # Clean + compile TypeScript to dist/
+npm run lint          # Run ESLint 9 (fail on any warning)
+npm run type-check    # tsc --noEmit
+npm run test:unit     # Vitest unit tests (no Unreal required)
+npm run test:smoke    # Offline mock in-memory MCP check (needs built dist/)
+npm run manifest:check   # Fail if generated gateway manifest artifacts drift
+npm run test:native-parity # TS vs native canonical tool/action equality
+npm run test:params      # Parity + strict parameter audit
+npm run version:check    # Assert all version sources agree
+npm test                 # Integration suite (needs a live Unreal Editor + bridge)
 ```
 
+### Gateway manifest generation
+
+The neutral gateway manifest is generated from `src/tools/catalog/consolidated-tool-definitions.ts` into three artifacts (runtime `.ts`/`.json` plus the native `.h`). Never hand-edit the generated files.
+
+```bash
+node --loader ts-node/esm scripts/generate-gateway-manifest.ts          # regenerate
+node --loader ts-node/esm scripts/generate-gateway-manifest.ts --check  # CI gate: fail on drift
+```
+
+### CI gates
+
+CI runs, in order: ESLint 9 (`npx eslint . --max-warnings=0`), TypeScript type-check, unit tests, `registry:check`, `normalization:check`, `manifest:check`, `policy:check`, native parity + parameter audit (`test:params`), `migration:check`, `primitives:check`, `security:check`, `eval:check`, `version:check`, `workflow:check`, then a blocking runtime-only dependency audit (`npm audit --omit=dev --audit-level=high`) followed by an informational full-tree `npm audit --audit-level=moderate`. A plugin packaging job runs `scripts/package-plugin.sh` only when an Unreal Engine source root secret is provided (opt-in), because CI runners do not ship an engine. Release archives exclude `Binaries/`, `Intermediate/`, and `Saved/` so generated build dirs never leak.
+
 ---
 
 ## Community
 
 | Resource | Description |
 |----------|-------------|
-| [Project Roadmap](https://github.com/users/ChiR24/projects/3) | Track development progress across 47 phases |
+| [Project Roadmap](https://github.com/users/ChiR24/projects/3) | Track roadmap progress and priorities |
 | [Discussions](https://github.com/ChiR24/Unreal_mcp/discussions) | Ask questions, share ideas, get help |
 | [Issues](https://github.com/ChiR24/Unreal_mcp/issues) | Report bugs and request features |
 
@@ -397,3 +528,4 @@ Contributions welcome! Please:
 ## License
 
 MIT — See [LICENSE](LICENSE)
+

package/dist/automation/bridge-client.d.ts

@@ -0,0 +1,38 @@
+import type { Logger } from '../utils/logging/logger.js';
+import { type AutomationBridgeResolvedConfig } from './bridge-config.js';
+import type { AutomationBridgeRuntimeState } from './bridge-state.js';
+import type { ConnectionManager } from './connection-manager.js';
+import type { HandshakeHandler } from './handshake.js';
+import type { MessageHandler } from './message-handler.js';
+import type { AutomationBridgeEvents, AutomationBridgeMessage } from './types.js';
+interface AutomationBridgeClientDependencies {
+    readonly config: AutomationBridgeResolvedConfig;
+    readonly state: AutomationBridgeRuntimeState;
+    readonly connectionManager: ConnectionManager;
+    readonly handshakeHandler: HandshakeHandler;
+    readonly messageHandler: MessageHandler;
+    readonly log: Logger;
+    readonly emit: <K extends keyof AutomationBridgeEvents>(event: K, ...args: Parameters<AutomationBridgeEvents[K]>) => void;
+    readonly rejectQueuedRequests: (error: Error) => void;
+    readonly rejectPendingRequests: (error: Error) => void;
+    readonly rejectOwnedRequests: (ownerId: string, error: Error) => number;
+}
+export declare class AutomationBridgeClient {
+    private readonly deps;
+    private pendingConnectionSocket?;
+    private readonly abortedConnectionSockets;
+    constructor(deps: AutomationBridgeClientDependencies);
+    getClientUrl(): string;
+    startClient(): void;
+    abortPendingConnection(): void;
+    send(payload: AutomationBridgeMessage): boolean;
+    broadcast(payload: AutomationBridgeMessage): boolean;
+    private handleClientConnection;
+    private recordHandshakeSuccess;
+    private installMessageHandler;
+    private clearPendingConnection;
+    private redactPeerText;
+    private redactPeerError;
+}
+export {};
+//# sourceMappingURL=bridge-client.d.ts.map

package/dist/automation/bridge-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-client.d.ts","sourceRoot":"","sources":["../../src/automation/bridge-client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,KAAK,8BAA8B,EAAoB,MAAM,oBAAoB,CAAC;AAE3F,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAMvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAOlF,UAAU,kCAAkC;IACxC,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,4BAA4B,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,MAAM,sBAAsB,EAClD,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,UAAU,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,KAC7C,IAAI,CAAC;IACV,QAAQ,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtD,QAAQ,CAAC,qBAAqB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACvD,QAAQ,CAAC,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;CAC3E;AAED,qBAAa,sBAAsB;IAInB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,uBAAuB,CAAC,CAAY;IAC5C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAA4B;gBAExC,IAAI,EAAE,kCAAkC;IAE9D,YAAY,IAAI,MAAM;IAKtB,WAAW,IAAI,IAAI;IA6BnB,sBAAsB,IAAI,IAAI;IAc9B,IAAI,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO;IAmB/C,SAAS,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO;YAuB7C,sBAAsB;IAkEpC,OAAO,CAAC,sBAAsB;IAyB9B,OAAO,CAAC,qBAAqB;IAiC7B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,eAAe;CAM1B"}