Initial commit

2025-12-11 20:29:51 +01:00
commit 1761c3cdd3
23 changed files with 5987 additions and 0 deletions
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -0,0 +1,510 @@
+# 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
+```