feat: consolidate duplicate tools (108 → 105 tools) (#423)

Consolidating system info and blueprint tools to reduce tool count from 108 to 105 decorated tools (100 at runtime).

Changes:
- Merged ha_get_system_info and ha_get_system_version into ha_get_overview
- Merged ha_list_blueprints into ha_get_blueprint with optional path parameter
- Added tool count limit test (max 105 decorated tools)
- Updated all E2E tests

Related: #420, #424

Author: julienld

src/ha_mcp/tools/tools_blueprints.py

@@ -18,105 +18,53 @@
 def register_blueprint_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register Home Assistant blueprint management tools."""
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["blueprint"], "title": "List Blueprints"})
-    @log_tool_usage
-    async def ha_list_blueprints(
-        domain: Annotated[
-            str,
-            Field(
-                description="Blueprint domain: 'automation' or 'script'",
-                default="automation",
-            ),
-        ] = "automation",
-    ) -> dict[str, Any]:
-        """
-        List installed blueprints for a specific domain.
+    def _format_blueprint_list(blueprints_data: dict[str, Any], domain: str) -> dict[str, Any]:
+        """Format blueprint data into list response structure.
 
-        Returns all blueprints available in Home Assistant for the specified domain,
-        including their paths and metadata.
-
-        EXAMPLES:
-        - List automation blueprints: ha_list_blueprints("automation")
-        - List script blueprints: ha_list_blueprints("script")
+        Args:
+            blueprints_data: Raw blueprint data from WebSocket API
+            domain: Blueprint domain (automation or script)
 
-        RETURNS:
-        - List of blueprints with path, name, and domain information
-        - Each blueprint includes its relative path for use with ha_get_blueprint
+        Returns:
+            Formatted response with blueprints list, count, and domain
         """
-        try:
-            # Validate domain
-            valid_domains = ["automation", "script"]
-            if domain not in valid_domains:
-                return {
-                    "success": False,
-                    "error": f"Invalid domain '{domain}'. Must be one of: {', '.join(valid_domains)}",
-                    "valid_domains": valid_domains,
-                }
-
-            # Send WebSocket command to list blueprints
-            response = await client.send_websocket_message(
-                {"type": "blueprint/list", "domain": domain}
-            )
-
-            if not response.get("success"):
-                return {
-                    "success": False,
-                    "error": response.get("error", "Failed to list blueprints"),
-                    "domain": domain,
-                }
-
-            # Process the blueprint list
-            blueprints_data = response.get("result", {})
-
-            # Convert to a more usable format
-            blueprints = []
-            for path, metadata in blueprints_data.items():
-                blueprint_info = {
-                    "path": path,
-                    "domain": domain,
-                    "name": metadata.get("name", path.split("/")[-1].replace(".yaml", "")),
-                }
-
-                # Add optional metadata if available
-                if "metadata" in metadata:
-                    meta = metadata["metadata"]
-                    blueprint_info.update({
-                        "description": meta.get("description"),
-                        "source_url": meta.get("source_url"),
-                        "author": meta.get("author"),
-                    })
-
-                blueprints.append(blueprint_info)
-
-            return {
-                "success": True,
+        blueprints = []
+        for bp_path, metadata in blueprints_data.items():
+            blueprint_info = {
+                "path": bp_path,
                 "domain": domain,
-                "count": len(blueprints),
-                "blueprints": blueprints,
+                "name": metadata.get("name", bp_path.split("/")[-1].replace(".yaml", "")),
             }
 
-        except Exception as e:
-            logger.error(f"Error listing blueprints: {e}")
-            return {
-                "success": False,
-                "domain": domain,
-                "error": str(e),
-                "suggestions": [
-                    "Verify Home Assistant connection",
-                    "Check if blueprint integration is enabled",
-                    f"Use domain 'automation' or 'script' (got '{domain}')",
-                ],
-            }
+            # Add optional metadata if available
+            if "metadata" in metadata:
+                meta = metadata["metadata"]
+                blueprint_info.update({
+                    "description": meta.get("description"),
+                    "source_url": meta.get("source_url"),
+                    "author": meta.get("author"),
+                })
+
+            blueprints.append(blueprint_info)
+
+        return {
+            "success": True,
+            "domain": domain,
+            "count": len(blueprints),
+            "blueprints": blueprints,
+        }
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["blueprint"], "title": "Get Blueprint Details"})
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["blueprint"], "title": "Get Blueprint"})
     @log_tool_usage
     async def ha_get_blueprint(
         path: Annotated[
-            str,
+            str | None,
             Field(
-                description="Blueprint path (e.g., 'homeassistant/motion_light.yaml' or 'custom/my_blueprint.yaml')"
+                description="Blueprint path to get details for (e.g., 'homeassistant/motion_light.yaml'). "
+                "If omitted, lists all blueprints in the domain.",
+                default=None,
             ),
-        ],
+        ] = None,
         domain: Annotated[
             str,
             Field(
@@ -126,17 +74,22 @@ async def ha_get_blueprint(
         ] = "automation",
     ) -> dict[str, Any]:
         """
-        Get detailed information about a specific blueprint.
+        Get blueprint information - list all blueprints or get details for a specific one.
 
-        Retrieves the full blueprint configuration including inputs, triggers,
-        conditions, and actions. Use this to understand what a blueprint does
-        and what inputs it requires.
+        Without a path: Lists all installed blueprints for the specified domain.
+        With a path: Retrieves full blueprint configuration including inputs, triggers,
+        conditions, and actions.
 
         EXAMPLES:
-        - Get automation blueprint: ha_get_blueprint("homeassistant/motion_light.yaml", "automation")
-        - Get script blueprint: ha_get_blueprint("custom/backup_script.yaml", "script")
+        - List all automation blueprints: ha_get_blueprint(domain="automation")
+        - List script blueprints: ha_get_blueprint(domain="script")
+        - Get specific blueprint: ha_get_blueprint(path="homeassistant/motion_light.yaml", domain="automation")
 
-        RETURNS:
+        RETURNS (when listing):
+        - List of blueprints with path, name, and domain information
+        - Count of blueprints found
+
+        RETURNS (when getting specific blueprint):
         - Blueprint metadata (name, description, author, source_url)
         - Input definitions with selectors and defaults
         - Blueprint configuration (triggers, conditions, actions for automations; sequence for scripts)
@@ -151,22 +104,25 @@ async def ha_get_blueprint(
                     "valid_domains": valid_domains,
                 }
 
-            # First, list blueprints to check if path exists
+            # Get list of blueprints
             list_response = await client.send_websocket_message(
                 {"type": "blueprint/list", "domain": domain}
             )
 
             if not list_response.get("success"):
                 return {
                     "success": False,
-                    "error": "Failed to query blueprints",
-                    "path": path,
+                    "error": list_response.get("error", "Failed to query blueprints"),
                     "domain": domain,
                 }
 
             blueprints_data = list_response.get("result", {})
 
-            # Check if blueprint exists
+            # If no path provided, return list of all blueprints
+            if path is None:
+                return _format_blueprint_list(blueprints_data, domain)
+
+            # Path provided - get specific blueprint details
             if path not in blueprints_data:
                 available_paths = list(blueprints_data.keys())[:10]
                 return {
@@ -176,7 +132,7 @@ async def ha_get_blueprint(
                     "domain": domain,
                     "available_blueprints": available_paths,
                     "suggestions": [
-                        "Use ha_list_blueprints() to see available blueprints",
+                        "Use ha_get_blueprint() without path to see all available blueprints",
                         "Check the path format (e.g., 'homeassistant/motion_light.yaml')",
                     ],
                 }
@@ -223,7 +179,7 @@ async def ha_get_blueprint(
                 "error": str(e),
                 "suggestions": [
                     "Verify the blueprint path is correct",
-                    "Use ha_list_blueprints() to find available blueprints",
+                    "Use ha_get_blueprint() without path to see available blueprints",
                     "Check Home Assistant connection",
                 ],
             }
@@ -284,7 +240,7 @@ async def ha_import_blueprint(
                 ]
 
                 if "already exists" in str(error_msg).lower():
-                    suggestions.insert(0, "Blueprint already exists - use ha_list_blueprints() to see installed blueprints")
+                    suggestions.insert(0, "Blueprint already exists - use ha_get_blueprint() to see installed blueprints")
 
                 return {
                     "success": False,
@@ -305,7 +261,7 @@ async def ha_import_blueprint(
                     "name": result_data.get("blueprint", {}).get("name"),
                     "description": result_data.get("blueprint", {}).get("description"),
                 },
-                "message": "Blueprint imported successfully. Use ha_list_blueprints() to see all installed blueprints.",
+                "message": "Blueprint imported successfully. Use ha_get_blueprint() to see all installed blueprints.",
             }
 
         except Exception as e:

src/ha_mcp/tools/tools_search.py

@@ -449,7 +449,8 @@ async def ha_get_overview(
         )
         result = cast(dict[str, Any], result)
 
-        # Include system info in the overview
+        # Include comprehensive system info in the overview
+        # This replaces the deprecated ha_get_system_info and ha_get_system_version tools
         try:
             config = await client.get_config()
             result["system_info"] = {
@@ -464,6 +465,15 @@ async def ha_get_overview(
                 "latitude": config.get("latitude"),
                 "longitude": config.get("longitude"),
                 "elevation": config.get("elevation"),
+                "config_dir": config.get("config_dir"),
+                "allowlist_external_dirs": config.get("allowlist_external_dirs", []),
+                "allowlist_external_urls": config.get("allowlist_external_urls", []),
+                "components": config.get("components", []),
+                "components_loaded": len(config.get("components", [])),
+                "state": config.get("state"),
+                "safe_mode": config.get("safe_mode", False),
+                "internal_url": config.get("internal_url"),
+                "external_url": config.get("external_url"),
             }
         except Exception as e:
             logger.warning(f"Failed to fetch system info for overview: {e}")

src/ha_mcp/tools/tools_system.py

@@ -304,50 +304,6 @@ async def ha_reload_core(
                 ],
             }
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["system"], "title": "Get System Info"})
-    @log_tool_usage
-    async def ha_get_system_info() -> dict[str, Any]:
-        """
-        Get Home Assistant system information.
-
-        Returns version, location settings, timezone, loaded components, and configuration paths.
-        """
-        try:
-            config = await client.get_config()
-
-            # Extract relevant system information
-            system_info = {
-                "success": True,
-                "version": config.get("version"),
-                "location_name": config.get("location_name"),
-                "time_zone": config.get("time_zone"),
-                "unit_system": config.get("unit_system", {}),
-                "latitude": config.get("latitude"),
-                "longitude": config.get("longitude"),
-                "elevation": config.get("elevation"),
-                "currency": config.get("currency"),
-                "country": config.get("country"),
-                "language": config.get("language"),
-                "config_dir": config.get("config_dir"),
-                "allowlist_external_dirs": config.get("allowlist_external_dirs", []),
-                "allowlist_external_urls": config.get("allowlist_external_urls", []),
-                "components": config.get("components", []),
-                "component_count": len(config.get("components", [])),
-                "state": config.get("state"),
-                "safe_mode": config.get("safe_mode", False),
-                "internal_url": config.get("internal_url"),
-                "external_url": config.get("external_url"),
-            }
-
-            return system_info
-
-        except Exception as e:
-            logger.error(f"Failed to get system info: {e}")
-            return {
-                "success": False,
-                "error": f"Failed to get system info: {str(e)}",
-            }
-
     @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["system"], "title": "Get System Health"})
     @log_tool_usage
     async def ha_get_system_health() -> dict[str, Any]:
@@ -396,7 +352,7 @@ async def ha_get_system_health() -> dict[str, Any]:
                 "error": f"Failed to get system health: {str(e)}",
                 "suggestions": [
                     "System health may not be available in all HA installations",
-                    "Try ha_get_system_info() for basic system information",
+                    "Try ha_get_overview() for basic system information",
                 ],
             }
         finally:

src/ha_mcp/tools/tools_updates.py

@@ -271,76 +271,6 @@ async def ha_get_release_notes(
                 "error": f"Failed to get release notes: {str(e)}",
             }
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["system"], "title": "Get System Version"})
-    @log_tool_usage
-    async def ha_get_system_version() -> dict[str, Any]:
-        """
-        Get Home Assistant version and basic system information.
-
-        Returns current version, installation type, and system details.
-        Useful for:
-        - Checking current version before updates
-        - Verifying update success
-        - Compatibility checks for integrations
-        - Debugging system configuration
-
-        Returns:
-            Dictionary containing:
-            - version: Current Home Assistant Core version
-            - location_name: Configured location name
-            - config_dir: Configuration directory path
-            - timezone: System timezone
-            - components_loaded: Number of loaded components
-            - unit_system: Metric or imperial
-            - internal_url: Internal access URL (if configured)
-            - external_url: External access URL (if configured)
-        """
-        try:
-            # Get configuration via REST API
-            config = await client.get_config()
-
-            # Extract relevant information
-            version_info = {
-                "success": True,
-                "version": config.get("version"),
-                "location_name": config.get("location_name"),
-                "config_dir": config.get("config_dir"),
-                "timezone": config.get("time_zone"),
-                "elevation": config.get("elevation"),
-                "latitude": config.get("latitude"),
-                "longitude": config.get("longitude"),
-                "unit_system": config.get("unit_system", {}).get(
-                    "temperature", "unknown"
-                ),
-                "components_loaded": len(config.get("components", [])),
-                "allowlist_external_dirs": config.get("allowlist_external_dirs", []),
-                "allowlist_external_urls": config.get("allowlist_external_urls", []),
-                "internal_url": config.get("internal_url"),
-                "external_url": config.get("external_url"),
-                "currency": config.get("currency"),
-                "country": config.get("country"),
-                "language": config.get("language"),
-                "safe_mode": config.get("safe_mode", False),
-                "state": config.get("state"),
-            }
-
-            # Clean up None values
-            version_info = {k: v for k, v in version_info.items() if v is not None}
-
-            return version_info
-
-        except Exception as e:
-            logger.error(f"Failed to get system version: {e}")
-            return {
-                "success": False,
-                "error": f"Failed to get system version: {str(e)}",
-                "suggestions": [
-                    "Check Home Assistant connection",
-                    "Verify API access permissions",
-                ],
-            }
-
-
 def _supports_release_notes(entity_id: str, attributes: dict[str, Any]) -> bool:
     """
     Determine if an update entity supports fetching release notes.