unreal-engine-mcp-server 0.5.20 → 0.5.30

package/CHANGELOG.md

@@ -7,6 +7,256 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## 🏷️ [0.5.30] - 2026-06-05
+
+> [!IMPORTANT]
+> ### 🚀 Native MCP & Code-Backed Tool Parity Release
+> This release covers the `v0.5.21` to `0.5.30` release diff, including the TypeScript MCP server, native bridge plugin, tests, scripts, docs, workflows, and dependency manifests. The summary below is based on code and test changes, not commit subjects alone.
+
+<details>
+<summary><b>✨ Added</b></summary>
+
+- **Native MCP Streamable HTTP endpoint** — added an opt-in in-plugin `/mcp` server with JSON-RPC 2.0 initialize/tools/list/tools/call handling, POST/GET/DELETE routing, `Mcp-Session-Id` session tracking, SSE tool-result streaming, progress notifications, persistent notification streams, `notifications/tools/list_changed` broadcasts, CORS handling, loopback-first binding, capability-token checks, and an editor status-bar indicator.
+- **Self-describing native MCP tools** — added C++ `FMcpToolRegistry`, `FMcpSchemaBuilder`, `MCP_REGISTER_TOOL`, canonical native tool filtering, cached schema generation, and native dynamic tool/category enablement for the 23 canonical parent tools.
+- **PCG automation** — added `manage_pcg` TypeScript/native schemas and handlers for graph/subgraph creation, PCG node aliases, pin connections, reflected node settings, component/world execution, partition grid configuration, save/overwrite behavior, and PCG plugin availability errors.
+- **Environment systems automation** — added build-environment coverage for heightmap import/export, landscape layer info/material/splines/LOD/streaming proxies, foliage type configuration/paint/remove flows, sky and volumetric-cloud setup, weather/wind/time-of-day systems, water bodies, water waves/material/collision, and buoyancy components.
+- **Behavior Tree authoring and introspection** — added `add_subnode`, root-sentinel decorators, decorator/service validation, subnode-aware lookup, `FBlackboardKeySelector` assignment, and `get_tree` runtime hierarchy serialization with root decorators, edge decorators, decorator ops, services, key properties, subtree references, and a success-with-null-root contract for graphless trees.
+- **Blueprint, property, and inspection tools** — added `inspect_cdo`, Class Default Object component/property export, SCS and inherited SCS component classification, typed Blueprint custom-event pins, Enhanced Input graph nodes, inherited variable/member-class graph node lookup, and property access for Blueprint-added SCS component templates.
+- **Editor, world, and input capabilities** — added full editor-window screenshots, game viewport screenshot routing, image content responses, simulated keyboard/mouse input aliases, active camera reporting, PIE runtime inspection, native `get_current_level`, actor material/view-target native actions, spawn scale support, and create-plane height handling.
+- **Material, audio, animation, and system actions** — added Material Function creation/editing/calls/info, FunctionInput/FunctionOutput graph support, source-effect chains and source-effect presets, `force_rebuild_blend_space`, legacy/per-key input mapping edits, project setting writes, native asset validation, and `execute_python` for inline or project-local Python files.
+
+</details>
+
+<details>
+<summary><b>🛡️ Security</b></summary>
+
+- **GraphQL attack surface removed** — deleted the GraphQL server, schema/resolver/loaders, GraphQL docs, GraphQL unit tests, and direct GraphQL runtime dependencies.
+- **Native MCP exposure controls** — default native MCP binding stays loopback-only unless explicitly allowed; non-loopback hosts warn, sessions are validated, stale requests/streams are cleaned up, and native HTTP requests use explicit request-origin routing instead of socket inference.
+- **Capability-token and dynamic-tool protections** — native MCP validates `X-MCP-Capability-Token` when required, while both TypeScript and native dynamic tool managers protect `manage_tools`/`inspect` and protected categories from accidental disablement.
+- **Python execution hardening** — `execute_python` enforces code/file exclusivity, a 1 MB inline code limit, project-root path normalization, symlink escape checks, `__file__` setup for file execution, temp-file cleanup, and direct `PythonScriptPlugin` execution.
+- **Path, command, log, and workflow hardening** — tightened UE path normalization, console-command validation, snapshot/log path handling, level save/load flows, image/log redaction, safe `tmp/` cleanup, sync-script argument parsing, and GitHub Actions interpolation by moving untrusted values into environment variables.
+
+</details>
+
+<details>
+<summary><b>🔧 Changed</b></summary>
+
+- **Release metadata** — updated `package.json`, `package-lock.json`, `server.json`, the `src/index.ts` fallback, and `McpAutomationBridge.uplugin` to `0.5.30`.
+- **Canonical TypeScript tool surface** — kept the 23 parent tools but moved action lists into shared constants, grouped tools into `core`, `world`, `gameplay`, and `utility`, merged nested `params` into top-level arguments for constrained clients, centralized handler routing, and removed legacy per-domain tool files.
+- **Dynamic tool listing** — `tools/list` now checks known client support for `tools.listChanged`; dynamic clients can receive category-filtered tools, while clients without dynamic loading still see the full compatible tool surface.
+- **Automation bridge lifecycle** — refactored host/port parsing, multi-port WebSocket connection attempts, handshake metadata, request queueing, progress timeout extension, stale-progress detection, absolute timeout caps, rate/message-size boundaries, disconnect/error tracking, and image-payload redaction.
+- **Native bridge runtime** — split request dispatch out of the subsystem, added explicit `ERequestOrigin`, queued requests through the game thread, converted captured engine errors into failed responses, pumped GameThread tasks during native transport shutdown, and exposed native transport session/tool counts to UI.
+- **Response and schema handling** — improved response validation, summary text generation, image response content, scalar result promotion, safe JSON cleanup, schema reuse, action-specific parameter descriptions, and stricter error context on tool failures.
+- **Plugin compatibility** — updated bridge metadata for UE 5.8 Preview and added PythonScriptPlugin, StructUtils, Synthesis, and PCG plugin declarations where the new handlers need them.
+- **Scripts and workflows** — made smoke tests run through SDK `InMemoryTransport`, added native parity/parameter audit npm scripts, changed `clean` to remove `tsconfig.tsbuildinfo`, added Linux/macOS/Windows plugin packaging scripts, strengthened sync/cleanup scripts, and made CI/publish/release gates stricter.
+
+</details>
+
+<details>
+<summary><b>🛠️ Fixed</b></summary>
+
+#### Routing & Native Tool Parity
+
+- Fixed native/consolidated action routing for validation, audio creation, material graph pins, editor simulation, `add_widget_child`, `get_current_level`, AnimBP graph discovery, lighting, SCS edits, native actor/editor actions, exact action matching, and nested `params` payloads.
+
+#### Blueprint, Graph & Property Handling
+
+- Fixed inherited UPROPERTY lookup for VariableGet/VariableSet with `memberClass`, stale `K2Node_EnhancedInputAction` title cache refresh, Blueprint SCS component introspection, SCS template get/set paths, typed custom-event pin reconstruction, transaction ordering, null pin checks, case-insensitive pin connections, graph allocation fallback, and Blueprint busy-state cleanup.
+
+#### Editor, World & Gameplay Behavior
+
+- Fixed PIE/game viewport screenshots, full editor screenshot capture, simulated input dispatch, active camera view-state reporting, PIE runtime inspection, spawn scale application, plane height fields, landscape bounds fallback, prompt-save return codes, actor list response handling, editor/world handler stability, and native actor/editor contract alignment.
+
+#### Asset, Level, Animation, Niagara & Audio
+
+- Fixed unloaded level info via AssetRegistry fallback, classNames-only recursive asset search, normalized level path validation, source audio persistence, source-effect routing, audio authoring saves, material expression aliases, material pin routing to main inputs, UMaterialFunction graph details, animation notify validation, BlendSpace grid rebuilds, Niagara crash paths, hollow getters, parameter aliases, FText and FText-array property serialization, and `execute_python` file mode/output capture.
+
+#### Plugin Stability & Compatibility
+
+- Fixed native plugin compatibility across UE versions, macOS Clang audio literal builds, plugin package output detection, bridge socket/runtime handling, JSON key normalization, request telemetry, native MCP session validation, safe operations includes, handler review findings, and optional module/plugin availability paths.
+
+</details>
+
+<details>
+<summary><b>🧪 Tests</b></summary>
+
+- Added/expanded Vitest coverage for automation bridge connection, handshake, message schema, request tracking, config defaults, resources, health/metrics services, response validation, command validation, log reading/redaction, safe JSON, type coercion, normalization, queues, elicitation, and consolidated handler routing.
+- Expanded MCP integration suites across core/world/gameplay/utility tools, including PCG, Behavior Tree subnodes/get-tree, networking/sessions/input, control-editor screenshots/input, actor list handling, audio/source effects, assets/material functions, Blueprints/SCS, levels, geometry, GAS, combat, inventory, interaction, sequence, environment, and system-control Python/project-setting flows.
+- Added static native MCP action parity auditing and strict parameter-combination auditing that compare TypeScript schemas, native C++ tool definitions, native canonical registration, and test coverage.
+- Hardened the custom test runner with richer assertions, captured variables, live/static reports, fake-success detection, progress output, expectation utilities, and deterministic parameter audit behavior.
+
+</details>
+
+<details>
+<summary><b>🧰 Maintenance</b></summary>
+
+- Refreshed AGENTS/project guidance, README/setup content, handler maps, testing guide, native automation progress notes, Roadmap, MCP coverage notes, UE 5.8 support notes, native audio routing notes, plugin READMEs, issue templates, labels, gitignore rules, production env defaults, Context7 config, and release metadata.
+- Removed obsolete GraphQL API docs and GraphQL security tests with the GraphQL implementation.
+- Trimmed unused plugin helpers/includes, streamlined bridge build settings, normalized Node built-in imports, simplified startup cleanup, optimized server utilities/build caching, and improved package/sync/cleanup script safety.
+
+</details>
+
+<details>
+<summary><b>🔄 Dependencies</b></summary>
+
+- Removed direct runtime dependencies for `@graphql-tools/schema`, `dataloader`, `graphql`, and `graphql-yoga`.
+- Refreshed the lockfile across npm dependency groups, including security/maintenance updates for transitive runtime and dev packages.
+- Updated pinned GitHub Actions used by checkout, setup-node, CodeQL, Release Drafter, github-script, action-gh-release, stale, labeler, and dependency-review workflows.
+
+</details>
+
+<details>
+<summary><b>📚 Documentation</b></summary>
+
+- Refreshed root and plugin README content, MCP/native transport setup, handler mapping, editor plugin extension notes, Roadmap, testing guide, native automation progress, MCP coverage notes, UE 5.8 support, and native audio routing notes.
+- Added and updated repository guidance files for root, TypeScript server/tools/handlers/automation/utils/tests, native MCP internals, and McpAutomationBridge areas.
+- Removed obsolete GraphQL API documentation.
+
+</details>
+
+<details>
+<summary><b>👥 Contributors</b></summary>
+
+Special thanks to the contributors in this release window, with obvious author aliases collapsed.
+
+- **GitHub Actions command-injection hardening:** @google-labs-jules[bot]
+- **Dependency and workflow version updates:** @dependabot[bot]
+- **Editor/runtime behavior fixes:** @xqdd for native `get_current_level` routing, spawn scale, create-plane height, lighting routing, Blueprint SCS verification, PIE runtime reporting, active camera state, per-key input mapping edits, and prompt-save return handling.
+- **Behavior Tree and Blueprint introspection:** @kalihman for `get_tree`, decorator/service subnodes, Blackboard key selector assignment, inherited Blueprint/SCS introspection, and classNames-only asset search behavior.
+- **Blueprint graph and animation reliability:** @VictorZhang01 for inherited UPROPERTY graph nodes, stale K2 node title refresh, AnimBP graph routing, and `force_rebuild_blend_space`.
+- **Material and Blueprint component support:** @nekwo for Material Function authoring support and Blueprint-added component template property get/set coverage.
+- **Plugin packaging and inspection:** @azwjp for Windows plugin packaging fixes, and @6r0m for `inspect_cdo` Blueprint CDO inspection.
+- **Platform/build and routing fixes:** @jenniferied for macOS Clang audio-handler build fixes, @Miriam-R-coder for exact Blueprint action routing, and @spencer-zaid for screenshot, Niagara, hollow getter, and parameter-alias fixes.
+- **Python and level metadata fixes:** @zmarx for `execute_python` file-mode handling and Python plugin initialization guards, and @codeman101 for unloaded `get_level_info` AssetRegistry fallback.
+
+</details>
+
+<details>
+<summary><b>📊 Release Statistics</b></summary>
+
+| Metric | Count |
+|--------|-------|
+| Release diff | `v0.5.21..0.5.30` |
+| Files changed | 406 |
+| Insertions | 61,393 |
+| Deletions | 30,957 |
+| TypeScript canonical tools | 23 |
+| Native canonical tools | 23 |
+| Native action parity mismatches | 0 |
+
+</details>
+
+---
+
+## 🏷️ [0.5.21] - 2026-04-03
+
+> [!IMPORTANT]
+> ### 🔒 Security, New Features & Major Crash Fixes
+> This release adds custom content mount points, full audio authoring, project settings management, vehicle physics configuration, blend tree/procedural animation/state machine creation, sequencer improvements, and critical crash prevention for deleting animation/IK assets and folders.
+
+<details>
+<summary><b>🛡️ Security</b></summary>
+
+- **Command Injection in bump-version action** – Sanitized `release-type` input ([#327](https://github.com/ChiR24/Unreal_mcp/pull/327))
+- **Command Injection in editor console commands** – Mixed-context sanitization for `start_recording`, `set_camera_fov`, `set_game_speed` ([#322](https://github.com/ChiR24/Unreal_mcp/pull/322))
+- **Path Traversal in `export_level`** – Added path validation ([#305](https://github.com/ChiR24/Unreal_mcp/pull/305))
+- **Path Traversal in screenshot filename** – Sanitized filenames, blocked traversal patterns ([#314](https://github.com/ChiR24/Unreal_mcp/pull/314))
+- **Synchronous fs Hardening** – Replaced blocking `fs.existsSync` / `fs.readdirSync` with async versions ([#318](https://github.com/ChiR24/Unreal_mcp/pull/318))
+
+</details>
+
+<details>
+<summary><b>✨ Added</b></summary>
+
+- **Custom Content Mount Points** – `MCP_ADDITIONAL_PATH_PREFIXES` to whitelist plugin mount points (`/ProjectObject/`, etc.) ([#326](https://github.com/ChiR24/Unreal_mcp/pull/326) – thanks @6r0m)
+- **Full Audio Authoring** – Create sound waves, sound cues, sound classes, sound mixes, attenuation settings; success flags in responses.
+- **Project Settings Management** – New `manage_project_settings` tool (get/set project settings via config).
+- **Animation Authoring** – `create_blend_tree`, `create_procedural_anim`, `create_state_machine` (C++ implementations, not console commands).
+- **Vehicle Physics Configuration** – `configure_vehicle` with wheels, engine, transmission, mass, drag coefficient.
+- **Sequencer** – `set_tick_resolution`, `set_view_range` actions.
+- **Widget Authoring** – New template widgets: main menu, pause menu, HUD, crosshair, ammo counter, health bar, compass, interaction prompt, objective tracker, damage indicator, inventory grid, dialog box, radial menu, credits scroll, shop UI, quest tracker.
+- **Runtime Module Checks** – Verify GameplayAbilities, EnhancedInput, BehaviorTreeEditor, LevelSequenceEditor, NiagaraEditor, StateTree, SmartObjects, MassEntity are loaded before use (clear error messages when plugins missing).
+
+</details>
+
+<details>
+<summary><b>🛠️ Fixed</b></summary>
+
+#### Crash Prevention (UE 5.7+)
+
+- **Animation/Rig asset deletion** – Completely rewrote `McpSafeDeleteFolder` and added `DeleteAnimationRigClusterOrdered` to prevent 0xFFFFFFFFFFFFFFFF crashes when deleting AnimBlueprints, IKRigs, IKRetargeters, ControlRigBlueprints, and AnimSequences.
+- **Folder deletion** – Replaced `UEditorAssetLibrary::DeleteDirectory` with `McpSafeDeleteFolder` (proper world switching, package unloading, compilation quiesce).
+- **Blueprint creation** – Added pre‑creation checks in `CreateControlRigBlueprint` and widget blueprint creation to prevent engine assertion failures.
+- **Widget creation** – Fixed widget crash ([#306](https://github.com/ChiR24/Unreal_mcp/pull/306)) by adding GUID registration (`RegisterWidgetGuid`) and safe tree replacement (`SafeAddWidgetToTree`).
+- **AnimNotify/NotifyState** – Added abstract class validation and track existence checks.
+
+#### Asset & Path Handling
+
+- Improved asset loading reliability for newly created AI assets (removed stale `DoesAssetExist` checks).
+- Resolved asset query parameter bugs and expanded `classNames` support ([#311](https://github.com/ChiR24/Unreal_mcp/pull/311)).
+- Replaced custom asset directory checks with `UEditorAssetLibrary` to avoid stale cache issues.
+- Fixed `searchText` filtering in `search_assets` action ([#308](https://github.com/ChiR24/Unreal_mcp/pull/308)).
+- Added `offset` pagination to asset search.
+
+#### Blueprint & Graph Editing
+
+- Unified pin serialization across blueprint graph handlers ([#309](https://github.com/ChiR24/Unreal_mcp/pull/309)) – linked pins returned as objects with `nodeId` and `pinName`.
+- Improved actor lookup to match subsystem behavior (checks both label and name).
+- Aligned `get_ai_info` output with TypeScript schema ([#310](https://github.com/ChiR24/Unreal_mcp/pull/310)).
+
+#### Performance & Console
+
+- Delegated console command settings to C++ handler for better performance.
+- Ensured successful execution of console commands (check `GEngine->Exec` return value).
+- Added validation for required session parameters (interfaceType, controllerId, playerIndex, etc.).
+- Removed redundant `AsyncTask` wrappers in `generate_thumbnail` and `generate_lods` (fixed 30‑second timeout).
+
+#### Level Operations
+
+- **`rename_level`** – Now uses `DuplicateAsset` + `DeleteAsset` to avoid modal “Find/Replace” dialog.
+- **`duplicate_level`** – Validates source existence and deletes destination if already present.
+- **`export_level`** – Added source level existence check before export.
+
+#### Voice Chat & Sessions
+
+- Improved `mute_player` – falls back to `BlockPlayers` when voice server not connected.
+- Added validation for required parameters in all session actions.
+
+#### Plugin Stability
+
+- Used delay‑load for optional plugin modules to prevent missing dependency errors ([#317](https://github.com/ChiR24/Unreal_mcp/pull/317)).
+- Refactored IK retargeter initialization using controller API (UE 5.7+) with backward compatibility fallback.
+- Enhanced actor and component stability across subsystems.
+
+#### Documentation
+
+- Fixed rate limiting defaults and missing GraphQL heading ([#307](https://github.com/ChiR24/Unreal_mcp/pull/307)).
+
+</details>
+
+<details>
+<summary><b>🔄 Dependencies</b></summary>
+
+| Package | Update | PR |
+|---------|--------|-----|
+| `picomatch` | 4.0.3 → 4.0.4 | [#316](https://github.com/ChiR24/Unreal_mcp/pull/316) |
+| Dependencies group | 9 updates | [#320](https://github.com/ChiR24/Unreal_mcp/pull/320) |
+| `github/codeql-action` | 4.33.0 → 4.34.1 | [#319](https://github.com/ChiR24/Unreal_mcp/pull/319) |
+
+</details>
+
+<details>
+<summary><b>👥 Contributors</b></summary>
+
+- @google-labs-jules[bot] for all security fixes
+- @kalihman for asset query, searchText, docs, and blueprint graph fixes
+- @dependabot[bot] for dependency updates
+- @6r0m for custom content mount points (first contribution)
+
+</details>
+
+---
+
 ## 🏷️ [0.5.20] - 2026-03-21
 
 > [!IMPORTANT]
@@ -2090,7 +2340,7 @@ Replaced `console.error`/`console.warn` with structured `Logger` across all tool
 > ### 🔄 Major Architecture Migration
 > This release marks the **complete migration** from Unreal's built-in Remote Plugin to a native C++ **McpAutomationBridge** plugin. This provides:
 > - ⚡ Better performance
-> - 🔗 Tighter editor integration  
+> - 🔗 Tighter editor integration
 > - 🚫 No dependency on Unreal's Remote API
 >
 > **BREAKING CHANGE:** Response format has been standardized across all automation tools. Clients should expect responses to follow the new `StandardActionResponse` format with `success`, `data`, `warnings`, and `error` fields.