ha-mcp-dev 7.3.0.dev403__tar.gz → 7.4.0.dev406__tar.gz

{ha_mcp_dev-7.3.0.dev403/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.0.dev406}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.3.0.dev403
+Version: 7.4.0.dev406
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -37,7 +37,7 @@ Dynamic: license-file
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-87-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-86-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>
@@ -180,7 +180,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (87 tools)</b></summary>
+<summary><b>Complete Tool List (86 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -197,9 +197,9 @@ 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_remove_helper`, `ha_config_set_helper`, `ha_get_helper_schema` |
+| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations`, `ha_get_helper_schema` |
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
-| **Integrations** | `ha_delete_config_entry`, `ha_get_integration`, `ha_set_integration_enabled` |
+| **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` |
 | **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |
 | **Search & Discovery** | `ha_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_search_entities` |

{ha_mcp_dev-7.3.0.dev403 → ha_mcp_dev-7.4.0.dev406}/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-87-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-86-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 (87 tools)</b></summary>
+<summary><b>Complete Tool List (86 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -168,9 +168,9 @@ 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_remove_helper`, `ha_config_set_helper`, `ha_get_helper_schema` |
+| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations`, `ha_get_helper_schema` |
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
-| **Integrations** | `ha_delete_config_entry`, `ha_get_integration`, `ha_set_integration_enabled` |
+| **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` |
 | **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |
 | **Search & Discovery** | `ha_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_search_entities` |

{ha_mcp_dev-7.3.0.dev403 → ha_mcp_dev-7.4.0.dev406}/pyproject.toml

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

@@ -308,6 +308,13 @@ def exception_to_structured_error(
     error_response = _classify_exception(error, error_str, error_msg, context)
 
     if suggestions and "error" in error_response and isinstance(error_response["error"], dict):
+        # Set both `suggestion` (singular, first item) and `suggestions`
+        # (plural, full list). create_error_response (errors.py) sets the
+        # singular key; existing tests for exception_to_structured_error
+        # rely on the plural key being present even for single-item caller
+        # suggestions. Setting both keeps response consumers on both code
+        # paths working.
+        error_response["error"]["suggestion"] = suggestions[0]
         error_response["error"]["suggestions"] = suggestions
 
     # Append macOS-specific hints for connection failures (after all other processing

{ha_mcp_dev-7.3.0.dev403 → ha_mcp_dev-7.4.0.dev406}/src/ha_mcp/tools/tools_config_helpers.py

@@ -26,7 +26,6 @@ from .util_helpers import (
     parse_json_param,
     parse_string_list_param,
     wait_for_entity_registered,
-    wait_for_entity_removed,
 )
 
 # Simple helper types — managed via {type}/create and {type}/update WebSocket APIs
@@ -1668,269 +1667,3 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     "Ensure required parameters are provided for the helper type",
                 ],
             )
-
-    @mcp.tool(
-        tags={"Helper Entities"},
-        annotations={
-            "destructiveHint": True,
-            "idempotentHint": True,
-            "title": "Remove Helper",
-        },
-    )
-    @log_tool_usage
-    async def ha_config_remove_helper(
-        helper_type: Annotated[
-            Literal[
-                "input_button",
-                "input_boolean",
-                "input_select",
-                "input_number",
-                "input_text",
-                "input_datetime",
-                "counter",
-                "timer",
-                "schedule",
-                "zone",
-                "person",
-                "tag",
-            ],
-            Field(description="Type of helper entity to delete"),
-        ],
-        helper_id: Annotated[
-            str,
-            Field(
-                description="Helper ID to delete (e.g., 'my_button' or 'input_button.my_button')"
-            ),
-        ],
-        wait: Annotated[
-            bool | str,
-            Field(
-                description="Wait for helper entity to be fully removed before returning. Default: True.",
-                default=True,
-            ),
-        ] = True,
-    ) -> dict[str, Any]:
-        """
-        Delete a Home Assistant helper entity.
-
-        SUPPORTED HELPER TYPES:
-        - input_button, input_boolean, input_select, input_number, input_text, input_datetime
-        - counter, timer, schedule, zone, person, tag
-
-        For flow-based helper types (template, group, utility_meter, derivative,
-        min_max, threshold, integration, statistics, trend, random, filter, tod,
-        generic_thermostat, switch_as_x, generic_hygrostat) use ha_delete_config_entry.
-
-        EXAMPLES:
-        - Delete button: ha_config_remove_helper("input_button", "my_button")
-        - Delete counter: ha_config_remove_helper("counter", "my_counter")
-        - Delete timer: ha_config_remove_helper("timer", "my_timer")
-        - Delete schedule: ha_config_remove_helper("schedule", "work_hours")
-
-        **WARNING:** Deleting a helper that is used by automations or scripts may cause those automations/scripts to fail.
-        Use ha_search_entities() to verify the helper exists before attempting to delete it.
-        """
-        try:
-            # Convert helper_id to full entity_id if needed
-            entity_id = (
-                helper_id
-                if helper_id.startswith(helper_type)
-                else f"{helper_type}.{helper_id}"
-            )
-
-            # Try to get unique_id with retry logic to handle race conditions
-            unique_id = None
-            registry_result = None
-            max_retries = 3
-
-            for attempt in range(max_retries):
-                logger.info(
-                    f"Getting entity registry for: {entity_id} (attempt {attempt + 1}/{max_retries})"
-                )
-
-                # Check if entity exists via state API first (faster check)
-                try:
-                    state_check = await client.get_entity_state(entity_id)
-                    if not state_check:
-                        # Entity doesn't exist in state, wait a bit for registration
-                        if attempt < max_retries - 1:
-                            wait_time = 0.5 * (
-                                2**attempt
-                            )  # Exponential backoff: 0.5s, 1s, 2s
-                            logger.debug(
-                                f"Entity {entity_id} not found in state, waiting {wait_time}s before retry..."
-                            )
-                            await asyncio.sleep(wait_time)
-                            continue
-                except Exception as e:
-                    logger.debug(f"State check failed for {entity_id}: {e}")
-
-                # Try registry lookup
-                registry_msg: dict[str, Any] = {
-                    "type": "config/entity_registry/get",
-                    "entity_id": entity_id,
-                }
-
-                try:
-                    registry_result = await client.send_websocket_message(registry_msg)
-
-                    if registry_result.get("success"):
-                        entity_entry = registry_result.get("result", {})
-                        unique_id = entity_entry.get("unique_id")
-                        if unique_id:
-                            logger.info(f"Found unique_id: {unique_id} for {entity_id}")
-                            break
-
-                    # If registry lookup failed but we haven't exhausted retries, wait and try again
-                    if attempt < max_retries - 1:
-                        wait_time = 0.5 * (2**attempt)  # Exponential backoff
-                        logger.debug(
-                            f"Registry lookup failed for {entity_id}, waiting {wait_time}s before retry..."
-                        )
-                        await asyncio.sleep(wait_time)
-
-                except Exception as e:
-                    logger.warning(f"Registry lookup attempt {attempt + 1} failed: {e}")
-                    if attempt < max_retries - 1:
-                        wait_time = 0.5 * (2**attempt)
-                        await asyncio.sleep(wait_time)
-
-            # Fallback strategy 1: Try deletion with helper_id directly if unique_id not found
-            if not unique_id:
-                logger.info(
-                    f"Could not find unique_id for {entity_id}, trying direct deletion with helper_id"
-                )
-
-                # Try deleting using helper_id directly (fallback approach)
-                delete_msg: dict[str, Any] = {
-                    "type": f"{helper_type}/delete",
-                    f"{helper_type}_id": helper_id,
-                }
-
-                logger.info(f"Sending fallback WebSocket delete message: {delete_msg}")
-                result = await client.send_websocket_message(delete_msg)
-
-                if result.get("success"):
-                    # Wait for entity to be removed
-                    wait_bool = coerce_bool_param(wait, "wait", default=True)
-                    response: dict[str, Any] = {
-                        "success": True,
-                        "action": "delete",
-                        "helper_type": helper_type,
-                        "helper_id": helper_id,
-                        "entity_id": entity_id,
-                        "method": "fallback_direct_id",
-                        "message": f"Successfully deleted {helper_type}: {helper_id} using direct ID (entity: {entity_id})",
-                    }
-                    if wait_bool:
-                        try:
-                            removed = await wait_for_entity_removed(client, entity_id)
-                            if not removed:
-                                response["warning"] = (
-                                    f"Deletion confirmed but {entity_id} may still appear briefly."
-                                )
-                        except Exception as e:
-                            response["warning"] = (
-                                f"Deletion confirmed but removal verification failed: {e}"
-                            )
-                    return response
-
-                # Fallback strategy 2: Check if entity was already deleted
-                try:
-                    final_state_check = await client.get_entity_state(entity_id)
-                    if not final_state_check:
-                        logger.info(
-                            f"Entity {entity_id} no longer exists, considering deletion successful"
-                        )
-                        return {
-                            "success": True,
-                            "action": "delete",
-                            "helper_type": helper_type,
-                            "helper_id": helper_id,
-                            "entity_id": entity_id,
-                            "method": "already_deleted",
-                            "message": f"Helper {helper_id} was already deleted or never properly registered",
-                        }
-                except Exception:
-                    pass
-
-                # Final fallback failed
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.ENTITY_NOT_FOUND,
-                        f"Helper not found in entity registry after {max_retries} attempts: {registry_result.get('error', 'Unknown error') if registry_result else 'No registry response'}",
-                        suggestions=[
-                            "Helper may not be properly registered or was already deleted. Use ha_search_entities() to verify.",
-                        ],
-                        context={"helper_id": helper_id, "entity_id": entity_id},
-                    )
-                )
-
-            # Delete helper using unique_id (correct API from docs)
-            delete_message: dict[str, Any] = {
-                "type": f"{helper_type}/delete",
-                f"{helper_type}_id": unique_id,
-            }
-
-            logger.info(f"Sending WebSocket delete message: {delete_message}")
-            result = await client.send_websocket_message(delete_message)
-            logger.info(f"WebSocket delete response: {result}")
-
-            if result.get("success"):
-                # Wait for entity to be removed
-                wait_bool = coerce_bool_param(wait, "wait", default=True)
-                response = {
-                    "success": True,
-                    "action": "delete",
-                    "helper_type": helper_type,
-                    "helper_id": helper_id,
-                    "entity_id": entity_id,
-                    "unique_id": unique_id,
-                    "method": "standard",
-                    "message": f"Successfully deleted {helper_type}: {helper_id} (entity: {entity_id})",
-                }
-                if wait_bool:
-                    try:
-                        removed = await wait_for_entity_removed(client, entity_id)
-                        if not removed:
-                            response["warning"] = (
-                                f"Deletion confirmed but {entity_id} may still appear briefly."
-                            )
-                    except Exception as e:
-                        response["warning"] = (
-                            f"Deletion confirmed but removal verification failed: {e}"
-                        )
-                return response
-            else:
-                error_msg = result.get("error", "Unknown error")
-                # Handle specific HA error messages
-                if isinstance(error_msg, dict):
-                    error_msg = error_msg.get("message", str(error_msg))
-
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.SERVICE_CALL_FAILED,
-                        f"Failed to delete helper: {error_msg}",
-                        suggestions=[
-                            "Make sure the helper exists and is not being used by automations or scripts",
-                        ],
-                        context={
-                            "helper_id": helper_id,
-                            "entity_id": entity_id,
-                            "unique_id": unique_id,
-                        },
-                    )
-                )
-
-        except ToolError:
-            raise
-        except Exception as e:
-            exception_to_structured_error(
-                e,
-                context={"helper_type": helper_type, "helper_id": helper_id},
-                suggestions=[
-                    "Check Home Assistant connection",
-                    "Verify helper_id exists using ha_search_entities()",
-                    "Ensure helper is not being used by automations or scripts",
-                ],
-            )

{ha_mcp_dev-7.3.0.dev403 → ha_mcp_dev-7.4.0.dev406}/src/ha_mcp/tools/tools_groups.py

@@ -250,12 +250,12 @@ class GroupTools:
         **When NOT to use:** for typical "combine these entities into one controllable group"
         requests, prefer `ha_config_set_helper(helper_type="group", ...)`. Config-entry-backed
         groups are registered in the entity registry, so `ha_set_entity` can assign them to
-        areas and they are deletable via `ha_delete_config_entry`.
+        areas and they are deletable via `ha_delete_helpers_integrations`.
 
         **When to use:** compatibility with existing groups already configured via group.set
         or YAML, or the rare case where entity-registry membership is explicitly unwanted.
-        Groups created here are only removable via `ha_config_remove_group` — neither
-        `ha_config_remove_helper` nor `ha_delete_config_entry` will find them.
+        Groups created here are only removable via `ha_config_remove_group` —
+        `ha_delete_helpers_integrations` will not find them.
 
         **For NEW groups:** Provide object_id and entities (required).
         **For EXISTING groups:** Provide object_id and any fields to update.
@@ -343,8 +343,8 @@ class GroupTools:
         Remove a service-based Home Assistant entity group via the group.remove service.
 
         **When NOT to use:** for groups created through `ha_config_set_helper(helper_type="group", ...)`,
-        use `ha_delete_config_entry`. Those config-entry-backed groups are not reachable via the
-        group.remove service, and `ha_config_remove_helper` does not support helper_type="group".
+        use `ha_delete_helpers_integrations`. Those config-entry-backed groups are not reachable via the
+        group.remove service.
 
         **When to use:** removing groups created with `ha_config_set_group` or defined in YAML
         via `group:` configuration. Config-entry-backed deletion tools cannot find these.