search_entities
Find Home Assistant devices by describing them in plain language. Enter phrases like 'office light' or 'kitchen fan' to locate matching entities for control.
Instructions
Search for Home Assistant entities matching a natural language description.
Args:
description: Natural language description of the entity (e.g., "office light", "kitchen fan")
Returns:
A list of matching entity IDs with their friendly names, or an error message
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes |
Implementation Reference
- app/tools/device_controls.py:89-109 (handler)The main execution logic for the 'search_entities' MCP tool. Fetches entities from Home Assistant, matches using keyword helper, formats and returns results.async def search_entities(description: str) -> str: """Search for Home Assistant entities matching a natural language description. Args: description: Natural language description of the entity (e.g., "office light", "kitchen fan") Returns: A list of matching entity IDs with their friendly names, or an error message """ # Check token if not HOME_ASSISTANT_TOKEN: return "Home Assistant token not configured. Set HOME_ASSISTANT_TOKEN environment variable." # Get all entities entities = await get_all_entities() if not entities: return "Failed to retrieve entities from Home Assistant." # Search and format results matches = search_entities_by_keywords(entities, description) return format_entity_results(matches)
- app/tools/device_controls.py:11-20 (registration)Registers the 'search_entities' tool (and others) with the FastMCP instance using decorator.def init_tools(fastmcp_instance: FastMCP): """Initialize the tools with a FastMCP instance.""" global mcp mcp = fastmcp_instance # Register tools with the FastMCP instance fastmcp_instance.tool()(control_device) fastmcp_instance.tool()(search_entities) fastmcp_instance.tool()(set_device_color) # Register set_device_color like other tools
- app/utils/search.py:4-37 (helper)Supporting utility that implements keyword-based search scoring for entities based on description.def search_entities_by_keywords(entities: List[Dict[str, Any]], description: str) -> List[Dict[str, Any]]: """Search for entities matching a natural language description. Args: entities: List of entity dictionaries from Home Assistant description: Natural language description of the entity Returns: A list of matching entities sorted by relevance score """ # Break description into keywords keywords = re.findall(r'\w+', description.lower()) # Search for matching entities matches = [] for entity in entities: entity_id = entity.get("entity_id", "").lower() friendly_name = entity.get("attributes", {}).get("friendly_name", "").lower() # Check if any keyword matches the entity_id or friendly_name score = 0 for keyword in keywords: if keyword in entity_id or keyword in friendly_name: score += 1 if score > 0: matches.append({ "entity_id": entity.get("entity_id"), "friendly_name": entity.get("attributes", {}).get("friendly_name", ""), "score": score }) # Sort matches by score (descending) return sorted(matches, key=lambda x: x["score"], reverse=True)
- app/utils/search.py:39-55 (helper)Supporting utility to format the list of matching entities into a user-readable string.def format_entity_results(matches: List[Dict[str, Any]], limit: int = 5) -> str: """Format entity search results into a readable string. Args: matches: List of matching entities with scores limit: Maximum number of results to include Returns: Formatted string with entity results """ if matches: result = "Found matching entities:\n" for match in matches[:limit]: result += f"- {match['entity_id']} ({match['friendly_name']})\n" return result else: return "No matching entities found."