ha-mcp-dev 7.4.1.dev470__tar.gz → 7.4.1.dev472__tar.gz

{ha_mcp_dev-7.4.1.dev470/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev472}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev470
+Version: 7.4.1.dev472
 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.4.1.dev470 → ha_mcp_dev-7.4.1.dev472}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.4.1.dev470"
+version = "7.4.1.dev472"
 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.4.1.dev470 → ha_mcp_dev-7.4.1.dev472}/src/ha_mcp/client/rest_client.py

@@ -13,6 +13,7 @@ import httpx
 
 from .._version import get_supervisor_base_url, is_running_in_addon
 from ..config import get_global_settings
+from .supervisor_client import make_supervisor_httpx_client
 
 
 def _is_ssl_error(exc: BaseException) -> bool:
@@ -555,23 +556,21 @@ class HomeAssistantClient:
                 "(addon-mode gate fired but SUPERVISOR_TOKEN env var not set)"
             )
 
-        url = f"{get_supervisor_base_url()}/{path}/logs"
-        logger.debug("Fetching %s via Supervisor direct", url)
+        relative_path = f"/{path}/logs"
+        logger.debug(
+            "Fetching %s%s via Supervisor direct",
+            get_supervisor_base_url(),
+            relative_path,
+        )
 
         try:
-            async with httpx.AsyncClient(
+            async with make_supervisor_httpx_client(
                 timeout=httpx.Timeout(self.timeout),
-                # `verify` is a no-op for plain http://supervisor, but kept
-                # for symmetry with the other two direct-Supervisor httpx
-                # clients (#1128 establishes the 3-site convention).
                 verify=self.verify_ssl,
             ) as client:
                 response = await client.get(
-                    url,
-                    headers={
-                        "Authorization": f"Bearer {token}",
-                        "Accept": "text/plain",
-                    },
+                    relative_path,
+                    headers={"Accept": "text/plain"},
                 )
         except httpx.TimeoutException as e:
             raise HomeAssistantConnectionError(

ha_mcp_dev-7.4.1.dev472/src/ha_mcp/client/supervisor_client.py

@@ -0,0 +1,88 @@
+"""Shared factory for direct-Supervisor httpx clients.
+
+Three call sites in the codebase talk directly to the Home Assistant
+Supervisor REST API at ``http://supervisor`` rather than through
+``HomeAssistantClient.httpx_client`` (which is bound to HA Core, not the
+Supervisor — different base URL, different token, different role gate):
+
+- :meth:`ha_mcp.client.rest_client.HomeAssistantClient._supervisor_logs_get`
+  — fetches addon and system-service logs
+- :func:`ha_mcp.tools.tools_bug_report._fetch_addon_logs` — bundles ha-mcp's
+  own addon logs into a bug-report payload
+- :func:`ha_mcp.settings_ui._restart_addon` — POSTs ``/addons/self/restart``
+  from the settings UI
+
+All three share the same boilerplate (base URL, ``Authorization: Bearer
+${SUPERVISOR_TOKEN}`` header), so this module supplies a single factory and
+keeps the three sites consistent.
+"""
+
+from __future__ import annotations
+
+import os
+import ssl
+
+import httpx
+
+from .._version import get_supervisor_base_url
+
+__all__ = ["make_supervisor_httpx_client"]
+
+
+def make_supervisor_httpx_client(
+    *,
+    timeout: float | httpx.Timeout,
+    verify: bool | str | ssl.SSLContext,
+) -> httpx.AsyncClient:
+    """Construct an ``httpx.AsyncClient`` pre-configured for the Supervisor REST API.
+
+    Args:
+        timeout: Per-request timeout. Accepts either a plain ``float``
+            (seconds, applied to all phases) or a full :class:`httpx.Timeout`
+            for finer-grained control.
+        verify: TLS verify policy. A no-op for the default
+            ``http://supervisor`` base URL (plain HTTP — no TLS to verify),
+            but kept as a parameter because :func:`get_supervisor_base_url`
+            honours ``SUPERVISOR_BASE_URL`` env-var overrides that may be
+            HTTPS in non-add-on test rigs. The full httpx ``verify`` surface
+            (``bool``, CA-bundle path, or :class:`ssl.SSLContext`) is
+            accepted and forwarded verbatim.
+
+    Returns:
+        A new :class:`httpx.AsyncClient` bound to the Supervisor base URL
+        with ``Authorization: Bearer ${SUPERVISOR_TOKEN}`` preset. Callers
+        pass relative paths (``/addons/self/logs``) to ``client.get/post``;
+        ``base_url`` joins them onto the Supervisor host.
+
+    Raises:
+        RuntimeError: ``SUPERVISOR_TOKEN`` is unset or empty in the
+            environment. Each call site has its own absent-token policy
+            (a rich :class:`HomeAssistantAuthError`, a silent ``""``
+            return, or a 400 ``JSONResponse``) that does not share a
+            common shape, so the factory cannot translate. Detecting the
+            absence at construction time prevents a malformed
+            ``Authorization: Bearer `` header from being read as a token
+            rejection by Supervisor, which would mask the missing-env-var
+            root cause.
+
+    Note:
+        ``SUPERVISOR_TOKEN`` is read from env at construction time and
+        baked into the constructed client's ``Authorization`` header.
+        Reusing a single client across token rotations would not pick up
+        the new value — short-lived ``async with`` callers are unaffected,
+        but a future long-lived caller would need to discard and re-create.
+    """
+    token = os.environ.get("SUPERVISOR_TOKEN", "")
+    if not token:
+        raise RuntimeError(
+            "SUPERVISOR_TOKEN is not set; "
+            "make_supervisor_httpx_client cannot construct an "
+            "authenticated client. Callers must verify the token is "
+            "present before invoking the factory."
+        )
+    return httpx.AsyncClient(
+        base_url=get_supervisor_base_url(),
+        timeout=timeout,
+        verify=verify,
+        headers={"Authorization": f"Bearer {token}"},
+    )

{ha_mcp_dev-7.4.1.dev470 → ha_mcp_dev-7.4.1.dev472}/src/ha_mcp/server.py

@@ -21,6 +21,7 @@ from mcp.types import Icon
 
 from .config import _PACKAGE_VERSION, get_global_settings
 from .tools.enhanced import EnhancedToolsMixin
+from .tools.util_helpers import strip_internal_fields
 from .transforms import DEFAULT_PINNED_TOOLS
 
 if TYPE_CHECKING:
@@ -930,13 +931,19 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         return await self.client.call_service(domain, service, service_data)
 
     async def get_entities_by_area(self, area_name: str) -> dict[str, Any]:
-        """Bridge method to existing area functionality."""
-        return cast(
-            dict[str, Any],
-            await self.smart_tools.get_entities_by_area(
-                area_query=area_name, group_by_domain=True
-            ),
+        """Bridge method to existing area functionality.
+
+        ``smart_tools.get_entities_by_area`` enriches per-entity dicts
+        with leading-underscore internals (``_hidden_by`` etc.) so
+        downstream search branches can apply the score penalty without
+        a second registry lookup. Strip them here so this public bridge
+        doesn't leak internals to MCP clients.
+        """
+        result = await self.smart_tools.get_entities_by_area(
+            area_query=area_name, group_by_domain=True
         )
+        strip_internal_fields(result)
+        return cast(dict[str, Any], result)
 
     async def start(self) -> None:
         """Start the Smart MCP server with async compatibility."""

{ha_mcp_dev-7.4.1.dev470 → ha_mcp_dev-7.4.1.dev472}/src/ha_mcp/settings_ui.py

@@ -19,7 +19,8 @@ import httpx
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse
 
-from ._version import get_supervisor_base_url, is_running_in_addon
+from ._version import is_running_in_addon
+from .client.supervisor_client import make_supervisor_httpx_client
 from .errors import ErrorCode, create_error_response
 from .transforms import DEFAULT_PINNED_TOOLS
 from .utils.data_paths import get_data_dir
@@ -893,8 +894,7 @@ def register_settings_routes(
         )
 
     async def _restart_addon(_: Request) -> JSONResponse:
-        token = os.environ.get("SUPERVISOR_TOKEN")
-        if not token:
+        if not os.environ.get("SUPERVISOR_TOKEN"):
             return JSONResponse(
                 create_error_response(
                     ErrorCode.CONFIG_VALIDATION_FAILED,
@@ -906,13 +906,10 @@ def register_settings_routes(
         # Short timeout — the supervisor kills our process during restart so
         # the connection will drop. A connection drop is actually success.
         try:
-            async with httpx.AsyncClient(
+            async with make_supervisor_httpx_client(
                 timeout=5.0, verify=server.settings.verify_ssl
             ) as client:
-                resp = await client.post(
-                    f"{get_supervisor_base_url()}/addons/self/restart",
-                    headers={"Authorization": f"Bearer {token}"},
-                )
+                resp = await client.post("/addons/self/restart")
         except (httpx.ReadError, httpx.RemoteProtocolError):
             # Connection dropped mid-request — restart is happening.
             # `ConnectError` is deliberately NOT in this tuple: it fires

{ha_mcp_dev-7.4.1.dev470 → ha_mcp_dev-7.4.1.dev472}/src/ha_mcp/tools/smart_search.py

@@ -113,9 +113,10 @@ class SmartSearchTools:
         offset: int = 0,
         include_attributes: bool = False,
         domain_filter: str | None = None,
+        include_hidden: bool = True,
     ) -> dict[str, Any]:
         """
-        Advanced entity search with fuzzy matching and typo tolerance.
+        Search entities with fuzzy matching and typo tolerance.
 
         Args:
             query: Search query (can be partial, with typos)
@@ -123,16 +124,120 @@ class SmartSearchTools:
             offset: Number of results to skip for pagination
             include_attributes: Whether to include full entity attributes
             domain_filter: Optional domain to filter entities before search (e.g., "light", "sensor")
+            include_hidden: When True (default), entities with ``hidden_by``
+                set in the entity registry are still returned but receive
+                a score penalty so they sort below comparable visible
+                matches. Pass False to filter them out entirely.
 
         Returns:
             Dictionary with search results and metadata
         """
         try:
-            # Get all entities
-            entities = await self.client.get_states()
+            # HA domains are canonically lowercase and unpadded; defend
+            # the service layer so internal callers get the same
+            # normalization the tool layer applies (strip + lowercase
+            # before the prefix match downstream).
+            if domain_filter:
+                domain_filter = domain_filter.strip().lower()
+            # Fetch states + entity registry list in parallel. The slim
+            # ``list`` view gives us ``hidden_by`` (used to filter
+            # UI-hidden entities by default) and the entity_ids we need
+            # to feed into ``get_entries`` for the full-fidelity data
+            # (aliases live only in get_entries, not the slim list).
+            entities_task = self.client.get_states()
+            entity_registry_task = self.client.send_websocket_message(
+                {"type": "config/entity_registry/list"}
+            )
+            results = await asyncio.gather(
+                entities_task, entity_registry_task, return_exceptions=True
+            )
+            # States-fetch failure is fatal — auth/connection errors must
+            # propagate so the caller sees the real cause instead of a
+            # bogus "zero matches" with success=True.
+            if isinstance(results[0], BaseException):
+                raise results[0]
+            # CancelledError on the registry task must propagate too;
+            # gather captures it like any other exception when
+            # return_exceptions=True.
+            if isinstance(results[1], asyncio.CancelledError):
+                raise results[1]
+            entities = results[0]
 
-            # Filter by domain BEFORE fuzzy search if domain_filter provided
-            # This ensures fuzzy search only looks at entities in the target domain
+            # Build entity_id -> slim registry entry map. Registry-list
+            # failure is tolerated: search continues without alias /
+            # hidden awareness rather than failing the whole call.
+            registry_slim: dict[str, dict[str, Any]] = {}
+            if isinstance(results[1], dict) and results[1].get("success"):
+                for entry in results[1].get("result", []):
+                    eid = entry.get("entity_id")
+                    if eid:
+                        registry_slim[eid] = entry
+
+            # First pass: hidden filter + collect entity_ids for the
+            # alias batch fetch. Pre-filtering shrinks the get_entries
+            # payload on installations with thousands of entities.
+            survivor_ids: list[str] = []
+            survivor_states: list[dict[str, Any]] = []
+            for entity in entities:
+                eid = entity.get("entity_id", "")
+                if not eid:
+                    continue
+                slim = registry_slim.get(eid, {})
+                hidden_by = slim.get("hidden_by")
+                if hidden_by is not None and not include_hidden:
+                    continue
+                survivor_ids.append(eid)
+                survivor_states.append(entity)
+
+            # Second pass: batch-fetch full registry entries for aliases.
+            # ``config/entity_registry/list`` deliberately omits
+            # ``aliases``; ``get_entries`` includes them. One extra
+            # round-trip enriches the survivor set without N+1 fan-out.
+            aliases_map: dict[str, list[str]] = {}
+            if survivor_ids:
+                try:
+                    entries_resp = await self.client.send_websocket_message({
+                        "type": "config/entity_registry/get_entries",
+                        "entity_ids": survivor_ids,
+                    })
+                    if (
+                        isinstance(entries_resp, dict)
+                        and entries_resp.get("success")
+                    ):
+                        for eid, entry in (
+                            entries_resp.get("result", {}) or {}
+                        ).items():
+                            if isinstance(entry, dict):
+                                aliases_map[eid] = entry.get("aliases", []) or []
+                    else:
+                        logger.warning(
+                            "alias_enrichment_failed: get_entries returned "
+                            "non-success for %d entities (resp=%r)",
+                            len(survivor_ids),
+                            entries_resp,
+                        )
+                except (KeyError, TypeError, AttributeError) as alias_err:
+                    logger.warning(
+                        "alias_enrichment_failed: malformed payload for "
+                        "%d entities (err=%r)",
+                        len(survivor_ids),
+                        alias_err,
+                    )
+
+            # Enrich entities with aliases + hidden_by for the fuzzy layer.
+            enriched: list[dict[str, Any]] = []
+            for entity, eid in zip(survivor_states, survivor_ids, strict=True):
+                slim = registry_slim.get(eid, {})
+                # Shallow copy + private-prefixed keys so downstream
+                # consumers that round-trip these dicts don't ship
+                # internal fields back to clients.
+                enriched.append({
+                    **entity,
+                    "_aliases": aliases_map.get(eid, []),
+                    "_hidden_by": slim.get("hidden_by"),
+                })
+
+            entities = enriched
             if domain_filter:
                 entities = [
                     e
@@ -159,19 +264,12 @@ class SmartSearchTools:
 
                 if include_attributes:
                     result["attributes"] = match["attributes"]
-                else:
-                    # Include only essential attributes
-                    attrs = match["attributes"]
-                    essential_attrs = {}
-                    for key in [
-                        "unit_of_measurement",
-                        "device_class",
-                        "icon",
-                        "area_id",
-                    ]:
-                        if key in attrs:
-                            essential_attrs[key] = attrs[key]
-                    result["essential_attributes"] = essential_attrs
+                # No ``essential_attributes`` fallback — the other four
+                # search-type branches (exact_match, area_only,
+                # area_filtered_query, domain_listing) never emit it, so
+                # surfacing it only from fuzzy_search was a shape
+                # asymmetry. Callers needing full state should follow
+                # up with ``ha_get_state``.
 
                 results.append(result)
 
@@ -213,18 +311,25 @@ class SmartSearchTools:
             )
 
     async def get_entities_by_area(
-        self, area_query: str, group_by_domain: bool = True
+        self,
+        area_query: str,
+        group_by_domain: bool = True,
+        include_hidden: bool = True,
     ) -> dict[str, Any]:
         """
         Get entities grouped by area/room using the HA registries for accurate area resolution.
 
         Uses entity registry, device registry, and area registry to determine
         which area each entity belongs to. Fuzzy matches the query against
-        area names/IDs to find the target area(s).
+        area names, IDs, and area-registry aliases to find the target area(s).
 
         Args:
-            area_query: Area/room name to search for
+            area_query: Area/room name (or alias) to search for
             group_by_domain: Whether to group results by domain within each area
+            include_hidden: When True (default), entities with ``hidden_by``
+                set in the entity registry are still grouped under their
+                area but receive a score penalty when ranked. Pass False
+                to filter them out entirely.
 
         Returns:
             Dictionary with area-grouped entities
@@ -260,7 +365,7 @@ class SmartSearchTools:
                     if area_id:
                         area_registry[area_id] = area
 
-            # Parse entity registry: entity_id -> {area_id, device_id}
+            # Parse entity registry: entity_id -> {area_id, device_id, hidden_by}
             entity_reg_map: dict[str, dict[str, str | None]] = {}
             if isinstance(results[2], dict) and results[2].get("success"):
                 for entry in results[2].get("result", []):
@@ -269,6 +374,7 @@ class SmartSearchTools:
                         entity_reg_map[entity_id] = {
                             "area_id": entry.get("area_id"),
                             "device_id": entry.get("device_id"),
+                            "hidden_by": entry.get("hidden_by"),
                         }
 
             # Parse device registry: device_id -> area_id
@@ -279,27 +385,54 @@ class SmartSearchTools:
                     if device_id:
                         device_area_map[device_id] = device.get("area_id")
 
-            # Fuzzy match area_query against known area names and IDs
+            # Two-pass area resolution. Pass 1 collects exact id / name /
+            # alias matches; if any are found, fuzzy aggregation is
+            # skipped entirely. This makes ``area_filter`` honor a
+            # literal area_id from ``ha_config_list_areas`` — pre-fix a
+            # query like ``"bedroom_kids"`` would also fuzzy-match its
+            # parent ``"bedroom"`` (partial_ratio=100) and aggregate
+            # sibling areas' entities. Aliases (per-area registry, used
+            # by HA voice config) mirror the entity-side enrichment in
+            # smart_entity_search.
             area_query_lower = area_query.lower().strip()
-            matched_area_ids: set[str] = set()
+            exact_area_ids: set[str] = set()
+            fuzzy_area_ids: set[str] = set()
 
             for area_id, area_info in area_registry.items():
                 area_name = area_info.get("name", "")
-                # Exact match on area_id or name (case-insensitive)
+                area_aliases = area_info.get("aliases", []) or []
+                # Exact match on area_id, name, or any alias (case-insensitive)
                 if (
                     area_query_lower == area_id.lower()
                     or area_query_lower == area_name.lower()
+                    or any(
+                        area_query_lower == a.lower()
+                        for a in area_aliases
+                        if isinstance(a, str)
+                    )
                 ):
-                    matched_area_ids.add(area_id)
+                    exact_area_ids.add(area_id)
                     continue
-                # Fuzzy match on area name
+                # Fuzzy match on area name, id, or any alias
                 name_score = calculate_partial_ratio(
                     area_query_lower, area_name.lower()
                 )
                 id_score = calculate_partial_ratio(area_query_lower, area_id.lower())
-                best_score = max(name_score, id_score)
+                alias_score = max(
+                    (
+                        calculate_partial_ratio(area_query_lower, a.lower())
+                        for a in area_aliases
+                        if isinstance(a, str)
+                    ),
+                    default=0,
+                )
+                best_score = max(name_score, id_score, alias_score)
                 if best_score >= 80:
-                    matched_area_ids.add(area_id)
+                    fuzzy_area_ids.add(area_id)
+
+            # Exact matches win — fuzzy aggregation only runs when no
+            # area_query_lower is itself an area_id / name / alias.
+            matched_area_ids = exact_area_ids or fuzzy_area_ids
 
             if not matched_area_ids:
                 return {
@@ -313,10 +446,19 @@ class SmartSearchTools:
                     ],
                 }
 
-            # Build entity_id -> resolved area_id mapping
-            # Priority: entity direct area_id > device area_id
+            # Build entity_id -> resolved area_id mapping.
+            # Priority: entity direct area_id > device area_id.
+            # Hidden entities are filtered only when include_hidden is
+            # False; otherwise they pass through and downstream applies
+            # the score penalty so they sort below visible matches.
             entity_area_resolved: dict[str, str] = {}
+            hidden_entity_ids: set[str] = set()
             for entity_id, reg_info in entity_reg_map.items():
+                is_hidden = reg_info.get("hidden_by") is not None
+                if is_hidden and not include_hidden:
+                    continue
+                if is_hidden:
+                    hidden_entity_ids.add(entity_id)
                 area_id = reg_info.get("area_id")
                 device_id = reg_info.get("device_id")
                 if not area_id and device_id:
@@ -331,7 +473,12 @@ class SmartSearchTools:
                 if eid:
                     state_map[eid] = entity
 
-            # Collect entities belonging to matched areas
+            # Collect entities belonging to matched areas. Alias data is
+            # NOT enriched here — exposing private `_aliases` on a public
+            # method would leak through any caller that round-trips this
+            # response (e.g. server.py:get_entities_by_area). The
+            # area+query consumer in tools_search.py fetches aliases on
+            # its own when needed.
             formatted_areas: dict[str, dict[str, Any]] = {}
             total_entities = 0
 
@@ -360,6 +507,9 @@ class SmartSearchTools:
                         state_info = state_map.get(entity_id, {})
                         if domain not in domains:
                             domains[domain] = []
+                        # Carry ``_hidden_by`` as a sentinel ("hidden" or
+                        # None) so downstream branches can apply the
+                        # score penalty without a second registry lookup.
                         domains[domain].append(
                             {
                                 "entity_id": entity_id,
@@ -367,6 +517,11 @@ class SmartSearchTools:
                                     "friendly_name", entity_id
                                 ),
                                 "state": state_info.get("state", "unknown"),
+                                "_hidden_by": (
+                                    "hidden"
+                                    if entity_id in hidden_entity_ids
+                                    else None
+                                ),
                             }
                         )
                     area_data["entities"] = domains
@@ -381,6 +536,11 @@ class SmartSearchTools:
                             .get("friendly_name", entity_id),
                             "domain": entity_id.split(".")[0],
                             "state": state_info.get("state", "unknown"),
+                            "_hidden_by": (
+                                "hidden"
+                                if entity_id in hidden_entity_ids
+                                else None
+                            ),
                         }
                         for entity_id in area_entities
                     ]

{ha_mcp_dev-7.4.1.dev470 → ha_mcp_dev-7.4.1.dev472}/src/ha_mcp/tools/tools_bug_report.py

@@ -20,7 +20,7 @@ from pydantic import Field
 
 from ha_mcp import __version__
 
-from .._version import get_supervisor_base_url
+from ..client.supervisor_client import make_supervisor_httpx_client
 from ..config import Settings, get_global_settings
 from ..utils.usage_logger import (
     AVG_LOG_ENTRIES_PER_TOOL,
@@ -349,18 +349,14 @@ async def _fetch_addon_logs() -> str:
     """
     # Redundant with the caller's `install_method == "addon"` gate, but kept
     # as a defensive guard for any direct callers added later.
-    token = os.environ.get("SUPERVISOR_TOKEN", "")
-    if not token:
+    if not os.environ.get("SUPERVISOR_TOKEN"):
         return ""
 
     try:
-        async with httpx.AsyncClient(
+        async with make_supervisor_httpx_client(
             timeout=10.0, verify=get_global_settings().verify_ssl
         ) as http_client:
-            resp = await http_client.get(
-                f"{get_supervisor_base_url()}/addons/self/logs",
-                headers={"Authorization": f"Bearer {token}"},
-            )
+            resp = await http_client.get("/addons/self/logs")
             if resp.status_code != 200:
                 logger.info("Addon log fetch returned HTTP %s", resp.status_code)
                 return ""