Bridge: deferred init, stop-before-reload, breadcrumb logs; stable rebinds.

Editor: auto-rewrite MCP client config when package path changes.

Server: heartbeat-aware retries, structured {state: reloading, retry_after_ms}, single auto-retry across tools; guard empty calls.

Repo: remove global *~ ignore (was hiding UnityMcpServer~), track tilde server folder (Unity still excludes it from assemblies).

Author: dsarno

UnityMcpBridge/Editor/UnityMcpBridge.cs

@@ -24,13 +24,31 @@ public static partial class UnityMcpBridge
         private static readonly object lockObj = new();
         private static readonly object startStopLock = new();
         private static bool initScheduled = false;
+        private static bool ensureUpdateHooked = false;
+        private static bool isStarting = false;
+        private static double nextStartAt = 0.0f;
         private static double nextHeartbeatAt = 0.0f;
+        private static int heartbeatSeq = 0;
         private static Dictionary<
             string,
             (string commandJson, TaskCompletionSource<string> tcs)
         > commandQueue = new();
         private static int currentUnityPort = 6400; // Dynamic port, starts with default
         private static bool isAutoConnectMode = false;
+        
+        // Debug helpers
+        private static bool IsDebugEnabled()
+        {
+            try { return EditorPrefs.GetBool("UnityMCP.DebugLogs", false); } catch { return false; }
+        }
+        
+        private static void LogBreadcrumb(string stage)
+        {
+            if (IsDebugEnabled())
+            {
+                Debug.Log($"<b><color=#2EA3FF>UNITY-MCP</color></b>: [{stage}]");
+            }
+        }
 
         public static bool IsRunning => isRunning;
         public static int GetCurrentPort() => currentUnityPort;
@@ -78,11 +96,24 @@ public static bool FolderExists(string path)
 
         static UnityMcpBridge()
         {
-            // Immediate start for minimal downtime, plus quit hook
-            Start();
+            // Skip bridge in headless/batch environments (CI/builds)
+            if (Application.isBatchMode)
+            {
+                return;
+            }
+            // Defer start until the editor is idle and not compiling
+            ScheduleInitRetry();
+            // Add a safety net update hook in case delayCall is missed during reload churn
+            if (!ensureUpdateHooked)
+            {
+                ensureUpdateHooked = true;
+                EditorApplication.update += EnsureStartedOnEditorIdle;
+            }
             EditorApplication.quitting += Stop;
             AssemblyReloadEvents.beforeAssemblyReload += OnBeforeAssemblyReload;
             AssemblyReloadEvents.afterAssemblyReload += OnAfterAssemblyReload;
+            // Also coalesce play mode transitions into a deferred init
+            EditorApplication.playModeStateChanged += _ => ScheduleInitRetry();
         }
 
         /// <summary>
@@ -94,7 +125,7 @@ private static void InitializeAfterCompilation()
             initScheduled = false;
 
             // Play-mode friendly: allow starting in play mode; only defer while compiling
-            if (EditorApplication.isCompiling)
+            if (IsCompiling())
             {
                 ScheduleInitRetry();
                 return;
@@ -118,9 +149,77 @@ private static void ScheduleInitRetry()
                 return;
             }
             initScheduled = true;
+            // Debounce: start ~200ms after the last trigger
+            nextStartAt = EditorApplication.timeSinceStartup + 0.20f;
+            // Ensure the update pump is active
+            if (!ensureUpdateHooked)
+            {
+                ensureUpdateHooked = true;
+                EditorApplication.update += EnsureStartedOnEditorIdle;
+            }
+            // Keep the original delayCall as a secondary path
             EditorApplication.delayCall += InitializeAfterCompilation;
         }
 
+        // Safety net: ensure the bridge starts shortly after domain reload when editor is idle
+        private static void EnsureStartedOnEditorIdle()
+        {
+            // Do nothing while compiling
+            if (IsCompiling())
+            {
+                return;
+            }
+
+            // If already running, remove the hook
+            if (isRunning)
+            {
+                EditorApplication.update -= EnsureStartedOnEditorIdle;
+                ensureUpdateHooked = false;
+                return;
+            }
+
+            // Debounced start: wait until the scheduled time
+            if (nextStartAt > 0 && EditorApplication.timeSinceStartup < nextStartAt)
+            {
+                return;
+            }
+
+            if (isStarting)
+            {
+                return;
+            }
+
+            isStarting = true;
+            // Attempt start; if it succeeds, remove the hook to avoid overhead
+            Start();
+            isStarting = false;
+            if (isRunning)
+            {
+                EditorApplication.update -= EnsureStartedOnEditorIdle;
+                ensureUpdateHooked = false;
+            }
+        }
+
+        // Helper to check compilation status across Unity versions
+        private static bool IsCompiling()
+        {
+            if (EditorApplication.isCompiling)
+            {
+                return true;
+            }
+            try
+            {
+                System.Type pipeline = System.Type.GetType("UnityEditor.Compilation.CompilationPipeline, UnityEditor");
+                var prop = pipeline?.GetProperty("isCompiling", System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static);
+                if (prop != null)
+                {
+                    return (bool)prop.GetValue(null);
+                }
+            }
+            catch { }
+            return false;
+        }
+
         public static void Start()
         {
             lock (startStopLock)
@@ -140,6 +239,9 @@ public static void Start()
                     // Always consult PortManager first so we prefer the persisted project port
                     currentUnityPort = PortManager.GetPortWithFallback();
 
+                    // Breadcrumb: Start
+                    LogBreadcrumb("Start");
+
                     const int maxImmediateRetries = 3;
                     const int retrySleepMs = 75;
                     int attempt = 0;
@@ -153,6 +255,13 @@ public static void Start()
                                 SocketOptionName.ReuseAddress,
                                 true
                             );
+#if UNITY_EDITOR_WIN
+                            try
+                            {
+                                listener.ExclusiveAddressUse = false;
+                            }
+                            catch { }
+#endif
                             // Minimize TIME_WAIT by sending RST on close
                             try
                             {
@@ -180,6 +289,13 @@ public static void Start()
                                 SocketOptionName.ReuseAddress,
                                 true
                             );
+#if UNITY_EDITOR_WIN
+                            try
+                            {
+                                listener.ExclusiveAddressUse = false;
+                            }
+                            catch { }
+#endif
                             try
                             {
                                 listener.Server.LingerState = new LingerOption(true, 0);
@@ -198,7 +314,8 @@ public static void Start()
                     Task.Run(ListenerLoop);
                     EditorApplication.update += ProcessCommands;
                     // Write initial heartbeat immediately
-                    WriteHeartbeat(false);
+                    heartbeatSeq++;
+                    WriteHeartbeat(false, "ready");
                     nextHeartbeatAt = EditorApplication.timeSinceStartup + 0.5f;
                 }
                 catch (SocketException ex)
@@ -571,16 +688,22 @@ private static string GetParamsSummary(JObject @params)
         // Heartbeat/status helpers
         private static void OnBeforeAssemblyReload()
         {
-            WriteHeartbeat(true);
+            // Stop cleanly before reload so sockets close and clients see 'reloading'
+            try { Stop(); } catch { }
+            WriteHeartbeat(true, "reloading");
+            LogBreadcrumb("Reload");
         }
 
         private static void OnAfterAssemblyReload()
         {
             // Will be overwritten by Start(), but mark as alive quickly
-            WriteHeartbeat(false);
+            WriteHeartbeat(false, "idle");
+            LogBreadcrumb("Idle");
+            // Schedule a safe restart after reload to avoid races during compilation
+            ScheduleInitRetry();
         }
 
-        private static void WriteHeartbeat(bool reloading)
+        private static void WriteHeartbeat(bool reloading, string reason = null)
         {
             try
             {
@@ -591,6 +714,8 @@ private static void WriteHeartbeat(bool reloading)
                 {
                     unity_port = currentUnityPort,
                     reloading,
+                    reason = reason ?? (reloading ? "reloading" : "ready"),
+                    seq = heartbeatSeq,
                     project_path = Application.dataPath,
                     last_heartbeat = DateTime.UtcNow.ToString("O")
                 };

UnityMcpBridge/Editor/Windows/UnityMcpEditorWindow.cs

@@ -1311,14 +1311,38 @@ private void CheckMcpConfiguration(McpClient mcpClient)
                 // Common logic for checking configuration status
                 if (configExists)
                 {
-                    if (pythonDir != null && 
-                        Array.Exists(args, arg => arg.Contains(pythonDir, StringComparison.Ordinal)))
+                    bool matches = pythonDir != null && Array.Exists(args, arg => arg.Contains(pythonDir, StringComparison.Ordinal));
+                    if (matches)
                     {
                         mcpClient.SetStatus(McpStatus.Configured);
                     }
                     else
                     {
-                        mcpClient.SetStatus(McpStatus.IncorrectPath);
+                        // Attempt auto-rewrite once if the package path changed
+                        try
+                        {
+                            string rewriteResult = WriteToConfig(pythonDir, configPath, mcpClient);
+                            if (rewriteResult == "Configured successfully")
+                            {
+                                if (debugLogsEnabled)
+                                {
+                                    UnityEngine.Debug.Log($"UnityMCP: Auto-updated MCP config for '{mcpClient.name}' to new path: {pythonDir}");
+                                }
+                                mcpClient.SetStatus(McpStatus.Configured);
+                            }
+                            else
+                            {
+                                mcpClient.SetStatus(McpStatus.IncorrectPath);
+                            }
+                        }
+                        catch (Exception ex)
+                        {
+                            mcpClient.SetStatus(McpStatus.IncorrectPath);
+                            if (debugLogsEnabled)
+                            {
+                                UnityEngine.Debug.LogWarning($"UnityMCP: Auto-config rewrite failed for '{mcpClient.name}': {ex.Message}");
+                            }
+                        }
                     }
                 }
                 else

UnityMcpBridge/UnityMcpServer~/src/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+# Install required system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Install uv package manager
+RUN pip install uv
+
+# Copy required files
+COPY config.py /app/
+COPY server.py /app/
+COPY unity_connection.py /app/
+COPY pyproject.toml /app/
+COPY __init__.py /app/
+COPY tools/ /app/tools/
+
+# Install dependencies using uv
+RUN uv pip install --system -e .
+
+
+# Command to run the server
+CMD ["uv", "run", "server.py"] 

UnityMcpBridge/UnityMcpServer~/src/__init__.py

@@ -0,0 +1,3 @@
+"""
+Unity MCP Server package.
+""" 

UnityMcpBridge/UnityMcpServer~/src/config.py

@@ -0,0 +1,30 @@
+"""
+Configuration settings for the Unity MCP Server.
+This file contains all configurable parameters for the server.
+"""
+
+from dataclasses import dataclass
+
+@dataclass
+class ServerConfig:
+    """Main configuration class for the MCP server."""
+    
+    # Network settings
+    unity_host: str = "localhost"
+    unity_port: int = 6400
+    mcp_port: int = 6500
+    
+    # Connection settings
+    connection_timeout: float = 60.0  # default steady-state timeout; retries use shorter timeouts
+    buffer_size: int = 16 * 1024 * 1024  # 16MB buffer
+    
+    # Logging settings
+    log_level: str = "INFO"
+    log_format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    
+    # Server settings
+    max_retries: int = 10
+    retry_delay: float = 0.25
+
+# Create a global config instance
+config = ServerConfig()