ha-mcp-dev 8.3.0.dev2419__tar.gz → 8.3.0.dev2425__tar.gz

{ha_mcp_dev-8.3.0.dev2419/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2425}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.3.0.dev2419
+Version: 8.3.0.dev2425
 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.3.0.dev2419 → ha_mcp_dev-8.3.0.dev2425}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2419"
+version = "8.3.0.dev2425"
 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
@@ -256,8 +256,9 @@ markers = [
     "error_handling: error handling and edge case tests",
     "cleanup: tests that create entities needing cleanup",
     "performance: performance measurement and regression tests",
-    "external_only: skips on HAOS inaddon tier (server runs in a separate addon container, so in-process env monkeypatching doesn't reach it)",
+    "external_only: in-process-server tiers only; skips inaddon, stdio, container-embedded, and HAOS-embedded servers",
     "inaddon_only: only runs on HAOS inaddon tier",
+    "beta_haos_only: beta HAOS image lanes with Supervisor/Core version expectations configured",
 ]
 asyncio_mode = "auto"
 

{ha_mcp_dev-8.3.0.dev2419 → ha_mcp_dev-8.3.0.dev2425}/src/ha_mcp/__main__.py

@@ -33,15 +33,13 @@ import threading  # noqa: E402
 from collections.abc import Coroutine  # noqa: E402
 from typing import TYPE_CHECKING, Any, NoReturn  # noqa: E402
 
-from fastmcp.exceptions import ToolError  # noqa: E402
-from pydantic import ValidationError as PydanticValidationError  # noqa: E402
-
 from ha_mcp.browser_landing import (  # noqa: E402
     register_browser_landing as _register_landing_route,
 )
 from ha_mcp.browser_landing import (  # noqa: E402
     register_healthz as _register_healthz_route,
 )
+from ha_mcp.log_filters import install_sdk_log_filters  # noqa: E402
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -384,68 +382,6 @@ mcp = _DeferredMCP()
 _LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
 
 
-class StatelessSessionLogFilter(logging.Filter):
-    """Suppress the routine 'Terminating session: None' log from the MCP SDK.
-
-    In stateless HTTP mode every request creates and tears down a temporary
-    session whose id is ``None``, so the SDK emits an INFO
-    ``Terminating session: None`` (mcp/server/streamable_http.py) on *every*
-    request. The line is routine but looks alarming and has repeatedly
-    confused users into thinking the connection is broken.
-
-    Returning ``False`` drops the record at this logger before it reaches any
-    handler. (Merely downgrading the level to DEBUG did not work: the level
-    gate is applied before the filter runs, so the record was already admitted
-    and still emitted -- just relabelled.) Real session terminations carry an
-    actual id and are not matched, so they still log.
-
-    # TODO: remove when modelcontextprotocol/python-sdk#2329 is resolved
-    """
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        if record.name != "mcp.server.streamable_http":
-            return True
-        try:
-            message = record.getMessage()
-        except (ValueError, TypeError):
-            # A malformed %-format record on this logger is not our target, and
-            # a filter must not raise: filters run in Logger.handle() with no
-            # exception handling, so a raise would crash the logging call.
-            return True
-        # Drop the stateless teardown noise; keep everything else.
-        return "Terminating session: None" not in message
-
-
-class ToolValidationLogFilter(logging.Filter):
-    """Demote fastmcp tool-failure tracebacks to single-line warnings.
-
-    Pydantic ValidationError and tool-raised ToolError aren't server bugs,
-    so the traceback through fastmcp/pydantic internals is just noise. The
-    structured error detail is preserved in the WARNING message; stack is
-    intentionally dropped because these are user-input errors, not bugs.
-    """
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        if record.name != "fastmcp.server.server" or not record.exc_info:
-            return True
-
-        msg = record.getMessage()
-        err = record.exc_info[1]
-        if "Error validating tool" in msg and isinstance(err, PydanticValidationError):
-            record.msg = f"{msg}: {err.errors(include_url=False)}"
-        elif "Error calling tool" in msg and isinstance(err, ToolError):
-            record.msg = f"{msg}: {err}"
-        else:
-            return True
-
-        record.args = ()
-        record.levelno = logging.WARNING
-        record.levelname = "WARNING"
-        record.exc_info = None
-        record.exc_text = None
-        return True
-
-
 class ProbeAccessLogFilter(logging.Filter):
     """Drop benign, non-MCP HTTP probe noise from the uvicorn access log.
 
@@ -528,10 +464,7 @@ def _setup_logging(log_level_str: str, force: bool = True) -> None:
         # disabled. Prevent that NOTSET namespace from inheriting our root handler.
         fastmcp_logger.setLevel(logging.CRITICAL + 1)
 
-    logging.getLogger("mcp.server.streamable_http").addFilter(
-        StatelessSessionLogFilter()
-    )
-    logging.getLogger("fastmcp.server.server").addFilter(ToolValidationLogFilter())
+    install_sdk_log_filters()
 
 
 def _log_startup_version() -> None:

{ha_mcp_dev-8.3.0.dev2419 → ha_mcp_dev-8.3.0.dev2425}/src/ha_mcp/client/rest_client.py

@@ -704,8 +704,9 @@ class HomeAssistantClient:
     async def get_addon_logs(self, slug: str, lines: int | None = None) -> str:
         """Fetch an add-on's container logs.
 
-        Branch on ``is_running_in_addon()`` (which keys off ``SUPERVISOR_TOKEN``
-        in env): inside the add-on container goes directly to the Supervisor
+        Branch on ``is_running_in_addon()``, which requires a truthy
+        ``SUPERVISOR_TOKEN`` and excludes ``HA_MCP_EMBEDDED``: inside the app
+        (add-on) container goes directly to the Supervisor
         REST API at ``http://supervisor/addons/{slug}/logs`` with the
         Supervisor token. The HA Core proxy at
         ``/api/hassio/addons/{slug}/logs`` rejects this token+path combination
@@ -730,8 +731,9 @@ class HomeAssistantClient:
         Raises:
             HomeAssistantAuthError: 401 response, or ``SUPERVISOR_TOKEN`` empty
                 at call time on the addon branch.
-            HomeAssistantAPIError: 403 (role too low — addon needs hassio_role
-                ``manager``), 404 (unknown slug), or other non-2xx. The
+            HomeAssistantAPIError: 403 (unrecognized token, missing
+                ``hassio_api``, or insufficient ``hassio_role``), 404
+                (unknown slug), or other non-2xx. The
                 ``status_code`` attribute lets callers map to specific
                 suggestions.
             HomeAssistantConnectionError: Network, timeout, or transport error.
@@ -775,25 +777,28 @@ class HomeAssistantClient:
 
         ``path`` is everything between ``http://supervisor/`` and ``/logs``:
 
-        - ``"addons/<slug>"`` for add-on container logs
+        - ``"addons/<slug>"`` for app (add-on) container logs
         - ``"<service>"`` (where service ∈ {supervisor, host, core, dns, audio,
           cli, multicast, observer}) for system-service logs
 
         ``lines`` maps to the endpoint's ``?lines=`` journald-window query
         param; omitted → Supervisor's 100-line default window.
 
-        Bypasses ``HomeAssistantClient.httpx_client`` because the Supervisor
-        endpoint uses a different base URL (``http://supervisor``) and a
-        different token (``SUPERVISOR_TOKEN``) than HA Core REST. Both
-        endpoints require the addon's ``hassio_role`` to be ``manager`` (not
-        ``default``); a ``default`` role gets a 403 here — see #1116.
+        Bypasses ``HomeAssistantClient.httpx_client`` because that client targets
+        Home Assistant Core through ``http://supervisor/core/api``, while logs
+        belong to Supervisor at ``http://supervisor``. Both clients use the same
+        ``SUPERVISOR_TOKEN``; the Core proxy requires ``homeassistant_api``, while
+        system-service and arbitrary app-log paths require ``hassio_api`` and
+        ``hassio_role: manager``. The recognized-app-token exception is
+        ``/addons/self/logs``.
 
         Raises:
             HomeAssistantAuthError: ``SUPERVISOR_TOKEN`` absent at call time,
                 or 401 from Supervisor.
-            HomeAssistantAPIError: 403 (role too low — distinct branch with
-                role hint), 404, other 4xx/5xx. Tries to parse Supervisor's
-                ``{"result":"error","message":"..."}`` JSON envelope before
+            HomeAssistantAPIError: 403 (unrecognized token, missing
+                ``hassio_api``, or insufficient role), 404, other 4xx/5xx.
+                Parses Supervisor's ``{"result":"error","message":"..."}``
+                JSON envelope before
                 falling back to text body / reason phrase / placeholder.
             HomeAssistantConnectionError: Timeout or transport error, with
                 distinct messages so callers can tell them apart.
@@ -839,18 +844,19 @@ class HomeAssistantClient:
         if response.status_code == 401:
             raise HomeAssistantAuthError(f"Invalid Supervisor token for /{path}/logs")
         if response.status_code == 403:
-            # Distinct from 401: token is valid but addon's hassio_role isn't
-            # high enough. Most-likely cause for this exact endpoint at the
-            # time #1116 surfaced (default → manager bump in addon config.yaml
-            # is the same-PR companion fix).
+            # Supervisor uses 403 for an unrecognized app token, missing
+            # hassio_api permission, or a hassio_role that cannot access this
+            # endpoint. The default-to-manager role bump fixed #1116, but it is
+            # not the only possible cause.
             logger.warning(
-                "Supervisor returned 403 for /%s/logs — addon hassio_role may "
-                "be too low (need 'manager')",
+                "Supervisor returned 403 for /%s/logs — check token, hassio_api, "
+                "and hassio_role (need 'manager')",
                 path,
             )
             raise HomeAssistantAPIError(
-                f"Supervisor forbids /{path}/logs (403) — addon's hassio_role "
-                "may be 'default'; need 'manager' or higher",
+                f"Supervisor forbids /{path}/logs (403) — token may be unrecognized, "
+                "app may lack hassio_api, or hassio_role may not allow this endpoint "
+                "(manager required)",
                 status_code=403,
                 response_data={"path": path},
             )
@@ -873,14 +879,15 @@ class HomeAssistantClient:
     async def _get_addon_logs_via_supervisor(
         self, slug: str, lines: int | None = None
     ) -> str:
-        """Fetch add-on container logs directly from Supervisor's REST API.
+        """Fetch app (add-on) container logs directly from Supervisor REST.
 
-        Distinct from ``tools_bug_report._fetch_addon_logs``: that helper is
-        hardcoded to ``/addons/self/logs`` and silently swallows failures
-        (it's an aux-data fetch for bug reports, fine to skip on error). This
-        helper takes arbitrary slugs and surfaces failures as exceptions
-        because callers (``ha_get_logs(source="supervisor", slug=...)``) need
-        them. Both endpoints require ``hassio_role: manager``.
+        Distinct from ``tools_bug_report._fetch_addon_logs``: that auxiliary
+        helper uses the app self-service path ``/addons/self/logs`` and may skip
+        failures. This helper takes arbitrary slugs and surfaces failures because
+        callers (``ha_get_logs(source="supervisor", slug=...)``) need them.
+        Arbitrary app-log slugs require a recognized app token with ``hassio_api``
+        and ``hassio_role: manager``; ``/addons/self/logs`` bypasses the role and
+        API-permission checks but still requires a recognized app token.
 
         Delegates to ``_supervisor_logs_get`` so error handling stays in
         lockstep with ``_get_system_service_logs``.
@@ -895,26 +902,21 @@ class HomeAssistantClient:
         ``service`` must be one of the eight Supervisor-managed services:
         ``supervisor``, ``host``, ``core``, ``dns``, ``audio``, ``cli``,
         ``multicast``, ``observer``. Caller is responsible for validating
-        ``service`` against the allowed set; this helper does no validation
-        and will raise ``HomeAssistantAPIError`` on any unknown path (404).
+        ``service``; this helper performs no validation, and unsupported paths
+        are rejected by the selected direct-Supervisor or Core-proxy route.
 
         Branch on ``is_running_in_addon()`` — mirror of ``get_addon_logs``:
-        inside the addon container goes directly to Supervisor at
+        inside the app (add-on) container goes directly to Supervisor at
         ``http://supervisor/{service}/logs`` with the Supervisor token
-        (``hassio_role: manager`` required). On non-addon installs (Docker
+        (``hassio_api`` and ``hassio_role: manager`` required). On non-app
+        installs (Docker
         without Supervisor, pyinstaller, pip pointing at a normal HA URL),
         falls back to the HA Core proxy at ``/api/hassio/{service}/logs``.
 
-        All seven slugs are whitelisted in HA Core's hassio proxy
+        All eight service slugs are whitelisted in HA Core's hassio proxy
         (``homeassistant/components/hassio/http.py`` — ``PATHS_ADMIN``), so
         an admin LLA is sufficient to reach any of them from outside the
-        addon.
-
-        Closes #1260: pre-fix this method had only the addon-direct branch,
-        so non-addon installs (the Docker image, uvx ha-mcp, etc.) hit the
-        ``SUPERVISOR_TOKEN``-absent fail-fast in ``_supervisor_logs_get`` for
-        every service, while the sibling ``source="supervisor"`` (addon
-        logs) call kept working through its own Core-proxy fallback.
+        app.
         """
         if is_running_in_addon():
             return await self._supervisor_logs_get(service, lines=lines)

{ha_mcp_dev-8.3.0.dev2419 → ha_mcp_dev-8.3.0.dev2425}/src/ha_mcp/client/supervisor_client.py

@@ -1,20 +1,14 @@
 """Shared factory for direct-Supervisor httpx clients.
 
-Three call sites in the codebase talk directly to the Home Assistant
-Supervisor REST API at ``http://supervisor`` rather than through
-``HomeAssistantClient.httpx_client`` (which is bound to HA Core, not the
-Supervisor — different base URL, different token, different role gate):
+Several code paths call the Home Assistant Supervisor REST API directly with
+a short-lived client configured for the Supervisor base URL and
+``SUPERVISOR_TOKEN``. Callers cover log collection, app (add-on) management
+and restart, backup operations, and screenshot-engine discovery.
 
-- :meth:`ha_mcp.client.rest_client.HomeAssistantClient._supervisor_logs_get`
-  — fetches addon and system-service logs
-- :func:`ha_mcp.tools.tools_bug_report._fetch_addon_logs` — bundles ha-mcp's
-  own addon logs into a bug-report payload
-- :func:`ha_mcp.settings_ui._handlers_server._restart_addon` — POSTs
-  ``/addons/self/restart`` from the settings UI
-
-All three share the same boilerplate (base URL, ``Authorization: Bearer
-${SUPERVISOR_TOKEN}`` header), so this module supplies a single factory and
-keeps the three sites consistent.
+These calls cannot use ``HomeAssistantClient.httpx_client``, which targets
+Home Assistant Core rather than Supervisor. In app mode it carries the same
+token value, but requests use a different base URL and authorization surface.
+This module centralizes the direct transport setup.
 """
 
 from __future__ import annotations
@@ -56,14 +50,11 @@ def make_supervisor_httpx_client(
 
     Raises:
         RuntimeError: ``SUPERVISOR_TOKEN`` is unset or empty in the
-            environment. Each call site has its own absent-token policy
-            (a rich :class:`HomeAssistantAuthError`, a silent ``""``
-            return, or a 400 ``JSONResponse``) that does not share a
-            common shape, so the factory cannot translate. Detecting the
-            absence at construction time prevents a malformed
-            ``Authorization: Bearer `` header from being read as a token
-            rejection by Supervisor, which would mask the missing-env-var
-            root cause.
+            environment. Callers must either gate construction on token
+            presence or translate this exception for their response surface.
+            Detecting it here prevents a malformed
+            ``Authorization: Bearer `` header from masking the missing
+            environment variable as a token rejection from Supervisor.
 
     Note:
         ``SUPERVISOR_TOKEN`` is read from env at construction time and

ha_mcp_dev-8.3.0.dev2425/src/ha_mcp/log_filters.py

@@ -0,0 +1,207 @@
+"""MCP SDK / fastmcp log-noise filters shared across every HTTP launcher.
+
+Extracted from :mod:`ha_mcp.__main__` for the same reason as
+:mod:`ha_mcp.browser_landing`: the in-process server (the ``ha_mcp_tools``
+custom-component worker thread) must never import ``ha_mcp.__main__``, since
+that module runs process-global side effects at import time
+(``truststore.inject_into_ssl()``, signal handlers, ``asyncio.run``). These
+filters only call ``logging.Logger.addFilter`` on specific named loggers --
+no ``basicConfig``, no handler or root-logger changes -- so
+``install_sdk_log_filters()`` is safe to call from any launcher, including
+one that must leave Home Assistant's own logging configuration untouched
+(see the ``log_config=None`` comment in ``embedded_server.py``).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import anyio
+from fastmcp.exceptions import ToolError
+from pydantic import ValidationError as PydanticValidationError
+
+
+class StatelessSessionLogFilter(logging.Filter):
+    """Suppress the routine 'Terminating session: None' log from the MCP SDK.
+
+    In stateless HTTP mode every request creates and tears down a temporary
+    session whose id is ``None``, so the SDK emits an INFO
+    ``Terminating session: None`` (mcp/server/streamable_http.py) on *every*
+    request. The line is routine but looks alarming and has repeatedly
+    confused users into thinking the connection is broken.
+
+    Returning ``False`` drops the record at this logger before it reaches any
+    handler. (Merely downgrading the level to DEBUG did not work: the level
+    gate is applied before the filter runs, so the record was already admitted
+    and still emitted -- just relabelled.) Real session terminations carry an
+    actual id and are not matched, so they still log.
+
+    # TODO: remove when modelcontextprotocol/python-sdk#2329 is resolved
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Drop the routine stateless-teardown record; pass everything else."""
+        if record.name != "mcp.server.streamable_http":
+            return True
+        try:
+            message = record.getMessage()
+        except (ValueError, TypeError):
+            # A malformed %-format record on this logger is not our target, and
+            # a filter must not raise: filters run in Logger.handle() with no
+            # exception handling, so a raise would crash the logging call.
+            return True
+        # Drop the stateless teardown noise; keep everything else.
+        return "Terminating session: None" not in message
+
+
+class ToolValidationLogFilter(logging.Filter):
+    """Demote fastmcp tool-failure tracebacks to single-line warnings.
+
+    Pydantic ValidationError and tool-raised ToolError aren't server bugs,
+    so the traceback through fastmcp/pydantic internals is just noise. The
+    structured error detail is preserved in the WARNING message; stack is
+    intentionally dropped because these are user-input errors, not bugs.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Demote a known-benign validation/tool-error record to WARNING."""
+        if record.name != "fastmcp.server.server" or not record.exc_info:
+            return True
+
+        msg = record.getMessage()
+        err = record.exc_info[1]
+        if "Error validating tool" in msg and isinstance(err, PydanticValidationError):
+            record.msg = f"{msg}: {err.errors(include_url=False)}"
+        elif "Error calling tool" in msg and isinstance(err, ToolError):
+            record.msg = f"{msg}: {err}"
+        else:
+            return True
+
+        record.args = ()
+        record.levelno = logging.WARNING
+        record.levelname = "WARNING"
+        record.exc_info = None
+        record.exc_text = None
+        return True
+
+
+_DISCONNECT_TEARDOWN_ERRORS = (anyio.ClosedResourceError, anyio.BrokenResourceError)
+
+
+def _is_only_disconnect_teardown_errors(err: BaseException) -> bool:
+    """True if ``err`` is (or an ExceptionGroup wrapping only) a benign
+    streamable-HTTP memory-stream teardown error.
+
+    ``mcp.server.lowlevel.server.Server.run()`` dispatches each incoming
+    message via ``anyio.create_task_group().start_soon(...)``, so an error
+    raised while delivering one message's response is raised from a
+    task-group child -- anyio always wraps that in an ``ExceptionGroup``,
+    even for a single failure. The exception a "session crashed" log record
+    carries is therefore ``ExceptionGroup(...[<teardown error>])``, not a
+    bare one.
+
+    Both ``ClosedResourceError`` and ``BrokenResourceError`` -- sibling
+    ``Exception`` subclasses, neither a subclass of the other -- can surface
+    here for the same disconnect race: which one depends on which end
+    closed first (our end closing raises ``Closed``; the peer's
+    ``streamable_http`` ``terminate()`` closing first can wake a parked
+    sender into raising ``Broken`` instead, even though the situation is
+    identical from the caller's perspective). This repo already treats the
+    two as an equivalent pair for streamable-HTTP memory-stream teardown
+    elsewhere -- see ``tests/src/haos_runtime.py``'s transient-error tuple.
+
+    Recurse through (possibly nested) groups; any other leaf type means
+    this is not the known-benign disconnect race, so the caller should
+    leave the record alone.
+    """
+    if isinstance(err, _DISCONNECT_TEARDOWN_ERRORS):
+        return True
+    if isinstance(err, BaseExceptionGroup):
+        return bool(err.exceptions) and all(
+            _is_only_disconnect_teardown_errors(sub) for sub in err.exceptions
+        )
+    return False
+
+
+class SessionDisconnectLogFilter(logging.Filter):
+    """Demote 'session crashed' tracebacks caused by an already-gone client.
+
+    Every HTTP entry point runs Streamable HTTP in stateless mode (see
+    ``ha_mcp.__main__._http_run_kwargs``). A tool call slow enough to outlast
+    the client's patience -- a busy Home Assistant instance, a
+    resource-contended local LLM host on the client side, or an ordinary HTTP
+    timeout -- lets the SDK finish serving the response and tear the
+    transport down while ``app.run()`` is still working; the eventual attempt
+    to deliver the response then writes into an already-closed memory stream
+    and raises ``anyio.ClosedResourceError`` or ``anyio.BrokenResourceError``
+    (wrapped in an ``ExceptionGroup`` -- see
+    ``_is_only_disconnect_teardown_errors``). The SDK already catches this
+    (``except Exception: logger.exception(...)`` in both the stateless and
+    stateful session runners of mcp/server/streamable_http_manager.py) -- it
+    just logs it as an alarming ERROR-level traceback. That's an expected
+    race in a stateless HTTP protocol (the client already gave up), not a
+    server bug, so demote it the same way ToolValidationLogFilter demotes
+    other known-benign failures. Any other exception on this logger -- an
+    actual crash -- is left untouched.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Demote a disconnect-caused 'session crashed' record to WARNING."""
+        if record.name != "mcp.server.streamable_http_manager" or not record.exc_info:
+            return True
+
+        err = record.exc_info[1]
+        if err is None or not _is_only_disconnect_teardown_errors(err):
+            return True
+
+        record.msg = (
+            f"{record.getMessage()}: client disconnected before response delivery"
+        )
+        record.args = ()
+        record.levelno = logging.WARNING
+        record.levelname = "WARNING"
+        record.exc_info = None
+        record.exc_text = None
+        return True
+
+
+def _add_filter_once(logger_name: str, filter_cls: type[logging.Filter]) -> None:
+    """Attach one ``filter_cls`` instance to ``logger_name``, replacing any stale one.
+
+    ``install_sdk_log_filters()`` can run more than once per process: the
+    in-process embedded server calls it on every ``_serve()`` reload without
+    a process restart, and process-wide ``logging`` state (including each
+    named logger's filter list) persists across those reloads. Each reload
+    also re-imports this module from scratch (the embedded server purges
+    ``ha_mcp.*`` from ``sys.modules`` before reinstalling -- see
+    ``_purge_ha_mcp_modules``), so ``filter_cls`` is a BRAND NEW class object
+    each time, even though its name is unchanged. A same-``isinstance``-check
+    against a filter instance from a PREVIOUS generation would therefore
+    never match, letting filters accumulate one more stale instance per
+    reload forever. Match by ``(module, qualname)`` instead -- stable across
+    reloads of the same module path -- and drop every stale-generation match
+    before attaching the current one, so a logger never carries more than
+    one filter of a given conceptual type, and it's always this generation's.
+    """
+    logger = logging.getLogger(logger_name)
+    identity = (filter_cls.__module__, filter_cls.__qualname__)
+    logger.filters[:] = [
+        f
+        for f in logger.filters
+        if (type(f).__module__, type(f).__qualname__) != identity
+    ]
+    logger.addFilter(filter_cls())
+
+
+def install_sdk_log_filters() -> None:
+    """Attach the demotion filters above to their target SDK/fastmcp loggers.
+
+    Every HTTP launcher must call this: the CLI (``ha_mcp.__main__``), the
+    Home Assistant app's ``start.py``, and the in-process embedded server
+    (``ha_mcp_tools/embedded_server.py``) each build and run their own
+    Streamable HTTP app, so none of them share another launcher's logging
+    setup. Safe to call repeatedly -- see ``_add_filter_once``.
+    """
+    _add_filter_once("mcp.server.streamable_http", StatelessSessionLogFilter)
+    _add_filter_once("mcp.server.streamable_http_manager", SessionDisconnectLogFilter)
+    _add_filter_once("fastmcp.server.server", ToolValidationLogFilter)