e3256682ba
- Add detailed documentation for various tools and management interfaces - Create development best practices and interface documentation - Expand tools section with device management, automation, and event subscription guides - Include configuration, usage examples, and error handling for each tool - Update MkDocs navigation to reflect new documentation structure
2.5 KiB
2.5 KiB
List Devices Tool
The List Devices tool provides functionality to retrieve and manage device information from your Home Assistant instance.
Features
- List all available Home Assistant devices
- Group devices by domain
- Get device states and attributes
- Filter devices by various criteria
Usage
REST API
GET /api/devices
GET /api/devices/{domain}
GET /api/devices/{device_id}/state
WebSocket
// List all devices
{
"type": "list_devices",
"domain": "optional_domain"
}
// Get device state
{
"type": "get_device_state",
"device_id": "required_device_id"
}
Examples
List All Devices
const response = await fetch('http://your-ha-mcp/api/devices', {
headers: {
'Authorization': 'Bearer your_access_token'
}
});
const devices = await response.json();
Get Devices by Domain
const response = await fetch('http://your-ha-mcp/api/devices/light', {
headers: {
'Authorization': 'Bearer your_access_token'
}
});
const lightDevices = await response.json();
Response Format
Device List Response
{
"success": true,
"data": {
"devices": [
{
"id": "device_id",
"name": "Device Name",
"domain": "light",
"state": "on",
"attributes": {
"brightness": 255,
"color_temp": 370
}
}
]
}
}
Device State Response
{
"success": true,
"data": {
"state": "on",
"attributes": {
"brightness": 255,
"color_temp": 370
},
"last_changed": "2024-02-05T12:00:00Z",
"last_updated": "2024-02-05T12:00:00Z"
}
}
Error Handling
Common Error Codes
404: Device not found401: Unauthorized400: Invalid request parameters
Error Response Format
{
"success": false,
"message": "Error description",
"error_code": "ERROR_CODE"
}
Rate Limiting
- Default limit: 100 requests per 15 minutes
- Configurable through environment variables:
DEVICE_LIST_RATE_LIMITDEVICE_LIST_RATE_WINDOW
Best Practices
- Cache device lists when possible
- Use domain filtering for better performance
- Implement proper error handling
- Handle rate limiting gracefully