alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor API Documentation with Comprehensive MCP Schema and Endpoint Details

Browse Source 
- Completely restructured API.md with a more modular and detailed approach
- Added comprehensive schema documentation for MCP endpoint
- Expanded sections on device control, add-on management, and core functions
- Included WebSocket event handling and real-time update mechanisms
- Enhanced error handling and rate limiting documentation
- Added example usage sections with curl and JavaScript demonstrations
- Improved overall readability and technical depth of API reference
This commit is contained in:
jango-blockchained
2025-02-03 00:28:07 +01:00
parent bd7e206b96
commit cb6b16546b
1 changed files with 343 additions and 288 deletions
Download Patch File Download Diff File Expand all files Collapse all files

641
docs/API.md
View File

@@ -1,364 +1,419 @@
# Home Assistant MCP API Documentation # API Reference
## Overview ## MCP Schema Endpoint
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. The server exposes an MCP (Model Context Protocol) schema endpoint that describes all available tools and their parameters:
## Authentication
All API requests require authentication using a Bearer token.
```http ```http
Authorization: Bearer your_home_assistant_token GET /mcp
``` ```
## Rate Limiting This endpoint returns a JSON schema describing all available tools, their parameters, and documentation resources. The schema follows the MCP specification and can be used by LLM clients to understand the server's capabilities.
The API implements rate limiting with the following defaults: Example response:
- 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 ```json
{ {
"input": "Turn on the living room lights", "tools": [
"context": { {
"user_id": "user123", "name": "list_devices",
"session_id": "sess456", "description": "List all devices connected to Home Assistant",
"timestamp": "2024-03-20T10:30:00Z", "parameters": {
"location": "home", "type": "object",
"previous_actions": [], "properties": {
"environment_state": {} "domain": {
}, "type": "string",
"model": "claude" // Optional: defaults to "claude" "enum": ["light", "climate", "alarm_control_panel", ...]
} },
``` "area": { "type": "string" },
"floor": { "type": "string" }
**Response:** }
```json }
{ },
"natural_language": "I'll turn on the living room lights", // ... other tools
"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, "prompts": [],
"context": { "resources": [
"user_id": "user123", {
"session_id": "sess456", "name": "Home Assistant API",
"timestamp": "2024-03-20T10:30:00Z" "url": "https://developers.home-assistant.io/docs/api/rest/"
} }
]
} }
``` ```
### 2. Device Control Note: The `/mcp` endpoint is publicly accessible and does not require authentication, as it only provides schema information.
#### POST /control ## Device Control
Controls Home Assistant devices and services. ### Common Entity Controls
**Request Body:**
```json ```json
{ {
"tool": "control",
"command": "turn_on", // or "turn_off", "toggle"
"entity_id": "light.living_room"
}
```
### Light Control
```json
{
"tool": "control",
"command": "turn_on", "command": "turn_on",
"entity_id": "light.living_room", "entity_id": "light.living_room",
"brightness": 255, "brightness": 128,
"color_temp": 4000, "color_temp": 4000,
"rgb_color": [255, 0, 0] "rgb_color": [255, 0, 0]
} }
``` ```
**Example Commands by Device Type:** ## Add-on Management
**1. Lights:** ### List Available Add-ons
```json ```json
{ {
"command": "turn_on", "tool": "addon",
"entity_id": "light.bedroom", "action": "list"
"brightness": 128,
"color_temp": 3500
} }
``` ```
**2. Climate:** ### Install Add-on
```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 ```json
{ {
"tool": "addon",
"action": "install", "action": "install",
"slug": "core_configurator", "slug": "core_configurator",
"version": "5.6.0" "version": "5.6.0"
} }
``` ```
### 7. Package Management (HACS) ### Manage Add-on State
#### GET /packages
Lists available HACS packages.
**Query Parameters:**
- `category`: One of ["integration", "plugin", "theme", "python_script", "appdaemon", "netdaemon"]
**Response:**
```json ```json
{ {
"success": true, "tool": "addon",
"packages": [ "action": "start", // or "stop", "restart"
{ "slug": "core_configurator"
"name": "Custom Component",
"repository": "owner/repo",
"category": "integration",
"installed_version": "1.0.0",
"available_version": "1.1.0"
}
]
} }
``` ```
#### POST /packages ## Package Management
Manages HACS packages. ### List HACS Packages
**Request Body (Install):**
```json ```json
{ {
"tool": "package",
"action": "list",
"category": "integration" // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}
```
### Install Package
```json
{
"tool": "package",
"action": "install", "action": "install",
"category": "integration", "category": "integration",
"repository": "owner/repo", "repository": "hacs/integration",
"version": "1.1.0" "version": "1.32.0"
} }
``` ```
## Error Handling ## Automation Management
All endpoints return errors in a consistent format:
### Create Automation
```json ```json
{ {
"error": { "tool": "automation_config",
"code": "ERROR_CODE", "action": "create",
"message": "Human readable error message", "config": {
"suggestion": "Suggestion to fix the error", "alias": "Motion Light",
"recovery_options": [ "description": "Turn on light when motion detected",
"Option 1", "mode": "single",
"Option 2" "trigger": [
{
"platform": "state",
"entity_id": "binary_sensor.motion",
"to": "on"
}
],
"action": [
{
"service": "light.turn_on",
"target": {
"entity_id": "light.living_room"
}
}
] ]
} }
} }
``` ```
Common HTTP status codes: ### Duplicate Automation
```json
{
"tool": "automation_config",
"action": "duplicate",
"automation_id": "automation.motion_light"
}
```
## Core Functions
### State Management
```http
GET /api/state
POST /api/state
```
Manages the current state of the system.
**Example Request:**
```json
POST /api/state
{
"context": "living_room",
"state": {
"lights": "on",
"temperature": 22
}
}
```
### Context Updates
```http
POST /api/context
```
Updates the current context with new information.
**Example Request:**
```json
POST /api/context
{
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
}
```
## Action Endpoints
### Execute Action
```http
POST /api/action
```
Executes a specified action with given parameters.
**Example Request:**
```json
POST /api/action
{
"action": "turn_on_lights",
"parameters": {
"room": "living_room",
"brightness": 80
}
}
```
### Batch Actions
```http
POST /api/actions/batch
```
Executes multiple actions in sequence.
**Example Request:**
```json
POST /api/actions/batch
{
"actions": [
{
"action": "turn_on_lights",
"parameters": {
"room": "living_room"
}
},
{
"action": "set_temperature",
"parameters": {
"temperature": 22
}
}
]
}
```
## Query Functions
### Get Available Actions
```http
GET /api/actions
```
Returns a list of all available actions.
**Example Response:**
```json
{
"actions": [
{
"name": "turn_on_lights",
"parameters": ["room", "brightness"],
"description": "Turns on lights in specified room"
},
{
"name": "set_temperature",
"parameters": ["temperature"],
"description": "Sets temperature in current context"
}
]
}
```
### Context Query
```http
GET /api/context?type=current
```
Retrieves context information.
**Example Response:**
```json
{
"current_context": {
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
}
}
```
## WebSocket Events
The server supports real-time updates via WebSocket connections.
```javascript
// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received update:', data);
};
```
### Supported Events
- `state_change`: Emitted when system state changes
- `context_update`: Emitted when context is updated
- `action_executed`: Emitted when an action is completed
- `error`: Emitted when an error occurs
**Example Event Data:**
```json
{
"event": "state_change",
"data": {
"previous_state": {
"lights": "off"
},
"current_state": {
"lights": "on"
},
"timestamp": "2024-03-20T10:30:00Z"
}
}
```
## Error Handling
All endpoints return standard HTTP status codes:
- 200: Success - 200: Success
- 400: Bad Request - 400: Bad Request
- 401: Unauthorized - 401: Unauthorized
- 403: Forbidden - 403: Forbidden
- 404: Not Found - 404: Not Found
- 429: Too Many Requests
- 500: Internal Server Error - 500: Internal Server Error
## WebSocket Events **Error Response Format:**
```json
{
"error": {
"code": "INVALID_PARAMETERS",
"message": "Missing required parameter: room",
"details": {
"missing_fields": ["room"]
}
}
}
```
The server supports WebSocket connections for real-time updates. ## Rate Limiting
### Connection The API implements rate limiting to prevent abuse:
- 100 requests per minute per IP for regular endpoints
- 1000 requests per minute per IP for WebSocket connections
When rate limit is exceeded, the server returns:
```json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"reset_time": "2024-03-20T10:31:00Z"
}
}
```
## Example Usage
### Using curl
```bash
# Get current state
curl -X GET \
http://localhost:3000/api/state \
-H 'Authorization: ApiKey your_api_key_here'
# Execute action
curl -X POST \
http://localhost:3000/api/action \
-H 'Authorization: ApiKey your_api_key_here' \
-H 'Content-Type: application/json' \
-d '{
"action": "turn_on_lights",
"parameters": {
"room": "living_room",
"brightness": 80
}
}'
```
### Using JavaScript
```javascript ```javascript
const ws = new WebSocket('ws://your-server/api/websocket'); // Execute action
ws.onmessage = (event) => { async function executeAction() {
const data = JSON.parse(event.data); const response = await fetch('http://localhost:3000/api/action', {
console.log('Received:', data); method: 'POST',
}; headers: {
``` 'Authorization': 'ApiKey your_api_key_here',
'Content-Type': 'application/json'
### Event Subscription },
body: JSON.stringify({
```javascript action: 'turn_on_lights',
// Subscribe to all events parameters: {
ws.send(JSON.stringify({ room: 'living_room',
type: 'subscribe_events' brightness: 80
})); }
})
// Subscribe to specific event type });
ws.send(JSON.stringify({
type: 'subscribe_events', const data = await response.json();
event_type: 'state_changed' console.log('Action result:', data);
})); }
```
## 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
``` ```