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

639
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.
## Authentication
All API requests require authentication using a Bearer token.
The server exposes an MCP (Model Context Protocol) schema endpoint that describes all available tools and their parameters:
```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:
- 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:**
Example response:
```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": {}
"tools": [
{
"name": "list_devices",
"description": "List all devices connected to Home Assistant",
"parameters": {
"type": "object",
"properties": {
"domain": {
"type": "string",
"enum": ["light", "climate", "alarm_control_panel", ...]
},
"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"
"area": { "type": "string" },
"floor": { "type": "string" }
}
}
},
"next_suggestions": [
"Would you like to adjust the brightness?",
"Should I turn on other lights?",
"Would you like to save this as a scene?"
// ... other tools
],
"confidence": 0.95,
"context": {
"user_id": "user123",
"session_id": "sess456",
"timestamp": "2024-03-20T10:30:00Z"
"prompts": [],
"resources": [
{
"name": "Home Assistant API",
"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.
**Request Body:**
### Common Entity Controls
```json
{
"tool": "control",
"command": "turn_on", // or "turn_off", "toggle"
"entity_id": "light.living_room"
}
```
### Light Control
```json
{
"tool": "control",
"command": "turn_on",
"entity_id": "light.living_room",
"brightness": 255,
"brightness": 128,
"color_temp": 4000,
"rgb_color": [255, 0, 0]
}
```
**Example Commands by Device Type:**
## Add-on Management
**1. Lights:**
### List Available Add-ons
```json
{
"command": "turn_on",
"entity_id": "light.bedroom",
"brightness": 128,
"color_temp": 3500
"tool": "addon",
"action": "list"
}
```
**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):**
### Install Add-on
```json
{
"tool": "addon",
"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:**
### Manage Add-on State
```json
{
"success": true,
"packages": [
{
"name": "Custom Component",
"repository": "owner/repo",
"tool": "addon",
"action": "start", // or "stop", "restart"
"slug": "core_configurator"
}
```
## Package Management
### List HACS Packages
```json
{
"tool": "package",
"action": "list",
"category": "integration" // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}
```
### Install Package
```json
{
"tool": "package",
"action": "install",
"category": "integration",
"installed_version": "1.0.0",
"available_version": "1.1.0"
"repository": "hacs/integration",
"version": "1.32.0"
}
```
## Automation Management
### Create Automation
```json
{
"tool": "automation_config",
"action": "create",
"config": {
"alias": "Motion Light",
"description": "Turn on light when motion detected",
"mode": "single",
"trigger": [
{
"platform": "state",
"entity_id": "binary_sensor.motion",
"to": "on"
}
],
"action": [
{
"service": "light.turn_on",
"target": {
"entity_id": "light.living_room"
}
}
]
}
}
```
### 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
}
}
]
}
```
#### POST /packages
## Query Functions
Manages HACS packages.
### Get Available Actions
```http
GET /api/actions
```
**Request Body (Install):**
Returns a list of all available actions.
**Example Response:**
```json
{
"action": "install",
"category": "integration",
"repository": "owner/repo",
"version": "1.1.0"
"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 errors in a consistent format:
All endpoints return standard HTTP status codes:
```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
**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
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
// Execute action
async function executeAction() {
const response = await fetch('http://localhost:3000/api/action', {
method: 'POST',
headers: {
'Authorization': 'ApiKey your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
action: 'turn_on_lights',
parameters: {
room: 'living_room',
brightness: 80
}
})
});
const data = await response.json();
console.log('Action result:', data);
}
```