ha-mcp-dev 7.8.1.dev715__tar.gz → 7.8.1.dev717__tar.gz

{ha_mcp_dev-7.8.1.dev715/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.8.1.dev717}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.1.dev715
+Version: 7.8.1.dev717
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -27,6 +27,7 @@ Requires-Dist: websockets==16.0
 Requires-Dist: cryptography==49.0.0
 Requires-Dist: pydantic-monty==0.0.18
 Requires-Dist: tzdata>=2024.1
+Requires-Dist: packaging>=24.0
 Dynamic: license-file
 
 > **Breaking change (v7.3.0):** `ha_config_set_yaml` has been moved to [beta](docs/beta.md).

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.8.1.dev715"
+version = "7.8.1.dev717"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -33,6 +33,7 @@ dependencies = [
     "cryptography==49.0.0",
     "pydantic-monty==0.0.18",
     "tzdata>=2024.1",
+    "packaging>=24.0",
 ]
 
 [project.urls]

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/src/ha_mcp/__main__.py

@@ -479,16 +479,24 @@ def _setup_logging(log_level_str: str, force: bool = False) -> None:
 
 
 def _log_startup_version() -> None:
-    """Log ha-mcp version at startup, plus a dev-channel banner when relevant.
+    """Log ha-mcp version at startup, plus dev-channel / update banners.
 
     The dev banner only fires for standalone dev installs (Docker ``:dev`` /
     ``:latest``, or ``pip install ha-mcp-dev``). It is suppressed under the HA
     Supervisor because add-on users already pick dev vs stable in the HAOS UI.
+
+    The update banner fires on every startup when a newer release is available,
+    on every deployment — pip/Docker/stdio compare against PyPI, the HA add-on
+    (stable AND dev) against the Supervisor add-on store — mirroring FastMCP's
+    ``log_server_banner``. ``get_update_info`` is a no-op for the ``unknown``
+    version (PyPI path) and the ``HA_MCP_DISABLE_UPDATE_CHECK`` opt-out, and
+    never raises.
     """
     from ha_mcp._version import get_version, is_dev_version, is_running_in_addon
 
     version = get_version()
     logger.info(f"ha-mcp {version}")
+
     if is_dev_version(version) and not is_running_in_addon():
         logger.warning(
             "This is the dev channel. For the stable release use the "
@@ -496,6 +504,17 @@ def _log_startup_version() -> None:
             "(or 'pip install ha-mcp' on PyPI)."
         )
 
+    from ha_mcp.update_check import get_update_info, update_command_hint
+
+    info = get_update_info()
+    if info is not None and info.update_available:
+        logger.warning(
+            "A newer ha-mcp release is available: %s (you have %s). %s",
+            info.latest,
+            info.current,
+            update_command_hint(info.current),
+        )
+
 
 def _get_timestamped_uvicorn_log_config() -> dict:
     """Return a Uvicorn log config with human-readable timestamps added."""

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/src/ha_mcp/read_only.py

@@ -93,8 +93,8 @@ def _addon_write(args: dict[str, Any]) -> str | None:
         return "array_patch modification"
     if args.get("websocket"):
         # A WebSocket session's initial message can command mutations
-        # (e.g. ESPHome /compile), so it is not statically classifiable
-        # as a read — fail closed.
+        # (e.g. an ESPHome firmware/compile or devices/update_config command),
+        # so it is not statically classifiable as a read — fail closed.
         return "WebSocket proxy session"
     method = str(args.get("method") or "GET").strip().upper()
     if method != "GET":

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/src/ha_mcp/tools/tools_addons.py

@@ -958,7 +958,7 @@ async def _call_addon_ws(
     Args:
         client: Home Assistant REST client
         slug: Add-on slug (e.g., "<prefix>_esphome")
-        path: WebSocket endpoint path (e.g., "/compile", "/validate")
+        path: WebSocket endpoint path (e.g., "/ws" for the ESPHome dashboard's command channel)
         body: Message to send after connecting (JSON-encoded if dict, raw if string)
         timeout: Max seconds to wait for messages (default 60)
         debug: Include diagnostic info
@@ -2622,7 +2622,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         body: Annotated[
             dict[str, Any] | str | None,
             Field(
-                description="Proxy mode only. Request body for POST/PUT/PATCH. Pass a JSON object or JSON string.",
+                description="Proxy mode only. Request body for POST/PUT/PATCH — or, with websocket=True, the initial WebSocket message. Pass a JSON object or JSON string.",
                 default=None,
             ),
         ] = None,
@@ -2658,17 +2658,20 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         websocket: Annotated[
             bool,
             Field(
-                description="Proxy mode only. Use WebSocket instead of HTTP. For streaming endpoints "
-                "(e.g., ESPHome /compile, /validate). Sends 'body' as initial message, "
-                "collects responses. Default: false.",
+                description="Proxy mode only. Use WebSocket instead of HTTP — for an add-on's "
+                "WebSocket API (e.g. the ESPHome dashboard's '/ws' command channel; see the "
+                "docstring's ESPHome section). Sends 'body' as the initial message, collects "
+                "responses. Default: false.",
                 default=False,
             ),
         ] = False,
         wait_for_close: Annotated[
             bool,
             Field(
-                description="Proxy mode only. WebSocket: True: wait for server to close (for compile/validate). "
-                "False: return after first response batch (for quick commands). Default: true.",
+                description="Proxy mode only. WebSocket: True: wait for the server to close the stream "
+                "(run-to-completion ops like an ESPHome compile/validate). False: return after the first "
+                "response batch — use for a one-shot command/response or a bounded log capture on a channel "
+                "that stays open (e.g. ESPHome '/ws'). Default: true.",
                 default=True,
             ),
         ] = True,
@@ -2839,6 +2842,29 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         share Home Assistant's container network (i.e. only the HAOS addon).
         Use ha_get_addon(slug="...") to discover available ports and endpoints.
 
+        **ESPHome Device Builder dashboard (current rewrite):** config and log
+        access is a WebSocket JSON-command API, NOT REST. The legacy endpoints
+        are gone — `GET /edit?configuration=` now returns the dashboard SPA, and
+        the old `/compile` `/validate` `/logs` WebSocket paths (which took
+        `{"type": "spawn", ...}` bodies) reject the upgrade (HTTP 200). Use
+        instead:
+        - HTTP `GET /devices` → JSON list of configured devices; each entry's
+          `configuration` field is the YAML filename to pass below.
+        - WebSocket `path="/ws"` with body
+          `{"command": "<cmd>", "message_id": "1", "args": {...}}`. The server
+          sends a `server_info` message first, then one reply per `message_id`.
+          Wire-confirmed commands: `devices/get_config` `{configuration}` → raw
+          YAML (in the reply's `result`); `devices/logs` (stream)
+          `{configuration, port: "OTA"}` → live device logs. Also exposed by the
+          dashboard frontend (command/arg names not wire-tested here):
+          `devices/update_config` `{configuration, content}` → save,
+          `devices/validate`, `firmware/compile`.
+        - The `/ws` channel stays open, so for a one-shot read or a bounded log
+          capture pass `wait_for_close=False` with `message_limit` (and
+          `message_offset` to skip the server_info / config-banner preamble).
+          Reach the dashboard through Ingress — omit `port`; direct `port=` does
+          not route to it.
+
         **Array-patch mode** (when path AND array_patch are provided):
         Atomic "GET array, mutate, POST array" workflow for addon APIs whose write
         contract is "send the whole resource collection back". Operations are applied
@@ -2847,8 +2873,8 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         full array. Designed for Node-RED /flows and similar endpoints.
 
         **Response shaping (proxy mode):**
-        - WebSocket streams can be noisy (ESPHome /validate often emits hundreds of
-          config-dump lines). By default, `summarize=True` collapses long runs of
+        - WebSocket streams can be noisy (e.g. the ESPHome dashboard's devices/logs
+          dumps the device's full config banner on connect). By default, `summarize=True` collapses long runs of
           non-signal messages into short elision markers; INFO/WARNING/ERROR/exit
           lines always pass through. Pagination via `message_offset` / `message_limit`
           works on the raw collected list before summarize runs.
@@ -2881,9 +2907,10 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         - Set boot mode: ha_manage_addon(slug="...", boot="manual")
         - Call HTTP API: ha_manage_addon(slug="...", path="/api/events")
         - Direct port: ha_manage_addon(slug="...", path="/flows", port=1880)
-        - WebSocket: ha_manage_addon(slug="...", path="/validate", port=6052, websocket=True, body={"type": "spawn", "configuration": "device.yaml"})
-        - Quick WS health check (50 msgs, raw): ha_manage_addon(slug="...", path="/logs", websocket=True, message_limit=50, summarize=False)
-        - Filter WS errors only: ha_manage_addon(slug="...", path="/validate", websocket=True, python_transform="response = [m for m in response if 'ERROR' in str(m) or 'WARN' in str(m)]")
+        - ESPHome list devices (HTTP): ha_manage_addon(slug="<prefix>_esphome", path="/devices")
+        - ESPHome read a device's YAML (WS one-shot): ha_manage_addon(slug="<prefix>_esphome", path="/ws", websocket=True, wait_for_close=False, message_limit=2, body={"command": "devices/get_config", "message_id": "1", "args": {"configuration": "device.yaml"}})
+        - ESPHome live logs (WS, bounded): ha_manage_addon(slug="<prefix>_esphome", path="/ws", websocket=True, wait_for_close=False, message_limit=60, body={"command": "devices/logs", "message_id": "1", "args": {"configuration": "device.yaml", "port": "OTA"}})
+        - Filter WS errors only: ha_manage_addon(slug="...", path="/ws", websocket=True, python_transform="response = [m for m in response if 'ERROR' in str(m) or 'WARN' in str(m)]")
         - HTTP subset: ha_manage_addon(slug="...", path="/flows", python_transform="response = [f['id'] for f in response]")
         - Array-patch (Node-RED, rename a node):
             ha_manage_addon(

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/src/ha_mcp/tools/tools_search.py

@@ -1896,13 +1896,14 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     "notification_count, notifications, repair_count, "
                     "dismissed_repair_count, repairs, repairs_error, "
                     "tool_discovery, settings_url, settings_url_hint, "
-                    "read_only_mode, read_only_mode_hint. Note: "
+                    "read_only_mode, read_only_mode_hint, ha_mcp_update. Note: "
                     "``settings_url`` (stdio mode), ``settings_url_hint`` "
-                    "(HTTP/Docker/OAuth mode), and the ``read_only_mode`` / "
+                    "(HTTP/Docker/OAuth mode), the ``read_only_mode`` / "
                     "``read_only_mode_hint`` pair (only while Read Only Mode "
-                    "is on) are emitted regardless of ``fields=`` projection "
-                    "so the settings page and the active mode stay "
-                    "discoverable; see the tool description."
+                    "is on), and ``ha_mcp_update`` (when an update check applies) "
+                    "are emitted regardless of ``fields=`` projection so the "
+                    "settings page, the active mode, and a newer ha-mcp release "
+                    "stay discoverable; see the tool description."
                 ),
             ),
         ] = None,
@@ -1936,6 +1937,13 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         instead carries a ``settings_url_hint`` string telling the user where
         the page is mounted and to read the full URL from the startup logs.
         Hand whichever of the two fields is present to the user.
+
+        The response also carries an ``ha_mcp_update`` object
+        ``{current, latest, update_available}`` reporting whether a newer ha-mcp
+        release is available (PyPI for pip/Docker, the Supervisor add-on store
+        for the add-on) — proactively tell the user when ``update_available`` is
+        true. Emitted regardless of ``fields=``; omitted only for the
+        ``unknown`` version and when ``HA_MCP_DISABLE_UPDATE_CHECK`` is set.
         """
         # Validate fields= early so a malformed value returns VALIDATION_FAILED
         # with parameter="fields" (ha_get_overview has no outer try/except, so
@@ -2172,6 +2180,17 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "configuration."
             )
 
+        # Surface the MCP server's own update status after projection (like
+        # settings_url / read_only_mode) so it survives any fields= filter — the
+        # model should learn about a newer ha-mcp release even from a minimal
+        # overview, the most common session-start call. Best-effort and never
+        # raises; see ha_mcp.update_check.
+        from ..update_check import get_update_field
+
+        mcp_update = await get_update_field()
+        if mcp_update is not None:
+            projected["ha_mcp_update"] = mcp_update
+
         return projected
 
     async def ha_deep_search(

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/src/ha_mcp/tools/tools_system.py

@@ -375,6 +375,15 @@ class SystemTools:
         Returns health check results from integrations, system resources, and connectivity.
         Available information varies by installation type and loaded integrations.
 
+        The result also carries an ``ha_mcp_update`` object —
+        ``{current, latest, update_available}`` — reporting whether a newer
+        ha-mcp release is available (from PyPI for pip/Docker, or the Supervisor
+        add-on store for the add-on), so you can proactively tell the user to
+        upgrade. Present on every install type including the HA add-on (so a user
+        who missed the Supervisor's update prompt still hears about it); omitted
+        only for the ``unknown`` version and when ``HA_MCP_DISABLE_UPDATE_CHECK``
+        is set.
+
         **Parameters:**
         - include: Optional comma-separated list of additional data to include.
           - "repairs": Repair items from Settings > System > Repairs (active only by default; pass `include_dismissed_repairs=True` for all)
@@ -700,6 +709,16 @@ class SystemTools:
                     result.setdefault("warnings", []).extend(section_warnings)
                 result["dead_entities"] = dead_section
 
+            # Surface the MCP server's own update status so the model can relay
+            # it in chat. ``get_update_field`` is best-effort, thread-offloaded,
+            # and never raises (omits the field on any hiccup); see
+            # ha_mcp.update_check for gating/throttle details.
+            from ..update_check import get_update_field
+
+            mcp_update = await get_update_field()
+            if mcp_update is not None:
+                result["ha_mcp_update"] = mcp_update
+
             return result
 
         except ToolError:

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/src/ha_mcp/tools/tools_updates.py

@@ -524,7 +524,7 @@ class UpdateTools:
 
         categories = {k: v for k, v in categories.items() if v}
 
-        return {
+        result: dict[str, Any] = {
             "success": True,
             "updates_available": len(available_updates),
             "skipped_count": len(skipped_updates),
@@ -533,6 +533,19 @@ class UpdateTools:
             "include_skipped": include_skipped,
         }
 
+        # Surface the MCP server's OWN update status alongside HA's updates so the
+        # model is more likely to mention "you're on X, but Y is out" — this tool
+        # is HA-centric, but spreading the ha-mcp self-update signal across the
+        # status surfaces raises the odds an AI relays it. ``get_update_field`` is
+        # best-effort and never raises; see ha_mcp.update_check for details.
+        from ..update_check import get_update_field
+
+        mcp_update = await get_update_field()
+        if mcp_update is not None:
+            result["ha_mcp_update"] = mcp_update
+
+        return result
+
     async def _get_update_details(
         self, entity_id: str, include_release_notes: bool = False
     ) -> dict[str, Any]:
@@ -702,6 +715,11 @@ class UpdateTools:
         - updates_available: Count of available updates
         - updates: List of update entities with version info
         - categories: Updates grouped by category (core, addons, devices, hacs, os)
+        - ha_mcp_update: This MCP server's own update status
+          {current, latest, update_available} — so you can flag a newer ha-mcp
+          release (from PyPI for pip/Docker, the Supervisor add-on store for the
+          add-on). Present on all install types; omitted only for the unknown
+          version and when HA_MCP_DISABLE_UPDATE_CHECK is set.
 
         RETURNS (when getting specific update):
         - Update details including installed/latest versions

ha_mcp_dev-7.8.1.dev717/src/ha_mcp/update_check.py

@@ -0,0 +1,261 @@
+"""Self-update notifier for ha-mcp.
+
+An operator can sit on an old build without ever knowing. This does a
+fail-silent check, holds the result in memory for the process, and surfaces a
+newer release via a startup log banner and the ``ha_get_overview`` /
+``ha_get_system_health`` / ``ha_get_updates`` tool fields.
+
+The comparison reference depends on how ha-mcp is deployed, because the running
+version only means something against the matching source:
+
+* **pip / Docker / stdio** — the running version IS a PyPI version, so it is
+  compared against PyPI: stable installs against ``ha-mcp``, dev installs
+  (``.dev``) against ``ha-mcp-dev``.
+* **HA add-on (stable AND dev)** — the add-on is built from source and updated
+  through the Supervisor add-on store, so its ``HA_MCP_BUILD_VERSION`` is on the
+  add-on's own counter, NOT PyPI's. The reference is therefore the Supervisor
+  add-on store (``GET /addons/self/info`` → ``version`` / ``version_latest`` /
+  ``update_available``), which is the same counter — so the dev add-on, like
+  every other deployment, correctly says "you're on X, Y is out."
+
+The check runs once per process — memoized in memory, no disk, no throttle. For
+stdio that is once per session (the server is spawned per conversation); for a
+long-running Docker/web server or the add-on, once at boot. It is a no-op for the
+``unknown`` version (PyPI path) and the ``HA_MCP_DISABLE_UPDATE_CHECK`` opt-out.
+Every network call is best-effort: any failure yields "no update info" rather
+than raising, so callers never need to guard it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, TypedDict
+
+import httpx
+from packaging.version import InvalidVersion, Version
+
+from ._version import (
+    get_supervisor_base_url,
+    get_version,
+    is_dev_version,
+    is_running_in_addon,
+)
+from .stdio_settings_sidecar import _TRUTHY  # shared HA_MCP_DISABLE_* truthy set
+
+logger = logging.getLogger(__name__)
+
+DISABLE_ENV = "HA_MCP_DISABLE_UPDATE_CHECK"
+_PYPI_JSON_URL = "https://pypi.org/pypi/{package}/json"
+_STABLE_PACKAGE = "ha-mcp"
+_DEV_PACKAGE = "ha-mcp-dev"
+# Tight timeout so the once-per-process check can never add more than a blip of
+# latency to a cold stdio spawn.
+_HTTP_TIMEOUT_SECONDS = 2.0
+
+
+@dataclass(frozen=True)
+class UpdateInfo:
+    """Result of a self-update check.
+
+    ``update_available`` is the field callers branch on; ``current`` and
+    ``latest`` are carried so a banner or tool field can show both versions.
+    """
+
+    current: str
+    latest: str
+    update_available: bool
+
+
+def _is_disabled() -> bool:
+    # Reuse the shared _TRUTHY set so HA_MCP_DISABLE_UPDATE_CHECK parses
+    # identically to the sibling HA_MCP_DISABLE_SETTINGS_UI flag: only a truthy
+    # value disables; 0/false/no/off/blank (and anything unrecognized) keep the
+    # check enabled, so a user who sets =0 to "keep it on" isn't surprised.
+    return os.environ.get(DISABLE_ENV, "").strip().lower() in _TRUTHY
+
+
+def _is_newer(latest: str, current: str) -> bool:
+    """Return True only when ``latest`` is a strictly higher PEP 440 release.
+
+    ``packaging.version`` orders dev/pre/post correctly — e.g.
+    ``7.8.0.dev714 < 7.8.0.dev720 < 7.8.0`` and ``7.8.0 < 7.9.0`` — so this works
+    for both the stable and dev channels. An unparseable version on either side
+    reads as "can't compare" → not newer (never a bogus banner).
+    """
+    try:
+        return Version(latest) > Version(current)
+    except InvalidVersion:
+        return False
+
+
+def _fetch_latest_from_pypi(package: str) -> str | None:
+    """Fetch ``package``'s latest published version from PyPI, or None on failure."""
+    try:
+        # follow_redirects=True mirrors the sibling fetch in tools_updates.py and
+        # survives any future PyPI redirect (the JSON API serves 200 directly today).
+        resp = httpx.get(
+            _PYPI_JSON_URL.format(package=package),
+            timeout=_HTTP_TIMEOUT_SECONDS,
+            follow_redirects=True,
+        )
+        resp.raise_for_status()
+        version = resp.json()["info"]["version"]
+        return version if isinstance(version, str) else None
+    except (httpx.HTTPError, KeyError, ValueError, TypeError) as err:
+        logger.debug("ha-mcp update check skipped (PyPI fetch failed: %s)", err)
+        return None
+
+
+def _fetch_supervisor_addon_info() -> dict[str, Any] | None:
+    """Return this add-on's Supervisor info dict, or None on any failure.
+
+    GET ``/addons/self/info`` carries ``version`` (installed), ``version_latest``
+    (the add-on store's latest), and ``update_available`` — all on the add-on's
+    own version counter. Sync + fail-silent, mirroring ``_fetch_latest_from_pypi``.
+    """
+    token = os.environ.get("SUPERVISOR_TOKEN")
+    if not token:
+        return None
+    try:
+        resp = httpx.get(
+            f"{get_supervisor_base_url()}/addons/self/info",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=_HTTP_TIMEOUT_SECONDS,
+        )
+        resp.raise_for_status()
+        body = resp.json()
+        # Supervisor REST envelope is {"result": "ok", "data": {...}}; some mocks
+        # return the data dict directly — handle both (mirrors settings_ui).
+        data = body.get("data") if isinstance(body, dict) and "data" in body else body
+        return data if isinstance(data, dict) else None
+    except (httpx.HTTPError, ValueError, TypeError) as err:
+        logger.debug("ha-mcp update check skipped (Supervisor fetch failed: %s)", err)
+        return None
+
+
+def _resolve_from_supervisor() -> UpdateInfo | None:
+    """Build UpdateInfo for the add-on from the Supervisor add-on store."""
+    info = _fetch_supervisor_addon_info()
+    if info is None:
+        return None
+    current = info.get("version")
+    latest = info.get("version_latest")
+    if not isinstance(current, str) or not isinstance(latest, str):
+        return None
+    return UpdateInfo(
+        current=current,
+        latest=latest,
+        update_available=bool(info.get("update_available")),
+    )
+
+
+def _resolve_update_info() -> UpdateInfo | None:
+    """Update-check logic; see ``get_update_info`` for the memo + never-raises wrapper."""
+    if _is_disabled():
+        return None
+    # In the add-on (stable OR dev), the authoritative reference is the
+    # Supervisor add-on store, which tracks the SAME version counter as the
+    # installed add-on. PyPI is the wrong reference there: the add-on builds
+    # ha-mcp from source on its own cadence (HA_MCP_BUILD_VERSION), unrelated to
+    # the ha-mcp/ha-mcp-dev PyPI counters — comparing them yields false
+    # positives/negatives. Non-add-on deployments (pip / Docker / stdio) report a
+    # real PyPI version and take the PyPI path below.
+    if is_running_in_addon():
+        return _resolve_from_supervisor()
+    current = get_version()
+    if current == "unknown":
+        return None
+    # A dev install (``.dev`` version) tracks the renamed ``ha-mcp-dev`` package;
+    # a stable install tracks ``ha-mcp``.
+    package = _DEV_PACKAGE if is_dev_version(current) else _STABLE_PACKAGE
+    latest = _fetch_latest_from_pypi(package)
+    if latest is None:
+        return None
+    return UpdateInfo(
+        current=current,
+        latest=latest,
+        update_available=_is_newer(latest, current),
+    )
+
+
+@functools.lru_cache(maxsize=1)
+def get_update_info() -> UpdateInfo | None:
+    """Return self-update info for this process, or None when no check applies.
+
+    Memoized in memory (``lru_cache``) so the network check runs once per process
+    — the startup banner warms it and the tool fields reuse it without re-hitting
+    PyPI. No disk, no throttle: a long-running server reflects its boot-time check
+    until restart, which is fine (those operators aren't watching startup logs).
+    Never raises — an unexpected failure degrades to None so the unguarded
+    startup-banner call can't break startup. Tests reset via
+    ``get_update_info.cache_clear()``.
+    """
+    try:
+        return _resolve_update_info()
+    except Exception as err:  # pragma: no cover - contract backstop
+        logger.debug("ha-mcp update check skipped (unexpected error: %s)", err)
+        return None
+
+
+class UpdateField(TypedDict):
+    """The ``ha_mcp_update`` object embedded in status-tool responses."""
+
+    current: str
+    latest: str
+    update_available: bool
+
+
+async def get_update_field() -> UpdateField | None:
+    """Return an embeddable self-update dict for tool responses, or None.
+
+    Off-loads the (memoized, networks-at-most-once-per-process) check to a thread
+    so it never blocks the event loop, and shapes the result for embedding under
+    an ``ha_mcp_update`` key. Never raises — a hiccup yields None (the tool omits
+    the field) and is logged at debug. Shared by every status tool that surfaces
+    the notice (``ha_get_overview`` / ``ha_get_system_health`` / ``ha_get_updates``)
+    so the shaping and event-loop offload live in one place.
+    """
+    try:
+        # Once the lru_cache is warm (normally at startup), the result is a
+        # sub-microsecond cache hit, so call it directly. Only the cold first
+        # call — which may hit PyPI — is offloaded to a thread so it can't block
+        # the event loop.
+        if get_update_info.cache_info().currsize > 0:
+            info = get_update_info()
+        else:
+            info = await asyncio.to_thread(get_update_info)
+    except Exception as err:  # pragma: no cover - defensive
+        logger.debug("ha-mcp self-update check skipped: %s", err)
+        return None
+    if info is None:
+        return None
+    return {
+        "current": info.current,
+        "latest": info.latest,
+        "update_available": info.update_available,
+    }
+
+
+def _running_in_docker() -> bool:
+    return os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv")
+
+
+def update_command_hint(current: str) -> str:
+    """Return a deployment- and channel-aware one-liner for how to upgrade."""
+    if is_running_in_addon():
+        # Add-on users update through the Supervisor UI, not pip/docker.
+        return "Update from Settings -> Add-ons -> Home Assistant MCP Server."
+    dev = is_dev_version(current)
+    if _running_in_docker():
+        # Dev images are tagged :dev (rolling); :stable is the stable channel.
+        tag = "dev" if dev else "stable"
+        return (
+            f"Pull the new image: docker pull "
+            f"ghcr.io/homeassistant-ai/ha-mcp:{tag} (then restart)."
+        )
+    package = _DEV_PACKAGE if dev else _STABLE_PACKAGE
+    return f"Upgrade with: pip install -U {package}."

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.1.dev715
+Version: 7.8.1.dev717
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -27,6 +27,7 @@ Requires-Dist: websockets==16.0
 Requires-Dist: cryptography==49.0.0
 Requires-Dist: pydantic-monty==0.0.18
 Requires-Dist: tzdata>=2024.1
+Requires-Dist: packaging>=24.0
 Dynamic: license-file
 
 > **Breaking change (v7.3.0):** `ha_config_set_yaml` has been moved to [beta](docs/beta.md).

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ src/ha_mcp/settings.js
 src/ha_mcp/settings_ui.py
 src/ha_mcp/smoke_test.py
 src/ha_mcp/stdio_settings_sidecar.py
+src/ha_mcp/update_check.py
 src/ha_mcp/auth/__init__.py
 src/ha_mcp/auth/consent_form.py
 src/ha_mcp/auth/provider.py

{ha_mcp_dev-7.8.1.dev715 → ha_mcp_dev-7.8.1.dev717}/src/ha_mcp_dev.egg-info/requires.txt

@@ -7,3 +7,4 @@ websockets==16.0
 cryptography==49.0.0
 pydantic-monty==0.0.18
 tzdata>=2024.1
+packaging>=24.0