ha-mcp-dev 7.5.0.dev524__tar.gz → 7.5.0.dev526__tar.gz

{ha_mcp_dev-7.5.0.dev524/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev526}/PKG-INFO

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

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

@@ -548,7 +548,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "utility_meter, derivative, statistics, trend, threshold, "
             "filter, switch_as_x, etc.) cannot be listed through this "
             "tool — use ha_search_entities or ha_deep_search.\n\n"
-            "For per-type schemas, see ha_get_helper_schema and "
+            "For per-type schemas and decision guidance, see "
             "ha_get_skill_guide."
         ),
         "ha_config_set_helper": (
@@ -558,10 +558,10 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "flow-based types (template, group, utility_meter, "
             "derivative, statistics, trend, threshold, filter, "
             "switch_as_x, and others).\n\n"
-            "For per-type config schemas, call "
-            "ha_get_helper_schema(helper_type) first. For decision "
-            "matrix and worked examples (which helper type for which "
-            "use case), see ha_get_skill_guide."
+            "Field set is delivered as `data_schema` on the first "
+            "validation error — submit once and self-correct. For "
+            "decision matrix and worked examples (which helper type "
+            "for which use case), see ha_get_skill_guide."
         ),
         "ha_config_get_dashboard": (
             "Get Home Assistant dashboard info (list mode, search "

{ha_mcp_dev-7.5.0.dev524 → ha_mcp_dev-7.5.0.dev526}/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.dev524 → ha_mcp_dev-7.5.0.dev526}/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.dev524 → ha_mcp_dev-7.5.0.dev526}/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.dev524 → ha_mcp_dev-7.5.0.dev526}/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.dev524 → ha_mcp_dev-7.5.0.dev526}/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.dev524 → ha_mcp_dev-7.5.0.dev526}/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: