ha-mcp-dev 9.1.0.dev3241__tar.gz → 9.1.0.dev3245__tar.gz

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3241
+Version: 9.1.0.dev3245
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
@@ -94,9 +94,9 @@ Description-Content-Type: text/markdown
 
 ## 🚀 Get Started
 
-The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS, runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
+The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS (the built-in Marketplace on Home Assistant 2026.11+), runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
 
-**Add it to Home Assistant via HACS (the preferred install):**
+**Add it to Home Assistant via HACS or, on Home Assistant 2026.11+, the Marketplace (the preferred install):**
 
 [![Add HA-MCP to HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp&category=integration)
 
@@ -104,7 +104,8 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 
 > The setup below is for version 9.0.0 (October 28, 2026) and later; earlier versions show a shorter setup form without the administrator account step.
 
-1. Install the **HA-MCP Custom Component** from HACS — click the badge above, or in HACS open **Integrations → ⋮ → Custom repositories**, add `https://github.com/homeassistant-ai/ha-mcp` (category: **Integration**), then **Download**.
+1. Install the **HA-MCP Custom Component**. On **Home Assistant 2026.10 or older**, from HACS — click the badge above, or in HACS open **Integrations → ⋮ → Custom repositories**, add `https://github.com/homeassistant-ai/ha-mcp` (category: **Integration**), then **Download**.
+   On **Home Assistant 2026.11 or newer**, HACS is built in as the **Marketplace**: open **Settings → Marketplace** and accept its first-run warning, then **Connect GitHub** (a device sign-in). Adding a custom repository needs it, and until HA-MCP is in the Marketplace catalog it is also what makes the Marketplace check HA-MCP for updates in the background; without it, **Refresh information** on HA-MCP's Marketplace page checks by hand. Then click the badge above, or open the **Add from link** tab and add `https://github.com/homeassistant-ai/ha-mcp` as an **Integration**, and **Install**.
    Already installed from the earlier `homeassistant-ai/ha-mcp-integration` repository? It keeps receiving the same releases; nothing to change.
 2. **Restart Home Assistant.**
 3. Decide which administrator account the server acts as. Either create a long-lived access token on your own account (your profile → **Security** → **Long-lived access tokens** → **Create token**; it works from anywhere if it leaks, and the server's changes show under your name), or, safer, create an account just for HA-MCP under **Settings → People → Add person** with **Allow login**, **Local access only** and **Administrator** on. Never use your own login for the second option.
@@ -118,7 +119,7 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 - **Local only?** Leave remote access disabled at setup (or turn off **Remote access via webhook** in the entry options) — no webhook is registered at all, while the direct port and sidebar panel keep working.
 - **Settings panel:** while the server runs, an admin-only **HA-MCP** panel appears in the Home Assistant sidebar for managing tools, feature flags, backups, and themes.
 - **Optional authentication:** set **Authentication mode** to `ha_auth` to require a Home Assistant account sign-in instead of using the secret URL as the credential.
-- **Manual install (no HACS):** copy `custom_components/ha_mcp_tools/` from this repository into your Home Assistant `config/custom_components/` directory, then restart and add the integration as above.
+- **Manual install (no HACS or Marketplace):** copy `custom_components/ha_mcp_tools/` from this repository into your Home Assistant `config/custom_components/` directory, then restart and add the integration as above.
 
 The component's second entry type, the **File & YAML services entry** (**HA-MCP File & YAML Tools**), is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time. It works with any server type (in-process, app, Docker, or stdio).
 
@@ -374,7 +375,7 @@ Install the **HA-MCP File & YAML Tools** entry from the same **HA-MCP Custom Com
 
 [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp&category=integration)
 
-To add manually: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**. Or copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory.
+To add manually on Home Assistant 2026.10 or older: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**. On 2026.11 or newer: in **Marketplace**, accept the first-run warning and **Connect GitHub**, then **Add from link** > `https://github.com/homeassistant-ai/ha-mcp` as an **Integration** > **Install**. Or copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory.
 
 After installing, restart Home Assistant, then open **Settings** > **Devices & Services** > **Add Integration**, search for **HA-MCP Custom Component**, and add the **HA-MCP File & YAML Tools** entry.
 

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/README.md

@@ -34,9 +34,9 @@
 
 ## 🚀 Get Started
 
-The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS, runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
+The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS (the built-in Marketplace on Home Assistant 2026.11+), runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
 
-**Add it to Home Assistant via HACS (the preferred install):**
+**Add it to Home Assistant via HACS or, on Home Assistant 2026.11+, the Marketplace (the preferred install):**
 
 [![Add HA-MCP to HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp&category=integration)
 
@@ -44,7 +44,8 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 
 > The setup below is for version 9.0.0 (October 28, 2026) and later; earlier versions show a shorter setup form without the administrator account step.
 
-1. Install the **HA-MCP Custom Component** from HACS — click the badge above, or in HACS open **Integrations → ⋮ → Custom repositories**, add `https://github.com/homeassistant-ai/ha-mcp` (category: **Integration**), then **Download**.
+1. Install the **HA-MCP Custom Component**. On **Home Assistant 2026.10 or older**, from HACS — click the badge above, or in HACS open **Integrations → ⋮ → Custom repositories**, add `https://github.com/homeassistant-ai/ha-mcp` (category: **Integration**), then **Download**.
+   On **Home Assistant 2026.11 or newer**, HACS is built in as the **Marketplace**: open **Settings → Marketplace** and accept its first-run warning, then **Connect GitHub** (a device sign-in). Adding a custom repository needs it, and until HA-MCP is in the Marketplace catalog it is also what makes the Marketplace check HA-MCP for updates in the background; without it, **Refresh information** on HA-MCP's Marketplace page checks by hand. Then click the badge above, or open the **Add from link** tab and add `https://github.com/homeassistant-ai/ha-mcp` as an **Integration**, and **Install**.
    Already installed from the earlier `homeassistant-ai/ha-mcp-integration` repository? It keeps receiving the same releases; nothing to change.
 2. **Restart Home Assistant.**
 3. Decide which administrator account the server acts as. Either create a long-lived access token on your own account (your profile → **Security** → **Long-lived access tokens** → **Create token**; it works from anywhere if it leaks, and the server's changes show under your name), or, safer, create an account just for HA-MCP under **Settings → People → Add person** with **Allow login**, **Local access only** and **Administrator** on. Never use your own login for the second option.
@@ -58,7 +59,7 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 - **Local only?** Leave remote access disabled at setup (or turn off **Remote access via webhook** in the entry options) — no webhook is registered at all, while the direct port and sidebar panel keep working.
 - **Settings panel:** while the server runs, an admin-only **HA-MCP** panel appears in the Home Assistant sidebar for managing tools, feature flags, backups, and themes.
 - **Optional authentication:** set **Authentication mode** to `ha_auth` to require a Home Assistant account sign-in instead of using the secret URL as the credential.
-- **Manual install (no HACS):** copy `custom_components/ha_mcp_tools/` from this repository into your Home Assistant `config/custom_components/` directory, then restart and add the integration as above.
+- **Manual install (no HACS or Marketplace):** copy `custom_components/ha_mcp_tools/` from this repository into your Home Assistant `config/custom_components/` directory, then restart and add the integration as above.
 
 The component's second entry type, the **File & YAML services entry** (**HA-MCP File & YAML Tools**), is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time. It works with any server type (in-process, app, Docker, or stdio).
 
@@ -314,7 +315,7 @@ Install the **HA-MCP File & YAML Tools** entry from the same **HA-MCP Custom Com
 
 [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp&category=integration)
 
-To add manually: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**. Or copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory.
+To add manually on Home Assistant 2026.10 or older: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**. On 2026.11 or newer: in **Marketplace**, accept the first-run warning and **Connect GitHub**, then **Add from link** > `https://github.com/homeassistant-ai/ha-mcp` as an **Integration** > **Install**. Or copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory.
 
 After installing, restart Home Assistant, then open **Settings** > **Devices & Services** > **Add Integration**, search for **HA-MCP Custom Component**, and add the **HA-MCP File & YAML Tools** entry.
 

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3241"
+version = "9.1.0.dev3245"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3241"
+version = "9.1.0.dev3245"
 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-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/src/ha_mcp/config_settings.py

@@ -231,6 +231,13 @@ class Settings(BaseSettings):
         bool, Setting(surface="advanced", section="operations")
     ] = Field(False, alias="HAMCP_ENABLE_HISTORY_QUERY_GUARDRAILS")
 
+    # Opt-in: ask HACS / the Marketplace to refresh the component's repository
+    # at startup after a server update (hacs_auto_refresh). An install that ran
+    # the refresh before it became opt-in has it turned on once, on its behalf.
+    hacs_refresh_after_update: Annotated[
+        bool, Setting(surface="advanced", section="operations")
+    ] = Field(False, alias="HAMCP_HACS_REFRESH_AFTER_UPDATE")
+
     # Optional process-wide outer tool-call concurrency. Zero preserves the
     # existing unlimited behavior; constrained installs can opt into queuing.
     ha_tool_concurrency: Annotated[

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/src/ha_mcp/errors.py

@@ -249,7 +249,10 @@ DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
         "Report this issue if it persists",
     ],
     ErrorCode.COMPONENT_NOT_INSTALLED: [
-        "Install the required custom component via HACS",
+        (
+            "Install the required custom component via HACS (the Marketplace on "
+            "Home Assistant 2026.11+)"
+        ),
         "Restart Home Assistant after installation",
     ],
 }

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/src/ha_mcp/hacs_auto_refresh.py

@@ -1,16 +1,23 @@
-"""Ask HACS to surface the paired component update after a server update.
+"""Ask HACS to surface the paired component update after a server update (opt-in).
 
 HACS refreshes a *custom* repository's release data from GitHub only about
-every 48 hours, and the ha_mcp_tools component ships in lockstep with each
-server release — so a freshly updated server can sit for two days next to a
-component update HACS has not noticed yet. This module closes that gap for
-add-on, Docker, pip and stdio installs. The embedded server is skipped: the
-component manages its updates.
+every 48 hours, and the Marketplace that replaces it in Home Assistant 2026.11
+only when a GitHub account is connected. The ha_mcp_tools component ships in
+lockstep with each server release, so a component update can go unnoticed for
+days, or for good. This module closes that gap for every install, the embedded
+server included. It goes away once ha-mcp is in the default catalog, which the
+Marketplace refreshes every 6 hours.
 
 On startup, when the server version changed since the last recorded nudge (the
-just-updated case) or a newer release is pending, it sends HACS's "Update
-information" refresh (``hacs/repository/refresh``) over the existing admin
-WebSocket for every INSTALLED candidate repository entry.
+just-updated case) or a newer release is pending, it sends the store's "Update
+information" refresh (``marketplace/repository/refresh``, or
+``hacs/repository/refresh`` before 2026.11) over the existing admin WebSocket
+for every INSTALLED candidate repository entry. Nothing is installed: the user
+still updates from the update entity.
+
+It is opt-in (``hacs_refresh_after_update``). An install whose nudge completed
+a pass before it became opt-in has a marker file and no explicit choice; the
+setting is turned on for it once, so its behavior does not change.
 
 Fully advisory: every failure degrades to a debug log and nothing here can
 fault startup. A marker file in the data dir records the state the last
@@ -24,19 +31,21 @@ import asyncio
 import hashlib
 import json
 import logging
+import os
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager, suppress
 from pathlib import Path
 from typing import Any
 
 from ._vendor import websockets
-from ._version import get_version, is_embedded
+from ._version import get_version
 from .client.rest_client import (
     HomeAssistantCommandError,
     HomeAssistantCommandTimeout,
     HomeAssistantConnectionError,
 )
 from .config import OAUTH_MODE_TOKEN, get_global_settings
+from .config_overrides import _read_feature_flag_override_file
 from .update_check import UpdateInfo, get_update_info, is_update_check_disabled
 from .utils.data_paths import get_data_dir
 
@@ -123,18 +132,23 @@ async def _refresh_installed_candidates() -> dict[str, Any] | None:
     or None when the outcome could not be determined.
     """
     from .client.websocket_client import get_websocket_client
+    from .tools.hacs_backend import STORE_APIS
     from .tools.hacs_registration import send_hacs_repository_refresh
 
     ws_client = await get_websocket_client()
-    try:
-        response = await ws_client.send_command("hacs/repositories/list")
-    except HomeAssistantCommandError as err:
-        # HACS not installed at all — HA rejects its commands as unknown. Same
-        # detection as ``_assert_hacs_available`` in tools/tools_hacs.py. Any
-        # other command failure is a real error: let the retry loop see it.
-        if err.code == "unknown_command" or "unknown command" in str(err).lower():
-            return {"hacs": "absent", "refreshed": []}
-        raise
+    for api in STORE_APIS:
+        try:
+            response = await ws_client.send_command(api.command("list"))
+        except HomeAssistantCommandError as err:
+            # A store that is not installed answers as an unknown command; any
+            # other failure (the Marketplace still loading included) is real:
+            # let the retry loop see it.
+            if err.code == "unknown_command" or "unknown command" in str(err).lower():
+                continue
+            raise
+        break
+    else:
+        return {"hacs": "absent", "refreshed": []}
 
     wanted = {name.lower() for name in CANDIDATE_REPO_FULL_NAMES}
     refreshed: list[str] = []
@@ -148,7 +162,7 @@ async def _refresh_installed_candidates() -> dict[str, Any] | None:
             continue
         attempted += 1
         try:
-            await send_hacs_repository_refresh(ws_client, str(repo["id"]))
+            await send_hacs_repository_refresh(ws_client, str(repo["id"]), api)
         except Exception as err:  # noqa: BLE001
             # Both entries read installed only when someone downloaded the
             # mirror without removing the legacy record — HACS guards against
@@ -199,12 +213,34 @@ async def _refresh_with_retries() -> dict[str, Any] | None:
     return absent_result
 
 
+SETTING = "hacs_refresh_after_update"
+SETTING_ENV = "HAMCP_HACS_REFRESH_AFTER_UPDATE"
+
+
+async def _opted_in(settings: Any, marker: dict[str, Any] | None) -> bool:
+    """Whether the nudge is on; an install that already ran it keeps it."""
+    if getattr(settings, SETTING):
+        return True
+    explicit = os.environ.get(SETTING_ENV) is not None or SETTING in (
+        await asyncio.to_thread(_read_feature_flag_override_file)
+    )
+    if explicit or marker is None:
+        return False
+    from .settings_ui._handlers_advanced import _write_advanced_overrides_file
+
+    if await _write_advanced_overrides_file({SETTING: True}) is not None:
+        logger.warning("Could not save %s=true; it stays on for this run", SETTING)
+    setattr(settings, SETTING, True)
+    logger.info(
+        "HACS auto-refresh is opt-in now; it stays on for this install, which "
+        "already used it (turn it off under Advanced settings)"
+    )
+    return True
+
+
 async def maybe_refresh_hacs_after_update() -> None:
     """Nudge HACS once per startup when the update picture changed."""
     try:
-        if is_embedded():
-            # The component manages the embedded server's updates.
-            return
         if is_update_check_disabled():
             return
 
@@ -215,11 +251,16 @@ async def maybe_refresh_hacs_after_update() -> None:
             return
         ha_url = settings.homeassistant_url
 
+        marker = await asyncio.to_thread(_read_marker, ha_url)
+        if not await _opted_in(settings, marker):
+            # Per-boot DEBUG line: the add-on lane proves scheduling with it.
+            logger.debug("HACS auto-refresh: off (%s is opt-in)", SETTING_ENV)
+            return
+
         current = get_version()
         # Normally a cache hit — the startup banner warms the lru_cache — but
         # offloaded anyway so a cold call can never touch the event loop.
         info = await asyncio.to_thread(get_update_info)
-        marker = await asyncio.to_thread(_read_marker, ha_url)
         if not _nudge_due(current, info, marker):
             # DEBUG, not INFO: the not-due return is the per-conversation
             # stdio hot path and must stay quiet at default levels. The line

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/src/ha_mcp/settings_ui/_handlers_oauth_callbacks.py

@@ -61,7 +61,8 @@ async def _component_command(
     if not component_supports(caps, CAPABILITY):
         raise _Unavailable(
             "This HA-MCP component cannot edit the callback list. Update the "
-            "HA-MCP integration in HACS."
+            "HA-MCP integration in HACS (the Marketplace on Home Assistant "
+            "2026.11+)."
         )
     ws = await get_websocket_client(
         url=client.base_url,

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/src/ha_mcp/settings_ui/locales/en.json

@@ -472,6 +472,8 @@
     "advanced.individual_fetch_batch_size.help": "Concurrent per-ID config fetches. Lower toward 1 on serial HA servers.",
     "advanced.enable_history_query_guardrails.label": "History query guardrails",
     "advanced.enable_history_query_guardrails.help": "Reject recorder queries that exceed conservative entity and time-range budgets. Disabled by default.",
+    "advanced.hacs_refresh_after_update.label": "Refresh the component in HACS after an update",
+    "advanced.hacs_refresh_after_update.help": "At startup after a server update, ask HACS (the Marketplace on Home Assistant 2026.11+) to re-check the HA-MCP Custom Component repository, so its matching update shows right away instead of at the next 48-hour check. Off by default; installs that already did this keep it on.",
     "advanced.ha_tool_concurrency.label": "Home Assistant tool concurrency",
     "advanced.ha_tool_concurrency.help": "Optional limit on outer Home Assistant tool calls across all sessions. Internal REST, WebSocket, and per-tool fan-out concurrency is unchanged. 0 keeps unlimited behavior. A call waiting for capacity fails after 60 seconds.",
     "advanced.dashboard_screenshot_engine_url.label": "Dashboard screenshot engine URL",

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/src/ha_mcp/tools/dashboard_card_describe.py

@@ -120,7 +120,10 @@ async def describe_card_response(client: Any, card_type: str | None) -> dict[str
                 "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",
+                    (
+                        "Install or update the HA-MCP Custom Component through "
+                        "HACS (the Marketplace on Home Assistant 2026.11+)"
+                    ),
                     "Restart Home Assistant after the update completes",
                 ],
                 context={"action": "describe", "card_type": card_type},

{ha_mcp_dev-9.1.0.dev3241 → ha_mcp_dev-9.1.0.dev3245}/src/ha_mcp/tools/device_control.py

@@ -65,8 +65,8 @@ _BULK_ROW_SHAPE_SUGGESTION = (
 # The ha_mcp_tools/bulk_call_service WS command (Phase 3, D5a): the BATCH write
 # capability. When the component advertises ``bulk_call_service`` the consumer
 # resolves every op's domain/service server-side (D6), sends one register-before-fire
-# batch frame, and maps the inline-confirmed per-op transitions back into the legacy
-# bulk response shape — no operation-id polling needed. Named once so the routing
+# batch frame, and maps each op's inline result (confirmed or not) back into the
+# legacy bulk response shape — no operation-id polling needed. Named once so the routing
 # helper and its tests agree on the wire string.
 WS_BULK_CALL_SERVICE = "ha_mcp_tools/bulk_call_service"
 
@@ -887,30 +887,24 @@ class DeviceControlTools:
                 )
 
             # Route through the component's bulk_call_service capability when
-            # advertised (D5a): one register-before-fire batch frame confirms every
-            # op inline, so ops return already-verified (no operation-id polling). A
-            # None return means nothing dispatched (capability miss / unresolvable op
-            # / transport failure), so the legacy path below is a safe first fire
-            # (D9 at-most-once).
+            # advertised (D5a): one register-before-fire batch frame; HA confirms ops
+            # inline (no operation-id polling) and each op's result says whether it
+            # did. A None return means nothing dispatched (capability miss /
+            # unresolvable op / pre-send failure), so the legacy path below is a safe
+            # first fire (D9 at-most-once).
             component_response = await self._bulk_via_component(
                 operations, valid_operations, skipped_operations, parallel
             )
             if component_response is not None:
-                # M-progress-msg: the ambiguous batch response carries a top-level
-                # ``partial`` (dispatched but the batch confirmation never arrived — not
-                # retried); only a fully-served batch is "confirmed inline". The legacy
-                # ``_build_bulk_response`` never sets a top-level ``partial``, so this
-                # flag reliably marks the ambiguous path.
-                component_message = (
-                    "dispatched via component (unconfirmed — not retried)"
-                    if component_response.get("partial")
-                    else "dispatched via component (confirmed inline)"
-                )
+                # Report the dispatch only; each op's outcome is in its result and is
+                # never summarised here.
                 await safe_progress(
                     ctx,
                     progress=len(valid_operations),
                     total=len(valid_operations),
-                    message=component_message,
+                    message=(
+                        "dispatched via component; each op's result shows its outcome"
+                    ),
                 )
                 return component_response
 
@@ -1012,7 +1006,7 @@ class DeviceControlTools:
     ) -> dict[str, Any]:
         """Map one component op result into the legacy per-op result shape.
 
-        The component confirms inline, so the op returns already-verified with a
+        The component reports each op's confirmation inline, so the op returns a
         synthesized terminal status instead of the legacy ``pending_verification`` +
         operation-id handle. A ``command_sent: True`` result is counted ``successful``
         by ``_build_bulk_response`` exactly as the legacy dispatch result is; an op
@@ -1137,7 +1131,7 @@ class DeviceControlTools:
             "action": action,
             "parameters": op.get("parameters") or {},
             "command_sent": True,
-            # M-status: an inline-confirmed op has no operation_id, so a
+            # M-status: a component-path op has no operation_id, so a
             # "pending_verification" status is misleading (nothing will poll it). Use
             # "dispatched_unconfirmed" — the same label the ambiguous batch path uses.
             "status": "completed" if confirmed else "dispatched_unconfirmed",
@@ -1182,7 +1176,7 @@ class DeviceControlTools:
 
         Returns a legacy-shaped bulk response (built by the SAME
         ``_build_bulk_response`` the legacy path uses, with ``operation_ids`` empty
-        and ``follow_up`` None since ops are confirmed inline) when the component
+        and ``follow_up`` None since confirmation is inline) when the component
         advertises ``bulk_call_service`` and the frame lands, else ``None`` so the
         caller runs the unchanged legacy operation-registry path.
 
@@ -1316,7 +1310,7 @@ class DeviceControlTools:
                 valid_operations, rows, op_results, strict=True
             )
         ]
-        # Reuse the legacy response builder: operation_ids is empty (ops confirmed
+        # Reuse the legacy response builder: operation_ids is empty (confirmation is
         # inline, no polling handle) → follow_up is None, and the successful/failed
         # tallies key off command_sent exactly as the legacy path.
         return self._build_bulk_response(
@@ -1386,14 +1380,14 @@ class DeviceControlTools:
         skipped_operations: list[dict[str, Any]],
         parallel: bool,
     ) -> dict[str, Any]:
-        """Partial-success bulk response for a post-send batch-frame timeout/drop.
-
-        The batch frame WAS sent, so some/all ops may have dispatched; the batch
-        response never arrived. Per D9 at-most-once every valid op is reported
-        dispatched-but-unconfirmed (``partial``) and the batch is NEVER re-dispatched
-        via legacy. ``rows`` is aligned 1:1 with ``valid_operations`` (both built in
-        order; an unresolvable op returned to legacy earlier, so no ``None`` rows
-        reach here).
+        """Partial-success bulk response for a sent batch frame with no usable reply.
+
+        The batch frame WAS sent, so some/all ops may have dispatched, but the reply
+        timed out, the connection dropped, or the success envelope was malformed.
+        Per D9 at-most-once every valid op is reported dispatched-but-unconfirmed
+        (``partial``) and the batch is NEVER re-dispatched via legacy. ``rows`` is
+        aligned 1:1 with ``valid_operations`` (both built in order; an unresolvable op
+        returned to legacy earlier, so no ``None`` rows reach here).
         """
         results: list[dict[str, Any]] = [
             {
@@ -1413,8 +1407,8 @@ class DeviceControlTools:
                 },
                 "verification_method": "component_state_change",
                 "message": (
-                    f"{entity_id} {action} dispatched but the batch confirmation did "
-                    "not arrive within the timeout; not retried"
+                    f"{entity_id} {action} dispatched but no usable batch "
+                    "confirmation arrived; not retried"
                 ),
             }
             for (_idx, op, entity_id, action), row in zip(
@@ -1426,9 +1420,9 @@ class DeviceControlTools:
         )
         response["partial"] = True
         response.setdefault("warnings", []).append(
-            "The bulk operation was dispatched but Home Assistant did not confirm "
-            "within the timeout. Operations were NOT retried (at-most-once). Use "
-            "ha_get_state to verify the affected entities."
+            "The bulk operation was dispatched but no usable confirmation arrived "
+            "(timeout, dropped connection or malformed reply). Operations were NOT "
+            "retried (at-most-once). Use ha_get_state to verify the affected entities."
         )
         return response
 

ha_mcp_dev-9.1.0.dev3245/src/ha_mcp/tools/entity_expose_batch.py

@@ -0,0 +1,67 @@
+"""Bulk ``homeassistant/expose_entity`` calls for ``ha_set_entity``."""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def changed_entity_ids(reply: dict[str, Any]) -> set[str] | None:
+    """The entities Core reports it changed, or None before Core 2026.11."""
+    result = reply.get("result")
+    if isinstance(result, dict) and isinstance(result.get("changed_entity_ids"), list):
+        return set(result["changed_entity_ids"])
+    return None
+
+
+async def apply_bulk_expose(
+    client: Any,
+    entity_ids: list[str],
+    parsed_expose_to: dict[str, bool],
+    extract_error: Callable[[dict[str, Any]], str],
+) -> tuple[str | None, set[str] | None]:
+    """Expose/hide many entities in one homeassistant/expose_entity call per set.
+
+    The command's schema accepts the full entity_ids list, so bulk exposure
+    needs at most two WS calls (one for the assistants being turned on, one
+    for those being turned off) regardless of entity count — not one per
+    entity. Returns (error, changed): error is None on success, or the message
+    of the first failing set, which applies to every id in the list. changed
+    holds the ids Core reports it changed, or None when Core does not report
+    them (before 2026.11).
+    """
+    expose_true = [a for a, v in parsed_expose_to.items() if v]
+    expose_false = [a for a, v in parsed_expose_to.items() if not v]
+    applied: list[str] = []
+    changed: set[str] | None = set()
+    for assistants, should_expose in [(expose_true, True), (expose_false, False)]:
+        if not assistants:
+            continue
+        logger.info(
+            f"{'Exposing' if should_expose else 'Hiding'} {len(entity_ids)} "
+            f"entities {'to' if should_expose else 'from'} {assistants}"
+        )
+        result = await client.send_websocket_message(
+            {
+                "type": "homeassistant/expose_entity",
+                "assistants": assistants,
+                "entity_ids": entity_ids,
+                "should_expose": should_expose,
+            }
+        )
+        if not result.get("success"):
+            error = extract_error(result)
+            if applied:
+                # The earlier assistant group already changed — say so, or
+                # the all-failed report implies no exposure was touched.
+                error = (
+                    f"{error} (note: expose changes for "
+                    f"{', '.join(applied)} were already applied before "
+                    "this failure)"
+                )
+            return error, None
+        applied.extend(assistants)
+        reported = changed_entity_ids(result)
+        changed = None if reported is None or changed is None else changed | reported
+    return None, changed