Merge remote-tracking branch 'upstream/master' into issue-2239-dependency-diagnostics

Author: kingpanther13

custom_components/ha_mcp_tools/websocket_api.py

@@ -2,9 +2,10 @@
 
 This module registers versioned ``ha_mcp_tools/*`` WebSocket commands that the
 ha-mcp server calls in-process (same HA core, no REST/WS round-trips) behind a
-capability gate. It registers twenty-two commands (twenty-two capabilities — the
-``search_visibility`` capability is a flag on the existing ``search`` command,
-and ``info`` itself carries no capability entry):
+capability gate. It registers twenty-three commands. It advertises twenty-five
+capabilities: twenty-two command capabilities plus three additive flags
+(dashboards_doc_search, search_visibility, and search_entity_membership);
+the info handshake carries no capability entry:
 
 * ``ha_mcp_tools/info`` — the handshake: ``schema_version`` + ``capabilities[]``
   + ``component_version`` + advisory ``limits`` + the instance ``timezone``
@@ -13,6 +14,7 @@
   negotiation, NOT a version floor).
 * ``ha_mcp_tools/search`` — a unified in-process search over live registries and
   states, joined and scored, mirroring today's ``ha_search`` response envelope.
+  The search_entity_membership flag gates opt-in generic group metadata.
 * ``ha_mcp_tools/overview`` — the raw in-process reads the server's
   ``get_system_overview`` + ``ha_get_overview`` wrapper consume (states,
   services, entity/device/area registries, ``hass.config``, persistent
@@ -262,7 +264,7 @@
 
 import logging
 import re
-from collections.abc import Mapping
+from collections.abc import Collection, Mapping
 from dataclasses import dataclass
 from difflib import SequenceMatcher
 from pathlib import Path
@@ -336,12 +338,15 @@
 # bump it (the server checks ``schema_version >= N`` before using a new shape).
 SCHEMA_VERSION = 1
 
-# Which commands exist. Grows one entry per shipped command; the server gates
+# Advertised command support and additive feature flags; the server gates
 # each consumer on ``capability in caps.capabilities``. Never remove an entry
 # without a major bump. (``info`` is always present in 1.1.0+, so it carries no
 # capability key of its own.)
 CAPABILITIES: list[str] = [
     "search",
+    # A flag on search: gates its additive result_fields request and generic
+    # is_group/member_entity_ids response fields.
+    "search_entity_membership",
     "overview",
     "helpers_list",
     "states",
@@ -650,13 +655,15 @@ def _visibility_param_schema() -> Any:
 
 
 def _search_schema() -> dict[Any, Any]:
+    """Build the schema for search WebSocket requests."""
     return {
         vol.Required("type"): WS_SEARCH,
         vol.Optional("query"): vol.Any(str, None),
         vol.Optional("search_types"): [vol.In(ALL_SEARCH_TYPES)],
         vol.Optional("domain_filter"): str,
         vol.Optional("area_filter"): str,
         vol.Optional("state_filter"): str,
+        vol.Optional("result_fields"): [vol.In(("is_group", "member_entity_ids"))],
         vol.Optional("exact", default=True): bool,
         vol.Optional("include_hidden", default=True): bool,
         vol.Optional("include_config", default=False): bool,
@@ -1011,6 +1018,7 @@ def _do_search(
     domain_filter = params.get("domain_filter")
     area_filter = params.get("area_filter")
     state_filter = params.get("state_filter")
+    membership_requested = bool(params.get("result_fields"))
     # Opt-in visibility filter (search_visibility capability). A non-empty dict of
     # the server's raw VisibilityConfig fields; applied as a hard entity exclude.
     visibility = params.get("visibility")
@@ -1023,6 +1031,7 @@ def _do_search(
     # filter is applied. Surfaced additively so the fast path isn't silent about
     # incomplete filtering (parity with the server's load_hidden_set warnings).
     visibility_warnings: list[str] = []
+    hidden: set[str] = set()
 
     # ``secret_values`` (loaded off-loop by _search_prep) scrubs resolved-!secret
     # plaintext from the config-body match corpus: a YAML-loaded automation/script/
@@ -1045,6 +1054,7 @@ def _do_search(
             domain_filter=domain_filter,
             area_filter=area_filter,
             state_filter=state_filter,
+            include_membership=membership_requested,
         )
         # Opt-in visibility filter: a hard exclude applied BEFORE counts/pagination,
         # exactly where the legacy path drops ``visibility_hidden`` entities at the
@@ -1078,8 +1088,17 @@ def _do_search(
         scored_entities.sort(key=lambda r: (-r["score"], r["entity_id"]))
         entity_total = len(scored_entities)
         page = scored_entities[offset : offset + limit]
+        _redact_hidden_members(
+            page,
+            hidden,
+            view=view,
+            include_hidden=include_hidden,
+            enabled=membership_requested,
+        )
         entity_has_more = offset + len(page) < entity_total
-        entities = [_project_entity(r) for r in page]
+        entities = [
+            _project_entity(r, include_membership=membership_requested) for r in page
+        ]
 
     # --- Config surfaces (automations + scripts + scenes + helpers) ----------
     # One combined pagination window, mirroring the server's config branch.
@@ -1277,6 +1296,7 @@ def _search_entities(
     domain_filter: str | None,
     area_filter: str | None,
     state_filter: str | None,
+    include_membership: bool = False,
 ) -> list[dict[str, Any]]:
     """Score every state against the query over the joined registry view."""
     results: list[dict[str, Any]] = []
@@ -1286,7 +1306,7 @@ def _search_entities(
     # matches state_filter="vacation").
     state_filter_lower = state_filter.lower() if state_filter is not None else None
     for state in _iter_states(hass):
-        rec = _entity_record(state, view)
+        rec = _entity_record(state, view, include_membership=include_membership)
         if domain_filter and rec["domain"] != domain_filter:
             continue
         if rec["_hidden"] and not include_hidden:
@@ -1448,12 +1468,15 @@ def _registry_enrichment(view: _RegistryView, entity_id: str) -> dict[str, Any]:
     }
 
 
-def _entity_record(state: Any, view: _RegistryView) -> dict[str, Any]:
+def _entity_record(
+    state: Any, view: _RegistryView, *, include_membership: bool = False
+) -> dict[str, Any]:
     """Join a state with the entity/device/area/floor/label registries."""
     entity_id = getattr(state, "entity_id", "") or ""
     domain = entity_id.split(".")[0] if "." in entity_id else ""
     attrs = getattr(state, "attributes", None) or {}
     friendly = attrs.get("friendly_name", entity_id)
+    members = _normalize_member_entity_ids(attrs) if include_membership else None
 
     join = _registry_enrichment(view, entity_id)
     area_name = join["area"]
@@ -1481,6 +1504,14 @@ def _entity_record(state: Any, view: _RegistryView) -> dict[str, Any]:
         "floor": floor_name,
         "labels": label_names,
         "aliases": aliases,
+        **(
+            {
+                "is_group": members is not None,
+                **({"member_entity_ids": members} if members is not None else {}),
+            }
+            if include_membership
+            else {}
+        ),
         "_hidden": join["_hidden"],
         "_area_id": join["_area_id"],
         "_match_texts": match_texts,
@@ -1495,7 +1526,9 @@ def _entity_matches_area(rec: dict[str, Any], area_filter_lower: str) -> bool:
     return bool(area_name and str(area_name).lower() == area_filter_lower)
 
 
-def _project_entity(rec: dict[str, Any]) -> dict[str, Any]:
+def _project_entity(
+    rec: dict[str, Any], *, include_membership: bool = False
+) -> dict[str, Any]:
     """Strip internal ``_``-prefixed keys for the wire response."""
     return {
         "entity_id": rec["entity_id"],
@@ -1508,9 +1541,80 @@ def _project_entity(rec: dict[str, Any]) -> dict[str, Any]:
         "aliases": rec["aliases"],
         "score": rec["score"],
         "match_type": rec["match_type"],
+        **(
+            {"is_group": rec["is_group"]}
+            if include_membership and "is_group" in rec
+            else {}
+        ),
+        **(
+            {"member_entity_ids": rec["member_entity_ids"]}
+            if include_membership and "member_entity_ids" in rec
+            else {}
+        ),
     }
 
 
+def _redact_hidden_members(
+    records: list[dict[str, Any]],
+    hidden: set[str],
+    *,
+    view: _RegistryView | None = None,
+    include_hidden: bool = True,
+    enabled: bool = True,
+) -> None:
+    """Withhold members excluded by visibility or include_hidden."""
+    if not enabled:
+        return
+    for record in records:
+        members = record.get("member_entity_ids")
+        denied = bool(members and hidden.intersection(members))
+        if members and not include_hidden and view is not None:
+            denied = denied or any(
+                getattr(_reg_entity(view, member), "hidden_by", None) is not None
+                for member in members
+            )
+        if denied:
+            record.pop("member_entity_ids", None)
+
+
+def _normalize_member_entity_ids(attributes: Any) -> list[str] | None:
+    """Normalize HA's modern or historical explicit group membership."""
+    if not isinstance(attributes, Mapping):
+        return None
+    for key in ("group_entities", "entity_id"):
+        raw = attributes.get(key)
+        if isinstance(raw, (str, bytes, bytearray, Mapping)):
+            continue
+        if not isinstance(raw, Collection):
+            continue
+        members: set[str] = set()
+        valid = True
+        for value in raw:
+            if not _is_entity_id(value):
+                valid = False
+                break
+            members.add(value)
+        if valid:
+            return sorted(members)
+    return None
+
+
+def _is_entity_id(value: Any) -> bool:
+    """Return whether a value has the Home Assistant entity ID shape."""
+    if not isinstance(value, str) or value.count(".") != 1:
+        return False
+    domain, object_id = value.split(".", 1)
+    return bool(
+        domain
+        and object_id
+        and value == value.lower()
+        and all(
+            char in "abcdefghijklmnopqrstuvwxyz0123456789_"
+            for char in domain + object_id
+        )
+    )
+
+
 # --- Config surfaces (automation/script/scene) -------------------------------
 def _search_config_surface(
     hass: HomeAssistant,

homeassistant-addon-dev/config.yaml

@@ -1,6 +1,6 @@
 name: "Home Assistant MCP Server (Dev)"
 description: "Development channel - AI assistant integration via MCP (unstable)"
-version: "8.3.0.dev2387"
+version: "8.3.0.dev2390"
 slug: "ha_mcp_dev"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 stage: experimental

site/src/data/tools.json

@@ -2910,7 +2910,7 @@
   {
     "name": "ha_search",
     "title": "Search",
-    "description": "Search for entities (lights, sensors, switches, climate, etc.) by name, domain, or area — AND inside automation/script/scene/helper/dashboard configurations — in one call.\n\nTwo surfaces run in parallel and return tagged results:\n  - **entities**: entity-registry matches (entity_id, friendly name,\n    area). Filter with `domain_filter`/`area_filter`/`state_filter`;\n    omit `query` to enumerate a domain, area, or state.\n  - **automations / scripts / scenes / helpers / dashboards**: matches\n    *inside* config definitions — triggers, actions, sequences, scene\n    entity-sets, helper bodies, dashboard cards. Driven by `query`;\n    narrow with `search_types`.\n\nUse this whenever you need to find something in HA without deciding\nentity-name vs config-body search up front.\n\nWhen NOT to use:\n  - To read a known entity_id's state: use `ha_get_state` (cheaper).\n  - To inspect one automation/script/scene config by id: use the\n    matching `ha_config_get_*`.\n  - To list installed Apps (add-ons): use `ha_get_app`.\n\nConfig-body search is skipped when `domain_filter`/`area_filter`/\n`state_filter` signal entity-only intent (keeping name lookups off the\nexpensive backend); a `warnings[]` entry names the skip. Pass\n`search_types=[...]` to force config search.\n\nCaveats:\n  - `partial: True` means results are NOT exhaustive — a surface raised,\n    or the config-body branch lost data (per-id time budget exhausted,\n    an individual fetch failed, or a helper-type list fetch failed).\n    Empty buckets with `partial: True` mean \"search failed\", not \"no\n    results\". The cause is in `partial_reason`, also mirrored into\n    `warnings[]` with an \"incomplete results: \" prefix. Do not treat a\n    partial response as complete.\n  - `count` is items in this response (post-pagination), not corpus\n    totals — use `entity_total_matches` + `config_total_matches`.\n  - `limit`/`offset` apply per-surface. Flat `has_more`/`next_offset`\n    page the next call (iterate `offset = next_offset`); per-surface\n    `entity_*`/`config_*` variants show which surface still has results.\n\nFor parameters, schema, and worked examples, see ha_get_skill_guide.\n\nExamples:\n    - List sensors in an area: ha_search(domain_filter=\"sensor\", area_filter=\"Living Room\")\n    - Find a light by name: ha_search(\"kitchen\", domain_filter=\"light\")\n    - Which automations use an entity: ha_search(\"light.bed_light\")\n    - Scenes touching a light: ha_search(\"light.kitchen\", search_types=[\"scene\"])\n    - Narrow the response to the entity bucket: ha_search(\"kitchen\", fields=[\"entities\"])\n    - All unavailable entities: ha_search(state_filter=\"unavailable\")",
+    "description": "Search for entities (lights, sensors, switches, climate, etc.) by name, domain, or area — AND inside automation/script/scene/helper/dashboard configurations — in one call.\n\nTwo surfaces run in parallel and return tagged results:\n  - **entities**: entity-registry matches (entity_id, friendly name,\n    area). Filter with `domain_filter`/`area_filter`/`state_filter`;\n    omit `query` to enumerate a domain, area, or state.\n  - **automations / scripts / scenes / helpers / dashboards**: matches\n    *inside* config definitions — triggers, actions, sequences, scene\n    entity-sets, helper bodies, dashboard cards. Driven by `query`;\n    narrow with `search_types`.\n\nUse this whenever you need to find something in HA without deciding\nentity-name vs config-body search up front.\n\nFor control requests with exclusions such as \"except\", \"excluding\", or\n\"but not\", include `is_group` and `member_entity_ids` in `result_fields`.\nDo not control an aggregate whose members include an excluded entity;\nprefer leaf entities when the exception cannot be verified safely.\nA withheld member list still returns is_group=true; absence of\nmember_entity_ids must not be interpreted as a leaf entity.\n\nWhen NOT to use:\n  - To read a known entity_id's state: use `ha_get_state` (cheaper).\n  - To inspect one automation/script/scene config by id: use the\n    matching `ha_config_get_*`.\n  - To list installed Apps (add-ons): use `ha_get_app`.\n\nConfig-body search is skipped when `domain_filter`/`area_filter`/\n`state_filter` signal entity-only intent (keeping name lookups off the\nexpensive backend); a `warnings[]` entry names the skip. Pass\n`search_types=[...]` to force config search.\n\nCaveats:\n  - `partial: True` means results are NOT exhaustive — a surface raised,\n    or the config-body branch lost data (per-id time budget exhausted,\n    an individual fetch failed, or a helper-type list fetch failed).\n    Empty buckets with `partial: True` mean \"search failed\", not \"no\n    results\". The cause is in `partial_reason`, also mirrored into\n    `warnings[]` with an \"incomplete results: \" prefix. Do not treat a\n    partial response as complete.\n  - `count` is items in this response (post-pagination), not corpus\n    totals — use `entity_total_matches` + `config_total_matches`.\n  - `limit`/`offset` apply per-surface. Flat `has_more`/`next_offset`\n    page the next call (iterate `offset = next_offset`); per-surface\n    `entity_*`/`config_*` variants show which surface still has results.\n\nFor parameters, schema, and worked examples, see ha_get_skill_guide.\n\nExamples:\n    - List sensors in an area: ha_search(domain_filter=\"sensor\", area_filter=\"Living Room\")\n    - Find a light by name: ha_search(\"kitchen\", domain_filter=\"light\")\n    - Find lights safely before an \"all except one\" control request:\n      ha_search(\"living room\", domain_filter=\"light\",\n      result_fields=[\"entity_id\", \"friendly_name\", \"is_group\",\n      \"member_entity_ids\"])\n    - Which automations use an entity: ha_search(\"light.bed_light\")\n    - Scenes touching a light: ha_search(\"light.kitchen\", search_types=[\"scene\"])\n    - Narrow the response to the entity bucket: ha_search(\"kitchen\", fields=[\"entities\"])\n    - All unavailable entities: ha_search(state_filter=\"unavailable\")",
     "inputSchema": {
       "properties": {
         "query": {
@@ -2962,7 +2962,7 @@
           "default": null
         },
         "result_fields": {
-          "type": "Annotated[str | list[str] | None, JSON_STRING_COERCION, Field(default=None, description='Project each entity-registry record to only the specified keys (e.g. [\"entity_id\", \"state\"]). None = full records. Base keys: entity_id, friendly_name, domain, state, score, match_type. Opt-in enrichment keys (joined on request): area, floor, labels, aliases. An unknown key is rejected.')]",
+          "type": "Annotated[str | list[str] | None, JSON_STRING_COERCION, Field(default=None, description='Project each entity-registry record to only the specified keys (e.g. [\"entity_id\", \"state\"]). None = full records. Base keys: entity_id, friendly_name, domain, state, score, match_type. Opt-in enrichment/membership keys (computed on request): area, floor, labels, aliases, is_group, member_entity_ids. Membership is recognized only when HA explicitly exposes a valid group_entities or legacy entity_id collection; member IDs are sorted, direct (not recursively expanded), and omitted if visibility/include_hidden excludes a member. is_group remains true when member IDs are withheld; requesting member_entity_ids also retains is_group. An unknown key is rejected.')]",
           "default": null
         },
         "fields": {