ha-mcp-dev 7.6.0.dev604__tar.gz → 7.6.0.dev606__tar.gz

{ha_mcp_dev-7.6.0.dev604/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev606}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev604
+Version: 7.6.0.dev606
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.6.0.dev604 → ha_mcp_dev-7.6.0.dev606}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev604"
+version = "7.6.0.dev606"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.6.0.dev604 → ha_mcp_dev-7.6.0.dev606}/src/ha_mcp/tools/tools_filesystem.py

@@ -17,7 +17,7 @@ import asyncio
 import json
 import logging
 import weakref
-from typing import Annotated, Any
+from typing import Annotated, Any, NoReturn
 
 from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
@@ -47,6 +47,28 @@ MCP_TOOLS_DOMAIN = "ha_mcp_tools"
 # subsequent call comes back unauthorized (covers token rotation).
 CALLER_TOKEN_FIELD = "_ha_mcp_token"
 CALLER_TOKEN_BOOTSTRAP_SERVICE = "get_caller_token"
+
+# Minimum version of the ha_mcp_tools custom component that this ha-mcp
+# release expects. Bumps in lockstep with ``manifest.json`` whenever a
+# server-side behavior change requires it. Older components (no
+# ``version`` in the get_caller_token response, or a version below this)
+# get an actionable "update via HACS" error.
+MIN_COMPONENT_VERSION = "0.5.1"
+
+
+def _version_tuple(version: str) -> tuple[int, ...]:
+    """Parse ``'0.5.1'`` → ``(0, 5, 1)`` for tuple-comparison.
+
+    Raises ``ValueError`` on any non-numeric segment. Coercing a bad
+    segment to ``0`` would not actually achieve the "fail closed"
+    intent: a malformed high-order segment like ``"1.x.0"`` would
+    still parse to ``(1, 0, 0)`` and pass a ``>= (0, 5, 1)`` gate.
+    Caller routes the ValueError through ``_raise_component_too_old``
+    so the actionable update prompt fires.
+    """
+    return tuple(int(segment) for segment in version.split("."))
+
+
 # Weak-keyed by client object to support multi-client setups and self-evict
 # when a client is garbage-collected (avoids id() reuse if a freed client's
 # address gets recycled before the unauthorized-retry fires).
@@ -81,29 +103,47 @@ async def _is_bootstrap_service_registered(client: Any) -> bool:
     return False
 
 
+def _raise_component_too_old(detail: str) -> NoReturn:
+    """Single actionable 'update via HACS' error path."""
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.COMPONENT_NOT_INSTALLED,
+            f"The installed ha_mcp_tools custom component is too old: {detail}. "
+            f"This ha-mcp release requires >= {MIN_COMPONENT_VERSION}. "
+            "Update via HACS and restart Home Assistant.",
+            suggestions=[
+                "HACS → Integrations → HA MCP Tools → Update",
+                "Restart Home Assistant after update completes",
+                "Then retry the operation",
+            ],
+        )
+    )
+
+
 async def _fetch_caller_token(client: Any) -> str:
     """Call the bootstrap service and cache the returned token.
 
-    Old custom-component versions (<0.5.0) don't register get_caller_token.
-    We detect that explicitly and surface an actionable "update component"
-    error rather than a generic "no usable token" string, which would
-    otherwise be the symptom for both (a) old component installed and
-    (b) a race condition during integration setup.
+    Two version gates:
+
+    1. ``_is_bootstrap_service_registered`` — pre-0.5.0 components don't
+       ship ``get_caller_token`` at all. Surface an actionable "update"
+       error instead of letting HA return an opaque 400 to the caller.
+    2. ``MIN_COMPONENT_VERSION`` — even when the bootstrap service is
+       present, the response now carries the component's manifest
+       version. ha-mcp releases that depend on newer custom-component
+       behavior (e.g. a new accepted yaml_path key, a new schema field)
+       bump ``MIN_COMPONENT_VERSION`` together with the manifest, and
+       this check rejects 0.5.0+ components that are still behind that
+       bar with the same actionable update prompt.
+
+    Components that pre-date the version-reporting field (returned no
+    ``version`` in the response) are treated as "too old" for the same
+    reason: the absence of the field IS the signal that the component
+    doesn't yet know how to report its capabilities to ha-mcp.
     """
     if not await _is_bootstrap_service_registered(client):
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.COMPONENT_NOT_INSTALLED,
-                "The installed ha_mcp_tools custom component is too old "
-                "(pre-0.5.0) — it does not register the get_caller_token "
-                "bootstrap service that this ha-mcp version requires. "
-                "Update via HACS and restart Home Assistant.",
-                suggestions=[
-                    "HACS → Integrations → HA MCP Tools → Update",
-                    "Restart Home Assistant after update completes",
-                    "Then retry the operation",
-                ],
-            )
+        _raise_component_too_old(
+            "the get_caller_token bootstrap service is not registered (pre-0.5.0)"
         )
     result = await client.call_service(
         MCP_TOOLS_DOMAIN,
@@ -125,6 +165,19 @@ async def _fetch_caller_token(client: Any) -> str:
                 ],
             )
         )
+    raw_version: Any = unwrapped.get("version") if isinstance(unwrapped, dict) else None
+    if not isinstance(raw_version, str) or not raw_version:
+        _raise_component_too_old(
+            "the get_caller_token response did not include a version "
+            f"field (pre-{MIN_COMPONENT_VERSION})"
+        )
+    version: str = raw_version
+    try:
+        parsed = _version_tuple(version)
+    except ValueError:
+        _raise_component_too_old(f"malformed version: {version!r}")
+    if parsed < _version_tuple(MIN_COMPONENT_VERSION):
+        _raise_component_too_old(f"reported version is {version}")
     _CALLER_TOKEN_CACHE[client] = token
     return token
 

{ha_mcp_dev-7.6.0.dev604 → ha_mcp_dev-7.6.0.dev606}/src/ha_mcp/tools/tools_mcp_component.py

@@ -8,6 +8,7 @@ that are not available through standard Home Assistant APIs.
 Feature Flag: Set HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true to enable this tool.
 """
 
+import asyncio
 import logging
 from typing import Annotated, Any
 
@@ -15,6 +16,7 @@ from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
 from pydantic import Field
 
+from ..client.rest_client import HomeAssistantCommandError
 from ..errors import ErrorCode, create_error_response
 from .helpers import (
     exception_to_structured_error,
@@ -246,22 +248,54 @@ class McpComponentTools:
             repo_id = await self._resolve_repo_id(ws_client, existing_repo)
 
             logger.info(f"Installing {MCP_TOOLS_REPO} (ID: {repo_id})")
-            download_response = await ws_client.send_command(
-                "hacs/repository/download",
-                repository=repo_id,
-            )
-
-            if not download_response.get("success"):
+            # HACS' download often returns a generic "Command failed:
+            # Unknown error" on transient GitHub hiccups (rate-limit,
+            # tarball stream interruption). Retry the download with
+            # exponential backoff so a one-shot transient doesn't
+            # surface as an installation failure to the caller.
+            # ``send_command`` raises ``HomeAssistantCommandError`` on
+            # ``success: False`` responses, so the retry catches that
+            # specific class — programming bugs / connection errors
+            # propagate normally.
+            max_attempts = 3
+            backoff_seconds = 2.0
+            last_error: HomeAssistantCommandError | None = None
+            download_response: dict[str, Any] | None = None
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    download_response = await ws_client.send_command(
+                        "hacs/repository/download",
+                        repository=repo_id,
+                    )
+                    last_error = None
+                    break
+                except HomeAssistantCommandError as e:
+                    last_error = e
+                    if attempt < max_attempts:
+                        wait_for = backoff_seconds * (2 ** (attempt - 1))
+                        logger.warning(
+                            "hacs/repository/download attempt %d/%d failed (%s); "
+                            "retrying in %.1fs",
+                            attempt,
+                            max_attempts,
+                            e,
+                            wait_for,
+                        )
+                        await asyncio.sleep(wait_for)
+            if last_error is not None:
                 raise_tool_error(
                     create_error_response(
                         ErrorCode.SERVICE_CALL_FAILED,
-                        f"Failed to download repository: {download_response}",
+                        f"Failed to download repository after {max_attempts} "
+                        f"attempts: {last_error}",
                         suggestions=[
                             "Check HACS logs for errors",
                             "Verify GitHub is accessible",
+                            "HACS may be rate-limited; wait a minute and retry",
                         ],
                     )
                 )
+            assert download_response is not None  # narrowing for type checker
 
             result: dict[str, Any] = {
                 "success": True,

{ha_mcp_dev-7.6.0.dev604 → ha_mcp_dev-7.6.0.dev606}/src/ha_mcp/tools/tools_yaml_config.py

@@ -108,9 +108,13 @@ class YamlConfigTools:
                     "For YAML-mode dashboards, "
                     "use the dotted form 'lovelace.dashboards.<url_path>' where "
                     "<url_path> is lowercase, hyphenated, and not a reserved HA "
-                    "route. No other dotted paths are supported. Not for template "
-                    "sensors (use ha_config_set_helper), automations, scripts, "
-                    "scenes, or input_* helpers — those have dedicated tools."
+                    "route. No other multi-segment paths are supported. "
+                    "'automation', 'script', and 'scene' are accepted only when "
+                    "file is under packages/*.yaml; in configuration.yaml use "
+                    "the dedicated storage-mode tools "
+                    "(ha_config_set_automation, ha_config_set_script, "
+                    "ha_config_set_scene). Not for template sensors or "
+                    "input_* helpers — those have dedicated tools."
                 ),
             ),
         ],
@@ -162,9 +166,9 @@ class YamlConfigTools:
 
         - Template sensors (state-based or trigger-based) ->
           ha_config_set_helper(helper_type='template')
-        - Automations -> ha_config_set_automation
-        - Scripts -> ha_config_set_script
-        - Scenes -> ha_config_set_scene
+        - Automations (storage-mode) -> ha_config_set_automation
+        - Scripts (storage-mode) -> ha_config_set_script
+        - Scenes (storage-mode) -> ha_config_set_scene
         - All 27 helper types (input_*, counter, timer, schedule, zone, person,
           tag, group, min_max, threshold, derivative, statistics, utility_meter,
           trend, filter, switch_as_x, etc.) -> ha_config_set_helper
@@ -174,10 +178,16 @@ class YamlConfigTools:
         for integrations with significant YAML-only configuration (knx
         entities in package files), and for registering YAML-mode dashboards via
         ``lovelace.dashboards.<url_path>`` (no other ``lovelace.*`` keys).
+        Also accepts ``automation``, ``script``, and ``scene`` keys when
+        ``file`` is a ``packages/*.yaml`` — for git-managed YAML configs
+        that track these alongside templates and other YAML items. Writes
+        to ``configuration.yaml`` for those three keys remain rejected so
+        storage-mode and YAML-mode collections don't collide; use the
+        dedicated storage-mode tools instead.
         Check ``post_action`` in the response: most keys need a full HA
-        restart; template, mqtt, and group support reload. Preserves YAML
-        comments and HA tags (``!include``, ``!secret``) on round-trip;
-        ``replace`` swaps the subtree as-is.
+        restart; template, mqtt, group, automation, script, and scene
+        support reload. Preserves YAML comments and HA tags (``!include``,
+        ``!secret``) on round-trip; ``replace`` swaps the subtree as-is.
 
         For detailed routing guidance, use ha_get_skill_guide.
         """

{ha_mcp_dev-7.6.0.dev604 → ha_mcp_dev-7.6.0.dev606/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev604
+Version: 7.6.0.dev606
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT