feat: add ha_call_event tool for publishing events on the HA event bus (#996) (#1239)

* feat: add ha_fire_event tool for firing events on the HA event bus (#996)

* refactor(internal): add fire verb to approved list, add Caveats to docstring (#996)

- Add `fire` verb to AGENTS.md approved-verb list as Gemini suggested
- Add Caveats section to ha_fire_event docstring: events are fire-and-forget

* fix: set destructiveHint=True on ha_fire_event and remove unused import

- ha_fire_event fires events with side effects (triggers automations,
  subscribers) so destructiveHint=True is correct; False was bypassing
  the annotation compliance test
- Remove unused safe_call_tool import from test_ha_fire_event.py (ruff F401)

* fix: align ha_fire_event data parsing with repo error-handling pattern

- Wrap parse_json_param in try/except ValueError → raise_tool_error with
  invalid_json=True, matching _parse_service_data and ha_bulk_control
- Declare parsed_data before the inner try block (repo variable-init rule)
- Replace cast(dict, raw) with direct isinstance check + explicit assignment;
  include details=f"Received type: {type(raw).__name__}" in the validation error
- Add unit test: test_raises_tool_error_on_invalid_json_string covers the
  new ValueError → ToolError path (was previously untested)

Addresses Gemini code-review comment on PR #1239.

* refactor(internal): rename ha_fire_event -> ha_call_event, revert fire verb

Per maintainer feedback: use the existing `call` verb for consistency with
ha_call_service rather than introducing a new `fire` verb. No behavior
change; only the tool name, method name, test files, and AGENTS.md entry
are updated.

* test(internal): address all CHANGES_REQUESTED items on ha_call_event PR

- Rename ha_fire_event → ha_call_event in tools_service.py; update
  docstring verb to 'Execute'; revert 'fire' from approved verbs list
- Add event_type validation: reject empty/whitespace and path-separator
  values before the wire call (fixes malformed URL at POST /api/events/)
- Mirror HomeAssistantConnectionError + httpx.TimeoutException handling
  from ha_call_service: return partial-success instead of raising
- Unit tests: fix broken ha_fire_event call, remove duplicate method,
  strengthen assertions (event_type + success fields), add 4 new tests
  (empty type, whitespace type, slash in type, ToolError re-raise)
- E2E tests: drop test_call_builtin_event_type (fires homeassistant_start
  mid-suite, pollutes later tests); add test_call_event_delivery_verified
  using input_boolean + event-triggered automation to prove end-to-end
  delivery through the HA event bus

Author: SealKan

AGENTS.md

@@ -507,7 +507,7 @@ These feed the picker tiles in the markup section AND the wizard `<script>` bloc
 - `set` — create/update (`ha_config_set_helper`)
 - `delete` — delete dashboards, config entries, or files (`ha_config_delete_dashboard`, `ha_delete_file`)
 - `remove` — remove registry items (`ha_remove_entity`, `ha_remove_area_or_floor`)
-- `call` — execute (`ha_call_service`)
+- `call` — execute (`ha_call_service`, `ha_call_event`)
 - `manage` — multi-modal tools combining several operations behind one interface (`ha_manage_addon`)
 
 **Namespace prefixes**: An optional `<namespace>_` prefix between `ha_` and the verb is allowed for grouped tool families that share a domain. The full shape becomes `ha_<namespace>_<verb>_<noun>`:

src/ha_mcp/tools/tools_service.py

@@ -431,6 +431,115 @@ async def ha_bulk_control(
         )
         return cast(dict[str, Any], result)
 
+    @tool(
+        name="ha_call_event",
+        tags={"Service & Device Control"},
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": False,
+            "title": "Call Event",
+        },
+    )
+    @log_tool_usage
+    async def ha_call_event(
+        self,
+        event_type: str,
+        data: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Execute a custom event on the Home Assistant event bus.
+
+        When NOT to use: for controlling entities (lights, switches, climate) — use
+        ha_call_service instead. For triggering automations by name, use
+        ha_call_service("automation", "trigger").
+
+        Use this to publish custom event types consumed by event-triggered automations,
+        Node-RED flows, or custom integrations that subscribe to specific event types.
+
+        Caveats: Events are fire-and-forget; this tool confirms the event was accepted
+        by the bus but does not verify whether any automation or subscriber acted on it.
+        """
+        # Validate event_type before hitting the wire — empty strings or path separators
+        # produce malformed URLs at POST /api/events/{event_type}.
+        if not event_type or not event_type.strip():
+            raise_tool_error(
+                create_validation_error(
+                    "event_type cannot be empty or whitespace",
+                    parameter="event_type",
+                )
+            )
+        if "/" in event_type or "\\" in event_type:
+            raise_tool_error(
+                create_validation_error(
+                    "event_type cannot contain path separators",
+                    parameter="event_type",
+                    details=f"Received: {event_type!r}",
+                )
+            )
+
+        parsed_data: dict[str, Any] | None = None
+        if data is not None:
+            raw: Any = None
+            try:
+                raw = parse_json_param(data, "data")
+            except ValueError as e:
+                raise_tool_error(
+                    create_validation_error(
+                        f"Invalid data parameter: {e}",
+                        parameter="data",
+                        invalid_json=True,
+                    )
+                )
+            if raw is not None:
+                if not isinstance(raw, dict):
+                    raise_tool_error(
+                        create_validation_error(
+                            "Event data must be a JSON object (dict)",
+                            parameter="data",
+                            details=f"Received type: {type(raw).__name__}",
+                        )
+                    )
+                parsed_data = raw
+
+        try:
+            response = await self._client.fire_event(event_type, parsed_data)
+        except HomeAssistantConnectionError as error:
+            if isinstance(error.__cause__, httpx.TimeoutException):
+                return {
+                    "success": True,
+                    "partial": True,
+                    "event_type": event_type,
+                    "message": (
+                        f"Event {event_type} was dispatched but Home Assistant "
+                        "did not respond within the timeout period."
+                    ),
+                    "warning": (
+                        "Response timed out. The event was dispatched and may still "
+                        "have been delivered to subscribers."
+                    ),
+                }
+            exception_to_structured_error(
+                error,
+                context={"event_type": event_type},
+                suggestions=["Check Home Assistant connection"],
+            )
+        except ToolError:
+            raise
+        except Exception as e:
+            exception_to_structured_error(
+                e,
+                context={"event_type": event_type},
+                suggestions=[
+                    "Check Home Assistant connection",
+                    "Verify event_type is a valid identifier",
+                ],
+            )
+
+        return {
+            "success": True,
+            "event_type": event_type,
+            "message": response.get("message", f"Event {event_type} fired."),
+        }
+
 
 def register_service_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register service call and operation monitoring tools with the MCP server."""

tests/src/e2e/tools/test_ha_call_event.py

@@ -0,0 +1,156 @@
+"""
+E2E tests for ha_call_event tool - publish events onto the HA event bus.
+"""
+
+import logging
+import uuid
+
+import pytest
+from fastmcp.exceptions import ToolError
+
+from ..utilities.assertions import assert_mcp_success, wait_for_automation
+from ..utilities.wait_helpers import wait_for_entity_state
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.mark.asyncio
+async def test_call_event_no_data(mcp_client):
+    """Publish a custom event without event data."""
+    result = await mcp_client.call_tool(
+        "ha_call_event",
+        {"event_type": "test_mcp_event_no_data"},
+    )
+    data = assert_mcp_success(result, "call event without data")
+    assert data["success"] is True
+    assert data["event_type"] == "test_mcp_event_no_data"
+    assert "message" in data
+    logger.info("Called event without data: %s", data)
+
+
+@pytest.mark.asyncio
+async def test_call_event_with_dict_data(mcp_client):
+    """Publish a custom event with dict event data."""
+    result = await mcp_client.call_tool(
+        "ha_call_event",
+        {"event_type": "test_mcp_event_with_data", "data": {"key": "value", "count": 1}},
+    )
+    data = assert_mcp_success(result, "call event with dict data")
+    assert data["success"] is True
+    assert data["event_type"] == "test_mcp_event_with_data"
+    logger.info("Called event with dict data: %s", data)
+
+
+@pytest.mark.asyncio
+async def test_call_event_with_json_string_data(mcp_client):
+    """Publish a custom event with JSON-string event data (auto-parsed)."""
+    result = await mcp_client.call_tool(
+        "ha_call_event",
+        {"event_type": "test_mcp_event_json_str", "data": '{"source": "e2e_test"}'},
+    )
+    data = assert_mcp_success(result, "call event with JSON string data")
+    assert data["success"] is True
+    assert data["event_type"] == "test_mcp_event_json_str"
+    logger.info("Called event with JSON string data: %s", data)
+
+
+@pytest.mark.asyncio
+async def test_call_event_list_data_rejected(mcp_client):
+    """Event data must be a dict — a JSON array is rejected with ToolError."""
+    with pytest.raises(ToolError):
+        await mcp_client.call_tool(
+            "ha_call_event",
+            {"event_type": "test_mcp_event_bad_data", "data": "[1, 2, 3]"},
+        )
+
+
+@pytest.mark.asyncio
+async def test_call_event_delivery_verified(mcp_client):
+    """Prove that ha_call_event delivers events to HA subscribers end-to-end.
+
+    Creates an input_boolean flag and an automation that turns it on when the
+    custom event fires. After calling ha_call_event, polls until the flag
+    reaches 'on', confirming event delivery through the HA event bus.
+    """
+    suffix = uuid.uuid4().hex[:8]
+    event_type = f"test_mcp_event_delivery_{suffix}"
+    boolean_id = None
+    automation_id = None
+
+    # 1. Create input_boolean flag (starts 'off')
+    boolean_result = await mcp_client.call_tool(
+        "ha_config_set_helper",
+        {"helper_type": "input_boolean", "name": f"e2e event delivery {suffix}"},
+    )
+    boolean_data = assert_mcp_success(boolean_result, "Create input_boolean flag")
+    boolean_id = (
+        boolean_data.get("entity_id")
+        or f"input_boolean.{boolean_data['helper_data']['id']}"
+    )
+    logger.info("Created flag entity: %s", boolean_id)
+
+    try:
+        # 2. Create automation: event trigger → turn on the flag
+        automation_config = {
+            "alias": f"e2e event delivery {suffix}",
+            "trigger": [{"platform": "event", "event_type": event_type}],
+            "action": [
+                {
+                    "service": "input_boolean.turn_on",
+                    "target": {"entity_id": boolean_id},
+                }
+            ],
+        }
+        create_result = await mcp_client.call_tool(
+            "ha_config_set_automation",
+            {"config": automation_config},
+        )
+        create_data = assert_mcp_success(create_result, "Create delivery-probe automation")
+        automation_id = create_data.get("entity_id") or create_data.get("automation_id")
+        logger.info("Created automation: %s", automation_id)
+
+        # 3. Wait for automation to be fully registered before firing
+        config = await wait_for_automation(mcp_client, automation_id, timeout=15)
+        assert config is not None, f"Automation {automation_id} not registered within 15s"
+
+        # 4. Fire the event via ha_call_event
+        event_result = await mcp_client.call_tool(
+            "ha_call_event",
+            {"event_type": event_type},
+        )
+        data = assert_mcp_success(event_result, "fire custom event")
+        assert data["success"] is True
+        assert data["event_type"] == event_type
+        logger.info("Fired event %r: %s", event_type, data)
+
+        # 5. Wait for flag to flip 'on' — proves event reached the bus
+        state_reached = await wait_for_entity_state(
+            mcp_client, boolean_id, "on", timeout=15
+        )
+        assert state_reached, (
+            f"Event {event_type!r} was not delivered: "
+            f"{boolean_id} did not reach 'on' within 15s"
+        )
+        logger.info("Event delivery verified: %s reached 'on'", boolean_id)
+
+    finally:
+        if automation_id:
+            try:
+                await mcp_client.call_tool(
+                    "ha_config_remove_automation",
+                    {"identifier": automation_id},
+                )
+            except Exception as exc:
+                logger.warning("Cleanup failed for automation %s: %s", automation_id, exc)
+        if boolean_id:
+            try:
+                await mcp_client.call_tool(
+                    "ha_delete_helpers_integrations",
+                    {
+                        "target": boolean_id,
+                        "helper_type": "input_boolean",
+                        "confirm": True,
+                    },
+                )
+            except Exception as exc:
+                logger.warning("Cleanup failed for helper %s: %s", boolean_id, exc)

tests/src/unit/test_ha_call_event.py

@@ -0,0 +1,98 @@
+"""Unit tests for ha_call_event tool."""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from fastmcp.exceptions import ToolError
+
+from ha_mcp.tools.tools_service import ServiceTools
+
+
+def _make_tools(fire_event_return: dict | Exception) -> ServiceTools:
+    client = MagicMock()
+    if isinstance(fire_event_return, Exception):
+        client.fire_event = AsyncMock(side_effect=fire_event_return)
+    else:
+        client.fire_event = AsyncMock(return_value=fire_event_return)
+    tools = ServiceTools.__new__(ServiceTools)
+    tools._client = client
+    tools._device_tools = MagicMock()
+    return tools
+
+
+class TestHaCallEvent:
+    async def test_fires_event_with_no_data(self):
+        tools = _make_tools({"message": "Event my_event fired."})
+        result = await tools.ha_call_event("my_event")
+        assert result["success"] is True
+        assert result["event_type"] == "my_event"
+        assert "fired" in result["message"]
+        tools._client.fire_event.assert_called_once_with("my_event", None)
+
+    async def test_fires_event_with_dict_data(self):
+        tools = _make_tools({"message": "Event custom_event fired."})
+        result = await tools.ha_call_event("custom_event", {"key": "value"})
+        assert result["success"] is True
+        assert result["event_type"] == "custom_event"
+        tools._client.fire_event.assert_called_once_with("custom_event", {"key": "value"})
+
+    async def test_fires_event_with_json_string_data(self):
+        tools = _make_tools({"message": "Event my_event fired."})
+        result = await tools.ha_call_event("my_event", '{"temperature": 22}')
+        assert result["success"] is True
+        assert result["event_type"] == "my_event"
+        tools._client.fire_event.assert_called_once_with("my_event", {"temperature": 22})
+
+    async def test_raises_tool_error_on_list_data(self):
+        tools = _make_tools({"message": "ok"})
+        with pytest.raises(ToolError):
+            await tools.ha_call_event("my_event", "[1, 2, 3]")
+
+    async def test_raises_tool_error_on_invalid_json_string(self):
+        """Invalid JSON raises ToolError via the ValueError → invalid_json path."""
+        tools = _make_tools({"message": "ok"})
+        with pytest.raises(ToolError):
+            await tools.ha_call_event("my_event", "{not valid json")
+
+    async def test_returns_fallback_message_when_response_empty(self):
+        tools = _make_tools({})
+        result = await tools.ha_call_event("my_event")
+        assert result["success"] is True
+        assert result["event_type"] == "my_event"
+        assert "my_event" in result["message"]
+
+    async def test_propagates_connection_error_as_tool_error(self):
+        tools = _make_tools(ConnectionError("HA unreachable"))
+        with pytest.raises(ToolError):
+            await tools.ha_call_event("my_event")
+
+    async def test_event_type_passed_to_client(self):
+        tools = _make_tools({"message": "Event zone_entered fired."})
+        await tools.ha_call_event("zone_entered", {"zone": "home"})
+        call_args = tools._client.fire_event.call_args
+        assert call_args[0][0] == "zone_entered"
+        assert call_args[0][1] == {"zone": "home"}
+
+    async def test_raises_tool_error_on_empty_event_type(self):
+        """Empty event_type is rejected before hitting the wire."""
+        tools = _make_tools({"message": "ok"})
+        with pytest.raises(ToolError):
+            await tools.ha_call_event("")
+
+    async def test_raises_tool_error_on_whitespace_event_type(self):
+        """Whitespace-only event_type is rejected before hitting the wire."""
+        tools = _make_tools({"message": "ok"})
+        with pytest.raises(ToolError):
+            await tools.ha_call_event("   ")
+
+    async def test_raises_tool_error_on_event_type_with_slash(self):
+        """event_type containing a slash produces a malformed URL — rejected early."""
+        tools = _make_tools({"message": "ok"})
+        with pytest.raises(ToolError):
+            await tools.ha_call_event("bad/event")
+
+    async def test_reraises_tool_error_from_client(self):
+        """ToolError from fire_event propagates unchanged (not swallowed by except Exception)."""
+        tools = _make_tools(ToolError("already structured"))
+        with pytest.raises(ToolError, match="already structured"):
+            await tools.ha_call_event("my_event")