homeassistant-ai
diff --git a/‎docs/FAQ.md‎
Lines changed: 87 additions & 0 deletions b/‎docs/FAQ.md‎
Lines changed: 87 additions & 0 deletions
diff --git a/‎src/ha_mcp/settings_ui/__init__.py‎
Lines changed: 60 additions & 0 deletions b/‎src/ha_mcp/settings_ui/__init__.py‎
Lines changed: 60 additions & 0 deletions
diff --git a/‎src/ha_mcp/settings_ui/settings.css‎
Lines changed: 15 additions & 0 deletions b/‎src/ha_mcp/settings_ui/settings.css‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎src/ha_mcp/settings_ui/settings.html‎
Lines changed: 65 additions & 0 deletions b/‎src/ha_mcp/settings_ui/settings.html‎
Lines changed: 65 additions & 0 deletions
@@ -311,6 +311,93 @@ The version should match the [latest release](https://github.com/homeassistant-a
 | `weak` | Rarely suggests backups |
 | `auto` | Same as normal (future: auto-detection) |
 
+### Entity visibility filter (opt-in)
+
+By default the agent sees every entity. If auto-generated diagnostic or helper
+entities clutter search and overview results, you can hide a chosen set of them
+from the *collection* read tools (`ha_search`, `ha_get_overview`). This is
+**noise reduction, not access control** – a hidden entity is still returned by a
+direct `ha_get_state` / `ha_get_entity` on its `entity_id`, and still appears in
+automation, dashboard, and template content, so do not rely on it as a security
+boundary.
+
+**Reads only – it does not gate control tools.** The filter scopes what the
+*collection read* tools return. It does **not** stop an agent from calling a
+service on a hidden `entity_id`: gating writes is a separate concern handled by
+the Tool Security Policies engine (which matches on a call's arguments), not by
+visibility. Visibility is deliberately read-scoping only, precisely because it
+is noise reduction and cannot be a security boundary (content-bearing reads such
+as automation and template bodies would leak hidden entities anyway).
+
+The easiest way to configure it is the **Entity Visibility** tab in the ha-mcp
+settings UI (enable toggle, category checkboxes, area/label fields, per-entity
+denylist). It reads and writes the same file described below, so either surface
+works.
+
+The filter is off until `entity_visibility.json` exists in the ha-mcp data
+directory (the same directory as `tool_policy.json`; `/data` in the add-on) with
+`"enabled": true`:
+
+```json
+{
+  "version": 1,
+  "enabled": true,
+  "exclude_categories": ["diagnostic", "config"],
+  "exclude_hidden": false,
+  "deny_entity_ids": [],
+  "exclude_areas": [],
+  "exclude_labels": [],
+  "allow_entity_ids": [],
+  "allow_areas": [],
+  "allow_labels": [],
+  "respect_assist_exposure": false
+}
+```
+
+The filter is a conjunction of independent dimensions: an entity is shown only if
+it passes every active one.
+
+- **Excludes / denylist.** An entity is hidden when its `entity_category` is in
+  `exclude_categories`, its `entity_id` is in `deny_entity_ids`, or its area/label
+  is in `exclude_areas` / `exclude_labels`. `exclude_categories` accepts only Home
+  Assistant's two entity categories (`diagnostic`, `config`); an unknown value is
+  ignored and surfaced as a `warnings` entry on the next read rather than silently
+  doing nothing. Set `exclude_hidden: true` to also fold in entities already
+  marked hidden in Home Assistant.
+- **Allowlist.** The moment any of `allow_entity_ids` / `allow_areas` /
+  `allow_labels` is non-empty, the filter inverts to *restrict* mode: only
+  entities matching an allowlist stay visible and everything else – including
+  entities added later – is hidden. Leave all three empty to keep the allowlist
+  off. `deny_entity_ids` still wins over an allow match — and so does any
+  `exclude_*` match: an entity an allowlist would admit but an
+  `exclude_categories` / `exclude_areas` / `exclude_labels` also hides stays
+  hidden (every dimension can only hide, so any one hide is enough — the allow
+  dimensions cannot un-hide what another dimension excluded).
+- **Respect Assist exposure.** With `respect_assist_exposure: true` the filter
+  hides entities not effectively exposed to Home Assistant's Assist
+  (`conversation`) assistant, mirroring `async_should_expose` (an explicit
+  per-entity exposure override wins; otherwise, if the instance exposes new
+  entities, the entity's domain and device-class defaults decide). Because HA
+  offers no single "effective exposure" API, the decision is reconstructed
+  client-side from two extra websocket reads per search — the set of entities
+  explicitly exposed to the assistant (`expose_entity/list`, which reports only
+  the *exposed* ones) and the "expose new entities" flag that drives the default
+  branch; if either read fails the dimension is skipped with a `warnings` note
+  rather than hiding everything. A registry entity's explicit override — exposed
+  *or* un-exposed — is read directly from the entity-registry `options` the
+  registry list already carries, so an explicit un-expose is honored. One residual
+  limit: for an entity that lives only in the state machine (a YAML/template entity
+  with no entity-registry entry), HA surfaces it through `expose_entity/list` only
+  when it is *exposed*; an explicit un-expose cannot be observed there, so such an
+  entity falls to its domain/device-class default and stays visible (fail-open).
+
+`version` drives optimistic-concurrency for the settings UI (it bumps
+on each save so two tabs can't clobber each other); when hand-editing the file,
+leave it as-is. The config is read live per request, so edits apply on the next
+call; a missing or invalid file leaves the filter off (and, when enabled but the
+registry read degrades, results are unfiltered with a `warnings` note rather than
+silently wrong).
+
 ---
 
 ## Feedback & Help
 
@@ -796,6 +796,61 @@ async def unavailable(_: Request) -> JSONResponse:
     }
 
 
+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 @@ async def _save_fs_custom_paths(request: Request) -> JSONResponse:
     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:
 
@@ -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;
+  }
@@ -158,6 +158,7 @@ <h1>HA-MCP Settings</h1>
   <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 @@ <h2 class="a11y-section-title">Custom colors</h2>
     <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">