@akiojin/unity-mcp-server 4.0.0 → 4.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "4.0.0",
+  "version": "4.1.2",
   "description": "MCP server and Unity Editor bridge — enables AI assistants to control Unity for AI-assisted workflows",
   "type": "module",
   "main": "src/core/server.js",

package/src/core/config.js

@@ -115,6 +115,12 @@ const baseConfig = {
     description: 'MCP server for Unity Editor integration'
   },
 
+  // Compatibility / safety checks
+  compat: {
+    // warn|error|off
+    versionMismatch: 'warn'
+  },
+
   // Logging settings
   logging: {
     level: 'info',
@@ -171,6 +177,7 @@ function loadEnvConfig() {
   const projectRoot = envString('UNITY_PROJECT_ROOT');
 
   const logLevel = envString('UNITY_MCP_LOG_LEVEL');
+  const versionMismatch = envString('UNITY_MCP_VERSION_MISMATCH');
 
   const httpEnabled = parseBoolEnv(process.env.UNITY_MCP_HTTP_ENABLED);
   const httpPort = parseIntEnv(process.env.UNITY_MCP_HTTP_PORT);
@@ -197,6 +204,10 @@ function loadEnvConfig() {
     out.logging = { level: logLevel };
   }
 
+  if (versionMismatch) {
+    out.compat = { versionMismatch };
+  }
+
   if (httpEnabled !== undefined || httpPort !== undefined) {
     out.http = {};
     if (httpEnabled !== undefined) out.http.enabled = httpEnabled;
@@ -247,6 +258,22 @@ function validateAndNormalizeConfig(cfg) {
     }
   }
 
+  // compat.versionMismatch
+  if (cfg.compat?.versionMismatch) {
+    const raw = String(cfg.compat.versionMismatch).trim().toLowerCase();
+    const normalized =
+      raw === 'warning' ? 'warn' : raw === 'none' || raw === 'ignore' ? 'off' : raw;
+    const allowed = new Set(['warn', 'error', 'off']);
+    if (!allowed.has(normalized)) {
+      console.error(
+        `[unity-mcp-server] WARN: Invalid UNITY_MCP_VERSION_MISMATCH (${cfg.compat.versionMismatch}); using default warn`
+      );
+      cfg.compat.versionMismatch = 'warn';
+    } else {
+      cfg.compat.versionMismatch = normalized;
+    }
+  }
+
   // unity hosts
   if (typeof cfg.unity.unityHost !== 'string' || cfg.unity.unityHost.trim() === '') {
     cfg.unity.unityHost = 'localhost';

package/src/core/projectInfo.js

@@ -18,17 +18,32 @@ const looksLikeUnityProjectRoot = dir => {
 };
 
 const inferUnityProjectRootFromDir = startDir => {
+  // First, search immediate child directories (1 level deep)
+  try {
+    const entries = fs.readdirSync(startDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      // Skip hidden directories and common non-project directories
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const childDir = path.join(startDir, entry.name);
+      if (looksLikeUnityProjectRoot(childDir)) return childDir;
+    }
+  } catch {
+    // Fall through to upward search
+  }
+  // If not found in children, walk up to find a Unity project
   try {
     let dir = startDir;
     const { root } = path.parse(dir);
     while (true) {
       if (looksLikeUnityProjectRoot(dir)) return dir;
-      if (dir === root) return null;
+      if (dir === root) break;
       dir = path.dirname(dir);
     }
   } catch {
-    return null;
+    // Ignore errors (e.g., permission denied)
   }
+  return null;
 };
 
 const resolveDefaultCodeIndexRoot = projectRoot => {

package/src/core/unityConnection.js

@@ -23,6 +23,11 @@ export class UnityConnection extends EventEmitter {
     this.maxInFlight = 1; // process one command at a time by default
     this.connectedAt = null; // Timestamp when connection was established
     this.hasConnectedOnce = false;
+
+    // Version compatibility between Node package and Unity package
+    this._versionCompatibilityChecked = false;
+    this._unityPackageVersion = null;
+    this._versionMismatchError = null;
   }
 
   /**
@@ -360,6 +365,10 @@ export class UnityConnection extends EventEmitter {
    * @returns {Promise<any>} - Response from Unity
    */
   async sendCommand(type, params = {}) {
+    if (this._versionMismatchError) {
+      throw this._versionMismatchError;
+    }
+
     logger.info(`[Unity] enqueue sendCommand: ${type}`, { connected: this.connected });
 
     if (!this.connected) {
@@ -380,6 +389,18 @@ export class UnityConnection extends EventEmitter {
   _pumpQueue() {
     if (!this.connected) return;
     if (this.inFlight >= this.maxInFlight) return;
+
+    if (this._versionMismatchError) {
+      const err = this._versionMismatchError;
+      while (this.sendQueue.length) {
+        const task = this.sendQueue.shift();
+        try {
+          task.outerReject(err);
+        } catch {}
+      }
+      return;
+    }
+
     const task = this.sendQueue.shift();
     if (!task) return;
 
@@ -447,6 +468,8 @@ export class UnityConnection extends EventEmitter {
       `[Unity] Parsed response id=${response?.id || 'n/a'} status=${response?.status || (response?.success === false ? 'error' : 'success')}`
     );
 
+    this._checkVersionCompatibility(response);
+
     const id = response?.id != null ? String(response.id) : null;
 
     const hasExplicitPending = id && this.pendingCommands.has(id);
@@ -470,10 +493,15 @@ export class UnityConnection extends EventEmitter {
             logger.warning(`[Unity] Failed to parse result as JSON: ${parseError.message}`);
           }
         }
-        if (response.version) result._version = response.version;
+        const responseVersion = response?.version || response?.editorState?.version;
+        if (responseVersion && result._version == null) result._version = responseVersion;
         if (response.editorState) result._editorState = response.editorState;
-        logger.info(`[Unity] Command ${targetId} resolved successfully`);
-        pending.resolve(result);
+        if (this._versionMismatchError) {
+          pending.reject(this._versionMismatchError);
+        } else {
+          logger.info(`[Unity] Command ${targetId} resolved successfully`);
+          pending.resolve(result);
+        }
       } else if (response.status === 'error' || response.success === false) {
         logger.error(`[Unity] Command ${targetId} failed:`, response.error);
         const err = new Error(response.error || 'Command failed');
@@ -491,6 +519,47 @@ export class UnityConnection extends EventEmitter {
     this.emit('message', response);
   }
 
+  _checkVersionCompatibility(response) {
+    if (this._versionCompatibilityChecked) return;
+
+    const policy = String(config?.compat?.versionMismatch || 'warn')
+      .trim()
+      .toLowerCase();
+    if (policy === 'off') {
+      this._versionCompatibilityChecked = true;
+      return;
+    }
+
+    const unityVersionRaw = response?.version ?? response?.editorState?.version;
+    if (typeof unityVersionRaw !== 'string') return;
+    const unityVersion = unityVersionRaw.trim();
+    if (!unityVersion || unityVersion.toLowerCase() === 'unknown') return;
+
+    const nodeVersion = String(config?.server?.version || '').trim();
+    if (!nodeVersion || nodeVersion.toLowerCase() === 'unknown') {
+      this._versionCompatibilityChecked = true;
+      return;
+    }
+
+    this._unityPackageVersion = unityVersion;
+    this._versionCompatibilityChecked = true;
+
+    if (unityVersion === nodeVersion) return;
+
+    const message =
+      `Version mismatch detected: Node package v${nodeVersion} != Unity package v${unityVersion}. ` +
+      `Update @akiojin/unity-mcp-server or the Unity UPM package so they match.`;
+
+    if (policy === 'error') {
+      const err = new Error(message);
+      err.code = 'UNITY_VERSION_MISMATCH';
+      this._versionMismatchError = err;
+      logger.error(message);
+    } else {
+      logger.warning(`${message} (Set UNITY_MCP_VERSION_MISMATCH=error to fail fast.)`);
+    }
+  }
+
   /**
    * Sends a ping command to Unity
    * @returns {Promise<any>}