docs: expand documentation with comprehensive tools and development guides

- 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

docs/tools/device-management/control.md

@@ -0,0 +1,195 @@
+# Device Control Tool
+
+The Device Control tool provides functionality to control various types of devices in your Home Assistant instance.
+
+## Supported Device Types
+
+- Lights
+- Switches
+- Covers
+- Climate devices
+- Media players
+- And more...
+
+## Usage
+
+### REST API
+
+```typescript
+POST /api/devices/{device_id}/control
+```
+
+### WebSocket
+
+```typescript
+{
+    "type": "control_device",
+    "device_id": "required_device_id",
+    "domain": "required_domain",
+    "service": "required_service",
+    "data": {
+        // Service-specific data
+    }
+}
+```
+
+## Domain-Specific Commands
+
+### Lights
+
+```typescript
+// Turn on/off
+POST /api/devices/light/{device_id}/control
+{
+    "service": "turn_on",  // or "turn_off"
+}
+
+// Set brightness
+{
+    "service": "turn_on",
+    "data": {
+        "brightness": 255  // 0-255
+    }
+}
+
+// Set color
+{
+    "service": "turn_on",
+    "data": {
+        "rgb_color": [255, 0, 0]  // Red
+    }
+}
+```
+
+### Covers
+
+```typescript
+// Open/close
+POST /api/devices/cover/{device_id}/control
+{
+    "service": "open_cover",  // or "close_cover"
+}
+
+// Set position
+{
+    "service": "set_cover_position",
+    "data": {
+        "position": 50  // 0-100
+    }
+}
+```
+
+### Climate
+
+```typescript
+// Set temperature
+POST /api/devices/climate/{device_id}/control
+{
+    "service": "set_temperature",
+    "data": {
+        "temperature": 22.5
+    }
+}
+
+// Set mode
+{
+    "service": "set_hvac_mode",
+    "data": {
+        "hvac_mode": "heat"  // heat, cool, auto, off
+    }
+}
+```
+
+## Examples
+
+### Control Light Brightness
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/devices/light/living_room/control', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "service": "turn_on",
+        "data": {
+            "brightness": 128
+        }
+    })
+});
+```
+
+### Control Cover Position
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/devices/cover/bedroom/control', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "service": "set_cover_position",
+        "data": {
+            "position": 75
+        }
+    })
+});
+```
+
+## Response Format
+
+### Success Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "state": "on",
+        "attributes": {
+            // Updated device attributes
+        }
+    }
+}
+```
+
+### Error Response
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Device not found
+- `401`: Unauthorized
+- `400`: Invalid service or parameters
+- `409`: Device unavailable or offline
+
+## Rate Limiting
+
+- Default limit: 100 requests per 15 minutes
+- Configurable through environment variables:
+  - `DEVICE_CONTROL_RATE_LIMIT`
+  - `DEVICE_CONTROL_RATE_WINDOW`
+
+## Best Practices
+
+1. Validate device availability before sending commands
+2. Implement proper error handling
+3. Use appropriate retry strategies for failed commands
+4. Cache device capabilities when possible
+5. Handle rate limiting gracefully
+
+## See Also
+
+- [List Devices](list-devices.md)
+- [Device History](../history-state/history.md)
+- [Event Subscription](../events/subscribe-events.md) 

docs/tools/device-management/list-devices.md

@@ -0,0 +1,139 @@
+# 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
+
+```typescript
+GET /api/devices
+GET /api/devices/{domain}
+GET /api/devices/{device_id}/state
+```
+
+### WebSocket
+
+```typescript
+// 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
+
+```typescript
+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
+
+```typescript
+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
+
+```json
+{
+    "success": true,
+    "data": {
+        "devices": [
+            {
+                "id": "device_id",
+                "name": "Device Name",
+                "domain": "light",
+                "state": "on",
+                "attributes": {
+                    "brightness": 255,
+                    "color_temp": 370
+                }
+            }
+        ]
+    }
+}
+```
+
+### Device State Response
+
+```json
+{
+    "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 found
+- `401`: Unauthorized
+- `400`: Invalid request parameters
+
+### Error Response Format
+
+```json
+{
+    "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_LIMIT`
+  - `DEVICE_LIST_RATE_WINDOW`
+
+## Best Practices
+
+1. Cache device lists when possible
+2. Use domain filtering for better performance
+3. Implement proper error handling
+4. Handle rate limiting gracefully
+
+## See Also
+
+- [Device Control](control.md)
+- [Device History](../history-state/history.md)
+- [Event Subscription](../events/subscribe-events.md)