@uemcp/server 1.5.0 → 1.6.0

package/dist/index.mjs

@@ -153,10 +153,13 @@ const projectIdSchema = z.string().trim().transform((value) => {
 	return HYPHENATED_PROJECT_ID_PATTERN.test(normalizedValue) ? normalizedValue.replaceAll("-", "") : normalizedValue;
 }).refine((value) => UNREAL_PROJECT_ID_PATTERN.test(value), "Expected a 32-character Unreal ProjectID");
 const upsertProjectRequestSchema = z.object({
+	engineVersion: z.string().trim().min(1).optional(),
+	pid: z.number().int().min(1),
+	pluginVersion: z.string().trim().min(1).optional(),
+	port: z.number().int().min(1).max(65535),
 	projectName: z.string().trim().min(1),
 	projectPath: z.string().trim().min(1),
-	port: z.number().int().min(1).max(65535),
-	pid: z.number().int().min(1)
+	protocolVersion: z.number().int().min(1).optional()
 });
 const projectParamsSchema = z.object({ projectId: projectIdSchema });
 const mcpPingResponseSchema = z.object({ pong: z.literal(true) });
@@ -8140,6 +8143,9 @@ function createBridgeSetDefaultGamemodeRequest(scope, gameModePath, options = {}
 	});
 }
 //#endregion
+//#region src/version.ts
+const SERVER_VERSION = "1.6.0";
+//#endregion
 //#region src/bridgeSocketClient.ts
 var BridgeSocketError = class extends Error {
 	code;
@@ -8149,6 +8155,18 @@ var BridgeSocketError = class extends Error {
 		this.name = new.target.name;
 	}
 };
+var BridgeProtocolVersionMismatchError = class extends BridgeSocketError {
+	pluginProtocolVersion;
+	serverProtocolVersion = 2;
+	constructor(pluginProtocolVersion, options) {
+		super("protocol_version_mismatch", describeProtocolVersionMismatch(pluginProtocolVersion), options);
+		this.pluginProtocolVersion = pluginProtocolVersion;
+	}
+};
+function describeProtocolVersionMismatch(pluginProtocolVersion) {
+	const remedy = pluginProtocolVersion < 2 ? `Update the MCPBridge plugin in this Unreal project to a release that speaks bridge protocol v${String(2)}.` : `Update the MCP server (npx -y @uemcp/server@latest) to a release that speaks bridge protocol v${String(pluginProtocolVersion)}.`;
+	return `Plugin/server version skew: the MCPBridge plugin speaks bridge protocol v${String(pluginProtocolVersion)}, but MCP server ${SERVER_VERSION} speaks v${String(2)}. ${remedy}`;
+}
 async function sendBridgePingRequest(request, options) {
 	return parseBridgeResponse(await exchangeBridgeMessage(encodeBridgeFrame(request), options), bridgePingResponseSchema, request.requestId);
 }
@@ -8456,6 +8474,8 @@ function encodeBridgeFrame(payload) {
 }
 function parseBridgeResponse(responsePayload, schema, expectedRequestId) {
 	const parsedResponse = parseBridgePayload(responsePayload);
+	const pluginProtocolVersion = readForeignProtocolVersion(parsedResponse);
+	if (pluginProtocolVersion !== null) throw new BridgeProtocolVersionMismatchError(pluginProtocolVersion);
 	const parsed = schema.safeParse(parsedResponse);
 	const payloadBytes = Buffer.byteLength(responsePayload, "utf8");
 	if (!parsed.success) throw new BridgeSocketError("invalid_response", `Bridge response did not match schema: ${parsed.error.message}. Payload bytes: ${String(payloadBytes)}.`, { cause: parsed.error });
@@ -8651,6 +8671,12 @@ var BridgeSessionClient = class {
 		});
 	}
 };
+function readForeignProtocolVersion(payload) {
+	if (typeof payload !== "object" || payload === null || !("version" in payload)) return null;
+	const { version } = payload;
+	if (typeof version !== "number" || !Number.isInteger(version) || version === 2) return null;
+	return version;
+}
 function parseBridgePayload(responsePayload) {
 	try {
 		return JSON.parse(responsePayload);
@@ -8997,9 +9023,24 @@ async function pingRegistryEntry$1(entry, options) {
 		};
 		return {
 			alive: true,
-			lastSeenAt: /* @__PURE__ */ new Date()
+			lastSeenAt: /* @__PURE__ */ new Date(),
+			pluginProtocolVersion: responseBody.version
 		};
 	} catch (error) {
+		if (error instanceof BridgeProtocolVersionMismatchError) {
+			options.logger.warn({
+				pluginProtocolVersion: error.pluginProtocolVersion,
+				port: entry.port,
+				projectId: entry.projectId,
+				serverProtocolVersion: error.serverProtocolVersion
+			}, "Engine ping found a plugin/server protocol version mismatch");
+			return {
+				alive: true,
+				lastSeenAt: /* @__PURE__ */ new Date(),
+				pluginProtocolVersion: error.pluginProtocolVersion,
+				reason: error.message
+			};
+		}
 		options.logger.warn({
 			error,
 			port: entry.port,
@@ -9111,12 +9152,21 @@ function createHttpApi(options) {
 			projectPath: entry.projectPath
 		}, "Project registration changed path for an existing projectId");
 		options.logger.info({
+			engineVersion: parsedBody.data.engineVersion,
 			pid: entry.pid,
+			pluginVersion: parsedBody.data.pluginVersion,
 			port: entry.port,
 			projectId: entry.projectId,
 			projectName: entry.projectName,
-			projectPath: entry.projectPath
+			projectPath: entry.projectPath,
+			protocolVersion: parsedBody.data.protocolVersion
 		}, "Upserted Unreal Editor project registration");
+		if (parsedBody.data.protocolVersion !== void 0 && parsedBody.data.protocolVersion !== 2) options.logger.warn({
+			pluginProtocolVersion: parsedBody.data.protocolVersion,
+			pluginVersion: parsedBody.data.pluginVersion,
+			projectId: entry.projectId,
+			serverProtocolVersion: 2
+		}, "Registered Unreal Editor speaks a different bridge protocol version; its bridge calls will fail");
 		notifyRegistryChanged();
 		return {
 			projectId: entry.projectId,
@@ -10184,7 +10234,7 @@ function buildDiagnoseBridgeDisconnectPrompt(args) {
 		"",
 		`1. Read ${REGISTRY_RESOURCE_URI}. No entry at all means registration never landed or was evicted. An entry with a stale lastSeenAt means registration landed but health checks are failing.`,
 		projectPathStep,
-		"3. Call ping_project with the registered projectId. reachable: false with registrationRemoved: true means the editor’s TCP listener is gone — the editor died, or the plugin lost its port. Note that this call evicts a stale registration, so read the registry resource before calling it, not after.",
+		"3. Call ping_project with the registered projectId. reachable: false with registrationRemoved: true means the editor’s TCP listener is gone — the editor died, or the plugin lost its port. Note that this call evicts a stale registration, so read the registry resource before calling it, not after. reachable: true with compatible: false is version skew, not a disconnect: the plugin and server speak different bridge protocol versions, reason names which one to update, and no other tool will work until they match.",
 		"4. If the registration looks healthy but one specific tool fails, call stream_output_log and drain with the returned cursor. Plugin-side faults are logged under the LogMCPBridgeRuntime category: failures resolving the ProjectID, failures binding the bridge socket, and rejected registrations all name themselves there.",
 		"",
 		"Common causes, in rough order of likelihood: the editor was closed or crashed and the registration is stale; the editor is open on a different project than the one being asked about; the project directory was copied, so two directories share one ProjectID and fight over one registration; the plugin is pointed at a different server address.",
@@ -12017,7 +12067,7 @@ function registerMcpTools(server, dependencies) {
 		}, dependencies));
 	});
 	server.registerTool("ping_project", {
-		description: "Ping the registered Unreal engine bridge for a projectId and evict stale registrations after retries.",
+		description: "Ping the registered Unreal engine bridge for a projectId and evict stale registrations after retries. Reports the plugin, engine and server versions; compatible: false means the plugin and server speak different bridge protocol versions, and reason names which one to update.",
 		inputSchema: pingProjectInputSchema,
 		title: "Ping Project"
 	}, async ({ projectId }) => {
@@ -15356,7 +15406,8 @@ async function pingProject(projectId, dependencies) {
 			projectId: normalizedProjectId,
 			reason: "Registration was removed while ping_project was running.",
 			reachable: false,
-			registrationRemoved: false
+			registrationRemoved: false,
+			versions: buildPingProjectVersions(startedEntry)
 		};
 		attemptsUsed = retryIndex + 1;
 		const pingResult = await pingRegistryEntry$1(currentEntry, {
@@ -15379,12 +15430,18 @@ async function pingProject(projectId, dependencies) {
 					projectId: currentEntry.projectId
 				}, "Failed to persist registry snapshot after successful ping_project");
 			}
-			return {
+			const versions = buildPingProjectVersions(currentEntry, pingResult.pluginProtocolVersion);
+			const compatible = versions.pluginProtocolVersion === 2;
+			const result = {
 				attemptsUsed,
+				compatible,
 				projectId: currentEntry.projectId,
 				reachable: true,
-				registrationRemoved: false
+				registrationRemoved: false,
+				versions
 			};
+			if (!compatible && pingResult.reason !== void 0) result.reason = pingResult.reason;
+			return result;
 		}
 		lastFailureReason = pingResult.reason ?? "Unknown ping failure.";
 		if (retryIndex < 3) await sleep(getPingRetryDelayMs(retryIndex));
@@ -15401,7 +15458,8 @@ async function pingProject(projectId, dependencies) {
 			projectId: normalizedProjectId,
 			reason: lastFailureReason,
 			reachable: false,
-			registrationRemoved: false
+			registrationRemoved: false,
+			versions: buildPingProjectVersions(startedEntry)
 		};
 	}
 	const removalResult = await runQueuedRegistryWrite(dependencies, async () => {
@@ -15441,7 +15499,8 @@ async function pingProject(projectId, dependencies) {
 			projectId: normalizedProjectId,
 			reason: lastFailureReason,
 			reachable: false,
-			registrationRemoved: false
+			registrationRemoved: false,
+			versions: buildPingProjectVersions(startedEntry)
 		};
 	}
 	dependencies.logger.warn({
@@ -15454,9 +15513,21 @@ async function pingProject(projectId, dependencies) {
 		projectId: currentEntry.projectId,
 		reason: lastFailureReason,
 		reachable: false,
-		registrationRemoved: true
+		registrationRemoved: true,
+		versions: buildPingProjectVersions(currentEntry)
 	};
 }
+function buildPingProjectVersions(entry, observedPluginProtocolVersion) {
+	const versions = {
+		serverProtocolVersion: 2,
+		serverVersion: SERVER_VERSION
+	};
+	const pluginProtocolVersion = observedPluginProtocolVersion ?? entry.protocolVersion;
+	if (pluginProtocolVersion !== void 0) versions.pluginProtocolVersion = pluginProtocolVersion;
+	if (entry.pluginVersion !== void 0) versions.pluginVersion = entry.pluginVersion;
+	if (entry.engineVersion !== void 0) versions.engineVersion = entry.engineVersion;
+	return versions;
+}
 async function listRegisteredProjects(input, dependencies) {
 	const maxResults = input.maxResults ?? 50;
 	const entries = dependencies.registry.snapshot().sort(compareRegistryEntries);
@@ -15487,10 +15558,17 @@ async function verifyRegisteredProjects(entries, dependencies) {
 				timeoutMs: dependencies.pingTimeoutMs
 			}), budgetExpiry]);
 			const summary = toRegisteredProjectSummary(entry);
-			if (pingResult.alive) return {
-				...summary,
-				reachable: true
-			};
+			if (pingResult.alive) {
+				if (pingResult.pluginProtocolVersion !== void 0 && pingResult.reason !== void 0) return {
+					...summary,
+					reachable: true,
+					reason: pingResult.reason
+				};
+				return {
+					...summary,
+					reachable: true
+				};
+			}
 			return {
 				...summary,
 				reachable: false,
@@ -15502,7 +15580,7 @@ async function verifyRegisteredProjects(entries, dependencies) {
 	}
 }
 function toRegisteredProjectSummary(entry) {
-	return {
+	const summary = {
 		host: BRIDGE_LOOPBACK_HOST,
 		lastSeenAt: entry.lastSeenAt,
 		pid: entry.pid,
@@ -15512,6 +15590,10 @@ function toRegisteredProjectSummary(entry) {
 		projectPath: entry.projectPath,
 		registeredAt: entry.registeredAt
 	};
+	if (entry.pluginVersion !== void 0) summary.pluginVersion = entry.pluginVersion;
+	if (entry.engineVersion !== void 0) summary.engineVersion = entry.engineVersion;
+	if (entry.protocolVersion !== void 0) summary.protocolVersion = entry.protocolVersion;
+	return summary;
 }
 function compareRegistryEntries(left, right) {
 	if (left.projectName !== right.projectName) return left.projectName < right.projectName ? -1 : 1;
@@ -17744,7 +17826,6 @@ function isMissingFileError(error) {
 //#endregion
 //#region src/server.ts
 const SERVER_NAME = "ue-mcp-server";
-const SERVER_VERSION = "1.5.0";
 const logger = createModuleLogger("bootstrap");
 const enginePingLogger = createModuleLogger("engine-ping");
 const httpApiLogger = createModuleLogger("http-api");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uemcp/server",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "MCP server for making Unreal Engine and C++ development easier",
   "type": "module",
   "main": "dist/index.mjs",