ha-mcp-dev 8.3.0.dev2395__tar.gz → 8.3.0.dev2397__tar.gz

{ha_mcp_dev-8.3.0.dev2395/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2397}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2395"
+version = "8.3.0.dev2397"
 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-8.3.0.dev2395 → ha_mcp_dev-8.3.0.dev2397}/src/ha_mcp/client/rest_client.py

@@ -409,13 +409,26 @@ class HomeAssistantClient:
         return await self._request("GET", "/config")
 
     async def get_states(self) -> list[dict[str, Any]]:
-        """Get all entity states."""
+        """Get all entity states.
+
+        Raises ``HomeAssistantConnectionError`` when the response isn't the
+        JSON array ``/states`` always returns on success -- including
+        ``_request``'s own empty-dict fallback for an unparseable body.
+        Silently returning ``[]`` here would let a genuine fetch failure
+        masquerade as "this instance has zero entities", which no real,
+        running Home Assistant instance produces; callers that need to
+        verify something against the live entity set (e.g. a bulk-control
+        safety check) would otherwise treat that failure as "verified,
+        nothing to worry about" instead of "could not verify".
+        """
         logger.debug("Fetching all entity states")
         result = await self._request("GET", "/states")
         if isinstance(result, list):
             return result
-        else:
-            return []
+        raise HomeAssistantConnectionError(
+            f"Home Assistant /states returned an unexpected response shape: "
+            f"{type(result).__name__}"
+        )
 
     async def get_entity_state(self, entity_id: str) -> dict[str, Any]:
         """

{ha_mcp_dev-8.3.0.dev2395 → ha_mcp_dev-8.3.0.dev2397}/src/ha_mcp/errors.py

@@ -100,6 +100,16 @@ class ErrorCode(StrEnum):
     USER_DENIED = "USER_DENIED"
     POLICY_LOAD_FAILED = "POLICY_LOAD_FAILED"
 
+    # Distinct from POLICY_LOAD_FAILED above: the policy file itself loaded
+    # fine, but this call's own arguments were too deeply nested to
+    # evaluate against it safely (see normalize_stringified_containers'
+    # RecursionError handling in middleware.py). A different failure with a
+    # different, caller-shaped remedy ("reduce the nesting depth and
+    # retry") -- sharing POLICY_LOAD_FAILED would make the two
+    # indistinguishable to anything grouping on the code (a dashboard, an
+    # operator grepping logs after "my policy broke").
+    POLICY_ARGS_TOO_DEEPLY_NESTED = "POLICY_ARGS_TOO_DEEPLY_NESTED"
+
     # Read Only Mode (discussion #1569). A write operation was blocked
     # because the server-wide Read Only Mode toggle is on.
     READ_ONLY_MODE = "READ_ONLY_MODE"
@@ -210,6 +220,10 @@ DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
         "Check documentation for required fields",
         "Ensure all required parameters are provided",
     ],
+    ErrorCode.VALIDATION_FAILED: [
+        "Check the parameter values and format against the tool documentation",
+        "Review the message and details fields for the specific constraint that failed",
+    ],
     ErrorCode.VALIDATION_INVALID_JSON: [
         "Ensure the parameter is valid JSON",
         "Check for syntax errors in JSON",
@@ -310,10 +324,21 @@ def create_connection_error(
     details: str | None = None,
     timeout: bool = False,
     context: dict[str, Any] | None = None,
+    suggestions: list[str] | None = None,
 ) -> dict[str, Any]:
-    """Create a connection error response."""
+    """Create a connection error response.
+
+    ``suggestions`` overrides ``DEFAULT_SUGGESTIONS[CONNECTION_FAILED/TIMEOUT]``
+    (network/URL/connectivity checks) for a caller whose failure is
+    CONNECTION_FAILED-shaped (unavailable, not the caller's fault to fix by
+    editing input) but not actually a network problem — e.g. malformed local
+    registry data or an unloadable local config file, where "check your
+    HOMEASSISTANT_URL" is not an actionable next step.
+    """
     code = ErrorCode.CONNECTION_TIMEOUT if timeout else ErrorCode.CONNECTION_FAILED
-    return create_error_response(code, message, details, context=context)
+    return create_error_response(
+        code, message, details, suggestions=suggestions, context=context
+    )
 
 
 # Authentication-error suggestions for Home Assistant add-on installs. On the

ha_mcp_dev-8.3.0.dev2397/src/ha_mcp/policy/evaluator.py

@@ -0,0 +1,314 @@
+"""Evaluate a tool call against a Policy. Pure functions — no I/O, no state."""
+
+import logging
+import re
+from collections.abc import Iterator
+from enum import StrEnum
+from typing import Any
+
+from ..tools.util_helpers import loads_if_json_container_str
+from .model import Policy, Predicate, Rule
+
+logger = logging.getLogger(__name__)
+
+
+class Verdict(StrEnum):
+    ALLOW = "allow"
+    REQUIRE_APPROVAL = "require_approval"
+
+
+def normalize_stringified_containers(value: Any) -> Any:
+    """Recursively parse JSON-encoded object/array strings into real containers.
+
+    Some MCP client stacks (Claude Desktop stdio among them — see
+    ``tools/util_helpers.py``'s ``JSON_STRING_COERCION``) pass model-emitted
+    stringified objects through unrepaired, e.g. sending
+    ``{"selector": "{\\"domain\\": \\"light\\"}"}`` instead of a nested
+    object. Pydantic's ``JSON_STRING_COERCION`` ``BeforeValidator`` repairs
+    this, but only when the tool's own parameter validation runs — INSIDE
+    ``call_next``, after policy evaluation. ``iter_path_values`` only
+    descends into ``dict``/``list``, so a still-stringified value makes a
+    predicate targeting a nested field (``args.selector.domain``,
+    ``args.operations.*.entity_id``) silently yield nothing: no rule
+    matches, and — for ``ha_bulk_control`` — ``args.get("selector")`` still
+    sees a truthy string, so the selector fail-safe's own dynamic-call
+    detection still fires, but nothing inside it can be inspected either.
+    Applying the same repair here, once, before evaluation and hashing,
+    closes that gap for both plain predicate rules and the fail-safe, and
+    makes ``compute_args_hash`` key on the same logical value regardless of
+    which wire shape the client sent.
+
+    Malformed JSON that merely looks like a container is left as the raw
+    string (not raised): policy evaluation is not the place to surface a
+    JSON syntax error — the tool's own validation does that, with a
+    properly attributed parameter name.
+
+    Deeply-nested INPUT (real nested dicts/lists in the caller's own
+    ``args`` -- NOT a stringified container decoding into deep nesting;
+    ``loads_if_json_container_str`` already absorbs ``json.loads``'s own
+    ``RecursionError``, so a still-stringified value can never reach this
+    function's own recursion at all) can exceed the interpreter's
+    recursion limit and raise ``RecursionError`` here. Unlike the
+    malformed-JSON case, this is deliberately NOT swallowed: silently
+    returning the unrepaired value would let this security gate evaluate
+    (and hash) unnormalized args and, for a rule scoped to a nested
+    selector-inspectable field, silently ALLOW a call that should have
+    required approval -- the identical "fail open on a degraded gate"
+    mistake ``PolicyMiddleware.on_call_tool`` already refuses to make for
+    a corrupt policy file. The caller (``on_call_tool``) is responsible
+    for catching this and failing the call closed with a structured,
+    logged error, matching that same precedent.
+    """
+    return _normalize_stringified_containers(value)
+
+
+def _normalize_stringified_containers(value: Any) -> Any:
+    """Unbounded recursive worker for ``normalize_stringified_containers``.
+
+    Split out so the public function's ``RecursionError`` guard wraps a
+    single top-level call instead of needing a try/except at every
+    recursive frame.
+    """
+    if isinstance(value, str):
+        try:
+            return loads_if_json_container_str(value)
+        except ValueError:
+            return value
+    if isinstance(value, dict):
+        return {key: _normalize_stringified_containers(v) for key, v in value.items()}
+    if isinstance(value, list):
+        return [_normalize_stringified_containers(v) for v in value]
+    return value
+
+
+def has_dynamic_selector_targets(name: str, args: dict[str, Any]) -> bool:
+    """Return whether identical arguments can resolve to different targets later.
+
+    Single source of truth for the ``ha_bulk_control`` selector-mode predicate:
+    both ``PolicyMiddleware`` (approval-sharing/remembering gates) and
+    ``evaluate()`` below (the operations fail-safe) must agree on exactly
+    which calls are "dynamic", or a future rename/extension of this check in
+    one place silently stops applying to the other.
+    """
+    return name == "ha_bulk_control" and args.get("selector") is not None
+
+
+def iter_path_values(args: dict[str, Any], path: str) -> Iterator[Any]:
+    """Yield every value the dotted path resolves to.
+
+    The leading ``args`` segment is implicit and stripped. A ``*`` segment
+    fans out across the current node — across dict values for dicts,
+    across items for lists — so ``args.*`` yields every top-level
+    argument, ``args.config.*`` yields every leaf of the ``config``
+    sub-dict, and so on. Empty iterator = no match.
+    """
+    parts = path.split(".")
+    if parts[0] == "args":
+        parts = parts[1:]
+
+    def walk(cur: Any, rest: list[str]) -> Iterator[Any]:
+        if not rest:
+            yield cur
+            return
+        head, tail = rest[0], rest[1:]
+        if head == "*":
+            if isinstance(cur, dict):
+                for v in cur.values():
+                    yield from walk(v, tail)
+            elif isinstance(cur, (list, tuple)):
+                for v in cur:
+                    yield from walk(v, tail)
+            return
+        if isinstance(cur, dict) and head in cur:
+            yield from walk(cur[head], tail)
+
+    yield from walk(args, parts)
+
+
+def _ci(x: Any) -> Any:
+    """Lower-case strings for case-insensitive comparison; pass other
+    types through unchanged so type semantics (int != "1") survive.
+    Used on both sides of every string op — security gates should fire
+    whether the caller wrote 'Lock' or 'LOCK' or 'lock'."""
+    return x.lower() if isinstance(x, str) else x
+
+
+def _contains_matches(val: Any, pv: Any) -> bool:
+    if isinstance(val, str) and isinstance(pv, str):
+        return pv.lower() in val.lower()
+    # Mirror the case-insensitive treatment that ``eq`` / ``in`` /
+    # ``not_in`` already apply: a rule listing ``["light.kitchen"]``
+    # must match an LLM passing ``"Light.Kitchen"``. Per-element
+    # ``_ci`` guards non-string entries so mixed-type collections
+    # (e.g. ``[1, "two"]``) keep their natural equality semantics.
+    return isinstance(val, (list, tuple, set)) and any(_ci(pv) == _ci(x) for x in val)
+
+
+def _numeric_matches(val: Any, op: str, pv: Any) -> bool:
+    try:
+        return bool(val > pv) if op == "gt" else bool(val < pv)
+    except TypeError:
+        # Numeric rule against a non-numeric arg value — log so
+        # users can tell their "temperature > 30" rule isn't
+        # silently never firing because the arg is a string.
+        logger.debug(
+            "policy: %s type-mismatch (val=%r pv=%r) — predicate skipped",
+            op,
+            val,
+            pv,
+        )
+        return False
+
+
+def _op_matches(val: Any, op: str, pv: Any) -> bool:
+    """Apply one op to one concrete value. Predicate dispatches over
+    the candidate values (which may be many for wildcard paths).
+
+    String comparisons are case-insensitive (security gates shouldn't
+    care whether the LLM lowercased its args). Non-string types
+    preserve their natural comparison semantics.
+    """
+    match op:
+        case "eq":
+            return bool(_ci(val) == _ci(pv))
+        case "neq":
+            return bool(_ci(val) != _ci(pv))
+        case "in":
+            return _ci(val) in [_ci(x) for x in (pv or [])]
+        case "not_in":
+            return _ci(val) not in [_ci(x) for x in (pv or [])]
+        case "regex":
+            # `regex` is re.search (substring match). Anchor with ^...$
+            # for full-match. re.IGNORECASE so '^light\.' matches 'Light.x'.
+            return (
+                isinstance(val, str)
+                and isinstance(pv, str)
+                and re.search(pv, val, re.IGNORECASE) is not None
+            )
+        case "contains":
+            return _contains_matches(val, pv)
+        case "gt" | "lt":
+            return _numeric_matches(val, op, pv)
+    return False
+
+
+def match_predicate(predicate: Predicate, args: dict[str, Any]) -> bool:
+    values = list(iter_path_values(args, predicate.path))
+    if predicate.op == "exists":
+        return bool(values)
+    if not values:
+        return False
+    # Existential semantics: a wildcard path matches if ANY value at the
+    # wildcard satisfies the op. For non-wildcard paths there's at most
+    # one value so the any() collapses to a single check.
+    return any(_op_matches(v, predicate.op, predicate.value) for v in values)
+
+
+def match_rule(rule: Rule, tool_name: str, args: dict[str, Any]) -> bool:
+    if rule.tool_name not in ("*", tool_name):
+        return False
+    return all(match_predicate(p, args) for p in rule.when)
+
+
+def find_matching_rule(
+    tool_name: str, args: dict[str, Any], policy: Policy
+) -> Rule | None:
+    for rule in policy.rules:
+        if match_rule(rule, tool_name, args):
+            return rule
+    return None
+
+
+def _predicate_reaches_operations(path: str) -> bool:
+    """Whether ``path`` can walk into ``args.operations`` under ``iter_path_values``.
+
+    ``operations`` sits directly under ``args``, so only the first two
+    segments after stripping the implicit ``args`` prefix matter. A literal
+    ``operations`` first segment obviously reaches it. A leading ``*`` reaches
+    it too — a wildcard segment fans out over EVERY value at that level (see
+    ``iter_path_values``), landing on the `operations` list value exactly as
+    readily as any other top-level key — but ``operations`` is a *list*, so a
+    literal segment right after that wildcard (e.g. ``domain`` in
+    ``args.*.domain``) can only ever match a *dict* value at that level (like
+    ``selector``) — ``walk()`` requires ``isinstance(cur, dict)`` for a
+    literal head, so it silently yields nothing against a list and can never
+    reach an operation row. Only a SECOND wildcard (``args.*.*...``, as in
+    ``args.*.*.entity_id``) or no further segment at all (bare ``args.*``,
+    which yields the raw ``operations`` list value itself) can actually reach
+    into the list. Any other concrete first segment (e.g. ``selector``) can
+    only ever address selector-inspectable fields and is precisely excluded.
+    """
+    parts = path.split(".")
+    if parts and parts[0] == "args":
+        parts = parts[1:]
+    if not parts:
+        return False
+    if parts[0] == "operations":
+        return True
+    return parts[0] == "*" and (len(parts) == 1 or parts[1] == "*")
+
+
+def _rule_needs_resolved_operations(rule: Rule) -> bool:
+    """Whether ``rule`` inspects fields only known after selector resolution.
+
+    A selector-mode ``ha_bulk_control`` call carries ``args.selector``, not
+    ``args.operations`` — the leaf targets don't exist yet, they're resolved
+    inside the tool after this middleware runs. A rule predicate that can
+    reach ``args.operations`` (exact, prefixed, or via a leading wildcard —
+    see ``_predicate_reaches_operations``) can therefore never get a fair
+    match attempt against a selector call and needs the fail-safe below. A
+    rule whose predicates only ever address selector-inspectable fields
+    (e.g. ``args.selector.domain``) already got a fair, precise match
+    attempt in ``find_matching_rule`` and must not be broadened into an
+    unconditional gate.
+    """
+    return any(_predicate_reaches_operations(p.path) for p in rule.when)
+
+
+def evaluate(tool_name: str, args: dict[str, Any], policy: Policy) -> Verdict:
+    """Decide whether one tool call requires approval under ``policy``.
+
+    A normal rule match (``find_matching_rule``) decides most calls. Two
+    fail-safes broaden approval beyond an exact predicate match, each only
+    when the operator has SOME rule that could plausibly apply: an
+    unmatched ``ha_call_service`` ``ws_command`` call (no ``domain``/
+    ``service`` args for a domain/service-keyed rule to match), and an
+    ``ha_bulk_control`` selector call whose matching rule needs fields
+    (``args.operations.*``) that don't exist yet at gate time, resolved
+    only later inside the tool. See the fail-safe blocks below for the
+    full reasoning behind each.
+    """
+    if find_matching_rule(tool_name, args, policy) is not None:
+        return Verdict.REQUIRE_APPROVAL
+    # ha_call_service exposes a raw WebSocket escape hatch (``ws_command``) that
+    # carries no ``domain``/``service`` argument, so a rule keyed on
+    # ``args.domain``/``args.service`` cannot match it and it would otherwise slip
+    # through the fail-open default. If the operator has ANY rule that applies to
+    # ha_call_service -- one scoped to it by name, or a wildcard ``*`` rule, which
+    # ``match_rule`` treats as applying to every tool -- treat an unmatched
+    # ws_command call as require-approval (fail safe) so the escape hatch cannot
+    # sneak past that oversight. Blocking the call (require-approval) rather than
+    # silently allowing it is the safe error direction for a raw WS escape hatch,
+    # especially since the write-command blocklist is a deliberately
+    # non-exhaustive wrapper-bypass list that leans on this gate.
+    # Operators who want finer control can add a rule keyed on ``args.ws_command``.
+    if (
+        tool_name == "ha_call_service"
+        and args.get("ws_command")
+        and any(rule.tool_name in ("ha_call_service", "*") for rule in policy.rules)
+    ):
+        return Verdict.REQUIRE_APPROVAL
+    # Structural selectors are resolved inside the tool, after this middleware.
+    # A pre-existing rule that inspects args.operations.* therefore cannot inspect
+    # the eventual leaf targets. Fail safe only for rules that actually depend on
+    # that unresolved data — a rule fully expressed over selector-inspectable
+    # fields (e.g. args.selector.domain) already had its precise shot at matching
+    # above, and broadening it here would defeat a deliberately conditional rule
+    # (a rule scoped to selector.domain == "lock" must not gate a "light" call).
+    if has_dynamic_selector_targets(tool_name, args) and any(
+        rule.tool_name in ("ha_bulk_control", "*")
+        and _rule_needs_resolved_operations(rule)
+        for rule in policy.rules
+    ):
+        return Verdict.REQUIRE_APPROVAL
+    return Verdict.ALLOW