ha-mcp-dev 7.5.0.dev525__tar.gz → 7.5.0.dev527__tar.gz

{ha_mcp_dev-7.5.0.dev525/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev527}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev525
+Version: 7.5.0.dev527
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -38,7 +38,7 @@ Dynamic: license-file
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-89-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-88-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -181,7 +181,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (89 tools)</b></summary>
+<summary><b>Complete Tool List (88 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -198,7 +198,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Files** | `ha_delete_file` *(beta)*, `ha_list_files` *(beta)*, `ha_read_file` *(beta)*, `ha_write_file` *(beta)* |
 | **Groups** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |
 | **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_repository_info`, `ha_hacs_search` |
-| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations`, `ha_get_helper_schema` |
+| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations` |
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
 | **Integrations** | `ha_get_integration`, `ha_set_integration_enabled` |
 | **Labels & Categories** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/README.md

@@ -8,7 +8,7 @@
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-89-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-88-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -151,7 +151,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (89 tools)</b></summary>
+<summary><b>Complete Tool List (88 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -168,7 +168,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Files** | `ha_delete_file` *(beta)*, `ha_list_files` *(beta)*, `ha_read_file` *(beta)*, `ha_write_file` *(beta)* |
 | **Groups** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |
 | **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_repository_info`, `ha_hacs_search` |
-| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations`, `ha_get_helper_schema` |
+| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations` |
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
 | **Integrations** | `ha_get_integration`, `ha_set_integration_enabled` |
 | **Labels & Categories** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev525"
+version = "7.5.0.dev527"
 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.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/helpers.py

@@ -78,6 +78,90 @@ def extract_tool_error_message(te: ToolError) -> str:
         return str(te)
 
 
+def validate_identifier_not_empty(
+    value: str | None,
+    param_name: str,
+    *,
+    message: str | None = None,
+    suggestions: list[str] | None = None,
+    context: dict[str, Any] | None = None,
+) -> str:
+    """Reject ``None``, empty, or whitespace-only identifier values.
+
+    Surfaces a structured ``VALIDATION_INVALID_PARAMETER`` response so
+    CRUD-style tools fail loudly on missing identifiers instead of silently
+    routing on Python falsy semantics or relying on Home Assistant to
+    translate a missing identifier into a generic ``RESOURCE_NOT_FOUND``.
+
+    The destructive class this protects against:
+    ``action = "update" if label_id else "create"`` — passing ``""`` as
+    ``label_id`` silently routes to ``create`` when the caller intended
+    ``update``. The whitespace class this protects against: ``" "`` is truthy
+    in Python so ``if not value:`` lets it through, but Home Assistant has
+    no entry with id ``" "``.
+
+    The value is checked but not normalised: ``" abc "`` (a real id wrapped
+    in spaces) is accepted as-is and returned untouched. Only purely empty or
+    purely whitespace strings are rejected.
+
+    ``None`` is also rejected by this helper. Callers for whom ``None`` is a
+    documented sentinel (e.g. ``label_id=None`` meaning "list all" or
+    "create new") must gate the call themselves with
+    ``if value is not None: validate_identifier_not_empty(value, ...)``.
+
+    Returning ``str`` (rather than ``None``) lets call sites use the helper
+    in narrowing position — ``name = validate_identifier_not_empty(name, …)``
+    re-binds ``name`` from ``str | None`` to ``str`` so mypy can prove later
+    uses are safe without a duplicate inline check.
+
+    Args:
+        value: Identifier string supplied by the caller. ``None`` is
+            rejected — see the ``None``-sentinel note above for the caller
+            pattern that permits the sentinel.
+        param_name: Name of the parameter, used in the structured error
+            response's ``context`` and the human-readable message.
+        message: Optional override for the human-readable error message.
+            Defaults to ``"{param_name} must be a non-empty, non-whitespace
+            string"`` when omitted.
+        suggestions: Optional list of guidance strings for the response's
+            ``suggestions`` field. Defaults to a generic
+            "provide a non-empty value" hint.
+        context: Optional additional context fields merged into the error
+            response (e.g. ``{"action": "update"}``). The keys ``parameter``
+            and ``value`` are always set and take precedence.
+
+    Returns:
+        The validated ``value`` unchanged (typed as ``str``).
+
+    Raises:
+        ToolError: When ``value`` is ``None``, empty, or whitespace-only —
+            carrying a structured ``VALIDATION_INVALID_PARAMETER`` response
+            with the parameter name, the offending value (for diagnostics),
+            and the suggestions.
+
+    Example:
+        >>> validate_identifier_not_empty(label_id, "label_id",
+        ...     suggestions=["Omit label_id to create a new label"])
+    """
+    if value is not None and value.strip():
+        return value
+
+    final_context: dict[str, Any] = {}
+    if context:
+        final_context.update(context)
+    final_context["parameter"] = param_name
+    final_context["value"] = value
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            message or f"{param_name} must be a non-empty, non-whitespace string",
+            suggestions=suggestions
+            or [f"Provide a valid non-empty value for {param_name}"],
+            context=final_context,
+        )
+    )
+
+
 async def get_connected_ws_client(
     base_url: str, token: str, verify_ssl: bool | None = None
 ) -> tuple[HomeAssistantWebSocketClient | None, dict[str, Any] | None]:

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/tools_addons.py

@@ -38,6 +38,7 @@ from .helpers import (
     get_connected_ws_client,
     log_tool_usage,
     raise_tool_error,
+    validate_identifier_not_empty,
 )
 from .util_helpers import ANSI_ESCAPE_RE
 
@@ -1208,14 +1209,16 @@ def _apply_array_ops(
                     )
                 )
             new_id = new_item[id_field]
-            if new_id is None or new_id == "":
+            if new_id is None or (isinstance(new_id, str) and not new_id.strip()):
                 # Items missing the id field have `dict.get(id_field) == None`
-                # by default, so allowing None/"" ids would let later patch /
-                # delete ops match unrelated items.
+                # by default, so allowing None/""/whitespace-only ids would
+                # let later patch / delete ops match unrelated items.
+                # Non-string ids (e.g. integers) stay valid by design — see
+                # ``test_add_with_integer_zero_id_is_accepted``.
                 raise_tool_error(
                     create_validation_error(
                         f"array_patch add op #{index} item {id_field!r} cannot be "
-                        "None or an empty string",
+                        "None, empty, or whitespace-only",
                         parameter=f"array_patch.operations[{index}].item.{id_field}",
                     )
                 )
@@ -1954,6 +1957,18 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
             ha_manage_addon(slug="...", path="/api/state",
                             request_headers={"Accept": "text/plain"})
         """
+        # Empty/whitespace slug would propagate to every dispatch arm
+        # (Supervisor API, ingress proxy, websocket bridge) and surface as a
+        # misleading "addon not found" or 404 from the Supervisor. Reject
+        # up-front so the caller learns the slug was unusable before any
+        # backend call.
+        validate_identifier_not_empty(
+            slug,
+            "slug",
+            suggestions=[
+                "Use ha_get_addon() to discover installed add-on slugs",
+            ],
+        )
         # Build config payload from provided config parameters
         config_data: dict[str, Any] = {}
         if options:

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/tools_areas.py

@@ -18,6 +18,7 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    validate_identifier_not_empty,
 )
 from .util_helpers import parse_string_list_param
 
@@ -465,19 +466,19 @@ class AreaTools:
                     ],
                 ))
 
-            # Reject empty-string id explicitly. `if id:` below treats it as
-            # falsy and would silently route to the create branch — destructive
-            # if the caller intended an update.
-            if id == "":
-                raise_tool_error(create_error_response(
-                    ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    "id must be a non-empty string when provided (omit to create)",
-                    context={"kind": kind},
+            # ``None`` stays the documented "create-new" sentinel; explicit
+            # empty/whitespace would silently route to the ``if id:`` create
+            # branch below and lose update intent.
+            if id is not None:
+                validate_identifier_not_empty(
+                    id,
+                    "id",
                     suggestions=[
                         "Omit id entirely to create a new entry",
                         "Pass a real area_id/floor_id to update an existing entry",
                     ],
-                ))
+                    context={"kind": kind},
+                )
 
             if kind == "area":
                 if id:
@@ -486,13 +487,15 @@ class AreaTools:
                     )
                     operation = "update"
                 else:
-                    if not name:
-                        raise_tool_error(create_error_response(
-                            ErrorCode.VALIDATION_MISSING_PARAMETER,
-                            "name is required when creating a new area",
-                            context={"operation": "create_area"},
-                            suggestions=["Provide a name for the new area"],
-                        ))
+                    # Reassignment narrows ``name`` from ``str | None`` to
+                    # ``str`` for the build-message call below.
+                    name = validate_identifier_not_empty(
+                        name,
+                        "name",
+                        message="name is required when creating a new area",
+                        context={"operation": "create_area"},
+                        suggestions=["Provide a non-empty name for the new area"],
+                    )
                     message = self._build_area_create_message(
                         name, floor_id, icon, parsed_aliases, picture,
                     )
@@ -506,13 +509,13 @@ class AreaTools:
                     )
                     operation = "update"
                 else:
-                    if not name:
-                        raise_tool_error(create_error_response(
-                            ErrorCode.VALIDATION_MISSING_PARAMETER,
-                            "name is required when creating a new floor",
-                            context={"operation": "create_floor"},
-                            suggestions=["Provide a name for the new floor"],
-                        ))
+                    name = validate_identifier_not_empty(
+                        name,
+                        "name",
+                        message="name is required when creating a new floor",
+                        context={"operation": "create_floor"},
+                        suggestions=["Provide a non-empty name for the new floor"],
+                    )
                     message = self._build_floor_create_message(
                         name, level, icon, parsed_aliases,
                     )
@@ -590,6 +593,15 @@ class AreaTools:
         registry = "area_registry" if kind == "area" else "floor_registry"
         id_key = "area_id" if kind == "area" else "floor_id"
         try:
+            # Empty/whitespace would surface as a misleading HA delete-failure.
+            validate_identifier_not_empty(
+                id,
+                "id",
+                suggestions=[
+                    f"Pass a valid {id_key} (use ha_list_floors_areas() to list)",
+                ],
+                context={"action": "remove", "kind": kind},
+            )
             message: dict[str, Any] = {
                 "type": f"config/{registry}/delete",
                 id_key: id,

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/tools_calendar.py

@@ -21,6 +21,7 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    validate_identifier_not_empty,
 )
 
 logger = logging.getLogger(__name__)
@@ -354,6 +355,18 @@ class CalendarTools:
                     ],
                 ))
 
+            # entity_id format-check above does not cover the ``uid`` parameter.
+            # Empty/whitespace uid would flow through to ``calendar.delete_event``
+            # and HA returns a misleading "event not found".
+            validate_identifier_not_empty(
+                uid,
+                "uid",
+                suggestions=[
+                    "Use ha_config_get_calendar_events() to list events and obtain valid UIDs",
+                ],
+                context={"entity_id": entity_id},
+            )
+
             # Build service data
             service_data: dict[str, Any] = {
                 "entity_id": entity_id,

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/tools_categories.py

@@ -21,6 +21,7 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    validate_identifier_not_empty,
 )
 
 logger = logging.getLogger(__name__)
@@ -76,6 +77,18 @@ class CategoryTools:
         Use ha_set_entity(categories={"automation": "category_id"}) to assign categories to entities.
         """
         try:
+            # ``None`` stays the documented "list-all" sentinel; explicit
+            # empty/whitespace is rejected by ``validate_identifier_not_empty``.
+            if category_id is not None:
+                validate_identifier_not_empty(
+                    category_id,
+                    "category_id",
+                    suggestions=[
+                        "Omit category_id to list all categories for the scope",
+                        "Pass a valid non-empty category_id",
+                    ],
+                    context={"action": "get", "scope": scope},
+                )
             message: dict[str, Any] = {
                 "type": "config/category_registry/list",
                 "scope": scope,
@@ -194,6 +207,19 @@ class CategoryTools:
         After creating a category, use ha_set_entity(categories={"automation": "category_id"}) to assign it.
         """
         try:
+            # ``None`` stays the documented "create-new" sentinel; explicit
+            # empty/whitespace is rejected so the create/update discriminator
+            # below cannot silently route an intended update to create.
+            if category_id is not None:
+                validate_identifier_not_empty(
+                    category_id,
+                    "category_id",
+                    suggestions=[
+                        "Omit category_id entirely to create a new category",
+                        "Pass a valid category_id to update an existing category",
+                    ],
+                    context={"action": "set", "scope": scope, "name": name},
+                )
             action = "update" if category_id else "create"
 
             message: dict[str, Any] = {
@@ -282,6 +308,15 @@ class CategoryTools:
         This action cannot be undone.
         """
         try:
+            # Empty/whitespace would surface as a misleading HA delete-failure.
+            validate_identifier_not_empty(
+                category_id,
+                "category_id",
+                suggestions=[
+                    "Pass a valid category_id (use ha_config_get_category() to list)",
+                ],
+                context={"action": "remove", "scope": scope},
+            )
             message: dict[str, Any] = {
                 "type": "config/category_registry/delete",
                 "scope": scope,

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/tools_config_automations.py

@@ -33,6 +33,7 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    validate_identifier_not_empty,
 )
 from .reference_validator import validate_config_references
 from .util_helpers import (
@@ -965,6 +966,15 @@ class AutomationConfigTools:
         **WARNING:** Deleting an automation removes it permanently from your Home Assistant configuration.
         """
         try:
+            # Empty/whitespace would surface as a misleading HA delete-failure.
+            validate_identifier_not_empty(
+                identifier,
+                "identifier",
+                suggestions=[
+                    "Use ha_search_entities(domain_filter='automation') to find existing automations"
+                ],
+                context={"operation": "remove_automation"},
+            )
             # Resolve entity_id for wait verification (identifier may be a unique_id)
             entity_id_for_wait = await self._resolve_automation_entity_id(identifier)
             if not entity_id_for_wait:

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/tools_config_helpers.py

@@ -16,7 +16,12 @@ from pydantic import AliasChoices, Field
 
 from ..client.rest_client import HomeAssistantAPIError
 from ..errors import ErrorCode, create_error_response
-from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
+from .helpers import (
+    exception_to_structured_error,
+    log_tool_usage,
+    raise_tool_error,
+    validate_identifier_not_empty,
+)
 from .tools_config_entry_flow import (
     FLOW_HELPER_TYPES,
     create_flow_helper,
@@ -1223,11 +1228,12 @@ async def _check_name_collision(
     duplicate entity instead of updating the original. Detect and reject before
     we send the create message, pointing the caller at the existing helper_id.
 
-    Empty / missing `name` is left to the existing name-required check downstream
-    so the user sees the standard "name is required" error rather than a
-    spurious collision miss.
+    Empty / missing / whitespace-only `name` is left to the existing
+    name-required check downstream so the user sees the standard "name is
+    required" error rather than a spurious collision miss (or a wasted WS
+    round-trip on a name the validator is about to reject anyway).
     """
-    if not name:
+    if not name or not name.strip():
         return
 
     target_slug = _slugify_helper_name(name)
@@ -1563,6 +1569,22 @@ async def _handle_flow_helper(
     is consistent has already happened upstream in ha_config_set_helper.
     """
     if action is None:
+        # Defence in depth: when reached via the legacy implicit-action
+        # path, an empty/whitespace ``helper_id`` would otherwise be falsy
+        # and silently route to ``create`` — same destructive intent-loss
+        # class as the registry-metadata twins. ``None`` stays the
+        # documented "create-new" sentinel.
+        if helper_id is not None:
+            validate_identifier_not_empty(
+                helper_id,
+                "helper_id",
+                suggestions=[
+                    "Omit helper_id entirely to create a new flow helper",
+                    "Pass a valid helper_id to update an existing one",
+                    "Or pass action='create' / action='update' explicitly",
+                ],
+                context={"helper_type": helper_type},
+            )
         action = "update" if helper_id else "create"
 
     # Normalize empty string to None, matching ha_config_set_helper's treatment
@@ -1618,7 +1640,7 @@ async def _handle_flow_helper(
     # caller-supplied `name` (you cannot rename a flow helper through its
     # options flow). Strip `name` from config_dict and emit a warning so the
     # caller learns their attempted rename was a no-op.
-    if action == "create" and name and "name" not in config_dict:
+    if action == "create" and name and name.strip() and "name" not in config_dict:
         schema_fields = await get_user_step_field_names(client, helper_type)
         if schema_fields is None or "name" in schema_fields:
             config_dict["name"] = name
@@ -1661,7 +1683,12 @@ async def _handle_flow_helper(
         # Some helpers (switch_as_x) deliberately don't have `name` injected into
         # config_dict because their schema rejects it — but the tool still
         # requires `name` to be supplied so callers fail fast and consistently.
-        if not (name or config_dict.get("name")):
+        # Reject whitespace-only too (``" "`` is truthy in Python) so the
+        # flow-helper create gate is coherent with the simple-helper twin.
+        config_name = config_dict.get("name")
+        config_name_ok = isinstance(config_name, str) and bool(config_name.strip())
+        name_ok = name is not None and bool(name.strip())
+        if not (name_ok or config_name_ok):
             raise_tool_error(
                 create_error_response(
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
@@ -2373,9 +2400,45 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                             ],
                         )
                     )
+                # Explicit-action update path: helper_id was confirmed non-None
+                # above; close the whitespace gap before the FLOW dispatch
+                # below (``if helper_type in FLOW_HELPER_TYPES: return await
+                # _handle_flow_helper(...)``). The simple-path whitespace twin
+                # inside the ``elif action == "update":`` branch fires after
+                # the FLOW dispatch returns and so is unreachable for flow
+                # helpers; without this guard, ``helper_id="   "`` would reach
+                # ``update_flow_helper`` and surface as a misleading "entry
+                # not found" from HA.
+                if action == "update" and helper_id is not None:
+                    validate_identifier_not_empty(
+                        helper_id,
+                        "helper_id",
+                        suggestions=[
+                            "Pass a valid helper_id to identify the helper to update",
+                            "Or omit helper_id and pass action='create' to create a new helper",
+                        ],
+                        context={"helper_type": helper_type, "action": action},
+                    )
             else:
                 # Implicit discriminator (back-compat). Pass action='create'
                 # or action='update' explicitly to avoid the inference.
+                # Reject empty/whitespace helper_id up front: ``bool("")`` is
+                # False, so without this gate ``helper_id=""`` silently routes
+                # to ``create`` even when the caller's intent was ``update``,
+                # producing a destructive intent-loss class identical to the
+                # one closed for labels/categories. ``None`` stays the
+                # documented "create-new" sentinel.
+                if helper_id is not None:
+                    validate_identifier_not_empty(
+                        helper_id,
+                        "helper_id",
+                        suggestions=[
+                            "Omit helper_id entirely to create a new helper",
+                            "Pass a valid helper_id to update an existing helper",
+                            "Or pass action='create' / action='update' explicitly to declare intent",
+                        ],
+                        context={"helper_type": helper_type},
+                    )
                 action = "update" if helper_id else "create"
 
             # Bug 4b/7c/10/14 (issue #1150): reject typed params that don't apply
@@ -2496,7 +2559,9 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 )
 
             if action == "create":
-                if not name:
+                # ``bool(" ")`` is True, so plain ``if not name`` would let
+                # whitespace-only names through to a downstream HA error.
+                if not name or not name.strip():
                     raise_tool_error(
                         create_error_response(
                             ErrorCode.VALIDATION_INVALID_PARAMETER,
@@ -2839,7 +2904,9 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     )
 
             elif action == "update":
-                if not helper_id:
+                # Same whitespace-upgrade rationale as the create-name check
+                # above — ``if not helper_id`` would let ``"   "`` through.
+                if not helper_id or not helper_id.strip():
                     raise_tool_error(
                         create_error_response(
                             ErrorCode.VALIDATION_INVALID_PARAMETER,

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/tools_config_scripts.py

@@ -28,6 +28,7 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    validate_identifier_not_empty,
 )
 from .reference_validator import validate_config_references
 from .util_helpers import (
@@ -619,6 +620,15 @@ class ConfigScriptTools:
         **WARNING:** Deleting a script that is used by automations may cause those automations to fail.
         """
         try:
+            # Empty/whitespace would surface as a misleading HA delete-failure.
+            validate_identifier_not_empty(
+                script_id,
+                "script_id",
+                suggestions=[
+                    "Use ha_search_entities(domain_filter='script') to find existing script_ids"
+                ],
+                context={"operation": "remove_script"},
+            )
             result = await self._client.delete_script_config(script_id)
 
             # Wait for script to be removed

{ha_mcp_dev-7.5.0.dev525 → ha_mcp_dev-7.5.0.dev527}/src/ha_mcp/tools/tools_energy.py

@@ -41,6 +41,7 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
+    validate_identifier_not_empty,
 )
 
 logger = logging.getLogger(__name__)
@@ -1011,6 +1012,18 @@ class EnergyTools:
                     ],
                 )
             )
+        # Empty/whitespace stat_consumption would write a ``{"stat_consumption": ""}``
+        # entry to energy prefs storage — a phantom row keyed on an empty
+        # sensor reference. Same multi-modal-destructive class as
+        # ``ha_manage_addon`` slug guard.
+        validate_identifier_not_empty(
+            stat_consumption,
+            "stat_consumption",
+            suggestions=[
+                "Pass stat_consumption='sensor.<your_device_energy>'",
+            ],
+            context={"mode": "add_device"},
+        )
 
         target_key = "device_consumption_water" if water else "device_consumption"
 
@@ -1049,6 +1062,17 @@ class EnergyTools:
                     ],
                 )
             )
+        # Empty/whitespace stat_consumption would search the prefs storage for
+        # an empty match (always missing) and surface as a misleading
+        # "Device with stat_consumption='' not found".
+        validate_identifier_not_empty(
+            stat_consumption,
+            "stat_consumption",
+            suggestions=[
+                "Pass stat_consumption='sensor.<existing_device_energy>'",
+            ],
+            context={"mode": "remove_device"},
+        )
 
         target_key = "device_consumption_water" if water else "device_consumption"