ha-mcp-dev 7.8.0.dev714__tar.gz → 7.8.1.dev716__tar.gz

{ha_mcp_dev-7.8.0.dev714/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.8.1.dev716}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev714
+Version: 7.8.1.dev716
 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).
@@ -319,9 +320,16 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ## 🔍 Tool Discovery for AI Agents
 
-By default, the full tool catalog (~86 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus,) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
 
-For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing 86 tools eats ~46K tokens of idle context. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+
+### Smaller or local LLMs (Ollama, etc.)
+
+If your model can't see the tools or your Home Assistant, it may be getting handed the whole tool catalog at once and struggling with it. It's recommended to try the following to see if it helps:
+
+- **Enable tool search** (`ENABLE_TOOL_SEARCH=true`, or the add-on option below). Instead of listing every tool up front, the server defers the catalog behind a search interface so the model pulls in only the tools it needs, when it needs them.
+- **Raise the model's context window above the default.** Local runtimes ship with small defaults (Ollama's `num_ctx` is one example) that can't hold a large tool set plus the conversation — increase it well beyond the default.
 
 ### Enable search-based discovery
 
@@ -338,14 +346,14 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (~46K → ~5K idle tokens). |
+| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
 | `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
 | `PINNED_TOOLS` | empty | Comma-separated tool names to keep always visible. The web settings UI is the primary way to manage this. |
 
 ### When to enable
 
 - **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
-- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 86.
+- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 84.
 - **Cost-sensitive deployments** — fewer idle tokens per turn.
 
 Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.

{ha_mcp_dev-7.8.0.dev714 → ha_mcp_dev-7.8.1.dev716}/README.md

@@ -288,9 +288,16 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ## 🔍 Tool Discovery for AI Agents
 
-By default, the full tool catalog (~86 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus,) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
 
-For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing 86 tools eats ~46K tokens of idle context. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+
+### Smaller or local LLMs (Ollama, etc.)
+
+If your model can't see the tools or your Home Assistant, it may be getting handed the whole tool catalog at once and struggling with it. It's recommended to try the following to see if it helps:
+
+- **Enable tool search** (`ENABLE_TOOL_SEARCH=true`, or the add-on option below). Instead of listing every tool up front, the server defers the catalog behind a search interface so the model pulls in only the tools it needs, when it needs them.
+- **Raise the model's context window above the default.** Local runtimes ship with small defaults (Ollama's `num_ctx` is one example) that can't hold a large tool set plus the conversation — increase it well beyond the default.
 
 ### Enable search-based discovery
 
@@ -307,14 +314,14 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (~46K → ~5K idle tokens). |
+| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
 | `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
 | `PINNED_TOOLS` | empty | Comma-separated tool names to keep always visible. The web settings UI is the primary way to manage this. |
 
 ### When to enable
 
 - **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
-- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 86.
+- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 84.
 - **Cost-sensitive deployments** — fewer idle tokens per turn.
 
 Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.

{ha_mcp_dev-7.8.0.dev714 → ha_mcp_dev-7.8.1.dev716}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.8.0.dev714"
+version = "7.8.1.dev716"
 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.0.dev714 → ha_mcp_dev-7.8.1.dev716}/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.0.dev714 → ha_mcp_dev-7.8.1.dev716}/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.0.dev714 → ha_mcp_dev-7.8.1.dev716}/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.0.dev714 → ha_mcp_dev-7.8.1.dev716}/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.dev716/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.0.dev714 → ha_mcp_dev-7.8.1.dev716/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev714
+Version: 7.8.1.dev716
 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).
@@ -319,9 +320,16 @@ Skills can still be installed manually for clients that prefer local skill files
 
 ## 🔍 Tool Discovery for AI Agents
 
-By default, the full tool catalog (~86 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus,) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
+By default, the full tool catalog (~84 tools) is listed to the client through the standard MCP `tools/list` response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.
 
-For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing 86 tools eats ~46K tokens of idle context. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+For models *without* deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.
+
+### Smaller or local LLMs (Ollama, etc.)
+
+If your model can't see the tools or your Home Assistant, it may be getting handed the whole tool catalog at once and struggling with it. It's recommended to try the following to see if it helps:
+
+- **Enable tool search** (`ENABLE_TOOL_SEARCH=true`, or the add-on option below). Instead of listing every tool up front, the server defers the catalog behind a search interface so the model pulls in only the tools it needs, when it needs them.
+- **Raise the model's context window above the default.** Local runtimes ship with small defaults (Ollama's `num_ctx` is one example) that can't hold a large tool set plus the conversation — increase it well beyond the default.
 
 ### Enable search-based discovery
 
@@ -338,14 +346,14 @@ The proxy split lets MCP clients apply different permission policies per categor
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (~46K → ~5K idle tokens). |
+| `ENABLE_TOOL_SEARCH` | `false` | Replace full tool catalog with search-based discovery (tools deferred behind on-demand search). |
 | `TOOL_SEARCH_MAX_RESULTS` | `5` | Max results returned by `ha_search_tools` (range 2–10). |
 | `PINNED_TOOLS` | empty | Comma-separated tool names to keep always visible. The web settings UI is the primary way to manage this. |
 
 ### When to enable
 
 - **Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support** — large idle-context savings.
-- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 86.
+- MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 84.
 - **Cost-sensitive deployments** — fewer idle tokens per turn.
 
 Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.

{ha_mcp_dev-7.8.0.dev714 → ha_mcp_dev-7.8.1.dev716}/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.0.dev714 → ha_mcp_dev-7.8.1.dev716}/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