ue-mcp 1.2.4 → 1.3.0

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/UE_MCP_Bridge.Build.cs

@@ -8,8 +8,67 @@ public class UE_MCP_Bridge : ModuleRules
 	// new .cpp until this file changes.
 	// Private/Handlers/AssetHandlers_BulkUpsert.cpp: UBT caches the module's
 	// file list and will not pick up a new .cpp until this file changes.
+	// Private/Handlers/LevelHandlers_Inspection.cpp and its focused test: same reason.
 	// Private/BridgeStateFiles.cpp, Private/BridgeParamEcho.cpp and
 	// Private/Tests/BridgeProtocolTests.cpp: same reason.
+	// Private/Tests/SequencerHandlerTests.cpp: same reason.
+	// Private/Handlers/LevelHandlers_InstanceProjection.cpp and
+	// Private/Tests/LevelInstanceProjectionTests.cpp: same reason.
+	// Private/Tests/PackageSaveExtensionTests.cpp: same reason.
+	// Private/Handlers/AnimationHandlers_ControlRigSequencer.cpp,
+	// Private/Handlers/AnimationHandlers_Validation.cpp,
+	// Private/Handlers/AnimationHandlers_IKRigAuthoring.cpp and
+	// Private/Handlers/AnimationHandlers_IKRetargeterAuthoring.cpp plus
+	// Private/Tests/AnimationControlRigTimelineTests.cpp: same reason.
+	// Private/Tests/DataTableRowWriteTests.cpp: same reason.
+	// Private/Handlers/EditorHandlers_RuntimeVisibility.cpp and
+	// Private/Tests/RuntimeVisibilityTests.cpp: same reason.
+	// Private/Handlers/MaterialHandlers_Build.cpp and
+	// Private/Tests/MaterialBuildTests.cpp: same reason.
+	// Private/Handlers/AssetHandlers_Geometry.cpp,
+	// Private/Handlers/AnimationHandlers_Pose.cpp,
+	// Private/Tests/MeshGeometryTests.cpp and
+	// Private/Tests/AnimationPoseTests.cpp: same reason.
+	// Private/Tests/WidgetBlueprintResolveTests.cpp and
+	// Private/Tests/GasLiveAttributeTests.cpp: same reason.
+	// Private/Tests/BlueprintHandlerSurfaceTests.cpp: same reason.
+	// Private/Handlers/BlueprintHandlers_Search.cpp: same reason.
+	// Private/Handlers/LevelHandlers_Query.cpp,
+	// Private/Handlers/LevelHandlers_BatchWrite.cpp,
+	// Private/Handlers/LevelHandlers_Convert.cpp,
+	// Private/Handlers/LevelHandlers_Refresh.cpp,
+	// Private/Handlers/LevelHandlers_Transient.cpp,
+	// Private/Handlers/AssetHandlers_BulkRead.cpp,
+	// Private/Handlers/FoliageHandlers_Batch.cpp,
+	// Private/Tests/LevelQueryComponentsTests.cpp,
+	// Private/Tests/LevelBatchWriteTests.cpp,
+	// Private/Tests/LevelRefreshTests.cpp,
+	// Private/Tests/LevelConvertBrushesTests.cpp,
+	// Private/Tests/LevelTransientActorTests.cpp,
+	// Private/Tests/AssetBulkReadTests.cpp and
+	// Private/Tests/FoliageBatchTests.cpp: same reason.
+	// Private/Tests/EditorFunctionCallTests.cpp (#885/#969): same reason.
+	// Private/Tests/SequencerScrubTests.cpp (#881): same reason.
+	// Private/Tests/AssetPathResolutionTests.cpp and
+	// Private/Tests/AssetPropertyPersistTests.cpp: same reason.
+	// Private/Handlers/AssetHandlers_Subobject.cpp,
+	// Private/Handlers/AssetHandlers_Redirectors.cpp and
+	// Private/Tests/AssetSubobjectTests.cpp: same reason.
+	// Private/Tests/AssetDeleteGuardTests.cpp (#976): same reason.
+	// Private/Tests/PackageWriteGuardTests.cpp (#932): same reason.
+	// Private/Handlers/BlueprintHandlers_Collision.cpp and
+	// Private/Tests/CollisionQueryTests.cpp (#925): same reason.
+	// Private/Handlers/AssetHandlers_MeshBoolean.cpp and
+	// Private/Tests/MeshBooleanTests.cpp (#916): same reason.
+	// Private/Tests/LevelTraceWorldScopeTests.cpp (#933): same reason.
+	// Private/Tests/LandscapeSampleTests.cpp (#939): same reason.
+	// Private/Handlers/LevelHandlers_PostProcess.cpp and
+	// Private/Tests/LevelPostProcessOverrideTests.cpp (#950): same reason.
+	// Private/Handlers/LevelHandlers_Save.cpp and
+	// Private/Tests/LevelSaveReportTests.cpp (#964): same reason.
+	// Private/Tests/LevelComponentTreeInstanceCountTests.cpp (#986): same reason.
+	// Private/Handlers/LevelHandlers_WorldPartitionSettings.cpp and
+	// Private/Tests/LevelWorldPartitionSettingsTests.cpp (#985): same reason.
 	public UE_MCP_Bridge(ReadOnlyTargetRules Target) : base(Target)
 	{
 		PCHUsage = ModuleRules.PCHUsageMode.UseExplicitOrSharedPCHs;
@@ -30,9 +89,25 @@ public class UE_MCP_Bridge : ModuleRules
 			new string[]
 			{
 				"AIModule",
+				// #889: authoring a BehaviorTree means driving UBehaviorTreeGraph
+				// and its node classes, then calling UpdateAsset to compile the
+				// graph into the runnable UBTCompositeNode tree. That orchestration
+				// lives only in BehaviorTreeEditor (with FGraphNodeClassData and
+				// UAIGraphNode::AddSubNode coming from AIGraph beneath it) and is
+				// not exposed to script, so no reflected runtime API can stand in
+				// for it. Both are editor modules, which this plugin already is:
+				// its .uplugin declares Type "Editor" and UnrealEd, UMGEditor and
+				// MaterialEditor are already linked the same way.
+				"AIGraph",
+				"BehaviorTreeEditor",
 				"MessageLog",
+				"AnimationCore",
 				"AnimGraph",
 				"AnimationEditor",
+				// UAnimPoseExtensions / FAnimPoseEvaluationOptions (AnimPose.h),
+				// the engine's own pose evaluator, used by animation(sample_pose)
+				// and animation(measure_natural_speed).
+				"AnimationBlueprintLibrary",
 				"AnimationModifiers",
 				"AssetRegistry",
 				"AssetTools",
@@ -51,6 +126,7 @@ public class UE_MCP_Bridge : ModuleRules
 				"ContentBrowser",
 				"ControlRig",
 				"ControlRigDeveloper",
+				"ControlRigEditor",
 				"RigVMDeveloper",
 				"DataValidation",
 				"EditorScriptingUtilities",
@@ -74,6 +150,7 @@ public class UE_MCP_Bridge : ModuleRules
 				"LevelEditor",
 				"LevelSequence",
 				"LevelSequenceEditor",
+				"MainFrame",
 				"MaterialEditor",
 				"MovieScene",
 				"MovieSceneTracks",
@@ -90,6 +167,7 @@ public class UE_MCP_Bridge : ModuleRules
 				"PythonScriptPlugin",
 				"Sequencer",
 				"Settings",
+				"SkeletalMeshEditor",
 				"Slate",
 				"SlateCore",
 				"StateTreeModule",
@@ -139,4 +217,13 @@ public class UE_MCP_Bridge : ModuleRules
 	}
 }
 
+// Rescan trigger: level-script handler automation coverage added.
 // Rescan trigger: round 2 added handler translation units.
+// Rescan trigger: Private/Tests/GameThreadGateTests.cpp (#968).
+// Rescan trigger: Private/Tests/AutomationRunnerTests.cpp (#993).
+// Rescan trigger: Mass and skeletal-mesh handler translation units.
+// Rescan trigger: FInstancedStruct scalar, wrapper-array and nested path tests added.
+// Round 3: Private/Handlers/GameplayHandlers_BehaviorTree.cpp and
+// Private/Tests/BehaviorTreeNodeTests.cpp.
+// Round 4: Private/Handlers/GameplayHandlers_BTAuthoring.cpp and
+// Private/Tests/BehaviorTreeAuthoringTests.cpp.

package/plugin/ue_mcp_bridge/Source/UE_MCP_BridgeStatus/Private/MCPEngineStatus.cpp

@@ -128,10 +128,25 @@ void FMCPEngineStatus::Install()
 
 	RebindFeedbackContextIfNeeded();
 
+	// #990: nothing polls a commandlet's engine state, and 32 of them writing
+	// one document four times a second was a build-breaking error storm. Do not
+	// even start the thread there.
+	if (!ShouldPublishStatus())
+	{
+		UE_LOG(LogMCPBridgeStatus, Log,
+			TEXT("[UE-MCP] Engine status snapshot installed without a writer thread: this process is a commandlet, and nothing polls a commandlet's engine state."));
+		return;
+	}
+
+	// Per-process status files from editors that crashed. Swept once, here, by
+	// the next process that can prove them stale, so a machine that crashes
+	// repeatedly does not accumulate a directory of them.
+	RemoveStaleInstanceStatusFiles();
+
 	bStopWriter = false;
 	WriterThread = FRunnableThread::Create(this, TEXT("MCPEngineStatusWriter"), 0, TPri_BelowNormal);
 
-	UE_LOG(LogMCPBridgeStatus, Log, TEXT("[UE-MCP] Engine status snapshot installed -> %s"), *StatusFilePath());
+	UE_LOG(LogMCPBridgeStatus, Log, TEXT("[UE-MCP] Engine status snapshot installed -> %s"), *InstanceStatusFilePath());
 }
 
 void FMCPEngineStatus::Shutdown()
@@ -188,9 +203,36 @@ void FMCPEngineStatus::Shutdown()
 	ModalProvider = nullptr;
 	CompileProvider = nullptr;
 
-	// Leave no stale file behind: a status.json from a dead editor claiming a
-	// 40% slow task is worse than no file at all.
-	IFileManager::Get().Delete(*StatusFilePath(), false, false, true);
+	// Leave no stale file behind: a status from a dead editor claiming a 40%
+	// slow task is worse than no file at all. This process's own file always
+	// goes; the shared one only if this process is the last thing that wrote
+	// it, so an editor shutting down does not blind a client watching another
+	// editor of the same project (#990).
+	IFileManager::Get().Delete(*InstanceStatusFilePath(), false, false, true);
+	if (SharedStatusBelongsToThisProcess())
+	{
+		IFileManager::Get().Delete(*StatusFilePath(), false, false, true);
+	}
+}
+
+bool FMCPEngineStatus::SharedStatusBelongsToThisProcess()
+{
+	FString Raw;
+	if (!FFileHelper::LoadFileToString(Raw, *StatusFilePath()))
+	{
+		return false;
+	}
+	TSharedPtr<FJsonObject> Parsed;
+	TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(Raw);
+	if (!FJsonSerializer::Deserialize(Reader, Parsed) || !Parsed.IsValid())
+	{
+		// Unreadable, so nothing can be shown to own it. Leaving it costs one
+		// stale file; removing it could take a live editor's snapshot away.
+		return false;
+	}
+	double Pid = 0.0;
+	return Parsed->TryGetNumberField(TEXT("pid"), Pid)
+		&& (uint32)Pid == FPlatformProcess::GetCurrentProcessId();
 }
 
 void FMCPEngineStatus::RebindFeedbackContextIfNeeded()
@@ -370,6 +412,10 @@ TSharedPtr<FJsonObject> FMCPEngineStatus::Snapshot() const
 	FScopeLock Lock(&Mutex);
 
 	Out->SetStringField(TEXT("phase"), Phase);
+	// #990: which process this describes. One project directory can hold the
+	// status of several, and a document that does not name its subject cannot
+	// be told apart from one that does.
+	Out->SetNumberField(TEXT("pid"), (double)FPlatformProcess::GetCurrentProcessId());
 	Out->SetNumberField(TEXT("uptimeSeconds"), Now - InstallSeconds);
 	Out->SetNumberField(TEXT("modulesLoaded"), ModulesLoaded);
 
@@ -450,13 +496,105 @@ TSharedPtr<FJsonObject> FMCPEngineStatus::Snapshot() const
 	return Out;
 }
 
+FString FMCPEngineStatus::StatusDir()
+{
+	return FPaths::Combine(FPaths::ProjectSavedDir(), TEXT("UE_MCP_Bridge"));
+}
+
 FString FMCPEngineStatus::StatusFilePath()
 {
-	return FPaths::Combine(FPaths::ProjectSavedDir(), TEXT("UE_MCP_Bridge"), TEXT("status.json"));
+	return FPaths::Combine(StatusDir(), TEXT("status.json"));
+}
+
+FString FMCPEngineStatus::InstanceStatusFilePath()
+{
+	return FPaths::Combine(StatusDir(),
+		FString::Printf(TEXT("status.%u.json"), FPlatformProcess::GetCurrentProcessId()));
+}
+
+bool FMCPEngineStatus::ShouldPublishStatus()
+{
+	// #990: a commandlet publishes nothing. A distributed HLOD build runs 32
+	// WorldPartitionBuilderCommandlet slots, each its own UnrealEditor-Cmd.exe
+	// with this plugin loaded, and all 32 wrote the same status.json from their
+	// own writer threads four times a second. One run produced 3,743
+	// Error-severity log lines, up to 147 in a single slot, and every slot then
+	// finished with "Failure - 112 error(s)" even where the HLOD work had
+	// succeeded, which breaks exit-status and error-count success detection for
+	// CI. One commandlet died in a retry storm. Nothing polls a commandlet's
+	// engine state in the first place: this exists so an agent can see what an
+	// INTERACTIVE editor is doing while its game thread is blocked.
+	//
+	// Asked per flush rather than once at Install, because the commandlet flag
+	// is set during engine startup and Install runs at PostConfigInit.
+	return !IsRunningCommandlet();
+}
+
+bool FMCPEngineStatus::PublishAtomically(const FString& FinalPath, const FString& Contents)
+{
+	// Write then move: a reader polling at the same rate would otherwise catch
+	// a half-written file and report "no snapshot" at the exact moment the
+	// snapshot matters.
+	//
+	// #990: the temp file carries this process's pid, the way
+	// FMCPBridgeStateFiles::PublishJson has always done it. Without that every
+	// process in the project directory wrote and renamed one shared
+	// `status.json.tmp`, so concurrent writers deleted each other's temp file
+	// out from under the rename and each failure was logged at Error severity.
+	const FString TempPath = FString::Printf(TEXT("%s.%u.tmp"), *FinalPath, FPlatformProcess::GetCurrentProcessId());
+	if (!FFileHelper::SaveStringToFile(Contents, *TempPath))
+	{
+		return false;
+	}
+	if (!IFileManager::Get().Move(*FinalPath, *TempPath, /*Replace*/ true, /*EvenIfReadOnly*/ true))
+	{
+		IFileManager::Get().Delete(*TempPath, /*RequireExists*/ false, /*EvenReadOnly*/ false, /*Quiet*/ true);
+		return false;
+	}
+	return true;
+}
+
+void FMCPEngineStatus::RemoveStaleInstanceStatusFiles()
+{
+	const FString Dir = StatusDir();
+	TArray<FString> FileNames;
+	IFileManager::Get().FindFiles(FileNames, *FPaths::Combine(Dir, TEXT("status.*.json")), /*Files*/ true, /*Directories*/ false);
+
+	const uint32 OwnPid = FPlatformProcess::GetCurrentProcessId();
+	for (const FString& FileName : FileNames)
+	{
+		// "status.<pid>.json" - the middle token is the pid, and anything that
+		// is not a number is not a file this writes.
+		FString Middle = FileName;
+		Middle.RemoveFromStart(TEXT("status."));
+		Middle.RemoveFromEnd(TEXT(".json"));
+		if (Middle.IsEmpty() || !Middle.IsNumeric())
+		{
+			continue;
+		}
+
+		const uint32 Pid = (uint32)FCString::Strtoui64(*Middle, nullptr, 10);
+		if (Pid == 0 || Pid == OwnPid || FPlatformProcess::IsApplicationRunning(Pid))
+		{
+			continue;
+		}
+
+		const FString FilePath = FPaths::Combine(Dir, FileName);
+		if (IFileManager::Get().Delete(*FilePath, /*RequireExists*/ false, /*EvenReadOnly*/ false, /*Quiet*/ true))
+		{
+			UE_LOG(LogMCPBridgeStatus, Log,
+				TEXT("[UE-MCP] Removed the stale engine status file for pid %u: that process is gone."), Pid);
+		}
+	}
 }
 
 void FMCPEngineStatus::FlushToDisk()
 {
+	if (!ShouldPublishStatus())
+	{
+		return;
+	}
+
 	TSharedPtr<FJsonObject> Json = Snapshot();
 	Json->SetStringField(TEXT("writtenAt"), FDateTime::UtcNow().ToIso8601());
 
@@ -464,15 +602,15 @@ void FMCPEngineStatus::FlushToDisk()
 	TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&Serialised);
 	FJsonSerializer::Serialize(Json.ToSharedRef(), Writer);
 
-	// Write then move: a reader polling at the same rate would otherwise catch
-	// a half-written file and report "no snapshot" at the exact moment the
-	// snapshot matters.
-	const FString Final = StatusFilePath();
-	const FString Temp = Final + TEXT(".tmp");
-	if (FFileHelper::SaveStringToFile(Serialised, *Temp))
-	{
-		IFileManager::Get().Move(*Final, *Temp, true, true);
-	}
+	// The per-process file first: it is the one nobody else can overwrite, and
+	// it is what a reader that understands several editors of one project uses.
+	PublishAtomically(InstanceStatusFilePath(), Serialised);
+
+	// And the shared path, so a client older than this change still finds a
+	// snapshot where it has always looked. Two editors of one project take
+	// turns here; the per-process files above are where each one's own truth
+	// stays intact.
+	PublishAtomically(StatusFilePath(), Serialised);
 }
 
 uint32 FMCPEngineStatus::Run()

package/plugin/ue_mcp_bridge/Source/UE_MCP_BridgeStatus/Private/Tests/MCPEngineStatusTests.cpp

@@ -0,0 +1,65 @@
+#if WITH_DEV_AUTOMATION_TESTS
+
+#include "MCPEngineStatus.h"
+#include "CoreGlobals.h"
+#include "Dom/JsonObject.h"
+#include "HAL/PlatformProcess.h"
+#include "Misc/AutomationTest.h"
+#include "Misc/Paths.h"
+
+/**
+ * What the status writer puts on disk, and what it refuses to put there.
+ *
+ * #990: every process that loads this plugin ran a writer thread that wrote
+ * `status.json` through one shared `status.json.tmp`. A distributed HLOD build
+ * runs 32 WorldPartitionBuilderCommandlet slots against one project directory,
+ * so 32 processes deleted and renamed the same temp file four times a second.
+ * One run produced 3,743 Error-severity log lines, and every slot ended with
+ * "Failure - 112 error(s)" even where the HLOD work succeeded, which breaks
+ * error-count success detection for CI.
+ *
+ * Nothing here binds a port or writes into the live state directory: these are
+ * assertions about paths and about the commandlet decision, both of which are
+ * pure.
+ */
+IMPLEMENT_SIMPLE_AUTOMATION_TEST(
+	FMCPEngineStatusPathsTest,
+	"UE.MCP.BridgeStatus.StatusPaths",
+	EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter)
+
+bool FMCPEngineStatusPathsTest::RunTest(const FString& Parameters)
+{
+	const FString Shared = FMCPEngineStatus::StatusFilePath();
+	const FString Own = FMCPEngineStatus::InstanceStatusFilePath();
+
+	TestEqual(TEXT("the shared path keeps its historical name"),
+		FPaths::GetCleanFilename(Shared), FString(TEXT("status.json")));
+
+	// The per-process name is what makes two editors of one project describable
+	// at the same time, and what a reader falls back across.
+	TestEqual(TEXT("the per-process path is named for this pid"),
+		FPaths::GetCleanFilename(Own),
+		FString::Printf(TEXT("status.%u.json"), FPlatformProcess::GetCurrentProcessId()));
+	TestNotEqual(TEXT("the two are different files"), Own, Shared);
+	TestEqual(TEXT("and live in the same directory"), FPaths::GetPath(Own), FPaths::GetPath(Shared));
+	TestEqual(TEXT("which is the bridge state directory"),
+		FPaths::GetPath(Own), FMCPEngineStatus::StatusDir());
+
+	// The publish decision. An editor publishes; a commandlet does not, because
+	// nothing polls a commandlet's engine state and dozens of them share one
+	// project directory.
+	TestTrue(TEXT("publishing follows the commandlet flag, and only that"),
+		FMCPEngineStatus::ShouldPublishStatus() == !IsRunningCommandlet());
+
+	// The snapshot has to name its subject: a document that does not say which
+	// process it describes cannot be told apart from one that does.
+	const TSharedPtr<FJsonObject> Snapshot = FMCPEngineStatus::Get().Snapshot();
+	TestTrue(TEXT("a snapshot exists"), Snapshot.IsValid());
+	double Pid = 0.0;
+	TestTrue(TEXT("the snapshot names its process"), Snapshot.IsValid() && Snapshot->TryGetNumberField(TEXT("pid"), Pid));
+	TestEqual(TEXT("and it is this one"), (int32)Pid, (int32)FPlatformProcess::GetCurrentProcessId());
+
+	return true;
+}
+
+#endif

package/plugin/ue_mcp_bridge/Source/UE_MCP_BridgeStatus/Public/MCPEngineStatus.h

@@ -86,6 +86,30 @@ public:
 	virtual uint32 Run() override;
 	virtual void Stop() override;
 
+	/** <Project>/Saved/UE_MCP_Bridge. */
+	static FString StatusDir();
+
+	/**
+	 * The shared `status.json`, still written so a client older than #990 finds
+	 * a snapshot where it has always looked.
+	 */
+	static FString StatusFilePath();
+
+	/**
+	 * `status.<pid>.json`, this process's own. One project directory can hold
+	 * the status of several processes, and a single shared document describes
+	 * only whichever of them wrote last (#990).
+	 */
+	static FString InstanceStatusFilePath();
+
+	/**
+	 * False in a commandlet. Nothing polls a commandlet's engine state, and a
+	 * distributed build runs dozens of them against one project directory,
+	 * where they used to fight over one file and turn a successful build into
+	 * thousands of Error lines (#990).
+	 */
+	static bool ShouldPublishStatus();
+
 private:
 	struct FSlowTaskEntry
 	{
@@ -96,7 +120,14 @@ private:
 	/** Serialise under the lock, then write atomically (temp file + move). */
 	void FlushToDisk();
 
-	static FString StatusFilePath();
+	/** Temp file plus rename, with the temp file named for this process. */
+	static bool PublishAtomically(const FString& FinalPath, const FString& Contents);
+
+	/** Drop `status.<pid>.json` files left by processes that are gone. */
+	static void RemoveStaleInstanceStatusFiles();
+
+	/** Does the shared status.json currently name this process? */
+	static bool SharedStatusBelongsToThisProcess();
 
 	mutable FCriticalSection Mutex;
 

package/plugin/ue_mcp_bridge/Source/UE_MCP_BridgeStatus/UE_MCP_BridgeStatus.Build.cs

@@ -36,3 +36,5 @@ public class UE_MCP_BridgeStatus : ModuleRules
 		);
 	}
 }
+
+// Rescan trigger: Private/Tests/MCPEngineStatusTests.cpp (#990).

package/skills/ue-mcp-animation/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: ue-mcp-animation
+description: Use when creating, modifying, retargeting, rigging, constraining, or validating skeletal animation through UE-MCP. Covers native UE 5.8 IK Rig and Retargeter authoring, the Control Rig begin/read/apply/bake loop, generic contact locks, per-rig anatomical and mirrored-axis discovery, quaternion keying, deterministic bone analysis, and exact fixed-frame Unreal capture.
+---
+
+# UE-MCP native animation workflow
+
+Create quality animation from measured pose constraints, not guessed control
+angles. Control names, local axes, palm axes, handedness, and scale are
+properties of the selected rig. Discover them again for every unfamiliar rig;
+never paste values from another rig or negate a left-side Euler pose to make a
+right-side pose.
+
+## Required loop
+
+1. Call `project(action="get_status")`; verify the intended project and editor.
+2. Establish the character's authoring baseline before editing clips. Search
+   for a Control Rig already bound to the target mesh/skeleton and inspect it
+   with `read_control_rig_hierarchy` and `read_control_rig_graph`. It must have
+   the controls, Forward Solve, and Backward Solve required for the intended
+   edits. If the project or character has no suitable rig, create one first
+   with the bundled Epic 5.8 controlrig actions (`epic_create`,
+   `epic_import_bones_from_asset`, `epic_add_control`, deliberate Forward Solve
+   nodes/links, and `epic_add_backward_solve_graph`), then save the exact rig
+   with `asset(epic_save_assets)`. `epic_create` alone creates no imported
+   bones, authored controls, or solver wiring. Run an unchanged
+   source-to-controls-to-bones round trip on the exact production mesh. Do not
+   begin production work on an unverified or merely name-compatible rig.
+3. Resolve the source AnimSequence, mesh, skeleton, verified Control Rig, and
+   frame rate.
+   When IK/retarget assets are part of the job, use `read_ik_rig` and
+   `read_ik_retargeter` first. On UE 5.8 use `configure_ik_rig` for validated
+   roots, ancestry-valid chains, concrete goals, solver connections and
+   effectors; use `configure_ik_retargeter` for the default op stack, source and
+   target rig assignment to every op, auto/manual mappings, preview meshes, and
+   a named retarget pose. Read both assets back after saving. A chain's goal
+   string is not proof that a goal or solver exists.
+4. Create a versioned session with `begin_control_rig_edit`. Use a unique
+   LevelSequence path and `bindingTag`, an end-exclusive frame range, and
+   `onConflict="error"`. Use `rigMode="asset"` for a project rig or `"fk"` only
+   when generated FK controls are intentional. The source must be non-additive
+   and mesh-compatible; flatten an additive clip against its intended base
+   first. `layered` controls the session layer, not an additive source base.
+   A finite non-zero source `RateScale` is compensated in Sequencer so the raw
+   timeline maps once without modifying the source asset; zero is rejected.
+5. Call `read_control_rig_edit` at rest, transitions, extrema, and end in both
+   `local` and `global` space. Here `global` is rig/global (normally mesh
+   component) space, not actor world space.
+6. Inspect every control's `controlType`, `animatable`, and enum metadata. Write
+   scalars with the matching `set_bool`, `set_float`, or `set_int`; enum values
+   must come from `enumOptions`. Never write `animatable=false` controls.
+7. Define anatomical component-space targets, then solve proximal to distal:
+   shoulder/upper arm, elbow pole and bend, forearm direction, wrist, palm
+   normal, then secondary motion. For a wave, the forearm must rise, the wrist
+   must sit above the elbow/near the shoulder region, and the probed palm normal
+   must face the intended viewer before wrist oscillation is added.
+8. When an axis is uncertain, make an immutable probe session. Apply a small
+   positive and negative rotation to one local axis at one fixed frame, bake,
+   and inspect the resulting component-space shoulder/forearm/hand landmarks
+   with `analyze_animation`. Probe the right side separately; mirrored parents
+   or negative scale can reverse anatomical meanings. Preserve the full scale
+   read from the control.
+9. Apply absolute `set_keys` transforms with finite normalized quaternions,
+   complete translation/rotationQuaternion/scale payloads, and strictly
+   increasing frames. Preserve translation and scale unless intentionally
+   editing them. If the source bake has dense keys, key every affected frame;
+   sparse keys will not replace the intervening source motion. Apply related
+   controls and scalar switches in one transaction.
+   For a fixed contact, use `contact_lock` in the same operation batch. Supply a
+   keyable translatable driver, optional driven bone/socket, inclusive frame
+   range, component-space target, optional pole/stabilizer controls, and
+   position/rotation tolerances. The session must contain one source animation
+   section. The bridge samples it per frame, writes dense smooth-edged keys, and
+   transactionally reads back the driver and stabilizers. A driven bone/socket
+   returns `verification=bake_and_analyze_required`; bake, analyze every
+   constrained frame, and reject the output if its residual misses the motion's
+   acceptance tolerance. FK contacts whose translation is ignored by skeleton
+   retargeting use a local rotation-chain solve and report
+   `solver=fk_rotation_chain`; that path requires a driven bone and does not
+   accept stabilizers. Position-only locks leave the driven control orientation
+   unkeyed. The bridge does not guess the driver, pole, foot roll, friction,
+   joint limits, or pelvis compensation.
+10. Read back the edited frames in local and global space. Reject elbow flips,
+   discontinuities, wrong forearm direction, wrong palm normal, or unexpected
+   changes outside the edited chain before baking.
+11. Bake to a new versioned AnimSequence with `bake_control_rig_edit`,
+    `reduceKeys=false`, and `onConflict="error"`. Never overwrite source,
+    another iteration's session, or prior approved output assets.
+
+## Validation and visual review
+
+Run `analyze_animation` on source and output using the same mesh, explicit
+frames, and bones. Include root, pelvis, the complete edited chain, feet,
+opposite side, and any controls/bones expected to remain unchanged. Write its
+native `manifest.json` and `samples.ndjson` beneath
+`Saved/Codex/AnimationQA`.
+
+Check numeric integrity, invalid transforms, selected-bone bounds, root
+displacement/speed, and loop seam metrics. Derive gesture-specific checks from
+component transforms: shoulder-relative wrist height, elbow-to-wrist vector,
+elbow angle/plane stability, probed palm-normal alignment, speed/acceleration,
+direction changes, and drift in untouched bones. Numeric samples are the source
+of truth; screenshots are the human visual gate.
+
+Use the analyzer's `rateScale`, `effectiveDurationSeconds`, and per-notify
+`rawTriggerTimeSeconds` / `effectiveTriggerTimeSeconds` fields when validating
+gameplay release timing. Effective times use the asset-rate magnitude and are
+null when the asset rate is zero.
+
+For an exact native frame capture, without Computer Use or Python:
+
+1. `editor(action="open_asset", assetPath=<baked_anim>)`.
+2. `editor(action="find_object")` for `className="AnimSingleNodeInstance"`,
+   `nameContains="AnimPreviewInstance"`, `world="any"`; select the match under
+   the current `AnimationEditorPreviewActor`.
+3. In one `editor(action="invoke_object_functions")` call, invoke `SetPlaying` with
+   `bIsPlaying=false`, then `SetPosition` with
+   `InPosition=frame*rateDenominator/rateNumerator` and
+   `bFireNotifies=false` on that object path.
+4. Open the asset again to focus its window and call
+   `editor(action="capture_screenshot", target="window")`.
+5. Capture start, entry, both extrema, exit, and end with a consistent view.
+
+Keep versioned V&V fixtures for a from-scratch gesture, full-body IK authoring,
+a retarget between known skeletons, a copied animation modified through IK plus
+its pole target, a bone/socket contact with an unrelated simultaneous edit, and
+edge cases covering mirrored/negative scale, dense keys, additive-source
+rejection/flattening, layered sessions, scalar enums, root motion, loops, and
+short clips.
+
+The loop generalizes beyond humanoid arms. Re-discover the rig mapping, then
+express legs as hip/knee-pole/foot/contact constraints; spine and head as
+arc/twist/aim constraints; tails, tentacles, and ropes as length-preserving
+chain curves with delayed phase; and props or mechanisms as pivot, attachment,
+contact, and clearance constraints. Only control/bone names, axes/signs,
+mirrored scale, limits, and motion constraints are rig-specific.
+
+## Compatibility and endpoint rule
+
+The four Control Rig session actions, `configure_ik_rig`,
+`configure_ik_retargeter`, and `contact_lock` are UE 5.8 only and return
+`unsupported_engine_version` on older engines; do not invent a reflected or
+raw-bone fallback. Legacy IK create/read behavior is unchanged.
+`analyze_animation` is cross-version through the native APIs in the compiled
+engine. See the public
+[Native Control Rig Animation](https://ue-mcp.com/docs/control-rig-animation/)
+guide for full call shapes and fixture guidance.
+
+Edit ranges are `[startFrame, endFrameExclusive)`. The bridge keeps an internal
+support frame for Unreal's exact-duration export sample without making the
+exclusive end authorable. Validate the last visible frame and exact-duration
+sample separately. A non-looping endpoint must hold the intended final pose
+without an adjacent-frame teleport or rotation jump; a looping endpoint must
+pass the requested seam check. A large endpoint discontinuity fails the bake.