fix: add blueprint/save step to ha_import_blueprint (#685) (#751)

ha_import_blueprint only called HA's blueprint/import WebSocket command,
which downloads and validates but does not persist the blueprint to disk.
This caused the tool to report success while the blueprint never appeared.

Changes:
- Call blueprint/save after blueprint/import to actually write to disk
- Fix metadata extraction (blueprint.metadata.name, not blueprint.name)
- Ensure suggested_filename always has .yaml extension
- Validate that import returns filename and raw data before saving
- Add e2e test verifying imported blueprints appear in the list

Closes #685

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: teh-hippo

src/ha_mcp/tools/tools_blueprints.py

@@ -248,18 +248,75 @@ async def ha_import_blueprint(
                     suggestions=suggestions,
                 ))
 
-            # Extract import result
+            # Extract import result (blueprint/import only validates, does not save)
             result_data = response.get("result", {})
+            suggested_filename = result_data.get("suggested_filename", "")
+            raw_data = result_data.get("raw_data", "")
+            blueprint_meta = result_data.get("blueprint", {}).get("metadata", {})
+            domain = blueprint_meta.get("domain", "automation")
+
+            if not suggested_filename or not raw_data:
+                raise_tool_error(create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    "Blueprint validated but no filename or YAML data was returned",
+                    context={"url": url},
+                    suggestions=[
+                        "This may indicate an incompatible blueprint format",
+                        "Try a different blueprint URL",
+                    ],
+                ))
+
+            # Ensure the path has a .yaml extension — HA's blueprint/import returns
+            # suggested_filename without the extension (e.g. "user/blueprint_name")
+            if not suggested_filename.endswith((".yaml", ".yml")):
+                suggested_filename = suggested_filename + ".yaml"
+
+            # Save the blueprint to disk (blueprint/import only validates)
+            save_response = await client.send_websocket_message(
+                {
+                    "type": "blueprint/save",
+                    "domain": domain,
+                    "path": suggested_filename,
+                    "yaml": raw_data,
+                    "source_url": url,
+                }
+            )
+
+            if not save_response.get("success"):
+                error = save_response.get("error", {})
+                save_error = (
+                    error.get("message", str(error))
+                    if isinstance(error, dict)
+                    else str(error)
+                )
+
+                suggestions = [
+                    "The blueprint was validated but could not be saved to disk",
+                    "Use ha_get_blueprint() to check if it already exists",
+                ]
+
+                if "already exists" in save_error.lower():
+                    suggestions.insert(0, "A blueprint with this path already exists")
+
+                raise_tool_error(create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    save_error,
+                    context={"url": url, "path": suggested_filename},
+                    suggestions=suggestions,
+                ))
+
+            save_result = save_response.get("result") or {}
 
             return {
                 "success": True,
                 "url": url,
                 "imported_blueprint": {
-                    "path": result_data.get("suggested_filename") or result_data.get("path"),
-                    "domain": result_data.get("blueprint", {}).get("domain", "automation"),
-                    "name": result_data.get("blueprint", {}).get("name"),
-                    "description": result_data.get("blueprint", {}).get("description"),
+                    "path": suggested_filename,
+                    "domain": domain,
+                    "name": blueprint_meta.get("name"),
+                    "description": blueprint_meta.get("description"),
                 },
+                "overrides_existing": save_result.get("overrides_existing", False),
                 "message": "Blueprint imported successfully. Use ha_get_blueprint() to see all installed blueprints.",
             }
 

tests/src/e2e/workflows/blueprints/test_blueprints.py

@@ -13,7 +13,12 @@
 
 import pytest
 
-from ...utilities.assertions import MCPAssertions, safe_call_tool, wait_for_automation
+from ...utilities.assertions import (
+    MCPAssertions,
+    _extract_error_message,
+    safe_call_tool,
+    wait_for_automation,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -231,6 +236,65 @@ async def test_import_blueprint_nonexistent_url(self, mcp_client):
             assert "suggestions" in result.get("error", {}), "Error response should include suggestions"
             logger.info("ha_import_blueprint properly handles non-existent URL")
 
+    @pytest.mark.slow
+    async def test_import_blueprint_saves_to_disk(self, mcp_client):
+        """
+        Test: Import blueprint actually saves to disk (issue #685)
+
+        Validates that ha_import_blueprint calls both blueprint/import (validate)
+        AND blueprint/save (persist), so the blueprint appears in the list.
+        Uses a known community blueprint that won't already be installed.
+        """
+        logger.info("Testing ha_import_blueprint saves blueprint to disk...")
+
+        # Use a community blueprint unlikely to be pre-installed
+        test_url = "https://gist.github.com/Blackshome/4010fb83bb8c19b5fa1425526c6ff0e2"
+
+        async with MCPAssertions(mcp_client) as mcp:
+            # List blueprints before import
+            before = await mcp.call_tool_success(
+                "ha_get_blueprint",
+                {"domain": "automation"},
+            )
+            before_paths = [bp["path"] for bp in before.get("blueprints", [])]
+
+            # Try to import
+            result = await safe_call_tool(
+                mcp_client,
+                "ha_import_blueprint",
+                {"url": test_url},
+            )
+
+            if result.get("success"):
+                # Import succeeded - verify metadata is populated
+                imported = result.get("imported_blueprint", {})
+                assert imported.get("path", "").endswith(".yaml"), \
+                    f"Blueprint path should end with .yaml, got: {imported.get('path')}"
+                assert imported.get("domain") in ("automation", "script"), \
+                    f"Blueprint domain should be automation or script, got: {imported.get('domain')}"
+                assert imported.get("name"), "Blueprint name should not be empty"
+                assert imported["path"] not in before_paths, \
+                    f"Blueprint {imported['path']} should not have existed before import"
+                logger.info(f"Blueprint imported: {imported.get('name')} at {imported.get('path')}")
+
+                # Verify it appears in the blueprint list
+                after = await mcp.call_tool_success(
+                    "ha_get_blueprint",
+                    {"domain": imported.get("domain", "automation")},
+                )
+                after_paths = [bp["path"] for bp in after.get("blueprints", [])]
+                assert imported["path"] in after_paths, \
+                    f"Imported blueprint {imported['path']} should appear in blueprint list"
+                logger.info("Blueprint appears in list after import")
+            else:
+                # Only acceptable failure is "already exists"
+                error_msg = _extract_error_message(result)
+                assert "already exists" in error_msg.lower(), \
+                    f"Expected 'already exists' error, got: {result}"
+                logger.info("Blueprint already existed (prior test run), still valid")
+
+            logger.info("ha_import_blueprint save-to-disk test completed")
+
 
 @pytest.mark.blueprint
 async def test_blueprint_discovery_workflow(mcp_client):