system_overview

Instructions

Implementation Reference

• app/server.py:633-656 (handler)

  The main handler function for the 'system_overview' tool, decorated with @mcp.tool() for registration and @async_handler for logging. It executes the tool logic by calling the helper function get_system_overview().

  @mcp.tool()
  @async_handler("system_overview")
  async def system_overview() -> Dict[str, Any]:
      """
      Get a comprehensive overview of the entire Home Assistant system
      
      Returns:
          A dictionary containing:
          - total_entities: Total count of all entities
          - domains: Dictionary of domains with their entity counts and state distributions
          - domain_samples: Representative sample entities for each domain (2-3 per domain)
          - domain_attributes: Common attributes for each domain
          - area_distribution: Entities grouped by area (if available)
          
      Examples:
          Returns domain counts, sample entities, and common attributes
      Best Practices:
          - Use this as the first call when exploring an unfamiliar Home Assistant instance
          - Perfect for building context about the structure of the smart home
          - After getting an overview, use domain_summary_tool to dig deeper into specific domains
      """
      logger.info("Generating complete system overview")
      return await get_system_overview()

• app/hass.py:544-666 (helper)

  Core helper function that implements the system overview logic. Fetches all entity states from Home Assistant API, applies lean filtering, groups by domain and area, computes statistics including entity counts, state distributions, representative samples, common attributes, and returns a structured overview dictionary.

  @handle_api_errors
  async def get_system_overview() -> Dict[str, Any]:
      """
      Get a comprehensive overview of the entire Home Assistant system
      
      Returns:
          A dictionary containing:
          - total_entities: Total count of all entities
          - domains: Dictionary of domains with their entity counts and state distributions
          - domain_samples: Representative sample entities for each domain (2-3 per domain)
          - domain_attributes: Common attributes for each domain
          - area_distribution: Entities grouped by area (if available)
      """
      try:
          # Get ALL entities with minimal fields for efficiency
          # We retrieve all entities since API calls don't consume tokens, only responses do
          client = await get_client()
          response = await client.get(f"{HA_URL}/api/states", headers=get_ha_headers())
          response.raise_for_status()
          all_entities_raw = response.json()
          
          # Apply lean formatting to reduce token usage in the response
          all_entities = []
          for entity in all_entities_raw:
              domain = entity["entity_id"].split(".")[0]
              
              # Start with basic lean fields
              lean_fields = ["entity_id", "state", "attr.friendly_name"]
              
              # Add domain-specific important attributes
              if domain in DOMAIN_IMPORTANT_ATTRIBUTES:
                  for attr in DOMAIN_IMPORTANT_ATTRIBUTES[domain]:
                      lean_fields.append(f"attr.{attr}")
              
              # Filter and add to result
              all_entities.append(filter_fields(entity, lean_fields))
          
          # Initialize overview structure
          overview = {
              "total_entities": len(all_entities),
              "domains": {},
              "domain_samples": {},
              "domain_attributes": {},
              "area_distribution": {}
          }
          
          # Group entities by domain
          domain_entities = {}
          for entity in all_entities:
              domain = entity["entity_id"].split(".")[0]
              if domain not in domain_entities:
                  domain_entities[domain] = []
              domain_entities[domain].append(entity)
          
          # Process each domain
          for domain, entities in domain_entities.items():
              # Count entities in this domain
              count = len(entities)
              
              # Collect state distribution
              state_distribution = {}
              for entity in entities:
                  state = entity.get("state", "unknown")
                  if state not in state_distribution:
                      state_distribution[state] = 0
                  state_distribution[state] += 1
              
              # Store domain information
              overview["domains"][domain] = {
                  "count": count,
                  "states": state_distribution
              }
              
              # Select representative samples (2-3 per domain)
              sample_limit = min(3, count)
              samples = []
              for i in range(sample_limit):
                  entity = entities[i]
                  samples.append({
                      "entity_id": entity["entity_id"],
                      "state": entity.get("state", "unknown"),
                      "friendly_name": entity.get("attributes", {}).get("friendly_name", entity["entity_id"])
                  })
              overview["domain_samples"][domain] = samples
              
              # Collect common attributes for this domain
              attribute_counts = {}
              for entity in entities:
                  for attr in entity.get("attributes", {}):
                      if attr not in attribute_counts:
                          attribute_counts[attr] = 0
                      attribute_counts[attr] += 1
              
              # Get top 5 most common attributes for this domain
              common_attributes = sorted(attribute_counts.items(), key=lambda x: x[1], reverse=True)[:5]
              overview["domain_attributes"][domain] = [attr for attr, count in common_attributes]
              
              # Group by area if available
              for entity in entities:
                  area_id = entity.get("attributes", {}).get("area_id", "Unknown")
                  area_name = entity.get("attributes", {}).get("area_name", area_id)
                  
                  if area_name not in overview["area_distribution"]:
                      overview["area_distribution"][area_name] = {}
                  
                  if domain not in overview["area_distribution"][area_name]:
                      overview["area_distribution"][area_name][domain] = 0
                      
                  overview["area_distribution"][area_name][domain] += 1
          
          # Add summary information
          overview["domain_count"] = len(domain_entities)
          overview["most_common_domains"] = sorted(
              [(domain, len(entities)) for domain, entities in domain_entities.items()],
              key=lambda x: x[1],
              reverse=True
          )[:5]
          
          return overview
      except Exception as e:
          logger.error(f"Error generating system overview: {str(e)}")
          return {"error": f"Error generating system overview: {str(e)}"}