fix: startup tweaks (#41)

* fix: startup tweaks

* fix: Add a few safety checks

addon/FreecadRobustMCPBridge/Init.py

@@ -37,6 +37,27 @@ def _auto_start_bridge() -> None:
     This function is called via a deferred timer (GUI mode) or directly
     (headless mode) after FreeCAD finishes loading. It starts the bridge
     without requiring the workbench to be selected.
+
+    Args:
+        None.
+
+    Returns:
+        None. Early returns if auto-start is disabled or bridge is already running.
+
+    Raises:
+        Exception: Any exception during bridge startup is caught, logged to
+            FreeCAD.Console.PrintError with full traceback, and suppressed.
+
+    Side Effects:
+        - Imports and checks auto-start preference from preferences module
+        - Creates and starts a FreecadMCPPlugin instance if not already running
+        - Registers the plugin with the workbench commands module
+        - Prints status messages to FreeCAD.Console
+
+    Example:
+        This function is typically called via QTimer or GuiWaiter callback::
+
+            QtCore.QTimer.singleShot(1000, _auto_start_bridge)
     """
     try:
         from preferences import get_auto_start

addon/FreecadRobustMCPBridge/InitGui.py

@@ -183,9 +183,42 @@ try:
     # This runs at FreeCAD GUI startup (InitGui.py module-level code)
     # Note: Init.py does NOT run at startup for workbench addons, so auto-start
     # must be triggered from here instead.
-    def _deferred_auto_start() -> None:
-        """Auto-start bridge after GUI is fully ready."""
+    #
+    # We use GuiWaiter to poll FreeCAD.GuiUp instead of a fixed timer delay.
+    # This ensures we wait for the GUI to actually be ready, rather than
+    # hoping a fixed delay is long enough.
+    def _auto_start_bridge() -> None:
+        """Auto-start bridge after GUI is confirmed ready.
+
+        This is the callback invoked by GuiWaiter once FreeCAD.GuiUp is True
+        and a defer period has elapsed. At this point, it's safe to start
+        the MCP bridge with Qt timer-based queue processing.
+
+        Args:
+            None.
+
+        Returns:
+            None. Early returns if auto-start disabled or bridge already running.
+
+        Raises:
+            Exception: Any exception during bridge startup is caught, logged
+                to FreeCAD.Console.PrintError with full traceback, and suppressed.
+
+        Side Effects:
+            - Creates and starts a FreecadMCPPlugin instance
+            - Registers the plugin with the workbench commands module
+            - Syncs the status bar widget with bridge state
+        """
         try:
+            # Safety check: verify GUI is actually ready before starting
+            # If not ready, reschedule for another attempt
+            if not FreeCAD.GuiUp:
+                FreeCAD.Console.PrintMessage(
+                    "Robust MCP Bridge: GUI not ready, rescheduling auto-start...\n"
+                )
+                QtCore.QTimer.singleShot(500, _auto_start_bridge)
+                return
+
             from preferences import get_auto_start
 
             if not get_auto_start():
@@ -238,12 +271,23 @@ try:
 
             FreeCAD.Console.PrintError(traceback.format_exc())
 
-    # Schedule auto-start after a short delay to ensure GUI is fully ready
-    # Use a longer delay than status bar sync to avoid race conditions
-    QtCore.QTimer.singleShot(3000, _deferred_auto_start)
-    FreeCAD.Console.PrintMessage(
-        "Robust MCP Bridge: Auto-start scheduled from InitGui (3s)\n"
-    )
+    # Check if auto-start is enabled before scheduling
+    from preferences import get_auto_start
+
+    if get_auto_start():
+        # Schedule auto-start after a delay to ensure GUI is fully ready.
+        # InitGui.py module-level code runs early in FreeCAD startup, so we
+        # need to defer the bridge start to avoid race conditions.
+        # Note: We use a simple QTimer.singleShot() here because GuiWaiter
+        # has timing issues when used from module-level code during startup.
+        QtCore.QTimer.singleShot(3000, _auto_start_bridge)
+        FreeCAD.Console.PrintMessage(
+            "Robust MCP Bridge: Auto-start scheduled from InitGui (3s)\n"
+        )
+    else:
+        FreeCAD.Console.PrintMessage(
+            "Robust MCP Bridge: Auto-start disabled in preferences\n"
+        )
 except Exception as e:
     FreeCAD.Console.PrintWarning(
         f"Robust MCP Bridge: Could not schedule status bar sync: {e}\n"

addon/FreecadRobustMCPBridge/RELEASE_NOTES.md

@@ -17,7 +17,7 @@ This release fixes some auto-start issues and improves the overall startup exper
 
 - **Auto-start not working at FreeCAD startup**: Fixed bug where auto-start only worked when manually selecting the workbench. For FreeCAD workbench addons, `Init.py` does NOT run at startup - only `InitGui.py` module-level code runs. Auto-start logic has been moved to `InitGui.py`.
 - **Status bar not appearing after auto-start**: The status bar widget now syncs immediately after the bridge starts, instead of on a timer that ran before the bridge was ready.
-- **Integration test crashes**: Fixed race condition where the bridge could start before `FreeCAD.GuiUp` was `True`, causing Qt operations to run on a background thread and crash FreeCAD.
+- **Integration test crashes**: Fixed race condition where the bridge could start before `FreeCAD.GuiUp` was `True`, causing Qt operations to run on a background thread and crash FreeCAD. Auto-start is now deferred with `QTimer.singleShot()` to allow the GUI to stabilize.
 
 ### Note
 

addon/FreecadRobustMCPBridge/freecad_mcp_bridge/server.py

@@ -269,8 +269,8 @@ class FreecadMCPPlugin:
         if FREECAD_AVAILABLE:
             FreeCAD.Console.PrintMessage(
                 f"MCP Bridge started (Instance ID: {self._instance_id}):\n"
-                f"  - JSON-RPC: {self._host}:{self._port}\n"
             )
+            FreeCAD.Console.PrintMessage(f"  - JSON-RPC: {self._host}:{self._port}\n")
             if self._enable_xmlrpc:
                 FreeCAD.Console.PrintMessage(
                     f"  - XML-RPC: {self._host}:{self._xmlrpc_port}\n"

addon/FreecadRobustMCPBridge/freecad_mcp_bridge/startup_bridge.py

@@ -59,6 +59,12 @@ def _start_bridge() -> None:
     environment variables and registers the plugin with the workbench commands
     module for visibility to other components.
 
+    Args:
+        None.
+
+    Returns:
+        None. Early returns if bridge is already running.
+
     Environment Variables:
         FREECAD_XMLRPC_PORT: XML-RPC port (default: 9875)
         FREECAD_SOCKET_PORT: JSON-RPC socket port (default: 9876)
@@ -73,6 +79,12 @@ def _start_bridge() -> None:
         - Creates and starts a FreecadMCPPlugin instance
         - Registers the plugin with the workbench commands module
         - Prints status messages to FreeCAD.Console
+
+    Example:
+        This function is typically called via GuiWaiter callback or directly::
+
+            _gui_waiter = GuiWaiter(callback=_start_bridge)
+            _gui_waiter.start()
     """
     # Check if bridge is already running (from auto-start in Init.py)
     from bridge_utils import get_running_plugin