fix: stop the auto-updated in-process server crashing under an older custom component (#1792)

* fix: keep the server up when a single tool module fails to register

A tool module that fails to import or register is now skipped with a
loud error log (naming the module and the restart-HA recovery hint)
instead of crashing the whole server; only a total failure - zero
modules registered - still raises. Also read Settings.enable_dev_mode
via getattr with a False default so a stale settings singleton from an
older package generation degrades to "dev mode off" instead of
AttributeError.

This is the server half of issues #1783/#1785: the in-process
auto-update installed ha-mcp 7.12.0 into a running Home Assistant whose
component (1.0.0) predates the sys.modules purge, and the old cached
registry imported the new on-disk tools_dev module into a stale module
graph - one module's AttributeError took the whole server down.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L7FvJAi5hk5vy7FvtdcZZe

* fix: hold automatic server updates that shipped with a newer component

Before reloading to install a newer server build, the component now
fetches the component manifest at the candidate release's git tag: a
component version there newer than the running one means that release
changed the component too, so the automatic server install waits until
HACS delivers the component update (the ordering that broke in issues
#1783/#1785, where the server auto-installed before HACS had even
surfaced the matching component release).

The hold is loud and never indefinite-by-accident: it files a repair
issue pointing at the HACS update and warns in the log on every check,
the update entity keeps showing the pending build and its Install
button bypasses the hold, pip-spec overrides (PR-tarball testing) never
pass through the gate, and every failure inside the gate fails open so
an unreachable GitHub cannot block updates. On the dev channel the
release tag appears only after the binary builds, so a brand-new dev
version fails open during that window (documented; the registry-side
skip is the backstop there). Bumps the component to 1.0.2.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L7FvJAi5hk5vy7FvtdcZZe

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

custom_components/ha_mcp_tools/const.py

@@ -243,6 +243,22 @@ def channel_for_dist(dist: str) -> str:
 # is DIST_NAME_STABLE or DIST_NAME_DEV depending on the selected channel.
 PYPI_JSON_URL = "https://pypi.org/pypi/{dist}/json"
 
+# The component manifest as it existed at a server release's git tag. Its
+# ``version`` is the component version that SHIPPED with that server build, so
+# a value newer than the running component means the release changed the
+# component too — the pre-install auto-update gate in embedded_setup holds the
+# server update until HACS delivers the component (issues #1783/#1785).
+# Tag-timing caveat: stable ``vX.Y.Z`` tags exist before the PyPI publish
+# (semantic-release pushes the tag first), but a dev ``vX.Y.Z.devN`` tag is
+# only created when its draft GitHub release is published — AFTER the binary
+# builds, minutes after PyPI already has the version. During that dev window
+# this URL 404s and the gate deliberately fails open (the registry's
+# skip-on-failure is the backstop on that channel).
+COMPONENT_MANIFEST_AT_TAG_URL = (
+    "https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/"
+    "v{version}/custom_components/ha_mcp_tools/manifest.json"
+)
+
 # Options-flow keys (stored in entry.options).
 OPT_CHANNEL = "channel"
 # Automatic server-version updates toggle (default on). When on, the channel is
@@ -366,6 +382,14 @@ def channel_for_dist(dist: str) -> str:
 # the server expects; this points the user at the HACS component update
 # (non-blocking).
 ISSUE_COMPONENT_OUTDATED = "component_outdated"
+# Repair issue surfaced while an automatic server update is HELD because the
+# newer server release also shipped a newer custom component than the one
+# running (issues #1783/#1785): installing that server under the old component
+# is the combination that broke starts. Held is loud (this issue + a warning
+# log every check) and escapable — applying the HACS component update (which
+# takes an HA restart) unblocks the next check, and the update entity's
+# Install button bypasses the hold entirely.
+ISSUE_UPDATE_HELD = "server_update_held"
 # Repair issue surfaced when HACS is tracking the MAIN ha-mcp server repo for
 # this component (the pre-mirror install path — issue #1760). That install
 # keeps working (HACS downloads the repo snapshot at the release tag, which

custom_components/ha_mcp_tools/embedded_setup.py

@@ -19,15 +19,18 @@
 from typing import TYPE_CHECKING
 from urllib.parse import urlparse
 
+from aiohttp import ClientError
 from awesomeversion import AwesomeVersion, AwesomeVersionException
 from homeassistant.components import persistent_notification
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers import issue_registry as ir
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
 from homeassistant.loader import async_get_integration
 
 from .const import (
     BIND_HOST_ALL,
     CHANNEL_DEV,
+    COMPONENT_MANIFEST_AT_TAG_URL,
     DATA_BRINGUP_TASK,
     DATA_MANAGER,
     DATA_PENDING_UPDATE_NOTIFY,
@@ -43,6 +46,7 @@
     ISSUE_COMPONENT_OUTDATED,
     ISSUE_PACKAGE_FAILED,
     ISSUE_START_FAILED,
+    ISSUE_UPDATE_HELD,
     OPT_AUTO_UPDATE,
     OPT_BIND_HOST,
     OPT_ENABLE_WEBHOOK,
@@ -65,7 +69,15 @@
 
 _NOTIFICATION_ID = "ha_mcp_tools_server_connect"
 _UPDATE_NOTIFICATION_ID = "ha_mcp_tools_server_updated"
-_ISSUE_IDS = (ISSUE_PACKAGE_FAILED, ISSUE_START_FAILED)
+# ISSUE_UPDATE_HELD is cleared at bring-up start too: any reload that reaches
+# bring-up either bypassed the hold deliberately (the update entity's Install
+# button) or made it moot; if the hold still applies, the coordinator refresh
+# that follows setup re-files it within moments.
+_ISSUE_IDS = (ISSUE_PACKAGE_FAILED, ISSUE_START_FAILED, ISSUE_UPDATE_HELD)
+
+# Per-request timeout for the component-manifest fetch behind the auto-update
+# gate — mirrors the coordinator's PyPI fetch budget; a miss fails open.
+_MANIFEST_FETCH_TIMEOUT_SECONDS = 30
 
 
 async def async_bring_up_server(hass: HomeAssistant, entry: ConfigEntry) -> None:
@@ -326,6 +338,16 @@ async def async_maybe_auto_update(
     coordinator's ``data`` type before its first successful refresh), or a
     bring-up is still in flight (below).
 
+    A pending update is additionally gated on component compatibility
+    (issues #1783/#1785): when the candidate release also shipped a newer
+    custom component than the one running, the reload is HELD — loudly (a
+    repair issue plus a warning log every check) and escapably (applying the
+    HACS component update — which takes an HA restart, as the issue text
+    says — unblocks the next check; the update entity's Install button never
+    passes through here, so manual installs — like pip-spec overrides above —
+    bypass the hold entirely). Every failure inside the gate fails OPEN so a
+    GitHub hiccup can never wedge updates.
+
     Best-effort: an incomparable version string (AwesomeVersionException) is
     logged at debug and skipped; the next refresh retries. Genuine bugs
     propagate per the repo's no-silent-failure convention.
@@ -363,7 +385,39 @@ async def async_maybe_auto_update(
         return
 
     if not newer:
+        # Up to date: a hold that was pending is resolved (the component
+        # update landed and the unblocked reload installed the server).
+        ir.async_delete_issue(hass, DOMAIN, ISSUE_UPDATE_HELD)
+        return
+
+    held = await _async_update_held_by_component(hass, info)
+    if held is not None:
+        shipped, running = held
+        _LOGGER.warning(
+            "HA-MCP server %s is available, but that release also updated the "
+            "custom component (%s; running %s); holding the automatic server "
+            "update until the component is updated via HACS. Press Install on "
+            "the HA-MCP server update entity to install anyway.",
+            info.latest,
+            shipped,
+            running,
+        )
+        ir.async_create_issue(
+            hass,
+            DOMAIN,
+            ISSUE_UPDATE_HELD,
+            is_fixable=False,
+            severity=ir.IssueSeverity.WARNING,
+            translation_key=ISSUE_UPDATE_HELD,
+            translation_placeholders={
+                "latest": str(info.latest),
+                "shipped": shipped,
+                "running": running,
+            },
+            learn_more_url=HACS_COMPONENT_URL,
+        )
         return
+    ir.async_delete_issue(hass, DOMAIN, ISSUE_UPDATE_HELD)
 
     channel = channel_for_dist(info.dist)
     _LOGGER.info(
@@ -403,6 +457,79 @@ def _drop_pending_update_notify(hass: HomeAssistant) -> None:
     hass.data.get(DOMAIN, {}).pop(DATA_PENDING_UPDATE_NOTIFY, None)
 
 
+async def _async_update_held_by_component(
+    hass: HomeAssistant, info: ServerVersionInfo
+) -> tuple[str, str] | None:
+    """Return ``(shipped, running)`` when the pending update must be held.
+
+    The #1783/#1785 breakage: a server release whose repo state also bumped the
+    custom component auto-installed under the OLD component before HACS had
+    even surfaced the component update. The component version in the manifest
+    at the candidate release's git tag is what shipped with that server build —
+    newer than the running component means the release changed the component
+    too, so the automatic server install waits for the component.
+
+    Fails OPEN (returns None → install proceeds, the pre-gate behavior) on
+    every expected failure: manifest unreachable, component version unreadable,
+    incomparable versions. Blocking updates indefinitely on a transient would
+    be worse than the crash this guards against — and the crash itself is now
+    also survivable server-side (the tools registry skips a failing module).
+    """
+    shipped = await _async_fetch_shipped_component_version(hass, str(info.latest))
+    if shipped is None:
+        return None
+
+    try:
+        integration = await async_get_integration(hass, DOMAIN)
+        running = str(integration.version)
+    except Exception:
+        # Same wide loader surface as _async_check_component_compat: advisory
+        # gate, logged visibly rather than swallowed silently.
+        _LOGGER.warning(
+            "Could not read the HA-MCP component version for the auto-update "
+            "gate; proceeding with the update",
+            exc_info=True,
+        )
+        return None
+
+    try:
+        if AwesomeVersion(running) < AwesomeVersion(shipped):
+            return shipped, running
+    except AwesomeVersionException as err:
+        # Incomparable version strategies only; real bugs propagate.
+        _LOGGER.debug("HA-MCP auto-update gate version compare failed: %s", err)
+    return None
+
+
+async def _async_fetch_shipped_component_version(
+    hass: HomeAssistant, server_version: str
+) -> str | None:
+    """Return the component version shipped at server release ``vX.Y.Z``.
+
+    Reads the component manifest as committed at the release's git tag (raw
+    GitHub URL). Stable tags exist before the PyPI publish; a dev tag only
+    appears after its binary builds finish, so a fresh dev version can 404
+    here for some minutes — see COMPONENT_MANIFEST_AT_TAG_URL. Returns None
+    on any failure; the caller treats that as "nothing to hold on"
+    (fail-open).
+    """
+    url = COMPONENT_MANIFEST_AT_TAG_URL.format(version=server_version)
+    try:
+        session = async_get_clientsession(hass)
+        async with asyncio.timeout(_MANIFEST_FETCH_TIMEOUT_SECONDS):
+            async with session.get(url) as resp:
+                resp.raise_for_status()
+                # content_type=None: raw.githubusercontent.com serves
+                # text/plain, which aiohttp's default json() rejects.
+                payload = await resp.json(content_type=None)
+        return str(payload["version"])
+    except (ClientError, TimeoutError, KeyError, TypeError, ValueError) as err:
+        _LOGGER.debug(
+            "HA-MCP shipped-component manifest fetch failed for %s: %s", url, err
+        )
+        return None
+
+
 async def _async_finish_update_cycle(hass: HomeAssistant) -> None:
     """Refresh the version entity and fire the deferred update notification.
 

custom_components/ha_mcp_tools/manifest.json

@@ -19,5 +19,5 @@
     "requirements": [
         "ruamel.yaml>=0.18.0"
     ],
-    "version": "1.0.1"
+    "version": "1.0.2"
 }

custom_components/ha_mcp_tools/strings.json

@@ -74,6 +74,10 @@
             "title": "Update the HA-MCP Custom Component via HACS",
             "description": "The installed ha-mcp server requires HA-MCP Custom Component {required} or newer, but you have {installed}. Update the component via HACS and restart Home Assistant. The server keeps running in the meantime, but some newer features may not work until the component is updated."
         },
+        "server_update_held": {
+            "title": "HA-MCP server update waiting for a component update",
+            "description": "ha-mcp server {latest} is available, but that release also updated the HA-MCP Custom Component (to {shipped}; you are running {running}). To avoid starting a server version the running component has never been tested with, the automatic server update is on hold until the component is updated.\n\nUpdate the component via HACS (open the HA-MCP Custom Component entry and use 'Update information' if no update is shown yet), then restart Home Assistant - the server update installs automatically afterwards. To install the server update anyway, press Install on the HA-MCP server update entity."
+        },
         "legacy_hacs_source": {
             "title": "Component installed from the legacy repository",
             "description": "HACS is tracking the main ha-mcp server repository for this component, so HACS shows the server's version numbers (7.x) and the server's release notes here instead of the component's own (1.x). Updates keep working, but stay mislabeled this way. To fix: remove this repository from HACS (your integration settings and config entries are kept), add homeassistant-ai/ha-mcp-integration as a custom repository, reinstall the component from it, and restart Home Assistant."

custom_components/ha_mcp_tools/translations/en.json

@@ -74,6 +74,10 @@
             "title": "Update the HA-MCP Custom Component via HACS",
             "description": "The installed ha-mcp server requires HA-MCP Custom Component {required} or newer, but you have {installed}. Update the component via HACS and restart Home Assistant. The server keeps running in the meantime, but some newer features may not work until the component is updated."
         },
+        "server_update_held": {
+            "title": "HA-MCP server update waiting for a component update",
+            "description": "ha-mcp server {latest} is available, but that release also updated the HA-MCP Custom Component (to {shipped}; you are running {running}). To avoid starting a server version the running component has never been tested with, the automatic server update is on hold until the component is updated.\n\nUpdate the component via HACS (open the HA-MCP Custom Component entry and use 'Update information' if no update is shown yet), then restart Home Assistant - the server update installs automatically afterwards. To install the server update anyway, press Install on the HA-MCP server update entity."
+        },
         "legacy_hacs_source": {
             "title": "Component installed from the legacy repository",
             "description": "HACS is tracking the main ha-mcp server repository for this component, so HACS shows the server's version numbers (7.x) and the server's release notes here instead of the component's own (1.x). Updates keep working, but stay mislabeled this way. To fix: remove this repository from HACS (your integration settings and config entries are kept), add homeassistant-ai/ha-mcp-integration as a custom repository, reinstall the component from it, and restart Home Assistant."

src/ha_mcp/tools/registry.py

@@ -143,7 +143,8 @@ def _import_and_register_module(
         When ``func_name`` is given, uses it directly (explicit mode); otherwise scans
         the module for an attribute matching the ``register_*_tools`` convention.
         Returns True if registered, False if no register function was found.
-        Re-raises on import or registration failure (fail-fast).
+        Re-raises on import or registration failure; ``register_all_tools``
+        contains that failure to the one module (see its docstring).
         """
         import importlib
 
@@ -169,15 +170,23 @@ def _import_and_register_module(
                 logger.warning(f"Module {module_name} has no register_*_tools function")
                 return False
 
-        except Exception as e:
-            logger.error(f"Failed to register tools from {module_name}: {e}")
+        except Exception:
+            logger.exception(f"Failed to register tools from {module_name}")
             raise
 
     def register_all_tools(self) -> None:
         """Register all tools with the MCP server using lazy auto-discovery.
 
         Tool modules are imported and registered only when this method is called,
         which happens after the MCP server is ready to accept connections.
+
+        A module that fails to import or register is SKIPPED (logged loudly),
+        not fatal: the in-process server auto-updates the ha-mcp package inside
+        a running Home Assistant, and a mixed old/new module generation — or a
+        module needing a newer custom component — previously took the whole
+        server down over one module (issues #1783/#1785). Only a TOTAL failure
+        (zero modules registered) still raises: a tool-less server "running"
+        would hide a genuinely broken install.
         """
         if self._modules_registered:
             logger.debug("Tools already registered, skipping")
@@ -189,23 +198,52 @@ def register_all_tools(self) -> None:
             "device_tools": self.device_tools,
         }
 
+        # tools_*.py modules by convention, then the explicit modules (those
+        # not following the convention) — each only if discovery included it
+        # (respects filtering).
+        worklist: list[tuple[str, str | None]] = [
+            (name, None)
+            for name in self._discovered_modules
+            if name not in EXPLICIT_MODULES
+        ]
+        worklist += [
+            (name, func_name)
+            for name, func_name in EXPLICIT_MODULES.items()
+            if name in self._discovered_modules
+        ]
+
         registered_count = 0
+        failed: list[tuple[str, Exception]] = []
+        for module_name, func_name in worklist:
+            try:
+                if self._import_and_register_module(module_name, kwargs, func_name):
+                    registered_count += 1
+            except Exception as e:
+                failed.append((module_name, e))
 
-        # Import and register tools_*.py modules
-        for module_name in self._discovered_modules:
-            # Skip explicit modules - handled separately
-            if module_name in EXPLICIT_MODULES:
-                continue
-            if self._import_and_register_module(module_name, kwargs):
-                registered_count += 1
-
-        # Register explicit modules (those not following tools_*.py convention)
-        # Only register if they were included in discovered modules (respects filtering)
-        for module_name, func_name in EXPLICIT_MODULES.items():
-            if module_name not in self._discovered_modules:
-                continue
-            if self._import_and_register_module(module_name, kwargs, func_name):
-                registered_count += 1
+        self._raise_or_log_registration_failures(failed, registered_count)
 
         self._modules_registered = True
         logger.info(f"Auto-discovery registered tools from {registered_count} modules")
+
+    @staticmethod
+    def _raise_or_log_registration_failures(
+        failed: list[tuple[str, Exception]], registered_count: int
+    ) -> None:
+        """Raise on a total registration failure, log a summary on a partial one."""
+        if not failed:
+            return
+        if registered_count == 0:
+            raise RuntimeError(
+                "No tool module could be registered "
+                f"({', '.join(name for name, _ in failed)} all failed); "
+                "the installed ha-mcp package is broken."
+            ) from failed[0][1]
+        logger.error(
+            "Skipped %d tool module(s) that failed to register: %s. The "
+            "server is running without their tools. If this happened right "
+            "after a package update, restart Home Assistant so every "
+            "module loads from the same package version.",
+            len(failed),
+            ", ".join(name for name, _ in failed),
+        )

src/ha_mcp/tools/tools_dev.py

@@ -67,11 +67,15 @@ def is_dev_mode_enabled() -> bool:
 
     Reads through :func:`config.get_global_settings` so the same
     env-var / override-file / default precedence path applies as
-    every other runtime-editable Settings field.
+    every other runtime-editable Settings field. ``getattr`` with a
+    False default, not attribute access: during an in-process package
+    update the cached settings singleton can predate this field
+    (issues #1783/#1785), and that stale read must mean "dev mode
+    off", never AttributeError.
     """
     from ..config import get_global_settings
 
-    return bool(get_global_settings().enable_dev_mode)
+    return bool(getattr(get_global_settings(), "enable_dev_mode", False))
 
 
 def _spawn_background(coro: Any) -> None: