ha-mcp-dev 9.0.0.dev3224__tar.gz → 9.0.1.dev3235__tar.gz

{ha_mcp_dev-9.0.0.dev3224 → ha_mcp_dev-9.0.1.dev3235}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.0.0.dev3224
+Version: 9.0.1.dev3235
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.0.0.dev3224 → ha_mcp_dev-9.0.1.dev3235}/pyproject.toml

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

{ha_mcp_dev-9.0.0.dev3224 → ha_mcp_dev-9.0.1.dev3235}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.0.dev3224"
+version = "9.0.1.dev3235"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-9.0.0.dev3224 → ha_mcp_dev-9.0.1.dev3235}/src/ha_mcp/backup_dashboards.py

@@ -70,6 +70,7 @@ async def fetch_dashboard(client: Any, entity_id: str) -> Any:
     """
     from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
+    from .tools.dashboard_read_errors import UNKNOWN_CONFIG_PREFIX
     from .tools.tools_config_dashboards import (
         _component_dashboard_config,
         _get_dashboard_config_internal,
@@ -108,7 +109,7 @@ async def fetch_dashboard(client: Any, entity_id: str) -> Any:
             # url_path ("Unknown config specified", also the create path), or
             # a dashboard whose config was never saved, which keeps its row.
             msg = str(err).lower()
-            if "not_found" not in msg and "unknown config" not in msg:
+            if "not_found" not in msg and UNKNOWN_CONFIG_PREFIX.lower() not in msg:
                 raise
             config = None
             if row is None:
@@ -134,10 +135,12 @@ async def _save(client: Any, url_path: str, config: Any) -> Any:
 
 async def _saved(client: Any, url_path: str, config: Any) -> bool:
     """Write; ``False`` when Core has no dashboard at ``url_path``."""
+    from .tools.dashboard_read_errors import CONFIG_NOT_FOUND_CODE
+
     try:
         await _save(client, url_path, config)
     except HomeAssistantCommandError as err:
-        if err.code != "config_not_found":
+        if err.code != CONFIG_NOT_FOUND_CODE:
             raise
         return False
     return True

{ha_mcp_dev-9.0.0.dev3224 → ha_mcp_dev-9.0.1.dev3235}/src/ha_mcp/backup_manager.py

@@ -109,6 +109,7 @@ from .client.rest_client import (
     HomeAssistantConnectionError,
     HomeAssistantError,
 )
+from .storage_helper_types import SIMPLE_HELPER_TYPES
 from .utils.data_paths import get_data_dir
 from .utils.registry_update_lock import registry_update_lock
 
@@ -2730,20 +2731,7 @@ async def _restore_device(client: Any, entity_id: str, config: Any) -> Any:
 # endpoints (fetch: backup_helper_target.py). The decorator
 # constructs the domain key as ``helper_<type>`` so files group naturally.
 
-_HELPER_LIST_TYPES = {
-    "input_boolean",
-    "input_text",
-    "input_number",
-    "input_select",
-    "input_datetime",
-    "input_button",
-    "counter",
-    "timer",
-    "schedule",
-    "zone",
-    "person",
-    "tag",
-}
+_HELPER_LIST_TYPES = SIMPLE_HELPER_TYPES
 
 
 async def _restore_helper(

{ha_mcp_dev-9.0.0.dev3224 → ha_mcp_dev-9.0.1.dev3235}/src/ha_mcp/dashboard_screenshot/paths.py

@@ -12,13 +12,15 @@ from typing import Any, cast
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
 from ..errors import ErrorCode, create_error_response
+from ..tools.dashboard_read_errors import (
+    CONFIG_NOT_FOUND_CODE,
+    NO_STORED_CONFIG_MESSAGES,
+    NO_STORED_CONFIG_NOTE,
+    UNKNOWN_CONFIG_PREFIX,
+)
 from ..tools.helpers import raise_tool_error
 from .capture import _normalize_dashboard_path
 
-_UNKNOWN_CONFIG_PREFIX = "Unknown config specified:"
-_NO_CONFIG_MESSAGES = frozenset(
-    {"No config found.", "Command failed: No config found."}
-)
 _JS_DECIMAL_NUMBER = re.compile(
     r"[+-]?(?:(?:\d+(?:\.\d*)?)|(?:\.\d+))(?:[eE][+-]?\d+)?\Z"
 )
@@ -264,8 +266,14 @@ def _fallback_view_target(
     )
 
 
-async def fetch_dashboard_render_config(client: Any, url_path: str) -> dict[str, Any]:
-    """Fetch a Lovelace dashboard config for stable view-path resolution."""
+async def fetch_dashboard_render_config(
+    client: Any, url_path: str
+) -> dict[str, Any] | None:
+    """Fetch a Lovelace dashboard config for stable view-path resolution.
+
+    ``None`` when Home Assistant holds no config for the dashboard, which the
+    frontend renders as its generated default view.
+    """
     base_path = dashboard_frontend_path(url_path)
     request: dict[str, Any] = {"type": "lovelace/config", "force": True}
     if base_path != "lovelace":
@@ -296,12 +304,13 @@ async def fetch_dashboard_render_config(client: Any, url_path: str) -> dict[str,
         else:
             error_code = ""
             message = str(error)
-        missing_dashboard = (
-            error_code == "config_not_found"
-            or message.startswith(
-                (_UNKNOWN_CONFIG_PREFIX, f"Command failed: {_UNKNOWN_CONFIG_PREFIX}")
+        if message in NO_STORED_CONFIG_MESSAGES:
+            return None
+        missing_dashboard = error_code == CONFIG_NOT_FOUND_CODE or message.startswith(
+            (
+                f"{UNKNOWN_CONFIG_PREFIX}:",
+                f"Command failed: {UNKNOWN_CONFIG_PREFIX}:",
             )
-            or message in _NO_CONFIG_MESSAGES
         )
         if missing_dashboard:
             raise_tool_error(
@@ -502,14 +511,14 @@ async def _resolve_legacy_dashboard_target(
         raw_view = parts[1] if len(parts) > 1 else None
         numeric_index = _numeric_view_index(raw_view) if raw_view is not None else None
         return DashboardRenderTarget(
-            url_path="lovelace",
+            url_path=dashboard_root,
             view_path=None,
             render_path=render_path,
             view_index=numeric_index,
             stable=False,
             warnings=(
-                "Legacy built-in Lovelace routes are accepted without a stored "
-                "dashboard config; the selected view cannot be verified.",
+                "Routes of a dashboard without a stored config are accepted; "
+                "the selected view cannot be verified.",
             ),
         )
     if len(parts) == 1:
@@ -667,6 +676,25 @@ async def resolve_dashboard_render_target(
             ),
         )
     config = await fetch_dashboard_render_config(client, url_path)
+    if config is None:
+        if view_path is not None:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    NO_STORED_CONFIG_NOTE,
+                    context={"url_path": url_path, "view_path": view_path},
+                    suggestions=["Omit view_path: there are no static views"],
+                )
+            )
+        base_path = dashboard_frontend_path(url_path)
+        return DashboardRenderTarget(
+            url_path=base_path,
+            view_path=None,
+            render_path=base_path,
+            view_index=None,
+            stable=False,
+            warnings=(NO_STORED_CONFIG_NOTE,),
+        )
     return resolve_dashboard_view(url_path, config, view_path)
 
 
@@ -718,7 +746,7 @@ async def _numeric_view_warning(
         return []
     if config is None:
         config = await fetch_dashboard_render_config(client, url_path)
-    views = config.get("views")
+    views = (config or {}).get("views")
     if not isinstance(views, list):
         return []
     view_index = index if matched_view_index is None else matched_view_index

ha_mcp_dev-9.0.1.dev3235/src/ha_mcp/mcp_client_context.py

@@ -0,0 +1,164 @@
+"""What the connected MCP client said about itself on the current request.
+
+Handshake-era clients (through 2025-11-25) send their client info and
+capabilities once, in ``initialize``. On 2026-07-28 there is no handshake:
+every request carries its protocol version, client info and capabilities in
+``_meta``, and the SDK exposes them on that request's session. Either way the
+values are read per request, so they describe the request being served.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ha_mcp._vendor.fastmcp.server.dependencies import get_http_headers
+from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
+    CallNext,
+    Middleware,
+    MiddlewareContext,
+)
+from ha_mcp._vendor.mcp_types import ClientCapabilities
+
+logger = logging.getLogger(__name__)
+
+
+def protocol_version(ctx: Any) -> str | None:
+    """The MCP protocol version this request was served on."""
+    version = getattr(getattr(ctx, "request_context", None), "protocol_version", None)
+    return version if isinstance(version, str) else None
+
+
+def client_capabilities(ctx: Any) -> ClientCapabilities | None:
+    """The capabilities the client declared for this request, if any."""
+    session = getattr(getattr(ctx, "request_context", None), "session", None)
+    caps = getattr(session, "client_capabilities", None)
+    return caps if isinstance(caps, ClientCapabilities) else None
+
+
+def declares_form_elicitation(caps: ClientCapabilities | None) -> bool:
+    """True when the client can show a form-mode elicitation to its user.
+
+    An empty ``elicitation`` object predates the form/url split and means
+    form mode only.
+    """
+    elicitation = caps.elicitation if caps is not None else None
+    if elicitation is None:
+        return False
+    return elicitation.form is not None or elicitation.url is None
+
+
+def capability_names(caps: ClientCapabilities | None) -> list[str] | None:
+    """Flatten declared capabilities into stable, readable names.
+
+    ``None`` means the request carried none to read, which is not the same as
+    declaring none: a handshake-era client over stateless HTTP sends them only
+    in ``initialize``, never on a later call.
+    """
+    if caps is None:
+        return None
+    names: list[str] = []
+    if caps.elicitation is not None:
+        if declares_form_elicitation(caps):
+            names.append("elicitation.form")
+        if caps.elicitation.url is not None:
+            names.append("elicitation.url")
+    names.extend(
+        field
+        for field in ("sampling", "roots", "tasks")
+        if getattr(caps, field) is not None
+    )
+    names.extend(f"extension:{key}" for key in sorted(caps.extensions or {}))
+    names.extend(f"experimental:{key}" for key in sorted(caps.experimental or {}))
+    return names
+
+
+def extract_client_info(ctx: Any) -> dict[str, str]:
+    """Pull the connecting MCP client's self-identification off the request context.
+
+    The MCP ``initialize`` handshake carries a ``clientInfo`` Implementation
+    object (``name``/``version``/optional ``title``). FastMCP exposes the
+    underlying server session as ``ctx.session``; the MCP SDK's
+    ``ServerSession`` keeps the parsed initialize params on ``client_params``;
+    on the 2026-07-28 protocol the SDK synthesizes them from the request's
+    ``_meta`` when it carries both client info and capabilities. An
+    older-protocol client over stateless HTTP sends client info only in
+    ``initialize``, so the request's ``User-Agent`` is the fallback there,
+    marked as such in ``title``.
+
+    Returns ``{"name": ..., "version": ..., "title": ...}``. ``name`` and
+    ``version`` fall back to ``"unknown"`` when the client didn't send them;
+    ``title`` falls back to the empty string so callers can distinguish "not
+    sent" from a real title without false-positive aside rendering.
+
+    Returns an empty dict when there is no context, or no client info and no
+    ``User-Agent`` (e.g. stdio), so its callers (bug report, overview, debug
+    log) never fail on it. The log level is intentionally INFO, not DEBUG:
+    this catch is the only signal we'd get if FastMCP/MCP SDK shape drifts in
+    a future release, and silent drift would hide a regression for months.
+    """
+    if ctx is None:
+        return {}
+    try:
+        params = getattr(getattr(ctx, "session", None), "client_params", None)
+        client = getattr(params, "client_info", None) or getattr(
+            params, "clientInfo", None
+        )
+        if client is None:
+            return _client_info_from_user_agent()
+        return {
+            "name": getattr(client, "name", None) or "unknown",
+            "version": getattr(client, "version", None) or "unknown",
+            "title": getattr(client, "title", None) or "",
+        }
+    except Exception as e:  # noqa: BLE001
+        logger.info(
+            "Failed to read MCP client info from context: %s (%s)",
+            e,
+            type(e).__name__,
+        )
+        return {}
+
+
+def _client_info_from_user_agent() -> dict[str, str]:
+    """``{"name", "version", "title"}`` from the HTTP ``User-Agent``, or ``{}``."""
+    user_agent = get_http_headers(include={"user-agent"}).get("user-agent", "").strip()
+    if not user_agent:
+        return {}
+    product = user_agent.split()[0]
+    name, _, version = product.partition("/")
+    logger.debug("No MCP client info on the request; using User-Agent %r", product)
+    return {
+        "name": name or "unknown",
+        "version": version or "unknown",
+        "title": "from HTTP User-Agent",
+    }
+
+
+def describe_mcp_client(ctx: Any) -> dict[str, Any]:
+    """Protocol version, client info and declared capabilities of this request."""
+    return {
+        "protocol_version": protocol_version(ctx) or "unknown",
+        "client_info": extract_client_info(ctx),
+        "capabilities": capability_names(client_capabilities(ctx)),
+    }
+
+
+class McpClientDebugLogMiddleware(Middleware):
+    """Log, at DEBUG, which protocol and capabilities each tool call arrived with.
+
+    The modern protocol is stateless, so there is no connection to log once
+    per client; the line is per call and costs one level check when DEBUG is
+    off.
+    """
+
+    async def on_call_tool(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "tools/call %s: %s",
+                context.message.name,
+                describe_mcp_client(context.fastmcp_context),
+            )
+        return await call_next(context)

{ha_mcp_dev-9.0.0.dev3224 → ha_mcp_dev-9.0.1.dev3235}/src/ha_mcp/policy/middleware.py

@@ -15,6 +15,7 @@ from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
     Middleware,
     MiddlewareContext,
 )
+from ha_mcp._vendor.fastmcp.tools.base import InputRequiredToolResult
 
 from ..errors import ErrorCode, create_error_response
 from ..renamed_tools import current_tool_name
@@ -30,7 +31,12 @@ from .evaluator import (
 )
 from .events import emit_approval_requested
 from .model import Policy, Rule
-from .mrtr import ApprovalContinuation, supports_mrtr
+from .mrtr import (
+    ApprovalAnswer,
+    ApprovalContinuation,
+    approval_answer,
+    supports_mrtr,
+)
 
 if TYPE_CHECKING:
     from ..client.rest_client import HomeAssistantClient
@@ -264,8 +270,22 @@ class PolicyMiddleware(Middleware):
             continuation = ApprovalContinuation.start(
                 pending, policy, wait, dynamic_targets=dynamic_targets
             )
+        if resumed is not None and (answer := approval_answer(context)) != "accept":
+            return await self._end_unconfirmed_resume(
+                pending,
+                rule,
+                resumed[0],
+                answer,
+                dynamic_targets=dynamic_targets,
+                policy=policy,
+                name=name,
+            )
         await self._wait_for_decision(
-            context, pending, continuation.wait_seconds() if continuation else wait
+            context,
+            pending,
+            continuation.wait_seconds(confirmed=resumed is not None)
+            if continuation
+            else wait,
         )
 
         if pending.decision == "approved":
@@ -292,17 +312,87 @@ class PolicyMiddleware(Middleware):
             self._queue.remove(pending.token)
             self._raise_denied_error()
 
-        if continuation is not None:
+        # Only the first leg asks; an accepted form already waited out the window.
+        if continuation is not None and resumed is None:
             result = continuation.next_result(self._queue)
             if result is not None:
                 return result
 
+        await self._raise_unresolved(
+            pending, rule, dynamic_targets=dynamic_targets, policy=policy, name=name
+        )
+        return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
+
+    async def _end_unconfirmed_resume(
+        self,
+        pending: PendingApproval,
+        rule: Rule | None,
+        continuation: ApprovalContinuation,
+        answer: ApprovalAnswer | None,
+        *,
+        dynamic_targets: bool,
+        policy: Policy,
+        name: str,
+    ) -> InputRequiredToolResult | None:
+        """Handle a resumed call whose form was not accepted. Never dispatches.
+
+        Only an accepted form continues a resumed call, even once the row is
+        approved. The answer is client-supplied, so it may stop or deny the
+        call but never approve it: decline denies or removes the row (for
+        every call waiting on a shared static row, as a Deny click would),
+        cancel ends with the approval error, and a retry with no answer is
+        asked again.
+        """
+        if answer is not None:
+            # Logged because a client answer can end a row a human approved.
+            logger.info(
+                "policy middleware: token %s for tool=%s ended by the client's "
+                "form answer=%s (decision was %s)",
+                pending.token,
+                name,
+                answer,
+                pending.decision,
+            )
+        if answer == "decline" or pending.decision == "denied":
+            self._queue.deny(pending.token)
+            self._queue.remove(pending.token)
+            self._raise_denied_error()
+        if answer is None:
+            ask = continuation.next_result(self._queue)
+            if ask is not None:
+                return ask
+        await self._raise_unresolved(
+            pending,
+            rule,
+            dynamic_targets=dynamic_targets,
+            policy=policy,
+            name=name,
+            dismissed=answer == "cancel",
+        )
+        return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
+
+    async def _raise_unresolved(
+        self,
+        pending: PendingApproval,
+        rule: Rule | None,
+        *,
+        dynamic_targets: bool,
+        policy: Policy,
+        name: str,
+        dismissed: bool = False,
+    ) -> NoReturn:
+        """End a call that has no decision: finalize the row, re-announce, raise."""
         pending = self._finalize_timed_out_pending(
-            pending, dynamic_targets=dynamic_targets, policy=policy, name=name
+            pending,
+            dynamic_targets=dynamic_targets,
+            policy=policy,
+            name=name,
+            dismissed=dismissed,
         )
         await self._announce_reissued(pending, rule, dynamic_targets=dynamic_targets)
-        self._raise_pending_error(pending, rule, dynamic_targets=dynamic_targets)
-        return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
+        self._raise_pending_error(
+            pending, rule, dynamic_targets=dynamic_targets, dismissed=dismissed
+        )
 
     async def _announce_reissued(
         self,
@@ -526,8 +616,12 @@ class PolicyMiddleware(Middleware):
         dynamic_targets: bool,
         policy: Policy,
         name: str,
+        dismissed: bool = False,
     ) -> PendingApproval:
-        """Resolve a pending entry that timed out without a decision.
+        """Resolve a pending entry that ended without a decision.
+
+        ``dismissed`` means the user dismissed the approval form rather than
+        the wait running out; it only changes what is logged.
 
         Two mutually exclusive outcomes, split by ``dynamic_targets`` for
         the same reason the entry was never shared or looked up in the
@@ -561,9 +655,12 @@ class PolicyMiddleware(Middleware):
             # an operator tell those apart.
             logger.info(
                 "policy middleware: dynamic pending token %s removed after "
-                "its single-use wait window closed for tool=%s; a late "
-                "Approve click on it will log as an unknown token",
+                "%s for tool=%s; a late Approve click on it will log as an "
+                "unknown token",
                 pending.token,
+                "the approval form was dismissed"
+                if dismissed
+                else "its single-use wait window closed",
                 name,
             )
             return pending
@@ -627,6 +724,7 @@ class PolicyMiddleware(Middleware):
         rule: Rule | None = None,
         *,
         dynamic_targets: bool = False,
+        dismissed: bool = False,
     ) -> NoReturn:
         """Raise the structured USER_APPROVAL_REQUIRED error for one pending entry.
 
@@ -638,9 +736,9 @@ class PolicyMiddleware(Middleware):
         picked up by a later re-call -- so its wording must not promise the
         normal "re-call after the user approves" recovery path the
         non-dynamic case uses, and must not describe a still-open approval
-        window: this is the ONLY call site, reached after
-        ``_wait_for_decision`` returns with no decision, so the wait window
-        has already closed by the time this message is built.
+        window. It ends either after ``_wait_for_decision`` returned with no
+        decision (the window closed) or, with ``dismissed``, when the user
+        dismissed the approval form, and the message says which.
         """
         context: dict[str, Any] = {"token": pending.token}
         # Surface the matched rule so users (and the LLM) can tell at a
@@ -657,10 +755,15 @@ class PolicyMiddleware(Middleware):
             # countdown left to report -- a number here would read as
             # "there's still time", exactly the false impression this
             # message must not give.
+            ended = (
+                "the approval form for this call was dismissed"
+                if dismissed
+                else "this call's wait window has now closed"
+            )
             message = (
                 "User approval required, and this specific request has "
-                "already expired: it was single-use, bound to this one "
-                "call only, and this call's wait window has now closed. "
+                "already ended: it was single-use, bound to this one "
+                f"call only, and {ended}. "
                 "The token above has already been removed and no longer "
                 "exists -- there is nothing left to approve for this call. "
                 "Re-call this tool to create a brand-new, independent "