ha-mcp-dev 7.1.0.dev305__tar.gz → 7.1.0.dev307__tar.gz

{ha_mcp_dev-7.1.0.dev305/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.1.0.dev307}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.1.0.dev305
+Version: 7.1.0.dev307
 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-95+-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-93-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>
@@ -158,33 +158,37 @@ Spend less time configuring, more time enjoying your smart home.
 | **💾 System** | Backup/restore, updates, add-ons, device registry |
 
 <details>
-<summary><b>🛠️ Complete Tool List (97 tools)</b></summary>
+<!-- TOOLS_TABLE_START -->
+
+<summary><b>Complete Tool List (93 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
-| **Search & Discovery** | `ha_search_entities`, `ha_deep_search`, `ha_get_overview`, `ha_get_state` |
-| **Service & Device Control** | `ha_call_service`, `ha_bulk_control`, `ha_get_operation_status`, `ha_get_bulk_status`, `ha_list_services` |
-| **Automations** | `ha_config_get_automation`, `ha_config_set_automation`, `ha_config_remove_automation` |
-| **Scripts** | `ha_config_get_script`, `ha_config_set_script`, `ha_config_remove_script` |
-| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_remove_helper` |
-| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard` + dashboard skill references |
-| **Areas & Floors** | `ha_config_list_areas`, `ha_config_set_area`, `ha_config_remove_area`, `ha_config_list_floors`, `ha_config_set_floor`, `ha_config_remove_floor` |
-| **Labels** | `ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels` |
-| **Zones** | `ha_get_zone`, `ha_set_zone`, `ha_remove_zone` |
-| **Groups** | `ha_config_list_groups`, `ha_config_set_group`, `ha_config_remove_group` |
-| **Todo Lists** | `ha_get_todo`, `ha_add_todo_item`, `ha_update_todo_item`, `ha_remove_todo_item` |
-| **Calendar** | `ha_config_get_calendar_events`, `ha_config_set_calendar_event`, `ha_config_remove_calendar_event` |
-| **Blueprints** | `ha_list_blueprints`, `ha_get_blueprint`, `ha_import_blueprint` |
-| **Device Registry** | `ha_get_device`, `ha_update_device`, `ha_remove_device`, `ha_rename_entity` |
-| **ZHA & Integrations** | `ha_get_zha_devices`, `ha_get_entity_integration_source` |
-| **Add-ons** | `ha_get_addon`, `ha_call_addon_api` (HTTP & WebSocket, direct port access) |
+| **Add-ons** | `ha_call_addon_api`, `ha_get_addon` |
+| **Areas & Floors** | `ha_config_list_areas`, `ha_config_list_floors`, `ha_config_remove_area`, `ha_config_remove_floor`, `ha_config_set_area`, `ha_config_set_floor` |
+| **Automations** | `ha_config_get_automation`, `ha_config_remove_automation`, `ha_config_set_automation` |
+| **Blueprints** | `ha_get_blueprint`, `ha_import_blueprint` |
+| **Calendar** | `ha_config_get_calendar_events`, `ha_config_remove_calendar_event`, `ha_config_set_calendar_event` |
 | **Camera** | `ha_get_camera_image` |
-| **History & Statistics** | `ha_get_history`, `ha_get_statistics` |
-| **Automation Traces** | `ha_get_automation_traces` |
-| **System & Updates** | `ha_check_config`, `ha_restart`, `ha_reload_core`, `ha_get_system_info`, `ha_get_system_health`, `ha_get_updates` |
-| **Backup & Restore** | `ha_backup_create`, `ha_backup_restore` |
-| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_integration` |
-
+| **Dashboards** | `ha_config_delete_dashboard_resource`, `ha_config_delete_dashboard`, `ha_config_get_dashboard`, `ha_config_list_dashboard_resources`, `ha_config_set_dashboard_resource`, `ha_config_set_dashboard`, `ha_dashboard_find_card` |
+| **Device Registry** | `ha_get_device`, `ha_remove_device`, `ha_rename_entity_and_device`, `ha_rename_entity`, `ha_update_device` |
+| **Entity Registry** | `ha_get_entity_exposure`, `ha_get_entity`, `ha_set_entity` |
+| **Files** | `ha_delete_file`, `ha_list_files`, `ha_read_file`, `ha_write_file` |
+| **Groups** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |
+| **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_info`, `ha_hacs_list_installed`, `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`, `ha_set_config_entry_helper` |
+| **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logbook`, `ha_get_statistics` |
+| **Integrations** | `ha_delete_config_entry`, `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_get_states`, `ha_search_entities` |
+| **Service & Device Control** | `ha_bulk_control`, `ha_call_service`, `ha_get_bulk_status`, `ha_get_operation_status`, `ha_list_services` |
+| **System** | `ha_backup_create`, `ha_backup_restore`, `ha_check_config`, `ha_get_system_health`, `ha_get_updates`, `ha_reload_core`, `ha_restart` |
+| **Todo Lists** | `ha_add_todo_item`, `ha_get_todo`, `ha_remove_todo_item`, `ha_update_todo_item` |
+| **Utilities** | `ha_eval_template`, `ha_install_mcp_tools`, `ha_report_issue` |
+| **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |
+
+<!-- TOOLS_TABLE_END -->
 </details>
 
 ---

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/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-95+-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-93-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>
@@ -129,33 +129,37 @@ Spend less time configuring, more time enjoying your smart home.
 | **💾 System** | Backup/restore, updates, add-ons, device registry |
 
 <details>
-<summary><b>🛠️ Complete Tool List (97 tools)</b></summary>
+<!-- TOOLS_TABLE_START -->
+
+<summary><b>Complete Tool List (93 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
-| **Search & Discovery** | `ha_search_entities`, `ha_deep_search`, `ha_get_overview`, `ha_get_state` |
-| **Service & Device Control** | `ha_call_service`, `ha_bulk_control`, `ha_get_operation_status`, `ha_get_bulk_status`, `ha_list_services` |
-| **Automations** | `ha_config_get_automation`, `ha_config_set_automation`, `ha_config_remove_automation` |
-| **Scripts** | `ha_config_get_script`, `ha_config_set_script`, `ha_config_remove_script` |
-| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_remove_helper` |
-| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard` + dashboard skill references |
-| **Areas & Floors** | `ha_config_list_areas`, `ha_config_set_area`, `ha_config_remove_area`, `ha_config_list_floors`, `ha_config_set_floor`, `ha_config_remove_floor` |
-| **Labels** | `ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels` |
-| **Zones** | `ha_get_zone`, `ha_set_zone`, `ha_remove_zone` |
-| **Groups** | `ha_config_list_groups`, `ha_config_set_group`, `ha_config_remove_group` |
-| **Todo Lists** | `ha_get_todo`, `ha_add_todo_item`, `ha_update_todo_item`, `ha_remove_todo_item` |
-| **Calendar** | `ha_config_get_calendar_events`, `ha_config_set_calendar_event`, `ha_config_remove_calendar_event` |
-| **Blueprints** | `ha_list_blueprints`, `ha_get_blueprint`, `ha_import_blueprint` |
-| **Device Registry** | `ha_get_device`, `ha_update_device`, `ha_remove_device`, `ha_rename_entity` |
-| **ZHA & Integrations** | `ha_get_zha_devices`, `ha_get_entity_integration_source` |
-| **Add-ons** | `ha_get_addon`, `ha_call_addon_api` (HTTP & WebSocket, direct port access) |
+| **Add-ons** | `ha_call_addon_api`, `ha_get_addon` |
+| **Areas & Floors** | `ha_config_list_areas`, `ha_config_list_floors`, `ha_config_remove_area`, `ha_config_remove_floor`, `ha_config_set_area`, `ha_config_set_floor` |
+| **Automations** | `ha_config_get_automation`, `ha_config_remove_automation`, `ha_config_set_automation` |
+| **Blueprints** | `ha_get_blueprint`, `ha_import_blueprint` |
+| **Calendar** | `ha_config_get_calendar_events`, `ha_config_remove_calendar_event`, `ha_config_set_calendar_event` |
 | **Camera** | `ha_get_camera_image` |
-| **History & Statistics** | `ha_get_history`, `ha_get_statistics` |
-| **Automation Traces** | `ha_get_automation_traces` |
-| **System & Updates** | `ha_check_config`, `ha_restart`, `ha_reload_core`, `ha_get_system_info`, `ha_get_system_health`, `ha_get_updates` |
-| **Backup & Restore** | `ha_backup_create`, `ha_backup_restore` |
-| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_integration` |
-
+| **Dashboards** | `ha_config_delete_dashboard_resource`, `ha_config_delete_dashboard`, `ha_config_get_dashboard`, `ha_config_list_dashboard_resources`, `ha_config_set_dashboard_resource`, `ha_config_set_dashboard`, `ha_dashboard_find_card` |
+| **Device Registry** | `ha_get_device`, `ha_remove_device`, `ha_rename_entity_and_device`, `ha_rename_entity`, `ha_update_device` |
+| **Entity Registry** | `ha_get_entity_exposure`, `ha_get_entity`, `ha_set_entity` |
+| **Files** | `ha_delete_file`, `ha_list_files`, `ha_read_file`, `ha_write_file` |
+| **Groups** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |
+| **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_info`, `ha_hacs_list_installed`, `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`, `ha_set_config_entry_helper` |
+| **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logbook`, `ha_get_statistics` |
+| **Integrations** | `ha_delete_config_entry`, `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_get_states`, `ha_search_entities` |
+| **Service & Device Control** | `ha_bulk_control`, `ha_call_service`, `ha_get_bulk_status`, `ha_get_operation_status`, `ha_list_services` |
+| **System** | `ha_backup_create`, `ha_backup_restore`, `ha_check_config`, `ha_get_system_health`, `ha_get_updates`, `ha_reload_core`, `ha_restart` |
+| **Todo Lists** | `ha_add_todo_item`, `ha_get_todo`, `ha_remove_todo_item`, `ha_update_todo_item` |
+| **Utilities** | `ha_eval_template`, `ha_install_mcp_tools`, `ha_report_issue` |
+| **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |
+
+<!-- TOOLS_TABLE_END -->
 </details>
 
 ---

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.1.0.dev305"
+version = "7.1.0.dev307"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -177,6 +177,7 @@ dev = [
     "lefthook>=1.10.0",
     "ruff>=0.12.12",
     "testcontainers>=4.13.0",
+    "ast-grep-cli>=0.42.0",
 ]
 
 # Semantic versioning configuration

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/src/ha_mcp/tools/backup.py

@@ -391,7 +391,7 @@ def register_backup_tools(mcp: "FastMCP", client: HomeAssistantClient, **kwargs:
 
 **Returns:** Backup ID and job status"""
 
-    @mcp.tool(description=backup_create_description, annotations={"destructiveHint": True, "title": "Create Backup"})
+    @mcp.tool(description=backup_create_description, tags={"System"}, annotations={"destructiveHint": True, "title": "Create Backup"})
     @log_tool_usage
     async def ha_backup_create(
         name: Annotated[
@@ -405,7 +405,7 @@ def register_backup_tools(mcp: "FastMCP", client: HomeAssistantClient, **kwargs:
         """Create a fast Home Assistant backup (local only)."""
         return await create_backup(client, name)
 
-    @mcp.tool(annotations={"destructiveHint": True, "title": "Restore Backup"})
+    @mcp.tool(tags={"System"}, annotations={"destructiveHint": True, "title": "Restore Backup"})
     @log_tool_usage
     async def ha_backup_restore(
         backup_id: Annotated[

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/src/ha_mcp/tools/tools_addons.py

@@ -87,19 +87,19 @@ async def _supervisor_api_call(
         if not result.get("success"):
             error_msg = str(result.get("error", ""))
             if "not_found" in error_msg.lower() or "unknown" in error_msg.lower():
-                return create_error_response(
+                raise_tool_error(create_error_response(
                     ErrorCode.RESOURCE_NOT_FOUND,
                     "Supervisor API not available",
                     details=str(result),
                     suggestions=[
                         "This feature requires Home Assistant OS or Supervised installation",
                     ],
-                )
-            return create_error_response(
+                ))
+            raise_tool_error(create_error_response(
                 ErrorCode.SERVICE_CALL_FAILED,
                 f"Supervisor API call failed: {endpoint}",
                 details=str(result),
-            )
+            ))
 
         return {"success": True, "result": result.get("result", {})}
 
@@ -107,10 +107,9 @@ async def _supervisor_api_call(
         raise
     except Exception as e:
         logger.error(f"Error calling Supervisor API {endpoint}: {e}")
-        return exception_to_structured_error(
+        exception_to_structured_error(
             e,
             context={"endpoint": endpoint},
-            raise_error=False,
             suggestions=["Check Home Assistant connection and Supervisor availability"],
         )
     finally:
@@ -311,23 +310,23 @@ async def _call_addon_ws(
     # 1. Sanitize path
     normalized = unquote(path).lstrip("/")
     if ".." in normalized.split("/"):
-        return create_validation_error(
+        raise_tool_error(create_validation_error(
             "Path contains '..' traversal component",
             parameter="path",
             details=f"Rejected path: {path}",
-        )
+        ))
 
     # 2. Get add-on info
     addon_response = await get_addon_info(client, slug)
     if not addon_response.get("success"):
-        return addon_response
+        raise_tool_error(addon_response)
 
     addon = addon_response["addon"]
     addon_name = addon.get("name", slug)
 
     # 3. Verify add-on supports Ingress (unless using direct port override)
     if not port and not addon.get("ingress"):
-        return create_error_response(
+        raise_tool_error(create_error_response(
             ErrorCode.VALIDATION_FAILED,
             f"Add-on '{addon_name}' does not support Ingress",
             suggestions=[
@@ -335,37 +334,37 @@ async def _call_addon_ws(
                 f"Use ha_get_addon(slug='{slug}') to see available ports",
             ],
             context={"slug": slug},
-        )
+        ))
 
     # 4. Verify add-on is running
     if addon.get("state") != "started":
-        return create_error_response(
+        raise_tool_error(create_error_response(
             ErrorCode.SERVICE_CALL_FAILED,
             f"Add-on '{addon_name}' is not running (state: {addon.get('state')})",
             suggestions=[
                 f"Start the add-on first with: ha_call_service('hassio', 'addon_start', {{'addon': '{slug}'}})",
             ],
             context={"slug": slug, "state": addon.get("state")},
-        )
+        ))
 
     # 5. Build WebSocket URL
     addon_ip = addon.get("ip_address", "")
     if port:
         if not addon_ip:
-            return create_error_response(
+            raise_tool_error(create_error_response(
                 ErrorCode.INTERNAL_ERROR,
                 f"Add-on '{addon_name}' is missing ip_address",
                 context={"slug": slug},
-            )
+            ))
         target_port = port
     else:
         ingress_port = addon.get("ingress_port")
         if not addon_ip or not ingress_port:
-            return create_error_response(
+            raise_tool_error(create_error_response(
                 ErrorCode.INTERNAL_ERROR,
                 f"Add-on '{addon_name}' is missing network info",
                 context={"slug": slug},
-            )
+            ))
         target_port = ingress_port
 
     ws_url = f"ws://{addon_ip}:{target_port}/{normalized}"
@@ -439,7 +438,7 @@ async def _call_addon_ws(
                 total_size += len(clean)
 
     except websockets.exceptions.InvalidHandshake as e:
-        return create_error_response(
+        raise_tool_error(create_error_response(
             ErrorCode.SERVICE_CALL_FAILED,
             f"WebSocket handshake failed with '{addon_name}': {e!s}",
             suggestions=[
@@ -447,9 +446,9 @@ async def _call_addon_ws(
                 f"Use ha_get_addon(slug='{slug}') to inspect available endpoints",
             ],
             context={"slug": slug, "path": path},
-        )
+        ))
     except websockets.exceptions.ConnectionClosed as e:
-        return create_error_response(
+        raise_tool_error(create_error_response(
             ErrorCode.SERVICE_CALL_FAILED,
             f"WebSocket connection to '{addon_name}' closed unexpectedly: {e!s}",
             suggestions=[
@@ -457,20 +456,20 @@ async def _call_addon_ws(
                 "Try again or check add-on logs for errors",
             ],
             context={"slug": slug, "path": path},
-        )
+        ))
     except TimeoutError:
-        return create_timeout_error(
+        raise_tool_error(create_timeout_error(
             f"WebSocket connection to '{addon_name}'",
             timeout,
             details=f"path={path}",
             context={"slug": slug, "path": path},
-        )
+        ))
     except OSError as e:
-        return create_connection_error(
+        raise_tool_error(create_connection_error(
             f"Failed to connect to add-on '{addon_name}' WebSocket: {e!s}",
             details="Check that the add-on is running and the port is correct",
             context={"slug": slug},
-        )
+        ))
 
     elapsed = round(time.monotonic() - start_time, 2)
 
@@ -554,23 +553,23 @@ async def _call_addon_api(
     # 1. Sanitize path to prevent traversal attacks (including URL-encoded)
     normalized = unquote(path).lstrip("/")
     if ".." in normalized.split("/"):
-        return create_validation_error(
+        raise_tool_error(create_validation_error(
             "Path contains '..' traversal component",
             parameter="path",
             details=f"Rejected path: {path}",
-        )
+        ))
 
     # 2. Get add-on info to verify ingress support and get entry path
     addon_response = await get_addon_info(client, slug)
     if not addon_response.get("success"):
-        return addon_response
+        raise_tool_error(addon_response)
 
     addon = addon_response["addon"]
     addon_name = addon.get("name", slug)
 
     # 3. Verify add-on supports Ingress (unless using direct port override)
     if not port and not addon.get("ingress"):
-        return create_error_response(
+        raise_tool_error(create_error_response(
             ErrorCode.VALIDATION_FAILED,
             f"Add-on '{addon_name}' does not support Ingress",
             suggestions=[
@@ -579,18 +578,18 @@ async def _call_addon_api(
                 "Use the 'port' parameter to connect to a direct access port",
             ],
             context={"slug": slug},
-        )
+        ))
 
     # 4. Verify add-on is running
     if addon.get("state") != "started":
-        return create_error_response(
+        raise_tool_error(create_error_response(
             ErrorCode.SERVICE_CALL_FAILED,
             f"Add-on '{addon_name}' is not running (state: {addon.get('state')})",
             suggestions=[
                 f"Start the add-on first with: ha_call_service('hassio', 'addon_start', {{'addon': '{slug}'}})",
             ],
             context={"slug": slug, "state": addon.get("state")},
-        )
+        ))
 
     # 5. Build URL to the add-on container
     addon_ip = addon.get("ip_address", "")
@@ -600,21 +599,21 @@ async def _call_addon_api(
         # (e.g., 1880 for Node-RED, 6052 for ESPHome) instead of the ingress port.
         # Requires 'leave_front_door_open' or equivalent setting on the add-on.
         if not addon_ip:
-            return create_error_response(
+            raise_tool_error(create_error_response(
                 ErrorCode.INTERNAL_ERROR,
                 f"Add-on '{addon_name}' is missing ip_address",
                 context={"slug": slug, "ip_address": addon_ip},
-            )
+            ))
         target_port = port
     else:
         # Default: use the ingress port for direct container communication
         ingress_port = addon.get("ingress_port")
         if not addon_ip or not ingress_port:
-            return create_error_response(
+            raise_tool_error(create_error_response(
                 ErrorCode.INTERNAL_ERROR,
                 f"Add-on '{addon_name}' is missing network info (ip_address or ingress_port)",
                 context={"slug": slug, "ip_address": addon_ip, "ingress_port": ingress_port},
-            )
+            ))
         target_port = ingress_port
 
     url = f"http://{addon_ip}:{target_port}/{normalized}"
@@ -648,18 +647,18 @@ async def _call_addon_api(
                 content=request_content,
             )
     except httpx.TimeoutException:
-        return create_timeout_error(
+        raise_tool_error(create_timeout_error(
             f"add-on API call to '{addon_name}'",
             timeout,
             details=f"path={path}, method={method}",
             context={"slug": slug, "path": path},
-        )
+        ))
     except httpx.ConnectError as e:
-        return create_connection_error(
+        raise_tool_error(create_connection_error(
             f"Failed to connect to add-on '{addon_name}': {e!s}",
             details="Check that the add-on is running and Home Assistant Ingress is working",
             context={"slug": slug},
-        )
+        ))
 
     # 7. Parse response
     content_type = response.headers.get("content-type", "")
@@ -783,7 +782,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         **kwargs: Additional arguments (ignored, for auto-discovery compatibility)
     """
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["addon"], "title": "Get Add-ons"})
+    @mcp.tool(tags={"Add-ons"}, annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Add-ons"})
     @log_tool_usage
     async def ha_get_addon(
         source: Annotated[
@@ -878,13 +877,15 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
             raise_tool_error(result)
         return result
 
-    @mcp.tool(annotations={
-        "destructiveHint": True,
-        "idempotentHint": False,
-        "readOnlyHint": False,
-        "tags": ["addon"],
-        "title": "Call Add-on API",
-    })
+    @mcp.tool(
+        tags={"Add-ons"},
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": False,
+            "readOnlyHint": False,
+            "title": "Call Add-on API",
+        },
+    )
     @log_tool_usage
     async def ha_call_addon_api(
         slug: Annotated[

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/src/ha_mcp/tools/tools_areas.py

@@ -25,7 +25,7 @@ def register_area_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     # AREA TOOLS
     # ============================================================
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["area"], "title": "List Areas"})
+    @mcp.tool(tags={"Areas & Floors"}, annotations={"idempotentHint": True, "readOnlyHint": True, "title": "List Areas"})
     @log_tool_usage
     async def ha_config_list_areas() -> dict[str, Any]:
         """
@@ -63,7 +63,7 @@ def register_area_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "Verify WebSocket connection is active",
             ])
 
-    @mcp.tool(annotations={"destructiveHint": True, "tags": ["area"], "title": "Create or Update Area"})
+    @mcp.tool(tags={"Areas & Floors"}, annotations={"destructiveHint": True, "title": "Create or Update Area"})
     @log_tool_usage
     async def ha_config_set_area(
         name: Annotated[
@@ -208,7 +208,7 @@ def register_area_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "If assigning to a floor, verify floor_id exists",
             ])
 
-    @mcp.tool(annotations={"destructiveHint": True, "idempotentHint": True, "tags": ["area"], "title": "Remove Area"})
+    @mcp.tool(tags={"Areas & Floors"}, annotations={"destructiveHint": True, "idempotentHint": True, "title": "Remove Area"})
     @log_tool_usage
     async def ha_config_remove_area(
         area_id: Annotated[
@@ -258,7 +258,7 @@ def register_area_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     # FLOOR TOOLS
     # ============================================================
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["floor"], "title": "List Floors"})
+    @mcp.tool(tags={"Areas & Floors"}, annotations={"idempotentHint": True, "readOnlyHint": True, "title": "List Floors"})
     @log_tool_usage
     async def ha_config_list_floors() -> dict[str, Any]:
         """
@@ -296,7 +296,7 @@ def register_area_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "Verify WebSocket connection is active",
             ])
 
-    @mcp.tool(annotations={"destructiveHint": True, "tags": ["floor"], "title": "Create or Update Floor"})
+    @mcp.tool(tags={"Areas & Floors"}, annotations={"destructiveHint": True, "title": "Create or Update Floor"})
     @log_tool_usage
     async def ha_config_set_floor(
         name: Annotated[
@@ -429,7 +429,7 @@ def register_area_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "For update: Verify the floor_id exists using ha_config_list_floors()",
             ])
 
-    @mcp.tool(annotations={"destructiveHint": True, "idempotentHint": True, "tags": ["floor"], "title": "Remove Floor"})
+    @mcp.tool(tags={"Areas & Floors"}, annotations={"destructiveHint": True, "idempotentHint": True, "title": "Remove Floor"})
     @log_tool_usage
     async def ha_config_remove_floor(
         floor_id: Annotated[

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/src/ha_mcp/tools/tools_blueprints.py

@@ -56,7 +56,7 @@ def register_blueprint_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             "blueprints": blueprints,
         }
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["blueprint"], "title": "Get Blueprint"})
+    @mcp.tool(tags={"Blueprints"}, annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Blueprint"})
     @log_tool_usage
     async def ha_get_blueprint(
         path: Annotated[
@@ -183,7 +183,7 @@ def register_blueprint_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 ],
             )
 
-    @mcp.tool(annotations={"destructiveHint": True, "tags": ["blueprint"], "title": "Import Blueprint"})
+    @mcp.tool(tags={"Blueprints"}, annotations={"destructiveHint": True, "title": "Import Blueprint"})
     @log_tool_usage
     async def ha_import_blueprint(
         url: Annotated[

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/src/ha_mcp/tools/tools_bug_report.py

@@ -85,11 +85,11 @@ def register_bug_report_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register bug report tools with the MCP server."""
 
     @mcp.tool(
+        tags={"Utilities"},
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "tags": ["system", "diagnostics", "feedback"],
-            "title": "Report Issue or Feedback",
+            "title": "Report Issue or Feedback"
         }
     )
     @log_tool_usage

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/src/ha_mcp/tools/tools_calendar.py

@@ -23,7 +23,7 @@ logger = logging.getLogger(__name__)
 def register_calendar_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register calendar management tools with the MCP server."""
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["calendar"], "title": "Get Calendar Events"})
+    @mcp.tool(tags={"Calendar"}, annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Calendar Events"})
     @log_tool_usage
     async def ha_config_get_calendar_events(
         entity_id: Annotated[
@@ -144,7 +144,7 @@ def register_calendar_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
             exception_to_structured_error(error, context={"entity_id": entity_id}, suggestions=suggestions)
 
-    @mcp.tool(annotations={"destructiveHint": True, "tags": ["calendar"], "title": "Create or Update Calendar Event"})
+    @mcp.tool(tags={"Calendar"}, annotations={"destructiveHint": True, "title": "Create or Update Calendar Event"})
     @log_tool_usage
     async def ha_config_set_calendar_event(
         entity_id: Annotated[
@@ -263,7 +263,7 @@ def register_calendar_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
             exception_to_structured_error(error, context={"entity_id": entity_id}, suggestions=suggestions)
 
-    @mcp.tool(annotations={"destructiveHint": True, "idempotentHint": True, "tags": ["calendar"], "title": "Remove Calendar Event"})
+    @mcp.tool(tags={"Calendar"}, annotations={"destructiveHint": True, "idempotentHint": True, "title": "Remove Calendar Event"})
     @log_tool_usage
     async def ha_config_remove_calendar_event(
         entity_id: Annotated[

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/src/ha_mcp/tools/tools_camera.py

@@ -18,7 +18,7 @@ logger = logging.getLogger(__name__)
 def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register Home Assistant camera tools."""
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["camera"], "title": "Get Camera Image"})
+    @mcp.tool(tags={"Camera"}, annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Camera Image"})
     @log_tool_usage
     async def ha_get_camera_image(
         entity_id: str,

{ha_mcp_dev-7.1.0.dev305 → ha_mcp_dev-7.1.0.dev307}/src/ha_mcp/tools/tools_categories.py

@@ -24,11 +24,11 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register Home Assistant category management tools."""
 
     @mcp.tool(
+        tags={"Labels & Categories"},
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "tags": ["category"],
-            "title": "Get Category",
+            "title": "Get Category"
         }
     )
     @log_tool_usage
@@ -143,10 +143,10 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             )
 
     @mcp.tool(
+        tags={"Labels & Categories"},
         annotations={
             "destructiveHint": True,
-            "tags": ["category"],
-            "title": "Create or Update Category",
+            "title": "Create or Update Category"
         }
     )
     @log_tool_usage
@@ -246,11 +246,11 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             )
 
     @mcp.tool(
+        tags={"Labels & Categories"},
         annotations={
             "destructiveHint": True,
             "idempotentHint": True,
-            "tags": ["category"],
-            "title": "Remove Category",
+            "title": "Remove Category"
         }
     )
     @log_tool_usage