[FEATURE] Expose ha_fire_event tool (POST /api/events/{event_type})

[Patch76]

What would you like to see?

A tool to fire custom Home Assistant events:

• ha_fire_event(event_type, data=None) — POST to /api/events/{event_type}

Why do you need this?

ha_call_service covers service calls, but firing a raw event is a distinct HA mechanism used for custom integrations, event-triggered automations, and inter-component signaling. There is no way to trigger homeassistant_start, call_api, or any custom event type through the current tool surface.

The underlying client method HomeAssistantClient.fire_event() is already implemented in rest_client.py — the MCP tool wrapper is the only missing piece.

Additional context

• REST endpoint: POST /api/events/{event_type} (stable public API)
• Existing client method: rest_client.py::fire_event() (line 324)
• Analogous to ha_call_service but for the event bus rather than the service layer

[github-actions]

I'll add the ha_fire_event method to the ServiceTools class in src/ha_mcp/tools/tools_service.py, following existing patterns and using parse_json_param for data validation as I've confirmed all necessary components are available.

🔍 Analysis

The request to expose the ha_fire_event tool is highly valid and aligns with the existing architecture of ha-mcp. The underlying fire_event method is already implemented in the HomeAssistantClient (in src/ha_mcp/client/rest_client.py:324), but it lacks the corresponding MCP tool wrapper to make it accessible to AI assistants.

Firing events is a fundamental Home Assistant mechanism, distinct from service calls, and is essential for triggering certain automations or signaling custom integrations. Adding this tool will provide the "missing piece" for comprehensive Home Assistant control as noted in the issue.

The implementation should be added to the ServiceTools class in src/ha_mcp/tools/tools_service.py, as this class already handles similar execution actions like ha_call_service.

🛠️ Suggested Steps

1. Add ha_fire_event method: Update src/ha_mcp/tools/tools_service.py to include the ha_fire_event method within the ServiceTools class, using the @tool decorator.
2. Use existing helpers: Leverage parse_json_param from util_helpers.py for robust JSON parsing of the data parameter, ensuring consistency with other tools.
3. Implement error handling: Use the standard exception_to_structured_error pattern to provide helpful suggestions if the event firing fails (e.g., due to invalid JSON or connection issues).
4. Verify via tool list: After implementation, verify that ha_fire_event appears in the tool surface by running the MCP server and inspecting the available tools.

📊 Technical Analysis (for maintainers)

Root Cause

The ha-mcp server provides high-level tool wrappers for most Home Assistant operations, but it currently lacks a wrapper for the REST API's event-firing endpoint (POST /api/events/{event_type}). While the low-level client logic exists, it isn't exposed to the MCP interface.

Affected Code

• src/ha_mcp/client/rest_client.py:324 - Contains the existing fire_event client method.
• src/ha_mcp/tools/tools_service.py - The location where ServiceTools are defined and where ha_fire_event should be added.

Proposed Fix

--- a/src/ha_mcp/tools/tools_service.py
+++ b/src/ha_mcp/tools/tools_service.py
@@ -213,6 +213,44 @@
                 },
                 suggestions=suggestions,
             )
+
+    @tool(name="ha_fire_event", tags={"Service & Device Control"}, annotations={"destructiveHint": True, "title": "Fire Event"})
+    @log_tool_usage
+    async def ha_fire_event(
+        self,
+        event_type: str,
+        data: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Fire a custom Home Assistant event on the event bus.
+
+        Events are a core Home Assistant mechanism used for signaling between components
+        and triggering automations. This is distinct from service calls.
+
+        **Parameters:**
+        - **event_type**: The type of event to fire (e.g., 'homeassistant_start', 'my_custom_event')
+        - **data**: Optional JSON object containing event data
+        """
+        try:
+            event_data = parse_json_param(data, "data") or {}
+
+            result = await self._client.fire_event(event_type, event_data)
+
+            return {
+                "success": True,
+                "event_type": event_type,
+                "data": event_data,
+                "result": result,
+                "message": f"Successfully fired event: {event_type}",
+            }
+        except Exception as error:
+            exception_to_structured_error(
+                error,
+                context={
+                    "event_type": event_type,
+                    "data": data,
+                },
+            )
 
     @tool(name="ha_get_operation_status", tags={"Service & Device Control"}, annotations={"readOnlyHint": True, "title": "Get Operation Status"})
     @log_tool_usage

Related Issues/PRs

• No similar open issues found regarding ha_fire_event.

---

🤖 Automated analysis by Issue Bot

[kingpanther13]

This one seems a bit more obscure, I haven't done any proper research on it yet but I would want to see what all specifically this actually would do, like what all it brings to the table and if that's worth adding another tool for. I'd also want to see if it could potentially be merged into call service instead. Additionally, I don't believe that "fire" is one of the verbs we have been using for tools, so we would need to either consider adding that as one of the verbs or changing the name of the proposed tool to something else, if unable to cleanly merge it into another tool.

[Patch76]

Three good questions — let me work through each.

1. What does ha_fire_event bring to the table?

HA has two distinct mechanisms: the service registry (POST /api/services/{domain}/{service}) and the event bus (POST /api/events/{event_type}). They're not interchangeable — different subsystems, different handlers, different semantics.

What's currently reachable via ha_call_service:

• Script actions including action: event (which fires an event from within a script)
• Domain-specific services

What's not reachable today:

• Firing an event directly onto the bus as an external actor. There is no homeassistant.fire_event or event.fire service — I confirmed against /api/services on my instance (51 services in the homeassistant domain, none fire events; no other domain exposes one either).

Concrete use-cases for LLM consumers:

Use-case	Why it needs event-bus access
Trigger a custom-integration handler listening on mycomp_data_received	No service equivalent; event is the documented contract
Test/simulate an automation trigger (platform: event) without waiting for the real source	E.g., "simulate a mobile_app_notification_action to test the handler"
Signal between loosely-coupled automations	Events decouple producer and consumer cleanly; services force a direct target
Surface lifecycle events (homeassistant_start, call_service, custom) for debugging	Read-only today via WebSocket listen; no way to emit for testing

On my instance there are 7 event_type triggers across automations.yaml and 31 event types with active listeners — it's not a fringe mechanism, it's just invisible from the MCP surface right now.

2. Merge into ha_call_service?

I don't think it works cleanly, for two reasons:

• Different HA subsystems. Services and events are separate API surfaces in HA itself (/api/services/... vs /api/events/...). Merging them in the tool layer would paper over a distinction that HA deliberately maintains.
• Signature conflict. ha_call_service takes domain, service, entity_id, data, return_response, wait — all of which are service-semantic. Events have no domain, no entity_id, no return response, and no state to wait on. A merged tool would need a discriminator (event-mode vs. service-mode) and two dead parameter sets depending on which mode — more complexity in the already-busy service tool, no shared code path.

It's the mirror image of the #1007 conclusion: merging adds complexity without a real code-dedup win.

3. Verb naming

You're right, fire isn't in AGENTS.md's verb list (currently get, list, search, set, delete, remove, call, manage). Three options:

• Add fire as a verb. It's HA-native language — hass.bus.fire() in Python, Fire an event in the Developer Tools UI, action: event in scripts is literally called "firing an event" in HA docs. Would cover this one tool; unlikely to open a floodgate since the event bus is the last major HA primitive without tool coverage.
• Rename to stay within existing verbs. ha_post_event (maps to the REST verb) or ha_emit_event (generic). Both lose the HA-native ring but avoid an AGENTS.md edit.
• Avoid ha_trigger_event — trigger is overloaded in HA (automation triggers are a different concept) and would cause exactly the kind of naming friction we're trying to reduce.

My preference: add fire to the verb list — it's a one-line AGENTS.md edit and keeps the tool name aligned with HA's own vocabulary. But if you'd rather not grow the verb set, ha_post_event is the cleanest fallback.

---

Happy to draft the PR against whichever naming direction you prefer, or leave it until you've had a chance to dig deeper.

[kingpanther13]

Post event also doesn't fall in line with how we have been doing it. Would probably need to be ha_call_event. I'll research this one more as soon as I get the time, it still seems like it'd be kind of an edge case tool and not very commonly used from what you're describing, but it does seem like useful functionality.