ha-mcp-dev 7.2.0.dev319__tar.gz → 7.2.0.dev321__tar.gz

{ha_mcp_dev-7.2.0.dev319/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.2.0.dev321}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.2.0.dev319"
+version = "7.2.0.dev321"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -175,6 +175,7 @@ dev = [
     "pytest-xdist>=3.8.0",
     "requests>=2.25.0",
     "lefthook>=1.10.0",
+    "ruamel.yaml>=0.18.0",
     "ruff>=0.12.12",
     "testcontainers>=4.13.0",
     "ast-grep-cli>=0.42.0",

{ha_mcp_dev-7.2.0.dev319 → ha_mcp_dev-7.2.0.dev321}/src/ha_mcp/tools/tools_config_automations.py

@@ -24,7 +24,9 @@ from .best_practice_checker import (
 )
 from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import (
+    apply_entity_category,
     coerce_bool_param,
+    fetch_entity_category,
     parse_json_param,
     wait_for_entity_registered,
     wait_for_entity_removed,
@@ -205,6 +207,27 @@ def _strip_empty_automation_fields(config: dict[str, Any]) -> dict[str, Any]:
 def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register Home Assistant automation configuration tools."""
 
+    async def _resolve_automation_entity_id(identifier: str) -> str | None:
+        """Resolve an automation identifier to its entity_id.
+
+        If identifier is already an entity_id (starts with "automation."),
+        returns it directly. Otherwise, searches states to find the entity
+        whose unique_id matches the identifier.
+        """
+        if identifier.startswith("automation."):
+            return identifier
+        try:
+            states = await client.get_states()
+            for state in states:
+                if (
+                    state.get("entity_id", "").startswith("automation.")
+                    and state.get("attributes", {}).get("id") == identifier
+                ):
+                    return str(state["entity_id"])
+        except Exception as e:
+            logger.debug(f"Failed to resolve entity_id for automation {identifier}: {e}")
+        return None
+
     @mcp.tool(
         tags={"Automations"},
         annotations={
@@ -237,6 +260,14 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
             config_result = await client.get_automation_config(identifier)
             # Normalize config for round-trip compatibility (GET → SET)
             normalized_config = _normalize_config_for_roundtrip(config_result)
+
+            # Resolve entity_id and fetch category from entity registry
+            entity_id = await _resolve_automation_entity_id(identifier)
+            if entity_id:
+                cat_id = await fetch_entity_category(client, entity_id, "automation")
+                if cat_id:
+                    normalized_config["category"] = cat_id
+
             return {
                 "success": True,
                 "action": "get",
@@ -296,6 +327,13 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                 default=None,
             ),
         ] = None,
+        category: Annotated[
+            str | None,
+            Field(
+                description="Category ID to assign to this automation. Use ha_config_get_category(scope='automation') to list available categories, or ha_config_set_category() to create one.",
+                default=None,
+            ),
+        ] = None,
         wait: Annotated[
             bool | str,
             Field(
@@ -327,6 +365,7 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
 
         OPTIONAL CONFIG FIELDS (Regular Automations):
         - description: Detailed description of the user's intent (RECOMMENDED: helps safely modify implementation later)
+        - category: Category ID for organization (use ha_config_get_category to list, ha_config_set_category to create)
         - condition: Additional conditions that must be met
         - mode: 'single' (default), 'restart', 'queued', 'parallel'
         - max: Maximum concurrent executions (for queued/parallel modes)
@@ -444,6 +483,11 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
 
             config_dict = cast(dict[str, Any], parsed_config)
 
+            # Extract category before sending to HA REST API (which rejects unknown keys).
+            # Parameter takes precedence over config dict value.
+            config_category = config_dict.pop("category", None)
+            effective_category = category if category is not None else config_category
+
             # Normalize field names (triggers -> trigger, actions -> action, etc.)
             config_dict = _normalize_automation_config(config_dict)
 
@@ -499,6 +543,9 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
             # Wait for automation to be queryable
             wait_bool = coerce_bool_param(wait, "wait", default=True)
             entity_id = result.get("entity_id")
+            # On updates, entity_id may not be in the result — derive from identifier
+            if not entity_id and identifier and identifier.startswith("automation."):
+                entity_id = identifier
             if wait_bool and entity_id:
                 try:
                     registered = await wait_for_entity_registered(client, entity_id)
@@ -507,6 +554,12 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                 except Exception as e:
                     result["warning"] = f"Automation created but verification failed: {e}"
 
+            # Apply category to entity registry if provided
+            if effective_category and entity_id:
+                await apply_entity_category(
+                    client, entity_id, effective_category, "automation", result, "automation"
+                )
+
             if bp_warnings:
                 result["best_practice_warnings"] = bp_warnings
 
@@ -572,20 +625,11 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
         """
         try:
             # Resolve entity_id for wait verification (identifier may be a unique_id)
-            entity_id_for_wait: str | None = None
-            if identifier.startswith("automation."):
-                entity_id_for_wait = identifier
-            else:
-                # Try to find entity_id by matching unique_id in automation states
-                try:
-                    states = await client.get_states()
-                    for state in states:
-                        eid = state.get("entity_id", "")
-                        if eid.startswith("automation.") and state.get("attributes", {}).get("id") == identifier:
-                            entity_id_for_wait = eid
-                            break
-                except Exception as e:
-                    logger.warning(f"Could not resolve unique_id '{identifier}' to entity_id: {e} — wait verification will be skipped")
+            entity_id_for_wait = await _resolve_automation_entity_id(identifier)
+            if not entity_id_for_wait:
+                logger.warning(
+                    f"Could not resolve unique_id '{identifier}' to entity_id — wait verification will be skipped"
+                )
 
             result = await client.delete_automation_config(identifier)
 

{ha_mcp_dev-7.2.0.dev319 → ha_mcp_dev-7.2.0.dev321}/src/ha_mcp/tools/tools_config_helpers.py

@@ -16,6 +16,7 @@ from pydantic import Field
 from ..errors import ErrorCode, create_error_response
 from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import (
+    apply_entity_category,
     coerce_bool_param,
     parse_string_list_param,
     wait_for_entity_registered,
@@ -405,6 +406,13 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 default=None,
             ),
         ] = None,
+        category: Annotated[
+            str | None,
+            Field(
+                description="Category ID to assign to this helper. Use ha_config_get_category(scope='helpers') to list available categories, or ha_config_set_category() to create one.",
+                default=None,
+            ),
+        ] = None,
         wait: Annotated[
             bool | str,
             Field(
@@ -632,6 +640,9 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 if result.get("success"):
                     helper_data = result.get("result", {})
                     entity_id = helper_data.get("entity_id")
+                    # Some helper types don't return entity_id — derive from result id
+                    if not entity_id and helper_data.get("id"):
+                        entity_id = f"{helper_type}.{helper_data['id']}"
 
                     # Wait for entity to be properly registered before proceeding
                     wait_bool = coerce_bool_param(wait, "wait", default=True)
@@ -660,6 +671,18 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                         if update_result.get("success"):
                             helper_data["area_id"] = area_id
                             helper_data["labels"] = labels
+                        else:
+                            error_detail = update_result.get("error", {})
+                            error_msg = error_detail.get("message", "Unknown error") if isinstance(error_detail, dict) else str(error_detail)
+                            helper_data["warning"] = (
+                                f"Helper created but entity registry update failed: {error_msg}"
+                            )
+
+                    # Apply category via shared helper (consistent with automations/scripts)
+                    if category and entity_id:
+                        await apply_entity_category(
+                            client, entity_id, category, "helpers", helper_data, "helper"
+                        )
 
                     return {
                         "success": True,
@@ -890,7 +913,20 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                             registry_update["area_id"] = area_id
                         if labels:
                             registry_update["labels"] = labels
-                        await client.send_websocket_message(registry_update)
+                        reg_result = await client.send_websocket_message(registry_update)
+                        if not reg_result.get("success"):
+                            error_detail = reg_result.get("error", {})
+                            error_msg = error_detail.get("message", "Unknown error") if isinstance(error_detail, dict) else str(error_detail)
+                            logger.warning(f"Entity registry update failed for {entity_id}: {error_msg}")
+                            updated_data["warning"] = (
+                                f"Config updated but entity registry update failed: {error_msg}"
+                            )
+
+                    # Apply category via shared helper
+                    if category:
+                        await apply_entity_category(
+                            client, entity_id, category, "helpers", updated_data, "helper"
+                        )
 
                 else:
                     # Standard helpers: entity registry update only
@@ -919,6 +955,12 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                             context={"helper_type": helper_type, "entity_id": entity_id},
                         ))
 
+                    # Apply category via shared helper
+                    if category:
+                        await apply_entity_category(
+                            client, entity_id, category, "helpers", updated_data, "helper"
+                        )
+
                 # Wait for entity to reflect the update
                 wait_bool = coerce_bool_param(wait, "wait", default=True)
                 response: dict[str, Any] = {

{ha_mcp_dev-7.2.0.dev319 → ha_mcp_dev-7.2.0.dev321}/src/ha_mcp/tools/tools_config_scripts.py

@@ -20,7 +20,9 @@ from .best_practice_checker import (
 )
 from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import (
+    apply_entity_category,
     coerce_bool_param,
+    fetch_entity_category,
     parse_json_param,
     wait_for_entity_registered,
     wait_for_entity_removed,
@@ -82,6 +84,13 @@ def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         """
         try:
             config_result = await client.get_script_config(script_id)
+
+            # Fetch category from entity registry (best-effort)
+            entity_id = f"script.{script_id}"
+            cat_id = await fetch_entity_category(client, entity_id, "script")
+            if cat_id:
+                config_result["category"] = cat_id
+
             return {
                 "success": True,
                 "action": "get",
@@ -119,6 +128,13 @@ def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 description="Script configuration dictionary. Must include EITHER 'sequence' (for regular scripts) OR 'use_blueprint' (for blueprint-based scripts). Optional fields: 'alias', 'description', 'icon', 'mode', 'max', 'fields'"
             ),
         ],
+        category: Annotated[
+            str | None,
+            Field(
+                description="Category ID to assign to this script. Use ha_config_get_category(scope='script') to list available categories, or ha_config_set_category() to create one.",
+                default=None,
+            ),
+        ] = None,
         wait: Annotated[
             bool | str,
             Field(
@@ -259,6 +275,11 @@ def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
             config_dict = cast(dict[str, Any], parsed_config)
 
+            # Extract category before sending to HA REST API (which rejects unknown keys).
+            # Parameter takes precedence over config dict value.
+            config_category = config_dict.pop("category", None)
+            effective_category = category if category is not None else config_category
+
             # Validate required fields based on script type
             # Blueprint scripts only need use_blueprint, regular scripts need sequence
             if "use_blueprint" in config_dict:
@@ -289,6 +310,12 @@ def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 except Exception as e:
                     result["warning"] = f"Script created but verification failed: {e}"
 
+            # Apply category to entity registry if provided
+            if effective_category and entity_id:
+                await apply_entity_category(
+                    client, entity_id, effective_category, "script", result, "script"
+                )
+
             if bp_warnings:
                 result["best_practice_warnings"] = bp_warnings
 

{ha_mcp_dev-7.2.0.dev319 → ha_mcp_dev-7.2.0.dev321}/src/ha_mcp/tools/tools_yaml_config.py

@@ -123,8 +123,8 @@ def register_yaml_config_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         a full HA restart ('restart_required'). Only template, mqtt, and
         group support reload ('reload_available' with 'reload_service').
 
-        Note: YAML comments are not preserved after editing. The backup
-        retains the original file with comments intact.
+        YAML comments and Home Assistant tags (!include, !secret, etc.)
+        are preserved through edits.
         """
         try:
             # Validate action

{ha_mcp_dev-7.2.0.dev319 → ha_mcp_dev-7.2.0.dev321}/src/ha_mcp/tools/util_helpers.py

@@ -426,3 +426,72 @@ async def wait_for_state_change(
 
     logger.warning(f"Entity {entity_id} state did not change within {timeout}s")
     return None
+
+
+async def fetch_entity_category(
+    client: Any, entity_id: str, scope: str
+) -> str | None:
+    """Fetch a category ID for an entity from the entity registry.
+
+    Args:
+        client: HomeAssistantClient instance
+        entity_id: Entity to look up (e.g., 'automation.morning_routine')
+        scope: Category scope (e.g., 'automation', 'script', 'helpers')
+
+    Returns:
+        Category ID string if set, None otherwise
+    """
+    try:
+        result = await client.send_websocket_message(
+            {"type": "config/entity_registry/get", "entity_id": entity_id}
+        )
+        if result.get("success"):
+            categories = result.get("result", {}).get("categories", {})
+            cat_id = categories.get(scope)
+            return str(cat_id) if cat_id is not None else None
+    except Exception as e:
+        logger.warning(f"Failed to fetch category for {entity_id}: {e}")
+    return None
+
+
+async def apply_entity_category(
+    client: Any,
+    entity_id: str,
+    category: str,
+    scope: str,
+    result_dict: dict[str, Any],
+    entity_type: str = "entity",
+) -> None:
+    """Apply a category to an entity via the entity registry.
+
+    Updates result_dict in-place with 'category' on success or
+    'category_warning' on failure.
+
+    Args:
+        client: HomeAssistantClient instance
+        entity_id: Entity to update
+        category: Category ID to assign
+        scope: Category scope (e.g., 'automation', 'script')
+        result_dict: Tool result dict to update with category status
+        entity_type: Human-readable type for warning messages
+    """
+    try:
+        ws_result = await client.send_websocket_message({
+            "type": "config/entity_registry/update",
+            "entity_id": entity_id,
+            "categories": {scope: category},
+        })
+        if ws_result.get("success"):
+            result_dict["category"] = category
+        else:
+            error_detail = ws_result.get("error", {})
+            error_msg = error_detail.get("message", "Unknown error") if isinstance(error_detail, dict) else str(error_detail)
+            logger.warning(f"Failed to set category for {entity_id}: {error_msg}")
+            result_dict["category_warning"] = (
+                f"{entity_type.capitalize()} saved but failed to set category: {error_msg}"
+            )
+    except Exception as e:
+        logger.warning(f"Failed to set category for {entity_id}: {e}")
+        result_dict["category_warning"] = (
+            f"{entity_type.capitalize()} saved but failed to set category: {e}"
+        )

{ha_mcp_dev-7.2.0.dev319 → ha_mcp_dev-7.2.0.dev321/src/ha_mcp_dev.egg-info}/PKG-INFO

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