ultimate-unreal-engine-mcp 0.1.0

package/unreal-plugin/MCPBridge/Source/MCPBridgeEditor/Private/MCPWorldPartitionCommands.h

@@ -0,0 +1,23 @@
+// MCPWorldPartitionCommands.h (Plan 18-01)
+// Declares the registration function for all World Partition MCP command handlers.
+// Handlers: worldpartition.settings, worldpartition.dataLayers,
+//           worldpartition.streamingSources, worldpartition.hlod
+//
+// Call RegisterWorldPartitionCommands(*Router) in MCPBridgeSubsystem::Initialize()
+// BEFORE the TCP server starts accepting connections.
+
+#pragma once
+
+#include "MCPCommandRouter.h"
+
+/**
+ * Register all four World Partition command handlers into the given router.
+ * Must be called on the game thread before connections arrive.
+ *
+ * Registered commands:
+ *   worldpartition.settings        -- read WP grid size, loading range, streaming config (WP-01)
+ *   worldpartition.dataLayers      -- list/create/toggle data layers, assign actors (WP-02)
+ *   worldpartition.streamingSources -- inspect streaming sources with shape, priority, target state (WP-03)
+ *   worldpartition.hlod            -- inspect HLOD layer config and trigger HLOD generation (WP-04)
+ */
+void RegisterWorldPartitionCommands(FMCPCommandRouter& Router);

package/unreal-plugin/MCPBridge/Source/MCPBridgeEditor/Public/MCPBridgeEditor.h

@@ -0,0 +1,14 @@
+// MCPBridgeEditor.h
+// Public header for the MCPBridgeEditor module.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Modules/ModuleManager.h"
+
+class FMCPBridgeEditorModule : public IModuleInterface
+{
+public:
+    virtual void StartupModule() override;
+    virtual void ShutdownModule() override;
+};

package/unreal-plugin/MCPBridge/Source/MCPBridgeRuntime/MCPBridgeRuntime.Build.cs

@@ -0,0 +1,28 @@
+// MCPBridgeRuntime.Build.cs
+// Runtime module: TCP server, JSON framing, command router.
+// IMPORTANT: Do NOT add any editor module dependencies here.
+// Editor-only code lives exclusively in MCPBridgeEditor.
+
+using UnrealBuildTool;
+
+public class MCPBridgeRuntime : ModuleRules
+{
+    public MCPBridgeRuntime(ReadOnlyTargetRules Target) : base(Target)
+    {
+        PCHUsage = ModuleRules.PCHUsageMode.UseExplicitOrSharedPCHs;
+
+        PublicDependencyModuleNames.AddRange(new string[]
+        {
+            "Core",
+        });
+
+        PrivateDependencyModuleNames.AddRange(new string[]
+        {
+            "CoreUObject",
+            "Engine",
+            "Sockets",
+            "Networking",
+            "Json",
+        });
+    }
+}

package/unreal-plugin/MCPBridge/Source/MCPBridgeRuntime/Private/MCPBridgeRuntime.cpp

@@ -0,0 +1,22 @@
+// MCPBridgeRuntime.cpp
+// Startup/shutdown for the Runtime module.
+// TCP server lifecycle is managed by MCPBridgeSubsystem (Editor module).
+
+#include "MCPBridgeRuntime.h"
+
+#define LOCTEXT_NAMESPACE "FMCPBridgeRuntimeModule"
+
+void FMCPBridgeRuntimeModule::StartupModule()
+{
+    // TCP server is started by UMCPBridgeSubsystem::Initialize() in the Editor module.
+    // This module only provides the TCP server class -- it does not start it here.
+}
+
+void FMCPBridgeRuntimeModule::ShutdownModule()
+{
+    // TCP server is stopped by UMCPBridgeSubsystem::Deinitialize().
+}
+
+#undef LOCTEXT_NAMESPACE
+
+IMPLEMENT_MODULE(FMCPBridgeRuntimeModule, MCPBridgeRuntime)

package/unreal-plugin/MCPBridge/Source/MCPBridgeRuntime/Private/MCPCommandRouter.cpp

@@ -0,0 +1,118 @@
+// MCPCommandRouter.cpp
+// Implementation of FMCPCommandRouter.
+// All handler dispatches go through AsyncTask(ENamedThreads::GameThread) to protect
+// UE editor API calls from being invoked on a background network-receive thread.
+
+#include "MCPCommandRouter.h"
+#include "Serialization/JsonSerializer.h"
+#include "Serialization/JsonWriter.h"
+#include "Dom/JsonObject.h"
+#include "Async/Async.h"
+
+FMCPCommandRouter::FMCPCommandRouter()
+{
+	// Register built-in ping handler.
+	// ping validates the full round-trip: TypeScript -> TCP -> C++ -> AsyncTask -> response.
+	RegisterHandler(TEXT("ping"), [](TSharedPtr<FJsonObject> Cmd, FMCPResponseSender SendResponse)
+	{
+		// This lambda runs on the game thread (dispatched by Dispatch() below).
+		const FString CorrelationId = Cmd.IsValid() ? Cmd->GetStringField(TEXT("correlationId")) : TEXT("");
+
+		TSharedPtr<FJsonObject> Data = MakeShared<FJsonObject>();
+		Data->SetBoolField(TEXT("pong"), true);
+
+		TSharedPtr<FJsonObject> Response = MakeShared<FJsonObject>();
+		Response->SetBoolField(TEXT("success"), true);
+		if (!CorrelationId.IsEmpty())
+		{
+			Response->SetStringField(TEXT("correlationId"), CorrelationId);
+		}
+		Response->SetObjectField(TEXT("data"), Data);
+
+		FString Output;
+		TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&Output);
+		FJsonSerializer::Serialize(Response.ToSharedRef(), Writer);
+		Output += TEXT("\n");
+		SendResponse(Output);
+	});
+}
+
+void FMCPCommandRouter::RegisterHandler(const FString& CommandType, FMCPCommandHandler Handler)
+{
+	Handlers.Add(CommandType, MoveTemp(Handler));
+}
+
+void FMCPCommandRouter::Dispatch(const FString& RawMessage, FMCPResponseSender SendResponse) const
+{
+	// Parse the incoming JSON.
+	TSharedPtr<FJsonObject> JsonObj;
+	TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(RawMessage);
+	if (!FJsonSerializer::Deserialize(Reader, JsonObj) || !JsonObj.IsValid())
+	{
+		// T-07-04: malformed JSON must not crash -- return structured error.
+		SendResponse(BuildErrorResponse(TEXT(""), TEXT("invalid_json")) + TEXT("\n"));
+		return;
+	}
+
+	FString CorrelationId;
+	JsonObj->TryGetStringField(TEXT("correlationId"), CorrelationId);
+
+	FString CommandType;
+	if (!JsonObj->TryGetStringField(TEXT("type"), CommandType) || CommandType.IsEmpty())
+	{
+		SendResponse(BuildErrorResponse(CorrelationId, TEXT("missing_type")) + TEXT("\n"));
+		return;
+	}
+
+	const FMCPCommandHandler* HandlerPtr = Handlers.Find(CommandType);
+	if (!HandlerPtr)
+	{
+		SendResponse(BuildErrorResponse(CorrelationId, TEXT("unknown_command")) + TEXT("\n"));
+		return;
+	}
+
+	// Capture handler and response sender by value -- safe across async boundary.
+	FMCPCommandHandler Handler = *HandlerPtr;
+
+	// All UE API calls must run on the game thread (Pitfall 2: game-thread assertions).
+	// This wrapping is applied universally -- handlers must never call UE APIs directly
+	// from a background thread.
+	AsyncTask(ENamedThreads::GameThread, [Handler, JsonObj, SendResponse, CorrelationId]()
+	{
+		// Inject correlationId back into JsonObj so handlers can read it if needed.
+		JsonObj->SetStringField(TEXT("correlationId"), CorrelationId);
+		Handler(JsonObj, SendResponse);
+	});
+}
+
+FString FMCPCommandRouter::BuildErrorResponse(const FString& CorrelationId, const FString& Error)
+{
+	TSharedPtr<FJsonObject> Obj = MakeShared<FJsonObject>();
+	Obj->SetBoolField(TEXT("success"), false);
+	if (!CorrelationId.IsEmpty())
+	{
+		Obj->SetStringField(TEXT("correlationId"), CorrelationId);
+	}
+	Obj->SetStringField(TEXT("error"), Error);
+
+	FString Output;
+	TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&Output);
+	FJsonSerializer::Serialize(Obj.ToSharedRef(), Writer);
+	return Output;
+}
+
+FString FMCPCommandRouter::BuildSuccessResponse(const FString& CorrelationId, TSharedPtr<FJsonObject> Data)
+{
+	TSharedPtr<FJsonObject> Obj = MakeShared<FJsonObject>();
+	Obj->SetBoolField(TEXT("success"), true);
+	Obj->SetStringField(TEXT("correlationId"), CorrelationId);
+	if (Data.IsValid())
+	{
+		Obj->SetObjectField(TEXT("data"), Data);
+	}
+
+	FString Output;
+	TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&Output);
+	FJsonSerializer::Serialize(Obj.ToSharedRef(), Writer);
+	return Output;
+}

package/unreal-plugin/MCPBridge/Source/MCPBridgeRuntime/Private/MCPTcpServer.cpp

@@ -0,0 +1,196 @@
+// MCPTcpServer.cpp
+// TCP server implementation for MCPBridge.
+// Binds exclusively to 127.0.0.1 (FIPv4Address::InternalLoopback).
+// Ticks at 20 Hz via FTSTicker to accept connections and read data without
+// blocking the game thread.
+
+#include "MCPTcpServer.h"
+#include "SocketSubsystem.h"
+#include "Common/TcpSocketBuilder.h"
+#include "Interfaces/IPv4/IPv4Address.h"
+#include "Interfaces/IPv4/IPv4Endpoint.h"
+
+FMCPTcpServer::FMCPTcpServer(FMCPCommandRouter& InRouter)
+	: Router(InRouter)
+{
+}
+
+FMCPTcpServer::~FMCPTcpServer()
+{
+	Stop();
+}
+
+bool FMCPTcpServer::Start(int32 Port)
+{
+	// Bind to loopback only -- never 0.0.0.0 (CONTEXT.md security constraint).
+	FIPv4Endpoint Endpoint(FIPv4Address::InternalLoopback, static_cast<uint16>(Port));
+
+	ListenerSocket = FTcpSocketBuilder(TEXT("MCPBridge.Listener"))
+		.AsReusable()
+		.BoundToEndpoint(Endpoint)
+		.Listening(8)
+		.Build();
+
+	if (!ListenerSocket)
+	{
+		UE_LOG(LogTemp, Error, TEXT("[MCPBridge] Failed to bind TCP listener on 127.0.0.1:%d"), Port);
+		return false;
+	}
+
+	ListenerSocket->SetNonBlocking(true);
+	bRunning = true;
+
+	// 20 Hz tick -- low overhead, <50ms latency for interactive editor commands.
+	TickerHandle = FTSTicker::GetCoreTicker().AddTicker(
+		FTickerDelegate::CreateRaw(this, &FMCPTcpServer::Tick), 0.05f);
+
+	UE_LOG(LogTemp, Log, TEXT("[MCPBridge] TCP server listening on 127.0.0.1:%d"), Port);
+	return true;
+}
+
+void FMCPTcpServer::Stop()
+{
+	if (!bRunning)
+	{
+		return;
+	}
+	bRunning = false;
+
+	if (TickerHandle.IsValid())
+	{
+		FTSTicker::GetCoreTicker().RemoveTicker(TickerHandle);
+		TickerHandle.Reset();
+	}
+
+	ISocketSubsystem* SocketSS = ISocketSubsystem::Get(PLATFORM_SOCKETSUBSYSTEM);
+
+	for (FMCPClientState& Client : Clients)
+	{
+		if (Client.Socket)
+		{
+			Client.Socket->Close();
+			SocketSS->DestroySocket(Client.Socket);
+		}
+	}
+	Clients.Empty();
+
+	if (ListenerSocket)
+	{
+		ListenerSocket->Close();
+		SocketSS->DestroySocket(ListenerSocket);
+		ListenerSocket = nullptr;
+	}
+
+	UE_LOG(LogTemp, Log, TEXT("[MCPBridge] TCP server stopped."));
+}
+
+bool FMCPTcpServer::Tick(float /*DeltaTime*/)
+{
+	if (!bRunning)
+	{
+		return false;  // Remove ticker
+	}
+	AcceptConnections();
+	ReadClients();
+	return true;  // Keep ticking
+}
+
+void FMCPTcpServer::AcceptConnections()
+{
+	if (!ListenerSocket)
+	{
+		return;
+	}
+
+	bool bHasPendingConnection = false;
+	while (ListenerSocket->HasPendingConnection(bHasPendingConnection) && bHasPendingConnection)
+	{
+		FSocket* ClientSocket = ListenerSocket->Accept(TEXT("MCPBridge.Client"));
+		if (ClientSocket)
+		{
+			ClientSocket->SetNonBlocking(true);
+			FMCPClientState State;
+			State.Socket = ClientSocket;
+			Clients.Add(MoveTemp(State));
+			UE_LOG(LogTemp, Log, TEXT("[MCPBridge] Client connected."));
+		}
+	}
+}
+
+void FMCPTcpServer::ReadClients()
+{
+	ISocketSubsystem* SocketSS = ISocketSubsystem::Get(PLATFORM_SOCKETSUBSYSTEM);
+
+	for (int32 i = Clients.Num() - 1; i >= 0; --i)
+	{
+		FMCPClientState& Client = Clients[i];
+
+		if (!Client.Socket || Client.Socket->GetConnectionState() != SCS_Connected)
+		{
+			// Clean up disconnected client.
+			if (Client.Socket)
+			{
+				Client.Socket->Close();
+				SocketSS->DestroySocket(Client.Socket);
+				Client.Socket = nullptr;
+			}
+			Clients.RemoveAt(i);
+			UE_LOG(LogTemp, Log, TEXT("[MCPBridge] Client disconnected."));
+			continue;
+		}
+
+		uint32 PendingSize = 0;
+		while (Client.Socket->HasPendingData(PendingSize) && PendingSize > 0)
+		{
+			TArray<uint8> Buffer;
+			Buffer.SetNumUninitialized(PendingSize);
+			int32 BytesRead = 0;
+			if (!Client.Socket->Recv(Buffer.GetData(), Buffer.Num(), BytesRead) || BytesRead <= 0)
+			{
+				break;
+			}
+
+			// Null-terminate and convert UTF-8 bytes to TCHAR string.
+			Buffer.Add(0);
+			FUTF8ToTCHAR Converter(reinterpret_cast<const ANSICHAR*>(Buffer.GetData()), BytesRead);
+			Client.ReceiveBuffer.Append(Converter.Get(), Converter.Length());
+
+			// Process all complete lines (delimited by \n).
+			int32 NewlinePos;
+			while (Client.ReceiveBuffer.FindChar(TEXT('\n'), NewlinePos))
+			{
+				FString Message = Client.ReceiveBuffer.Left(NewlinePos).TrimEnd();
+				Client.ReceiveBuffer.RightChopInline(NewlinePos + 1);
+
+				if (!Message.IsEmpty())
+				{
+					// Capture socket pointer for response callback.
+					// Router.Dispatch() dispatches the handler to the game thread via AsyncTask.
+					// The SendResponse lambda captures Sock -- valid because clients are only
+					// destroyed on the next tick after disconnect detection.
+					FSocket* Sock = Client.Socket;
+					Router.Dispatch(Message, [this, Sock](const FString& Response)
+					{
+						SendResponse(Sock, Response);
+					});
+				}
+			}
+		}
+	}
+}
+
+void FMCPTcpServer::SendResponse(FSocket* ClientSocket, const FString& Response)
+{
+	if (!ClientSocket || Response.IsEmpty())
+	{
+		return;
+	}
+
+	// Convert TCHAR string to UTF-8 bytes for sending over the wire.
+	FTCHARToUTF8 Converter(*Response);
+	const uint8* Data = reinterpret_cast<const uint8*>(Converter.Get());
+	int32 Size = Converter.Length();
+	int32 BytesSent = 0;
+
+	ClientSocket->Send(Data, Size, BytesSent);
+}

package/unreal-plugin/MCPBridge/Source/MCPBridgeRuntime/Public/MCPBridgeRuntime.h

@@ -0,0 +1,15 @@
+// MCPBridgeRuntime.h
+// Public header for the MCPBridgeRuntime module.
+// Exposes the module interface and the TCP server singleton.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Modules/ModuleManager.h"
+
+class MCPBRIDGERUNTIME_API FMCPBridgeRuntimeModule : public IModuleInterface
+{
+public:
+    virtual void StartupModule() override;
+    virtual void ShutdownModule() override;
+};

package/unreal-plugin/MCPBridge/Source/MCPBridgeRuntime/Public/MCPCommandRouter.h

@@ -0,0 +1,55 @@
+// MCPCommandRouter.h
+// Routes incoming JSON-newline commands to registered handlers.
+// ALL handler invocations are dispatched via AsyncTask(ENamedThreads::GameThread).
+// This is non-retrofittable -- establish this pattern before any real handlers exist.
+//
+// Usage (from Phases 8-12):
+//   Router.RegisterHandler(TEXT("get_actors"), [](TSharedPtr<FJsonObject> Cmd,
+//       FMCPResponseSender Send) { /* editor API call -- runs on game thread */ });
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "Dom/JsonObject.h"
+
+/** Callback type for sending a JSON response back to the connected client. */
+using FMCPResponseSender = TFunction<void(const FString& JsonResponse)>;
+
+/**
+ * Handler signature: receives parsed command object, sends response via SendResponse.
+ * Guaranteed to run on the game thread -- safe to call any UE editor API.
+ */
+using FMCPCommandHandler = TFunction<void(TSharedPtr<FJsonObject> Command, FMCPResponseSender SendResponse)>;
+
+class MCPBRIDGERUNTIME_API FMCPCommandRouter
+{
+public:
+	FMCPCommandRouter();
+
+	/**
+	 * Register a handler for a command type.
+	 * Call this during plugin initialization (before any connections arrive).
+	 * Not thread-safe after the server is accepting connections.
+	 */
+	void RegisterHandler(const FString& CommandType, FMCPCommandHandler Handler);
+
+	/**
+	 * Dispatch an incoming JSON-newline message.
+	 * Parses JSON, looks up handler, dispatches on game thread via AsyncTask.
+	 * If no handler registered, sends {success:false, error:"unknown_command"}.
+	 * SendResponse is guaranteed to be called exactly once per Dispatch call.
+	 *
+	 * @param RawMessage  Raw JSON string (without trailing newline).
+	 * @param SendResponse Callback to send the JSON response back to the client.
+	 */
+	void Dispatch(const FString& RawMessage, FMCPResponseSender SendResponse) const;
+
+private:
+	/** Builds a JSON error response with the given correlationId and error string. */
+	static FString BuildErrorResponse(const FString& CorrelationId, const FString& Error);
+
+	/** Builds a JSON success response with the given correlationId and data object. */
+	static FString BuildSuccessResponse(const FString& CorrelationId, TSharedPtr<FJsonObject> Data);
+
+	TMap<FString, FMCPCommandHandler> Handlers;
+};

package/unreal-plugin/MCPBridge/Source/MCPBridgeRuntime/Public/MCPTcpServer.h

@@ -0,0 +1,59 @@
+// MCPTcpServer.h
+// FSocket-based TCP server for the MCP bridge.
+// Binds to 127.0.0.1:PORT (NEVER 0.0.0.0 -- see CONTEXT.md security constraint).
+// Uses FTSTicker for non-blocking periodic accept/read at 20 Hz.
+// Each message is one JSON object terminated by \n (JSON-newline framing).
+//
+// Per-client receive state is held in FMCPClientState to handle partial reads.
+
+#pragma once
+
+#include "CoreMinimal.h"
+#include "MCPCommandRouter.h"
+#include "Sockets.h"
+#include "Containers/Ticker.h"
+
+/**
+ * Holds per-connection state: socket handle + partial receive buffer.
+ */
+struct FMCPClientState
+{
+	FSocket* Socket = nullptr;
+	FString  ReceiveBuffer;  // accumulates bytes until \n is found
+};
+
+/**
+ * TCP server bound to 127.0.0.1:PORT.
+ * Owns the listener socket, all client sockets, and the ticker.
+ */
+class MCPBRIDGERUNTIME_API FMCPTcpServer
+{
+public:
+	explicit FMCPTcpServer(FMCPCommandRouter& InRouter);
+	~FMCPTcpServer();
+
+	/** Bind listener socket and start the FTSTicker. Returns false on bind failure. */
+	bool Start(int32 Port);
+
+	/** Close all client sockets, listener socket, and remove the ticker. */
+	void Stop();
+
+private:
+	/** Called at 20 Hz by FTSTicker. Accepts new connections and reads pending data. */
+	bool Tick(float DeltaTime);
+
+	/** Accept any pending new connections from the listener socket. */
+	void AcceptConnections();
+
+	/** Read all pending data from each connected client, dispatch complete messages. */
+	void ReadClients();
+
+	/** Send a JSON-newline response to a specific client socket. */
+	void SendResponse(FSocket* ClientSocket, const FString& Response);
+
+	FMCPCommandRouter&         Router;
+	FSocket*                   ListenerSocket = nullptr;
+	TArray<FMCPClientState>    Clients;
+	FTSTicker::FDelegateHandle TickerHandle;
+	bool                       bRunning = false;
+};