entity_action

Instructions

Implementation Reference

• app/server.py:104-142 (handler)

  The main handler function that performs actions on Home Assistant entities. Validates action (on/off/toggle), maps to service names (turn_on/turn_off/toggle), extracts domain from entity_id, and delegates to call_service.

  @mcp.tool()
  @async_handler("entity_action")
  async def entity_action(entity_id: str, action: str, params: Optional[Dict[str, Any]] = None) -> dict:
      """
      Perform an action on a Home Assistant entity (on, off, toggle)
      
      Args:
          entity_id: The entity ID to control (e.g. 'light.living_room')
          action: The action to perform ('on', 'off', 'toggle')
          params: Optional dictionary of additional parameters for the service call
      
      Returns:
          The response from Home Assistant
      
      Examples:
          entity_id="light.living_room", action="on", params={"brightness": 255}
          entity_id="switch.garden_lights", action="off"
          entity_id="climate.living_room", action="on", params={"temperature": 22.5}
      
      Domain-Specific Parameters:
          - Lights: brightness (0-255), color_temp, rgb_color, transition, effect
          - Covers: position (0-100), tilt_position
          - Climate: temperature, target_temp_high, target_temp_low, hvac_mode
          - Media players: source, volume_level (0-1)
      """
      if action not in ["on", "off", "toggle"]:
          return {"error": f"Invalid action: {action}. Valid actions are 'on', 'off', 'toggle'"}
      
      # Map action to service name
      service = action if action == "toggle" else f"turn_{action}"
      
      # Extract the domain from the entity_id
      domain = entity_id.split(".")[0]
      
      # Prepare service data
      data = {"entity_id": entity_id, **(params or {})}
      
      logger.info(f"Performing action '{action}' on entity: {entity_id} with params: {params}")
      return await call_service(domain, service, data)

• app/server.py:104-104 (registration)

  The @mcp.tool() decorator registers this function as an MCP tool named 'entity_action'.

  @mcp.tool()

• app/server.py:106-106 (schema)

  Type signature defines inputs: entity_id (str), action (str), optional params (dict), and returns a dict.

  async def entity_action(entity_id: str, action: str, params: Optional[Dict[str, Any]] = None) -> dict:

• app/hass.py:357-378 (helper)

  Helper function that makes the actual HTTP POST call to Home Assistant API to perform the service call. entity_action delegates to this function.

  async def call_service(domain: str, service: str, data: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
      """Call a Home Assistant service.
  
      Returns:
          List of affected entity states (may be empty for services like reload).
      """
      if data is None:
          data = {}
      
      client = await get_client()
      response = await client.post(
          f"{HA_URL}/api/services/{domain}/{service}", 
          headers=get_ha_headers(),
          json=data
      )
      response.raise_for_status()
      
      # Invalidate cache after service calls as they might change entity states
      global _entities_timestamp
      _entities_timestamp = 0
      
      return response.json()