Hass-MCP

Instructions

Implementation Reference

• app/server.py:61-85 (handler)

  The primary handler for the 'get_entity' tool. Registered via @mcp.tool(). Handles input parameters (entity_id, fields, detailed flag) and delegates to get_entity_state helper with appropriate filtering options.
  @async_handler("get_entity") async def get_entity(entity_id: str, fields: Optional[List[str]] = None, detailed: bool = False) -> dict: """ Get the state of a Home Assistant entity with optional field filtering Args: entity_id: The entity ID to get (e.g. 'light.living_room') fields: Optional list of fields to include (e.g. ['state', 'attr.brightness']) detailed: If True, returns all entity fields without filtering Examples: entity_id="light.living_room" - basic state check entity_id="light.living_room", fields=["state", "attr.brightness"] - specific fields entity_id="light.living_room", detailed=True - all details """ logger.info(f"Getting entity state: {entity_id}") if detailed: # Return all fields return await get_entity_state(entity_id, lean=False) elif fields: # Return only the specified fields return await get_entity_state(entity_id, fields=fields) else: # Return lean format with essential fields return await get_entity_state(entity_id, lean=True)
• app/hass.py:172-216 (helper)

  Core implementation that fetches the entity state directly from Home Assistant's /api/states/{entity_id} endpoint. Supports field filtering and 'lean' mode using predefined important attributes per domain. Used by the get_entity handler.
  async def get_entity_state( entity_id: str, fields: Optional[List[str]] = None, lean: bool = False ) -> Dict[str, Any]: """ Get the state of a Home Assistant entity Args: entity_id: The entity ID to get fields: Optional list of specific fields to include in the response lean: If True, returns a token-efficient version with minimal fields (overridden by fields parameter if provided) Returns: Entity state dictionary, optionally filtered to include only specified fields """ # Fetch directly client = await get_client() response = await client.get( f"{HA_URL}/api/states/{entity_id}", headers=get_ha_headers() ) response.raise_for_status() entity_data = response.json() # Apply field filtering if requested if fields: # User-specified fields take precedence return filter_fields(entity_data, fields) elif lean: # Build domain-specific lean fields lean_fields = DEFAULT_LEAN_FIELDS.copy() # Add domain-specific important attributes domain = entity_id.split('.')[0] if domain in DOMAIN_IMPORTANT_ATTRIBUTES: for attr in DOMAIN_IMPORTANT_ATTRIBUTES[domain]: lean_fields.append(f"attr.{attr}") return filter_fields(entity_data, lean_fields) else: # Return full entity data return entity_data
• app/hass.py:117-159 (helper)

  Utility function used by get_entity_state to filter entity data to only requested fields or lean set, optimizing response size and token usage.
  def filter_fields(data: Dict[str, Any], fields: List[str]) -> Dict[str, Any]: """ Filter entity data to only include requested fields This function helps reduce token usage by returning only requested fields. Args: data: The complete entity data dictionary fields: List of fields to include in the result - "state": Include the entity state - "attributes": Include all attributes - "attr.X": Include only attribute X (e.g. "attr.brightness") - "context": Include context data - "last_updated"/"last_changed": Include timestamp fields Returns: A filtered dictionary with only the requested fields """ if not fields: return data result = {"entity_id": data["entity_id"]} for field in fields: if field == "state": result["state"] = data.get("state") elif field == "attributes": result["attributes"] = data.get("attributes", {}) elif field.startswith("attr.") and len(field) > 5: attr_name = field[5:] attributes = data.get("attributes", {}) if attr_name in attributes: if "attributes" not in result: result["attributes"] = {} result["attributes"][attr_name] = attributes[attr_name] elif field == "context": if "context" in data: result["context"] = data["context"] elif field in ["last_updated", "last_changed"]: if field in data: result[field] = data[field] return result