ha-mcp-dev 8.1.1.dev2296__tar.gz → 8.2.0.dev2307__tar.gz

{ha_mcp_dev-8.1.1.dev2296/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.2.0.dev2307}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.1.1.dev2296
+Version: 8.2.0.dev2307
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastmcp==3.4.5
+Requires-Dist: fastmcp==3.4.6
 Requires-Dist: httpx[socks]==0.28.1
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: python-dotenv==1.2.2
@@ -117,7 +117,7 @@ These run the server outside Home Assistant — useful for **Container** / **Cor
 - **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
 - **PyPI / uvx (HTTP server):** run the published `ha-mcp` package with `uvx ha-mcp@latest` (or pip) as a streamable-HTTP server the same way. Details in the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/).
 - **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-command installers in the **Demo server** section below use this path; the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) covers connecting it to your own Home Assistant.
-- **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, Google, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).
+- **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).
 
   > ⚠️ **stdio has known transport issues.** The stdio transport has connection problems that streamable HTTP does not ([#1713](https://github.com/homeassistant-ai/ha-mcp/issues/1713)). It is recommended only for demo/testing tinkering — for a real setup, use the custom component or an HTTP method above.
 

{ha_mcp_dev-8.1.1.dev2296 → ha_mcp_dev-8.2.0.dev2307}/README.md

@@ -85,7 +85,7 @@ These run the server outside Home Assistant — useful for **Container** / **Cor
 - **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
 - **PyPI / uvx (HTTP server):** run the published `ha-mcp` package with `uvx ha-mcp@latest` (or pip) as a streamable-HTTP server the same way. Details in the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/).
 - **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-command installers in the **Demo server** section below use this path; the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) covers connecting it to your own Home Assistant.
-- **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, Google, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).
+- **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).
 
   > ⚠️ **stdio has known transport issues.** The stdio transport has connection problems that streamable HTTP does not ([#1713](https://github.com/homeassistant-ai/ha-mcp/issues/1713)). It is recommended only for demo/testing tinkering — for a real setup, use the custom component or an HTTP method above.
 

{ha_mcp_dev-8.1.1.dev2296 → ha_mcp_dev-8.2.0.dev2307}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.1.1.dev2296"
+version = "8.2.0.dev2307"
 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
@@ -28,7 +28,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "fastmcp==3.4.5",
+    "fastmcp==3.4.6",
     "httpx[socks]==0.28.1",
     "pydantic==2.13.4",
     "python-dotenv==1.2.2",

{ha_mcp_dev-8.1.1.dev2296 → ha_mcp_dev-8.2.0.dev2307}/src/ha_mcp/__init__.py

@@ -5,6 +5,10 @@ A Model Context Protocol server that provides complete control over Home Assista
 through REST API and WebSocket integration.
 """
 
+# Must be imported before anything that reaches fastmcp (``.auth`` below does),
+# because fastmcp configures rich logging at import time and dies on a rich
+# older than 13.9.4. Importing this module applies the shim. See #2186.
+from . import _rich_compat as _rich_compat
 from ._version import get_version
 
 __version__ = get_version()

{ha_mcp_dev-8.1.1.dev2296 → ha_mcp_dev-8.2.0.dev2307}/src/ha_mcp/__main__.py

@@ -503,15 +503,31 @@ def _setup_logging(log_level_str: str, force: bool = True) -> None:
     of the sweep ``force`` performs (which removes *and closes* every root
     handler) so ``ha_report_issue`` keeps its startup diagnostics.
     """
+    log_level = getattr(logging, log_level_str)
+
+    import fastmcp
+
     from ha_mcp.utils.usage_logger import preserve_startup_collector
 
     with preserve_startup_collector():
         logging.basicConfig(
-            level=getattr(logging, log_level_str),
+            level=log_level,
             format="%(asctime)s %(name)s %(levelname)s: %(message)s",
             datefmt=_LOG_DATE_FORMAT,
             force=force,
         )
+
+    fastmcp_logger = logging.getLogger("fastmcp")
+    if fastmcp.settings.log_enabled:
+        # FastMCP configures its own handler and disables propagation, so the root
+        # level above does not control its OIDC diagnostics. Preserve that handler
+        # and formatting while honoring ha-mcp's LOG_LEVEL setting.
+        fastmcp_logger.setLevel(log_level)
+    else:
+        # FastMCP deliberately leaves its logger unconfigured when logging is
+        # disabled. Prevent that NOTSET namespace from inheriting our root handler.
+        fastmcp_logger.setLevel(logging.CRITICAL + 1)
+
     logging.getLogger("mcp.server.streamable_http").addFilter(
         StatelessSessionLogFilter()
     )
@@ -1159,7 +1175,7 @@ def _oidc_verify_id_token_enabled() -> bool:
 
     Off by default: FastMCP's OIDCProxy verifies the access token as a JWT,
     which works for providers like Authentik and Keycloak. Providers that
-    issue opaque access tokens (Google always; Auth0 without an API
+    issue opaque access tokens (such as Authelia, or Auth0 without an API
     audience) need ``verify_id_token=True`` so FastMCP verifies the ID token
     instead.
     """
@@ -1599,7 +1615,7 @@ def main_oidc() -> None:
     """Run server with OIDC authentication over HTTP.
 
     This mode enables authentication via an external OIDC provider
-    (Authentik, Keycloak, Auth0, Google, etc.). All authenticated users
+    (Authentik, Keycloak, Auth0, etc.). All authenticated users
     share the same Home Assistant instance via the configured credentials.
 
     Unlike OAuth mode which collects per-user HA credentials via a consent form,
@@ -1621,7 +1637,7 @@ def main_oidc() -> None:
       patterns accepted from dynamically-registered clients. Strongly recommended for
       internet-facing deployments.
     - OIDC_VERIFY_ID_TOKEN (optional, default: false): Set true for providers that issue
-      opaque access tokens (e.g. Google, or Auth0 without an API audience).
+      opaque access tokens (e.g. Authelia, or Auth0 without an API audience).
     - OIDC_AUDIENCE (optional): Expected `aud` claim for IdP-issued access tokens.
       Without it (and with OIDC_VERIFY_ID_TOKEN off), FastMCP's JWT verifier checks
       issuer, signature, and expiry but not audience. With OIDC_VERIFY_ID_TOKEN=true,
@@ -1638,6 +1654,8 @@ def main_oidc() -> None:
     - HA_MCP_DISABLE_SETTINGS_UI (optional): set truthy to not serve the
       settings UI at all
     - LOG_LEVEL (optional, default: INFO)
+    - FASTMCP_LOG_ENABLED (optional, default: true): Set false to suppress
+      FastMCP framework logs while leaving ha-mcp logs at LOG_LEVEL.
     """
     # Configure logging for OIDC mode (force=True needed since logging may already be configured)
     log_level = os.getenv("LOG_LEVEL", "INFO").upper()
@@ -1723,8 +1741,7 @@ async def _run_oidc_server(
         port: Port to listen on
         path: MCP endpoint path
     """
-    from fastmcp.server.auth.oidc_proxy import OIDCProxy
-
+    from ha_mcp.auth.oidc_compat import HaMcpOIDCProxy
     from ha_mcp.server import HomeAssistantSmartMCPServer
     from ha_mcp.transport_security import ensure_host_origin_guard_default_off
 
@@ -1742,6 +1759,11 @@ async def _run_oidc_server(
         # IdP (Authentik, Keycloak, etc.) -- unlike `False`, this does not
         # log a security warning at startup that consent is disabled.
         "require_authorization_consent": "external",
+        # This entrypoint provides OIDC, so request the protocol-level scope
+        # that makes upstream providers return an ID token. FastMCP also
+        # advertises this scope through protected resource metadata so MCP
+        # clients include it in the authorization flow.
+        "required_scopes": ["openid"],
         # Preserve `or None`: an empty-but-set env var must not bypass
         # FastMCP's derive-from-client-secret default for jwt_signing_key.
         "jwt_signing_key": os.getenv("OIDC_JWT_SIGNING_KEY") or None,
@@ -1765,7 +1787,8 @@ async def _run_oidc_server(
         proxy_kwargs["audience"] = audience
 
     # Create OIDC auth provider — auto-discovers endpoints from config_url
-    auth = OIDCProxy(**proxy_kwargs)
+    auth = HaMcpOIDCProxy(**proxy_kwargs)
+    auth.setup_scope_compatibility()
 
     # Standard server with shared credentials (no proxy client needed)
     global _server

ha_mcp_dev-8.2.0.dev2307/src/ha_mcp/_rich_compat.py

@@ -0,0 +1,109 @@
+"""Tolerate a ``rich`` older than fastmcp's logging setup expects (#2186).
+
+``fastmcp/__init__.py`` calls ``configure_logging()`` at import time, which
+builds a ``rich.logging.RichHandler`` with ``tracebacks_max_frames`` and
+``tracebacks_suppress`` unconditionally — no version guard, no ``try``. Both
+keywords require ``rich>=13.9.4`` (``fastmcp-slim``'s declared floor), so an
+environment holding an older ``rich`` cannot ``import fastmcp`` at all::
+
+    TypeError: RichHandler.__init__() got an unexpected keyword argument
+    'tracebacks_max_frames'
+
+Since ``ha_mcp/__init__.py`` imports ``.auth`` -> ``fastmcp``, that takes the
+whole package down before any of our code runs. It is not hypothetical: the
+official Home Assistant container ships ``rich 10.16.2`` (held below 11 by
+``surepy``'s ``rich>=10.1.0,<11.0.0``) and ``rich`` is absent from HA's
+``package_constraints.txt``, so whether installing ``ha-mcp`` pulls ``rich``
+forward is left entirely to the resolver — it usually does, and when it does
+not the integration cannot start.
+
+The declared dependency floor is correct upstream and this module does not
+second-guess it: it only intervenes when the *installed* ``RichHandler``
+genuinely cannot accept a keyword, dropping the unsupported ones so logging
+setup degrades instead of aborting the import. On ``rich>=13.9.4`` it is a
+no-op. Handlers still attach and still render; such installs lose only
+traceback frame-limiting and framework-frame suppression, which beats not
+importing.
+
+Remove this once the upstream fix is released and ha-mcp's floor excludes the
+affected fastmcp versions.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Marker set on our wrapper so repeated calls do not stack wrappers.
+_PATCH_MARKER = "_ha_mcp_filters_unsupported_kwargs"
+
+# Present only on rich>=13.9.4; its absence is what makes fastmcp's call fatal.
+_PROBE_KWARG = "tracebacks_max_frames"
+
+
+def ensure_rich_handler_compat() -> bool:
+    """Make ``RichHandler`` ignore keywords the installed ``rich`` lacks.
+
+    Returns ``True`` when a shim is in place (freshly applied or already
+    applied), ``False`` when none is needed or none could be applied — an
+    unimportable ``rich``, an uninspectable ``__init__``, or a signature that
+    already absorbs ``**kwargs``.
+    """
+    try:
+        from rich.logging import RichHandler
+    except Exception:  # pragma: no cover - rich absent or broken
+        # fastmcp depends on rich, so this means the import would fail anyway
+        # for reasons this shim cannot address.
+        logger.debug("rich.logging unavailable; skipping RichHandler shim")
+        return False
+
+    original_init = RichHandler.__init__
+    if getattr(original_init, _PATCH_MARKER, False):
+        return True
+
+    try:
+        parameters = inspect.signature(original_init).parameters
+    except (TypeError, ValueError):  # pragma: no cover - exotic rich build
+        logger.debug("RichHandler.__init__ is not introspectable; skipping shim")
+        return False
+
+    if any(p.kind is inspect.Parameter.VAR_KEYWORD for p in parameters.values()):
+        # Already tolerant of anything fastmcp passes.
+        return False
+
+    if _PROBE_KWARG in parameters:
+        return False
+
+    supported = frozenset(parameters)
+
+    @functools.wraps(original_init)
+    def _init(self: Any, *args: Any, **kwargs: Any) -> Any:
+        dropped = kwargs.keys() - supported
+        if dropped:
+            logger.debug(
+                "Dropping RichHandler kwargs this rich does not accept: %s",
+                ", ".join(sorted(dropped)),
+            )
+        return original_init(
+            self, *args, **{k: v for k, v in kwargs.items() if k in supported}
+        )
+
+    setattr(_init, _PATCH_MARKER, True)
+    RichHandler.__init__ = _init  # type: ignore[method-assign]
+
+    logger.debug(
+        "Installed RichHandler compatibility shim: rich is older than "
+        "fastmcp expects, so tracebacks lose frame-limiting and "
+        "framework-frame suppression. Upgrade to rich>=13.9.4 to restore them."
+    )
+    return True
+
+
+# Applied as an import side effect: ``ha_mcp/__init__.py`` imports this module
+# ahead of anything that reaches fastmcp, and that is the only window in which
+# the shim can do any good.
+ensure_rich_handler_compat()

ha_mcp_dev-8.2.0.dev2307/src/ha_mcp/auth/oidc_compat.py

@@ -0,0 +1,106 @@
+"""FastMCP OIDC compatibility behavior scoped to ha-mcp's OIDC entrypoint."""
+
+from __future__ import annotations
+
+import logging
+from typing import override
+
+from fastmcp.server.auth.oauth_proxy.models import ProxyDCRClient
+from fastmcp.server.auth.oidc_proxy import OIDCProxy
+from mcp.server.auth.provider import AuthorizationParams, RefreshToken
+from mcp.shared.auth import OAuthClientInformationFull
+
+logger = logging.getLogger(__name__)
+
+
+class HaMcpOIDCProxy(OIDCProxy):
+    """OIDC proxy with ha-mcp's FastMCP 3.4.6 compatibility behavior."""
+
+    def _add_required_scopes(self, scopes: list[str]) -> list[str]:
+        """Prepend any configured required scopes missing from ``scopes``."""
+        missing_scopes = [
+            scope for scope in self.required_scopes if scope not in scopes
+        ]
+        return [*missing_scopes, *scopes]
+
+    def setup_scope_compatibility(self) -> None:
+        """Allow optional DCR scopes without advertising them as requirements.
+
+        FastMCP 3.4.6 copies ``required_scopes`` into both the DCR default and
+        valid-scope allow-list.  The MCP SDK then rejects clients that add
+        ordinary optional OIDC scopes.  ``None`` restores upstream IdP scope
+        validation while FastMCP continues to default, advertise, and enforce
+        ha-mcp's required ``openid`` scope.
+        """
+        if self.required_scopes != ["openid"]:
+            raise RuntimeError(
+                "HaMcpOIDCProxy requires exactly the openid scope before setup"
+            )
+        options = self.client_registration_options
+        if options is None:
+            raise RuntimeError("FastMCP OIDCProxy did not enable client registration")
+        if options.default_scopes != ["openid"] or self._default_scope_str != "openid":
+            raise RuntimeError("FastMCP OIDCProxy did not preserve the openid default")
+        options.valid_scopes = None
+
+    @override
+    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        """Persist DCR clients with every required scope included."""
+        current_scopes = client_info.scope.split() if client_info.scope else []
+        normalized_scopes = self._add_required_scopes(current_scopes)
+        if normalized_scopes != current_scopes:
+            client_info.scope = " ".join(normalized_scopes)
+        await super().register_client(client_info)
+
+    @override
+    async def authorize(
+        self,
+        client: OAuthClientInformationFull,
+        params: AuthorizationParams,
+    ) -> str:
+        """Forward every authorization with required scopes included."""
+        current_scopes = params.scopes or []
+        normalized_scopes = self._add_required_scopes(current_scopes)
+        if normalized_scopes != current_scopes:
+            params = params.model_copy(update={"scopes": normalized_scopes})
+        return await super().authorize(client, params)
+
+    @override
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        """Load a client, adding required scopes to persisted legacy records once."""
+        was_persisted = await self._client_store.get(key=client_id) is not None
+        client = await super().get_client(client_id)
+        if client is None or not was_persisted:
+            return client
+        if not isinstance(client, ProxyDCRClient):
+            raise RuntimeError("FastMCP returned an unexpected persisted client type")
+
+        current_scopes = client.scope.split() if client.scope else []
+        normalized_scopes = self._add_required_scopes(current_scopes)
+        if normalized_scopes == current_scopes:
+            return client
+
+        migrated = client.model_copy(update={"scope": " ".join(normalized_scopes)})
+        await self._client_store.put(key=client_id, value=migrated)
+        return migrated
+
+    @override
+    async def load_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: str,
+    ) -> RefreshToken | None:
+        """Reject legacy refresh tokens that predate required OIDC scopes."""
+        loaded = await super().load_refresh_token(client, refresh_token)
+        if loaded is None:
+            return None
+        missing_scopes = set(self.required_scopes) - set(loaded.scopes)
+        if missing_scopes:
+            logger.debug(
+                "Rejecting legacy refresh token for client_id=%s: "
+                "missing required scopes %s",
+                client.client_id,
+                sorted(missing_scopes),
+            )
+            return None
+        return loaded

{ha_mcp_dev-8.1.1.dev2296 → ha_mcp_dev-8.2.0.dev2307/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.1.1.dev2296
+Version: 8.2.0.dev2307
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastmcp==3.4.5
+Requires-Dist: fastmcp==3.4.6
 Requires-Dist: httpx[socks]==0.28.1
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: python-dotenv==1.2.2
@@ -117,7 +117,7 @@ These run the server outside Home Assistant — useful for **Container** / **Cor
 - **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config.
 - **PyPI / uvx (HTTP server):** run the published `ha-mcp` package with `uvx ha-mcp@latest` (or pip) as a streamable-HTTP server the same way. Details in the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/).
 - **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-command installers in the **Demo server** section below use this path; the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) covers connecting it to your own Home Assistant.
-- **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, Google, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).
+- **OIDC authentication:** gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See [OIDC Mode](docs/oidc.md).
 
   > ⚠️ **stdio has known transport issues.** The stdio transport has connection problems that streamable HTTP does not ([#1713](https://github.com/homeassistant-ai/ha-mcp/issues/1713)). It is recommended only for demo/testing tinkering — for a real setup, use the custom component or an HTTP method above.
 

{ha_mcp_dev-8.1.1.dev2296 → ha_mcp_dev-8.2.0.dev2307}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 src/ha_mcp/__init__.py
 src/ha_mcp/__main__.py
 src/ha_mcp/_pypi_marker
+src/ha_mcp/_rich_compat.py
 src/ha_mcp/_version.py
 src/ha_mcp/backup_manager.py
 src/ha_mcp/browser_landing.py
@@ -81,6 +82,7 @@ src/ha_mcp/_vendor/websockets/trio/server.py
 src/ha_mcp/_vendor/websockets/trio/utils.py
 src/ha_mcp/auth/__init__.py
 src/ha_mcp/auth/consent_form.py
+src/ha_mcp/auth/oidc_compat.py
 src/ha_mcp/auth/provider.py
 src/ha_mcp/client/__init__.py
 src/ha_mcp/client/rest_client.py

{ha_mcp_dev-8.1.1.dev2296 → ha_mcp_dev-8.2.0.dev2307}/src/ha_mcp_dev.egg-info/requires.txt

@@ -1,4 +1,4 @@
-fastmcp==3.4.5
+fastmcp==3.4.6
 httpx[socks]==0.28.1
 pydantic==2.13.4
 python-dotenv==1.2.2