Skip to content

Latest commit

 

History

History
2496 lines (1770 loc) · 94.8 KB

File metadata and controls

2496 lines (1770 loc) · 94.8 KB

📋 Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


[Unreleased]

Added

  • Native MCP Streamable HTTP Transport — built-in HTTP/SSE MCP server directly in the C++ plugin, no TypeScript bridge or Node.js required. AI clients connect via http://localhost:3000/mcp. Supports SSE streaming, multiple concurrent sessions, dynamic tool management. Opt-in via bEnableNativeMCP project setting.
  • execute_python action in system_control — execute Python code inline or from .py files with stdout/stderr capture, execution time tracking, and RAII temp file cleanup. Max code size: 1 MB.
  • Capability token authentication for native MCP transport — validates X-MCP-Capability-Token header when bRequireCapabilityToken is enabled.
  • 36 self-describing C++ tool definitions with FMcpSchemaBuilder fluent API — replaces JSON schema loader.
  • Dynamic tool manager — enable/disable tools and categories at runtime via manage_tools, with protected tools/categories.
  • Editor status bar indicator — shows MCP port and active session count.

Security

  • Symlink escape prevention in execute_python file path validation — resolves symlinks and re-validates against project directory.
  • Code size limitexecute_python enforces 1 MB maximum for inline code payloads.
  • Explicit request origin tracking (ERequestOrigin) — routes HTTP vs WebSocket responses by explicit origin instead of inferring from TargetSocket==nullptr.
  • Tool registry thread safetyRegister() holds CacheMutex for entire body; GetAllTools() returns copy.
  • Dynamic tool manager protectionEnableCategory("all") respects protected categories and initial state.

Changed

  • manage_blueprint schema: location, rotation, scale changed from flat number arrays to structured objects with named sub-fields — matches TypeScript schema.

  • system_control schema: removed export_asset action (not in TS) and additionalArgs parameter.

  • control_editor schema: added set_editor_mode action.

  • ScanPathsSynchronous removed from asset query/workflow handlers to prevent GameThread blocking. Documented limitation: newly-added assets may not appear until editor rescan.

  • Screenshot handler now returns async: true with expectedDelay field and timing guidance.

  • inspect_cdo sub-action for the inspect tool – inspect any Blueprint's Class Default Object without spawning an actor. Reads CDO property values via reflection. For Actor BPs, enumerates all components: native CDO components with effective override values, plus Blueprint SCS components from node templates (full parent chain). Includes parent attachment info for SCS components. Source classified as Native, SCS, or SCS_Inherited. Key fields (mesh, animClass, transform) included in summary; full property export via detailed or propertyNames filter.


🏷️ [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.

🛡️ Security
  • Command Injection in bump-version action – Sanitized release-type input (#327)
  • Command Injection in editor console commands – Mixed-context sanitization for start_recording, set_camera_fov, set_game_speed (#322)
  • Path Traversal in export_level – Added path validation (#305)
  • Path Traversal in screenshot filename – Sanitized filenames, blocked traversal patterns (#314)
  • Synchronous fs Hardening – Replaced blocking fs.existsSync / fs.readdirSync with async versions (#318)
✨ Added
  • Custom Content Mount PointsMCP_ADDITIONAL_PATH_PREFIXES to whitelist plugin mount points (/ProjectObject/, etc.) (#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 Authoringcreate_blend_tree, create_procedural_anim, create_state_machine (C++ implementations, not console commands).
  • Vehicle Physics Configurationconfigure_vehicle with wheels, engine, transmission, mass, drag coefficient.
  • Sequencerset_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).
🛠️ Fixed

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) 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).
  • Replaced custom asset directory checks with UEditorAssetLibrary to avoid stale cache issues.
  • Fixed searchText filtering in search_assets action (#308).
  • Added offset pagination to asset search.

Blueprint & Graph Editing

  • Unified pin serialization across blueprint graph handlers (#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).

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).
  • 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).
🔄 Dependencies
Package Update PR
picomatch 4.0.3 → 4.0.4 #316
Dependencies group 9 updates #320
github/codeql-action 4.33.0 → 4.34.1 #319
👥 Contributors
  • @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)

🏷️ [0.5.20] - 2026-03-21

Important

🛡️ Security Fix & UE 5.0 Compatibility

This release includes a critical path traversal fix in export_asset, UE 5.0 compatibility improvements, and external actors support for World Partition.

🛡️ Security

🔒 Path Traversal in export_asset (5cf2a3c)
Aspect Details
Severity 🚨 CRITICAL
Vulnerability Path traversal in export_asset action
Fix Added path validation to prevent directory traversal attacks

Files Modified:

  • McpAutomationBridge_SystemControlHandlers.cpp

✨ Added

🌍 External Actors Support (51143c3)
Feature Description
External Actors Support for World Partition external actors in level structure handlers
Streaming Reference Streaming reference creation for external actor packages

Files Modified:

  • McpAutomationBridge_LevelStructureHandlers.cpp (+127 lines)

🛠️ Fixed

🎮 UE 5.0 Compatibility (1057023)
Bug Fix
bIsWorldInitialized API not available in UE 5.0 Direct access to bIsWorldInitialized for UE 5.0 compatibility

Files Modified:

  • McpAutomationBridgeHelpers.h
  • McpAutomationBridge_LevelStructureHandlers.cpp
🐛 Tick Task Manager Crashes (8c311d7)
Bug Fix
Crashes from tick task manager during world operations Added safety checks and proper cleanup in world management
World cleanup issues Enhanced cleanup with FlushRenderingCommands safety

Files Modified:

  • McpAutomationBridgeHelpers.h (+36 lines)
  • McpAutomationBridge_LevelStructureHandlers.cpp (+65 lines)
  • McpSafeOperations.h (+16 lines)
🐛 Sublevel Creation (bffb68c)
Bug Fix
Sublevel creation path handling issues Enhanced sublevel creation process with proper path handling

Files Modified:

  • McpAutomationBridge_LevelStructureHandlers.cpp (+201 lines)
🔧 UE 5.7 Build (#295)
Bug Fix
Missing includes causing build failures on UE 5.7 Added missing includes in McpHandlerUtils.cpp and McpPropertyReflection.cpp

Contributors: @a2448825647

🔄 Dependencies

GitHub Actions Updates
Package From To PR
release-drafter/release-drafter 7.0.0 7.1.1 #300
softprops/action-gh-release 2.5.3 2.6.1 #301
github/codeql-action 4.32.6 4.33.0 #299
NPM Package Updates
Package From To PR
flatted 3.3.3 3.4.2 #304

🔌 Plugin

MCP Automation Bridge v0.1.3

Updated plugin version to 0.1.3 with all fixes and features from this release.

See Plugin CHANGELOG for details.


🏷️ [0.5.19] - 2026-03-18

Important

🛡️ Security Hardening & Major Plugin Refactoring

This release includes critical security fixes for command injection and path traversal vulnerabilities, a complete deep-level refactoring of 57 C++ handler files with centralized utilities, and removal of the WebAssembly integration.

🛡️ Security

🔒 Command Injection Prevention (#288)
Component Change
sanitizeCommandArgument() Added semicolon sanitization to prevent command chaining attacks
Physics Tools Sanitized constraint names, actor names, vehicle names, destruction names
Animation Tools Sanitized state machine names, state names, transition conditions
System Handlers Sanitized vehicle type, save paths, and all user-provided strings

Attack Vector Blocked: Input like "name;quit" can no longer execute arbitrary commands.

🔒 Path Traversal Fixes (#271, #282)
Component Change
validateSnapshotPath() Fixed bypass where paths equal to CWD (without trailing separator) were incorrectly rejected
Asset Handlers Added path sanitization to prevent traversal attacks
Blueprint Creation Added savePath sanitization
🔒 GraphQL CORS Hardening
Component Change
Default CORS Changed from permissive '*' to safe loopback origins
Allowed Origins localhost:4000, 127.0.0.1:4000, localhost:3000, 127.0.0.1:3000
Warning Added security warning when '*' is explicitly configured

🔧 Changed

🏗️ Complete C++ Plugin Refactoring (#280)

Deep line-by-line refactoring of 57 handler files and 8 infrastructure files:

New Infrastructure File Purpose
McpHandlerUtils.h/cpp Standardized JSON response builders (1,900 lines)
McpPropertyReflection.h/cpp Property reflection utilities (1,356 lines)
McpSafeOperations.h Safe asset/level save for UE 5.7 (659 lines)
McpVersionCompatibility.h UE 5.0-5.7 API compatibility macros (225 lines)
McpHandlerDeclarations.h Forward declarations (844 lines)
McpAutomationBridge_ConsoleCommandHandlers.cpp Batch and single command execution (302 lines)

Bugs Fixed During Refactoring:

  • EditorFunctionHandlers: use-after-free bug
  • EffectHandlers: truncated condition + missing braces
  • InventoryHandlers: duplicate TArray with undefined variables
  • MaterialAuthoringHandlers: duplicate include + missing UE 5.0 fallback
  • NavigationHandlers: case-sensitivity error
  • SkeletonHandlers: duplicate verification + redundant code
  • WidgetAuthoringHandlers: unreachable code block
⚡ Performance Improvements (#283)
Component Change
Batch Console Commands New batch execution API for parallel command processing
validate_assets Changed from sequential to Promise.all concurrent validation
State Machine Creation States now added in parallel instead of sequentially
🗑️ WebAssembly Integration Removed (#240)

Removed WebAssembly (wasm-pack/Rust) integration:

  • Deleted src/wasm/ directory (874 lines)
  • Deleted wasm/ Rust crate (1,500+ lines)
  • Removed WASM dependency from all handlers
  • Native C++ handlers provide equivalent functionality

🛠️ Fixed

🐛 Blueprint Inspect Crash (#270)
Bug Fix
Blueprint inspect crashed when variable list exceeded buffer Fixed truncated variable list handling
Function library blueprints not supported Added function library blueprint support (#258)
🐛 GAS Duplicate Effect Creation (#251)
Bug Fix
create_gameplay_effect assertion failure on duplicates Prevented duplicate GameplayEffect creation
🐛 Volume Handler Mobility
Bug Fix
Volume attachment failed for movable actors Added mobility check for target actors in volume handlers
🐛 UE 5.7 Compatibility (#274)
Bug Fix
GeometryScript AppendCapsule compile error on UE 5.5+ Added version guard for segment steps parameter
🐛 Action Name Alignment (#253)
Bug Fix
TypeScript action names mismatched C++ handlers Aligned all action names with C++ handler expectations

🗑️ Removed

Deprecated Tool Files

Removed deprecated standalone tool files (consolidated into handlers):

  • src/tools/audio.tssrc/tools/handlers/audio-handlers.ts
  • src/tools/debug.ts → consolidated into system handlers
  • src/tools/introspection.tssrc/tools/handlers/inspect-handlers.ts
  • src/tools/materials.tssrc/tools/handlers/material-authoring-handlers.ts
  • src/tools/performance.tssrc/tools/handlers/performance-handlers.ts
  • src/tools/ui.ts → consolidated into widget handlers
  • src/tools/input.tssrc/tools/handlers/input-handlers.ts
  • src/tools/behavior-tree.ts → consolidated
  • src/tools/engine.ts → consolidated

🔄 Dependencies

NPM Package Updates
Package From To PR
hono 4.12.0 4.12.7 #261, #277
express-rate-limit 8.2.1 8.3.0 #269
@types/node Various updates Multiple PRs
GitHub Actions Updates
Package From To PR
release-drafter/release-drafter 6.2.0 7.0.0 #286
softprops/action-gh-release 2.5.0 2.5.3 #287
actions/setup-node 6.2.0 6.3.0 #257
github/codeql-action 4.32.5 4.32.6 #266

📊 Statistics

  • Commits: 55 non-merge commits
  • Files Changed: 185 files
  • Lines Added: ~30,280
  • Lines Removed: ~20,440
  • New C++ Infrastructure: 5 files (~4,900 lines)
  • Bugs Fixed: 15+
  • Security Fixes: 4 critical

🏷️ [0.5.18] - 2026-02-21

Important

🔧 Installation, Documentation & Dependency Updates

This release fixes npm install failures when downloading from GitHub releases, adds first-time project setup guidance, and updates dependencies.

🛠️ Fixed

🐛 npm install failure from release archives (#215)
Issue Root Cause Fix
npm install fails with ESLint config error Release archives excluded eslint.config.mjs and other build files Added -source archives with complete build files
prepare script runs build unnecessarily Checked only dist/ existence, not build artifacts Now verifies dist/cli.js and dist/index.js exist
Deprecated --ext .ts flag in lint ESLint 9.x removed support for --ext flag Removed flag, extensions configured in eslint.config.mjs

Files Modified:

  • package.json (prepare script, lint scripts, removed prebuild)
  • .github/workflows/release.yml (added source archives, fixed plugin path)
  • README.md (added Rust/wasm-pack prerequisites)

📚 Documentation

📖 First-time project open instructions (112df08)

Added guidance for users opening Unreal projects for the first time:

  • Explains UE prompt to rebuild missing modules
  • Documents expected plugin load failure after first rebuild
  • Recommends closing and reopening project to resolve

⬆️ Dependencies

Package From To PR
hono 4.11.7 4.12.0 #213
ajv 8.17.1 8.18.0 #210
actions/stale 10.1.1 10.2.0 #208
actions/dependency-review-action 4.8.2 4.8.3 #212

🏷️ [0.5.17] - 2026-02-16

Important

🔧 World Tools Category Fixes & Security Hardening

This release includes critical bug fixes, security hardening, and UE 5.7 compatibility improvements across all world-building tools (landscape, foliage, geometry, volumes, navigation).

🛡️ Security

🔒 Path Validation & Input Sanitization (#207)
Component Change
SanitizeProjectRelativePath Rejects Windows absolute paths, normalizes slashes, collapses //, requires valid UE roots (/Game, /Engine, /Script)
SanitizeProjectFilePath File operations with path traversal protection
ValidateAssetCreationPath Combines folder + name validation for asset creation
Actor/Volume Name Validation Blocks invalid characters, enforces length checks
Snapshot Path Validation Prevents directory traversal attacks via snapshot paths

Files Modified:

  • McpAutomationBridgeHelpers.h (+326 lines of security helpers)
  • src/tools/environment.ts (snapshot path security)
  • src/utils/path-security.ts (path normalization)

🛠️ Fixed

🐛 Landscape Handler Silent Fallback Bug (McpAutomationBridge_LandscapeHandlers.cpp)
Bug Root Cause Fix
False positives on non-existent landscapes Path matching compared GetPathName() (internal path) with asset path Normalized both paths with .uasset stripping
Silent fallback to single landscape if (!Landscape && LandscapeCount == 1) used any available landscape Removed fallback, now returns LANDSCAPE_NOT_FOUND error
Wrong response path Returned requested path instead of actual path Now returns Landscape->GetPackage()->GetPathName()

Affected Handlers: HandleModifyHeightmap, HandlePaintLandscapeLayer, HandleSculptLandscape, HandleSetLandscapeMaterial

🐛 Rotation Yaw Bug (McpAutomationBridge_LightingHandlers.cpp:200)
Bug Fix
Rotation.Yaw read from LocPtr instead of RotPtr Changed to GetJsonNumberField((*RotPtr), TEXT("yaw"))

Impact: Incorrect rotation when spawning lights with rotation parameters.

🐛 Integer Overflow in Heightmap Operations (McpAutomationBridge_LandscapeHandlers.cpp:631-635)
Bug Fix
static_cast<int16>(CurrentHeights[i]) overflows for values > 32767 Changed to static_cast<int32>

Impact: Heightmap raise/lower operations now produce correct results for heights above midpoint.

🐛 set_curve_key Success Reporting (McpAutomationBridge_AnimationHandlers.cpp:2139)
Bug Fix
bSuccess initialized false, only set true inside if (bSuccess) block (unreachable) Moved success logic before the condition check

Impact: set_curve_key now correctly reports success.

🐛 CraftingSpeed Truncation (McpAutomationBridge_InventoryHandlers.cpp:2716)
Bug Fix
int32 CraftingSpeed truncated fractional multipliers (1.5 → 1) Changed to double
🐛 Invalid Color Fallback Not Applied (McpAutomationBridge_LightingHandlers.cpp:277)
Bug Fix
SetLightColor() only called when bColorValid == true, but bColorValid = false for invalid colors Removed guard, always call SetLightColor() after correcting invalid colors to white
🐛 Double-Validation in Snapshot Path (src/tools/environment.ts:253, 322)
Bug Fix
Redundant second validateSnapshotPath() call on already-resolved absolute paths Removed redundant call
🐛 Intel GPU Driver Crash Prevention (McpAutomationBridgeHelpers.h)
Bug Fix
MONZA DdiThreadingContext exceptions on Intel GPUs during level save Added McpSafeLevelSave helper with FlushRenderingCommands and retry logic

✨ Added

🛤️ LOD Generation Enhancements (McpAutomationBridge_GeometryHandlers.cpp)
Feature Description
landscapePath support LOD generation now accepts single landscapePath or array assetPaths
lodCount parameter Alternative to numLODs for specifying LOD count
Path sanitization All LOD operations use SanitizeProjectRelativePath
🌿 FoliageType Auto-Creation (McpAutomationBridge_FoliageHandlers.cpp)
Feature Description
Auto-create FoliageType When painting/adding foliage, FoliageType is automatically created from StaticMesh if missing
Path validation All foliage operations use path sanitization
🏔️ Landscape Layer Auto-Creation (McpAutomationBridge_LandscapeHandlers.cpp)
Feature Description
Auto-create layers When painting, landscape layers are auto-created if they don't exist (matches UE editor behavior)
📊 Handler Verification (Multiple Handler Files)
Pattern Description
AddActorVerification Returns actorPath, actorName, actorGuid, existsAfter, actorClass
AddComponentVerification Returns componentName, componentClass, ownerActorPath
AddAssetVerification Returns assetPath, assetName, existsAfter, assetClass
VerifyAssetExists Verifies asset exists at path

Files Updated: PropertyHandlers, LevelHandlers, EffectHandlers, GASHandlers, SequenceHandlers, SkeletonHandlers, and 30+ additional handler files

🔧 Changed

🎮 UE 5.7 Compatibility
Component Change
WebSocket Protocol GetProtocolType() (FName) replaces deprecated GetProtocolFamily() (enum)
SCS Save McpSafeAssetSave replaces SaveLoadedAssetThrottled to prevent recursive FlushRenderingCommands crashes
PostProcessVolume Conditionally compiled (removed in UE 5.7)
Niagara Graph Initialize GraphSource/NiagaraGraph to prevent null graph crashes
Landscape Edit FLandscapeEditDataInterface for UE 5.5+, deprecation suppression for 5.0-5.4
WorldPartition Support RuntimeHashSet in addition to RuntimeSpatialHash for UE 5.7+
📈 Performance Improvements
Component Change
Heightmap Modification Pass false to FLandscapeEditDataInterface to prevent 60+ second GPU sync delays
Landscape Updates Use MarkPackageDirty instead of PostEditChange to avoid unnecessary rebuilds
Geometry Operations Memory pressure checks and triangle limits to prevent OOM crashes

📊 Statistics

  • Files Changed: 70 files
  • Lines Added: ~7,200
  • Lines Removed: ~1,400
  • Bug Fixes: 8 critical bugs
  • New Verification Helpers: 4

🏷️ [0.5.16] - 2026-02-12

Important

🚀 Major Feature Release: 200+ Action Handlers

This release adds ~200 new C++ automation sub-actions across all domains, introduces progress heartbeat protocol for long-running operations, dynamic tool management, IPv6 support, and comprehensive security hardening.

✨ Added

🎮 200+ MCP Action Handlers (#200)
Domain New Actions
AI 50+ actions for EQS, Perception, State Trees, Smart Objects
Combat Weapons, projectiles, damage, melee combat
Character Character creation, movement, advanced locomotion
Inventory Items, equipment, loot tables, crafting
GAS Gameplay Ability System: abilities, effects, attributes
Audio MetaSounds, sound classes, dialogue
Materials Material expressions, landscape layers
Textures Texture creation, compression, virtual texturing
Levels 15+ new sub-actions for level management
Volumes 18 volume types
Performance Profiling, optimization, scalability
Input Enhanced Input Actions & Contexts
Interaction Interactables, destructibles, triggers
Misc System control, tests, logs

New Handler Files:

  • McpAutomationBridge_CharacterHandlers.cpp (337 lines)
  • McpAutomationBridge_CombatHandlers.cpp (398 lines)
  • McpAutomationBridge_SystemControlHandlers.cpp (324 lines)
  • McpAutomationBridge_MiscHandlers.cpp (1010 lines)
  • McpAutomationBridge_WidgetAuthoringHandlers.cpp (2404 lines)
💓 Progress Heartbeat Protocol (#201)
Feature Description
Progress Updates C++ sends progress_update WebSocket messages during long-running operations
Deadline Extensions TS extends request deadlines on each update with deadlock safeguards
Stale Detection Detects same percentage for 3 consecutive updates
Absolute Cap 5-minute maximum extension limit
Max Extensions 10 extensions per request

Timeout Changes:

  • Default request timeout: 60s → 30s (extensions handle slow ops)
🔧 Dynamic Tool Management
Feature Description
manage_tools MCP Tool Enables AI to enable/disable tools at runtime
Protected Tools manage_tools, inspect, and core category cannot be disabled
list_changed Notifications Tool registry sends MCP notifications when tools change
Category Filtering Filter tools by category (core, world, authoring, gameplay, utility)
🌐 IPv6 Support (#194)
Feature Description
IPv6 Addresses Full support for IPv6 addresses in automation bridge
Hostname Resolution DNS resolution via GetAddressInfo instead of fallback to 127.0.0.1
Address Family Detection Auto-detect IPv6 by checking for colons in address
Zone ID Handling Strip zone IDs from IPv6 addresses for Node.js compatibility
Fallback Support Re-create socket as IPv4 when IPv6 not available

🛡️ Security

🔒 Security Hardening
Function Description
SanitizeProjectRelativePath Rejects Windows absolute paths, normalizes slashes, collapses //, requires valid UE roots
SanitizeAssetName Strips SQL injection patterns, invalid characters, enforces 64-char limit
ValidateAssetCreationPath Combines folder + name validation
IsValidAssetPath Rejects : (Windows drive letters) and consecutive slashes

TypeScript Security:

  • src/utils/path-security.ts: Collapse // normalization
  • src/utils/validation.ts: SQL injection detection
🔒 String Escaping Fix (#202)
Issue Fix
Incomplete string escaping in path handling Added proper escaping for special characters

🔧 Changed

🎮 UE 5.7 Compatibility Fixes
Component Change
WebSocket GetProtocolType() (FName) replaces GetProtocolFamily() (enum)
SCS Save McpSafeAssetSave prevents recursive FlushRenderingCommands crashes
PostProcessVolume Conditionally compiled (removed in 5.7)
Niagara Initialize GraphSource/NiagaraGraph to prevent null graph crashes
⚡ Performance & Infrastructure
Change Description
Memory Detection Windows GlobalMemoryStatusEx replaces heuristic detection
Rate Limit MaxAutomationRequestsPerMinute raised 120 → 600
Logging Improved request/response logging with action name and filtered payload preview
Blueprint Handler Variable name collision generates unique suffix, type validation before loading

🛠️ Fixed

🐛 Various Fixes
Fix Description
~30 handlers Handlers that returned nullptr now return structured JSON
Blueprint Unknown actions return explicit error instead of silent failure
Level tools File existence checked before load, post-load path validation
Eject handler Changed from stopping PIE to ejecting from possessed pawn

📊 Statistics

  • Files Changed: 83 files
  • Lines Added: ~23,000
  • Lines Removed: ~2,700
  • New Action Handlers: ~200
  • New Handler Files: 5

🏷️ [0.5.15] - 2026-02-06

Note

🌐 Network Configuration Release

This release adds support for non-loopback binding in automation bridge settings, enabling LAN access configuration.

✨ Added

🌐 Non-Loopback Binding Support (#193)
Feature Description
Non-Loopback Binding Automation bridge can now bind to non-loopback addresses (e.g., 0.0.0.0) for LAN access
Allow Non-Loopback Setting New bAllowNonLoopback setting in plugin configuration
TypeScript Support Added MCP_AUTOMATION_ALLOW_NON_LOOPBACK environment variable
Host Validation Tests New test suite for bridge host validation

Configuration:

# Enable LAN access
MCP_AUTOMATION_ALLOW_NON_LOOPBACK=true
MCP_AUTOMATION_HOST=0.0.0.0

Security Note: Only enable on trusted networks with appropriate firewall rules.

🔄 Dependencies

Dependabot Updates
Package Update PR
github/codeql-action 4.32.1 → 4.32.2 #189
Dependencies group 2 updates #190

📊 Statistics

  • Files Changed: 8 files
  • Lines Added: ~270
  • Lines Removed: ~10

🏷️ [0.5.14] - 2026-02-05

Important

🔐 TLS & Network Security Release

This release introduces TLS/SSL support for secure WebSocket connections (wss://), per-connection rate limiting, loopback-only network binding enforcement, and authentication state tracking for the Automation Bridge.

🛡️ Security

🔒 Loopback-Only Binding & Handshake Enforcement (70c2745)
Aspect Details
Severity 🚨 HIGH
Loopback Binding Automation Bridge now only binds to loopback addresses (127.0.0.1 or ::1)
Handshake Required Automation requests require completed bridge_hello handshake

C++ Plugin:

  • Rejects 0.0.0.0 and :: bind attempts, falls back to 127.0.0.1 with warning
  • Added AuthenticatedSockets tracking set in McpConnectionManager
  • Unauthenticated sockets receive HANDSHAKE_REQUIRED error and connection close (code 4004)

TypeScript Bridge:

  • Added normalizeLoopbackHost() to validate and enforce loopback addresses
  • Non-loopback host values rejected with warning and fallback

✨ Added

🔐 TLS/SSL, Rate Limiting & Schema Validation (d2a94cf)
Feature Description
TLS/SSL Support Full wss:// WebSocket support with OpenSSL/TLS integration (TLS 1.2+)
Rate Limiting Per-connection limits: configurable, defaults to disabled (0) for development
Schema Validation New Zod schemas in src/automation/message-schema.ts for type-safe message parsing

New Plugin Settings:

  • bEnableTls, TlsCertificatePath, TlsPrivateKeyPath - TLS configuration
  • MaxMessagesPerMinute, MaxAutomationRequestsPerMinute - Rate limit configuration

C++ Implementation:

  • InitializeTlsContext(), EstablishTls(), SendRaw(), RecvRaw() - TLS-aware I/O
  • Requires UE 5.7+ for native socket release; graceful fallback on older versions

TypeScript Integration:

  • Added rateLimitState tracking with cleanup on connection close

🛠️ Fixed

🔧 TLS Memory Management (321206e)
Fix Description
Struct Initialization Fixed FParsedWebSocketUrl member initialization order (Port using uninitialized bUseTls)
SSL Context Ownership Added bOwnsSslContext to prevent double-free of client contexts owned by ISslManager
🔧 Thread Safety & TLS Error Handling (6fd1553)
Fix Description
Mutex Protection Added SocketRateLimits cleanup in ForceReconnect with proper mutex locking
Declaration Moved ShutdownTls() declaration outside WITH_SSL guard for compilation compatibility
🔧 Review Feedback Fixes (8987a3e)
Fix Description
Duplicate Call Fixed duplicate ActiveSockets.Empty() call in connection manager
TypeScript Cleanup Added rateLimitState cleanup in closeAll() method

🔄 Dependencies

NPM Package Updates
Package Update PR
@modelcontextprotocol/sdk 1.25.3 → 1.26.0 #187
mcp-client-capabilities Latest #186
GitHub Actions Updates
Package Update PR
github/codeql-action 4.32.0 → 4.32.1 #185
actions/github-script 7.0.1 → 8.0.0 #184

🏷️ [0.5.13] - 2026-02-02

Important

🛡️ Security & Compatibility Release

This release includes multiple critical security fixes for command injection and path traversal vulnerabilities, along with full Unreal Engine 5.0 backward compatibility and WebSocket stability improvements.

🛡️ Security

🔒 Command Injection in UITools (#144)
Aspect Details
Severity 🚨 HIGH
Vulnerability Command injection via unsanitized user input in widget creation
Fix Added sanitizeConsoleString() and applied sanitizeAssetName() to all user-provided identifiers
Contributors @google-labs-jules[bot]
🔒 Command Injection in LevelTools (#179)
Aspect Details
Severity 🚨 HIGH
Vulnerability Command injection via level names, event types, and game mode parameters
Fix Added sanitizeCommandArgument() and applied to all console command parameters
Contributors @google-labs-jules[bot]
🔒 Path Traversal in Asset Listing (#163)
Aspect Details
Severity 🚨 HIGH
Vulnerability Path traversal in listAssets via filter.pathStartsWith parameter
Fix Applied normalizeAndSanitizePath() to GraphQL listAssets and asset handler list action
Contributors @google-labs-jules[bot]

✨ Added

🎮 Unreal Engine 5.0 Compatibility (#183)
Component Description
API Abstractions Version-guarded macros for Material, Niagara, AssetRegistry, Animation, and World Partition APIs
Build System Made plugin dependencies optional with dynamic memory-based configuration
Coverage 41 handler files updated with UE 5.0-5.7 compatibility

Compatibility Macros Added:

  • MCP_GET_MATERIAL_EXPRESSIONS() - Abstracts material expression access
  • MCP_DATALAYER_TYPE / MCP_DATALAYER_ASSET_TYPE - Data layer type abstraction
  • MCP_ASSET_FILTER_CLASS_PATHS - Asset registry filter abstraction
  • MCP_ASSET_DATA_GET_CLASS_PATH() - FAssetData abstraction
  • MCP_NIAGARA_EMITTER_DATA_TYPE - Niagara emitter abstraction

🛠️ Fixed

🔌 WebSocket Stability (#180, #181)
Fix Description
TOCTOU Race Fixed Time-of-Check-Time-of-Use race condition in ListenSocket shutdown
Shutdown Hang Fixed WebSocket server blocking cook/package builds
Version Compatibility Fixed PendingReceived.RemoveAt() API differences for UE 5.4+

Contributors: @kalihman

🔧 Resource Handlers (#165)
  • Fixed broken actors and level resource handlers
  • Added missing actors and level resources to MCP resource list

Contributors: @kalihman

🔧 Other Fixes
Fix Description
UE 5.7 Resolved macro handling and ControlRig dynamic loading issues
UE 5.5 Fixed API compatibility issues in handlers
UE 5.1 Fixed MaterialDomain.h inclusion path
JSON Refactored JSON handling in McpAutomationBridge

🧪 Testing

  • Added security regression tests for UITools, LevelTools, and asset handlers

🔄 Dependencies

GitHub Actions Updates
Package Update PR
release-drafter/release-drafter 6.1.1 → 6.2.0 #160
actions/checkout 6.0.1 → 6.0.2 #161
github/codeql-action 4.31.10 → 4.32.0 #168, #170
google-github-actions/run-gemini-cli Latest #177
NPM Package Updates
Package Update PR
@modelcontextprotocol/sdk Latest #154
hono 4.11.4 → 4.11.7 #173
@types/node Various updates #158, #162, #175

🏷️ [0.5.12] - 2026-01-15

Note

🔧 Handler Synchronization Release

This release focuses on synchronizing TypeScript handler parameters with C++ handlers and dependency updates.

🛠️ Fixed

🔧 TS Handler Parameter Sync (5953232)
  • Synchronized TypeScript handler parameters with C++ handlers for consistency
  • Fixed parameter mapping issues between TS and C++ layers

🔄 Dependencies

GitHub Actions Updates
Package Update PR
release-drafter/release-drafter 6.1.0 → 6.1.1 #141
google-github-actions/run-gemini-cli Latest #142
NPM Package Updates (#143)
Package Update
@types/node Various dev dependency updates

🏷️ [0.5.11] - 2026-01-12

Important

🛡️ Security Hardening & UE 5.7 Compatibility

This release includes multiple critical security fixes for path traversal and command injection vulnerabilities, along with UE 5.7 Interchange compatibility fixes.

🛡️ Security

🔒 Path Traversal in Asset Import (#125)
Aspect Details
Severity 🚨 CRITICAL
Vulnerability Path traversal in asset import functionality
Fix Added path sanitization and validation
🔒 Command Injection Bypass (#122)
Aspect Details
Severity 🚨 CRITICAL
Vulnerability Command injection bypass via flexible whitespace
Fix Enhanced command validation to detect and block bypass attempts
🔒 Path Traversal in Screenshots (#120)
Aspect Details
Severity 🚨 HIGH
Vulnerability Path traversal in screenshot filenames
Fix Implemented filename sanitization and path validation
🔒 Path Traversal in GraphQL (#135)
Aspect Details
Severity 🚨 HIGH
Vulnerability Path traversal in GraphQL resolvers
Fix Added input sanitization for GraphQL resolver paths
🔒 GraphQL CORS Configuration (#118)
Aspect Details
Severity 🚨 MEDIUM
Vulnerability Insecure GraphQL CORS configuration
Fix Implemented secure CORS policy
🔒 Enhanced Command Validation (#113)
Aspect Details
Severity 🚨 HIGH
Vulnerability Command injection bypasses
Fix Enhanced validation patterns to prevent injection bypasses

🛠️ Fixed

🐛 UE 5.7 Asset Import Crash (#138)
Fix Description
Interchange Compatibility Deferred asset import to next tick for UE 5.7 Interchange compatibility
Name Sanitization Improved asset import robustness and name sanitization

Closes #137

🔄 Dependencies

NPM Package Updates
Package Update PR
@modelcontextprotocol/sdk 1.25.1 → 1.25.2 #119
hono 4.11.1 → 4.11.4 #129
@types/node Various updates #130, #133, #134
GitHub Actions Updates
Package Update PR
github/codeql-action 4.31.9 → 4.31.10 #126
actions/setup-node 6.1.0 → 6.2.0 #133
dependabot/fetch-metadata 2.4.0 → 2.5.0 #114

🏷️ [0.5.10] - 2026-01-04

Important

🚀 Context Reduction Initiative & Spline System

This release implements the Context Reduction Initiative (Phases 48-53), reducing AI context overhead from ~78,000 to ~25,000 tokens, and adds a complete Spline System (Phase 26) with 21 new actions. (#107, #105)

✨ Added

🛤️ Spline System (Phase 26) (#105)

New manage_splines tool with 21 actions for spline-based content creation:

Category Actions
Creation create_spline_actor, add_spline_point, remove_spline_point, set_spline_point
Properties set_closed_loop, set_spline_type, set_tangent, get_spline_info
Mesh Components create_spline_mesh, set_mesh_asset, set_spline_mesh_axis, set_spline_mesh_material
Scattering create_mesh_along_spline, set_scatter_spacing, randomize_scatter
Quick Templates create_road_spline, create_river_spline, create_fence_spline, create_wall_spline, create_cable_spline, create_pipe_spline
Utility get_splines_info

C++ Implementation:

  • McpAutomationBridge_SplineHandlers.cpp (1,512 lines)
  • Full UE5 Spline API integration with USplineComponent and USplineMeshComponent
🔧 Pipeline Management Tool

New manage_pipeline tool for dynamic tool category management:

Action Description
set_categories Enable specific tool categories (core, world, authoring, gameplay, utility, all)
list_categories Show available categories and their tools
get_status View current state and tool counts

MCP Capability:

  • Server advertises capabilities.tools.listChanged: true
  • Client capability detection via mcp-client-capabilities package
  • Backward compatible: clients without listChanged support get ALL tools

🔧 Changed

📉 Context Reduction Initiative (Phases 48-53) (#107)
Phase Description Token Reduction
Phase 48 Schema Pruning - Condensed all 35+ tool descriptions to 1-2 sentences ~23,000
Phase 49 Common Schema Extraction - Shared schemas for paths, names, locations ~8,000
Phase 50 Dynamic Tool Loading - Category-based filtering ~50,000 (when using filtering)
Phase 53 Strategic Tool Merging - Consolidated 4 tools ~10,000

Total Potential Reduction: ~91,000 tokens

Common Schemas Added:

  • assetPath, actorName, location, rotation, scale, save, overwrite
  • standardResponse for consistent output formatting
  • Helper functions: createOutputSchema(), actionDescription()
🔀 Tool Consolidation (Phase 53)
Deprecated Tool Merged Into Actions Moved
manage_blueprint_graph manage_blueprint 11 graph actions
manage_audio_authoring manage_audio 30 authoring actions
manage_niagara_authoring manage_effect 36 authoring actions
manage_animation_authoring animation_physics 45 authoring actions

Benefits:

  • Reduced tool count: 38 → 35
  • Simplified tool discovery for AI assistants
  • Backward compatible: deprecated tools still work with once-per-session warnings
  • Action routing uses parameter sniffing to resolve conflicts

⚠️ Deprecated

  • manage_blueprint_graph - Use manage_blueprint with graph actions instead
  • manage_audio_authoring - Use manage_audio with authoring actions instead
  • manage_niagara_authoring - Use manage_effect with authoring actions instead
  • manage_animation_authoring - Use animation_physics with authoring actions instead

📊 Statistics

  • Files Changed: 20
  • Lines Added: 4,541
  • Lines Removed: 3,555
  • Net Change: +986 lines
  • New C++ Handler: 1,512 lines (McpAutomationBridge_SplineHandlers.cpp)
  • New TS Handler: 169 lines (spline-handlers.ts)
  • Common Schemas Added: 50+ reusable schema definitions

🔗 Related Issues

Closes #104, #106, #108, #109, #111


🏷️ [0.5.9] - 2026-01-03

Important

🎮 Major Feature Release

This release introduces 15+ new automation tools with comprehensive handlers for Navigation, Volumes, Level Structure, Sessions, Game Framework, and complete game development systems. (#53)

🛡️ Security

🔒 Fix Arbitrary File Read in LogTools (#103)
Aspect Details
Severity 🚨 CRITICAL
Vulnerability Arbitrary file read via logPath parameter
Impact Attackers could read any file on the system by manipulating the logPath override
Fix Validated that logPath ends with .log and is within Saved/Logs directory

Protections Added:

  • Enforced .log extension requirement
  • Restricted to Saved/Logs directory (CWD or UE_PROJECT_PATH)
  • Added path traversal and sibling directory attack protection

✨ Added

🛠️ New Automation Tools
Tool Description
manage_navigation NavMesh configuration, Nav Modifiers, Nav Links, pathfinding control
manage_volumes 18 volume types (Trigger, Blocking, Audio, Physics, Navigation, Streaming)
manage_level_structure World Partition, HLOD, Data Layers, Level Blueprints
manage_sessions Split-screen, LAN play, Voice Chat configuration
manage_game_framework GameMode, GameState, PlayerController, match flow
manage_skeleton Bone manipulation, sockets, physics assets
manage_material_authoring Material expressions, landscape materials
manage_texture Texture creation, compression, virtual texturing
manage_animation_authoring AnimBP, Control Rig, IK Rig, Retargeter
manage_niagara_authoring Niagara systems, modules, parameters
manage_gas Gameplay Ability System (Abilities, Effects, Attributes)
manage_character Character creation, movement, locomotion
manage_combat Weapons, projectiles, damage, melee combat
manage_ai EQS, Perception, State Trees, Smart Objects
manage_inventory Items, equipment, loot tables, crafting
manage_interaction Interactables, destructibles, triggers
manage_widget_authoring UMG widgets, layout, styling
manage_networking Replication, RPCs, network prediction
manage_audio_authoring MetaSounds, sound classes, dialogue

🔧 Changed

Build & Infrastructure Improvements
Change Description
Bounded Directory Search Replaced unbounded recursive search with bounded depth search (3-4 levels)
Property Management Enhanced property management across all automation handlers
Connection Manager Added IsReconnectPending() method to McpConnectionManager
State Machine Improved state machine creation with enhanced error handling

📊 Statistics

  • New Tools: 15+
  • New C++ Handler Files: 20+

🏷️ [0.5.8] - 2026-01-02

Important

🛡️ Security Release

Critical security fix for path traversal vulnerability and material graph parameter improvements.

🛡️ Security

🔒 Fix Path Traversal in INI Reader (#48)
Aspect Details
Severity 🚨 CRITICAL
Vulnerability Path traversal in getProjectSetting()
Impact Attackers could access arbitrary files by injecting ../ sequences into the category parameter
Fix Added strict regex validation ^[a-zA-Z0-9_-]+$ to cleanCategory in src/utils/ini-reader.ts

🛠️ Fixed

Material Graph Parameter Mapping (#50)
Schema Parameter C++ Handler Expected Status
fromNodeId sourceNodeId ✅ Auto-mapped
toNodeId targetNodeId ✅ Auto-mapped
toPin inputName ✅ Auto-mapped

Closes #49


🏷️ [0.5.7] - 2026-01-01

Important

🛡️ Security Release

Critical security fix for Python execution bypass vulnerability.

🛡️ Security

🔒 Fix Python Execution Bypass (e16dab0)
Aspect Details
Severity 🚨 CRITICAL
Vulnerability Python execution restriction bypass
Impact Attackers could execute arbitrary Python code by using tabs instead of spaces after the py command
Fix Updated CommandValidator to use regex `^py(?:\s

🔧 Changed

Release Process Improvements
  • Removed automatic git tag creation from release workflow
  • Updated release summary instructions for manual tag management

🔄 Dependencies

Package Updates
Package Update Type
zod 4.2.1 → 4.3.4 Minor
qs 6.14.0 → 6.14.1 Patch (indirect)
github/codeql-action 3.28.1 → 4.31.9 Major

🏷️ [0.5.6] - 2025-12-30

Important

🛡️ Type Safety Milestone

This release achieves near-zero any type usage across the entire codebase. All tool interfaces, handlers, automation bridge, GraphQL resolvers, and WASM integration now use strict TypeScript types with unknown and proper type guards.

✨ Added

📐 New Zod Schema Infrastructure
File Description
src/schemas/primitives.ts 261 lines of Zod schemas for Vector3, Rotator, Transform, Color, etc.
src/schemas/responses.ts 380 lines of response validation schemas
src/schemas/parser.ts 167 lines of safe parsing utilities with type guards
src/schemas/index.ts 173 lines of unified schema exports

Total: 981 lines of new type-safe schema infrastructure

🔧 Type-Safe Argument Helpers (d5e6d1e)

New extraction functions in argument-helper.ts:

Function Description
extractString(params, key) Extract required string with assertion
extractOptionalString(params, key) Extract optional string
extractNumber(params, key) Extract required number with assertion
extractOptionalNumber(params, key) Extract optional number
extractBoolean(params, key) Extract required boolean with assertion
extractOptionalBoolean(params, key) Extract optional boolean
extractArray<T>(params, key, validator?) Extract typed array with optional validation
extractOptionalArray<T>(params, key, validator?) Extract optional array
normalizeArgsTyped(args, configs) Returns NormalizedArgs interface with accessor methods

NormalizedArgs Interface:

  • getString(key), getOptionalString(key)
  • getNumber(key), getOptionalNumber(key)
  • getBoolean(key), getOptionalBoolean(key)
  • get(key) for raw unknown access
  • raw() for full object access
🔌 WASM Module Interface (d5e6d1e)

Defined structured WASMModule interface replacing any:

interface WASMModule {
  PropertyParser?: new () => { parse_properties(json, maxDepth) };
  TransformCalculator?: new () => { composeTransform, decomposeMatrix };
  Vector?: new (x, y, z) => { x, y, z, add(other) };
  DependencyResolver?: new () => { analyzeDependencies, calculateDepth, ... };
}
📝 Automation Bridge Types (f97b008)
Type Location Description
QueuedRequestItem automation/types.ts Typed interface for queued request items
ASTFieldNode graphql/resolvers.ts GraphQL AST node types for parseLiteral
ASTNode graphql/resolvers.ts Typed AST parsing

🔧 Changed

🎯 Tool Interfaces Refactored (d5e6d1e)

ITools Interface - Replaced all any with concrete types:

Property Before After
materialTools any MaterialTools
niagaraTools any NiagaraTools
animationTools any AnimationTools
physicsTools any PhysicsTools
lightingTools any LightingTools
debugTools any DebugVisualizationTools
performanceTools any PerformanceTools
audioTools any AudioTools
uiTools any UITools
introspectionTools any IntrospectionTools
engineTools any EngineTools
behaviorTreeTools any BehaviorTreeTools
logTools any LogTools
inputTools any InputTools
Index signature [key: string]: any [key: string]: unknown

StandardActionResponse:

  • Changed StandardActionResponse<T = any>StandardActionResponse<T = unknown>

IBlueprintTools:

  • operations: any[]operations: Array<Record<string, unknown>>
  • defaultValue?: anydefaultValue?: unknown
  • propertyValue: anypropertyValue: unknown

IAssetResources:

  • list(): Promise<any>list(): Promise<Record<string, unknown>>
🔷 GraphQL Resolvers Type Safety (f97b008, fa4dddc)

All scalar resolvers now use typed parameters:

Scalar Before After
Vector.serialize (value: any) (value: unknown)
Rotator.serialize (value: any) (value: unknown)
Transform.parseLiteral (ast: any) (ast: ASTNode)
JSON.parseLiteral (ast: any) (ast: ASTNode): unknown

Internal interfaces typed:

  • Asset.metadata?: Record<string, any>Record<string, unknown>
  • Actor.properties?: Record<string, any>Record<string, unknown>
  • Blueprint.defaultValue?: anyunknown
🌐 Automation Bridge Type Safety (f97b008)
Location Before After
onError callback (err: any) (err: unknown)
onHandshakeFail callback (err: any) (err: Record<string, unknown>)
catch block catch (err: any) catch (err: unknown) with type guard
onMessage handler (data: any) (data: Buffer | string)
queuedRequestItems inline type with any QueuedRequestItem[]
🔌 WASM Integration Type Safety (d5e6d1e)
Method Before After
parseProperties() Promise<any> Promise<unknown>
analyzeDependencies() Promise<any> Promise<unknown>
fallbackParseProperties() any unknown
fallbackAnalyzeDependencies() any Record<string, unknown>
globalThis.fetch patch (globalThis as any).fetch Typed with GlobalThisWithFetch
Error handling (error as any)?.code (error as Record<string, unknown>)?.code
📊 Handler Types Expanded (d5e6d1e)

src/types/handler-types.ts expanded with 147+ lines of new typed interfaces for all handler argument types.

🛠️ Fixed

✅ extractOptionalArray Behavior (f97b008)
  • Now returns undefined (instead of throwing) when value is not an array
  • Documented behavior: graceful fallback for type mismatches
  • Allows handlers to use default behavior when optional arrays are invalid

📊 Statistics

  • Files Changed: 70 source files
  • Lines Added: 3,806
  • Lines Removed: 1,816
  • Net Change: +1,990 lines (mostly type definitions)
  • New Schema Files: 4 (981 lines total)
  • anyunknown Replacements: 100+ occurrences

🔄 Dependencies

GitHub Actions Updates
Package Update PR
actions/first-interaction 1.3.0 → 3.1.0 #38
actions/labeler 5.0.0 → 6.0.1 Dependabot
github/codeql-action SHA update Dependabot
release-drafter/release-drafter SHA update Dependabot
Dev dependencies group 2 updates Dependabot

🏷️ [0.5.5] - 2025-12-29

Note

📝 Quality & Validation Release

This release focuses on input validation, structured logging, and developer experience improvements. WebSocket connections now enforce message size limits, Blueprint graph editing supports user-friendly node names, and all tools use structured logging.

✨ Added

🔌 WebSocket Message Size Limits (#36)
Feature Description
Max Message Size 5MB limit for WebSocket frames and accumulated messages
Close Code 1009 Connections close with standard "Message Too Big" code when exceeded
Fragment Accumulation Size checks applied during fragmented message assembly

C++ Changes:

  • Added MaxWebSocketMessageBytes (5MB) and MaxWebSocketFramePayloadBytes constants
  • Implemented size validation at frame receive, fragment accumulation, and initial payload
  • Proper teardown with WebSocketCloseCodeMessageTooBig (1009)
🔷 Blueprint Node Type Aliases (#37)

User-friendly node names now map to internal K2Node classes:

Alias K2Node Class
Branch K2Node_IfThenElse
Sequence K2Node_ExecutionSequence
ForLoop K2Node_ForLoop
ForLoopWithBreak K2Node_ForLoopWithBreak
WhileLoop K2Node_WhileLoop
Switch K2Node_SwitchInteger
Select K2Node_Select
DoOnce, DoN, FlipFlop, Gate, MultiGate Flow control nodes
SpawnActorFromClass, GetAllActorsOfClass Actor manipulation
Timeline, MakeArray, MakeStruct, BreakStruct Data/utility nodes

C++ & TypeScript Sync:

  • BLUEPRINT_NODE_ALIASES map in graph-handlers.ts
  • NodeTypeAliases map in McpAutomationBridge_BlueprintGraphHandlers.cpp
🌳 Behavior Tree Generic Node Types (#37)
Node Type Default Class Category
Task BTTask_Wait task
Decorator / Blackboard BTDecorator_Blackboard decorator
Service / DefaultFocus BTService_DefaultFocus service
Composite BTComposite_Sequence composite

Aliases for common BT nodes: Wait, MoveTo, PlaySound, Cooldown, Loop, TimeLimit, Selector, etc.

📊 show_stats Action

New show_stats action in system_control tool:

  • Toggle engine stats display (stat Unit, stat FPS, etc.)
  • Parameters: category (string), enabled (boolean)

🔧 Changed

📋 Structured Logging (#36)

Replaced console.error/console.warn with structured Logger across all tools:

File Change
actors.ts WASM debug logging
debug.ts Viewmode stability warnings
dynamic-handler-registry.ts Handler overwrite warnings
editor.ts Removed commented debug logs
physics.ts Improved error handling with fallback mesh resolution
🎯 Handler Response Improvements
Handler Change
actor-handlers.ts Returns clean responses without ResponseFactory.success() wrapping
blueprint-handlers.ts Includes blueprintPath in responses
environment.ts Changed default snapshot path to ./tmp/unreal-mcp/

🛠️ Fixed

✅ Input Validation Enhancements (#37)
Handler Validation Added
editor-handlers.ts Viewport resolution requires positive numbers
asset-handlers.ts Folder paths must start with /
lighting-handlers.ts Valid light types: point, directional, spot, rect, sky
lighting-handlers.ts Valid GI methods: lumen, screenspace, none, raytraced, ssgi
performance-handlers.ts Valid profiling types with clear error messages
performance-handlers.ts Scalability levels clamped to 0-4 range
system-handlers.ts Quality level clamped to 0-4 range
🔧 WASM Binding Patching (7cc602a)
  • Fixed TOCTOU (Time-of-Check-Time-of-Use) race condition in patch-wasm.js
  • Uses atomic file operations with file descriptors (openSync, ftruncateSync, writeSync)
  • Proper error handling for missing WASM files

🗑️ Removed

🧹 Code Cleanup
Removed Lines Reason
src/types/responses.ts content 355 Obsolete response type definitions
scripts/validate-server.js 46 Unused validation script
scripts/verify-automation-bridge.js 177 Unused functions and broken code

📊 Statistics

  • Files Changed: 28+ source files
  • Lines Removed: 436 (cleanup)
  • Lines Added: 283 (validation + features)
  • New Node Aliases: 30+ Blueprint, 20+ Behavior Tree

🏷️ [0.5.4] - 2025-12-27

Important

🛡️ Security Release

This release focuses on security hardening and defensive improvements across the entire stack, including command injection prevention, network isolation, and resource management.

🛡️ Security & Command Hardening

UBT Validation & Safe Execution
Feature Description
UBT Argument Validation Added validateUbtArgumentsString and tokenizeArgs to block dangerous characters (;, `
Safe Process Spawning Updated child process spawning to use shell: false, preventing shell injection attacks
Console Command Validation Implemented strict input validation for the Unreal Automation Bridge to block chained or multi-line commands
Argument Quoting Improved logging and execution logic to correctly quote arguments containing spaces

🌐 Network & Host Binding

Localhost Default & Remote Configuration
Feature Description
Localhost Default WebSocket, Metrics, and GraphQL servers now bind to 127.0.0.1 by default
Remote Exposure Prevention Prevents accidental remote exposure of services
GRAPHQL_ALLOW_REMOTE Added environment variable check for explicit remote binding configuration
Security Warnings Warnings logged for unsafe/permissive network settings

🚦 Resource Management

Rate Limiting & Queue Management
Feature Description
IP-Based Rate Limiting Implemented rate limiting on the metrics server
Queue Limits Introduced maxQueuedRequests to automation bridge to prevent memory exhaustion
Message Size Enforcement Enforced MAX_WS_MESSAGE_SIZE_BYTES for WebSocket connections to reject oversized payloads

🧪 Testing & Cleanup

Test Updates & File Cleanup
Change Description
Path Sanitization Tests Modified validation tests to verify path sanitization and expect errors for traversal attempts
Removed Legacy Tests Removed outdated test files (run-unreal-tool-tests.mjs, test-asset-errors.mjs)
Response Logging Implemented better response logging in the test runner

🔄 Dependencies

  • dependencies group: Bumped 2 updates via @dependabot (#33)

🏷️ [0.5.3] - 2025-12-21

Important

🔄 Major Enhancements

  • Dynamic Type Discovery - New runtime introspection for lights, debug shapes, and sequencer tracks
  • Metrics Rate Limiting - Per-IP rate limiting (60 req/min) on Prometheus endpoint
  • Centralized Class Configuration - Unified Unreal Engine class aliases
  • Enhanced Type Safety - Comprehensive TypeScript interfaces replacing any types

✨ Added

🔍 Dynamic Discovery & Engine Handlers
Feature Description
list_light_types Discovers all available light class types at runtime
list_debug_shapes Enumerates supported debug shape types
list_track_types Lists all sequencer track types available in the engine
Heuristic Resolution Improved C++ handlers use multiple naming conventions and inheritance validation
Vehicle Type Support Expanded vehicle type from union to string for flexibility

C++ Changes:

  • McpAutomationBridge_LightingHandlers.cpp - Runtime ResolveUClass for lights
  • McpAutomationBridge_SequenceHandlers.cpp - Runtime resolution for tracks
  • Added UObjectIterator.h for dynamic type scanning
  • Unified spawn/track-creation flows
  • Removed editor/PIE branching logic
⚙️ Tooling & Configuration
Feature Description
class-aliases.ts Centralized Unreal Engine class name mappings
handler-types.ts Comprehensive TypeScript interfaces (ActorArgs, EditorArgs, LightingArgs, etc.)
timeout constants Command-specific operation timeouts in constants.ts
listDebugShapes() Programmatic access in DebugVisualizationTools

Type System:

  • Geometry types: Vector3, Rotator, Transform
  • Required-component lookups
  • Centralized class-alias mappings
📈 Metrics Server Enhancements
Feature Description
Rate Limiting Per-IP limit of 60 requests/minute
Server Lifecycle Returns instance for better management
Error Handling Improved internal error handling
📚 Documentation & DX
Feature Description
handler-mapping.md Updated with new discovery actions
README.md Clarified WASM build instructions
Tool Definitions Synchronized with new discovery actions

🔧 Changed

Handler Type Safety & Logic

src/tools/handlers/common-handlers.ts:

  • Replaced any typings with strict HandlerArgs/LocationInput/RotationInput
  • Added automation-bridge connectivity validation
  • Enhanced location/rotation normalization with type guards

Specialized Handlers:

  • actor-handlers.ts - Applied typed handler-args
  • asset-handlers.ts - Improved argument normalization
  • blueprint-handlers.ts - Added new action cases
  • editor-handlers.ts - Enhanced default handling
  • effect-handlers.ts - Added list_debug_shapes
  • graph-handlers.ts - Improved validation
  • level-handlers.ts - Type-safe operations
  • lighting-handlers.ts - Added list_light_types
  • pipeline-handlers.ts - Enhanced error handling
Infrastructure & Utilities

Security & Validation:

  • command-validator.ts - Blocks semicolons, pipes, backticks
  • error-handler.ts - Enhanced error logging
  • response-validator.ts - Improved Ajv typing
  • safe-json.ts - Generic typing for cleanObject
  • validation.ts - Expanded path-traversal protection

Performance:

  • unreal-command-queue.ts - Optimized queue processing (250ms interval)
  • unreal-bridge.ts - Centralized timeout constants

🛠️ Fixed

  • Command Injection Prevention - Additional dangerous command patterns blocked
  • Path Security - Enhanced asset-name validation
  • Type Safety - Eliminated any types across handler functions
  • Error Messages - Clearer error messages for class resolution failures

📊 Statistics

  • Files Changed: 20+
  • New Interfaces: 15+ handler type definitions
  • Discovery Actions: 3 new runtime introspection methods
  • Security Enhancements: 5+ new validation patterns

🔄 Dependencies

  • graphql-yoga: Bumped from 5.17.1 to 5.18.0 (#31)

🏷️ [0.5.2] - 2025-12-18

Important

🔄 Breaking Changes

  • Standardized Tools & Type Safety - All tool handlers now use consistent interfaces with improved type safety. Some internal API signatures have changed. (079e3c2)

✨ Added

🛠️ Blueprint Enhancements (e710751)
Feature Description
Dynamic Node Creation Support for creating nodes dynamically in Blueprint graphs
Struct Property Support Added ability to set and get struct properties on Blueprint components

🔄 Changed

🎯 Standardized Tool Interfaces (#28)
Component Change
Tool Handlers Optimized bridge communication and standardized response handling
Type Safety Hardened type definitions across all tool interfaces
Bridge Optimization Improved performance and reliability of automation bridge

🔧 CI/CD

  • 🔗 MCP Publisher - Fixed download URL format in workflow steps (0d452e7)
  • 🧹 Workflow Cleanup - Removed unnecessary success conditions from MCP workflow steps (82bd575)

🏷️ [0.5.1] - 2025-12-17

Warning

⚠️ Breaking Changes

  • Standardized Return Types - All tool methods now return StandardActionResponse type instead of generic objects. Consumers must update their code to handle the new response structure with success, data, warnings, and error fields. (5e615c5)
  • Test Suite Structure - New test files added and existing tests enhanced with comprehensive coverage.

🔄 Changed

🎯 Standardized Tool Interfaces (5e615c5)
Component Change
Tool Methods Updated all tool methods to return StandardActionResponse type for consistency
Tool Interfaces Modified interfaces (assets, blueprint, editor, environment, foliage, landscape, level, sequence) to use standardized response format
Type System Added proper type imports and exports for StandardActionResponse
Handler Files Updated to work with new standardized response types
Response Structure All implementations return correct structure with success/error fields

✨ Added

🧪 Comprehensive Test Suite (#25)
Feature Description
Test Coverage Added comprehensive test files with success, error, and edge cases
GraphQL DataLoader Implemented N+1 query optimization with batching and caching
Type-Safe Interfaces Added type-safe automation response interfaces for better error handling
Utility Tests Added tests for core utilities (normalize, safe-json, validation)
Real-World Scenarios Enhanced coverage with real-world scenarios and cleanup procedures
New Test Suites Audio, lighting, performance, input, and asset graph management
Enhanced Logging Improved diagnostic logging throughout tools
Documentation Updated supported Unreal Engine versions (5.0-5.7) in testing documentation

🧹 Maintenance

  • 🗑️ Prompts Module Cleanup - Removed prompts module and related GraphQL prompt functionality (#26)
  • 🔒 Security Updates - Removed unused dependencies (axios, json5, yargs) from package.json for security (5e615c5)
  • 📐 Tool Interfaces - Enhanced asset and level tools with security validation and timeout handling (5e615c5)

📦 Dependencies

GitHub Actions Updates
Package Update PR Commit
actions/checkout v4 → v6 #23 4c6b3b5
actions/setup-node v4 → v6 #22 71aa35c
softprops/action-gh-release 2.0.8 → 2.5.0 #21 b6c8a46
NPM Package Updates (#24, 5e615c5)
Package Update
@modelcontextprotocol/sdk 1.25.0 → 1.25.1
@types/node 25.0.2 → 25.0.3

🏷️ [0.5.0] - 2025-12-16

Important

🔄 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
  • 🚫 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.

🏗️ Architecture

Change Description
🆕 Native C++ Plugin Introduced McpAutomationBridge - a native UE5 editor plugin replacing the Remote API
🔌 Direct Editor Integration Commands execute directly in the editor context via automation bridge subsystem
🌐 WebSocket Communication Implemented McpBridgeWebSocket for real-time bidirectional communication
🎯 Bridge-First Architecture All operations route through the native C++ bridge (fe65968)
📐 Standardized Responses All tools now return StandardActionResponse format (0a8999b)

✨ Added

🎮 Engine Compatibility
  • UE 5.7 Support - Updated McpAutomationBridge with ControlRig dynamic loading and improved sequence handling (ec5409b)
🔧 New APIs & Integrations
  • GraphQL API - Broadened automation bridge with GraphQL support, WASM integration, UI/editor integrations (ffdd814)
  • WebAssembly Integration - High-performance JSON parsing with 5-8x performance gains (23f63c7)
🌉 Automation Bridge Features
Feature Commit
Server mode on port 8091 267aa42
Client mode with enhanced connection handling bf0fa56
Heartbeat tracking and output capturing 28242e1
Event handling and asset management d10e1e2
🎛️ New Tool Systems (0a8999b, 0ac82ac)
Tool Description
🎮 Input Management New manage_input tool with EnhancedInput support for Input Actions and Mapping Contexts
💡 Lighting Manager Full lighting configuration via manage_lighting including spawn, GI setup, shadow config, build lighting
📊 Performance Manager manage_performance with profiling (CPU/GPU/Memory), optimization, scalability, Nanite/Lumen config
🌳 Behavior Tree Editing Full behavior tree creation and node editing via manage_behavior_tree
🎬 Enhanced Sequencer Track operations (add/remove tracks, set muted/solo/locked), display rate, tick resolution
🌍 World Partition Cell management, data layer toggling via manage_level
🖼️ Widget Management UI widget creation, visibility controls, child widget adding
📊 Graph Editing Capabilities (0a8999b)
  • Blueprint Graph - Direct node manipulation with manage_blueprint_graph (create_node, delete_node, connect_pins, etc.)
  • Material Graph - Node operations via manage_asset (add_material_node, connect_material_pins, etc.)
  • Niagara Graph - Module and parameter editing (add_niagara_module, set_niagara_parameter, etc.)
🛠️ New Handlers & Actions
  • Blueprint graph management and Niagara functionalities (aff4d55)
  • Physics simulation setup in AnimationTools (83a6f5d)
  • New Asset Actions:
    • generate_lods, add_material_parameter, list_instances
    • reset_instance_parameters, get_material_stats, exists
    • nanite_rebuild_mesh
  • World partition and rendering tool handlers (83a6f5d)
  • Screenshot with base64 image encoding (bb4f6a8)
🧪 Test Suites

50+ new test cases covering:

  • Animation, Assets, Materials
  • Sequences, World Partition
  • Blueprints, Niagara, Behavior Trees
  • Audio, Input Actions
  • And more! (31c6db9, 85817c9, fc47839, 02fd2af)

🔄 Changed

Core Refactors

Component Change Commit
SequenceTools Migrated to Automation Bridge c2fb15a
UnrealBridge Refactored for bridge connection 7bd48d8
Automation Dispatch Editor-native handlers modernization c9db1a4
Test Runner Timeout expectations & content extraction c9766b0
UI Handlers Improved readability and organization bb4f6a8
Connection Manager Streamlined connection handling 0ac82ac

Tool Improvements

  • 🚗 PhysicsTools - Vehicle config logic updated, deprecated checks removed (6dba9f7)
  • 🎬 AnimationTools - Logging and response normalization (7666c31)
  • ⚠️ Error Handling - Utilities refactored, INI file reader added (f5444e4)
  • 📐 Blueprint Actions - Timeout handling enhancements (65d2738)
  • 🎨 Materials - Enhanced material graph editing capabilities (0a8999b)
  • 🔊 Audio - Improved sound component management (0a8999b)

Other Changes

  • 📡 Connection & Logging - Improved error messages for clarity (41350b3)
  • 📚 Documentation - README updated with UE 5.7, WASM docs, architecture overview, 17 tools (8d72f28, 4d77b7e)
  • 🔄 Dependencies - Updated to latest versions (08eede5)
  • 📝 Type Definitions - Enhanced tool interfaces and type coverage (0a8999b)

🐛 Fixed

  • McpAutomationBridgeSubsystem - Header removal, logging category, heartbeat methods (498f644)
  • McpBridgeWebSocket - Reliable WebSocket communication (861ad91)
  • AutomationBridge - Heartbeat handling and server metadata retrieval (0da54f7)
  • UI Handlers - Missing payload and invalid widget path error handling (bb4f6a8)
  • Screenshot - Clearer error messages and flow (bb4f6a8)

🗑️ Removed

Removed Reason
🔌 Remote API Dependency Replaced by native C++ plugin
🐍 Python Fallbacks Native C++ automation preferred (fe65968)
📦 Unused HTTP Client Cleanup from error-handler (f5444e4)

🏷️ [0.4.7] - 2025-11-16

✨ Added

  • Output Log reading via system_control tool with read_log action. filtering by category, level, line count.
  • New src/tools/logs.ts implementing robust log tailing.
  • 🆕 Initial McpAutomationBridge plugin with foundational implementation (30e62f9)
  • 🧪 Comprehensive test suites for various Unreal Engine tools (31c6db9)

🔄 Changed

  • system_control tool schema: Added read_log action.
  • Updated tool handlers to route read_log to LogTools.
  • Version bumped to 0.4.7.

📚 Documentation

  • Updated README.md with initial bridge documentation (a24dafd)

🏷️ [0.4.6] - 2025-10-04

🐛 Fixed

  • Fixed duplicate response output issue where tool responses were displayed twice in MCP content
  • Response validator now emits concise summaries instead of duplicating full JSON payloads
  • Structured content preserved for validation while user-facing output is streamlined

🏷️ [0.4.5] - 2025-10-03

✨ Added

  • 🔧 Expose UE_PROJECT_PATH environment variable across runtime config, Smithery manifest, and client configs
  • 📁 Added projectPath to runtime configSchema for Smithery's session UI

🔄 Changed

  • ⚡ Made createServer synchronous factory (removed async)
  • 🏠 Default for ueHost in exported configSchema

📚 Documentation

  • Updated README.md, config examples to include UE_PROJECT_PATH
  • Updated smithery.yaml and server.json manifests

🔨 Build

  • Rebuilt Smithery bundle and TypeScript output

🐛 Fixed

  • Smithery UI blank ueHost field by defining default in runtime schema

🏷️ [0.4.4] - 2025-09-28

✨ Improvements

  • 🤝 Client Elicitation Helper - Added support for Cursor, VS Code, Claude Desktop, and other MCP clients
  • 📊 Consistent RESULT Parsing - Handles JSON5 and legacy Python literals across all tools
  • 🔒 Safe Output Stringification - Robust handling of circular references and complex objects
  • 🔍 Enhanced Logging - Improved validation messages for easier debugging

🏷️ [0.4.0] - 2025-09-20

Major Release - Consolidated Tools Mode

✨ Improvements

  • 🎯 Consolidated Tools Mode Exclusively - Removed legacy mode, all tools now use unified handler system
  • 🧹 Simplified Tool Handlers - Removed deprecated code paths and inline plugin validation
  • 📝 Enhanced Error Handling - Better error messages and recovery mechanisms

🔧 Quality & Maintenance

  • ⚡ Reduced resource usage by optimizing tool handlers
  • 🧹 Cleanup of deprecated environment variables

🏷️ [0.3.1] - 2025-09-19

BREAKING: Connection behavior is now on-demand

🏗️ Architecture

  • 🔄 On-Demand Connection - Shifted to intelligent on-demand connection model
  • 🚫 No Background Processes - Eliminated persistent background connections

⚡ Performance

  • Reduced resource usage and eliminated background processes
  • Optimized connection state management

🛡️ Reliability

  • Improved error handling and connection state management
  • Better recovery from connection failures

🏷️ [0.3.0] - 2025-09-17

🎉 Initial Public Release

✨ Features

  • 🎮 13 Consolidated Tools - Full suite of Unreal Engine automation tools
  • 📁 Normalized Asset Listing - Auto-map /Content and /Game paths
  • 🏔️ Landscape Creation - Returns real UE/Python response data
  • 📝 Action-Oriented Descriptions - Enhanced tool documentation with usage examples

🔧 Quality & Maintenance

  • Server version 0.3.0 with clarified 13-tool mode
  • Comprehensive documentation and examples
  • Lint error fixes and code style cleanup

🔗 Links

GitHub npm UE5