ue-mcp 1.1.19 → 1.1.21

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/Handlers/DiffHandlers.cpp

@@ -0,0 +1,328 @@
+#include "Handlers/DiffHandlers.h"
+#include "HandlerRegistry.h"
+#include "HandlerUtils.h"
+#include "Engine/Blueprint.h"
+#include "EdGraph/EdGraph.h"
+#include "EdGraph/EdGraphNode.h"
+#include "EdGraph/EdGraphPin.h"
+#include "Engine/SimpleConstructionScript.h"
+#include "Engine/SCS_Node.h"
+
+// ── Structural extraction helpers ────────────────────────────────────────────
+namespace
+{
+	/** Compact, stable string for a pin type, e.g. "int", "object(Actor)",
+	 *  "struct(Vector)[]". Used to detect variable type changes. */
+	FString PinTypeToShortString(const FEdGraphPinType& T)
+	{
+		FString S = T.PinCategory.ToString();
+		if (const UObject* Sub = T.PinSubCategoryObject.Get())
+		{
+			S += TEXT("(") + Sub->GetName() + TEXT(")");
+		}
+		else if (!T.PinSubCategory.IsNone())
+		{
+			S += TEXT("(") + T.PinSubCategory.ToString() + TEXT(")");
+		}
+		switch (T.ContainerType)
+		{
+			case EPinContainerType::Array: S += TEXT("[]"); break;
+			case EPinContainerType::Set:   S += TEXT("{}"); break;
+			case EPinContainerType::Map:   S += TEXT("{:}"); break;
+			default: break;
+		}
+		return S;
+	}
+
+	/** All named graphs of a Blueprint keyed by graph name (event graphs +
+	 *  function graphs + macro graphs). */
+	TMap<FString, UEdGraph*> CollectGraphs(UBlueprint* BP)
+	{
+		TMap<FString, UEdGraph*> Out;
+		auto Add = [&Out](const TArray<UEdGraph*>& Graphs)
+		{
+			for (UEdGraph* G : Graphs)
+			{
+				if (G) Out.Add(G->GetName(), G);
+			}
+		};
+		Add(BP->UbergraphPages);
+		Add(BP->FunctionGraphs);
+		Add(BP->MacroGraphs);
+		return Out;
+	}
+
+	TSharedPtr<FJsonObject> NodeSummary(UEdGraphNode* Node)
+	{
+		TSharedPtr<FJsonObject> Obj = MakeShared<FJsonObject>();
+		Obj->SetStringField(TEXT("id"), Node->NodeGuid.ToString());
+		Obj->SetStringField(TEXT("class"), Node->GetClass()->GetName());
+		Obj->SetStringField(TEXT("title"), Node->GetNodeTitle(ENodeTitleType::ListView).ToString());
+		return Obj;
+	}
+
+	/** Canonical strings for every connection in a graph, emitted once per link
+	 *  (from the output side). Format: "SrcGuid.Pin -> DstGuid.Pin". */
+	TSet<FString> CollectConnections(UEdGraph* Graph)
+	{
+		TSet<FString> Out;
+		for (UEdGraphNode* Node : Graph->Nodes)
+		{
+			if (!Node) continue;
+			for (UEdGraphPin* Pin : Node->Pins)
+			{
+				if (!Pin || Pin->Direction != EGPD_Output) continue;
+				for (UEdGraphPin* Linked : Pin->LinkedTo)
+				{
+					if (!Linked || !Linked->GetOwningNodeUnchecked()) continue;
+					Out.Add(FString::Printf(TEXT("%s.%s -> %s.%s"),
+						*Node->NodeGuid.ToString(), *Pin->PinName.ToString(),
+						*Linked->GetOwningNode()->NodeGuid.ToString(), *Linked->PinName.ToString()));
+				}
+			}
+		}
+		return Out;
+	}
+
+	TArray<TSharedPtr<FJsonValue>> StringsToJson(const TArray<FString>& In)
+	{
+		TArray<TSharedPtr<FJsonValue>> Out;
+		Out.Reserve(In.Num());
+		for (const FString& S : In) Out.Add(MakeShared<FJsonValueString>(S));
+		return Out;
+	}
+}
+
+void FDiffHandlers::RegisterHandlers(FMCPHandlerRegistry& Registry)
+{
+	Registry.RegisterHandler(TEXT("diff_blueprint"), &FDiffHandlers::DiffBlueprint);
+	Registry.RegisterHandler(TEXT("diff_asset"), &FDiffHandlers::DiffAsset);
+}
+
+TSharedPtr<FJsonValue> FDiffHandlers::DiffBlueprint(const TSharedPtr<FJsonObject>& Params)
+{
+	FString PathA;
+	if (TSharedPtr<FJsonValue> Err = RequireStringAlt(Params, TEXT("assetPath"), TEXT("path"), PathA)) return Err;
+	FString PathB;
+	if (TSharedPtr<FJsonValue> Err = RequireString(Params, TEXT("otherPath"), PathB)) return Err;
+
+	// Revision-based diffing (loading a depot revision into a transient package)
+	// is a documented follow-up; for now both sides are loadable asset paths.
+	if (Params->HasField(TEXT("fromRevision")) || Params->HasField(TEXT("toRevision")))
+	{
+		return MCPError(TEXT("Revision-based diffing (fromRevision/toRevision via source control) is not wired yet - pass 'otherPath' to diff two loaded Blueprint assets. Revision loading is a staged follow-up."));
+	}
+
+	UBlueprint* A = LoadAssetByPath<UBlueprint>(PathA);
+	if (!A) return MCPError(FString::Printf(TEXT("Blueprint not found: %s"), *PathA));
+	UBlueprint* B = LoadAssetByPath<UBlueprint>(PathB);
+	if (!B) return MCPError(FString::Printf(TEXT("Blueprint not found: %s"), *PathB));
+
+	TSharedPtr<FJsonObject> Result = MCPSuccess();
+	Result->SetStringField(TEXT("assetType"), TEXT("Blueprint"));
+	Result->SetStringField(TEXT("from"), PathA);
+	Result->SetStringField(TEXT("to"), PathB);
+
+	int32 ChangeCount = 0;
+
+	// ── Parent class ────────────────────────────────────────────────────────
+	const FString ParentA = A->ParentClass ? A->ParentClass->GetPathName() : TEXT("");
+	const FString ParentB = B->ParentClass ? B->ParentClass->GetPathName() : TEXT("");
+	if (ParentA != ParentB)
+	{
+		TSharedPtr<FJsonObject> PC = MakeShared<FJsonObject>();
+		PC->SetStringField(TEXT("from"), ParentA);
+		PC->SetStringField(TEXT("to"), ParentB);
+		Result->SetObjectField(TEXT("parentClassChanged"), PC);
+		++ChangeCount;
+	}
+
+	// ── Variables ───────────────────────────────────────────────────────────
+	auto VarMap = [](UBlueprint* BP)
+	{
+		TMap<FString, TPair<FString, FString>> M; // name -> (type, default)
+		for (const FBPVariableDescription& V : BP->NewVariables)
+		{
+			M.Add(V.VarName.ToString(), TPair<FString, FString>(PinTypeToShortString(V.VarType), V.DefaultValue));
+		}
+		return M;
+	};
+	const TMap<FString, TPair<FString, FString>> VA = VarMap(A);
+	const TMap<FString, TPair<FString, FString>> VB = VarMap(B);
+	{
+		TArray<FString> Added, Removed;
+		TArray<TSharedPtr<FJsonValue>> Changed;
+		for (const auto& Pair : VB) if (!VA.Contains(Pair.Key)) Added.Add(Pair.Key);
+		for (const auto& Pair : VA)
+		{
+			if (const TPair<FString, FString>* Bv = VB.Find(Pair.Key))
+			{
+				if (Bv->Key != Pair.Value.Key || Bv->Value != Pair.Value.Value)
+				{
+					TSharedPtr<FJsonObject> C = MakeShared<FJsonObject>();
+					C->SetStringField(TEXT("name"), Pair.Key);
+					C->SetStringField(TEXT("fromType"), Pair.Value.Key);
+					C->SetStringField(TEXT("toType"), Bv->Key);
+					C->SetStringField(TEXT("fromDefault"), Pair.Value.Value);
+					C->SetStringField(TEXT("toDefault"), Bv->Value);
+					Changed.Add(MakeShared<FJsonValueObject>(C));
+				}
+			}
+			else
+			{
+				Removed.Add(Pair.Key);
+			}
+		}
+		if (Added.Num() || Removed.Num() || Changed.Num())
+		{
+			TSharedPtr<FJsonObject> V = MakeShared<FJsonObject>();
+			V->SetArrayField(TEXT("added"), StringsToJson(Added));
+			V->SetArrayField(TEXT("removed"), StringsToJson(Removed));
+			V->SetArrayField(TEXT("changed"), Changed);
+			Result->SetObjectField(TEXT("variables"), V);
+			ChangeCount += Added.Num() + Removed.Num() + Changed.Num();
+		}
+	}
+
+	// ── Components (SimpleConstructionScript) ───────────────────────────────
+	auto CompMap = [](UBlueprint* BP)
+	{
+		TMap<FString, FString> M; // name -> class
+		if (BP->SimpleConstructionScript)
+		{
+			for (USCS_Node* Node : BP->SimpleConstructionScript->GetAllNodes())
+			{
+				if (!Node) continue;
+				const FString Name = Node->GetVariableName().ToString();
+				const FString Cls = Node->ComponentClass ? Node->ComponentClass->GetName() : TEXT("");
+				M.Add(Name, Cls);
+			}
+		}
+		return M;
+	};
+	const TMap<FString, FString> CA = CompMap(A);
+	const TMap<FString, FString> CB = CompMap(B);
+	{
+		TArray<TSharedPtr<FJsonValue>> Added, Removed, Changed;
+		for (const auto& Pair : CB) if (!CA.Contains(Pair.Key))
+		{
+			TSharedPtr<FJsonObject> O = MakeShared<FJsonObject>();
+			O->SetStringField(TEXT("name"), Pair.Key);
+			O->SetStringField(TEXT("class"), Pair.Value);
+			Added.Add(MakeShared<FJsonValueObject>(O));
+		}
+		for (const auto& Pair : CA)
+		{
+			if (const FString* Bc = CB.Find(Pair.Key))
+			{
+				if (*Bc != Pair.Value)
+				{
+					TSharedPtr<FJsonObject> O = MakeShared<FJsonObject>();
+					O->SetStringField(TEXT("name"), Pair.Key);
+					O->SetStringField(TEXT("fromClass"), Pair.Value);
+					O->SetStringField(TEXT("toClass"), *Bc);
+					Changed.Add(MakeShared<FJsonValueObject>(O));
+				}
+			}
+			else
+			{
+				TSharedPtr<FJsonObject> O = MakeShared<FJsonObject>();
+				O->SetStringField(TEXT("name"), Pair.Key);
+				O->SetStringField(TEXT("class"), Pair.Value);
+				Removed.Add(MakeShared<FJsonValueObject>(O));
+			}
+		}
+		if (Added.Num() || Removed.Num() || Changed.Num())
+		{
+			TSharedPtr<FJsonObject> C = MakeShared<FJsonObject>();
+			C->SetArrayField(TEXT("added"), Added);
+			C->SetArrayField(TEXT("removed"), Removed);
+			C->SetArrayField(TEXT("changed"), Changed);
+			Result->SetObjectField(TEXT("components"), C);
+			ChangeCount += Added.Num() + Removed.Num() + Changed.Num();
+		}
+	}
+
+	// ── Graphs: node + connection deltas keyed on stable NodeGuid ───────────
+	const TMap<FString, UEdGraph*> GA = CollectGraphs(A);
+	const TMap<FString, UEdGraph*> GB = CollectGraphs(B);
+	{
+		// Functions/macros/event-graphs present on only one side.
+		TArray<FString> GraphsAdded, GraphsRemoved;
+		for (const auto& Pair : GB) if (!GA.Contains(Pair.Key)) GraphsAdded.Add(Pair.Key);
+		for (const auto& Pair : GA) if (!GB.Contains(Pair.Key)) GraphsRemoved.Add(Pair.Key);
+		if (GraphsAdded.Num() || GraphsRemoved.Num())
+		{
+			TSharedPtr<FJsonObject> G = MakeShared<FJsonObject>();
+			G->SetArrayField(TEXT("added"), StringsToJson(GraphsAdded));
+			G->SetArrayField(TEXT("removed"), StringsToJson(GraphsRemoved));
+			Result->SetObjectField(TEXT("graphsAddedRemoved"), G);
+			ChangeCount += GraphsAdded.Num() + GraphsRemoved.Num();
+		}
+
+		TArray<TSharedPtr<FJsonValue>> GraphDeltas;
+		for (const auto& Pair : GA)
+		{
+			UEdGraph* GraphA = Pair.Value;
+			UEdGraph* const* GraphBPtr = GB.Find(Pair.Key);
+			if (!GraphBPtr) continue; // whole-graph add/remove handled above
+			UEdGraph* GraphB = *GraphBPtr;
+
+			TMap<FString, UEdGraphNode*> NodesA, NodesB;
+			for (UEdGraphNode* N : GraphA->Nodes) if (N) NodesA.Add(N->NodeGuid.ToString(), N);
+			for (UEdGraphNode* N : GraphB->Nodes) if (N) NodesB.Add(N->NodeGuid.ToString(), N);
+
+			TArray<TSharedPtr<FJsonValue>> NodesAdded, NodesRemoved;
+			for (const auto& NB : NodesB) if (!NodesA.Contains(NB.Key)) NodesAdded.Add(MakeShared<FJsonValueObject>(NodeSummary(NB.Value)));
+			for (const auto& NA : NodesA) if (!NodesB.Contains(NA.Key)) NodesRemoved.Add(MakeShared<FJsonValueObject>(NodeSummary(NA.Value)));
+
+			const TSet<FString> ConnA = CollectConnections(GraphA);
+			const TSet<FString> ConnB = CollectConnections(GraphB);
+			TArray<FString> ConnAdded, ConnRemoved;
+			for (const FString& C : ConnB) if (!ConnA.Contains(C)) ConnAdded.Add(C);
+			for (const FString& C : ConnA) if (!ConnB.Contains(C)) ConnRemoved.Add(C);
+
+			if (NodesAdded.Num() || NodesRemoved.Num() || ConnAdded.Num() || ConnRemoved.Num())
+			{
+				TSharedPtr<FJsonObject> GD = MakeShared<FJsonObject>();
+				GD->SetStringField(TEXT("graph"), Pair.Key);
+				GD->SetArrayField(TEXT("nodesAdded"), NodesAdded);
+				GD->SetArrayField(TEXT("nodesRemoved"), NodesRemoved);
+				GD->SetArrayField(TEXT("connectionsAdded"), StringsToJson(ConnAdded));
+				GD->SetArrayField(TEXT("connectionsRemoved"), StringsToJson(ConnRemoved));
+				GraphDeltas.Add(MakeShared<FJsonValueObject>(GD));
+				ChangeCount += NodesAdded.Num() + NodesRemoved.Num() + ConnAdded.Num() + ConnRemoved.Num();
+			}
+		}
+		if (GraphDeltas.Num())
+		{
+			Result->SetArrayField(TEXT("graphs"), GraphDeltas);
+		}
+	}
+
+	Result->SetNumberField(TEXT("changeCount"), ChangeCount);
+	Result->SetBoolField(TEXT("identical"), ChangeCount == 0);
+	Result->SetStringField(TEXT("summary"), ChangeCount == 0
+		? FString::Printf(TEXT("%s and %s are structurally identical"), *PathA, *PathB)
+		: FString::Printf(TEXT("%d structural change(s) from %s to %s"), ChangeCount, *PathA, *PathB));
+
+	return MCPResult(Result);
+}
+
+TSharedPtr<FJsonValue> FDiffHandlers::DiffAsset(const TSharedPtr<FJsonObject>& Params)
+{
+	FString PathA;
+	if (TSharedPtr<FJsonValue> Err = RequireStringAlt(Params, TEXT("assetPath"), TEXT("path"), PathA)) return Err;
+
+	if (UObject* Asset = LoadAssetByPath<UObject>(PathA))
+	{
+		if (Asset->IsA<UBlueprint>())
+		{
+			return DiffBlueprint(Params);
+		}
+		return MCPError(FString::Printf(
+			TEXT("Diffing '%s' assets is not supported yet. Blueprint diffing is available now; StateTree and other graph assets are staged follow-ups."),
+			*Asset->GetClass()->GetName()));
+	}
+	return MCPError(FString::Printf(TEXT("Asset not found: %s"), *PathA));
+}

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/Handlers/DiffHandlers.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Dom/JsonValue.h"
+#include "Dom/JsonObject.h"
+
+/**
+ * Semantic revision diffing for graph-based binary assets. Blueprint and
+ * StateTree assets are opaque to git, so an agent's edits are unreviewable:
+ * there is no way to answer "what did this change between two versions".
+ *
+ * Phase 1 (here): Blueprint structural diff between two loadable asset paths —
+ * parent class, variables, functions/macros, components, and per-graph node and
+ * connection deltas, keyed on the stable node GUID so a moved or edited node is
+ * matched rather than reported as remove+add. Output is a structured JSON delta
+ * plus a human-readable summary.
+ *
+ * Follow-ups (documented, not yet wired): loading an arbitrary source-control
+ * revision into a transient package so the "to" side can be a depot revision
+ * rather than a second on-disk asset (needs a live SCC spike), then StateTree
+ * assets on the same diff spine.
+ */
+class FDiffHandlers
+{
+public:
+	static void RegisterHandlers(class FMCPHandlerRegistry& Registry);
+
+private:
+	// Diff two Blueprints loaded from asset paths. Params: assetPath (base/A),
+	// otherPath (compare/B). Reports changes as A -> B.
+	static TSharedPtr<FJsonValue> DiffBlueprint(const TSharedPtr<FJsonObject>& Params);
+
+	// Type-routing entry point. Blueprints delegate to DiffBlueprint; other
+	// asset classes return a clear "not yet supported" until their phase lands.
+	static TSharedPtr<FJsonValue> DiffAsset(const TSharedPtr<FJsonObject>& Params);
+};

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/Handlers/LockHandlers.cpp

@@ -0,0 +1,107 @@
+#include "Handlers/LockHandlers.h"
+#include "HandlerRegistry.h"
+#include "HandlerUtils.h"
+#include "LockRegistry.h"
+#include "HAL/PlatformTime.h"
+
+namespace
+{
+	/** Serialize a lock record to the wire shape shared by list/acquire/release. */
+	TSharedPtr<FJsonObject> LockToJson(const FMCPAssetLock& Lock)
+	{
+		const double Remaining = FMath::Max(0.0, Lock.ExpiresMono - FPlatformTime::Seconds());
+		TSharedPtr<FJsonObject> Obj = MakeShared<FJsonObject>();
+		Obj->SetStringField(TEXT("path"), Lock.AssetPath);
+		Obj->SetStringField(TEXT("sessionId"), Lock.SessionId);
+		Obj->SetStringField(TEXT("acquiredAt"), Lock.AcquiredAtUtc.ToIso8601());
+		Obj->SetNumberField(TEXT("ttlSeconds"), Lock.TtlSeconds);
+		Obj->SetNumberField(TEXT("ttlSecondsRemaining"), Remaining);
+		return Obj;
+	}
+}
+
+void FLockHandlers::RegisterHandlers(FMCPHandlerRegistry& Registry)
+{
+	Registry.RegisterHandler(TEXT("acquire_lock"), &FLockHandlers::AcquireLock);
+	Registry.RegisterHandler(TEXT("release_lock"), &FLockHandlers::ReleaseLock);
+	Registry.RegisterHandler(TEXT("release_session_locks"), &FLockHandlers::ReleaseSessionLocks);
+	Registry.RegisterHandler(TEXT("list_locks"), &FLockHandlers::ListLocks);
+}
+
+TSharedPtr<FJsonValue> FLockHandlers::AcquireLock(const TSharedPtr<FJsonObject>& Params)
+{
+	FString Path;
+	if (TSharedPtr<FJsonValue> Err = RequireStringAlt(Params, TEXT("path"), TEXT("assetPath"), Path)) return Err;
+	FString SessionId;
+	if (TSharedPtr<FJsonValue> Err = RequireString(Params, TEXT("sessionId"), SessionId)) return Err;
+
+	double Ttl = OptionalNumber(Params, TEXT("ttlSeconds"), 300.0);
+	if (Ttl <= 0.0) Ttl = 300.0;
+
+	FMCPAssetLock Holder;
+	const bool bAcquired = FMCPLockRegistry::Get().Acquire(Path, SessionId, Ttl, Holder);
+
+	TSharedPtr<FJsonObject> Res = MCPSuccess();
+	Res->SetBoolField(TEXT("acquired"), bAcquired);
+	Res->SetStringField(TEXT("path"), Path);
+	Res->SetStringField(TEXT("sessionId"), SessionId);
+	if (bAcquired)
+	{
+		Res->SetNumberField(TEXT("ttlSeconds"), Ttl);
+		Res->SetNumberField(TEXT("ttlSecondsRemaining"), FMath::Max(0.0, Holder.ExpiresMono - FPlatformTime::Seconds()));
+	}
+	else
+	{
+		// Busy: describe the current holder so the caller (or the Node
+		// middleware) can surface a retryable error.
+		Res->SetObjectField(TEXT("holder"), LockToJson(Holder));
+	}
+	return MCPResult(Res);
+}
+
+TSharedPtr<FJsonValue> FLockHandlers::ReleaseLock(const TSharedPtr<FJsonObject>& Params)
+{
+	FString Path;
+	if (TSharedPtr<FJsonValue> Err = RequireStringAlt(Params, TEXT("path"), TEXT("assetPath"), Path)) return Err;
+	FString SessionId;
+	if (TSharedPtr<FJsonValue> Err = RequireString(Params, TEXT("sessionId"), SessionId)) return Err;
+	const bool bForce = OptionalBool(Params, TEXT("force"), false);
+
+	FMCPAssetLock Released;
+	const bool bReleased = FMCPLockRegistry::Get().Release(Path, SessionId, bForce, Released);
+
+	TSharedPtr<FJsonObject> Res = MCPSuccess();
+	Res->SetBoolField(TEXT("released"), bReleased);
+	Res->SetStringField(TEXT("path"), Path);
+	return MCPResult(Res);
+}
+
+TSharedPtr<FJsonValue> FLockHandlers::ReleaseSessionLocks(const TSharedPtr<FJsonObject>& Params)
+{
+	FString SessionId;
+	if (TSharedPtr<FJsonValue> Err = RequireString(Params, TEXT("sessionId"), SessionId)) return Err;
+
+	const int32 Count = FMCPLockRegistry::Get().ReleaseSession(SessionId);
+
+	TSharedPtr<FJsonObject> Res = MCPSuccess();
+	Res->SetStringField(TEXT("sessionId"), SessionId);
+	Res->SetNumberField(TEXT("released"), Count);
+	return MCPResult(Res);
+}
+
+TSharedPtr<FJsonValue> FLockHandlers::ListLocks(const TSharedPtr<FJsonObject>& Params)
+{
+	const TArray<FMCPAssetLock> Locks = FMCPLockRegistry::Get().List();
+
+	TArray<TSharedPtr<FJsonValue>> Arr;
+	Arr.Reserve(Locks.Num());
+	for (const FMCPAssetLock& Lock : Locks)
+	{
+		Arr.Add(MakeShared<FJsonValueObject>(LockToJson(Lock)));
+	}
+
+	TSharedPtr<FJsonObject> Res = MCPSuccess();
+	Res->SetArrayField(TEXT("locks"), Arr);
+	Res->SetNumberField(TEXT("count"), Locks.Num());
+	return MCPResult(Res);
+}

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/Handlers/LockHandlers.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Dom/JsonValue.h"
+#include "Dom/JsonObject.h"
+
+/**
+ * Per-asset exclusive locking so concurrent agents (or an agent plus a human)
+ * don't issue conflicting mutations against the same asset. Backed by
+ * FMCPLockRegistry, which lives in the bridge — the single shared editor every
+ * agent connects to. Exposed as explicit acquire/release/list actions; the
+ * Node dispatch layer also wraps mutating calls with these when locking is
+ * enabled (see src/locking.ts).
+ */
+class FLockHandlers
+{
+public:
+	static void RegisterHandlers(class FMCPHandlerRegistry& Registry);
+
+private:
+	static TSharedPtr<FJsonValue> AcquireLock(const TSharedPtr<FJsonObject>& Params);
+	static TSharedPtr<FJsonValue> ReleaseLock(const TSharedPtr<FJsonObject>& Params);
+	static TSharedPtr<FJsonValue> ReleaseSessionLocks(const TSharedPtr<FJsonObject>& Params);
+	static TSharedPtr<FJsonValue> ListLocks(const TSharedPtr<FJsonObject>& Params);
+};

package/plugin/ue_mcp_bridge/Source/UE_MCP_Bridge/Private/Handlers/NiagaraHandlers.cpp

@@ -27,6 +27,7 @@
 #include "NiagaraNodeCustomHlsl.h"
 #include "NiagaraEmitterHandle.h"
 #include "NiagaraEditorUtilities.h"
+#include "NiagaraEmitterFactoryNew.h"
 #include "Editor.h"
 #include "Engine/World.h"
 #include "EngineUtils.h"
@@ -251,7 +252,18 @@ TSharedPtr<FJsonValue> FNiagaraHandlers::CreateNiagaraEmitter(const TSharedPtr<F
 		return MCPError(TEXT("NiagaraEmitter class not found - factory not available"));
 	}
 
-	auto Created = MCPCreateAssetIdempotent<UObject>(Name, PackagePath, OnConflict, TEXT("NiagaraEmitter"), EmitterClass, nullptr);
+	// Build the emitter through UNiagaraEmitterFactoryNew, not a bare NewObject.
+	// The factory's empty-emitter path initializes a UNiagaraScriptSource +
+	// graph (GraphSource) plus default modules and a sprite renderer - the same
+	// asset the "Niagara Emitter" content-browser action produces. A bare
+	// NewObject'd emitter has GraphSource==nullptr, "succeeds" here, then
+	// crashes the editor the moment it is added to a system. IAssetTools::
+	// CreateAsset runs FactoryCreateNew headlessly (no ConfigureProperties UI),
+	// and the factory defaults (EmitterToCopy=null) select the empty path.
+	UNiagaraEmitterFactoryNew* Factory = NewObject<UNiagaraEmitterFactoryNew>();
+	FGCRootScope FactoryRoot(Factory);
+
+	auto Created = MCPCreateAssetIdempotent<UObject>(Name, PackagePath, OnConflict, TEXT("NiagaraEmitter"), EmitterClass, Factory);
 	if (Created.EarlyReturn) return Created.EarlyReturn;
 
 	UEditorAssetLibrary::SaveAsset(Created.Asset->GetPathName());
@@ -532,6 +544,22 @@ TSharedPtr<FJsonValue> FNiagaraHandlers::SetNiagaraParameter(const TSharedPtr<FJ
 	return MCPResult(Result);
 }
 
+// An emitter is only safely addable to a system when its target version has a
+// GraphSource. A bare NewObject'd UNiagaraEmitter (how create_niagara_emitter
+// used to build them) or any asset left in a broken state has
+// GraphSource==nullptr; passing one to FNiagaraEditorUtilities::AddEmitterToSystem
+// makes Niagara's RebuildEmitterNodes dereference it and hard-crashes the editor
+// (ensure GraphSource != nullptr at NiagaraEmitter.cpp, then an access violation).
+// Every add-path must gate on this instead of trusting the emitter loaded clean.
+static bool EmitterHasGraphSource(UNiagaraEmitter* Emitter, const FGuid& Version)
+{
+	if (!Emitter) return false;
+	const FVersionedNiagaraEmitterData* Data = Version.IsValid()
+		? Emitter->GetEmitterData(Version)
+		: Emitter->GetLatestEmitterData();
+	return Data != nullptr && Data->GraphSource != nullptr;
+}
+
 TSharedPtr<FJsonValue> FNiagaraHandlers::AddEmitterToSystem(const TSharedPtr<FJsonObject>& Params)
 {
 	FString SystemPath;
@@ -591,6 +619,13 @@ TSharedPtr<FJsonValue> FNiagaraHandlers::AddEmitterToSystem(const TSharedPtr<FJs
 	// system's overview graph. This is the same path the editor uses for
 	// "Add Emitter to System" in the Niagara System editor.
 	const FGuid EmitterVersion = Emitter->GetExposedVersion().VersionGuid;
+	// Guard: a GraphSource-less emitter crashes AddEmitterToSystem. Fail cleanly.
+	if (!EmitterHasGraphSource(Emitter, EmitterVersion))
+	{
+		return MCPError(FString::Printf(
+			TEXT("Emitter '%s' has no GraphSource - it was created empty/invalid and cannot be added to a system (adding it would crash the editor). Recreate it with create_niagara_emitter, which now initializes a valid graph."),
+			*EmitterPath));
+	}
 	const FGuid HandleId = FNiagaraEditorUtilities::AddEmitterToSystem(*System, *Emitter, EmitterVersion);
 	if (!HandleId.IsValid())
 	{
@@ -1041,11 +1076,23 @@ TSharedPtr<FJsonValue> FNiagaraHandlers::CreateNiagaraSystemFromSpec(const TShar
 	const TArray<TSharedPtr<FJsonValue>>* EmittersArr = nullptr;
 	Params->TryGetArrayField(TEXT("emitters"), EmittersArr);
 
-	auto Created = MCPCreateAssetIdempotentNewObject<UNiagaraSystem>(Name, PackagePath, OptionalString(Params, TEXT("onConflict"), TEXT("skip")), TEXT("NiagaraSystem"));
+	// Create the system through UNiagaraSystemFactoryNew, not a bare NewObject.
+	// A NewObject'd UNiagaraSystem has no system spawn/update scripts and no
+	// editor data; FNiagaraEditorUtilities::AddEmitterToSystem then dereferences
+	// that missing state and hard-crashes the editor (access violation). The
+	// factory's InitializeSystem sets up the scripts + editor data + default
+	// nodes - the same asset the plain `create` action produces. (Mirrors
+	// CreateNiagaraSystem.)
+	UClass* SystemFactoryClass = FindObject<UClass>(nullptr, TEXT("/Script/NiagaraEditor.NiagaraSystemFactoryNew"));
+	UFactory* SystemFactory = SystemFactoryClass
+		? Cast<UFactory>(NewObject<UObject>(GetTransientPackage(), SystemFactoryClass))
+		: nullptr;
+	auto Created = MCPCreateAssetIdempotent<UNiagaraSystem>(Name, PackagePath, OptionalString(Params, TEXT("onConflict"), TEXT("skip")), TEXT("NiagaraSystem"), SystemFactory);
 	if (Created.EarlyReturn) return Created.EarlyReturn;
 	UNiagaraSystem* System = Created.Asset;
 
 	int32 AddedEmitters = 0;
+	TArray<FString> SkippedEmitters;
 	if (EmittersArr)
 	{
 		for (const TSharedPtr<FJsonValue>& V : *EmittersArr)
@@ -1065,6 +1112,14 @@ TSharedPtr<FJsonValue> FNiagaraHandlers::CreateNiagaraSystemFromSpec(const TShar
 			if (!Source) Source = Cast<UNiagaraEmitter>(UEditorAssetLibrary::LoadAsset(EmitterPath));
 			if (!Source) continue;
 			const FGuid Version = Source->GetExposedVersion().VersionGuid;
+			// Guard: skip GraphSource-less emitters instead of crashing the
+			// editor. Surfaced in the result so the caller knows which ones
+			// failed and can recreate them.
+			if (!EmitterHasGraphSource(Source, Version))
+			{
+				SkippedEmitters.Add(EmitterPath);
+				continue;
+			}
 			// #275: route through FNiagaraEditorUtilities so we get
 			// KillSystemInstances + RebuildEmitterNodes + unique-name
 			// resolution instead of mutating the handle list raw.
@@ -1080,6 +1135,15 @@ TSharedPtr<FJsonValue> FNiagaraHandlers::CreateNiagaraSystemFromSpec(const TShar
 	MCPSetCreated(Res);
 	Res->SetStringField(TEXT("path"), System->GetPathName());
 	Res->SetNumberField(TEXT("emittersAdded"), AddedEmitters);
+	if (SkippedEmitters.Num() > 0)
+	{
+		TArray<TSharedPtr<FJsonValue>> Skipped;
+		for (const FString& S : SkippedEmitters) Skipped.Add(MakeShared<FJsonValueString>(S));
+		Res->SetArrayField(TEXT("skippedEmitters"), Skipped);
+		Res->SetStringField(TEXT("warning"), FString::Printf(
+			TEXT("%d emitter(s) were skipped because they have no GraphSource (created empty/invalid). Recreate them with create_niagara_emitter."),
+			SkippedEmitters.Num()));
+	}
 	MCPSetDeleteAssetRollback(Res, System->GetPathName());
 	return MCPResult(Res);
 }