ha-mcp-dev 8.6.0.dev2934__tar.gz → 8.6.0.dev2938__tar.gz

{ha_mcp_dev-8.6.0.dev2934 → ha_mcp_dev-8.6.0.dev2938}/PKG-INFO

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

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

{ha_mcp_dev-8.6.0.dev2934 → ha_mcp_dev-8.6.0.dev2938}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2934"
+version = "8.6.0.dev2938"
 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.6.0.dev2934 → ha_mcp_dev-8.6.0.dev2938}/src/ha_mcp/errors.py

@@ -466,6 +466,7 @@ def create_validation_error(
     details: str | None = None,
     invalid_json: bool = False,
     context: dict[str, Any] | None = None,
+    suggestions: list[str] | None = None,
 ) -> dict[str, Any]:
     """Create a validation error response."""
     code = (
@@ -480,7 +481,11 @@ def create_validation_error(
     if parameter:
         final_context["parameter"] = parameter
     return create_error_response(
-        code, message, details, context=final_context if final_context else None
+        code,
+        message,
+        details,
+        suggestions=suggestions,
+        context=final_context if final_context else None,
     )
 
 

ha_mcp_dev-8.6.0.dev2938/src/ha_mcp/tools/config_write_errors.py

@@ -0,0 +1,185 @@
+"""Input-validation rejections for config writes (issue #2649).
+
+Kept out of tools_config_automations.py so that file stays under its
+module-size baseline. The helpers raise through ``raise_tool_error`` and
+carry no client or Home Assistant dependency.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import ErrorCode, create_error_response
+from .helpers import raise_tool_error
+
+# Guidance reused wherever the runtime-only ``enabled`` key folds into
+# another rejection.
+ENABLED_MISPLACED_GUIDANCE = (
+    "'enabled' is a runtime-only tool parameter, not a valid automation "
+    "config key — pass it to ha_config_set_automation as enabled=True/False "
+    "instead of putting it in config."
+)
+ENABLED_REMOVE_SUGGESTION = (
+    "Remove 'enabled' from config and pass enabled=True or False "
+    "to ha_config_set_automation"
+)
+ENABLED_UNCHANGED_SUGGESTION = (
+    "Use enabled=None to leave the current runtime state unchanged"
+)
+
+
+def config_has_enabled(config: Any) -> bool:
+    """Whether a config body carries the runtime-only ``enabled`` key."""
+    return isinstance(config, dict) and "enabled" in config
+
+
+def _missing_fields_shape(is_blueprint: bool) -> str:
+    """One-line expected config shape with copy-pasteable quoted keys."""
+    if is_blueprint:
+        return (
+            "config={'alias': 'My Automation', 'use_blueprint': "
+            "{'path': 'light.yaml', 'input': {...}}}"
+        )
+    return "config={'alias': 'My Automation', 'triggers': [...], 'actions': [...]}"
+
+
+def _missing_field_guidance(
+    missing_fields: list[str], is_blueprint: bool, source: str
+) -> tuple[str, list[str]]:
+    """Message and suggestions for missing required fields, worded by source.
+
+    For the ``config`` argument the guidance points inside ``config``; for a
+    ``python_transform`` the config came from a transform expression, so the
+    guidance points at the transform instead (telling it to send
+    ``config={...}`` would earn a write-modes rejection).
+    """
+    fields = ", ".join(missing_fields)
+    if source == "python_transform":
+        first = missing_fields[0]
+        return (
+            f"Missing required fields: {fields}. Add them in your "
+            f"python_transform expression, e.g. config['{first}'] = ... .",
+            [
+                "Set the missing field(s) on the transformed config, e.g. "
+                f"config['{first}'] = '...'."
+            ],
+        )
+    shape = _missing_fields_shape(is_blueprint)
+    return (
+        f"Missing required fields: {fields}. Required automation fields go "
+        f"inside `config`, e.g. {shape}.",
+        [f"Add the missing field(s) inside the `config` argument: {shape}."],
+    )
+
+
+def reject_sequence_misroute(
+    config_dict: dict[str, Any],
+    missing_fields: list[str],
+    identifier: str | None,
+    source: str = "config",
+) -> None:
+    """Raise when a 'sequence' key shows the config is really a script.
+
+    Returns silently when the config does not look script-shaped, so the
+    caller stays a one-liner. A runtime-only ``enabled`` key folds into the
+    same rejection instead of costing another round trip.
+    """
+    if not (
+        missing_fields
+        and "sequence" in config_dict
+        and ("triggers" in missing_fields or "actions" in missing_fields)
+    ):
+        return
+    context: dict[str, Any] = {"missing_fields": missing_fields}
+    if identifier:
+        context["identifier"] = identifier
+    message = f"Missing required fields: {', '.join(missing_fields)}"
+    if source == "python_transform":
+        automation_fix = (
+            "In the python_transform expression, replace 'sequence' with "
+            "'actions' and add 'triggers'."
+        )
+        if "alias" in missing_fields:
+            automation_fix += (
+                " Set 'alias' in the expression too, e.g. config['alias'] = '...'."
+            )
+    else:
+        automation_fix = (
+            "For an automation, replace 'sequence' with 'actions' and add 'triggers'."
+        )
+        if "alias" in missing_fields:
+            automation_fix += (
+                " Put 'alias' inside `config` too, e.g. "
+                f"{_missing_fields_shape(is_blueprint=False)}."
+            )
+    suggestions = [
+        "Did you mean ha_config_set_script? Scripts use 'sequence' directly.",
+        automation_fix,
+    ]
+    if config_has_enabled(config_dict):
+        context["invalid_key"] = "enabled"
+        message += f". {ENABLED_MISPLACED_GUIDANCE}"
+        suggestions.extend([ENABLED_REMOVE_SUGGESTION, ENABLED_UNCHANGED_SUGGESTION])
+    raise_tool_error(
+        create_error_response(
+            code=ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS,
+            message=message,
+            details=(
+                "Config contains 'sequence', which belongs to scripts. "
+                "Automations use 'triggers' and 'actions'; scripts use 'sequence'."
+            ),
+            suggestions=suggestions,
+            context=context,
+        )
+    )
+
+
+def reject_invalid_config_inputs(
+    config_dict: dict[str, Any],
+    missing_fields: list[str],
+    identifier: str | None,
+    source: str = "config",
+) -> None:
+    """Raise the structured rejection for a config write's input violations.
+
+    A missing-field rejection says where the field goes and shows the
+    expected shape in one line; a runtime-only ``enabled`` key together with
+    missing required fields surfaces in ONE rejection instead of one round
+    trip each. Returns silently when the inputs are valid.
+    """
+    enabled_in_config = config_has_enabled(config_dict)
+    if not missing_fields and not enabled_in_config:
+        return
+    context: dict[str, Any] = {}
+    if identifier:
+        context["identifier"] = identifier
+    if missing_fields:
+        context["missing_fields"] = missing_fields
+        message, suggestions = _missing_field_guidance(
+            missing_fields, "use_blueprint" in config_dict, source
+        )
+        if enabled_in_config:
+            context["invalid_key"] = "enabled"
+            message = f"{message} {ENABLED_MISPLACED_GUIDANCE}"
+            suggestions = suggestions + [
+                ENABLED_REMOVE_SUGGESTION,
+                ENABLED_UNCHANGED_SUGGESTION,
+            ]
+        raise_tool_error(
+            create_error_response(
+                code=ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS,
+                message=message,
+                details=f"Missing required fields: {', '.join(missing_fields)}",
+                suggestions=suggestions,
+                context=context or None,
+            )
+        )
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            "'enabled' is a runtime-only tool parameter, not a valid "
+            "automation config key",
+            suggestions=[ENABLED_REMOVE_SUGGESTION, ENABLED_UNCHANGED_SUGGESTION],
+            context={"action": "set", "invalid_key": "enabled"},
+        )
+    )

{ha_mcp_dev-8.6.0.dev2934 → ha_mcp_dev-8.6.0.dev2938}/src/ha_mcp/tools/tools_config_automations.py

@@ -20,7 +20,6 @@ from ..client.rest_client import (
 )
 from ..errors import (
     ErrorCode,
-    create_config_error,
     create_error_response,
     create_validation_error,
 )
@@ -47,6 +46,10 @@ from .blueprint_substitute import (
 from .coercion import JSON_STRING_COERCION, coerce_to_list, parse_json_param
 from .component_config_reads import fetch_entity_lookup_via_component
 from .config_helpers.registry import validate_registry_ids
+from .config_write_errors import (
+    reject_invalid_config_inputs,
+    reject_sequence_misroute,
+)
 from .config_write_helpers import (
     apply_entity_category,
     attach_skill_content,
@@ -425,24 +428,6 @@ def _run_actions_once_reloaded(
 _STANDALONE_RUNTIME_ACTIONS = ("set_enabled", "run_actions")
 
 
-def _reject_enabled_in_config(config: Any) -> None:
-    """Reject the runtime-only ``enabled`` key in a stored config body."""
-    if isinstance(config, dict) and "enabled" in config:
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.VALIDATION_INVALID_PARAMETER,
-                "'enabled' is a runtime-only tool parameter, not a valid "
-                "automation config key",
-                suggestions=[
-                    "Remove 'enabled' from config and pass enabled=True or False "
-                    + "to ha_config_set_automation",
-                    "Use enabled=None to leave the current runtime state unchanged",
-                ],
-                context={"action": "set", "invalid_key": "enabled"},
-            )
-        )
-
-
 async def _set_automation_enabled(client: Any, entity_id: str, enabled: bool) -> Any:
     """Set an automation's runtime enabled state through Home Assistant."""
     service = "turn_on" if enabled else "turn_off"
@@ -902,7 +887,6 @@ class AutomationConfigTools:
                 )
 
             config_dict = self._parse_and_validate_config(config)
-            _reject_enabled_in_config(config_dict)
 
             # Extract category before sending to HA REST API (which rejects unknown keys).
             # Parameter takes precedence over config dict value.
@@ -917,6 +901,13 @@ class AutomationConfigTools:
             # (trigger -> triggers, action -> actions, condition -> conditions).
             config_dict = _normalize_automation_config(config_dict)
 
+            # Purely local input checks run before the tool's own reads, so
+            # a malformed config rejects without spending the hash check's
+            # or the alias guard's GETs. (The auto-backup wrapper may take
+            # its pre-write snapshot first on updates; that read is outside
+            # this tool's control.)
+            self._validate_required_fields(config_dict, identifier)
+
             # Both the hash check and alias guard read the resolved storage key.
             # Reuse it for the write to avoid a second entity-ID lookup (#1813).
             # Creation and responses without an id retain the existing fallback.
@@ -930,7 +921,6 @@ class AutomationConfigTools:
                     identifier, config_dict
                 )
 
-            self._validate_required_fields(config_dict, identifier)
             bp_warnings = _check_best_practices(config_dict)
             validation_meta = await validate_config_references(
                 self._client, config_dict
@@ -1377,7 +1367,6 @@ class AutomationConfigTools:
             source="python_transform",
         )
         # Pop category before sending to HA REST API (rejects unknown keys)
-        _reject_enabled_in_config(transformed_config)
         transform_category = transformed_config.pop("category", None)
         effective_category = category if category is not None else transform_category
 
@@ -1387,7 +1376,9 @@ class AutomationConfigTools:
         conflict_warnings = _detect_conflicting_root_keys(transformed_config)
 
         transformed_config = _normalize_automation_config(transformed_config)
-        self._validate_required_fields(transformed_config, identifier)
+        self._validate_required_fields(
+            transformed_config, identifier, source="python_transform"
+        )
         bp_warnings = _check_best_practices(transformed_config)
 
         # Issue #2159: reject an unknown category before the write, so a
@@ -1848,9 +1839,13 @@ class AutomationConfigTools:
 
     @staticmethod
     def _validate_required_fields(
-        config_dict: dict[str, Any], identifier: str | None
+        config_dict: dict[str, Any], identifier: str | None, source: str = "config"
     ) -> None:
-        """Validate required fields and prevent duplicate creation."""
+        """Validate required fields and prevent duplicate creation.
+
+        A missing required field and a misplaced runtime-only ``enabled`` key
+        surface in ONE rejection (issue #2649).
+        """
         if "use_blueprint" in config_dict:
             required_fields = ["alias"]
             # Strip empty triggers/actions/conditions arrays that would override blueprint
@@ -1861,38 +1856,8 @@ class AutomationConfigTools:
             required_fields = ["alias", "triggers", "actions"]
 
         missing_fields = [f for f in required_fields if f not in config_dict]
-        if missing_fields:
-            # If the caller supplied a 'sequence' key, the config looks like a
-            # script — point them at ha_config_set_script instead of the generic
-            # missing-fields error.
-            if "sequence" in config_dict and (
-                "triggers" in missing_fields or "actions" in missing_fields
-            ):
-                context: dict[str, Any] = {"missing_fields": missing_fields}
-                if identifier:
-                    context["identifier"] = identifier
-                raise_tool_error(
-                    create_error_response(
-                        code=ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS,
-                        message=f"Missing required fields: {', '.join(missing_fields)}",
-                        details=(
-                            "Config contains 'sequence', which belongs to scripts. "
-                            "Automations use 'triggers' and 'actions'; scripts use 'sequence'."
-                        ),
-                        suggestions=[
-                            "Did you mean ha_config_set_script? Scripts use 'sequence' directly.",
-                            "For an automation, replace 'sequence' with 'actions' and add 'triggers'.",
-                        ],
-                        context=context,
-                    )
-                )
-            raise_tool_error(
-                create_config_error(
-                    f"Missing required fields: {', '.join(missing_fields)}",
-                    identifier=identifier,
-                    missing_fields=missing_fields,
-                )
-            )
+        reject_sequence_misroute(config_dict, missing_fields, identifier, source)
+        reject_invalid_config_inputs(config_dict, missing_fields, identifier, source)
 
         # Issue #1169: see _check_scene_create_misroute
         AutomationConfigTools._check_scene_create_misroute(config_dict, identifier)

{ha_mcp_dev-8.6.0.dev2934 → ha_mcp_dev-8.6.0.dev2938}/src/ha_mcp/tools/validation_middleware.py

@@ -48,6 +48,43 @@ _TYPE_HINTS: dict[str, str] = {
 
 _UNKNOWN_ARGUMENT = "unexpected_keyword_argument"
 
+# Config root keys that models habitually pass as top-level tool arguments on
+# the config-writing tools. When one arrives top-level, the rejection says the
+# key belongs inside `config` instead of only listing the valid tool
+# parameters (issue #2649 section 1).
+#
+# Scoped per tool on purpose: only the config-writing tools take a `config`
+# body, so only their top-level arguments can be misplaced config keys.
+# (Only these two were measured in BAT runs.)
+_CONFIG_ROOT_KEYS_BY_TOOL: dict[str, set[str]] = {
+    "ha_config_set_automation": {
+        "alias",
+        "description",
+        "triggers",
+        "trigger",
+        "actions",
+        "action",
+        "conditions",
+        "condition",
+        "mode",
+        "max",
+        "max_exceeded",
+        "variables",
+        "use_blueprint",
+    },
+    "ha_config_set_script": {
+        "alias",
+        "description",
+        "mode",
+        "sequence",
+        "max",
+        "max_exceeded",
+        "fields",
+        "icon",
+        "use_blueprint",
+    },
+}
+
 
 async def _tool_parameter_names(context: MiddlewareContext | None) -> list[str] | None:
     """Return the called tool's declared parameter names, or None if unavailable."""
@@ -103,14 +140,46 @@ def _closest_parameter(unknown: str, candidates: Sequence[str]) -> str | None:
     return best[3] if best else None
 
 
-def _unknown_argument_hint(param: str, unclaimed: Sequence[str]) -> str:
-    """Name an undeclared argument, suggesting the parameter it likely meant."""
+def _unknown_argument_hint(
+    param: str,
+    unclaimed: Sequence[str],
+    config_keys: set[str] | None = None,
+) -> str:
+    """Name an undeclared argument, suggesting the parameter it likely meant.
+
+    A config root key passed at the top level of a config-writing tool is told
+    to move inside ``config`` (issue #2649); everything else keeps the
+    did-you-mean behaviour.
+    """
+    if config_keys is not None and param in config_keys:
+        return (
+            f"unknown parameter; `{param}` is a config key, not a tool parameter "
+            "— move it inside `config`"
+        )
     match = _closest_parameter(param, unclaimed)
     return (
         f"unknown parameter, did you mean `{match}`?" if match else "unknown parameter"
     )
 
 
+def _argument_hint(
+    param: str,
+    errs: Sequence[ErrorDetails],
+    unclaimed: Sequence[str],
+    valid_parameters: list[str] | None,
+    config_keys: set[str] | None,
+) -> tuple[str, bool]:
+    """Hint for one rejected argument.
+
+    Returns the hint text and whether the argument is a config root key
+    passed at the top level of a config-writing tool (issue #2649).
+    """
+    if valid_parameters is not None and errs[0]["type"] == _UNKNOWN_ARGUMENT:
+        hint = _unknown_argument_hint(param, unclaimed, config_keys)
+        return hint, config_keys is not None and param in config_keys
+    return _type_hint(errs), False
+
+
 def _type_hint(errs: Sequence[ErrorDetails]) -> str:
     """Prefer a dict_type/list_type hint; else the first error's raw message."""
     return next(
@@ -161,22 +230,26 @@ class ValidationErrorMiddleware(Middleware):
                 else None
             )
             unclaimed: list[str] = []
+            config_keys: set[str] | None = None
             if valid_parameters is not None:
                 # Skip parameters the call already supplied: a second, invented
                 # argument almost never means one of them.
                 message_obj = getattr(context, "message", None)
                 supplied = getattr(message_obj, "arguments", None) or {}
                 unclaimed = [p for p in valid_parameters if p not in supplied]
+                tool_name = getattr(message_obj, "name", None)
+                config_keys = (
+                    _CONFIG_ROOT_KEYS_BY_TOOL.get(tool_name) if tool_name else None
+                )
 
             parts: list[str] = []
+            misplaced_keys: list[str] = []
             for param, errs in grouped.items():
-                if (
-                    valid_parameters is not None
-                    and errs[0]["type"] == _UNKNOWN_ARGUMENT
-                ):
-                    hint = _unknown_argument_hint(param, unclaimed)
-                else:
-                    hint = _type_hint(errs)
+                hint, misplaced = _argument_hint(
+                    param, errs, unclaimed, valid_parameters, config_keys
+                )
+                if misplaced:
+                    misplaced_keys.append(param)
                 parts.append(f"`{param}`: {hint}" if param else hint)
             message = "; ".join(parts) if parts else "Invalid argument types."
             error_context: dict[str, Any] | None = None
@@ -185,11 +258,22 @@ class ValidationErrorMiddleware(Middleware):
                 listing = ", ".join(valid_parameters) or "none"
                 message += f"{separator}Valid parameters: {listing}."
                 error_context = {"valid_parameters": valid_parameters}
+            # A misplaced config key repeats the move in the suggestions, the
+            # way the missing-field rejection does (issue #2649 section 1);
+            # otherwise the generic suggestions stand.
+            suggestions: list[str] | None = None
+            if misplaced_keys:
+                suggestions = [
+                    f"Move `{key}` inside the `config` argument, e.g. "
+                    f"config={{'{key}': ...}}."
+                    for key in misplaced_keys
+                ]
             raise_tool_error(
                 create_validation_error(
                     message,
                     details=", ".join(dict.fromkeys(err["type"] for err in errors)),
                     context=error_context,
+                    suggestions=suggestions,
                 )
             )
         return result