ha-mcp-dev 8.4.0.dev2509__tar.gz → 8.4.1.dev2516__tar.gz

{ha_mcp_dev-8.4.0.dev2509/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.1.dev2516}/PKG-INFO

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

{ha_mcp_dev-8.4.0.dev2509 → ha_mcp_dev-8.4.1.dev2516}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.0.dev2509"
+version = "8.4.1.dev2516"
 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

{ha_mcp_dev-8.4.0.dev2509 → ha_mcp_dev-8.4.1.dev2516}/src/ha_mcp/settings_ui/locales/en.json

@@ -114,13 +114,13 @@
     "visibility.entities.help": "One entity_id per line. These stay hidden even without an entity-registry entry.",
     "visibility.entities.denied": "Denied entity IDs",
     "visibility.allowlist.title": "Restrict to an allowlist",
-    "visibility.allowlist.help": "Advanced: when any allowlist field is set the filter inverts – only entities matching an allowlist stay visible, everything else is hidden (including entities added later). Leave all three empty to disable.",
+    "visibility.allowlist.help": "Advanced: when any allowlist field is set, nonmatching entities are hidden (including entities added later). A match overrides category, Home Assistant hidden-state, and Assist filters; denied entity IDs and excluded areas or labels still win. Leave all three empty to disable.",
     "visibility.allowlist.areas": "Allowed areas",
     "visibility.allowlist.labels": "Allowed labels",
     "visibility.allowlist.entities_help": "Allowed entity IDs, one per line.",
     "visibility.allowlist.entities": "Allowed entity IDs",
     "visibility.assist.title": "Respect Assist exposure",
-    "visibility.assist.help": "Hide entities not exposed to Home Assistant's Assist (“conversation”) voice assistant, mirroring the Settings > Voice assistants > Expose list. Adds two websocket reads per search while enabled.",
+    "visibility.assist.help": "Hide entities not exposed to Home Assistant's Assist (“conversation”) voice assistant, mirroring the Settings > Voice assistants > Expose list. Not applied while an allowlist is active; otherwise adds two websocket reads per search.",
     "visibility.assist.only_exposed": "Only show entities exposed to Assist",
     "features.enable_tool_search.label": "Enable tool search",
     "features.enable_tool_search.help": "Replace the full tool catalog with search-based discovery. Reduces idle context by roughly 90%, to about 5K tokens. ⚠️ Do NOT enable this in clients with their own built-in tool search / deferred tools (claude.ai, Claude Desktop, Claude Code) — the two search layers conflict, and the client's built-in tool search is the better choice there; leave this off. Whether tools are deferred depends on your client and model combination: use this when your setup loads the full catalog up front — models without native deferred tools (e.g. Gemini, OpenAI-compatible local models, Claude Haiku), clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI), or smaller context windows. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily. Tools are found via ha_search_tools and executed via categorized proxies (read/write/delete). Requires restart to take effect.",

{ha_mcp_dev-8.4.0.dev2509 → ha_mcp_dev-8.4.1.dev2516}/src/ha_mcp/settings_ui/settings.html

@@ -518,7 +518,7 @@
 
   <section class="a11y-section">
     <h2 class="a11y-section-title" data-i18n="visibility.allowlist.title">Restrict to an allowlist</h2>
-    <p class="a11y-section-help" data-i18n="visibility.allowlist.help">Advanced: when any allowlist field is set the filter inverts – only entities matching an allowlist stay visible, everything else is hidden (including entities added later). Leave all three empty to disable.</p>
+    <p class="a11y-section-help" data-i18n="visibility.allowlist.help">Advanced: when any allowlist field is set, nonmatching entities are hidden (including entities added later). A match overrides category, Home Assistant hidden-state, and Assist filters; denied entity IDs and excluded areas or labels still win. Leave all three empty to disable.</p>
     <label class="visibility-field"><span data-i18n="visibility.allowlist.areas">Allowed areas</span> <input type="text" id="visibility-allow-areas" placeholder="living_room, kitchen"></label>
     <label class="visibility-field"><span data-i18n="visibility.allowlist.labels">Allowed labels</span> <input type="text" id="visibility-allow-labels" placeholder="voice, main_floor"></label>
     <p class="a11y-section-help" data-i18n="visibility.allowlist.entities_help">Allowed entity IDs, one per line.</p>
@@ -528,7 +528,7 @@
 
   <section class="a11y-section">
     <h2 class="a11y-section-title" data-i18n="visibility.assist.title">Respect Assist exposure</h2>
-    <p class="a11y-section-help" data-i18n="visibility.assist.help">Hide entities not exposed to Home Assistant's Assist (&ldquo;conversation&rdquo;) voice assistant, mirroring the Settings &gt; Voice assistants &gt; Expose list. Adds two websocket reads per search while enabled.</p>
+    <p class="a11y-section-help" data-i18n="visibility.assist.help">Hide entities not exposed to Home Assistant's Assist (&ldquo;conversation&rdquo;) voice assistant, mirroring the Settings &gt; Voice assistants &gt; Expose list. Not applied while an allowlist is active; otherwise adds two websocket reads per search.</p>
     <label class="a11y-option"><input type="checkbox" id="visibility-respect-assist"> <span data-i18n="visibility.assist.only_exposed">Only show entities exposed to Assist</span></label>
   </section>
 

{ha_mcp_dev-8.4.0.dev2509 → ha_mcp_dev-8.4.1.dev2516}/src/ha_mcp/tools/tools_search.py

@@ -27,6 +27,7 @@ from ..errors import create_validation_error
 from ..transforms.categorized_search import DEFAULT_PINNED_TOOLS
 from ..utils.entity_membership import normalize_member_entity_ids
 from ..utils.fuzzy_search import apply_hidden_penalty
+from ..visibility.model import VisibilityWire, wire_has_allowlist_dimensions
 from ..visibility.resolver import (
     device_registry_needed_for_visibility,
     load_hidden_set,
@@ -1321,6 +1322,11 @@ def _merge_component_visibility_warnings(
             response,
             [w for w in component_visibility_warnings if isinstance(w, str)],
         )
+    elif component_visibility_warnings is not None:
+        logger.warning(
+            "component visibility_warnings ignored: expected a list, got %s",
+            type(component_visibility_warnings).__name__,
+        )
 
 
 async def _scrub_component_config_buckets(
@@ -2396,13 +2402,15 @@ class SearchTools:
         # hidden entities through the fast path. The ``search_visibility``
         # capability closes that: a component that advertises it accepts the raw
         # hide config (``VisibilityConfig.to_wire``) as the ``visibility`` param
-        # and excludes hidden entities before its own counts/pagination, exactly
-        # as the legacy path does — so a visibility-active install can still take
-        # the fast path. Without the capability an active filter stays on the
-        # legacy path; with no active filter the plain ``search`` route runs with
-        # no ``visibility`` param (old components keep working). ``ha_get_overview``
-        # needs no analogous gate — it re-applies the filter server-side over the
-        # component's raw slices. Checked only when the component would otherwise
+        # and excludes hidden entities before its own counts/pagination. The
+        # ``search_visibility_allowlist_authorization`` capability adds the
+        # ``allowlist_authorization`` wire key, which opts the component into the
+        # revised allowlist precedence; without it an active allowlist falls back
+        # to legacy (see ``_resolve_component_search_visibility``). With no active
+        # filter, the plain ``search`` route runs without a ``visibility`` param,
+        # so old components
+        # keep working. ``ha_get_overview`` needs no analogous gate — it reapplies
+        # the filter over the component's raw slices. Checked only when it would
         # serve, so the common (no-component / filter-off) install pays nothing.
         if (
             req.query_text
@@ -2429,7 +2437,7 @@ class SearchTools:
 
     async def _resolve_component_search_visibility(
         self, caps: Any
-    ) -> tuple[bool, dict[str, Any] | None]:
+    ) -> tuple[bool, VisibilityWire | None]:
         """Decide the ha_search route under the entity-visibility gate.
 
         Returns ``(route_component, visibility_param)`` for a caller that has
@@ -2437,13 +2445,21 @@ class SearchTools:
 
         - filter inactive → ``(True, None)``: the plain component search, no
           ``visibility`` param (parity with a pre-``search_visibility`` component).
-        - filter active + ``search_visibility`` capability + config serialized →
-          ``(True, <wire dict>)``: the component applies the hide dimensions
-          in-process.
-        - filter active without the capability, or the config could not be loaded
-          → ``(False, None)``: the legacy path applies the filter server-side
-          before the counts/pagination (fail-closed to legacy on a bad config,
-          matching ``visibility_state_and_wire``'s fail-closed pairing).
+        - filter active + ``search_visibility`` + config serialized:
+          - component also advertises ``search_visibility_allowlist_authorization``
+            → ``(True, <wire dict + allowlist_authorization: True>)``. The key opts
+            the component into the revised rule (an allow match authorizes past
+            category, HA-hidden, and Assist filters). It is never sent to a
+            component lacking the capability: that component's strict schema would
+            reject it, and the key's absence is what keeps a newer component on the
+            legacy precedence the released server still applies in its own
+            outbound scan.
+          - no allowlist dimensions → ``(True, <wire dict>)``: the nine-key wire;
+            with no allow dimensions the two precedences agree.
+          - allowlist active without the capability → ``(False, None)``.
+        - config could not be loaded → ``(False, None)``: the legacy path applies
+          the filter server-side before the counts/pagination (fail-closed to
+          legacy, matching ``visibility_state_and_wire``'s fail-closed pairing).
 
         ``visibility_state_and_wire`` loads the config once for both the active
         gate and its wire form, instead of the active check and the wire fetch
@@ -2452,16 +2468,21 @@ class SearchTools:
         active, visibility = await visibility_state_and_wire()
         if not active:
             return True, None
-        if component_supports(caps, "search_visibility") and visibility is not None:
-            return True, visibility
-        return False, None
+        if not component_supports(caps, "search_visibility") or visibility is None:
+            return False, None
+        if component_supports(caps, "search_visibility_allowlist_authorization"):
+            authorized: VisibilityWire = {**visibility, "allowlist_authorization": True}
+            return True, authorized
+        if wire_has_allowlist_dimensions(visibility):
+            return False, None
+        return True, visibility
 
     async def _ha_search_via_component(
         self,
         req: _ResolvedSearch,
         ctx: Context | None,
         *,
-        visibility: dict[str, Any] | None = None,
+        visibility: VisibilityWire | None = None,
         caps: Any = None,
     ) -> dict[str, Any] | None:
         """Serve ha_search from the component; ``None`` ⇒ run the legacy path.
@@ -2540,7 +2561,7 @@ class SearchTools:
         req: _ResolvedSearch,
         ctx: Context | None,
         *,
-        visibility: dict[str, Any] | None,
+        visibility: VisibilityWire | None,
     ) -> dict[str, Any] | None:
         """Serve a ``dashboard``-including request from both legs (issue #2289).
 
@@ -2636,7 +2657,7 @@ class SearchTools:
     async def _send_component_search(
         self,
         req: _ResolvedSearch,
-        visibility: dict[str, Any] | None = None,
+        visibility: VisibilityWire | None = None,
         *,
         dashboard_split: bool = False,
     ) -> dict[str, Any]:

{ha_mcp_dev-8.4.0.dev2509 → ha_mcp_dev-8.4.1.dev2516}/src/ha_mcp/tools/tools_service.py

@@ -1824,12 +1824,74 @@ class ServiceTools:
     @log_tool_usage
     async def ha_call_service(
         self,
-        domain: str | None = None,
-        service: str | None = None,
-        entity_id: str | None = None,
-        data: Annotated[dict[str, Any] | None, JSON_STRING_COERCION] = None,
-        return_response: bool = False,
-        wait: bool = True,
+        domain: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Service domain (e.g. 'light', 'climate', 'automation'). "
+                    "Required for a service call; must be omitted when ws_command "
+                    "is set."
+                ),
+            ),
+        ] = None,
+        service: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Service name within domain (e.g. 'turn_on', 'set_temperature', "
+                    "'trigger'). Required for a service call; must be omitted when "
+                    "ws_command is set."
+                ),
+            ),
+        ] = None,
+        entity_id: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Entity ID(s) the service call targets — one ID "
+                    "('light.living_room') or several comma-separated "
+                    "('light.a,light.b'). Optional for services that don't target "
+                    "a specific entity. Must be omitted when ws_command is set."
+                ),
+            ),
+        ] = None,
+        data: Annotated[
+            dict[str, Any] | None,
+            JSON_STRING_COERCION,
+            Field(
+                description=(
+                    "Extra service-call parameters beyond entity_id (e.g. "
+                    "{'temperature': 22} for climate.set_temperature). Also carries "
+                    "the raw command payload when ws_command is set. If entity_id "
+                    "is also present in data, the entity_id parameter wins."
+                ),
+            ),
+        ] = None,
+        return_response: Annotated[
+            bool,
+            Field(
+                description=(
+                    "If True, the service's response data is returned once, as "
+                    "the top-level 'service_response' key — never nested inside "
+                    "'result' (default: False). Must stay False when ws_command "
+                    "is set."
+                ),
+            ),
+        ] = False,
+        wait: Annotated[
+            bool,
+            Field(
+                description=(
+                    "If True (default), wait for the entity state to change "
+                    "before returning. Applies only to state-changing services "
+                    "called with a single entity_id. A comma-separated "
+                    "multi-target does not get confirmed by this: it falls "
+                    "through to a legacy path that polls for the literal "
+                    "composite entity_id and times out after 10s. Set "
+                    "wait=False for multi-target calls."
+                ),
+            ),
+        ] = True,
         verbose: Annotated[
             bool,
             Field(
@@ -1911,8 +1973,6 @@ class ServiceTools:
         ```
 
         **Key behavior:**
-        - **wait** (default True): wait for the entity state to change before
-          returning. Only applies to state-changing services on a single entity.
         - **Result compaction (default ON)**: ``result`` is trimmed
           to the targeted entity's record (drops parent-group propagation) and
           stripped of ``context`` / ``last_*`` metadata and heavy attribute
@@ -1920,9 +1980,6 @@ class ServiceTools:
           for the raw changed-state records, or ``result_fields`` /
           ``result_attribute_keys`` for explicit per-record projection (mirrors
           ``ha_get_state``).
-        - **return_response** (default False): the service's response data is
-          returned once, as the top-level ``service_response`` key — never nested
-          inside ``result``, which carries the changed entity states.
 
         **For detailed service documentation, use ha_get_skill_guide.**
 
@@ -1975,8 +2032,12 @@ class ServiceTools:
             )
 
             # Determine if we should wait for state change:
-            # Only for state-changing services on a single entity, not for
+            # Only for state-changing services with an entity_id set, not for
             # trigger/reload/fire-and-forget services or services without entities.
+            # A comma-separated multi-target entity_id is not excluded here — it
+            # still falls through to the legacy path, which polls for the literal
+            # composite entity_id and times out after 10s (see the wait Field
+            # description and _maybe_component_call_service).
             # This server-side decision (D6) also chooses whether to hand the
             # component wait+entity_ids: a non-state-changing call passes wait
             # implicitly false and no confirmation targets.