ha-mcp-dev 8.6.0.dev2968__tar.gz → 8.6.0.dev2973__tar.gz

{ha_mcp_dev-8.6.0.dev2968 → ha_mcp_dev-8.6.0.dev2973}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2968
+Version: 8.6.0.dev2973
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.6.0.dev2968 → ha_mcp_dev-8.6.0.dev2973}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2968"
+version = "8.6.0.dev2973"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
@@ -121,8 +121,10 @@ ignore_errors = true
 module = [
     "homeassistant.*",
     "awesomeversion",
+    "hass_frontend",
     "jsonschema",
     "psutil",
+    "quickjs",
 ]
 ignore_missing_imports = true
 
@@ -305,6 +307,7 @@ dev = [
     "pytest>=8.4.2",
     "pytest-asyncio>=1.1.0",
     "pytest-timeout>=2.3.0",
+    "quickjs-ng==0.17.0.1",
     "pytest-rerunfailures>=15.0",
     "voluptuous>=0.15.2",
     "voluptuous-openapi>=0.4.1",

{ha_mcp_dev-8.6.0.dev2968 → ha_mcp_dev-8.6.0.dev2973}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2968"
+version = "8.6.0.dev2973"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's
@@ -157,8 +157,10 @@ ignore_errors = true
 module = [
     "homeassistant.*",
     "awesomeversion",
+    "hass_frontend",
     "jsonschema",
     "psutil",
+    "quickjs",
 ]
 ignore_missing_imports = true
 
@@ -391,6 +393,8 @@ dev = [
     "pytest>=8.4.2",
     "pytest-asyncio>=1.1.0",
     "pytest-timeout>=2.3.0",
+    # Exercise the component's real sandbox thread affinity in focused unit tests.
+    "quickjs-ng==0.17.0.1",
     "pytest-rerunfailures>=15.0",
     # Real voluptuous for the config-flow tests (the component's
     # config_flow imports it; HA provides it at runtime, tests need it here).

{ha_mcp_dev-8.6.0.dev2968 → ha_mcp_dev-8.6.0.dev2973}/src/ha_mcp/client/websocket_client.py

@@ -481,15 +481,8 @@ class HomeAssistantWebSocketClient:
             await self._send_auth()
 
             # Wait for auth response
-            auth_response = await self._wait_for_auth_message(
-                message_type="auth_ok", timeout=5
-            )
+            auth_response = await self._wait_for_auth_message("auth_ok", timeout=5)
             if not auth_response:
-                auth_invalid = await self._wait_for_auth_message(
-                    message_type="auth_invalid", timeout=1
-                )
-                if auth_invalid:
-                    raise HomeAssistantAuthError("Authentication failed: Invalid token")
                 raise HomeAssistantConnectionError("Authentication timeout")
 
             self._state.mark_authenticated()
@@ -559,6 +552,8 @@ class HomeAssistantWebSocketClient:
         start_time = time.time()
 
         while time.time() - start_time < timeout:
+            if isinstance(self._last_connect_exception, HomeAssistantAuthError):
+                raise self._last_connect_exception
             message = self._state.consume_auth_message(message_type)
             if message:
                 return message
@@ -617,6 +612,10 @@ class HomeAssistantWebSocketClient:
 
         # Handle authentication messages (store for auth sequence)
         if message_type in ["auth_required", "auth_ok", "auth_invalid"]:
+            if message_type == "auth_invalid":
+                self._last_connect_exception = HomeAssistantAuthError(
+                    "Authentication failed: Invalid token"
+                )
             self._state.store_auth_message(message_type, data)
             return
 

{ha_mcp_dev-8.6.0.dev2968 → ha_mcp_dev-8.6.0.dev2973}/src/ha_mcp/server_tool_text.py

@@ -290,7 +290,7 @@ LITE_DOCSTRINGS: dict[str, str] = {
     "ha_config_get_dashboard": (
         "Get Home Assistant dashboard info (list mode, search "
         "mode, or full config).\n\n"
-        "Three modes: (1) list — `list_only=True` returns all "
+        "Four modes: (1) list — `list_only=True` returns all "
         "storage-mode dashboards with metadata. (2) search — pass "
         "any of `entity_id`, `card_type`, `heading` to find cards "
         "(including nested ones, with a `python_path`) inside a "
@@ -301,9 +301,13 @@ LITE_DOCSTRINGS: dict[str, str] = {
         "returns the full Lovelace config plus a stable "
         "`config_hash`. Use `url_path='default'` for the main "
         "dashboard. For known JSON Pointer paths, use "
-        "ha_config_set_dashboard(patch=..., config_hash=...).\n\n"
-        "For card-type taxonomy and search workflow examples, see "
-        "ha_get_skill_guide."
+        "ha_config_set_dashboard(patch=..., config_hash=...). (4) "
+        "describe — `describe=True` with `card_type` returns that "
+        "card's fields from Home Assistant's card editor; omit "
+        "`card_type` to list the card types. Describe requires the "
+        "ha_mcp_tools component with dashboard-card support. Without it, "
+        "use ha_get_skill_guide(file='references/dashboard-cards.md') "
+        "for card-selection guidance."
     ),
     "ha_config_set_dashboard": (
         "Create or update a Home Assistant dashboard.\n\n"

{ha_mcp_dev-8.6.0.dev2968 → ha_mcp_dev-8.6.0.dev2973}/src/ha_mcp/tools/config_helpers/describe.py

@@ -69,18 +69,18 @@ def compact_field(field: dict[str, Any]) -> dict[str, Any]:
         kind, cfg = next(iter(field["selector"].items()))
         cfg = cfg if isinstance(cfg, dict) else {}
         out["type"] = kind
-        if "options" in cfg:
+        if isinstance(cfg.get("options"), list | tuple):
             out["options"] = _option_values(cfg["options"])
         out.update(
             {k: cfg[k] for k in _SELECTOR_KEYS if cfg.get(k) not in (None, False)}
         )
-    elif field.get("type") == "expandable":
+    elif field.get("type") in {"expandable", "grid"}:
         out["type"] = "section"
         out["fields"] = [compact_field(f) for f in field.get("schema", [])]
     else:
         if "type" in field:
             out["type"] = field["type"]
-        if "options" in field:
+        if isinstance(field.get("options"), list | tuple):
             out["options"] = _option_values(field["options"])
         out.update({k: field[k] for k in _SERIALIZED_KEYS if k in field})
     if field.get("default") is not None:

ha_mcp_dev-8.6.0.dev2973/src/ha_mcp/tools/dashboard_card_describe.py

@@ -0,0 +1,161 @@
+"""Describe Lovelace card types from Home Assistant's own frontend (issue #2632).
+
+The ``ha_mcp_tools`` component reads each card editor's form from the frontend
+Home Assistant serves; this module compacts it the way helper ``describe`` does.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..client.websocket_client import get_websocket_client
+from ..errors import ErrorCode, create_error_response
+from .component_api import (
+    component_supports,
+    get_component_caps,
+    invalidate_caps,
+    is_unknown_command,
+)
+from .config_helpers.describe import compact_field
+from .helpers import exception_to_structured_error, raise_tool_error
+
+WS_DASHBOARD_CARDS = "ha_mcp_tools/dashboard_cards"
+
+
+def _flatten(schema: list[Any]) -> list[dict[str, Any]]:
+    """Match ha-form storage: named nodes nest unless explicitly flattened."""
+    fields: list[dict[str, Any]] = []
+    for node in schema:
+        if not isinstance(node, dict) or node.get("type") == "divider":
+            continue
+        children = node.get("schema") if isinstance(node.get("schema"), list) else None
+        if children is not None and node.get("name") and not node.get("flatten"):
+            fields.append({**node, "schema": _flatten(children)})
+        elif children is not None:
+            fields.extend(_flatten(children))
+        elif node.get("name"):
+            fields.append(node)
+    return fields
+
+
+async def describe_card_response(client: Any, card_type: str | None) -> dict[str, Any]:
+    """The card type list, or one card type's fields as its UI editor defines them."""
+    card_type = card_type or None
+    caps = await get_component_caps(client)
+    if not component_supports(caps, "dashboard_cards"):
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.COMPONENT_NOT_INSTALLED,
+                "Describing card types needs the ha_mcp_tools custom component "
+                "with dashboard card support.",
+                suggestions=[
+                    "Install or update the HA-MCP Custom Component through HACS",
+                    "Restart Home Assistant after the update completes",
+                ],
+                context={"action": "describe", "card_type": card_type},
+            )
+        )
+    try:
+        ws = await get_websocket_client(
+            url=client.base_url,
+            token=client.token,
+            verify_ssl=getattr(client, "verify_ssl", None),
+        )
+        kwargs = {"card_type": card_type} if card_type else {}
+        raw = await ws.send_command(WS_DASHBOARD_CARDS, **kwargs)
+    except Exception as exc:  # noqa: BLE001
+        if is_unknown_command(exc):
+            invalidate_caps(client)
+        exception_to_structured_error(
+            exc, context={"action": "describe", "card_type": card_type}
+        )
+    result = raw.get("result") if isinstance(raw, dict) else None
+    if not isinstance(result, dict):
+        result = {}
+    if result.get("success") is not True:
+        error = result.get("error")
+        if error in ("custom_cards_loading", "custom_card_not_inspected"):
+            status = result.get("custom_status", {})
+            loading = error == "custom_cards_loading"
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    "Custom card inspection is still loading; retry shortly."
+                    if loading
+                    else "This custom card could not be inspected from dashboard resources.",
+                    suggestions=["Retry after resource loading finishes"]
+                    if loading
+                    else [
+                        "Check the resource inspection status and type spelling",
+                        "Cards loaded through extra JavaScript may work in the browser without appearing in dashboard resources",
+                    ],
+                    context={
+                        "action": "describe",
+                        "card_type": card_type,
+                        "custom_status": status,
+                    },
+                )
+            )
+        if error == "unknown_card_type":
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    f"'{card_type}' is not a known card type.",
+                    suggestions=[
+                        "Use one of: " + ", ".join(result.get("card_types", [])),
+                    ],
+                    context={"action": "describe", "card_type": card_type},
+                )
+            )
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "Home Assistant's card definitions are unavailable.",
+                details=str(error),
+                suggestions=[
+                    "Use ha_get_skill_guide(file='references/dashboard-cards.md') for static card guidance"
+                ],
+                context={"action": "describe", "card_type": card_type},
+            )
+        )
+    if card_type is None:
+        return {
+            "success": True,
+            "card_types": result.get("card_types", []),
+            **(
+                {"custom_status": result["custom_status"]}
+                if "custom_status" in result
+                else {}
+            ),
+        }
+    fields = result.get("fields")
+    response: dict[str, Any] = {
+        "success": True,
+        "card_type": card_type,
+        "name": result.get("name"),
+        "description": result.get("description"),
+        "fields": [compact_field(f) for f in _flatten(fields)]
+        if isinstance(fields, list)
+        else None,
+    }
+    response.update(
+        {
+            key: value
+            for key, value in result.items()
+            if key in ("field_coverage", "note")
+        }
+    )
+    if response["fields"] is None:
+        response["note"] = " ".join(
+            filter(None, (response.get("note"), _no_fields_note(card_type)))
+        )
+    return response
+
+
+def _no_fields_note(card_type: str) -> str:
+    if card_type.startswith("custom:"):
+        return "The custom card's editor fields could not be inspected; the card may still work in the browser."
+    note = "No inspectable field form was found for this card."
+    if card_type in {"grid", "horizontal-stack", "vertical-stack", "conditional"}:
+        note += " This card nests other cards under cards or card."
+    return note

{ha_mcp_dev-8.6.0.dev2968 → ha_mcp_dev-8.6.0.dev2973}/src/ha_mcp/tools/tools_config_dashboards.py

@@ -67,6 +67,7 @@ from .config_write_helpers import (
     augment_error_dict_with_skill_content,
     augment_tool_error_with_skill_content,
 )
+from .dashboard_card_describe import describe_card_response
 from .dashboard_edit_errors import (
     raise_dashboard_edit_error,
     raise_dashboard_edit_fetch_error,
@@ -122,24 +123,27 @@ class _DashboardScreenshotOptions:
     render_timeout_seconds: float = DEFAULT_RENDER_TIMEOUT_SECONDS
 
 
-# dashboard-guide.md + dashboard-cards.md cover layout patterns and the
-# card-type taxonomy — both relevant on every dashboard write.
-_DASHBOARD_SKILL_FILES: tuple[str, ...] = (
-    "references/dashboard-guide.md",
-    "references/dashboard-cards.md",
-)
+# Live card fields replace the static reference only on capable components.
+_DASHBOARD_SKILL_FILES: tuple[str, ...] = ("references/dashboard-guide.md",)
 
 
-def _attach_dashboard_skill(response: dict[str, Any], MandatoryBPS: bool) -> None:
+async def _attach_dashboard_skill(
+    response: dict[str, Any], MandatoryBPS: bool, client: Any
+) -> None:
     """In-place attach skill_content to a dashboard response when applicable.
 
     Delegates to the shared :func:`attach_skill_content` so the
     missing-vendor-warning path is consistent across every write tool.
     """
+    files = _DASHBOARD_SKILL_FILES
+    if MandatoryBPS and not component_supports(
+        await get_component_caps(client), "dashboard_cards"
+    ):
+        files += ("references/dashboard-cards.md",)
     attach_skill_content(
         response,
         MandatoryBPS=MandatoryBPS,
-        canonical_files=_DASHBOARD_SKILL_FILES,
+        canonical_files=files,
         referenced_files=None,
     )
 
@@ -1789,7 +1793,7 @@ class DashboardConfigTools:
     @tool(
         name="ha_config_get_dashboard",
         tags={"Dashboards"},
-        annotations=read_only_hints("Get Dashboard", open_world=False),
+        annotations=read_only_hints("Get Dashboard", open_world=True),
     )
     @log_tool_usage
     async def ha_config_get_dashboard(
@@ -1874,6 +1878,10 @@ class DashboardConfigTools:
                 "find across all storage-mode dashboards. Ignored otherwise."
             ),
         ] = None,
+        describe: Annotated[
+            bool,
+            Field(description="Return card_type's fields from HA's card editor"),
+        ] = False,
     ) -> "dict[str, Any] | ToolResult":
         """Get dashboard info - list all dashboards, get config, or search for cards.
 
@@ -1931,15 +1939,11 @@ class DashboardConfigTools:
         - Find cards by entity (wildcards allowed): ha_config_get_dashboard(url_path="my-dash", entity_id="sensor.temperature_*")
         - Find heading: ha_config_get_dashboard(url_path="my-dash", heading="Climate", card_type="heading")
         - Which dashboards use an entity: ha_config_get_dashboard(mode="search", query="light.bedroom")
-
-        SEARCH WORKFLOW EXAMPLE:
-        1. find = ha_config_get_dashboard(url_path="my-dash", entity_id="light.bedroom")
-        2. ha_config_set_dashboard(
-               url_path="my-dash",
-               config_hash=find["config_hash"],
-               python_transform=f'config{find["matches"][0]["python_path"]}["icon"] = "mdi:lamp"'
-           )
+        - Fields of a card type before writing one (omit card_type to list types):
+          ha_config_get_dashboard(card_type="tile", describe=True)
         """
+        if describe:
+            return await describe_card_response(self._client, card_type)
         screenshot_options = _DashboardScreenshotOptions(view_path=view_path)
         search_mode = (
             entity_id is not None or card_type is not None or heading is not None
@@ -2074,12 +2078,7 @@ class DashboardConfigTools:
         return list_result
 
     async def _fetch_search_dashboard_config(
-        self,
-        url_path: str | None,
-        *,
-        entity_id: str | None,
-        card_type: str | None,
-        heading: str | None,
+        self, url_path: str | None
     ) -> tuple[dict[str, Any], str | None, str | None]:
         """Fetch + resolve the dashboard config for search mode.
 
@@ -2272,9 +2271,7 @@ class DashboardConfigTools:
             config,
             url_path,
             search_resolved_from,
-        ) = await self._fetch_search_dashboard_config(
-            url_path, entity_id=entity_id, card_type=card_type, heading=heading
-        )
+        ) = await self._fetch_search_dashboard_config(url_path)
         # Surface the canonicalized url_path to the caller's scope now, so
         # an unexpected exception from the search/hashing below still
         # reports the resolved identifier (see ha_config_get_dashboard's
@@ -2726,7 +2723,7 @@ class DashboardConfigTools:
             "Create or Update Dashboard",
             destructive=True,
             idempotent=False,
-            open_world=False,
+            open_world=True,
         ),
     )
     @with_auto_backup(domain="dashboard", id_param="url_path")
@@ -2835,8 +2832,8 @@ class DashboardConfigTools:
         """Create or update a Home Assistant dashboard.
 
         MUST call ha_get_skill_guide OR refer to your locally installed skills first.
-        `dashboard-guide.md` and `dashboard-cards.md` ship under `skill_content`
-        by default.
+        `dashboard-guide.md` ships under `skill_content` by default. A card's
+        fields: ha_config_get_dashboard(card_type=..., describe=True).
 
         MODES (pick one):
         - patch: edit known paths with literal values using JSON Patch
@@ -3395,7 +3392,7 @@ class DashboardConfigTools:
             result["message"] = f"Dashboard {url_path} unchanged"
         if edit["post_write_verified"]:
             _attach_dashboard_render_paths(result, url_path, edit["config"])
-        _attach_dashboard_skill(result, MandatoryBPS)
+        await _attach_dashboard_skill(result, MandatoryBPS, self._client)
         return await _maybe_attach_screenshot(
             result,
             url_path,
@@ -3961,7 +3958,7 @@ class DashboardConfigTools:
         render_config = await self._attach_dashboard_write_result(
             result_dict, url_path, render_config, native_result
         )
-        _attach_dashboard_skill(result_dict, MandatoryBPS)
+        await _attach_dashboard_skill(result_dict, MandatoryBPS, self._client)
         return await _maybe_attach_screenshot(
             result_dict,
             url_path,

{ha_mcp_dev-8.6.0.dev2968 → ha_mcp_dev-8.6.0.dev2973}/src/ha_mcp/tools/tools_hacs.py

@@ -18,6 +18,7 @@ from ..client.rest_client import (
     HomeAssistantCommandError,
     HomeAssistantCommandTimeout,
 )
+from ..client.websocket_client import HomeAssistantWebSocketClient
 from ..errors import ErrorCode, create_error_response
 from .hacs_registration import (
     CATEGORY_MAP,
@@ -42,7 +43,7 @@ from .tool_hints import read_only_hints, write_hints
 logger = logging.getLogger(__name__)
 
 
-async def _assert_hacs_available() -> None:
+async def _assert_hacs_available(ws_client: HomeAssistantWebSocketClient) -> None:
     """Raise ToolError if HACS is not installed or not responding.
 
     Distinguishes "unknown command" (HACS not installed) from other failures
@@ -52,9 +53,6 @@ async def _assert_hacs_available() -> None:
     exception_to_structured_error, so connection failures are classified
     correctly rather than masked as COMPONENT_NOT_INSTALLED.
     """
-    from ..client.websocket_client import get_websocket_client
-
-    ws_client = await get_websocket_client()
     response = await ws_client.send_command("hacs/info")
     if response.get("success"):
         return
@@ -129,6 +127,18 @@ class HacsTools:
     def __init__(self, client: Any) -> None:
         self._client = client
 
+    async def _get_hacs_client(self) -> HomeAssistantWebSocketClient:
+        """Check HACS on the current request's connection, including OAuth users."""
+        from ..client.websocket_client import get_websocket_client
+
+        ws_client = await get_websocket_client(
+            url=self._client.base_url,
+            token=self._client.token,
+            verify_ssl=self._client.verify_ssl,
+        )
+        await _assert_hacs_available(ws_client)
+        return ws_client
+
     @tool(
         name="ha_get_hacs_info",
         tags={"HACS"},
@@ -377,13 +387,7 @@ class HacsTools:
             ctx, progress=0, total=3, message="checking HACS availability"
         )
 
-        # Check if HACS is available
-        await _assert_hacs_available()
-
-        # Get all repositories via WebSocket
-        from ..client.websocket_client import get_websocket_client
-
-        ws_client = await get_websocket_client()
+        ws_client = await self._get_hacs_client()
 
         # Build command parameters - map user-friendly category to HACS internal name
         kwargs_cmd: dict[str, Any] = {}
@@ -441,12 +445,7 @@ class HacsTools:
         return {"success": True, **wrapped}
 
     async def _hacs_info(self, repository_id: str) -> dict[str, Any]:
-        # Check if HACS is available
-        await _assert_hacs_available()
-
-        from ..client.websocket_client import get_websocket_client
-
-        ws_client = await get_websocket_client()
+        ws_client = await self._get_hacs_client()
 
         # If repository_id contains a slash, it's a GitHub path - look up numeric ID
         actual_id, _ = await _resolve_hacs_repo_id(ws_client, repository_id)
@@ -534,12 +533,7 @@ class HacsTools:
                 "Or pass a GitHub path like 'owner/repo' to install by name",
             ],
         )
-        # Check if HACS is available
-        await _assert_hacs_available()
-
-        from ..client.websocket_client import get_websocket_client
-
-        ws_client = await get_websocket_client()
+        ws_client = await self._get_hacs_client()
 
         # Resolve GitHub path to numeric ID if needed
         actual_id, repo_name = await _resolve_hacs_repo_id(ws_client, repository_id)
@@ -627,11 +621,7 @@ class HacsTools:
                 "Or pass a GitHub path like 'owner/repo' to remove by name",
             ],
         )
-        await _assert_hacs_available()
-
-        from ..client.websocket_client import get_websocket_client
-
-        ws_client = await get_websocket_client()
+        ws_client = await self._get_hacs_client()
 
         actual_id, repo_name = await _resolve_hacs_repo_id(ws_client, repository_id)
 
@@ -756,11 +746,7 @@ class HacsTools:
                 "Or pass a GitHub path like 'owner/repo' to refresh by name",
             ],
         )
-        await _assert_hacs_available()
-
-        from ..client.websocket_client import get_websocket_client
-
-        ws_client = await get_websocket_client()
+        ws_client = await self._get_hacs_client()
 
         actual_id, repo_name = await _resolve_hacs_repo_id(ws_client, repository_id)
 
@@ -829,8 +815,7 @@ class HacsTools:
     async def _hacs_add_repository(
         self, repository: str, category: str
     ) -> dict[str, Any]:
-        # Check if HACS is available
-        await _assert_hacs_available()
+        ws_client = await self._get_hacs_client()
 
         # Validate repository format
         if "/" not in repository:
@@ -845,11 +830,6 @@ class HacsTools:
                 )
             )
 
-        # Add repository via WebSocket
-        from ..client.websocket_client import get_websocket_client
-
-        ws_client = await get_websocket_client()
-
         # Map user-friendly category to HACS internal name
         hacs_category = CATEGORY_MAP.get(category, category)