ha-mcp-dev 7.4.1.dev449__tar.gz → 7.4.1.dev450__tar.gz

{ha_mcp_dev-7.4.1.dev449/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev450}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev449
+Version: 7.4.1.dev450
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.4.1.dev449 → ha_mcp_dev-7.4.1.dev450}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.4.1.dev449"
+version = "7.4.1.dev450"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.4.1.dev449 → ha_mcp_dev-7.4.1.dev450}/src/ha_mcp/tools/tools_addons.py

@@ -28,7 +28,11 @@ from ..errors import (
     create_error_response,
     create_validation_error,
 )
-from ..utils.python_sandbox import PythonSandboxError, safe_execute_expression
+from ..utils.python_sandbox import (
+    PythonSandboxError,
+    format_sandbox_error,
+    safe_execute_expression,
+)
 from .helpers import (
     exception_to_structured_error,
     get_connected_ws_client,
@@ -179,16 +183,15 @@ def _apply_response_transform(response: Any, expr: str) -> Any:
     try:
         return safe_execute_expression(expr, {"response": response}, "response")
     except PythonSandboxError as e:
+        message, suggestions = format_sandbox_error(
+            e, expr, variable_name="response"
+        )
         raise_tool_error(
             create_error_response(
                 ErrorCode.VALIDATION_FAILED,
-                f"python_transform failed: {e!s}",
+                message,
                 context={"expression_preview": expr[:200]},
-                suggestions=[
-                    "Operate on the `response` variable (in-place or reassign)",
-                    "Allowed: dict/list access, assignment, loops, "
-                    "comprehensions, whitelisted str/list/dict methods",
-                ],
+                suggestions=suggestions,
             )
         )
 

{ha_mcp_dev-7.4.1.dev449 → ha_mcp_dev-7.4.1.dev450}/src/ha_mcp/tools/tools_config_automations.py

@@ -22,6 +22,7 @@ from ..errors import (
 from ..utils.config_hash import compute_config_hash
 from ..utils.python_sandbox import (
     PythonSandboxError,
+    format_sandbox_error,
     get_security_documentation,
     safe_execute,
 )
@@ -552,16 +553,12 @@ class AutomationConfigTools:
                 try:
                     transformed_config = safe_execute(python_transform, current_config)
                 except PythonSandboxError as e:
+                    message, suggestions = format_sandbox_error(e, python_transform)
                     raise_tool_error(
                         create_error_response(
                             ErrorCode.VALIDATION_FAILED,
-                            str(e),
-                            suggestions=[
-                                "Check expression syntax",
-                                "Ensure only allowed operations are used",
-                                "See tool description for allowed operations",
-                                f"Expression: {python_transform[:100]}{'...' if len(python_transform) > 100 else ''}",
-                            ],
+                            message,
+                            suggestions=suggestions,
                             context={"action": "python_transform", "identifier": identifier},
                         )
                     )

{ha_mcp_dev-7.4.1.dev449 → ha_mcp_dev-7.4.1.dev450}/src/ha_mcp/tools/tools_config_dashboards.py

@@ -16,6 +16,7 @@ from ..errors import ErrorCode, create_error_response, create_resource_not_found
 from ..utils.config_hash import compute_config_hash
 from ..utils.python_sandbox import (
     PythonSandboxError,
+    format_sandbox_error,
     get_security_documentation,
     safe_execute,
 )
@@ -1069,16 +1070,12 @@ def register_config_dashboard_tools(mcp: Any, client: Any, **kwargs: Any) -> Non
                 try:
                     transformed_config = safe_execute(python_transform, current_config)
                 except PythonSandboxError as e:
+                    message, suggestions = format_sandbox_error(e, python_transform)
                     raise_tool_error(
                         create_error_response(
                             ErrorCode.VALIDATION_FAILED,
-                            str(e),
-                            suggestions=[
-                                "Check expression syntax",
-                                "Ensure only allowed operations are used",
-                                "See tool description for allowed operations",
-                                f"Expression: {python_transform[:100]}...",
-                            ],
+                            message,
+                            suggestions=suggestions,
                             context={
                                 "action": "python_transform",
                                 "url_path": url_path,

{ha_mcp_dev-7.4.1.dev449 → ha_mcp_dev-7.4.1.dev450}/src/ha_mcp/tools/tools_config_scripts.py

@@ -16,6 +16,7 @@ from ..errors import ErrorCode, create_error_response
 from ..utils.config_hash import compute_config_hash
 from ..utils.python_sandbox import (
     PythonSandboxError,
+    format_sandbox_error,
     get_security_documentation,
     safe_execute,
 )
@@ -446,16 +447,12 @@ class ConfigScriptTools:
                 try:
                     transformed_config = safe_execute(python_transform, actual_config)
                 except PythonSandboxError as e:
+                    message, suggestions = format_sandbox_error(e, python_transform)
                     raise_tool_error(
                         create_error_response(
                             ErrorCode.VALIDATION_FAILED,
-                            str(e),
-                            suggestions=[
-                                "Check expression syntax",
-                                "Ensure only allowed operations are used",
-                                "See tool description for allowed operations",
-                                f"Expression: {python_transform[:100]}{'...' if len(python_transform) > 100 else ''}",
-                            ],
+                            message,
+                            suggestions=suggestions,
                             context={"action": "python_transform", "script_id": script_id},
                         )
                     )

{ha_mcp_dev-7.4.1.dev449 → ha_mcp_dev-7.4.1.dev450}/src/ha_mcp/utils/python_sandbox.py

@@ -11,8 +11,43 @@ from typing import Any, cast
 
 
 class PythonSandboxError(Exception):
-    """Raised when expression validation fails."""
+    """Base class for sandbox failures.
 
+    Catch this when callers don't need to distinguish validation-time
+    rejection from runtime exceptions — otherwise prefer the subclasses.
+    """
+
+
+class PythonSandboxValidationError(PythonSandboxError):
+    """Raised when AST validation rejects the expression before execution.
+
+    The expression contains a forbidden node, function, or method, or
+    failed to parse. The user can fix the input.
+    """
+
+
+class PythonSandboxExecutionError(PythonSandboxError):
+    """Raised when a validated expression raised at runtime.
+
+    The expression passed AST validation but produced a Python exception
+    when executed (e.g. KeyError on a missing key, TypeError on a bad
+    operation). Different from a validation failure: the *shape* of the
+    expression is fine, but it doesn't apply cleanly to the input data.
+    """
+
+
+# Cap on how much of a runtime exception's text gets surfaced. HA configs
+# can carry tokens / passwords / device addresses, and Python's default
+# repr happily embeds dict and list values into KeyError/TypeError text.
+# 240 chars is enough to identify the failure (exception type + a short
+# snippet) without pasting the input config back to the caller.
+_EXECUTION_ERROR_TEXT_LIMIT = 240
+
+
+def _truncate_for_error(text: str, limit: int = _EXECUTION_ERROR_TEXT_LIMIT) -> str:
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3] + "..."
 
 
 # Whitelist of safe AST node types
@@ -23,16 +58,19 @@ SAFE_NODES = {
     ast.Assign,
     ast.AugAssign,  # +=, -=, etc.
     ast.AnnAssign,  # type annotations
+    ast.Pass,  # explicit no-op
     # Control flow
     ast.If,
     ast.For,
     ast.While,
     ast.Break,
     ast.Continue,
+    ast.IfExp,  # ternary: x if c else y
     # Data access
     ast.Subscript,
     ast.Attribute,
     ast.Index,
+    ast.Slice,  # list[1:3]
     ast.Name,
     ast.Load,
     ast.Store,
@@ -43,6 +81,9 @@ SAFE_NODES = {
     ast.Dict,
     ast.Tuple,
     ast.Set,
+    ast.Starred,  # *iterable in calls/literals: f(*xs), [*xs, y]
+    ast.JoinedStr,  # f"…" — outer node holding parts
+    ast.FormattedValue,  # the {expr} part inside an f-string
     # Operations
     ast.Delete,
     ast.BinOp,
@@ -73,13 +114,54 @@ SAFE_NODES = {
     ast.IsNot,
     # Function calls (validated separately)
     ast.Call,
+    ast.keyword,  # keyword arguments: func(key=value)
     # Comprehensions
     ast.ListComp,
     ast.DictComp,
     ast.SetComp,
+    ast.GeneratorExp,  # (x for x in ...)
     ast.comprehension,
-    # Lambda (for comprehensions)
+    # Lambda — useful as `key=` for sorted/min/max. ast.arguments and
+    # ast.arg are the structure nodes ast.walk descends into for the
+    # parameter list; they have no execution semantics on their own
+    # (FunctionDef would be blocked at the SAFE_NODES check above).
     ast.Lambda,
+    ast.arguments,
+    ast.arg,
+}
+
+
+# Hints to help agents recover when a forbidden node is encountered.
+# Keyed on AST class name (string, not class) so entries for
+# version-specific nodes like Match (3.10+) or TryStar (3.11+) stay
+# evaluable on any Python. Unmapped keys fall through to the generic
+# "Forbidden node type: X" message in `_validate_node`.
+_NODE_SUGGESTIONS: dict[str, str] = {
+    "Try": "validate inputs with isinstance/in/.get() instead of try/except",
+    "TryStar": "validate inputs with isinstance/in/.get() instead of try/except",
+    "ExceptHandler": "validate inputs with isinstance/in/.get() instead of try/except",
+    "With": "perform the inner logic directly; with-blocks aren't supported",
+    "AsyncWith": "perform the inner logic directly; with-blocks aren't supported",
+    "FunctionDef": "use a list comprehension or inline the logic",
+    "AsyncFunctionDef": "use a list comprehension or inline the logic",
+    "ClassDef": "use a dict literal instead of defining a class",
+    "Yield": "build a list with a comprehension or for-loop append",
+    "YieldFrom": "build a list with a comprehension or for-loop append",
+    "Global": "assign directly to the variable; scope keywords aren't supported",
+    "Nonlocal": "assign directly to the variable; scope keywords aren't supported",
+    "Import": "imports aren't available; built-ins like isinstance/len/range are exposed",
+    "ImportFrom": "imports aren't available; built-ins like isinstance/len/range are exposed",
+    "Match": "use if/elif/else or a dict lookup instead of match/case",
+    # If Match ever enters SAFE_NODES, the sub-pattern nodes shouldn't
+    # silently slip through with a generic message.
+    "MatchAs": "use if/elif/else or a dict lookup instead of match/case",
+    "MatchValue": "use if/elif/else or a dict lookup instead of match/case",
+    "MatchClass": "use if/elif/else or a dict lookup instead of match/case",
+    "MatchSingleton": "use if/elif/else or a dict lookup instead of match/case",
+    "MatchSequence": "use if/elif/else or a dict lookup instead of match/case",
+    "MatchMapping": "use if/elif/else or a dict lookup instead of match/case",
+    "MatchOr": "use if/elif/else or a dict lookup instead of match/case",
+    "MatchStar": "use if/elif/else or a dict lookup instead of match/case",
 }
 
 # Whitelist of safe methods that can be called
@@ -201,12 +283,20 @@ def validate_expression(expr: str) -> tuple[bool, str]:
 
 
 def _validate_node(node: ast.AST) -> str | None:
-    """Validate a single AST node. Returns error message or None if safe."""
-    if type(node) not in SAFE_NODES:
-        return f"Forbidden node type: {type(node).__name__}"
+    """Validate a single AST node. Returns error message or None if safe.
 
-    if isinstance(node, (ast.Import, ast.ImportFrom)):
-        return "Forbidden: imports not allowed"
+    Whitelist check first: any node not in ``SAFE_NODES`` is rejected with
+    its class name and (when available) a recovery hint from
+    ``_NODE_SUGGESTIONS``. After that, only nodes that *are* safe but need
+    extra checks (Attribute → block dunder access, Call → block forbidden
+    functions/methods) get further validation.
+    """
+    if type(node) not in SAFE_NODES:
+        name = type(node).__name__
+        hint = _NODE_SUGGESTIONS.get(name)
+        if hint:
+            return f"Forbidden node type: {name} — {hint}"
+        return f"Forbidden node type: {name}"
 
     if isinstance(node, ast.Attribute):
         if node.attr.startswith("__") and node.attr.endswith("__"):
@@ -215,15 +305,6 @@ def _validate_node(node: ast.AST) -> str | None:
     if isinstance(node, ast.Call):
         return _validate_call_node(node)
 
-    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
-        return "Forbidden: function/class definitions not allowed"
-
-    if isinstance(node, (ast.With, ast.AsyncWith)):
-        return "Forbidden: with statements not allowed"
-
-    if isinstance(node, (ast.Try, ast.ExceptHandler)):
-        return "Forbidden: try/except not allowed"
-
     return None
 
 
@@ -279,10 +360,10 @@ def safe_execute_expression(
     """
     valid, error = validate_expression(expr)
     if not valid:
-        raise PythonSandboxError(f"Expression validation failed: {error}")
+        raise PythonSandboxValidationError(error)
 
     if result_key not in variables:
-        raise PythonSandboxError(
+        raise PythonSandboxValidationError(
             f"result_key {result_key!r} not found in variables",
         )
 
@@ -295,8 +376,24 @@ def safe_execute_expression(
 
     try:
         exec(expr, safe_globals, safe_locals)
+    except (MemoryError, RecursionError):
+        # Resource exhaustion — let the host decide. Reframing
+        # "ran out of memory" as "your transform was bad" would
+        # mislead the agent into rewriting an expression that
+        # was structurally fine.
+        #
+        # FastMCP's tool dispatch (server.py call_tool) catches
+        # `except Exception` and wraps in
+        # ``ToolError(f"Error calling tool {name!r}: {e}") from e`` —
+        # so the original exception's class name and text reach the
+        # agent, with the raw exception preserved as ``__cause__``.
+        # That's an acceptable surfacing (not opaque INTERNAL_ERROR).
+        raise
     except Exception as e:
-        raise PythonSandboxError(f"Execution error: {type(e).__name__}: {e}") from e
+        # Truncate so embedded reprs of input data (config dicts, tokens,
+        # etc.) don't reach the caller verbatim.
+        detail = _truncate_for_error(f"{type(e).__name__}: {e}")
+        raise PythonSandboxExecutionError(detail) from e
 
     return safe_locals[result_key]
 
@@ -335,6 +432,54 @@ def safe_execute(expr: str, config: dict[str, Any]) -> dict[str, Any]:
     )
 
 
+def format_sandbox_error(
+    error: PythonSandboxError,
+    expr: str,
+    variable_name: str = "config",
+) -> tuple[str, list[str]]:
+    """Build a (message, suggestions) pair appropriate for the error subclass.
+
+    ``PythonSandboxValidationError`` means the expression's shape was
+    rejected before execution — suggestions point at syntax/allowed-ops.
+    ``PythonSandboxExecutionError`` means the expression was accepted
+    but raised at runtime — suggestions point at keys/types/values.
+    Plain ``PythonSandboxError`` (no subclass) falls back to the
+    validation form.
+
+    ``variable_name`` is the name of the mutable target the expression
+    operates on. The default ``"config"`` matches the dashboard /
+    automation / script callers; addon helpers pass ``"response"`` and
+    a one-liner about that name is prepended to the suggestions so
+    agents know which variable to mutate.
+
+    Used by ``ha_config_set_*`` and addon helpers so each caller emits
+    the same shape of MCP error without duplicating the boilerplate.
+    """
+    preview = expr[:100] + ("..." if len(expr) > 100 else "")
+    if isinstance(error, PythonSandboxExecutionError):
+        message = f"Expression raised at runtime: {error}"
+        suggestions = [
+            "Verify referenced keys/indices exist in the input",
+            "Check that types match (e.g. dict vs list operations)",
+            "Use .get(key, default) to handle missing keys",
+            f"Expression: {preview}",
+        ]
+    else:
+        message = f"Expression validation failed: {error}"
+        suggestions = [
+            "Check expression syntax",
+            "Ensure only allowed operations are used",
+            "See tool description for allowed operations",
+            f"Expression: {preview}",
+        ]
+    if variable_name != "config":
+        suggestions = [
+            f"Operate on the `{variable_name}` variable (in-place or reassign)",
+            *suggestions,
+        ]
+    return message, suggestions
+
+
 def get_security_documentation() -> str:
     """
     Get formatted documentation of security restrictions.
@@ -346,12 +491,18 @@ PYTHON TRANSFORM SECURITY:
 
 ✅ ALLOWED:
 - Dictionary/list access: config['views'][0]['cards'][1]
+- Slicing: config['views'][0]['cards'][1:3]
 - Assignment: config['key'] = 'value'
 - Deletion: del config['key'] or config.pop('key')
 - List methods: append, insert, pop, remove, clear, extend
 - Dict methods: update, get, setdefault, keys, values, items
-- Loops: for, while, if/else
-- Comprehensions: [x for x in ...]
+- Loops: for, while, if/else, pass, break, continue
+- Comprehensions: [x for x in ...], {k: v for ...}, (x for x in ...)
+- Ternary: x if condition else y
+- Iterable unpacking (* in calls/literals): f(*xs), [*xs, y]
+- Dict unpacking (**) in calls and dict literals: {**d, 'k': v}
+- Keyword arguments: func(key=value)
+- Lambdas (e.g. for `key=`): sorted(items, key=lambda x: x['score'])
 - String methods: startswith, endswith, lower, upper, split, join
 - Safe builtins: isinstance, len, range, enumerate, zip, sorted, reversed,
   min, max, sum, abs, any, all, round, str, int, float, bool, list, dict,
@@ -363,5 +514,14 @@ PYTHON TRANSFORM SECURITY:
 - Dunder access: __class__, __bases__, __subclasses__
 - Dangerous builtins: eval, exec, compile, getattr, setattr, delattr, hasattr
 - Function definitions: def, class
-- Exception handling: try/except (use validation instead)
+- Exception handling: try/except (validate with isinstance/in/.get() instead)
+
+🎯 PATTERNS:
+- Filter cards: cards = [c for c in cards if keep(c)]
+- Skip in a loop: prefer `continue` over an empty `pass` branch (clearer)
+- Conditionally include: build a new list and `.append(x)` only the
+  cards you want, instead of iterating the original and using if/pass
+  branches to drop entries
+- Modify in place when possible (single pass, fewer surprises) over
+  reconstructing the entire list
 """.strip()

{ha_mcp_dev-7.4.1.dev449 → ha_mcp_dev-7.4.1.dev450/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev449
+Version: 7.4.1.dev450
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT