ue-mcp 1.2.4 → 1.3.0

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Public/HandlerUtils.h

@@ -7,11 +7,15 @@
 #include "UObject/UObjectIterator.h"
 #include "UObject/Package.h"
 #include "UObject/SavePackage.h"
+#include "HAL/FileManager.h"
 #include "Misc/PackageName.h"
 #include "Engine/World.h"
 #include "Engine/Blueprint.h"
 #include "EngineUtils.h"
 #include "GameFramework/Actor.h"
+#include "EditorAssetLibrary.h"
+#include "AssetRegistry/AssetRegistryModule.h"
+#include "AssetRegistry/IAssetRegistry.h"
 
 // Engine API tiers. One macro per supported minor version, so a gate reads the
 // same everywhere and nobody writes a second scheme. The supported range is
@@ -135,6 +139,280 @@ inline TSharedPtr<FJsonValue> MCPCheckAssetExists(
 	return TSharedPtr<FJsonValue>();
 }
 
+// -- Asset path forms ---------------------------------------------------------
+
+/** The forms one asset path can take. `/Game/Foo/DT_Thing` names the package
+ *  and `/Game/Foo/DT_Thing.DT_Thing` names the asset inside it; both are
+ *  legitimate ways to address the same asset, asset(search) reports the first
+ *  one, and #957 was a set of actions that accepted only the second. Deriving
+ *  both forms once, here, is what lets every action accept either and lets a
+ *  miss report which form it actually tried. */
+struct FMCPAssetPathForms
+{
+	/** Exactly what the caller sent, untouched. */
+	FString Input;
+	/** `/Game/Foo/DT_Thing` */
+	FString PackagePath;
+	/** `/Game/Foo/DT_Thing.DT_Thing` */
+	FString ObjectPath;
+	/** `DT_Thing` */
+	FString AssetName;
+	/** True when the caller already supplied the object name. */
+	bool bInputCarriedObjectName = false;
+};
+
+/** Derive every path form from whatever the caller supplied. Accepts the
+ *  export-text form (`DataTable'/Game/Foo/DT.DT'`), the object path and the
+ *  bare package path, and tolerates surrounding whitespace. */
+inline FMCPAssetPathForms MCPAssetPathForms(const FString& AssetPath)
+{
+	FMCPAssetPathForms Forms;
+	Forms.Input = AssetPath;
+
+	FString Normalized = FPackageName::ExportTextPathToObjectPath(AssetPath);
+	Normalized.TrimStartAndEndInline();
+	if (Normalized.IsEmpty()) return Forms;
+
+	Forms.PackagePath = FPackageName::ObjectPathToPackageName(Normalized);
+	// ObjectPathToPackageName is the identity on a bare package path, so a
+	// longer input is the only thing that can have carried an object name.
+	Forms.bInputCarriedObjectName = Normalized.Len() > Forms.PackagePath.Len();
+
+	if (Forms.bInputCarriedObjectName)
+	{
+		Forms.ObjectPath = Normalized;
+		Forms.AssetName = FPackageName::ObjectPathToObjectName(Normalized);
+	}
+	else
+	{
+		// A package holds its asset under the package's own leaf name. This is
+		// the convention every content asset follows and the form
+		// UEditorAssetLibrary::LoadAsset builds internally.
+		if (!Forms.PackagePath.Split(TEXT("/"), nullptr, &Forms.AssetName,
+			ESearchCase::CaseSensitive, ESearchDir::FromEnd))
+		{
+			Forms.AssetName = Forms.PackagePath;
+		}
+		Forms.ObjectPath = Forms.AssetName.IsEmpty()
+			? Forms.PackagePath
+			: Forms.PackagePath + TEXT(".") + Forms.AssetName;
+	}
+	return Forms;
+}
+
+/** Load the asset at `AssetPath`, the way asset(read) does.
+ *
+ *  UEditorAssetLibrary::LoadAsset is the usual entry point, but it validates
+ *  the path through EditorScriptingHelpers before it loads anything and
+ *  answers null for path forms it does not accept, and for any call made
+ *  while the editor is in play-in-editor. asset(read) has always had a
+ *  LoadObject fallback for exactly that reason, and the type-specific readers
+ *  did not: read_datatable, get_datatable_row and export all reported
+ *  "Asset not found" or "Asset is not a DataTable" for assets that
+ *  asset(read) opened and correctly named as DataTables (#930).
+ *
+ *  This lives here rather than as a copy per handler file: the asset handlers
+ *  share one unity blob, and a second copy would either collide at compile
+ *  time or drift into resolving differently from its neighbours. */
+inline UObject* MCPLoadAssetObject(const FString& AssetPath)
+{
+	if (AssetPath.IsEmpty()) return nullptr;
+
+	const FMCPAssetPathForms Forms = MCPAssetPathForms(AssetPath);
+	if (Forms.ObjectPath.IsEmpty()) return nullptr;
+
+	// An object already in memory is the answer, and running a path validator
+	// over it can only turn a good answer into a null and an error log. The
+	// object path is what this step needs: a path with no "." names a package,
+	// and returning the UPackage in place of the asset would be a worse answer
+	// than not looking, so the derived object path stands in for it.
+	if (UObject* Loaded = FindObject<UObject>(nullptr, *Forms.ObjectPath))
+	{
+		if (!Loaded->IsA<UPackage>()) return Loaded;
+	}
+
+	if (UObject* ViaEditorLibrary = UEditorAssetLibrary::LoadAsset(AssetPath))
+	{
+		return ViaEditorLibrary;
+	}
+
+	// #957: the caller's own form is tried first so nothing that used to work
+	// stops working, and the derived object path second. A bare package path
+	// for an asset that is not loaded yet is the case that used to answer
+	// "Asset not found" for an asset asset(search) had just reported by that
+	// exact string, because the load stopped at a form the loader would not
+	// resolve on its own.
+	if (UObject* ViaInput = LoadObject<UObject>(nullptr, *AssetPath))
+	{
+		if (!ViaInput->IsA<UPackage>()) return ViaInput;
+	}
+	if (!Forms.bInputCarriedObjectName)
+	{
+		if (UObject* ViaObjectPath = LoadObject<UObject>(nullptr, *Forms.ObjectPath))
+		{
+			if (!ViaObjectPath->IsA<UPackage>()) return ViaObjectPath;
+		}
+	}
+	return nullptr;
+}
+
+/** Look an asset path up in the Asset Registry without loading anything.
+ *  Tries the exact object path first, then any asset the registry holds in
+ *  that package, which is what distinguishes "the package has an asset under
+ *  a different name" from "there is nothing there at all". */
+inline FAssetData MCPFindAssetDataForPath(const FMCPAssetPathForms& Forms)
+{
+	if (Forms.PackagePath.IsEmpty()) return FAssetData();
+
+	FAssetRegistryModule* Module = FModuleManager::GetModulePtr<FAssetRegistryModule>(TEXT("AssetRegistry"));
+	if (!Module) return FAssetData();
+	IAssetRegistry& Registry = Module->Get();
+
+	if (!Forms.ObjectPath.IsEmpty())
+	{
+		const FAssetData Exact = Registry.GetAssetByObjectPath(FSoftObjectPath(Forms.ObjectPath));
+		if (Exact.IsValid()) return Exact;
+	}
+
+	TArray<FAssetData> InPackage;
+	Registry.GetAssetsByPackageName(FName(*Forms.PackagePath), InPackage);
+	for (const FAssetData& Candidate : InPackage)
+	{
+		if (Candidate.IsValid()) return Candidate;
+	}
+	return FAssetData();
+}
+
+/** The answer for a path MCPLoadAssetObject could not resolve.
+ *
+ *  A bare "Asset not found" is the same sentence for a path that names nothing,
+ *  a path whose shape the loader rejects, and an asset whose package will not
+ *  open, and #957 and #913 were both reported as missing assets that were not
+ *  missing at all. This names the forms that were tried, says whether the
+ *  package is on disk, reports what the Asset Registry knows without loading
+ *  anything, and, when the registry holds the asset under a different object
+ *  path, names the form that would have worked. */
+inline TSharedPtr<FJsonValue> MCPAssetNotFoundError(const FString& AssetPath, const FString& Context = FString())
+{
+	const FMCPAssetPathForms Forms = MCPAssetPathForms(AssetPath);
+	const FAssetData Found = MCPFindAssetDataForPath(Forms);
+	const bool bPackageOnDisk = !Forms.PackagePath.IsEmpty()
+		&& FPackageName::IsValidLongPackageName(Forms.PackagePath)
+		&& FPackageName::DoesPackageExist(Forms.PackagePath);
+
+	// Context, when given, names what the path was supposed to be, so the
+	// sentence reads "Source asset not found: ..." rather than the generic form.
+	const FString Prefix = FString::Printf(
+		TEXT("%s not found: '%s'."), Context.IsEmpty() ? TEXT("Asset") : *Context, *AssetPath);
+
+	FString RegistryObjectPath;
+	FString RegistryClass;
+	if (Found.IsValid())
+	{
+		RegistryObjectPath = Found.GetSoftObjectPath().ToString();
+		RegistryClass = Found.AssetClassPath.GetAssetName().ToString();
+	}
+
+	FString Reason;
+	FString Suggestion;
+	FString Message;
+	if (Found.IsValid() && !RegistryObjectPath.Equals(Forms.ObjectPath, ESearchCase::IgnoreCase))
+	{
+		// The package holds an asset, just not under the name the path form
+		// implies. Naming it is the difference between a dead end and a fix.
+		Reason = TEXT("pathShape");
+		Suggestion = RegistryObjectPath;
+		Message = FString::Printf(
+			TEXT("%s The Asset Registry has '%s' (%s) in package '%s'. Pass that object path."),
+			*Prefix, *RegistryObjectPath, *RegistryClass, *Forms.PackagePath);
+	}
+	else if (Found.IsValid())
+	{
+		Reason = TEXT("loadFailed");
+		Message = FString::Printf(
+			TEXT("%s The Asset Registry lists '%s' (%s), so the asset exists but the package would not open. ")
+			TEXT("It may be corrupt, or reference a class the editor cannot resolve."),
+			*Prefix, *RegistryObjectPath, *RegistryClass);
+	}
+	else if (bPackageOnDisk)
+	{
+		Reason = TEXT("notIndexed");
+		Suggestion = Forms.ObjectPath;
+		Message = FString::Printf(
+			TEXT("%s A package file exists at '%s' but the Asset Registry holds no asset in it, ")
+			TEXT("so it may still be scanning. Tried '%s' and '%s'."),
+			*Prefix, *Forms.PackagePath, *AssetPath, *Forms.ObjectPath);
+	}
+	else
+	{
+		Reason = TEXT("missing");
+		Message = FString::Printf(
+			TEXT("%s No package exists at '%s' and the Asset Registry has no entry for it. ")
+			TEXT("Tried '%s' and '%s'."),
+			*Prefix, *Forms.PackagePath, *AssetPath, *Forms.ObjectPath);
+	}
+
+	TSharedPtr<FJsonObject> Obj = MakeShared<FJsonObject>();
+	Obj->SetBoolField(TEXT("success"), false);
+	Obj->SetStringField(TEXT("error"), Message);
+	Obj->SetStringField(TEXT("assetPath"), AssetPath);
+	Obj->SetStringField(TEXT("packagePath"), Forms.PackagePath);
+	Obj->SetStringField(TEXT("objectPath"), Forms.ObjectPath);
+	Obj->SetBoolField(TEXT("packageExistsOnDisk"), bPackageOnDisk);
+	Obj->SetBoolField(TEXT("registryMatched"), Found.IsValid());
+	Obj->SetStringField(TEXT("reason"), Reason);
+	if (Found.IsValid())
+	{
+		Obj->SetStringField(TEXT("registryObjectPath"), RegistryObjectPath);
+		Obj->SetStringField(TEXT("registryClass"), RegistryClass);
+	}
+	if (!Suggestion.IsEmpty())
+	{
+		Obj->SetStringField(TEXT("suggestedPath"), Suggestion);
+	}
+	return MakeShared<FJsonValueObject>(Obj);
+}
+
+/** Resolve an asset path or hand back the diagnostic error. Returns nullptr
+ *  with OutError set on a miss, so a handler reads as
+ *  `if (!Asset) return OutError;`. */
+inline UObject* MCPRequireAssetObject(
+	const FString& AssetPath,
+	TSharedPtr<FJsonValue>& OutError,
+	const FString& Context = FString())
+{
+	UObject* Asset = MCPLoadAssetObject(AssetPath);
+	if (!Asset)
+	{
+		OutError = MCPAssetNotFoundError(AssetPath, Context);
+	}
+	return Asset;
+}
+
+/** The answer for a path that resolved to something of the wrong type.
+ *  Distinct from a miss on purpose: "not a DataTable" used to be the sentence
+ *  a caller saw when the path resolved to nothing at all. */
+inline TSharedPtr<FJsonValue> MCPAssetWrongTypeError(
+	const FString& AssetPath,
+	const UObject* Found,
+	const TCHAR* ExpectedType)
+{
+	TSharedPtr<FJsonObject> Obj = MakeShared<FJsonObject>();
+	Obj->SetBoolField(TEXT("success"), false);
+	Obj->SetStringField(TEXT("error"), FString::Printf(
+		TEXT("Asset is not a %s: '%s' (found a %s)."),
+		ExpectedType, *AssetPath,
+		Found ? *Found->GetClass()->GetName() : TEXT("null")));
+	Obj->SetStringField(TEXT("assetPath"), AssetPath);
+	Obj->SetStringField(TEXT("expectedClass"), ExpectedType);
+	if (Found)
+	{
+		Obj->SetStringField(TEXT("foundClass"), Found->GetClass()->GetName());
+		Obj->SetStringField(TEXT("objectPath"), Found->GetPathName());
+	}
+	return MakeShared<FJsonValueObject>(Obj);
+}
+
 /** Protected mount guardrail. Engine-shipped content (/Engine/, /Script/,
  *  /Memory/, /Temp/) and Verse runtime classes must never be mutated through
  *  the bridge: UEditorAssetLibrary::DeleteAsset will happily destroy files
@@ -153,18 +431,30 @@ inline bool MCPIsProtectedAssetPath(const FString& Path)
 	FString Normalized = Path;
 	Normalized.TrimStartAndEndInline();
 	if (Normalized.IsEmpty()) return false;
+	Normalized = FPackageName::ExportTextPathToObjectPath(Normalized);
+	Normalized.TrimStartAndEndInline();
 	// Tolerate the surface form, which may arrive without a leading slash.
 	if (!Normalized.StartsWith(TEXT("/"))) Normalized = TEXT("/") + Normalized;
 	const FString Lower = Normalized.ToLower();
-	if (Lower.StartsWith(TEXT("/engine/"))) return true;
-	if (Lower.StartsWith(TEXT("/memory/"))) return true;
-	if (Lower.StartsWith(TEXT("/temp/"))) return true;
+	if (Lower == TEXT("/engine") || Lower.StartsWith(TEXT("/engine/"))) return true;
+	if (Lower == TEXT("/memory") || Lower.StartsWith(TEXT("/memory/"))) return true;
+	if (Lower == TEXT("/temp") || Lower.StartsWith(TEXT("/temp/"))) return true;
 	// Verse runtime objects surface as /Script/CoreUObject.* etc, so /Script/
 	// is rejected wherever it appears, not just as a prefix.
-	if (Lower.Contains(TEXT("/script/"))) return true;
+	if (Lower == TEXT("/script") || Lower.Contains(TEXT("/script/"))) return true;
 	return false;
 }
 
+/** The refusal a protected mount produces. Beside the rule it enforces, so a
+ *  handler cannot pair MCPIsProtectedAssetPath with a message of its own that
+ *  says something slightly different. */
+inline TSharedPtr<FJsonValue> MCPProtectedPathError(const FString& Path)
+{
+	return MCPError(FString::Printf(
+		TEXT("Refusing to mutate protected mount: %s. Engine, /Script/, /Memory/, /Temp/ are read-only via the bridge."),
+		*Path));
+}
+
 /** Emit the standard delete_asset rollback record on a create result. */
 inline void MCPSetDeleteAssetRollback(TSharedPtr<FJsonObject> Result, const FString& AssetPath)
 {
@@ -173,76 +463,236 @@ inline void MCPSetDeleteAssetRollback(TSharedPtr<FJsonObject> Result, const FStr
 	MCPSetRollback(Result, TEXT("delete_asset"), Payload);
 }
 
-/** Find an actor by GetActorLabel(). Returns nullptr on miss. Centralises
- *  the iterator-based lookup that previously lived as a private static in
- *  several handler translation units. */
-inline AActor* FindActorByLabel(UWorld* World, const FString& Label)
+// ── Actor selection ──────────────────────────────────────────────────────────
+//
+// Editor labels are NOT unique. A copy-pasted Blueprint gives every copy the
+// same label, and a label lookup that answers with "the first actor the
+// iterator reached" is a coin flip decided by streaming order. #983 is what
+// that costs: several actors labelled BP_SnappyRoad2, a write aimed at the one
+// the user had selected, and the edit landing on a road at the other end of
+// the map with a success response and nothing to suggest a choice was made.
+//
+// So there is one resolver, and it refuses rather than guesses:
+//
+//   * 'actorPath' is the unambiguous selector and wins whenever it is given.
+//   * A label naming more than one actor is an error listing every candidate
+//     and its actorPath, so the caller can retry precisely.
+//   * There is no "just pick one" override. The precise selector already
+//     exists, so a caller who wants a specific one of the duplicates has a
+//     correct answer, and a caller who wants all of them is asking for a
+//     different, plural action. A flag that picks an arbitrary actor out of a
+//     set the caller could not tell apart is the same silent wrong write with
+//     a name on it.
+//
+// The plural need is served by MCPCollectActorsByToken, which returns every
+// match and is what the ignore-list and reference-list parameters use.
+
+/** How a selector token is allowed to match an actor. */
+enum class EMCPActorMatch : uint8
+{
+	/** Editor label only. */
+	Label,
+	/** Editor label, then the internal UObject name. */
+	LabelOrName,
+	/** Editor label, then internal name, then the full object path. */
+	LabelNameOrPath,
+};
+
+/** The actor in World whose full object path is Path, or nullptr. Paths are
+ *  unique, so there is never a choice to make. Accepts the export-text form
+ *  (Actor'/Game/...') and falls back to a case-insensitive compare, because a
+ *  path that came back from one action and was pasted into another is the
+ *  whole point of having it. */
+inline AActor* MCPFindActorByPath(UWorld* World, const FString& Path)
 {
-	if (!World) return nullptr;
+	if (!World || Path.IsEmpty()) return nullptr;
+	FString Wanted = FPackageName::ExportTextPathToObjectPath(Path);
+	Wanted.TrimStartAndEndInline();
+	if (Wanted.IsEmpty()) return nullptr;
+	AActor* CaseInsensitive = nullptr;
 	for (TActorIterator<AActor> It(World); It; ++It)
 	{
-		if (It->GetActorLabel() == Label) return *It;
+		AActor* A = *It;
+		if (!IsValid(A)) continue;
+		const FString Actual = A->GetPathName();
+		if (Actual.Equals(Wanted, ESearchCase::CaseSensitive)) return A;
+		if (!CaseInsensitive && Actual.Equals(Wanted, ESearchCase::IgnoreCase)) CaseInsensitive = A;
 	}
-	return nullptr;
+	return CaseInsensitive;
 }
 
-/** Find an actor by either editor label or internal UObject name. Used by
- *  PIE / runtime handlers where callers may pass either form. */
-inline AActor* FindActorByLabelOrName(UWorld* World, const FString& LabelOrName)
+/** Every actor the token names under Match, sorted by object path so the order
+ *  is the same on every run rather than whatever the actor iterator happened
+ *  to produce that time.
+ *
+ *  The tiers do not blend: a token that is one actor's label and another
+ *  actor's internal name resolves to the label match alone, because the label
+ *  is what the outliner shows and what a caller types. Name and path answer
+ *  only when the label tier found nothing (#806). */
+inline void MCPCollectActorsByToken(
+	UWorld* World,
+	const FString& Token,
+	EMCPActorMatch Match,
+	TArray<AActor*>& OutMatches)
 {
-	if (!World) return nullptr;
+	OutMatches.Reset();
+	if (!World || Token.IsEmpty()) return;
+
+	TArray<AActor*> ByName;
+	TArray<AActor*> ByPath;
 	for (TActorIterator<AActor> It(World); It; ++It)
 	{
-		if (It->GetActorLabel() == LabelOrName || It->GetName() == LabelOrName) return *It;
+		AActor* A = *It;
+		if (!IsValid(A)) continue;
+		if (A->GetActorLabel() == Token) { OutMatches.Add(A); continue; }
+		if (Match != EMCPActorMatch::Label && A->GetName() == Token) { ByName.Add(A); continue; }
+		if (Match == EMCPActorMatch::LabelNameOrPath && A->GetPathName() == Token) { ByPath.Add(A); }
 	}
-	return nullptr;
+	if (OutMatches.Num() == 0) OutMatches = MoveTemp(ByName);
+	if (OutMatches.Num() == 0) OutMatches = MoveTemp(ByPath);
+
+	OutMatches.Sort([](const AActor& A, const AActor& B)
+	{
+		return A.GetPathName().Compare(B.GetPathName()) < 0;
+	});
 }
 
-/** Find an actor by either editor label or full object path. Used by
- *  get_actor_details / get_component_tree which accept either form. */
-inline AActor* FindActorByLabelOrPath(UWorld* World, const FString& Label, const FString& Path)
+/** Which tier of MCPCollectActorsByToken produced a match, for the message. */
+inline const TCHAR* MCPDescribeActorMatchTier(const FString& Token, AActor* Match)
 {
-	if (!World) return nullptr;
-	const bool bHasLabel = !Label.IsEmpty();
-	const bool bHasPath = !Path.IsEmpty();
-	if (!bHasLabel && !bHasPath) return nullptr;
-	for (TActorIterator<AActor> It(World); It; ++It)
+	if (Match && Match->GetActorLabel() == Token) return TEXT("editor label");
+	if (Match && Match->GetName() == Token) return TEXT("internal object name");
+	return TEXT("object path");
+}
+
+/** One candidate row in an ambiguity refusal: enough to tell two same-labelled
+ *  actors apart without a follow-up call, plus the actorPath to retry with. */
+inline TSharedPtr<FJsonObject> MCPDescribeActorCandidate(AActor* Actor)
+{
+	TSharedPtr<FJsonObject> Row = MakeShared<FJsonObject>();
+	if (!Actor) return Row;
+	Row->SetStringField(TEXT("actorPath"), Actor->GetPathName());
+	Row->SetStringField(TEXT("actorLabel"), Actor->GetActorLabel());
+	Row->SetStringField(TEXT("actorName"), Actor->GetName());
+	Row->SetStringField(TEXT("actorClass"), Actor->GetClass()->GetName());
+	Row->SetStringField(TEXT("folderPath"), Actor->GetFolderPath().ToString());
+	const FVector Loc = Actor->GetActorLocation();
+	TSharedPtr<FJsonObject> LocObj = MakeShared<FJsonObject>();
+	LocObj->SetNumberField(TEXT("x"), Loc.X);
+	LocObj->SetNumberField(TEXT("y"), Loc.Y);
+	LocObj->SetNumberField(TEXT("z"), Loc.Z);
+	Row->SetObjectField(TEXT("location"), LocObj);
+	return Row;
+}
+
+/** The refusal an ambiguous selector produces. Lists every candidate and its
+ *  actorPath, so the retry is a copy of one field rather than a hunt back
+ *  through get_outliner. */
+inline TSharedPtr<FJsonValue> MCPAmbiguousActorError(
+	const FString& Token,
+	const TCHAR* LabelKey,
+	const TCHAR* PathKey,
+	const TCHAR* MatchedBy,
+	const TArray<AActor*>& Candidates)
+{
+	const int32 Cap = 25;
+	TSharedPtr<FJsonObject> Obj = MakeShared<FJsonObject>();
+	Obj->SetBoolField(TEXT("success"), false);
+	Obj->SetStringField(TEXT("error"), FString::Printf(
+		TEXT("Ambiguous actor selector: '%s' is the %s of %d actors. Editor labels are not unique, so this call refuses rather than picking one of them. Retry with '%s' set to one of the candidate paths below."),
+		*Token, MatchedBy, Candidates.Num(), PathKey));
+	Obj->SetBoolField(TEXT("ambiguous"), true);
+	Obj->SetStringField(TEXT("selector"), LabelKey);
+	Obj->SetStringField(TEXT("selectorValue"), Token);
+	Obj->SetStringField(TEXT("matchedBy"), MatchedBy);
+	Obj->SetNumberField(TEXT("matchCount"), Candidates.Num());
+	TArray<TSharedPtr<FJsonValue>> Rows;
+	for (int32 Index = 0; Index < Candidates.Num() && Index < Cap; ++Index)
 	{
-		if (bHasPath && It->GetPathName() == Path) return *It;
-		if (bHasLabel && It->GetActorLabel() == Label) return *It;
+		Rows.Add(MakeShared<FJsonValueObject>(MCPDescribeActorCandidate(Candidates[Index])));
 	}
-	return nullptr;
+	Obj->SetArrayField(TEXT("candidates"), Rows);
+	if (Candidates.Num() > Cap) Obj->SetBoolField(TEXT("candidatesTruncated"), true);
+	return MakeShared<FJsonValueObject>(Obj);
 }
 
-/** Three-way actor lookup against the placed instances in a world: label
- *  first, then internal object name, then full path. Used by
- *  EditorHandlers_PIE invoke_function which accepts any of the three.
- *
- *  #806: the priority is fixed rather than "first actor that matches any of
- *  the three", because a token can be one actor's label and another actor's
- *  internal name at the same time, and which one won then depended on level
- *  iteration order. The label is what the outliner shows and what callers
- *  pass, so it decides outright; name and path only resolve the misses. */
-inline AActor* FindActorByLabelNameOrPath(UWorld* World, const FString& Token)
+/** True when a resolver failure was a refusal to choose rather than a miss.
+ *  An action that treats an absent actor as a no-op still has to fail on an
+ *  ambiguous one: "already deleted" is the wrong answer when three actors
+ *  carry the label and none of them was touched. */
+inline bool MCPIsAmbiguousActorError(const TSharedPtr<FJsonValue>& Error)
 {
-	if (!World || Token.IsEmpty()) return nullptr;
-	AActor* NameMatch = nullptr;
-	AActor* PathMatch = nullptr;
-	for (TActorIterator<AActor> It(World); It; ++It)
+	if (!Error.IsValid() || Error->Type != EJson::Object) return false;
+	const TSharedPtr<FJsonObject> Obj = Error->AsObject();
+	bool bAmbiguous = false;
+	return Obj.IsValid() && Obj->TryGetBoolField(TEXT("ambiguous"), bAmbiguous) && bAmbiguous;
+}
+
+// FindActorByLabel, FindActorByLabelOrName, FindActorByLabelOrPath and
+// FindActorByLabelNameOrPath each answered a duplicate label with the first
+// match the actor iterator produced, which is the silent wrong write #983
+// reported, and four spellings of one search is how the rules drift apart.
+// Nothing in THIS plugin calls them any more: core goes through
+// MCPResolveActor, or MCPCollectActorsByToken where the plural answer is the
+// correct one.
+//
+// They survive as compatibility shims because this is a PUBLIC header shipped
+// to plugin authors, and deleting them outright is a breaking change for every
+// plugin built against it. PIE_Studio calls FindActorByLabelOrName today and
+// broke the moment they went; a third-party plugin nobody here can see would
+// have broken the same way, and only after publishing.
+//
+// They now share the consolidated search, so they cannot drift from it, and
+// they keep first-match semantics because that is the contract callers already
+// have. New code should use MCPResolveActor, which refuses an ambiguous label
+// rather than picking one.
+
+/** Legacy: first actor whose editor label matches. Prefer MCPResolveActor. */
+inline AActor* FindActorByLabel(UWorld* World, const FString& Label)
+{
+	TArray<AActor*> Matches;
+	MCPCollectActorsByToken(World, Label, EMCPActorMatch::Label, Matches);
+	return Matches.Num() > 0 ? Matches[0] : nullptr;
+}
+
+/** Legacy: first actor matching an editor label or internal name.
+ *  Prefer MCPResolveActor. */
+inline AActor* FindActorByLabelOrName(UWorld* World, const FString& LabelOrName)
+{
+	TArray<AActor*> Matches;
+	MCPCollectActorsByToken(World, LabelOrName, EMCPActorMatch::LabelOrName, Matches);
+	return Matches.Num() > 0 ? Matches[0] : nullptr;
+}
+
+/** Legacy: an actor by label, or by full object path when the label is empty.
+ *  Prefer MCPResolveActor. */
+inline AActor* FindActorByLabelOrPath(UWorld* World, const FString& Label, const FString& Path)
+{
+	if (!Path.IsEmpty())
 	{
-		AActor* A = *It;
-		if (!IsValid(A)) continue;
-		if (A->GetActorLabel() == Token) return A;
-		if (!NameMatch && A->GetName() == Token) NameMatch = A;
-		if (!PathMatch && A->GetPathName() == Token) PathMatch = A;
+		if (AActor* ByPath = MCPFindActorByPath(World, Path)) return ByPath;
 	}
-	return NameMatch ? NameMatch : PathMatch;
+	if (Label.IsEmpty()) return nullptr;
+	return FindActorByLabel(World, Label);
+}
+
+/** Legacy: first actor matching a label, internal name or object path.
+ *  Prefer MCPResolveActor. */
+inline AActor* FindActorByLabelNameOrPath(UWorld* World, const FString& Token)
+{
+	TArray<AActor*> Matches;
+	MCPCollectActorsByToken(World, Token, EMCPActorMatch::LabelNameOrPath, Matches);
+	return Matches.Num() > 0 ? Matches[0] : nullptr;
 }
 
 /** Build the "no such actor" message for a failed label/name/path lookup.
  *  Names what was searched and offers the labels that contain the token, so a
  *  caller that guessed a label sees the real one instead of a bare miss. */
-inline FString MCPDescribeActorLookupMiss(UWorld* World, const FString& Token, const FString& WorldLabel)
+inline FString MCPDescribeActorLookupMiss(
+	UWorld* World,
+	const FString& Token,
+	const FString& WorldLabel,
+	EMCPActorMatch Match = EMCPActorMatch::LabelNameOrPath)
 {
 	int32 ActorCount = 0;
 	TArray<FString> Near;
@@ -259,9 +709,16 @@ inline FString MCPDescribeActorLookupMiss(UWorld* World, const FString& Token, c
 			}
 		}
 	}
+	// Name what was actually searched. Claiming a name and path sweep that a
+	// label-only action never ran sends a caller looking for a typo in the
+	// wrong field.
+	const TCHAR* Searched =
+		Match == EMCPActorMatch::Label ? TEXT("by editor label")
+		: Match == EMCPActorMatch::LabelOrName ? TEXT("by editor label, then by internal object name")
+		: TEXT("by editor label, then by internal object name, then by full object path");
 	FString Msg = FString::Printf(
-		TEXT("Actor '%s' not found in the %s world. Searched every placed actor by editor label, then by internal object name, then by full object path (%d actors)."),
-		*Token, *WorldLabel, ActorCount);
+		TEXT("Actor '%s' not found in the %s world. Searched every placed actor %s (%d actors). Pass actorPath for an exact object path when a label is ambiguous or absent."),
+		*Token, *WorldLabel, Searched, ActorCount);
 	if (Near.Num() > 0)
 	{
 		Msg += FString::Printf(TEXT(" Labels containing that text: [%s]."), *FString::Join(Near, TEXT(", ")));
@@ -270,12 +727,138 @@ inline FString MCPDescribeActorLookupMiss(UWorld* World, const FString& Token, c
 	return Msg;
 }
 
+/** Which parameters carry the actor selector for one action, and how far the
+ *  label token is allowed to reach.
+ *
+ *  Handlers that name their actor something other than 'actorLabel' pass the
+ *  pair explicitly. The convention is that the path key is the label key with
+ *  its "Label" suffix swapped for "Path" (childLabel / childPath), so a caller
+ *  can guess it correctly. */
+struct FMCPActorSelector
+{
+	/** Parameter carrying the editor label (or the label/name/path token). */
+	const TCHAR* LabelKey = TEXT("actorLabel");
+	/** Parameter carrying the unambiguous full object path. */
+	const TCHAR* PathKey = TEXT("actorPath");
+	/** A second spelling of the label parameter, for actions that shipped
+	 *  with two (get_relative_transform takes 'target' or 'targetLabel').
+	 *  Read only when LabelKey is absent. */
+	const TCHAR* AltLabelKey = nullptr;
+	/** How far LabelKey's value is allowed to reach. */
+	EMCPActorMatch Match = EMCPActorMatch::Label;
+	/** When false, an absent selector is not an error: the resolver returns
+	 *  nullptr with OutError left unset and the caller decides what that
+	 *  means (an optional target, or a second selection route). */
+	bool bRequired = true;
+	/** Names the world in the miss message: "editor", "PIE". */
+	const TCHAR* WorldLabel = TEXT("editor");
+};
+
+/** Resolve one actor from an already-extracted token. Returns nullptr and
+ *  writes OutError on a miss or on ambiguity; the caller returns OutError
+ *  unchanged. Used where the token did not come from a parameter of its own
+ *  (a list entry, a fixed label). */
+inline AActor* MCPResolveActorToken(
+	UWorld* World,
+	const FString& Token,
+	TSharedPtr<FJsonValue>& OutError,
+	const FMCPActorSelector& Selector = FMCPActorSelector())
+{
+	OutError.Reset();
+	if (!World)
+	{
+		OutError = MCPError(TEXT("Editor world not available"));
+		return nullptr;
+	}
+	TArray<AActor*> Matches;
+	MCPCollectActorsByToken(World, Token, Selector.Match, Matches);
+	if (Matches.Num() == 1) return Matches[0];
+	if (Matches.Num() > 1)
+	{
+		OutError = MCPAmbiguousActorError(
+			Token, Selector.LabelKey, Selector.PathKey,
+			MCPDescribeActorMatchTier(Token, Matches[0]), Matches);
+		return nullptr;
+	}
+	OutError = MCPError(MCPDescribeActorLookupMiss(World, Token, Selector.WorldLabel, Selector.Match));
+	return nullptr;
+}
+
+/** THE actor resolver. Reads the unambiguous path selector first, then the
+ *  label, and refuses when the label names more than one actor.
+ *
+ *  A path that names nothing is an error rather than a quiet fall-through to
+ *  the label: the path is the precise selector, and demoting a precise miss to
+ *  a fuzzy hit is how the wrong actor gets edited in the first place.
+ *
+ *  Returns nullptr on every failure with OutError carrying the response to
+ *  return. When Selector.bRequired is false and neither key was supplied,
+ *  returns nullptr with OutError unset. */
+inline AActor* MCPResolveActor(
+	UWorld* World,
+	const TSharedPtr<FJsonObject>& Params,
+	TSharedPtr<FJsonValue>& OutError,
+	const FMCPActorSelector& Selector = FMCPActorSelector())
+{
+	OutError.Reset();
+
+	FString Path;
+	FString Token;
+	if (Params.IsValid())
+	{
+		Params->TryGetStringField(Selector.PathKey, Path);
+		Params->TryGetStringField(Selector.LabelKey, Token);
+		if (Token.IsEmpty() && Selector.AltLabelKey)
+		{
+			Params->TryGetStringField(Selector.AltLabelKey, Token);
+		}
+	}
+	Path.TrimStartAndEndInline();
+	Token.TrimStartAndEndInline();
+
+	if (Path.IsEmpty() && Token.IsEmpty())
+	{
+		if (Selector.bRequired)
+		{
+			OutError = MCPError(FString::Printf(
+				TEXT("Missing required parameter '%s' (or '%s'). Editor labels are not unique, so '%s' is the selector to prefer when you have one."),
+				Selector.LabelKey, Selector.PathKey, Selector.PathKey));
+		}
+		return nullptr;
+	}
+
+	if (!World)
+	{
+		OutError = MCPError(TEXT("Editor world not available"));
+		return nullptr;
+	}
+
+	if (!Path.IsEmpty())
+	{
+		if (AActor* ByPath = MCPFindActorByPath(World, Path)) return ByPath;
+		OutError = MCPError(FString::Printf(
+			TEXT("No actor at '%s' in the %s world. Object paths look like /Game/Maps/Map.Map:PersistentLevel.Actor_0; level(get_outliner) reports the real one for every actor."),
+			*Path, Selector.WorldLabel));
+		return nullptr;
+	}
+
+	return MCPResolveActorToken(World, Token, OutError, Selector);
+}
+
 /** Spawn-by-label idempotency check. If World already has an actor with the
  *  given Label, returns a fully-formed "already existed" result the caller
  *  can return directly (or an MCPError when OnConflict == "error"). When
  *  Label is empty or no match exists, returns an unset shared pointer so the
  *  caller proceeds to spawn. Mirrors MCPCheckAssetExists's contract for
- *  in-world actors. */
+ *  in-world actors.
+ *
+ *  #983: this asks "does this label already name something", so several
+ *  matches is an answer rather than a refusal, and refusing here would break
+ *  a rerun of a spawn that is meant to be idempotent. But it hands back an
+ *  actorPath the caller may then write to, so it must not be an arbitrary
+ *  one: the search is the shared, path-sorted one, and when the label names
+ *  several actors the result says so and lists them all instead of presenting
+ *  one as though it were the only. */
 inline TSharedPtr<FJsonValue> MCPCheckActorLabelExists(
 	UWorld* World,
 	const FString& Label,
@@ -283,22 +866,37 @@ inline TSharedPtr<FJsonValue> MCPCheckActorLabelExists(
 	const FString& FriendlyType = TEXT("Actor"))
 {
 	if (!World || Label.IsEmpty()) return TSharedPtr<FJsonValue>();
-	for (TActorIterator<AActor> It(World); It; ++It)
+	TArray<AActor*> Matches;
+	MCPCollectActorsByToken(World, Label, EMCPActorMatch::Label, Matches);
+	if (Matches.Num() == 0) return TSharedPtr<FJsonValue>();
+
+	if (OnConflict == TEXT("error"))
+	{
+		return MCPError(FString::Printf(TEXT("%s '%s' already exists"), *FriendlyType, *Label));
+	}
+
+	auto Existing = MCPSuccess();
+	MCPSetExisted(Existing);
+	Existing->SetStringField(TEXT("actorLabel"), Label);
+	Existing->SetStringField(TEXT("actorPath"), Matches[0]->GetPathName());
+	Existing->SetNumberField(TEXT("existingCount"), Matches.Num());
+	if (Matches.Num() > 1)
 	{
-		if (It->GetActorLabel() == Label)
+		// Deliberately NOT the 'ambiguous' key: that one marks a refusal, and
+		// this is a success. A consumer branching on 'ambiguous' must not read
+		// an idempotent no-op as a call that did nothing because it refused.
+		Existing->SetBoolField(TEXT("labelIsAmbiguous"), true);
+		TArray<TSharedPtr<FJsonValue>> Rows;
+		for (AActor* Match : Matches)
 		{
-			if (OnConflict == TEXT("error"))
-			{
-				return MCPError(FString::Printf(TEXT("%s '%s' already exists"), *FriendlyType, *Label));
-			}
-			auto Existing = MCPSuccess();
-			MCPSetExisted(Existing);
-			Existing->SetStringField(TEXT("actorLabel"), Label);
-			Existing->SetStringField(TEXT("actorPath"), It->GetPathName());
-			return MCPResult(Existing);
+			Rows.Add(MakeShared<FJsonValueObject>(MCPDescribeActorCandidate(Match)));
 		}
+		Existing->SetArrayField(TEXT("candidates"), Rows);
+		Existing->SetStringField(TEXT("note"), FString::Printf(
+			TEXT("%d actors already carry the label '%s'. actorPath names the first by object path; address any of them with the actorPath from candidates."),
+			Matches.Num(), *Label));
 	}
-	return TSharedPtr<FJsonValue>();
+	return MCPResult(Existing);
 }
 
 /** Load a Blueprint by path and return its CDO cast to T. Returns nullptr
@@ -400,6 +998,101 @@ inline bool OptionalBool(
 	return Params->TryGetBoolField(Key, Value) ? Value : DefaultValue;
 }
 
+/**
+ * Why an actor filter matched nothing, in terms of what it WOULD have matched.
+ *
+ * Level actions do not agree on filter semantics and their parameter names do
+ * not warn you: get_outliner's nameFilter is a case-insensitive substring over
+ * the label OR the internal name, while delete_actors' labelPrefix is a
+ * case-sensitive prefix over the label only. The same string selects different
+ * sets, and the losing call returns success with matched:0, which a caller
+ * reasonably reads as "nothing to do".
+ *
+ * So a zero match reports the counts under the OTHER semantics rather than
+ * leaving the caller to discover them. Returns an unset pointer when the
+ * string would have matched nothing under any of them, because then a zero
+ * really does mean zero.
+ */
+inline TSharedPtr<FJsonObject> MCPDescribeZeroActorMatch(UWorld* World, const FString& Needle)
+{
+	if (!World || Needle.IsEmpty())
+	{
+		return nullptr;
+	}
+
+	int32 LabelContains = 0;
+	int32 NameContains = 0;
+	int32 PrefixIgnoringCase = 0;
+	TArray<TSharedPtr<FJsonValue>> Samples;
+
+	for (TActorIterator<AActor> It(World); It; ++It)
+	{
+		AActor* Actor = *It;
+		if (!Actor) continue;
+		const FString Label = Actor->GetActorLabel();
+		const FString Name = Actor->GetName();
+		const bool bLabelContains = Label.Contains(Needle, ESearchCase::IgnoreCase);
+		const bool bNameContains = Name.Contains(Needle, ESearchCase::IgnoreCase);
+		const bool bPrefix = Label.StartsWith(Needle, ESearchCase::IgnoreCase);
+		if (bLabelContains) ++LabelContains;
+		if (bNameContains) ++NameContains;
+		if (bPrefix) ++PrefixIgnoringCase;
+		if ((bLabelContains || bNameContains) && Samples.Num() < 5)
+		{
+			Samples.Add(MakeShared<FJsonValueString>(
+				FString::Printf(TEXT("%s (internal name %s)"), *Label, *Name)));
+		}
+	}
+
+	if (LabelContains == 0 && NameContains == 0 && PrefixIgnoringCase == 0)
+	{
+		return nullptr;
+	}
+
+	TSharedPtr<FJsonObject> Hint = MakeShared<FJsonObject>();
+	Hint->SetStringField(TEXT("filter"), Needle);
+	Hint->SetNumberField(TEXT("actorsWhoseLabelContainsIt"), LabelContains);
+	Hint->SetNumberField(TEXT("actorsWhoseInternalNameContainsIt"), NameContains);
+	Hint->SetNumberField(TEXT("actorsWhoseLabelStartsWithItIgnoringCase"), PrefixIgnoringCase);
+	Hint->SetArrayField(TEXT("samples"), Samples);
+	Hint->SetStringField(TEXT("note"),
+		TEXT("labelPrefix is a case-sensitive PREFIX over the EDITOR LABEL. level(get_outliner)'s nameFilter is a case-insensitive SUBSTRING over the label OR the internal name, so the same string selects a different set there. Use labelContains for a substring over the label, or nameContains for one over the internal name."));
+	return Hint;
+}
+
+/**
+ * Note that an actor enumeration only saw the actors that are loaded.
+ *
+ * Every actor query in this plugin iterates the world, and on a World
+ * Partition map that is a real answer but not the whole answer. Saying so
+ * turns a silently wrong zero into an actionable one.
+ */
+inline void MCPNoteLoadedOnlyEnumeration(UWorld* World, TSharedPtr<FJsonObject> Result)
+{
+	if (!World || !Result.IsValid() || !World->IsPartitionedWorld())
+	{
+		return;
+	}
+	Result->SetBoolField(TEXT("partitionedWorld"), true);
+	Result->SetStringField(TEXT("enumerationNote"),
+		TEXT("This is a World Partition map and only LOADED actors were enumerated. An actor whose cell is not streamed in is invisible to every world query, including this one. Use level(list_actor_descs) to see the unloaded ones and level(load_actor_descs) to pin them first."));
+}
+
+/** Render a TArray<FString> as a JSON string array. The inverse of
+ *  JsonArrayToStringList, shared so batch handlers that report label lists do
+ *  not each define their own file-local copy (unity build: two anonymous
+ *  namespaces sharing a blob merge, and the second definition is C2084). */
+inline TArray<TSharedPtr<FJsonValue>> MCPStringListToJson(const TArray<FString>& Values)
+{
+	TArray<TSharedPtr<FJsonValue>> Out;
+	Out.Reserve(Values.Num());
+	for (const FString& Value : Values)
+	{
+		Out.Add(MakeShared<FJsonValueString>(Value));
+	}
+	return Out;
+}
+
 /** Extract a JSON array of strings into a TArray<FString>. */
 inline TArray<FString> JsonArrayToStringList(const TArray<TSharedPtr<FJsonValue>>* Arr)
 {
@@ -1026,46 +1719,284 @@ inline UWorld* ResolveWorldFromParams(const TSharedPtr<FJsonObject>& Params, con
 	UWorld* WorldVar = GetEditorWorld(); \
 	if (!WorldVar) return MCPError(TEXT("Editor world not available"));
 
-/** Load an asset by path with fallback to ObjectPath format.  Returns nullptr if not found. */
+/** Load an asset of a known type by path. Returns nullptr when the path names
+ *  nothing, and also when it names something of another type.
+ *
+ *  #957/#913: this used to run its own two-step resolution, one step short of
+ *  the one asset(read) uses, so a short package path for an asset that was not
+ *  loaded yet answered nullptr here and resolved fine there. It now defers to
+ *  MCPLoadAssetObject so there is exactly one answer to "what does this path
+ *  name" in the whole plugin. */
 template <typename T>
 T* LoadAssetByPath(const FString& AssetPath)
 {
-	T* Asset = LoadObject<T>(nullptr, *AssetPath);
-	if (Asset) return Asset;
+	return Cast<T>(MCPLoadAssetObject(AssetPath));
+}
 
-	// Try ObjectPath format: "/Game/Foo/Bar" → "/Game/Foo/Bar.Bar"
-	if (!AssetPath.Contains(TEXT(".")))
+/** The answer for a typed load that came back empty: names the class that was
+ *  found when the path resolved to the wrong thing, and falls through to the
+ *  full path diagnostic when it resolved to nothing. */
+inline TSharedPtr<FJsonValue> MCPAssetLoadError(const FString& AssetPath, const TCHAR* ExpectedType)
+{
+	if (UObject* Found = MCPLoadAssetObject(AssetPath))
 	{
-		FString AssetName;
-		AssetPath.Split(TEXT("/"), nullptr, &AssetName, ESearchCase::CaseSensitive, ESearchDir::FromEnd);
-		Asset = LoadObject<T>(nullptr, *(AssetPath + TEXT(".") + AssetName));
+		return MCPAssetWrongTypeError(AssetPath, Found, ExpectedType);
 	}
-	return Asset;
+	return MCPAssetNotFoundError(AssetPath);
 }
 
 /** Load an asset or return an error response.  Assigns to OutVar. */
 #define REQUIRE_ASSET(Type, OutVar, AssetPath) \
 	Type* OutVar = LoadAssetByPath<Type>(AssetPath); \
-	if (!OutVar) return MCPError(FString::Printf(TEXT("%s not found: %s"), TEXT(#Type), *AssetPath));
+	if (!OutVar) return MCPAssetLoadError(AssetPath, TEXT(#Type));
+
+/** Export a property's value as text, honouring C-style fixed arrays.
+ *
+ *  A UPROPERTY declared as `int32 Foo[3]` is ONE FProperty with ArrayDim == 3,
+ *  not three properties. ExportTextItem_Direct exports a single element, so a
+ *  caller that passes ContainerPtrToValuePtr<void>(Container) with no index
+ *  gets element 0 and nothing else, and the value reads as a plain scalar.
+ *
+ *  That is how #927 hid two thirds of RecastNavMesh's NavMeshResolutionParams:
+ *  the Low tier was reported as if it were the whole property while the engine
+ *  was generating from Default and High, so a navmesh diagnosis was performed
+ *  against numbers the engine was not using.
+ *
+ *  Returns a JSON string for a normal property, and a JSON array of one string
+ *  per element for a fixed array, so a caller can tell the two apart. */
+inline TSharedPtr<FJsonValue> MCPExportPropertyValue(const FProperty* Prop, const void* Container)
+{
+	if (!Prop || !Container) return MakeShared<FJsonValueString>(FString());
+
+	auto ExportOne = [Prop, Container](int32 Index) -> FString
+	{
+		FString Text;
+		Prop->ExportTextItem_Direct(
+			Text, Prop->ContainerPtrToValuePtr<void>(Container, Index), nullptr, nullptr, PPF_None);
+		return Text;
+	};
+
+	if (Prop->ArrayDim <= 1)
+	{
+		return MakeShared<FJsonValueString>(ExportOne(0));
+	}
+
+	TArray<TSharedPtr<FJsonValue>> Elements;
+	Elements.Reserve(Prop->ArrayDim);
+	for (int32 Index = 0; Index < Prop->ArrayDim; ++Index)
+	{
+		Elements.Add(MakeShared<FJsonValueString>(ExportOne(Index)));
+	}
+	return MakeShared<FJsonValueArray>(Elements);
+}
+
+/** True when a property is a C-style fixed array, so callers that must emit a
+ *  scalar can say the value was truncated rather than silently truncating. */
+inline bool MCPPropertyIsFixedArray(const FProperty* Prop)
+{
+	return Prop != nullptr && Prop->ArrayDim > 1;
+}
 
 // ── Package save ─────────────────────────────────────────────────────────────
 
+/** True when the package is a map package, i.e. one whose on-disk form is a
+ *  ".umap" rather than a ".uasset".
+ *
+ *  #949: writing a world package with the asset extension does not fail. It
+ *  creates a second file that claims the same long package name, so the level
+ *  then exists twice on disk and the two copies diverge silently as different
+ *  save paths write different files. Unreal resolves the ".uasset" first, so
+ *  the stale fork is the one that wins.
+ *
+ *  ContainsMap is the package flag Unreal sets on world packages and is the
+ *  same test editor(save_dirty) branches on. FindWorldInPackage is the backstop
+ *  for a world built in memory whose flag has not been stamped yet. One-file-
+ *  per-actor packages under __ExternalActors__ hold an AActor and no UWorld, so
+ *  both tests say false and they keep the ".uasset" extension OFPA expects. */
+inline bool IsMapPackage(UPackage* Package)
+{
+	if (!Package) return false;
+	return Package->ContainsMap() || UWorld::FindWorldInPackage(Package) != nullptr;
+}
+
+/** On-disk file extension for a package, dot included. ".umap" for world
+ *  packages, ".uasset" for everything else. */
+inline const FString& PackageFileExtension(UPackage* Package)
+{
+	return IsMapPackage(Package)
+		? FPackageName::GetMapPackageExtension()
+		: FPackageName::GetAssetPackageExtension();
+}
+
+/** Resolve the on-disk filename a package must be written to, extension
+ *  included. Returns false when the package name has no mounted root, which
+ *  keeps callers off FPackageName::LongPackageNameToFilename - that one is
+ *  fatal rather than recoverable when the name does not resolve. */
+inline bool ResolvePackageFileName(UPackage* Package, FString& OutFileName)
+{
+	if (!Package) return false;
+	return FPackageName::TryConvertLongPackageNameToFilename(
+		Package->GetName(), OutFileName, PackageFileExtension(Package));
+}
+
+/** Why an asset's package cannot be written, answered BEFORE the save is
+ *  attempted. Returns true when the write is blocked, with OutReason carrying
+ *  the sentence to hand the caller.
+ *
+ *  #932: blueprint(reparent) saved as part of the operation, and a read-only
+ *  .uasset (a file never checked out of source control) turned the failed save
+ *  into a FATAL engine error that took the whole editor process down. The asset
+ *  was undamaged and the call replayed cleanly after a checkout, but no handler
+ *  may answer a routine, foreseeable condition with a crash.
+ *
+ *  Asking the file system first is what turns that into an ordinary failure,
+ *  and it is the same order asset(set_property) already uses (#931). It lives
+ *  here, as one function, because "can this package be written" has to have a
+ *  single answer: the protected-mount guardrail had four copies once and two of
+ *  them enforced a weaker rule than the others. */
+inline bool MCPPackageWriteBlocked(UObject* Asset, FString& OutReason)
+{
+	OutReason.Reset();
+
+	UPackage* Package = Asset ? Asset->GetOutermost() : nullptr;
+	if (!Package)
+	{
+		OutReason = TEXT("The asset has no package, so there is nothing to write.");
+		return true;
+	}
+
+	const FString PackageName = Package->GetName();
+	if (MCPIsProtectedAssetPath(PackageName))
+	{
+		OutReason = FString::Printf(
+			TEXT("'%s' is on a protected mount, which the bridge never writes to."),
+			*PackageName);
+		return true;
+	}
+
+	FString PackageFileName;
+	if (!ResolvePackageFileName(Package, PackageFileName))
+	{
+		OutReason = FString::Printf(
+			TEXT("'%s' has no mounted content root, so there is no file to write it to."),
+			*PackageName);
+		return true;
+	}
+
+	// Only a file that already exists can be read-only. A package saved for the
+	// first time has nothing on disk to check, and asking about a missing file
+	// answers "not read-only", which is the right answer for a create.
+	if (IFileManager::Get().FileExists(*PackageFileName)
+		&& IFileManager::Get().IsReadOnly(*PackageFileName))
+	{
+		OutReason = FString::Printf(
+			TEXT("'%s' is read-only on disk. Check it out of source control or clear the read-only flag, then retry."),
+			*PackageFileName);
+		return true;
+	}
+
+	return false;
+}
+
 /** Mark the asset's package dirty and save it to disk. Used by every create/
  *  mutate handler that wants changes persisted across editor restarts.
- *  No-op if Asset or its package is null. Returns true on successful save. */
+ *  No-op if Asset or its package is null. Returns true on successful save.
+ *
+ *  Refuses before the engine is asked to write a file it cannot open (#932),
+ *  so the worst outcome of a read-only or protected package is a false return
+ *  rather than a fatal error. Callers that want the sentence explaining the
+ *  false use SaveAssetPackageChecked. */
 inline bool SaveAssetPackage(UObject* Asset)
 {
 	if (!Asset) return false;
 	UPackage* Package = Asset->GetOutermost();
 	if (!Package) return false;
 	Package->MarkPackageDirty();
-	const FString PackageFileName = FPackageName::LongPackageNameToFilename(
-		Package->GetName(), FPackageName::GetAssetPackageExtension());
+
+	FString BlockedReason;
+	if (MCPPackageWriteBlocked(Asset, BlockedReason)) return false;
+
+	// The extension has to follow the package, not the call site. Any handler
+	// that mutates an actor or component in the open level reaches this with a
+	// world package as the outermost (#949).
+	FString PackageFileName;
+	if (!ResolvePackageFileName(Package, PackageFileName)) return false;
 	FSavePackageArgs SaveArgs;
 	SaveArgs.TopLevelFlags = RF_Standalone;
 	return UPackage::SavePackage(Package, nullptr, *PackageFileName, SaveArgs);
 }
 
+/** SaveAssetPackage, with the reason when it did not write. A handler that
+ *  reports its own persistence uses this so a refusal reads as a named cause
+ *  rather than a bare false. */
+inline bool SaveAssetPackageChecked(UObject* Asset, FString& OutReason)
+{
+	if (MCPPackageWriteBlocked(Asset, OutReason)) return false;
+	if (SaveAssetPackage(Asset)) return true;
+
+	UPackage* Package = Asset ? Asset->GetOutermost() : nullptr;
+	OutReason = FString::Printf(
+		TEXT("The editor refused to write '%s'. The output log carries the reason."),
+		Package ? *Package->GetName() : TEXT("(no package)"));
+	return false;
+}
+
+/** The refusal an action that saves as a side effect returns when the package
+ *  cannot be written. Returns nullptr when the write may go ahead, so a handler
+ *  reads as `if (auto Blocked = MCPAssetWriteBlockedError(...)) return Blocked;`
+ *  placed BEFORE the first mutation.
+ *
+ *  Operation names what the caller asked for, in the imperative, so the message
+ *  reads "Cannot reparent this Blueprint: ...". */
+inline TSharedPtr<FJsonValue> MCPAssetWriteBlockedError(
+	UObject* Asset,
+	const FString& AssetPath,
+	const TCHAR* Operation)
+{
+	FString Reason;
+	if (!MCPPackageWriteBlocked(Asset, Reason)) return nullptr;
+
+	TSharedPtr<FJsonObject> Obj = MakeShared<FJsonObject>();
+	Obj->SetBoolField(TEXT("success"), false);
+	Obj->SetStringField(TEXT("error"), FString::Printf(
+		TEXT("Cannot %s: %s Nothing was changed."), Operation, *Reason));
+	Obj->SetStringField(TEXT("assetPath"), AssetPath);
+	Obj->SetStringField(TEXT("path"), AssetPath);
+	Obj->SetStringField(TEXT("reason"), TEXT("package_not_writable"));
+	Obj->SetBoolField(TEXT("saved"), false);
+	if (UPackage* Package = Asset ? Asset->GetOutermost() : nullptr)
+	{
+		Obj->SetStringField(TEXT("packageName"), Package->GetName());
+		FString PackageFileName;
+		if (ResolvePackageFileName(Package, PackageFileName))
+		{
+			Obj->SetStringField(TEXT("packageFile"), PackageFileName);
+		}
+	}
+	return MakeShared<FJsonValueObject>(Obj);
+}
+
+/** Record on a result whether the side-effect save reached disk, and why not
+ *  when it did not. A save that did not happen is a failure, not a success with
+ *  a footnote: the caller's next read comes off the in-memory object and looks
+ *  correct right up until the editor restarts (#931). */
+inline void MCPNoteSaveOutcome(
+	const TSharedPtr<FJsonObject>& Result,
+	const FString& AssetPath,
+	bool bSaved,
+	const FString& Reason)
+{
+	if (!Result.IsValid()) return;
+	Result->SetBoolField(TEXT("saved"), bSaved);
+	if (bSaved) return;
+
+	Result->SetBoolField(TEXT("success"), false);
+	Result->SetStringField(TEXT("saveError"), Reason);
+	Result->SetStringField(TEXT("error"), FString::Printf(
+		TEXT("The change was applied in memory but '%s' was not written: %s"),
+		*AssetPath, *Reason));
+}
+
 // ── GC root RAII ─────────────────────────────────────────────────────────────
 
 /** RAII: root a UObject on construction, unroot on scope exit. Prevents the