ha-mcp-server/EXAMPLES.md

# Home Assistant MCP Server - Usage Examples

This document provides practical examples of how LLMs can interact with Home Assistant through this MCP server.

## Basic Entity State Queries

### Example 1: Check if a light is on
```
User: Is the living room light on?

LLM Process:
1. Uses get_state tool
2. Parameters: { entity_id: "light.living_room" }
3. Receives response with state: "on" or "off"
4. Responds: "Yes, the living room light is currently on."
```

### Example 2: Get temperature reading
```
User: What's the temperature in the bedroom?

LLM Process:
1. Uses get_state tool
2. Parameters: { entity_id: "sensor.bedroom_temperature" }
3. Receives state with attributes
4. Responds: "The bedroom temperature is 22.5°C"
```

### Example 3: Check multiple sensors
```
User: Show me the status of all doors

LLM Process:
1. Reads ha://states resource
2. Filters for entities matching "binary_sensor.*_door"
3. Lists each door and its state (open/closed)
```

## Device Control

### Example 4: Turn on a light
```
User: Turn on the kitchen light

LLM Process:
1. Uses call_service tool
2. Parameters:
   {
     domain: "light",
     service: "turn_on",
     service_data: { entity_id: "light.kitchen" }
   }
3. Responds: "I've turned on the kitchen light."
```

### Example 5: Dim lights
```
User: Set the bedroom lights to 30% brightness

LLM Process:
1. Uses call_service tool
2. Parameters:
   {
     domain: "light",
     service: "turn_on",
     service_data: {
       entity_id: "light.bedroom",
       brightness_pct: 30
     }
   }
```

### Example 6: Set thermostat
```
User: Set the thermostat to 21 degrees

LLM Process:
1. Uses call_service tool
2. Parameters:
   {
     domain: "climate",
     service: "set_temperature",
     service_data: {
       entity_id: "climate.living_room",
       temperature: 21
     }
   }
```

### Example 7: Control multiple devices
```
User: Turn off all lights in the house

LLM Process:
1. Reads ha://states to find all light entities
2. Uses call_service tool
3. Parameters:
   {
     domain: "light",
     service: "turn_off",
     service_data: {
       entity_id: "all"  // or comma-separated list
     }
   }
```

## Complex Queries with Templates

### Example 8: Count entities by state
```
User: How many lights are currently on?

LLM Process:
1. Uses render_template tool
2. Parameters:
   {
     template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
   }
3. Receives: "5"
4. Responds: "There are 5 lights currently on."
```

### Example 9: Calculate total power consumption
```
User: What's the total power consumption right now?

LLM Process:
1. Uses render_template tool
2. Parameters:
   {
     template: "{{ states.sensor | selectattr('attributes.device_class', 'eq', 'power') | map(attribute='state') | map('float', 0) | sum | round(2) }}"
   }
```

### Example 10: Check battery levels
```
User: Which devices have low battery?

LLM Process:
1. Uses render_template tool
2. Parameters:
   {
     template: "{% for state in states.sensor if state.attributes.device_class == 'battery' and state.state | float < 20 %}{{ state.name }}: {{ state.state }}%\n{% endfor %}"
   }
```

## Historical Data Analysis

### Example 11: Temperature trend
```
User: Show me the living room temperature for the last 24 hours

LLM Process:
1. Calculate timestamps (now and 24h ago)
2. Uses get_history tool
3. Parameters:
   {
     entity_ids: ["sensor.living_room_temperature"],
     start_time: "2024-01-06T10:00:00Z",
     end_time: "2024-01-07T10:00:00Z"
   }
4. Analyzes data and presents trend
```

### Example 12: Door activity log
```
User: When was the front door last opened today?

LLM Process:
1. Uses get_logbook tool
2. Parameters:
   {
     entity_id: "binary_sensor.front_door",
     start_time: "2024-01-07T00:00:00Z"
   }
3. Finds most recent "opened" event
4. Responds: "The front door was last opened at 2:30 PM."
```

### Example 13: Energy usage comparison
```
User: Compare today's energy usage to yesterday

LLM Process:
1. Get today's energy data (get_history)
2. Get yesterday's energy data (get_history)
3. Calculate totals and difference
4. Present comparison
```

## Automation and Events

### Example 14: Trigger an automation
```
User: Run the "Good Night" automation

LLM Process:
1. Uses call_service tool
2. Parameters:
   {
     domain: "automation",
     service: "trigger",
     service_data: {
       entity_id: "automation.good_night"
     }
   }
```

### Example 15: Fire custom event
```
User: Send a notification that I'm working from home

LLM Process:
1. Uses fire_event tool
2. Parameters:
   {
     event_type: "custom_presence_update",
     event_data: {
       status: "working_from_home",
       timestamp: "2024-01-07T10:00:00Z"
     }
   }
```

### Example 16: Create automation trigger
```
User: Create a reminder state for watering plants

LLM Process:
1. Uses set_state tool
2. Parameters:
   {
     entity_id: "input_boolean.water_plants_reminder",
     state: "on",
     attributes: {
       friendly_name: "Water Plants Reminder",
       last_set: "2024-01-07T10:00:00Z"
     }
   }
```

## Scene and Group Management

### Example 17: Activate a scene
```
User: Activate the movie scene

LLM Process:
1. Uses call_service tool
2. Parameters:
   {
     domain: "scene",
     service: "turn_on",
     service_data: {
       entity_id: "scene.movie"
     }
   }
```

### Example 18: Control a group
```
User: Turn off all bedroom devices

LLM Process:
1. Uses call_service tool
2. Parameters:
   {
     domain: "homeassistant",
     service: "turn_off",
     service_data: {
       entity_id: "group.bedroom_devices"
     }
   }
```

## Media and Entertainment

### Example 19: Control media player
```
User: Play music in the living room

LLM Process:
1. Uses call_service tool
2. Parameters:
   {
     domain: "media_player",
     service: "media_play",
     service_data: {
       entity_id: "media_player.living_room"
     }
   }
```

### Example 20: Set volume
```
User: Set living room speaker volume to 50%

LLM Process:
1. Uses call_service tool
2. Parameters:
   {
     domain: "media_player",
     service: "volume_set",
     service_data: {
       entity_id: "media_player.living_room",
       volume_level: 0.5
     }
   }
```

## Camera and Security

### Example 21: Get camera snapshot
```
User: Show me the front door camera

LLM Process:
1. Uses get_camera_image tool
2. Parameters: { entity_id: "camera.front_door" }
3. Receives base64-encoded image
4. Can describe or analyze the image
```

### Example 22: Check security system status
```
User: Is the alarm armed?

LLM Process:
1. Uses get_state tool
2. Parameters: { entity_id: "alarm_control_panel.home" }
3. Checks state (armed_away, armed_home, disarmed)
4. Responds with status
```

## Calendar Integration

### Example 23: Check upcoming events
```
User: What's on my calendar tomorrow?

LLM Process:
1. Calculate tomorrow's date range
2. Uses get_calendar_events tool
3. Parameters:
   {
     entity_id: "calendar.personal",
     start: "2024-01-08T00:00:00Z",
     end: "2024-01-08T23:59:59Z"
   }
4. Lists events with times
```

### Example 24: Check if anyone is busy
```
User: Is anyone in a meeting right now?

LLM Process:
1. Get current time
2. Get calendar events for now
3. Check for active events
4. Respond with status
```

## System Information

### Example 25: Check Home Assistant version
```
User: What version of Home Assistant are you running?

LLM Process:
1. Reads ha://config resource
2. Extracts version field
3. Responds: "Home Assistant version 2024.1.0"
```

### Example 26: List available services
```
User: What can you control?

LLM Process:
1. Reads ha://services resource
2. Lists domains and key services
3. Provides capabilities summary
```

### Example 27: Check for errors
```
User: Are there any recent errors?

LLM Process:
1. Reads ha://error_log resource
2. Analyzes recent error entries
3. Summarizes issues or reports "No errors"
```

## Advanced Scenarios

### Example 28: Smart morning routine
```
User: Good morning! Start my day.

LLM Process:
1. Get current weather (state)
2. Turn on bedroom lights gradually (call_service with transition)
3. Start coffee maker (call_service)
4. Read calendar events for today (get_calendar_events)
5. Announce summary via TTS (call_service)
```

### Example 29: Energy optimization
```
User: Help me save energy right now

LLM Process:
1. Get all device states (ha://states)
2. Identify devices consuming power unnecessarily
3. Suggest turning off unused devices
4. Adjust thermostat based on occupancy
5. Provide energy-saving tips based on usage patterns
```

### Example 30: Presence detection
```
User: Is anyone home?

LLM Process:
1. Check person entities (device_tracker.*)
2. Check motion sensors
3. Check recent door activity (logbook)
4. Synthesize presence information
5. Respond with confidence level
```

## Error Handling Examples

### Example 31: Entity not found
```
User: Turn on the garage light

LLM Process:
1. Attempts to call service
2. Receives 404 error
3. Reads available entities
4. Responds: "I couldn't find a garage light. Did you mean 'light.driveway' or 'light.carport'?"
```

### Example 32: Service unavailable
```
User: Set the pool temperature to 28 degrees

LLM Process:
1. Checks if pool heater entity exists
2. Checks available services for climate domain
3. If service unavailable, suggests alternatives
4. Responds: "The pool heater isn't available. Would you like me to create a reminder to set it manually?"
```

## Best Practices for LLM Interactions

1. **Verify before acting**: Check entity states before making changes
2. **Provide context**: Include entity IDs and states in responses
3. **Handle errors gracefully**: Suggest alternatives when operations fail
4. **Use templates for complex queries**: Offload processing to Home Assistant
5. **Batch operations**: Use comma-separated entity IDs when possible
6. **Respect user preferences**: Confirm destructive operations
7. **Provide feedback**: Confirm successful operations with details

## Tips for Implementation

- Always read available services/states before attempting operations
- Use templates for calculations and complex filtering
- Leverage logbook for recent activity analysis
- Combine multiple operations for "scene-like" behavior
- Use attributes for rich context (battery level, last updated, etc.)
- Consider time zones when working with timestamps
- Handle partial matches gracefully (fuzzy entity ID matching)

## Common Patterns

### Discovery Pattern
```
1. Read ha://states or ha://services
2. Filter/search for relevant entities
3. Execute operation on found entities
```

### Validation Pattern
```
1. Get current state
2. Verify desired operation is valid
3. Execute operation
4. Confirm new state
```

### Historical Analysis Pattern
```
1. Calculate time range
2. Get historical data
3. Analyze trends
4. Present insights
```

### Multi-step Automation Pattern
```
1. Check preconditions
2. Execute step 1
3. Verify success
4. Execute step 2
5. Provide summary
```