ha-mcp-dev 7.9.0.dev764__tar.gz → 7.9.0.dev765__tar.gz

{ha_mcp_dev-7.9.0.dev764/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.9.0.dev765}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.9.0.dev764
+Version: 7.9.0.dev765
 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.9.0.dev764 → ha_mcp_dev-7.9.0.dev765}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.9.0.dev764"
+version = "7.9.0.dev765"
 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-7.9.0.dev764 → ha_mcp_dev-7.9.0.dev765}/src/ha_mcp/settings_ui/__init__.py

@@ -796,6 +796,61 @@ def _build_stub_policy_handlers(*, data_dir: Path) -> dict[str, Any]:
     }
 
 
+def _build_visibility_handlers(*, data_dir: Path) -> dict[str, Any]:
+    """Settings-UI handlers for the entity visibility filter config.
+
+    Serves the on-disk ``entity_visibility.json`` GET/PUT with the same
+    optimistic-concurrency (version) guard as the tool policy handlers. Pure
+    file I/O, so it is always available (no approval-queue dependency).
+    """
+    from pydantic import ValidationError
+
+    from ..visibility.model import VisibilityConfig
+    from ..visibility.persistence import (
+        load_visibility_config,
+        save_visibility_config,
+    )
+
+    async def get_config(_: Request) -> JSONResponse:
+        try:
+            return JSONResponse(
+                load_visibility_config(data_dir).model_dump(mode="json")
+            )
+        except ValueError as e:
+            # Surface corruption rather than crash the tab on a 500.
+            return JSONResponse(
+                {"error": str(e), "visibility_file_corrupt": True},
+                status_code=500,
+            )
+
+    async def put_config(request: Request) -> JSONResponse:
+        try:
+            new_config = VisibilityConfig.model_validate(await request.json())
+        except (ValidationError, ValueError) as e:
+            return JSONResponse({"error": str(e)}, status_code=400)
+        # Optimistic concurrency: reject if the on-disk version moved between
+        # this caller's GET and PUT.
+        current = load_visibility_config(data_dir)
+        if new_config.version != current.version:
+            return JSONResponse(
+                {
+                    "error": (
+                        "Visibility config version mismatch. Reload before saving."
+                    ),
+                    "current_version": current.version,
+                    "current_config": current.model_dump(mode="json"),
+                },
+                status_code=409,
+            )
+        save_visibility_config(data_dir, new_config)
+        return JSONResponse({"saved": True, "version": new_config.version + 1})
+
+    return {
+        "visibility_get_config": get_config,
+        "visibility_put_config": put_config,
+    }
+
+
 class _SupervisorOptionsError(NamedTuple):
     """Discriminated failure shape for the supervisor options helpers.
 
@@ -3237,6 +3292,8 @@ def build_settings_handlers(
     else:
         handlers.update(_build_stub_policy_handlers(data_dir=get_data_dir()))
 
+    handlers.update(_build_visibility_handlers(data_dir=get_data_dir()))
+
     return handlers
 
 
@@ -3397,6 +3454,9 @@ def register_settings_routes(
         ("/api/policy/deny", ["POST"], "policy_post_deny"),
         ("/api/policy/tool-schema", ["GET"], "policy_get_tool_schema"),
         ("/api/policy/value-source", ["GET"], "policy_get_value_source"),
+        # Entity visibility filter endpoints (issue #1728)
+        ("/api/visibility/config", ["GET"], "visibility_get_config"),
+        ("/api/visibility/config", ["PUT"], "visibility_put_config"),
     ]
 
     def _mount(prefix: str, *, guard: bool = False) -> None:

{ha_mcp_dev-7.9.0.dev764 → ha_mcp_dev-7.9.0.dev765}/src/ha_mcp/settings_ui/settings.css

@@ -953,3 +953,18 @@
     /* Modal fills the small viewport instead of floating in a sliver. */
     .modal { max-height: 94vh; }
   }
+
+  /* Entity visibility filter tab (#1728) */
+  .visibility-field {
+    display: block; margin: 10px 0; color: var(--text-secondary); font-size: 0.85rem;
+  }
+  .visibility-field input[type="text"], .visibility-textarea {
+    display: block; width: 100%; margin-top: 4px; padding: 6px 8px;
+    background: var(--surface); color: var(--text); border: 1px solid var(--border);
+    border-radius: 6px; font: inherit;
+  }
+  .visibility-textarea { resize: vertical; }
+  .visibility-error {
+    background: var(--danger); color: #fff; padding: 8px 12px;
+    border-radius: 6px; margin-bottom: 8px; font-size: 0.85rem;
+  }

{ha_mcp_dev-7.9.0.dev764 → ha_mcp_dev-7.9.0.dev765}/src/ha_mcp/settings_ui/settings.html

@@ -158,6 +158,7 @@
   <button class="tab" data-panel="server" role="tab" id="tab-server" aria-controls="panel-server" aria-selected="false" tabindex="-1">Server Settings</button>
   <button class="tab" data-panel="backups" role="tab" id="tab-backups" aria-controls="panel-backups" aria-selected="false" tabindex="-1">Backups</button>
   <button class="tab" data-panel="tool-security-policies" role="tab" id="tab-tool-security-policies" aria-controls="panel-tool-security-policies" aria-selected="false" tabindex="-1">Tool Security Policies</button>
+  <button class="tab" data-panel="entity-visibility" role="tab" id="tab-entity-visibility" aria-controls="panel-entity-visibility" aria-selected="false" tabindex="-1">Entity Visibility</button>
   <button class="tab" data-panel="accessibility" role="tab" id="tab-accessibility" aria-controls="panel-accessibility" aria-selected="false" tabindex="-1">Accessibility</button>
 </div>
 <div class="restart-notice" id="restartNotice">
@@ -403,6 +404,70 @@
     <button id="a11y-reset" class="restart-btn" type="button">Reset to defaults</button>
   </section>
 </div>
+<div class="panel" id="panel-entity-visibility" role="tabpanel" aria-labelledby="tab-entity-visibility" tabindex="0">
+  <p class="tool-desc" style="margin-bottom:12px">
+    Hide low-value entities (auto-generated diagnostic or helper entities, or an
+    explicit list) from the collection read tools <code>ha_search</code> and
+    <code>ha_get_overview</code>, so search and overview results are less
+    cluttered. Off by default; changes apply on the next tool call.
+  </p>
+  <p class="a11y-contrast-warning" id="visibility-boundary-note">
+    Noise reduction, not access control: a hidden entity is still returned by a
+    direct read of its entity_id and still appears in automation, dashboard, and
+    template content. Do not rely on this as a security boundary.
+  </p>
+  <div id="visibility-load-error" class="visibility-error" role="alert" aria-live="assertive" style="display:none"></div>
+
+  <section class="a11y-section">
+    <label class="a11y-option"><input type="checkbox" id="visibility-enabled"> Enable entity visibility filter</label>
+  </section>
+
+  <section class="a11y-section">
+    <h2 class="a11y-section-title">Hide by category</h2>
+    <p class="a11y-section-help">Home Assistant tags auto-generated entities as diagnostic or config.</p>
+    <fieldset class="a11y-options">
+      <legend class="visually-hidden">Entity categories to hide</legend>
+      <label class="a11y-option"><input type="checkbox" id="visibility-cat-diagnostic"> Diagnostic</label>
+      <label class="a11y-option"><input type="checkbox" id="visibility-cat-config"> Config</label>
+      <label class="a11y-option"><input type="checkbox" id="visibility-exclude-hidden"> Also entities already hidden in Home Assistant</label>
+    </fieldset>
+  </section>
+
+  <section class="a11y-section">
+    <h2 class="a11y-section-title">Hide by area or label</h2>
+    <p class="a11y-section-help">Comma-separated area IDs or label IDs; entities in any listed area or label are hidden.</p>
+    <label class="visibility-field">Areas <input type="text" id="visibility-areas" placeholder="garage, basement"></label>
+    <label class="visibility-field">Labels <input type="text" id="visibility-labels" placeholder="noise, archived"></label>
+  </section>
+
+  <section class="a11y-section">
+    <h2 class="a11y-section-title">Hide specific entities</h2>
+    <p class="a11y-section-help">One entity_id per line. These stay hidden even without an entity-registry entry.</p>
+    <label class="visibility-field visually-hidden" for="visibility-deny">Denied entity IDs</label>
+    <textarea id="visibility-deny" class="visibility-textarea" rows="4" placeholder="sensor.example_diagnostic&#10;light.unused"></textarea>
+  </section>
+
+  <section class="a11y-section">
+    <h2 class="a11y-section-title">Restrict to an allowlist</h2>
+    <p class="a11y-section-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>
+    <label class="visibility-field">Allowed areas <input type="text" id="visibility-allow-areas" placeholder="living_room, kitchen"></label>
+    <label class="visibility-field">Allowed labels <input type="text" id="visibility-allow-labels" placeholder="voice, main_floor"></label>
+    <p class="a11y-section-help">Allowed entity IDs, one per line.</p>
+    <label class="visibility-field visually-hidden" for="visibility-allow-entities">Allowed entity IDs</label>
+    <textarea id="visibility-allow-entities" class="visibility-textarea" rows="3" placeholder="light.living_room&#10;switch.desk"></textarea>
+  </section>
+
+  <section class="a11y-section">
+    <h2 class="a11y-section-title">Respect Assist exposure</h2>
+    <p class="a11y-section-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>
+    <label class="a11y-option"><input type="checkbox" id="visibility-respect-assist"> Only show entities exposed to Assist</label>
+  </section>
+
+  <section class="a11y-section">
+    <button id="visibility-save-btn" class="restart-btn" type="button">Save</button>
+    <span id="visibility-save-status" class="status" role="status" aria-live="polite"></span>
+  </section>
+</div>
 </main>
 <div class="modal-backdrop" id="modalBackdrop">
   <div class="modal" role="dialog" aria-modal="true" aria-labelledby="modalTitle" tabindex="-1">

{ha_mcp_dev-7.9.0.dev764 → ha_mcp_dev-7.9.0.dev765}/src/ha_mcp/settings_ui/settings.js

@@ -2875,6 +2875,7 @@ function activateTab(target, opts) {
   );
   if (target === 'backups') { loadBackupConfig(); loadBackups(); }
   if (target === 'tool-security-policies') { policyLoadConfig(); policyLoadPending(); }
+  if (target === 'entity-visibility') { visibilityLoadConfig(); }
   if (target === 'tools') {
     // Refresh gated-toggle + read-only state in case the user changed
     // them from another tab while it was active.
@@ -3582,3 +3583,115 @@ loadFsCustomPaths();
     });
   }
 })();
+
+// --- Entity visibility filter tab (#1728) ---
+let visibilityVersion = 1;
+
+function _visibilityShowLoadError(msg) {
+  const el = document.getElementById('visibility-load-error');
+  if (!el) return;
+  el.style.display = msg ? '' : 'none';
+  el.textContent = msg || '';
+}
+
+function _visibilityParseList(value, sep) {
+  return value.split(sep).map(s => s.trim()).filter(Boolean);
+}
+
+async function visibilityLoadConfig() {
+  _visibilityShowLoadError('');
+  let resp;
+  try {
+    resp = await fetch('./api/visibility/config');
+  } catch (e) {
+    _visibilityShowLoadError('Could not reach the server: ' + e.message);
+    return;
+  }
+  if (!resp.ok) {
+    let detail = 'HTTP ' + resp.status;
+    try {
+      const body = await resp.json();
+      if (body && body.error) detail = body.error;
+      if (body && body.visibility_file_corrupt) {
+        detail += ' (entity_visibility.json appears corrupt; edit or delete it on the App (add-on) /data volume)';
+      }
+    } catch (_e) { /* keep the HTTP-status fallback */ }
+    _visibilityShowLoadError('Failed to load visibility config: ' + detail);
+    return;
+  }
+  const c = await resp.json();
+  visibilityVersion = c.version ?? 1;
+  const cats = c.exclude_categories || [];
+  document.getElementById('visibility-enabled').checked = !!c.enabled;
+  document.getElementById('visibility-cat-diagnostic').checked = cats.includes('diagnostic');
+  document.getElementById('visibility-cat-config').checked = cats.includes('config');
+  document.getElementById('visibility-exclude-hidden').checked = !!c.exclude_hidden;
+  document.getElementById('visibility-areas').value = (c.exclude_areas || []).join(', ');
+  document.getElementById('visibility-labels').value = (c.exclude_labels || []).join(', ');
+  document.getElementById('visibility-deny').value = (c.deny_entity_ids || []).join('\n');
+  document.getElementById('visibility-allow-areas').value = (c.allow_areas || []).join(', ');
+  document.getElementById('visibility-allow-labels').value = (c.allow_labels || []).join(', ');
+  document.getElementById('visibility-allow-entities').value = (c.allow_entity_ids || []).join('\n');
+  document.getElementById('visibility-respect-assist').checked = !!c.respect_assist_exposure;
+}
+
+async function visibilitySaveConfig() {
+  const statusEl = document.getElementById('visibility-save-status');
+  const cats = [];
+  if (document.getElementById('visibility-cat-diagnostic').checked) cats.push('diagnostic');
+  if (document.getElementById('visibility-cat-config').checked) cats.push('config');
+  const config = {
+    version: visibilityVersion,
+    enabled: document.getElementById('visibility-enabled').checked,
+    exclude_categories: cats,
+    exclude_hidden: document.getElementById('visibility-exclude-hidden').checked,
+    deny_entity_ids: _visibilityParseList(document.getElementById('visibility-deny').value, '\n'),
+    exclude_areas: _visibilityParseList(document.getElementById('visibility-areas').value, ','),
+    exclude_labels: _visibilityParseList(document.getElementById('visibility-labels').value, ','),
+    allow_areas: _visibilityParseList(document.getElementById('visibility-allow-areas').value, ','),
+    allow_labels: _visibilityParseList(document.getElementById('visibility-allow-labels').value, ','),
+    allow_entity_ids: _visibilityParseList(document.getElementById('visibility-allow-entities').value, '\n'),
+    respect_assist_exposure: document.getElementById('visibility-respect-assist').checked,
+  };
+  setStatusAlert(statusEl, false);
+  statusEl.textContent = 'Saving...';
+  let resp;
+  try {
+    resp = await fetch('./api/visibility/config', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(config),
+    });
+  } catch (e) {
+    setStatusAlert(statusEl, true);
+    statusEl.textContent = 'Save failed: ' + e.message;
+    return;
+  }
+  if (resp.status === 409) {
+    // Do NOT reload the config here: that would overwrite the user's unsaved
+    // edits (there would be nothing left to "re-apply"). Keep the edits in the
+    // form, surface the conflict, and let the user reload deliberately — mirrors
+    // the policy tab's optimistic-lock message.
+    setStatusAlert(statusEl, true);
+    statusEl.textContent =
+      'Config was changed in another tab or session. Reload the page to see the '
+      + 'latest, then re-apply your changes.';
+    return;
+  }
+  if (!resp.ok) {
+    let detail = 'HTTP ' + resp.status;
+    try { const b = await resp.json(); if (b && b.error) detail = b.error; } catch (_e) { /* fallback */ }
+    setStatusAlert(statusEl, true);
+    statusEl.textContent = 'Save failed: ' + detail;
+    return;
+  }
+  const body = await resp.json();
+  visibilityVersion = body.version ?? (visibilityVersion + 1);
+  setStatusAlert(statusEl, false);
+  statusEl.textContent = 'Saved.';
+}
+
+(function wireVisibilitySave() {
+  const btn = document.getElementById('visibility-save-btn');
+  if (btn) btn.addEventListener('click', visibilitySaveConfig);
+})();

{ha_mcp_dev-7.9.0.dev764 → ha_mcp_dev-7.9.0.dev765}/src/ha_mcp/tools/smart_search/_deep.py

@@ -92,7 +92,11 @@ class DeepSearchMixin(SceneSearchMixin):
                 ctx,
                 progress=phase_done,
                 total=total_phases,
-                message=f"fetched {len(all_entities)} entity states",
+                # Config-reference search scans the full state machine by design
+                # (the config body is unfiltered), so this count is the scanned
+                # universe, not the visible one - phrase it so an operator with
+                # the visibility filter on doesn't read it as "the filter is off".
+                message=f"scanned {len(all_entities)} entity states for config references",
             )
 
             # Pre-resolve unique_ids from cached entity states to avoid redundant API calls

{ha_mcp_dev-7.9.0.dev764 → ha_mcp_dev-7.9.0.dev765}/src/ha_mcp/tools/smart_search/_entities.py

@@ -5,7 +5,9 @@ import logging
 from typing import Any
 
 from ...utils.fuzzy_search import calculate_partial_ratio
+from ...visibility.resolver import load_hidden_set
 from ..helpers import exception_to_structured_error
+from ..util_helpers import merge_visibility_warnings
 from ._base import _SearchBase
 
 logger = logging.getLogger(__name__)
@@ -47,7 +49,9 @@ class EntitySearchMixin(_SearchBase):
             if domain_filter:
                 domain_filter = domain_filter.strip().lower()
 
-            entities = await self._fetch_search_entities(domain_filter, include_hidden)
+            entities, visibility_warnings = await self._fetch_search_entities(
+                domain_filter, include_hidden
+            )
 
             # Perform fuzzy search - returns (paginated_results, total_count)
             matches, total_matches = self.fuzzy_searcher.search_entities(
@@ -73,7 +77,7 @@ class EntitySearchMixin(_SearchBase):
                     entities, query
                 )
 
-            return response
+            return merge_visibility_warnings(response, visibility_warnings)
 
         except Exception as e:
             logger.error(f"Error in smart_entity_search: {e}")
@@ -115,6 +119,7 @@ class EntitySearchMixin(_SearchBase):
         entities: list[dict[str, Any]],
         registry_slim: dict[str, dict[str, Any]],
         include_hidden: bool,
+        visibility_hidden: set[str],
     ) -> tuple[list[str], list[dict[str, Any]]]:
         """Drop UI-hidden entities (unless include_hidden); collect survivor ids.
 
@@ -127,6 +132,8 @@ class EntitySearchMixin(_SearchBase):
             eid = entity.get("entity_id", "")
             if not eid:
                 continue
+            if eid in visibility_hidden:
+                continue
             slim = registry_slim.get(eid, {})
             hidden_by = slim.get("hidden_by")
             if hidden_by is not None and not include_hidden:
@@ -175,7 +182,7 @@ class EntitySearchMixin(_SearchBase):
 
     async def _fetch_search_entities(
         self, domain_filter: str | None, include_hidden: bool
-    ) -> list[dict[str, Any]]:
+    ) -> tuple[list[dict[str, Any]], list[str]]:
         """Fetch + enrich the entity set fed into the fuzzy search layer.
 
         Fetches states + the slim entity-registry list in parallel (the slim
@@ -187,6 +194,7 @@ class EntitySearchMixin(_SearchBase):
         results = await asyncio.gather(
             self.client.get_states(),
             self.client.send_websocket_message({"type": "config/entity_registry/list"}),
+            self.client.send_websocket_message({"type": "config/device_registry/list"}),
             return_exceptions=True,
         )
         # States-fetch failure is fatal — auth/connection errors must propagate
@@ -194,15 +202,26 @@ class EntitySearchMixin(_SearchBase):
         # with success=True.
         if isinstance(results[0], BaseException):
             raise results[0]
-        # CancelledError on the registry task must propagate too; gather captures
+        # CancelledError on the registry tasks must propagate too; gather captures
         # it like any other exception when return_exceptions=True.
         if isinstance(results[1], asyncio.CancelledError):
             raise results[1]
+        if isinstance(results[2], asyncio.CancelledError):
+            raise results[2]
         entities = results[0]
 
+        # Opt-in visibility filter. results[1] is the unprojected registry, so
+        # entity_category/hidden_by/area_id/labels are present (the slim map
+        # below drops them); results[2] is the device registry, which lets the
+        # area/label dimensions match a device-bound entity by its device's
+        # area/labels. Fails open; do NOT wrap in try/except or the failure mode
+        # inverts.
+        visibility_hidden, visibility_warnings = await load_hidden_set(
+            results[1], results[0], self.client, results[2]
+        )
         registry_slim = self._build_registry_slim(results[1])
         survivor_ids, survivor_states = self._filter_hidden_entities(
-            entities, registry_slim, include_hidden
+            entities, registry_slim, include_hidden, visibility_hidden
         )
         aliases_map = await self._fetch_entity_aliases(survivor_ids)
 
@@ -226,7 +245,7 @@ class EntitySearchMixin(_SearchBase):
                 for e in enriched
                 if e.get("entity_id", "").startswith(f"{domain_filter}.")
             ]
-        return enriched
+        return enriched, visibility_warnings
 
     @staticmethod
     def _format_entity_matches(
@@ -293,7 +312,27 @@ class EntitySearchMixin(_SearchBase):
                 return_exceptions=True,
             )
 
-            entities = results[0] if not isinstance(results[0], Exception) else []
+            # States are mandatory — surface connection/auth errors instead of a
+            # bogus empty area result with success=True (mirrors
+            # _fetch_search_entities). The registry results below still fail open.
+            if isinstance(results[0], BaseException):
+                raise results[0]
+            entities = results[0]
+            # A registry sub-task that was individually cancelled must propagate,
+            # not be silently degraded to an empty registry by the parsers below
+            # (mirrors _fetch_search_entities). Non-cancellation registry errors
+            # still fail open.
+            for reg_result in results[1:]:
+                if isinstance(reg_result, asyncio.CancelledError):
+                    raise reg_result
+            # Opt-in visibility filter. results[2] is the unprojected entity
+            # registry, so entity_category/hidden_by/area_id/labels are present;
+            # results[3] is the device registry, so the area/label dimensions
+            # match a device-bound entity by its device's area/labels.
+            # Fails open (empty set on any error / non-dict payload).
+            visibility_hidden, visibility_warnings = await load_hidden_set(
+                results[2], results[0], self.client, results[3]
+            )
             area_registry = self._parse_area_registry(results[1])
             entity_reg_map = self._parse_entity_reg_map(results[2])
             device_area_map = self._parse_device_area_map(results[3])
@@ -302,19 +341,22 @@ class EntitySearchMixin(_SearchBase):
             matched_area_ids = self._match_area_ids(area_registry, area_query_lower)
 
             if not matched_area_ids:
-                return {
-                    "area_query": area_query,
-                    "total_areas_found": 0,
-                    "total_entities": 0,
-                    "areas": {},
-                    "available_areas": [
-                        {"area_id": aid, "name": ainfo.get("name", aid)}
-                        for aid, ainfo in area_registry.items()
-                    ],
-                }
+                return merge_visibility_warnings(
+                    {
+                        "area_query": area_query,
+                        "total_areas_found": 0,
+                        "total_entities": 0,
+                        "areas": {},
+                        "available_areas": [
+                            {"area_id": aid, "name": ainfo.get("name", aid)}
+                            for aid, ainfo in area_registry.items()
+                        ],
+                    },
+                    visibility_warnings,
+                )
 
             entity_area_resolved, hidden_entity_ids = self._resolve_entity_areas(
-                entity_reg_map, device_area_map, include_hidden
+                entity_reg_map, device_area_map, include_hidden, visibility_hidden
             )
             state_map = self._build_state_map(entities)
             formatted_areas, total_entities = self._format_area_entities(
@@ -326,12 +368,15 @@ class EntitySearchMixin(_SearchBase):
                 group_by_domain,
             )
 
-            return {
-                "area_query": area_query,
-                "total_areas_found": len(formatted_areas),
-                "total_entities": total_entities,
-                "areas": formatted_areas,
-            }
+            return merge_visibility_warnings(
+                {
+                    "area_query": area_query,
+                    "total_areas_found": len(formatted_areas),
+                    "total_entities": total_entities,
+                    "areas": formatted_areas,
+                },
+                visibility_warnings,
+            )
 
         except Exception as e:
             logger.error(f"Error in get_entities_by_area: {e}")
@@ -438,6 +483,7 @@ class EntitySearchMixin(_SearchBase):
         entity_reg_map: dict[str, dict[str, str | None]],
         device_area_map: dict[str, str | None],
         include_hidden: bool,
+        visibility_hidden: set[str],
     ) -> tuple[dict[str, str], set[str]]:
         """Map entity_id -> resolved area_id (entity area > device area).
 
@@ -449,6 +495,8 @@ class EntitySearchMixin(_SearchBase):
         entity_area_resolved: dict[str, str] = {}
         hidden_entity_ids: set[str] = set()
         for entity_id, reg_info in entity_reg_map.items():
+            if entity_id in visibility_hidden:
+                continue
             is_hidden = reg_info.get("hidden_by") is not None
             if is_hidden and not include_hidden:
                 continue

{ha_mcp_dev-7.9.0.dev764 → ha_mcp_dev-7.9.0.dev765}/src/ha_mcp/tools/smart_search/_overview.py

@@ -5,6 +5,7 @@ import logging
 import random
 from typing import Any
 
+from ...visibility.resolver import load_hidden_set
 from ..helpers import exception_to_structured_error
 from ._base import _SearchBase
 from ._config import _simplify_states_summary
@@ -64,11 +65,38 @@ class SystemOverviewMixin(_SearchBase):
             )
 
             # Entities are mandatory — surface connection/auth errors immediately.
-            if isinstance(results[0], Exception):
+            # Use BaseException so a cancelled states fetch propagates instead of
+            # being assigned to `entities` and crashing downstream iteration
+            # (mirrors get_entities_by_area / _fetch_search_entities).
+            if isinstance(results[0], BaseException):
                 raise results[0]
             entities = results[0]
+            # A cancelled services/registry sub-task must propagate too, not be
+            # silently degraded by the fail-open handlers below.
+            for sub_result in results[1:]:
+                if isinstance(sub_result, asyncio.CancelledError):
+                    raise sub_result
+
+            # Opt-in visibility filter: drop out-of-scope entities from the whole
+            # overview universe before any domain stats/samples are computed, so
+            # every count stays coherent. results[3] is the raw entity registry,
+            # results[4] the device registry (so the area/label dimensions match a
+            # device-bound entity by its device's area/labels).
+            # Fails open (empty set on any error); do NOT wrap in try/except.
+            visibility_hidden, visibility_warnings = await load_hidden_set(
+                results[3], results[0], self.client, results[4]
+            )
+            if visibility_hidden:
+                entities = [
+                    e for e in entities if e.get("entity_id") not in visibility_hidden
+                ]
 
-            # Services failure affects total count + catalog; log at warning.
+            # Services failure means the total count + catalog are genuinely
+            # incomplete, so it sets `partial`. Visibility warnings are kept
+            # separate: they annotate an otherwise-complete result (a config typo
+            # or a skipped Assist dimension), so they must surface in `warnings`
+            # without flipping `partial` — aligning with ha_search, which reports
+            # the same visibility warnings and never marks itself partial for them.
             partial_warnings: list[str] = []
             if isinstance(results[1], Exception):
                 logger.warning(f"Could not fetch services: {results[1]}")
@@ -125,7 +153,8 @@ class SystemOverviewMixin(_SearchBase):
                 formatted_domain_stats, limit, offset, detail_level
             )
 
-            # totals always reflect the full system, regardless of filtering
+            # totals reflect the full (visibility-filtered) system and are not
+            # narrowed by the domains_filter display filter below
             system_summary: dict[str, Any] = {
                 "total_entities": len(entities),
                 "total_domains": len(all_domains),
@@ -143,6 +172,7 @@ class SystemOverviewMixin(_SearchBase):
                 detail_level=detail_level,
                 pagination_metadata=pagination_metadata,
                 partial_warnings=partial_warnings,
+                visibility_warnings=visibility_warnings,
                 device_types=device_types,
                 service_stats=service_stats,
             )
@@ -162,9 +192,10 @@ class SystemOverviewMixin(_SearchBase):
                     "controllable_devices": {},
                 },
             )
-            # exception_to_structured_error always raises; unreachable but makes
-            # every code path return explicitly (py/mixed-returns).
-            return None
+            # ``exception_to_structured_error`` always raises (NoReturn); the
+            # explicit re-raise makes the exit unambiguous and matches the
+            # sibling handlers in get_entities_by_area / _fetch_search_entities.
+            raise
 
     @staticmethod
     def _build_entity_area_map(
@@ -478,6 +509,7 @@ class SystemOverviewMixin(_SearchBase):
         detail_level: str,
         pagination_metadata: dict[str, Any] | None,
         partial_warnings: list[str],
+        visibility_warnings: list[str],
         device_types: dict[str, int],
         service_stats: dict[str, dict[str, Any]],
     ) -> dict[str, Any]:
@@ -497,9 +529,14 @@ class SystemOverviewMixin(_SearchBase):
         if pagination_metadata:
             base_response["pagination"] = pagination_metadata
 
+        # Only genuinely incomplete data (e.g. a failed services fetch) marks the
+        # response partial; visibility warnings annotate a complete result. Both
+        # surface in `warnings`.
         if partial_warnings:
             base_response["partial"] = True
-            base_response["warnings"] = partial_warnings
+        all_warnings = partial_warnings + visibility_warnings
+        if all_warnings:
+            base_response["warnings"] = all_warnings
 
         # Full: add device types and service catalog
         if detail_level == "full":