Hass-MCP

Instructions

Implementation Reference

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

  The main handler function for the domain_summary_tool, decorated with @mcp.tool() for registration. It logs the call and delegates to the summarize_domain helper function from app.hass.

  @mcp.tool()
  @async_handler("domain_summary")
  async def domain_summary_tool(domain: str, example_limit: int = 3) -> Dict[str, Any]:
      """
      Get a summary of entities in a specific domain
      
      Args:
          domain: The domain to summarize (e.g., 'light', 'switch', 'sensor')
          example_limit: Maximum number of examples to include for each state
      
      Returns:
          A dictionary containing:
          - total_count: Number of entities in the domain
          - state_distribution: Count of entities in each state
          - examples: Sample entities for each state
          - common_attributes: Most frequently occurring attributes
          
      Examples:
          domain="light" - get light summary
          domain="climate", example_limit=5 - climate summary with more examples
      Best Practices:
          - Use this before retrieving all entities in a domain to understand what's available    """
      logger.info(f"Getting domain summary for: {domain}")
      return await summarize_domain(domain, example_limit)
  
  @mcp.tool()

• app/hass.py:333-397 (helper)

  The core helper function that implements the domain summary logic: fetches entities, computes state distribution, examples, and common attributes.

  async def summarize_domain(domain: str, example_limit: int = 3) -> Dict[str, Any]:
      """
      Generate a summary of entities in a domain
      
      Args:
          domain: The domain to summarize (e.g., 'light', 'switch')
          example_limit: Maximum number of examples to include for each state
          
      Returns:
          Dictionary with summary information
      """
      entities = await get_entities(domain=domain)
      
      # Check if we got an error response
      if isinstance(entities, dict) and "error" in entities:
          return entities  # Just pass through the error
      
      try:
          # Initialize summary data
          total_count = len(entities)
          state_counts = {}
          state_examples = {}
          attributes_summary = {}
          
          # Process entities to build the summary
          for entity in entities:
              state = entity.get("state", "unknown")
              
              # Count states
              if state not in state_counts:
                  state_counts[state] = 0
                  state_examples[state] = []
              state_counts[state] += 1
              
              # Add examples (up to the limit)
              if len(state_examples[state]) < example_limit:
                  example = {
                      "entity_id": entity["entity_id"],
                      "friendly_name": entity.get("attributes", {}).get("friendly_name", entity["entity_id"])
                  }
                  state_examples[state].append(example)
              
              # Collect attribute keys for summary
              for attr_key in entity.get("attributes", {}):
                  if attr_key not in attributes_summary:
                      attributes_summary[attr_key] = 0
                  attributes_summary[attr_key] += 1
          
          # Create the summary
          summary = {
              "domain": domain,
              "total_count": total_count,
              "state_distribution": state_counts,
              "examples": state_examples,
              "common_attributes": sorted(
                  [(k, v) for k, v in attributes_summary.items()], 
                  key=lambda x: x[1], 
                  reverse=True
              )[:10]  # Top 10 most common attributes
          }
          
          return summary
      except Exception as e:
          return {"error": f"Error generating domain summary: {str(e)}"}

• app/server.py:608-609 (registration)

  MCP tool registration decorators for the domain_summary_tool.

  @mcp.tool()
  @async_handler("domain_summary")