Hass-MCP

Instructions

Implementation Reference

• app/server.py:828-863 (handler)

  The primary handler function for the 'list_automations' MCP tool. Decorated with @mcp.tool() for registration and @async_handler for async handling. Fetches all Home Assistant automations via the get_automations helper, processes errors, and returns a list of automation dictionaries containing id, entity_id, state, and alias.
  @async_handler("list_automations") async def list_automations() -> List[Dict[str, Any]]: """ Get a list of all automations from Home Assistant This function retrieves all automations configured in Home Assistant, including their IDs, entity IDs, state, and display names. Returns: A list of automation dictionaries, each containing id, entity_id, state, and alias (friendly name) fields. Examples: Returns all automation objects with state and friendly names """ logger.info("Getting all automations") try: # Get automations will now return data from states API, which is more reliable automations = await get_automations() # Handle error responses that might still occur if isinstance(automations, dict) and "error" in automations: logger.warning(f"Error getting automations: {automations['error']}") return [] # Handle case where response is a list with error if isinstance(automations, list) and len(automations) == 1 and isinstance(automations[0], dict) and "error" in automations[0]: logger.warning(f"Error getting automations: {automations[0]['error']}") return [] return automations except Exception as e: logger.error(f"Error in list_automations: {str(e)}") return []
• app/hass.py:398-430 (helper)

  Supporting helper function that retrieves automation entities from Home Assistant by filtering get_entities to the 'automation' domain, extracts key fields like id, entity_id, state, alias, and optional last_triggered, and returns formatted list. Used directly by the list_automations handler.
  @handle_api_errors async def get_automations() -> List[Dict[str, Any]]: """Get a list of all automations from Home Assistant""" # Reuse the get_entities function with domain filtering automation_entities = await get_entities(domain="automation") # Check if we got an error response if isinstance(automation_entities, dict) and "error" in automation_entities: return automation_entities # Just pass through the error # Process automation entities result = [] try: for entity in automation_entities: # Extract relevant information automation_info = { "id": entity["entity_id"].split(".")[1], "entity_id": entity["entity_id"], "state": entity["state"], "alias": entity["attributes"].get("friendly_name", entity["entity_id"]), } # Add any additional attributes that might be useful if "last_triggered" in entity["attributes"]: automation_info["last_triggered"] = entity["attributes"]["last_triggered"] result.append(automation_info) except (TypeError, KeyError) as e: # Handle errors in processing the entities return {"error": f"Error processing automation entities: {str(e)}"} return result
• app/server.py:828-829 (registration)

  The MCP tool registration via @mcp.tool() decorator and async handler registration via @async_handler("list_automations") on the handler function.
  @async_handler("list_automations") async def list_automations() -> List[Dict[str, Any]]: