ha-mcp-dev 6.3.1.dev137__py3-none-any.whl

ha_mcp/tools/tools_hacs.py

@@ -0,0 +1,787 @@
+"""
+HACS (Home Assistant Community Store) integration tools for Home Assistant MCP server.
+
+This module provides tools to interact with HACS via the WebSocket API, enabling AI agents
+to discover custom integrations, Lovelace cards, themes, and more.
+"""
+
+import logging
+from typing import Annotated, Any, Literal
+
+from pydantic import Field
+
+from .helpers import exception_to_structured_error, log_tool_usage
+from .util_helpers import add_timezone_metadata, coerce_int_param
+
+logger = logging.getLogger(__name__)
+
+# HACS uses different category names internally vs what users expect
+# User-friendly name -> HACS internal name
+CATEGORY_MAP = {
+    "lovelace": "plugin",  # HACS calls Lovelace cards "plugin"
+    "integration": "integration",
+    "theme": "theme",
+    "appdaemon": "appdaemon",
+    "python_script": "python_script",
+    "template": "template",
+}
+
+# Reverse mapping for display
+CATEGORY_DISPLAY = {v: k for k, v in CATEGORY_MAP.items()}
+CATEGORY_DISPLAY["plugin"] = "lovelace"  # Display as lovelace for users
+
+
+async def _check_hacs_available(client) -> tuple[bool, str | None]:
+    """
+    Check if HACS is installed and available via WebSocket.
+
+    Returns:
+        Tuple of (is_available, error_message)
+    """
+    try:
+        from ..client.websocket_client import get_websocket_client
+        ws_client = await get_websocket_client()
+
+        # Try to get HACS info to verify it's installed
+        response = await ws_client.send_command("hacs/info")
+
+        if response.get("success"):
+            return True, None
+        else:
+            return False, "HACS is installed but returned an error"
+    except Exception as e:
+        error_str = str(e).lower()
+        if "unknown command" in error_str or "not found" in error_str:
+            return False, "HACS is not installed or not loaded. Please install HACS from https://hacs.xyz/"
+        return False, f"Failed to connect to HACS: {str(e)}"
+
+
+def register_hacs_tools(mcp, client, **kwargs):
+    """Register HACS integration tools with the MCP server."""
+
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["hacs", "info"], "title": "Get HACS Info"})
+    @log_tool_usage
+    async def ha_hacs_info() -> dict[str, Any]:
+        """Get HACS status, version, and enabled categories.
+
+        Returns information about the HACS installation including:
+        - Version number
+        - Enabled categories (integration, lovelace, theme, etc.)
+        - Stage (running, startup, etc.)
+        - Lovelace mode
+        - Disabled reason (if any)
+
+        This is useful for validating that HACS is installed and operational
+        before using other HACS tools.
+
+        **HACS Installation:**
+        If HACS is not installed, visit https://hacs.xyz/ for installation instructions.
+
+        Returns:
+            Dictionary with HACS status information or error if HACS is not available.
+        """
+        try:
+            # Check if HACS is available
+            is_available, error_msg = await _check_hacs_available(client)
+            if not is_available:
+                return await add_timezone_metadata(client, {
+                    "success": False,
+                    "error": error_msg,
+                    "error_code": "HACS_NOT_AVAILABLE",
+                    "suggestions": [
+                        "Install HACS from https://hacs.xyz/",
+                        "Ensure Home Assistant has been restarted after HACS installation",
+                        "Check Home Assistant logs for HACS errors",
+                    ],
+                })
+
+            # Get HACS info via WebSocket
+            from ..client.websocket_client import get_websocket_client
+            ws_client = await get_websocket_client()
+            response = await ws_client.send_command("hacs/info")
+
+            if not response.get("success"):
+                error_response = exception_to_structured_error(
+                    Exception(f"HACS info request failed: {response}"),
+                    context={"command": "hacs/info"},
+                )
+                return await add_timezone_metadata(client, error_response)
+
+            result = response.get("result", {})
+
+            return await add_timezone_metadata(client, {
+                "success": True,
+                "version": result.get("version"),
+                "categories": result.get("categories", []),
+                "stage": result.get("stage"),
+                "lovelace_mode": result.get("lovelace_mode"),
+                "disabled_reason": result.get("disabled_reason"),
+                "data": result,
+            })
+
+        except Exception as e:
+            error_response = exception_to_structured_error(
+                e,
+                context={"tool": "ha_hacs_info"},
+            )
+            if "error" in error_response and isinstance(error_response["error"], dict):
+                error_response["error"]["suggestions"] = [
+                    "Verify HACS is installed: https://hacs.xyz/",
+                    "Check Home Assistant connection",
+                    "Restart Home Assistant if HACS was recently installed",
+                ]
+            return await add_timezone_metadata(client, error_response)
+
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["hacs", "search"], "title": "List HACS Installed"})
+    @log_tool_usage
+    async def ha_hacs_list_installed(
+        category: Annotated[
+            Literal["integration", "lovelace", "theme", "appdaemon", "python_script"] | None,
+            Field(
+                default=None,
+                description=(
+                    "Filter by category: 'integration', 'lovelace', 'theme', "
+                    "'appdaemon', or 'python_script'. Use None for all categories."
+                ),
+            ),
+        ] = None,
+    ) -> dict[str, Any]:
+        """List installed HACS repositories with focused, small response.
+
+        **DASHBOARD TIP:** Use `category="lovelace"` to discover installed custom cards
+        for use with `ha_config_set_dashboard()`.
+
+        Returns a list of installed repositories with key information:
+        - name: Repository name
+        - full_name: Full GitHub repository name (owner/repo)
+        - category: Type of repository (integration, lovelace, theme, etc.)
+        - installed_version: Currently installed version
+        - available_version: Latest available version
+        - pending_update: Whether an update is available
+        - description: Repository description
+
+        **Categories:**
+        - `integration`: Custom integrations and components
+        - `lovelace`: Custom dashboard cards and panels
+        - `theme`: Custom themes for the UI
+        - `appdaemon`: AppDaemon apps
+        - `python_script`: Python scripts
+
+        Args:
+            category: Filter results by category (default: all categories)
+
+        Returns:
+            List of installed HACS repositories or error if HACS is not available.
+        """
+        try:
+            # Check if HACS is available
+            is_available, error_msg = await _check_hacs_available(client)
+            if not is_available:
+                return await add_timezone_metadata(client, {
+                    "success": False,
+                    "error": error_msg,
+                    "error_code": "HACS_NOT_AVAILABLE",
+                    "suggestions": [
+                        "Install HACS from https://hacs.xyz/",
+                        "Ensure Home Assistant has been restarted after HACS installation",
+                        "Check Home Assistant logs for HACS errors",
+                    ],
+                })
+
+            # Get installed repositories via WebSocket
+            from ..client.websocket_client import get_websocket_client
+            ws_client = await get_websocket_client()
+
+            # Build command parameters - map user-friendly category to HACS internal name
+            kwargs_cmd: dict[str, Any] = {}
+            if category:
+                hacs_category = CATEGORY_MAP.get(category, category)
+                kwargs_cmd["categories"] = [hacs_category]
+
+            response = await ws_client.send_command("hacs/repositories/list", **kwargs_cmd)
+
+            if not response.get("success"):
+                error_response = exception_to_structured_error(
+                    Exception(f"HACS repositories list request failed: {response}"),
+                    context={"command": "hacs/repositories/list", "category": category},
+                )
+                return await add_timezone_metadata(client, error_response)
+
+            repositories = response.get("result", [])
+
+            # Filter to only installed repositories and extract key info
+            installed = []
+            for repo in repositories:
+                if repo.get("installed", False):
+                    # Map HACS internal category back to user-friendly name
+                    repo_category = repo.get("category", "")
+                    display_category = CATEGORY_DISPLAY.get(repo_category, repo_category)
+                    installed.append({
+                        "name": repo.get("name"),
+                        "full_name": repo.get("full_name"),
+                        "category": display_category,
+                        "id": repo.get("id"),  # Include numeric ID for repository_info
+                        "installed_version": repo.get("installed_version"),
+                        "available_version": repo.get("available_version"),
+                        "pending_update": repo.get("pending_upgrade", False),
+                        "description": repo.get("description"),
+                        "authors": repo.get("authors", []),
+                        "domain": repo.get("domain"),  # For integrations
+                        "stars": repo.get("stars", 0),
+                    })
+
+            return await add_timezone_metadata(client, {
+                "success": True,
+                "category_filter": category,
+                "total_installed": len(installed),
+                "repositories": installed,
+            })
+
+        except Exception as e:
+            error_response = exception_to_structured_error(
+                e,
+                context={"tool": "ha_hacs_list_installed", "category": category},
+            )
+            if "error" in error_response and isinstance(error_response["error"], dict):
+                error_response["error"]["suggestions"] = [
+                    "Verify HACS is installed: https://hacs.xyz/",
+                    "Check category name is valid: integration, lovelace, theme, appdaemon, python_script",
+                    "Check Home Assistant connection",
+                ]
+            return await add_timezone_metadata(client, error_response)
+
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["hacs", "search"], "title": "Search HACS Store"})
+    @log_tool_usage
+    async def ha_hacs_search(
+        query: str,
+        category: Annotated[
+            Literal["integration", "lovelace", "theme", "appdaemon", "python_script"] | None,
+            Field(
+                default=None,
+                description="Filter by category (optional)",
+            ),
+        ] = None,
+        max_results: Annotated[
+            int | str,
+            Field(
+                default=10,
+                description="Maximum number of results to return (default: 10, max: 100)",
+            ),
+        ] = 10,
+    ) -> dict[str, Any]:
+        """Search HACS store for repositories by keyword with pagination.
+
+        Searches the HACS store for repositories matching the query string.
+        Returns repository information including stars, downloads, and descriptions.
+
+        **Use Cases:**
+        - Find custom cards: `ha_hacs_search("mushroom", category="lovelace")`
+        - Find integrations: `ha_hacs_search("nest", category="integration")`
+        - Browse themes: `ha_hacs_search("dark", category="theme")`
+
+        Results include:
+        - name: Repository name
+        - full_name: Full GitHub repository name
+        - description: Repository description
+        - category: Type of repository
+        - stars: GitHub stars count
+        - downloads: Number of HACS installations
+        - authors: Repository authors
+        - installed: Whether already installed
+
+        Args:
+            query: Search query (repository name, description, author)
+            category: Filter by category (optional)
+            max_results: Maximum results to return (default: 10, max: 100)
+
+        Returns:
+            Search results from HACS store or error if HACS is not available.
+        """
+        try:
+            # Coerce max_results to int
+            max_results_int = coerce_int_param(
+                max_results,
+                "max_results",
+                default=10,
+                min_value=1,
+                max_value=100,
+            ) or 10
+
+            # Check if HACS is available
+            is_available, error_msg = await _check_hacs_available(client)
+            if not is_available:
+                return await add_timezone_metadata(client, {
+                    "success": False,
+                    "error": error_msg,
+                    "error_code": "HACS_NOT_AVAILABLE",
+                    "suggestions": [
+                        "Install HACS from https://hacs.xyz/",
+                        "Ensure Home Assistant has been restarted after HACS installation",
+                        "Check Home Assistant logs for HACS errors",
+                    ],
+                })
+
+            # Get all repositories via WebSocket
+            from ..client.websocket_client import get_websocket_client
+            ws_client = await get_websocket_client()
+
+            # Build command parameters - map user-friendly category to HACS internal name
+            kwargs_cmd: dict[str, Any] = {}
+            if category:
+                hacs_category = CATEGORY_MAP.get(category, category)
+                kwargs_cmd["categories"] = [hacs_category]
+
+            response = await ws_client.send_command("hacs/repositories/list", **kwargs_cmd)
+
+            if not response.get("success"):
+                error_response = exception_to_structured_error(
+                    Exception(f"HACS search request failed: {response}"),
+                    context={"command": "hacs/repositories/list", "query": query, "category": category},
+                )
+                return await add_timezone_metadata(client, error_response)
+
+            all_repositories = response.get("result", [])
+
+            # Simple search: filter by query string in name, description, or authors
+            query_lower = query.lower().strip()
+            matches = []
+
+            for repo in all_repositories:
+                # Handle None values safely
+                name = (repo.get("name") or "").lower()
+                description = (repo.get("description") or "").lower()
+                full_name = (repo.get("full_name") or "").lower()
+                authors_list = repo.get("authors") or []
+                authors = " ".join(authors_list).lower()
+
+                # Calculate relevance score
+                score = 0
+                if query_lower in name:
+                    score += 100
+                if query_lower in full_name:
+                    score += 50
+                if query_lower in description:
+                    score += 30
+                if query_lower in authors:
+                    score += 20
+
+                if score > 0:
+                    # Map HACS internal category back to user-friendly name
+                    repo_category = repo.get("category", "")
+                    display_category = CATEGORY_DISPLAY.get(repo_category, repo_category)
+                    matches.append({
+                        "name": repo.get("name"),
+                        "full_name": repo.get("full_name"),
+                        "description": repo.get("description"),
+                        "category": display_category,
+                        "id": repo.get("id"),  # Include numeric ID for repository_info
+                        "stars": repo.get("stars", 0),
+                        "downloads": repo.get("downloads", 0),
+                        "authors": authors_list,
+                        "installed": repo.get("installed", False),
+                        "installed_version": repo.get("installed_version") if repo.get("installed") else None,
+                        "available_version": repo.get("available_version"),
+                        "score": score,
+                    })
+
+            # Sort by score (descending) and limit results
+            matches.sort(key=lambda x: x["score"], reverse=True)
+            limited_matches = matches[:max_results_int]
+
+            return await add_timezone_metadata(client, {
+                "success": True,
+                "query": query,
+                "category_filter": category,
+                "total_matches": len(matches),
+                "results_returned": len(limited_matches),
+                "results": limited_matches,
+            })
+
+        except Exception as e:
+            error_response = exception_to_structured_error(
+                e,
+                context={"tool": "ha_hacs_search", "query": query, "category": category},
+            )
+            if "error" in error_response and isinstance(error_response["error"], dict):
+                error_response["error"]["suggestions"] = [
+                    "Verify HACS is installed: https://hacs.xyz/",
+                    "Try a simpler search query",
+                    "Check category name is valid: integration, lovelace, theme, appdaemon, python_script",
+                ]
+            return await add_timezone_metadata(client, error_response)
+
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["hacs", "info"], "title": "Get HACS Repository Info"})
+    @log_tool_usage
+    async def ha_hacs_repository_info(repository_id: str) -> dict[str, Any]:
+        """Get detailed repository information including README and documentation.
+
+        Returns comprehensive information about a HACS repository:
+        - Basic info (name, description, category, authors)
+        - Installation status and versions
+        - README content (useful for configuration examples)
+        - Available releases and versions
+        - GitHub stats (stars, issues)
+        - Configuration examples (if available)
+
+        **Use Cases:**
+        - Get card configuration examples: `ha_hacs_repository_info("441028036")`
+        - Check integration setup instructions
+        - Find theme customization options
+
+        **Note:** The repository_id is the numeric ID from HACS, not the GitHub path.
+        Use `ha_hacs_list_installed()` or `ha_hacs_search()` to find the numeric ID.
+
+        Args:
+            repository_id: Repository numeric ID (e.g., "441028036") or GitHub path (e.g., "dvd-dev/hilo")
+
+        Returns:
+            Detailed repository information or error if not found.
+        """
+        try:
+            # Check if HACS is available
+            is_available, error_msg = await _check_hacs_available(client)
+            if not is_available:
+                return await add_timezone_metadata(client, {
+                    "success": False,
+                    "error": error_msg,
+                    "error_code": "HACS_NOT_AVAILABLE",
+                    "suggestions": [
+                        "Install HACS from https://hacs.xyz/",
+                        "Ensure Home Assistant has been restarted after HACS installation",
+                        "Check Home Assistant logs for HACS errors",
+                    ],
+                })
+
+            from ..client.websocket_client import get_websocket_client
+            ws_client = await get_websocket_client()
+
+            # If repository_id contains a slash, it's a GitHub path - need to look up numeric ID
+            actual_id = repository_id
+            if "/" in repository_id:
+                # Look up the numeric ID from the repository list
+                list_response = await ws_client.send_command("hacs/repositories/list")
+                if list_response.get("success"):
+                    repos = list_response.get("result", [])
+                    for repo in repos:
+                        if repo.get("full_name", "").lower() == repository_id.lower():
+                            actual_id = str(repo.get("id"))
+                            break
+                    else:
+                        return await add_timezone_metadata(client, {
+                            "success": False,
+                            "error": f"Repository '{repository_id}' not found in HACS",
+                            "error_code": "REPOSITORY_NOT_FOUND",
+                            "suggestions": [
+                                "Use ha_hacs_search() to find the repository",
+                                "Check the repository name is correct (case-insensitive)",
+                                "The repository may need to be added to HACS first",
+                            ],
+                        })
+
+            # Get repository info via WebSocket using numeric ID
+            response = await ws_client.send_command("hacs/repository/info", repository_id=actual_id)
+
+            if not response.get("success"):
+                error_response = exception_to_structured_error(
+                    Exception(f"HACS repository info request failed: {response}"),
+                    context={"command": "hacs/repository/info", "repository_id": repository_id},
+                )
+                return await add_timezone_metadata(client, error_response)
+
+            result = response.get("result", {})
+
+            # Extract and structure the most useful information
+            return await add_timezone_metadata(client, {
+                "success": True,
+                "repository_id": repository_id,
+                "name": result.get("name"),
+                "full_name": result.get("full_name"),
+                "description": result.get("description"),
+                "category": result.get("category"),
+                "authors": result.get("authors", []),
+                "domain": result.get("domain"),  # For integrations
+                "installed": result.get("installed", False),
+                "installed_version": result.get("installed_version"),
+                "available_version": result.get("available_version"),
+                "pending_update": result.get("pending_upgrade", False),
+                "stars": result.get("stars", 0),
+                "downloads": result.get("downloads", 0),
+                "topics": result.get("topics", []),
+                "releases": result.get("releases", []),
+                "default_branch": result.get("default_branch"),
+                "readme": result.get("readme"),  # Full README content
+                "data": result,  # Full response for advanced use
+            })
+
+        except Exception as e:
+            error_response = exception_to_structured_error(
+                e,
+                context={"tool": "ha_hacs_repository_info", "repository_id": repository_id},
+            )
+            if "error" in error_response and isinstance(error_response["error"], dict):
+                error_response["error"]["suggestions"] = [
+                    "Verify HACS is installed: https://hacs.xyz/",
+                    "Check repository ID format (e.g., 'hacs/integration' or 'owner/repo')",
+                    "Use ha_hacs_search() to find the correct repository ID",
+                ]
+            return await add_timezone_metadata(client, error_response)
+
+    @mcp.tool(annotations={"destructiveHint": True, "tags": ["hacs", "management"], "title": "Add HACS Repository"})
+    @log_tool_usage
+    async def ha_hacs_add_repository(
+        repository: str,
+        category: Annotated[
+            Literal["integration", "lovelace", "theme", "appdaemon", "python_script"],
+            Field(
+                description="Repository category (required)",
+            ),
+        ],
+    ) -> dict[str, Any]:
+        """Add a custom GitHub repository to HACS.
+
+        Allows adding custom repositories that are not in the default HACS store.
+        This is useful for:
+        - Adding custom integrations from GitHub
+        - Installing custom Lovelace cards
+        - Adding custom themes
+        - Installing beta/development versions
+
+        **Requirements:**
+        - Repository must be a valid GitHub repository
+        - Repository must follow HACS structure guidelines
+        - Category must match the repository type
+
+        **Examples:**
+        ```python
+        # Add custom integration
+        ha_hacs_add_repository("owner/custom-integration", category="integration")
+
+        # Add custom card
+        ha_hacs_add_repository("owner/custom-card", category="lovelace")
+
+        # Add custom theme
+        ha_hacs_add_repository("owner/custom-theme", category="theme")
+        ```
+
+        Args:
+            repository: GitHub repository in format "owner/repo"
+            category: Repository category (integration, lovelace, theme, appdaemon, python_script)
+
+        Returns:
+            Success status and repository ID if added successfully.
+        """
+        try:
+            # Check if HACS is available
+            is_available, error_msg = await _check_hacs_available(client)
+            if not is_available:
+                return await add_timezone_metadata(client, {
+                    "success": False,
+                    "error": error_msg,
+                    "error_code": "HACS_NOT_AVAILABLE",
+                    "suggestions": [
+                        "Install HACS from https://hacs.xyz/",
+                        "Ensure Home Assistant has been restarted after HACS installation",
+                        "Check Home Assistant logs for HACS errors",
+                    ],
+                })
+
+            # Validate repository format
+            if "/" not in repository:
+                return await add_timezone_metadata(client, {
+                    "success": False,
+                    "error": "Invalid repository format. Must be 'owner/repo'",
+                    "error_code": "INVALID_REPOSITORY_FORMAT",
+                    "suggestions": [
+                        "Use format: 'owner/repo' (e.g., 'hacs/integration')",
+                        "Check the repository exists on GitHub",
+                    ],
+                })
+
+            # Add repository via WebSocket
+            from ..client.websocket_client import get_websocket_client
+            ws_client = await get_websocket_client()
+
+            # Map user-friendly category to HACS internal name
+            hacs_category = CATEGORY_MAP.get(category, category)
+
+            response = await ws_client.send_command(
+                "hacs/repositories/add",
+                repository=repository,
+                category=hacs_category,
+            )
+
+            if not response.get("success"):
+                error_response = exception_to_structured_error(
+                    Exception(f"HACS add repository request failed: {response}"),
+                    context={
+                        "command": "hacs/repositories/add",
+                        "repository": repository,
+                        "category": category,
+                    },
+                )
+                return await add_timezone_metadata(client, error_response)
+
+            result = response.get("result", {})
+
+            return await add_timezone_metadata(client, {
+                "success": True,
+                "repository": repository,
+                "category": category,
+                "repository_id": result.get("id"),
+                "message": f"Successfully added {repository} to HACS",
+                "data": result,
+            })
+
+        except Exception as e:
+            error_response = exception_to_structured_error(
+                e,
+                context={
+                    "tool": "ha_hacs_add_repository",
+                    "repository": repository,
+                    "category": category,
+                },
+            )
+            if "error" in error_response and isinstance(error_response["error"], dict):
+                error_response["error"]["suggestions"] = [
+                    "Verify HACS is installed: https://hacs.xyz/",
+                    "Check repository format: 'owner/repo'",
+                    "Verify the repository exists on GitHub",
+                    "Ensure category matches repository type",
+                    "Check repository follows HACS guidelines: https://hacs.xyz/docs/publish/start",
+                ]
+            return await add_timezone_metadata(client, error_response)
+
+    @mcp.tool(annotations={"destructiveHint": True, "tags": ["hacs", "management"], "title": "Download/Install HACS Repository"})
+    @log_tool_usage
+    async def ha_hacs_download(
+        repository_id: str,
+        version: Annotated[
+            str | None,
+            Field(
+                default=None,
+                description="Specific version to install (e.g., 'v1.2.3'). If not specified, installs the latest version.",
+            ),
+        ] = None,
+    ) -> dict[str, Any]:
+        """Download and install a HACS repository.
+
+        This installs a repository from HACS to your Home Assistant instance.
+        For integrations, a restart of Home Assistant may be required after installation.
+
+        **Prerequisites:**
+        - The repository must already be in HACS (either from the default store or added via `ha_hacs_add_repository`)
+        - Use `ha_hacs_search()` or `ha_hacs_list_installed()` to find the repository ID
+
+        **Examples:**
+        ```python
+        # Install latest version of a repository
+        ha_hacs_download("441028036")
+
+        # Install specific version
+        ha_hacs_download("441028036", version="v2.0.0")
+
+        # Install by GitHub path (will look up the numeric ID)
+        ha_hacs_download("piitaya/lovelace-mushroom", version="v4.0.0")
+        ```
+
+        **Note:** For integrations, you may need to restart Home Assistant after installation.
+        For Lovelace cards, clear your browser cache to see the new card.
+
+        Args:
+            repository_id: Repository numeric ID or GitHub path (e.g., "441028036" or "owner/repo")
+            version: Specific version to install (optional, defaults to latest)
+
+        Returns:
+            Success status and installation details.
+        """
+        try:
+            # Check if HACS is available
+            is_available, error_msg = await _check_hacs_available(client)
+            if not is_available:
+                return await add_timezone_metadata(client, {
+                    "success": False,
+                    "error": error_msg,
+                    "error_code": "HACS_NOT_AVAILABLE",
+                    "suggestions": [
+                        "Install HACS from https://hacs.xyz/",
+                        "Ensure Home Assistant has been restarted after HACS installation",
+                        "Check Home Assistant logs for HACS errors",
+                    ],
+                })
+
+            from ..client.websocket_client import get_websocket_client
+            ws_client = await get_websocket_client()
+
+            # If repository_id contains a slash, it's a GitHub path - need to look up numeric ID
+            actual_id = repository_id
+            repo_name = repository_id
+            if "/" in repository_id:
+                # Look up the numeric ID from the repository list
+                list_response = await ws_client.send_command("hacs/repositories/list")
+                if list_response.get("success"):
+                    repos = list_response.get("result", [])
+                    for repo in repos:
+                        if repo.get("full_name", "").lower() == repository_id.lower():
+                            actual_id = str(repo.get("id"))
+                            repo_name = repo.get("name") or repository_id
+                            break
+                    else:
+                        return await add_timezone_metadata(client, {
+                            "success": False,
+                            "error": f"Repository '{repository_id}' not found in HACS",
+                            "error_code": "REPOSITORY_NOT_FOUND",
+                            "suggestions": [
+                                "Use ha_hacs_add_repository() to add the repository first",
+                                "Use ha_hacs_search() to find available repositories",
+                                "Check the repository name is correct (case-insensitive)",
+                            ],
+                        })
+
+            # Build download command parameters
+            download_kwargs: dict[str, Any] = {"repository": actual_id}
+            if version:
+                download_kwargs["version"] = version
+
+            # Download/install the repository
+            response = await ws_client.send_command("hacs/repository/download", **download_kwargs)
+
+            if not response.get("success"):
+                error_response = exception_to_structured_error(
+                    Exception(f"HACS download request failed: {response}"),
+                    context={
+                        "command": "hacs/repository/download",
+                        "repository_id": repository_id,
+                        "version": version,
+                    },
+                )
+                return await add_timezone_metadata(client, error_response)
+
+            result = response.get("result", {})
+
+            return await add_timezone_metadata(client, {
+                "success": True,
+                "repository_id": actual_id,
+                "repository": repo_name,
+                "version": version or "latest",
+                "message": f"Successfully installed {repo_name}" + (f" version {version}" if version else ""),
+                "note": "For integrations, restart Home Assistant to activate. For Lovelace cards, clear browser cache.",
+                "data": result,
+            })
+
+        except Exception as e:
+            error_response = exception_to_structured_error(
+                e,
+                context={
+                    "tool": "ha_hacs_download",
+                    "repository_id": repository_id,
+                    "version": version,
+                },
+            )
+            if "error" in error_response and isinstance(error_response["error"], dict):
+                error_response["error"]["suggestions"] = [
+                    "Verify HACS is installed: https://hacs.xyz/",
+                    "Check repository ID is valid (use ha_hacs_search() to find it)",
+                    "Ensure the repository is in HACS (use ha_hacs_add_repository() if needed)",
+                    "Check version format (e.g., 'v1.2.3' or '1.2.3')",
+                ]
+            return await add_timezone_metadata(client, error_response)