ue-mcp 1.2.3 → 1.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ue-mcp",
-  "version": "1.2.3",
-  "description": "Unreal Engine MCP server - 24 tools, 783+ actions for AI-driven editor control",
+  "version": "1.3.0",
+  "description": "Unreal Engine MCP server - 24 tools, 845+ actions for AI-driven editor control",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/plugin/ue_mcp_bridge/NATIVE_RUNTIME_VISIBILITY.md

@@ -0,0 +1,53 @@
+# Native Runtime Visibility Batch
+
+This plugin exposes two raw bridge handlers for bounded, reversible visibility
+changes in a running Play In Editor (PIE) world:
+
+- `set_runtime_visibility`
+- `restore_runtime_visibility`
+
+The handlers replace repeated Python actor/component enumeration and one-off
+visibility calls with one native preflighted operation. They are intentionally
+plugin-only in this change. Raw bridge clients can discover both names through
+`get_bridge_capabilities.actions`; adding a typed MCP server action is separate
+work outside this plugin-scoped change.
+
+## Set contract
+
+`set_runtime_visibility` requires `hidden` and exactly one actor selector:
+`actorLabels`, `actorPaths`, or `actorClass`. Optional `componentNames` and
+`componentClasses` filters select scene components. Class names use the shared
+UE-MCP class resolver, including C++ prefixes, script paths, and Blueprint class
+paths.
+
+Safety defaults and limits:
+
+- `world` is fixed to `pie`; `pieInstance` selects a specific PIE context and
+  is required when more than one PIE world is active.
+- `dryRun` defaults to `true`.
+- `maxTargets` defaults to 64 and cannot exceed 256.
+- Explicit actor and component filter arrays cannot exceed 64 entries.
+- `all` is rejected.
+- Selection, descendant expansion, and rollback state capture finish before any
+  visibility mutation.
+- Component state uses `SetVisibility` and `SetHiddenInGame`; actor state uses
+  `SetActorHiddenInGame`.
+- No editor visibility flag is changed and no package is saved or dirtied.
+
+When a non-dry-run call changes state, the response includes a standard rollback
+payload for `restore_runtime_visibility`. Its opaque token refers to a bounded
+native snapshot containing weak world and object identities, including Unreal's
+object serials. Restore fails closed after PIE restarts or if any target was
+destroyed, and it preflights every target before applying changes. Tokens are
+process-local and expire when their snapshot is pruned or the plugin unloads.
+
+Actor hidden state may be authority-owned or replicated. Callers should select
+the intended server or client `pieInstance`; later replication can supersede a
+client-local actor visibility change.
+
+## Native validation boundary
+
+The plugin Automation test verifies registration, raw capability discovery, and
+safe parameter/class/world rejections without mutating a user's running editor.
+Live apply, propagation, multi-PIE selection, and rollback behavior require the
+dedicated UE-MCP smoke project so they can operate on disposable runtime actors.

package/plugin/ue_mcp_bridge/NATIVE_STATIC_MESH_USAGE_PROGRESS.md

@@ -0,0 +1,115 @@
+# Native Static Mesh Usage Progress
+
+Last updated: 2026-08-12
+
+## Status
+
+| Field | Value |
+| --- | --- |
+| Overall | Source implementation committed; native validation pending; draft PR awaiting review |
+| Pull request | [db-lyon/ue-mcp#903](https://github.com/db-lyon/ue-mcp/pull/903) |
+| Branch | `codex/native-static-mesh-usage` |
+| Base | `db-lyon/ue-mcp:main` at `849a194` |
+| Scope | `plugin/ue_mcp_bridge` only |
+| Handler | `summarize_static_mesh_usage` |
+| Mutation policy | Read-only |
+
+## Goal
+
+Provide a native replacement for the repetitive current-level workflow of
+enumerating actors, reading each static mesh component, and aggregating mesh
+properties through many bridge calls or an `execute_python` script. The raw
+bridge handler performs the common inspection in one bounded game-thread request.
+A typed server action is intentionally deferred because this change is limited
+to the UE-MCP plugin folder.
+
+## Completed
+
+- [x] Register `summarize_static_mesh_usage` with the level handler registry.
+- [x] Support exact `editor` and `pie` world selection, including `pieInstance`.
+- [x] Scan loaded actors and all owned `UStaticMeshComponent` subclasses.
+- [x] Count actors, components, and placements separately.
+- [x] Count a plain static mesh component as one placement.
+- [x] Count ISMC and HISM placements with `GetInstanceCount()`.
+- [x] Preserve zero-instance components in component totals without adding placements.
+- [x] Report null-mesh components diagnostically.
+- [x] Sort results by placement count descending, then mesh path ascending.
+- [x] Bound returned mesh rows to 1 through 500.
+- [x] Bound occurrence examples to 0 through 256 across the response.
+- [x] Fail closed above 8,192 unique loaded meshes.
+- [x] Report full-scan totals even when result rows are truncated.
+- [x] Author plugin-local Automation coverage for registration, world validation,
+  aggregation, ordering, plain and ISMC placement semantics, null meshes, and bounds.
+- [x] Complete independent static review against Unreal Engine 5.8 APIs.
+- [x] Open a plugin-only draft pull request.
+
+## Validation
+
+| Check | Result | Evidence |
+| --- | --- | --- |
+| Local engine-free unit suite | Passed | 83 files, 840 tests |
+| Local TypeScript type check | Passed | `npx tsc --noEmit` |
+| Local unity collision audit | Passed | `npm run audit:unity` |
+| Local em dash audit | Passed | `npm run audit:em-dash` |
+| GitHub engine-free CI | Passed | Workflow run `31600014333`: 83 files and 840 unit tests, plus 4 files and 32 multi-editor tests |
+| UE 5.8 API/static review | Passed | No P0 or P1 findings |
+| Native Unreal compilation | Not yet proven | Guarded local build stopped before compilation because protected engine outputs would have changed |
+| Native Automation execution | Not yet run | Requires a prepared Unreal test engine or upstream CI lane that compiles the plugin |
+
+The GitHub CI runner has no Unreal installation. Its successful build job
+exercises the repository's Node and TypeScript checks; it does not replace
+native Unreal compilation or execution of the new Automation tests. The
+workflow's `publish` and `surface_counts` jobs were skipped, not failed.
+
+## Changed Files
+
+- `Source/UE_MCP_Bridge/Private/Handlers/LevelHandlers.cpp`
+- `Source/UE_MCP_Bridge/Private/Handlers/LevelHandlers.h`
+- `Source/UE_MCP_Bridge/Private/Handlers/LevelHandlers_Inspection.cpp`
+- `Source/UE_MCP_Bridge/Private/Tests/LevelStaticMeshUsageTests.cpp`
+- `Source/UE_MCP_Bridge/UE_MCP_Bridge.Build.cs`
+- `NATIVE_STATIC_MESH_USAGE_PROGRESS.md`
+
+## Current Contract
+
+Example parameters:
+
+```json
+{
+  "world": "editor",
+  "maxResults": 100,
+  "includeOccurrences": false,
+  "maxOccurrences": 32
+}
+```
+
+The result is explicitly `loadedOnly`. It summarizes the selected loaded world
+and makes no claim about unloaded World Partition actors. It performs no asset
+loads, saves, or mutations.
+
+## Remaining Work
+
+- [ ] Compile the plugin in a prepared Unreal Engine test lane.
+- [ ] Run `UE.MCP.Level.SummarizeStaticMeshUsage.*` Automation tests.
+- [ ] Address any upstream review comments on PR #903. None exist as of the
+  last-updated date.
+- [ ] Decide separately whether to expose a typed server action outside the
+  plugin folder. That is intentionally not part of this plugin-only change.
+- [ ] Mark the PR ready for review after native validation or maintainer approval
+  of the documented validation boundary.
+
+## Update Rules
+
+Keep this file current whenever implementation, validation, review state, or
+scope changes:
+
+1. Update the date and overall status.
+2. Move finished items into `Completed` or check them in place.
+3. Record exact validation commands and outcomes without overstating coverage.
+4. Add newly discovered blockers or follow-up work under `Remaining Work`.
+5. Keep all project-specific context outside this plugin progress record.
+
+## History
+
+- 2026-08-12: Native handler, focused tests, static review, engine-free validation,
+  and draft PR completed. Native Unreal compilation remains pending.

package/plugin/ue_mcp_bridge/README_MassHandlers.md

@@ -0,0 +1,97 @@
+# Mass entity config handler
+
+`ensure_mass_entity_config` creates or idempotently extends a
+`UMassEntityConfigAsset` without requiring a hard Mass module dependency in
+the bridge. The handler resolves the Mass classes at runtime, so the bridge
+continues to load when Mass is not enabled.
+
+`read_mass_entity_config` is the corresponding read-only audit operation. It
+returns `assetPath`, `assetClass`, `traitCount`, an ordered `traitClasses`
+array, and ordered `traits` records. Each record contains `index`, `classPath`,
+`className`, and a `properties` object. Object and soft-object properties are
+reported as object paths, so a StateTree assignment can be verified exactly.
+
+`read_state_tree` returns `schemaClass` and `schemaPath` plus `subTrees`. Each state record
+contains ordered `tasks`, `enterConditions`, and `transitions`; node records
+include `structType`, `instanceProperties`, and `nodeProperties` (including
+`bConsideredForCompletion`). Transition records include `trigger`,
+`transitionType`, `targetStateId`, `targetStatePath`, `bDelayTransition`,
+`delayDuration`, and `delayRandomVariance`. The response also includes exact
+`editorBindings` records with source/target struct IDs and paths.
+
+## Skeletal mesh instancing build flag
+
+`set_skeletal_mesh_optimize_for_instancing` edits only the requested skeletal
+mesh asset's LOD build settings. Parameters are `assetPath`, required boolean
+`enabled`, and either `lodIndex` (default `0`) or `allLods: true`. It validates
+the mesh and LOD selection before mutation, is idempotent, calls `Modify()`
+before changing settings, and saves only that mesh package. The response
+contains `updated`, `saved`, `changedLods`, and ordered `lods[]` records with
+`lodIndex`, `beforeOptimizeForInstancing`, `afterOptimizeForInstancing`, and
+`changed`. Each record also includes complete `beforeBuildSettings` and
+`afterBuildSettings` objects, including `bOptimizeForInstancing` and the
+other UE 5.8 skeletal build flags.
+
+`read_skeletal_mesh_build_settings` is the read-only counterpart. It accepts
+the same LOD selection parameters and returns `assetPath`, `lodCount`, and
+`lods[]` with the exact current `bOptimizeForInstancing` value and complete
+`afterBuildSettings` object for each LOD.
+
+Example:
+
+```json
+{
+  "assetPath": "/Game/Mass/WorkerAI.WorkerAI",
+  "onConflict": "update",
+  "traits": [
+    {
+      "class": "/Script/MassAIBehavior.MassStateTreeTrait",
+      "properties": {
+        "StateTree": "/Game/Mass/WorkerAIStateTree.WorkerAIStateTree"
+      }
+    }
+  ]
+}
+```
+
+The MMO persistent-pawn validation config uses this exact four-trait list:
+
+```json
+{
+  "assetPath": "/Game/MMOValidation/MassPersistentPawn/DA_MassPersistentPawnWorkerAI.DA_MassPersistentPawnWorkerAI",
+  "onConflict": "update",
+  "traits": [
+    { "class": "/Script/MMOHumanoidMassRuntime.MMOHumanoidMassEntityTrait" },
+    { "class": "/Script/MassNavMeshNavigation.MassNavMeshNavigationTrait" },
+    { "class": "/Script/MassMovement.MassMovementTrait" },
+    {
+      "class": "/Script/MassAIBehavior.MassStateTreeTrait",
+      "properties": {
+        "StateTree": "/Game/MMOValidation/MassPersistentPawn/ST_MassPersistentPawnWorkerAI.ST_MassPersistentPawnWorkerAI"
+      }
+    }
+  ]
+}
+```
+
+Traits are ordered and unique. Existing assets may be extended only when the
+requested list has the existing list as an exact prefix. Conflicting order,
+duplicate classes, replacement, and removal are rejected. `onConflict` accepts
+`skip`, `error`, or `update` (default). Trait properties use the bridge's
+recursive JSON property conversion, including object and soft-object paths.
+
+## Native asset validation
+
+`validate_assets` performs synchronous validation through
+`UEditorValidatorSubsystem::ValidateAssetsWithSettings`; it does not invoke a
+console command or save assets. Use `assetPaths` (an array) or `assetPath` for
+exact package/object paths, or retain the backward-compatible recursive
+`directory` form (default `/Game/`). Explicit package paths must resolve to
+exactly one asset; missing and ambiguous paths fail before validation starts.
+
+The successful response includes `selectionMode`, `selection`,
+`validationUsecase`, `requested`, `checked`, `valid`, `invalid`, `skipped`,
+`warnings`, `unableToValidate`, `externalObjects`, `assetLimitReached`, and an
+overall `result`. Ordered `assets[]` details include `objectPath`, package and
+asset names, per-asset result, `errors`, `warnings`, and tokenized `messages`;
+any non-asset tokenized messages are returned in `validatorMessages`.

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/BridgeServer.cpp

@@ -26,7 +26,11 @@
 #include "Async/Async.h"
 #include "Handlers/EditorHandlers.h"
 #include "Handlers/AssetHandlers.h"
+#include "Handlers/AssetHandlers_Geometry.h"
+#include "Handlers/AssetHandlers_MeshBoolean.h"
+#include "Handlers/AssetHandlers_BulkRead.h"
 #include "Handlers/BlueprintHandlers.h"
+#include "Handlers/BlueprintHandlers_Collision.h"
 #include "Handlers/ProjectHandlers.h"
 #include "Handlers/LevelHandlers.h"
 #include "Handlers/ReflectionHandlers.h"
@@ -49,6 +53,8 @@
 #include "Handlers/StateTreeHandlers.h"
 #include "Handlers/ChooserHandlers.h"
 #include "Handlers/EpicHandlers.h"
+#include "Handlers/MassHandlers.h"
+#include "Handlers/SkeletalMeshHandlers.h"
 #include "Handlers/FabHandlers.h"
 #include "Handlers/LockHandlers.h"
 #include "Handlers/DiffHandlers.h"
@@ -129,7 +135,13 @@ FMCPBridgeServer::FMCPBridgeServer(int32 Port, const FString& InPortSource, bool
 	// Register core handlers
 	FEditorHandlers::RegisterHandlers(HandlerRegistry);
 	FAssetHandlers::RegisterHandlers(HandlerRegistry);
+	FAssetGeometryHandlers::RegisterHandlers(HandlerRegistry);
+	FAssetMeshBooleanHandlers::RegisterHandlers(HandlerRegistry);
+	// #909: bulk_read_asset_properties, in its own translation unit so a
+	// library-wide read lands without reopening AssetHandlers.cpp.
+	FAssetBulkReadHandlers::RegisterHandlers(HandlerRegistry);
 	FBlueprintHandlers::RegisterHandlers(HandlerRegistry);
+	FCollisionQueryHandlers::RegisterHandlers(HandlerRegistry);
 	FLevelHandlers::RegisterHandlers(HandlerRegistry);
 	FReflectionHandlers::RegisterHandlers(HandlerRegistry);
 	FGasHandlers::RegisterHandlers(HandlerRegistry);
@@ -152,6 +164,8 @@ FMCPBridgeServer::FMCPBridgeServer(int32 Port, const FString& InPortSource, bool
 	FStateTreeHandlers::RegisterHandlers(HandlerRegistry);
 	FChooserHandlers::RegisterHandlers(HandlerRegistry);
 	FEpicHandlers::RegisterHandlers(HandlerRegistry);
+	FMassHandlers::RegisterHandlers(HandlerRegistry);
+	FSkeletalMeshHandlers::RegisterHandlers(HandlerRegistry);
 	FFabHandlers::RegisterHandlers(HandlerRegistry);
 	FLockHandlers::RegisterHandlers(HandlerRegistry);
 	FDiffHandlers::RegisterHandlers(HandlerRegistry);

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/GameThreadExecutor.cpp

@@ -84,7 +84,18 @@ void FMCPGameThreadExecutor::DrainModalSafeQueue()
 
 TSharedPtr<FJsonValue> FMCPGameThreadExecutor::ExecuteOnGameThread(FHandlerFunction Handler, const TSharedPtr<FJsonObject>& Params, float TimeoutSeconds, bool bModalSafe)
 {
-	if (!bEditorReady)
+	// #968: the readiness gate does not apply to the handlers whose job is to
+	// clear a block. A modal raised during startup (the "Restore Packages"
+	// prompt after an unclean shutdown) holds the game thread before the editor
+	// is ready, and this gate then rejected respond_to_dialog and
+	// set_dialog_policy - the two calls that could dismiss it - with "Editor is
+	// still initializing", while get_engine_state cheerfully described the
+	// dialog down to its button labels because it answers off the game thread.
+	// The gate was blocked by the very dialog the call would have dismissed,
+	// and the only way out was an OS kill that discarded the user's autosave
+	// choice. Modal-safe handlers read or answer the active dialog through
+	// Slate and touch nothing that startup has yet to build, so they run.
+	if (!bEditorReady && !bModalSafe)
 	{
 		TSharedPtr<FJsonObject> ErrorObject = MakeShared<FJsonObject>();
 		ErrorObject->SetStringField(TEXT("error"), TEXT("Editor is still initializing. Please wait and retry."));
@@ -106,7 +117,7 @@ TSharedPtr<FJsonValue> FMCPGameThreadExecutor::ExecuteOnGameThread(FHandlerFunct
 
 	// Capture Handler and Params by value so they outlive the caller's stack
 	// if the caller abandons the wait.
-	auto RunOnce = [State, Handler, Params]()
+	auto RunOnce = [State, Handler, Params, bModalSafe]()
 	{
 		// Caller already gave up - skip the work entirely. Python may
 		// still be mid-execution; we cannot safely cancel it, but we
@@ -122,8 +133,14 @@ TSharedPtr<FJsonValue> FMCPGameThreadExecutor::ExecuteOnGameThread(FHandlerFunct
 			return;
 		}
 
-		// Safety: verify GEditor is available before running handlers
-		if (!GEditor)
+		// Safety: verify GEditor is available before running handlers.
+		//
+		// #968: except for the modal-safe ones. They go through Slate and check
+		// FSlateApplication for themselves, so GEditor is not something they
+		// need, and refusing them here would put the startup deadlock back one
+		// layer down: a dialog raised before GEditor exists is exactly the one
+		// nothing else can clear.
+		if (!GEditor && !bModalSafe)
 		{
 			TSharedPtr<FJsonObject> ErrorObject = MakeShared<FJsonObject>();
 			ErrorObject->SetStringField(TEXT("error"), TEXT("Editor world not ready yet. Retry in a moment."));

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/GameThreadExecutor.h

@@ -23,6 +23,15 @@ public:
 	// could clear the dialog. Handlers that only read or answer the active
 	// dialog are safe to run in that loop and get unstuck this way; nothing
 	// else should set it.
+	//
+	// #968: it also exempts the call from the "editor is still initializing"
+	// gate and from the GEditor check. A modal raised during startup blocks the
+	// game thread before the editor is ever marked ready, so gating the dialog
+	// handlers on readiness made the block permanent: the gate was held shut by
+	// the dialog those calls exist to dismiss, and the only escape was an OS
+	// kill. The two exemptions travel together because they describe one
+	// property - this handler is how a blocked engine gets unblocked, so no
+	// block may stand in front of it.
 	TSharedPtr<FJsonValue> ExecuteOnGameThread(FHandlerFunction Handler, const TSharedPtr<FJsonObject>& Params, float TimeoutSeconds = 30.0f, bool bModalSafe = false);
 
 	// Run any modal-safe work that was queued while a dialog blocked the