ha-mcp-dev 9.1.0.dev3341__tar.gz → 9.1.0.dev3347__tar.gz

{ha_mcp_dev-9.1.0.dev3341 → ha_mcp_dev-9.1.0.dev3347}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3341
+Version: 9.1.0.dev3347
 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.1.0.dev3341 → ha_mcp_dev-9.1.0.dev3347}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3341"
+version = "9.1.0.dev3347"
 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.1.0.dev3341 → ha_mcp_dev-9.1.0.dev3347}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3341"
+version = "9.1.0.dev3347"
 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.1.0.dev3341 → ha_mcp_dev-9.1.0.dev3347}/src/ha_mcp/read_only.py

@@ -31,7 +31,6 @@ whether the call is a read (allowed) or a write (blocked).
 
 from __future__ import annotations
 
-import json
 import logging
 from collections.abc import Awaitable, Callable, Iterator, Sequence
 from contextlib import contextmanager
@@ -49,7 +48,7 @@ from ha_mcp._vendor.fastmcp.tools import Tool
 from .config import get_global_settings
 from .errors import ErrorCode, create_error_response
 from .renamed_tools import current_tool_name
-from .tool_dispatch import CALL_PROXY_META_TOOLS
+from .tool_dispatch import CALL_PROXY_META_TOOLS, coerce_proxy_arguments
 from .tools.helpers import raise_tool_error
 
 if TYPE_CHECKING:
@@ -477,32 +476,6 @@ class ReadOnlyMiddleware(Middleware):
             return "write"
         return "unknown"
 
-    @staticmethod
-    def _coerce_arguments(arguments: Any) -> dict[str, Any] | None:
-        """Normalise a proxy envelope's ``arguments`` to a dict or None.
-
-        The categorized proxies tolerate ``arguments`` arriving as a JSON
-        string (small models sometimes serialize it) and json.loads it
-        AFTER this middleware runs (categorized_search.py ~313-352). So:
-        a dict is used as-is; an absent value (``None``) becomes ``{}``
-        (a legitimate no-argument call, not malformed); a string is
-        parsed and only a JSON *object* yields a dict. Anything else — an
-        unparseable string, a non-dict JSON value (list/scalar/null), or
-        a non-str/non-dict type — returns None, meaning "malformed
-        envelope".
-        """
-        if isinstance(arguments, dict):
-            return arguments
-        if arguments is None:
-            return {}
-        if isinstance(arguments, str):
-            try:
-                parsed = json.loads(arguments)
-            except (json.JSONDecodeError, ValueError):
-                return None
-            return parsed if isinstance(parsed, dict) else None
-        return None
-
     @classmethod
     def _unwrap_proxy_call(
         cls,
@@ -518,7 +491,7 @@ class ReadOnlyMiddleware(Middleware):
         lets the middleware decide on the inner call first. Mirrors the
         proxy's own double-wrap unwrapping.
 
-        ``arguments`` is coerced at every level (see _coerce_arguments)
+        ``arguments`` is coerced at every level (see coerce_proxy_arguments)
         because the proxy accepts it as a JSON string. Returns None when
         there is no usable envelope — including when ``arguments`` is a
         MALFORMED string (json.loads fails, or the JSON is not an object).
@@ -528,7 +501,7 @@ class ReadOnlyMiddleware(Middleware):
         (categorized_search.py ~313-352), so no write can occur.
         """
         name = args.get("name")
-        arguments = cls._coerce_arguments(args.get("arguments"))
+        arguments = coerce_proxy_arguments(args.get("arguments"))
         while (
             isinstance(name, str)
             and name in CALL_PROXY_META_TOOLS
@@ -536,7 +509,7 @@ class ReadOnlyMiddleware(Middleware):
             and isinstance(arguments.get("name"), str)
         ):
             name = arguments.get("name")
-            arguments = cls._coerce_arguments(arguments.get("arguments"))
+            arguments = coerce_proxy_arguments(arguments.get("arguments"))
         if not isinstance(name, str):
             return None
         if arguments is None:

{ha_mcp_dev-9.1.0.dev3341 → ha_mcp_dev-9.1.0.dev3347}/src/ha_mcp/settings_ui/locales/en.json

@@ -519,7 +519,7 @@
     "advanced.sidecar_pin_port.label": "Settings UI sidecar port",
     "advanced.sidecar_pin_port.help": "0 picks a free port on first start and keeps it for later restarts; a port in the range pins a preferred port (falls back to a free one if taken).",
     "advanced.enable_dev_mode.label": "Developer mode",
-    "advanced.enable_dev_mode.help": "⚠ Registers hidden tools that can change settings and replace the running server. Development and testing only.",
+    "advanced.enable_dev_mode.help": "⚠ Registers hidden tools that can change settings and replace the running server. It also may bypass some entity visibility or other limitations. Development and testing only.",
     "advanced.dev_tools_security_policy_access.label": "Dev tools security policy access",
     "advanced.dev_tools_security_policy_access.help": "⚠ While developer mode is on, lets the developer tools rewrite tool security policies, add or remove per-tool approval gates, and approve or deny pending approvals on your behalf — an AI agent can accept its own gated calls. Policy testing only. Takes effect without a restart.",
     "addon.secret_path.name": "Secret path override",

{ha_mcp_dev-9.1.0.dev3341 → ha_mcp_dev-9.1.0.dev3347}/src/ha_mcp/tool_dispatch.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 from typing import Any
 
 # Call proxies dispatch the envelope's ``name`` back through middleware. Policy
@@ -37,3 +38,25 @@ def is_approval_management_call(name: str, args: dict[str, Any]) -> bool:
         name == _APPROVAL_MANAGEMENT_TOOL
         and args.get("action") in _APPROVAL_MANAGEMENT_ACTIONS
     )
+
+
+def coerce_proxy_arguments(arguments: Any) -> dict[str, Any] | None:
+    """Normalise a call-proxy envelope's ``arguments`` to a dict or None.
+
+    The categorized proxies tolerate ``arguments`` arriving as a JSON string
+    (small models sometimes serialize it) and json.loads it after middleware
+    runs. A dict is used as-is; an absent value (``None``) becomes ``{}`` (a
+    legitimate no-argument call); a string is parsed and only a JSON *object*
+    yields a dict. Anything else returns None, meaning "malformed envelope".
+    """
+    if isinstance(arguments, dict):
+        return arguments
+    if arguments is None:
+        return {}
+    if isinstance(arguments, str):
+        try:
+            parsed = json.loads(arguments)
+        except (json.JSONDecodeError, ValueError, RecursionError):
+            return None
+        return parsed if isinstance(parsed, dict) else None
+    return None

{ha_mcp_dev-9.1.0.dev3341 → ha_mcp_dev-9.1.0.dev3347}/src/ha_mcp/visibility/enforcement.py

@@ -5,7 +5,8 @@ The visibility filter (``visibility/``) normally only declutters ``ha_search`` /
 ``"enforce": true`` in ``entity_visibility.json``), the
 :class:`VisibilityInboundEnforcement` / :class:`VisibilityOutboundEnforcement`
 middleware pair makes the hidden set unreadable across tool reads, except for
-the deliberately unrestricted-by-default ``ha_report_issue`` diagnostic
+the never-gated server tools (``ha_get_skill_guide``, ``ha_search_tools``,
+``ha_dev_*``) and the unrestricted-by-default ``ha_report_issue`` diagnostic
 escape hatch — "refuse on contact":
 
 - **Direct reads are concealed.** A call whose arguments name a hidden entity_id
@@ -67,7 +68,7 @@ from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
 
 from ..errors import ErrorCode, create_entity_not_found_error, create_error_response
 from ..renamed_tools import current_tool_name
-from ..tool_dispatch import CALL_PROXY_META_TOOLS
+from ..tool_dispatch import CALL_PROXY_META_TOOLS, coerce_proxy_arguments
 from ..tools.helpers import raise_tool_error
 from . import resolver
 from .identifier_aliases import (
@@ -107,6 +108,10 @@ _CUSTOM_TOOL = "ha_manage_custom_tool"
 
 # Diagnostic tool deliberately outside the visibility barrier unless opted in.
 _REPORT_ISSUE_TOOL = "ha_report_issue"
+# Always outside the barrier: bundled docs and tool schemas whose examples can
+# name a hidden id (#2949), and the ha_dev_* developer override by design.
+_UNGATED_TOOLS = frozenset({"ha_get_skill_guide", "ha_search_tools"})
+_UNGATED_PREFIX = "ha_dev_"
 # State reads have a shape-bounded scrub exception before the outbound scan.
 _STATE_TOOL = "ha_get_state"
 
@@ -511,21 +516,6 @@ def _unscannable_reason(name: str, args: dict[str, Any]) -> str | None:
     return None
 
 
-def _coerce_arguments(arguments: Any) -> dict[str, Any] | None:
-    """Normalise a proxy envelope's ``arguments`` to a dict or None (mirrors read_only)."""
-    if isinstance(arguments, dict):
-        return arguments
-    if arguments is None:
-        return {}
-    if isinstance(arguments, str):
-        try:
-            parsed = json.loads(arguments)
-        except (json.JSONDecodeError, ValueError):
-            return None
-        return parsed if isinstance(parsed, dict) else None
-    return None
-
-
 def _unwrap_proxy_call(args: dict[str, Any]) -> tuple[str, dict[str, Any]] | None:
     """Extract the innermost proxy target and arguments, or None if unusable.
 
@@ -540,7 +530,7 @@ def _unwrap_proxy_call(args: dict[str, Any]) -> tuple[str, dict[str, Any]] | Non
     if not isinstance(raw_name, str):
         return None
     name = current_tool_name(raw_name)
-    arguments = _coerce_arguments(args.get("arguments"))
+    arguments = coerce_proxy_arguments(args.get("arguments"))
     while (
         name in CALL_PROXY_META_TOOLS
         and isinstance(arguments, dict)
@@ -548,7 +538,7 @@ def _unwrap_proxy_call(args: dict[str, Any]) -> tuple[str, dict[str, Any]] | Non
     ):
         raw_name = arguments["name"]
         name = current_tool_name(raw_name)
-        arguments = _coerce_arguments(arguments.get("arguments"))
+        arguments = coerce_proxy_arguments(arguments.get("arguments"))
     if arguments is None:
         return None
     return name, arguments
@@ -599,13 +589,10 @@ class _VisibilityEnforcementBase(Middleware):
             resolver.load_visibility_config, resolver.get_data_dir()
         )
 
-    async def _active_config(
-        self,
-        tool_name: str,
-        *,
-        emit_report_issue_diagnostic: bool = False,
+    async def _load_config_or_last_good(
+        self, tool_name: str
     ) -> VisibilityConfig | None:
-        """Return the config when enforce is active, ``None`` when passthrough.
+        """Load the config, falling back to the last good load (``None`` if none).
 
         The active-mode gate must not crash the call with an opaque trace on an
         unloadable config (a hand-edit typo would break EVERY tool call), nor
@@ -613,7 +600,7 @@ class _VisibilityEnforcementBase(Middleware):
         enforce was on). Policy: fall back to the last config this process
         loaded successfully — for the common non-enforce install that preserves
         availability, and for an enforce install it preserves the boundary.
-        With no good load ever, fail CLOSED like PolicyMiddleware does.
+        With no good load ever, the caller fails CLOSED like PolicyMiddleware.
 
         Each half diagnoses a distinct config-load failure. A context-local
         marker suppresses only the second traceback when both halves fail during
@@ -643,6 +630,18 @@ class _VisibilityEnforcementBase(Middleware):
                 )
                 if warning_emitted is not None:
                     _config_load_warning_emitted.set(True)
+        return config
+
+    async def _active_config(
+        self,
+        tool_name: str,
+        *,
+        emit_report_issue_diagnostic: bool = False,
+    ) -> VisibilityConfig | None:
+        """Return the config when enforce is active, ``None`` when passthrough."""
+        if tool_name in _UNGATED_TOOLS or tool_name.startswith(_UNGATED_PREFIX):
+            return None
+        config = await self._load_config_or_last_good(tool_name)
         # ``ha_report_issue`` is an unconditional diagnostic escape hatch while
         # the toggle is off, not only a registry-failure fallback. A missing or
         # corrupt first config load follows that safe default; a last-known-good