feat: Add domain filter and options support to ha_get_integration (#542)

* feat: Add domain filter and options support to ha_get_integration

Enhance ha_get_integration tool to expose config entry options (including
template sensor Jinja definitions) for auditing purposes.

Changes:
- Add `domain` parameter to filter entries by integration domain
- Add `include_options` parameter to include the options object in list responses
- Domain filter auto-enables options inclusion
- Update docstring with audit use case and template examples
- Add E2E tests for domain filtering, options inclusion, and specific entry retrieval

Closes #462

https://claude.ai/code/session_0189BzxxH6FEGSy5GhWdTKZA

* fix: Strengthen test_specific_entry_includes_options per review feedback

- Find an entry with non-empty options instead of picking an arbitrary one
- Assert that options field is present and matches the list endpoint data
- Skip test if no integrations with options exist in the test environment

https://claude.ai/code/session_0189BzxxH6FEGSy5GhWdTKZA

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: kingpanther13

src/ha_mcp/tools/tools_integrations.py

@@ -37,29 +37,57 @@ async def ha_get_integration(
                 default=None,
             ),
         ] = None,
+        domain: Annotated[
+            str | None,
+            Field(
+                description="Filter by integration domain (e.g. 'template', 'group'). "
+                "When set, includes the full options/configuration for each entry.",
+                default=None,
+            ),
+        ] = None,
+        include_options: Annotated[
+            bool | str,
+            Field(
+                description="Include the options object for each entry. "
+                "Automatically enabled when domain filter is set. "
+                "Useful for auditing template definitions and helper configurations.",
+                default=False,
+            ),
+        ] = False,
     ) -> dict[str, Any]:
         """
         Get integration (config entry) information - list all or get a specific one.
 
-        Without an entry_id: Lists all configured integrations with optional fuzzy search.
-        With an entry_id: Returns detailed information about a specific config entry.
+        Without an entry_id: Lists all configured integrations with optional filters.
+        With an entry_id: Returns detailed information including full options/configuration.
+
+        Use this to audit existing configurations (e.g. template sensor Jinja code).
+        When creating new functionality, prefer UI-based helpers over templates when possible.
 
         EXAMPLES:
         - List all integrations: ha_get_integration()
         - Search integrations: ha_get_integration(query="zigbee")
         - Get specific entry: ha_get_integration(entry_id="abc123")
+        - List template entries with definitions: ha_get_integration(domain="template")
+        - List all with options: ha_get_integration(include_options=True)
 
         STATES: 'loaded' (running), 'setup_error', 'setup_retry', 'not_loaded',
         'failed_unload', 'migration_error'.
 
         RETURNS (when listing):
         - entries: List of integrations with domain, title, state, capabilities
         - state_summary: Count of entries in each state
+        - When domain filter or include_options is set, each entry includes the 'options' object
 
         RETURNS (when getting specific entry):
-        - entry: Full config entry details
+        - entry: Full config entry details including options/configuration
         """
         try:
+            include_opts = coerce_bool_param(include_options, "include_options", default=False)
+            # Auto-enable options when domain filter is set
+            if domain is not None:
+                include_opts = True
+
             # If entry_id provided, get specific config entry
             if entry_id is not None:
                 try:
@@ -91,6 +119,11 @@ async def ha_get_integration(
 
             entries = response
 
+            # Apply domain filter before formatting
+            if domain:
+                domain_lower = domain.strip().lower()
+                entries = [e for e in entries if e.get("domain", "").lower() == domain_lower]
+
             # Format entries for response
             formatted_entries = []
             for entry in entries:
@@ -105,6 +138,10 @@ async def ha_get_integration(
                     "disabled_by": entry.get("disabled_by"),
                 }
 
+                # Include options when requested (for auditing template definitions, etc.)
+                if include_opts:
+                    formatted_entry["options"] = entry.get("options", {})
+
                 # Include pref_disable_new_entities and pref_disable_polling if present
                 if "pref_disable_new_entities" in entry:
                     formatted_entry["pref_disable_new_entities"] = entry[
@@ -152,13 +189,16 @@ async def ha_get_integration(
                 state = entry.get("state", "unknown")
                 state_summary[state] = state_summary.get(state, 0) + 1
 
-            return {
+            result_data: dict[str, Any] = {
                 "success": True,
                 "total": len(formatted_entries),
                 "entries": formatted_entries,
                 "state_summary": state_summary,
                 "query": query if query else None,
             }
+            if domain:
+                result_data["domain_filter"] = domain.strip().lower()
+            return result_data
 
         except Exception as e:
             logger.error(f"Failed to get integrations: {e}")

tests/src/e2e/workflows/integrations/test_list_integrations.py

@@ -236,6 +236,128 @@ async def test_entry_details(self, mcp_client):
         logger.info(f"All {data['total']} entries have valid structure")
 
 
+@pytest.mark.integrations
+class TestIntegrationFiltering:
+    """Test integration domain filtering and options inclusion."""
+
+    async def test_filter_by_domain(self, mcp_client):
+        """
+        Test: Filter integrations by domain.
+
+        Verifies that the domain parameter filters entries correctly
+        and auto-includes the options object.
+        """
+        logger.info("Testing ha_get_integration with domain filter...")
+
+        # First get all integrations to find a valid domain
+        all_result = await mcp_client.call_tool("ha_get_integration", {})
+        all_data = assert_mcp_success(all_result, "get all integrations")
+
+        if all_data["total"] == 0:
+            pytest.skip("No integrations available to test domain filter")
+
+        # Pick a domain that exists
+        test_domain = all_data["entries"][0]["domain"]
+
+        result = await mcp_client.call_tool(
+            "ha_get_integration", {"domain": test_domain}
+        )
+        data = assert_mcp_success(result, f"filter by domain {test_domain}")
+
+        assert data["total"] > 0, f"Expected entries for domain {test_domain}"
+        assert data.get("domain_filter") == test_domain
+
+        # All entries should be the filtered domain
+        for entry in data["entries"]:
+            assert entry["domain"] == test_domain, (
+                f"Expected domain {test_domain}, got {entry['domain']}"
+            )
+
+        # Domain filter auto-enables options inclusion
+        for entry in data["entries"]:
+            assert "options" in entry, "Domain filter should include options"
+
+        logger.info(f"Domain filter test passed: {data['total']} {test_domain} entries")
+
+    async def test_filter_by_nonexistent_domain(self, mcp_client):
+        """
+        Test: Filter by domain that doesn't exist returns empty results.
+        """
+        result = await mcp_client.call_tool(
+            "ha_get_integration", {"domain": "nonexistent_domain_xyz"}
+        )
+        data = assert_mcp_success(result, "filter by nonexistent domain")
+
+        assert data["total"] == 0, "Should have 0 results for nonexistent domain"
+        assert len(data["entries"]) == 0
+
+    async def test_include_options_flag(self, mcp_client):
+        """
+        Test: include_options parameter includes options in list response.
+        """
+        logger.info("Testing ha_get_integration with include_options=True...")
+
+        result = await mcp_client.call_tool(
+            "ha_get_integration", {"include_options": True}
+        )
+        data = assert_mcp_success(result, "list with include_options")
+
+        if data["total"] == 0:
+            pytest.skip("No integrations available")
+
+        # All entries should have options field
+        for entry in data["entries"]:
+            assert "options" in entry, "include_options should add options field"
+
+        logger.info(f"include_options test passed: {data['total']} entries with options")
+
+    async def test_specific_entry_includes_options(self, mcp_client):
+        """
+        Test: Getting a specific entry by entry_id returns full data including options.
+
+        This validates the audit use case from issue #462 - being able to
+        retrieve template definitions and other config entry options.
+        """
+        logger.info("Testing specific entry includes options...")
+
+        # Find an entry that actually has options to validate the audit use case
+        list_result = await mcp_client.call_tool(
+            "ha_get_integration", {"include_options": True}
+        )
+        list_data = assert_mcp_success(list_result, "list with options")
+
+        target_entry = next(
+            (e for e in list_data["entries"] if e.get("options")), None
+        )
+        if not target_entry:
+            pytest.skip("No integrations with non-empty options found")
+
+        entry_id = target_entry["entry_id"]
+
+        result = await mcp_client.call_tool(
+            "ha_get_integration", {"entry_id": entry_id}
+        )
+        data = assert_mcp_success(result, "get specific entry")
+
+        assert "entry" in data, "Should have entry data"
+        entry = data["entry"]
+
+        # The raw REST API response should include these fields
+        assert "entry_id" in entry
+        assert "domain" in entry
+
+        # Verify options are present and match what the list endpoint returned
+        assert "options" in entry, "Specific entry should include options"
+        assert entry["options"] == target_entry["options"], (
+            "Options from specific entry should match list endpoint"
+        )
+
+        logger.info(
+            f"Specific entry test passed: domain={entry.get('domain')}, "
+            f"options_keys={list(entry['options'].keys())}"
+        )
+
+
 @pytest.mark.integrations
 async def test_integration_discovery(mcp_client):
     """