Add comprehensive Home Assistant MCP API documentation
- Created detailed API documentation for Home Assistant Model Context Protocol (MCP) - Documented authentication, rate limiting, and security best practices - Included comprehensive endpoint descriptions for: * Natural Language Processing * Device Control * History * Scenes * Automations * Add-ons * Package Management - Added WebSocket event handling and connection examples - Provided error handling and response format guidelines
This commit is contained in:
jango-blockchained
364
docs/API.md
Normal file
364
docs/API.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# Home Assistant MCP API Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The Home Assistant Model Context Protocol (MCP) Server provides a comprehensive API for managing and controlling your Home Assistant instance. This document outlines all available endpoints, their parameters, and includes practical examples.
|
||||
|
||||
## Authentication
|
||||
|
||||
All API requests require authentication using a Bearer token.
|
||||
|
||||
```http
|
||||
Authorization: Bearer your_home_assistant_token
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
The API implements rate limiting with the following defaults:
|
||||
- 100 requests per 15-minute window per IP
|
||||
- Model-specific limits:
|
||||
- Claude: 100 requests/minute, 1000/hour
|
||||
- GPT-4: 50 requests/minute, 500/hour
|
||||
- Custom: 200 requests/minute, 2000/hour
|
||||
|
||||
## Endpoints
|
||||
|
||||
### 1. Natural Language Processing
|
||||
|
||||
#### POST /interpret
|
||||
|
||||
Interprets natural language commands for Home Assistant control.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"input": "Turn on the living room lights",
|
||||
"context": {
|
||||
"user_id": "user123",
|
||||
"session_id": "sess456",
|
||||
"timestamp": "2024-03-20T10:30:00Z",
|
||||
"location": "home",
|
||||
"previous_actions": [],
|
||||
"environment_state": {}
|
||||
},
|
||||
"model": "claude" // Optional: defaults to "claude"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"natural_language": "I'll turn on the living room lights",
|
||||
"structured_data": {
|
||||
"success": true,
|
||||
"action_taken": "turn_on",
|
||||
"entities_affected": ["light.living_room"],
|
||||
"state_changes": {
|
||||
"state": "on"
|
||||
}
|
||||
},
|
||||
"next_suggestions": [
|
||||
"Would you like to adjust the brightness?",
|
||||
"Should I turn on other lights?",
|
||||
"Would you like to save this as a scene?"
|
||||
],
|
||||
"confidence": 0.95,
|
||||
"context": {
|
||||
"user_id": "user123",
|
||||
"session_id": "sess456",
|
||||
"timestamp": "2024-03-20T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Device Control
|
||||
|
||||
#### POST /control
|
||||
|
||||
Controls Home Assistant devices and services.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"command": "turn_on",
|
||||
"entity_id": "light.living_room",
|
||||
"brightness": 255,
|
||||
"color_temp": 4000,
|
||||
"rgb_color": [255, 0, 0]
|
||||
}
|
||||
```
|
||||
|
||||
**Example Commands by Device Type:**
|
||||
|
||||
**1. Lights:**
|
||||
```json
|
||||
{
|
||||
"command": "turn_on",
|
||||
"entity_id": "light.bedroom",
|
||||
"brightness": 128,
|
||||
"color_temp": 3500
|
||||
}
|
||||
```
|
||||
|
||||
**2. Climate:**
|
||||
```json
|
||||
{
|
||||
"command": "set_temperature",
|
||||
"entity_id": "climate.living_room",
|
||||
"temperature": 72,
|
||||
"hvac_mode": "heat"
|
||||
}
|
||||
```
|
||||
|
||||
**3. Covers:**
|
||||
```json
|
||||
{
|
||||
"command": "set_position",
|
||||
"entity_id": "cover.garage",
|
||||
"position": 50
|
||||
}
|
||||
```
|
||||
|
||||
### 3. History
|
||||
|
||||
#### GET /history
|
||||
|
||||
Retrieves state history for entities.
|
||||
|
||||
**Query Parameters:**
|
||||
- `entity_id` (required): Entity ID to get history for
|
||||
- `start_time` (optional): Start time in ISO format
|
||||
- `end_time` (optional): End time in ISO format
|
||||
- `minimal_response` (optional): Boolean to reduce response size
|
||||
- `significant_changes_only` (optional): Boolean to filter minor changes
|
||||
|
||||
**Example Request:**
|
||||
```http
|
||||
GET /history?entity_id=light.living_room&start_time=2024-03-19T00:00:00Z&minimal_response=true
|
||||
```
|
||||
|
||||
### 4. Scenes
|
||||
|
||||
#### GET /scenes
|
||||
|
||||
Lists all available scenes.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"scenes": [
|
||||
{
|
||||
"entity_id": "scene.movie_time",
|
||||
"name": "Movie Time",
|
||||
"description": "Dim lights and lower blinds"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /scenes/activate
|
||||
|
||||
Activates a scene.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"scene_id": "scene.movie_time"
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Automations
|
||||
|
||||
#### GET /automations
|
||||
|
||||
Lists all automations.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"automations": [
|
||||
{
|
||||
"entity_id": "automation.morning_routine",
|
||||
"name": "Morning Routine",
|
||||
"state": "on",
|
||||
"last_triggered": "2024-03-20T06:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /automations
|
||||
|
||||
Creates or modifies automations.
|
||||
|
||||
**Request Body (Create):**
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"config": {
|
||||
"alias": "Morning Routine",
|
||||
"description": "Turn on lights at sunrise",
|
||||
"trigger": {
|
||||
"platform": "sun",
|
||||
"event": "sunrise"
|
||||
},
|
||||
"action": {
|
||||
"service": "light.turn_on",
|
||||
"target": {
|
||||
"entity_id": "light.living_room"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Add-ons
|
||||
|
||||
#### GET /addons
|
||||
|
||||
Lists available add-ons.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"addons": [
|
||||
{
|
||||
"name": "File Editor",
|
||||
"slug": "core_configurator",
|
||||
"description": "Simple browser-based file editor",
|
||||
"version": "5.6.0",
|
||||
"installed": true,
|
||||
"available": true,
|
||||
"state": "started"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /addons
|
||||
|
||||
Manages add-ons.
|
||||
|
||||
**Request Body (Install):**
|
||||
```json
|
||||
{
|
||||
"action": "install",
|
||||
"slug": "core_configurator",
|
||||
"version": "5.6.0"
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Package Management (HACS)
|
||||
|
||||
#### GET /packages
|
||||
|
||||
Lists available HACS packages.
|
||||
|
||||
**Query Parameters:**
|
||||
- `category`: One of ["integration", "plugin", "theme", "python_script", "appdaemon", "netdaemon"]
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"packages": [
|
||||
{
|
||||
"name": "Custom Component",
|
||||
"repository": "owner/repo",
|
||||
"category": "integration",
|
||||
"installed_version": "1.0.0",
|
||||
"available_version": "1.1.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /packages
|
||||
|
||||
Manages HACS packages.
|
||||
|
||||
**Request Body (Install):**
|
||||
```json
|
||||
{
|
||||
"action": "install",
|
||||
"category": "integration",
|
||||
"repository": "owner/repo",
|
||||
"version": "1.1.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
All endpoints return errors in a consistent format:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human readable error message",
|
||||
"suggestion": "Suggestion to fix the error",
|
||||
"recovery_options": [
|
||||
"Option 1",
|
||||
"Option 2"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Common HTTP status codes:
|
||||
- 200: Success
|
||||
- 400: Bad Request
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Not Found
|
||||
- 429: Too Many Requests
|
||||
- 500: Internal Server Error
|
||||
|
||||
## WebSocket Events
|
||||
|
||||
The server supports WebSocket connections for real-time updates.
|
||||
|
||||
### Connection
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://your-server/api/websocket');
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Received:', data);
|
||||
};
|
||||
```
|
||||
|
||||
### Event Subscription
|
||||
|
||||
```javascript
|
||||
// Subscribe to all events
|
||||
ws.send(JSON.stringify({
|
||||
type: 'subscribe_events'
|
||||
}));
|
||||
|
||||
// Subscribe to specific event type
|
||||
ws.send(JSON.stringify({
|
||||
type: 'subscribe_events',
|
||||
event_type: 'state_changed'
|
||||
}));
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. Always use HTTPS in production
|
||||
2. Store tokens securely
|
||||
3. Implement proper token rotation
|
||||
4. Monitor and log API usage
|
||||
5. Regular security audits
|
||||
|
||||
## Rate Limiting Headers
|
||||
|
||||
The API includes rate limit information in response headers:
|
||||
```http
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 95
|
||||
X-RateLimit-Reset: 1621436800
|
||||
```
|
||||
Reference in New Issue
Block a user