Home Assistant MCP

Instructions

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

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."