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

docs: enhance documentation with comprehensive API, architecture, and installation guides

Browse Source 
- Add detailed API documentation for core functions, SSE, and WebSocket APIs
- Create comprehensive architecture overview with system design diagrams
- Develop in-depth installation and quick start guides
- Improve troubleshooting documentation with advanced debugging techniques
- Update site navigation and markdown configuration
This commit is contained in:
jango-blockchained
2025-02-05 02:44:30 +01:00
parent af3399515a
commit 53a041921b
10 changed files with 1983 additions and 545 deletions
Download Patch File Download Diff File Expand all files Collapse all files

326
docs/api/core.md Normal file
View File

@@ -0,0 +1,326 @@
---
layout: default
title: Core Functions
parent: API Reference
nav_order: 3
---
# Core Functions API 🔧
The Core Functions API provides the fundamental operations for interacting with Home Assistant devices and services through MCP Server.
## Device Control
### Get Device State
Retrieve the current state of devices.
```http
GET /api/state
GET /api/state/{entity_id}
```
Parameters:
- `entity_id` (optional): Specific device ID to query
```bash
# Get all states
curl http://localhost:3000/api/state
# Get specific device state
curl http://localhost:3000/api/state/light.living_room
```
Response:
```json
{
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"color_temp": 370,
"friendly_name": "Living Room Light"
},
"last_changed": "2024-01-20T15:30:00Z"
}
```
### Control Device
Execute device commands.
```http
POST /api/device/control
```
Request body:
```json
{
"entity_id": "light.living_room",
"action": "turn_on",
"parameters": {
"brightness": 200,
"color_temp": 400
}
}
```
Available actions:
- `turn_on`
- `turn_off`
- `toggle`
- `set_value`
Example with curl:
```bash
curl -X POST http://localhost:3000/api/device/control \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"entity_id": "light.living_room",
"action": "turn_on",
"parameters": {
"brightness": 200
}
}'
```
## Natural Language Commands
### Execute Command
Process natural language commands.
```http
POST /api/command
```
Request body:
```json
{
"command": "Turn on the living room lights and set them to 50% brightness"
}
```
Example usage:
```bash
curl -X POST http://localhost:3000/api/command \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"command": "Turn on the living room lights and set them to 50% brightness"
}'
```
Response:
```json
{
"success": true,
"actions": [
{
"entity_id": "light.living_room",
"action": "turn_on",
"parameters": {
"brightness": 127
},
"status": "completed"
}
],
"message": "Command executed successfully"
}
```
## Scene Management
### Create Scene
Define a new scene with multiple actions.
```http
POST /api/scene
```
Request body:
```json
{
"name": "Movie Night",
"description": "Perfect lighting for movie watching",
"actions": [
{
"entity_id": "light.living_room",
"action": "turn_on",
"parameters": {
"brightness": 50,
"color_temp": 500
}
},
{
"entity_id": "cover.living_room",
"action": "close"
}
]
}
```
### Activate Scene
Trigger a predefined scene.
```http
POST /api/scene/{scene_name}/activate
```
Example:
```bash
curl -X POST http://localhost:3000/api/scene/movie_night/activate \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
```
## Groups
### Create Device Group
Create a group of devices for collective control.
```http
POST /api/group
```
Request body:
```json
{
"name": "Living Room",
"entities": [
"light.living_room_main",
"light.living_room_accent",
"switch.living_room_fan"
]
}
```
### Control Group
Control multiple devices in a group.
```http
POST /api/group/{group_name}/control
```
Request body:
```json
{
"action": "turn_off"
}
```
## System Operations
### Health Check
Check server status and connectivity.
```http
GET /health
```
Response:
```json
{
"status": "healthy",
"version": "1.0.0",
"uptime": 3600,
"homeAssistant": {
"connected": true,
"version": "2024.1.0"
}
}
```
### Configuration
Get current server configuration.
```http
GET /api/config
```
Response:
```json
{
"server": {
"port": 3000,
"host": "0.0.0.0",
"version": "1.0.0"
},
"homeAssistant": {
"url": "http://homeassistant:8123",
"connected": true
},
"features": {
"nlp": true,
"scenes": true,
"groups": true
}
}
```
## Error Handling
All endpoints follow standard HTTP status codes and return detailed error messages:
```json
{
"error": true,
"code": "INVALID_ENTITY",
"message": "Device 'light.nonexistent' not found",
"details": {
"entity_id": "light.nonexistent",
"available_entities": [
"light.living_room",
"light.kitchen"
]
}
}
```
Common error codes:
- `INVALID_ENTITY`: Device not found
- `INVALID_ACTION`: Unsupported action
- `INVALID_PARAMETERS`: Invalid command parameters
- `AUTHENTICATION_ERROR`: Invalid or missing token
- `CONNECTION_ERROR`: Home Assistant connection issue
## TypeScript Interfaces
```typescript
interface DeviceState {
entity_id: string;
state: string;
attributes: Record<string, any>;
last_changed: string;
}
interface DeviceCommand {
entity_id: string;
action: 'turn_on' | 'turn_off' | 'toggle' | 'set_value';
parameters?: Record<string, any>;
}
interface Scene {
name: string;
description?: string;
actions: DeviceCommand[];
}
interface Group {
name: string;
entities: string[];
}
```
## Related Resources
- [API Overview](index.md)
- [SSE API](sse.md)
- [Architecture](../architecture.md)
- [Examples](https://github.com/jango-blockchained/advanced-homeassistant-mcp/tree/main/examples)

234
docs/api/index.md Normal file
View File

@@ -0,0 +1,234 @@
---
layout: default
title: API Overview
parent: API Reference
nav_order: 1
has_children: false
---
# API Documentation 📚
Welcome to the MCP Server API documentation. This guide covers all available endpoints, authentication methods, and integration patterns.
## API Overview
The MCP Server provides several API categories:
1. **Core API** - Basic device control and state management
2. **SSE API** - Real-time event subscriptions
3. **Scene API** - Scene management and automation
4. **Voice API** - Natural language command processing
## Authentication
All API endpoints require authentication using JWT tokens:
```bash
# Include the token in your requests
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" http://localhost:3000/api/state
```
To obtain a token:
```bash
curl -X POST http://localhost:3000/auth/token \
-H "Content-Type: application/json" \
-d '{"username": "your_username", "password": "your_password"}'
```
## Core Endpoints
### Device State
```http
GET /api/state
```
Retrieve the current state of all devices:
```bash
curl http://localhost:3000/api/state
```
Response:
```json
{
"devices": [
{
"id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"color_temp": 370
}
}
]
}
```
### Command Execution
```http
POST /api/command
```
Execute a natural language command:
```bash
curl -X POST http://localhost:3000/api/command \
-H "Content-Type: application/json" \
-d '{"command": "Turn on the kitchen lights"}'
```
Response:
```json
{
"success": true,
"action": "turn_on",
"device": "light.kitchen",
"message": "Kitchen lights turned on"
}
```
## Real-Time Events
### Event Subscription
```http
GET /subscribe_events
```
Subscribe to device state changes:
```javascript
const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN');
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('State changed:', data);
};
```
### Filtered Subscriptions
Subscribe to specific device types:
```http
GET /subscribe_events?domain=light
GET /subscribe_events?entity_id=light.living_room
```
## Scene Management
### Create Scene
```http
POST /api/scene
```
Create a new scene:
```bash
curl -X POST http://localhost:3000/api/scene \
-H "Content-Type: application/json" \
-d '{
"name": "Movie Night",
"actions": [
{"device": "light.living_room", "action": "dim", "value": 20},
{"device": "media_player.tv", "action": "on"}
]
}'
```
### Activate Scene
```http
POST /api/scene/activate
```
Activate an existing scene:
```bash
curl -X POST http://localhost:3000/api/scene/activate \
-H "Content-Type: application/json" \
-d '{"name": "Movie Night"}'
```
## Error Handling
The API uses standard HTTP status codes:
- `200` - Success
- `400` - Bad Request
- `401` - Unauthorized
- `404` - Not Found
- `500` - Server Error
Error responses include detailed messages:
```json
{
"error": true,
"message": "Device not found",
"code": "DEVICE_NOT_FOUND",
"details": {
"device_id": "light.nonexistent"
}
}
```
## Rate Limiting
API requests are rate-limited to prevent abuse:
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200
```
When exceeded, returns `429 Too Many Requests`:
```json
{
"error": true,
"message": "Rate limit exceeded",
"reset": 1640995200
}
```
## WebSocket API
For bi-directional communication:
```javascript
const ws = new WebSocket('ws://localhost:3000/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received:', data);
};
ws.send(JSON.stringify({
type: 'command',
payload: {
command: 'Turn on lights'
}
}));
```
## API Versioning
The current API version is v1. Include the version in the URL:
```http
/api/v1/state
/api/v1/command
```
## Further Reading
- [SSE API Details](sse.md) - In-depth SSE documentation
- [Core Functions](core.md) - Detailed endpoint documentation
- [Architecture Overview](../architecture.md) - System design details
- [Troubleshooting](../troubleshooting.md) - Common issues and solutions

266
docs/api/sse.md Normal file
View File

@@ -0,0 +1,266 @@
---
layout: default
title: SSE API
parent: API Reference
nav_order: 2
---
# Server-Sent Events (SSE) API 📡
The SSE API provides real-time updates about device states and events from your Home Assistant setup. This guide covers how to use and implement SSE connections in your applications.
## Overview
Server-Sent Events (SSE) is a standard that enables servers to push real-time updates to clients over HTTP connections. MCP Server uses SSE to provide:
- Real-time device state updates
- Event notifications
- System status changes
- Command execution results
## Basic Usage
### Establishing a Connection
Create an EventSource connection to receive updates:
```javascript
const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_JWT_TOKEN');
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received update:', data);
};
```
### Connection States
Handle different connection states:
```javascript
eventSource.onopen = () => {
console.log('Connection established');
};
eventSource.onerror = (error) => {
console.error('Connection error:', error);
// Implement reconnection logic if needed
};
```
## Event Types
### Device State Events
Subscribe to all device state changes:
```javascript
const stateEvents = new EventSource('http://localhost:3000/subscribe_events?type=state');
stateEvents.onmessage = (event) => {
const state = JSON.parse(event.data);
console.log('Device state changed:', state);
};
```
Example state event:
```json
{
"type": "state_changed",
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"color_temp": 370
},
"timestamp": "2024-01-20T15:30:00Z"
}
```
### Filtered Subscriptions
#### By Domain
Subscribe to specific device types:
```javascript
// Subscribe to only light events
const lightEvents = new EventSource('http://localhost:3000/subscribe_events?domain=light');
// Subscribe to multiple domains
const multiEvents = new EventSource('http://localhost:3000/subscribe_events?domain=light,switch,sensor');
```
#### By Entity ID
Subscribe to specific devices:
```javascript
// Single entity
const livingRoomLight = new EventSource(
'http://localhost:3000/subscribe_events?entity_id=light.living_room'
);
// Multiple entities
const kitchenDevices = new EventSource(
'http://localhost:3000/subscribe_events?entity_id=light.kitchen,switch.coffee_maker'
);
```
## Advanced Usage
### Connection Management
Implement robust connection handling:
```javascript
class SSEManager {
constructor(url, options = {}) {
this.url = url;
this.options = {
maxRetries: 3,
retryDelay: 1000,
...options
};
this.retryCount = 0;
this.connect();
}
connect() {
this.eventSource = new EventSource(this.url);
this.eventSource.onopen = () => {
this.retryCount = 0;
console.log('Connected to SSE stream');
};
this.eventSource.onerror = (error) => {
this.handleError(error);
};
this.eventSource.onmessage = (event) => {
this.handleMessage(event);
};
}
handleError(error) {
console.error('SSE Error:', error);
this.eventSource.close();
if (this.retryCount < this.options.maxRetries) {
this.retryCount++;
setTimeout(() => {
console.log(`Retrying connection (${this.retryCount}/${this.options.maxRetries})`);
this.connect();
}, this.options.retryDelay * this.retryCount);
}
}
handleMessage(event) {
try {
const data = JSON.parse(event.data);
// Handle the event data
console.log('Received:', data);
} catch (error) {
console.error('Error parsing SSE data:', error);
}
}
disconnect() {
if (this.eventSource) {
this.eventSource.close();
}
}
}
// Usage
const sseManager = new SSEManager('http://localhost:3000/subscribe_events?token=YOUR_TOKEN');
```
### Event Filtering
Filter events on the client side:
```javascript
class EventFilter {
constructor(conditions) {
this.conditions = conditions;
}
matches(event) {
return Object.entries(this.conditions).every(([key, value]) => {
if (Array.isArray(value)) {
return value.includes(event[key]);
}
return event[key] === value;
});
}
}
// Usage
const filter = new EventFilter({
domain: ['light', 'switch'],
state: 'on'
});
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
if (filter.matches(data)) {
console.log('Matched event:', data);
}
};
```
## Best Practices
1. **Authentication**
- Always include authentication tokens
- Implement token refresh mechanisms
- Handle authentication errors gracefully
2. **Error Handling**
- Implement progressive retry logic
- Log connection issues
- Notify users of connection status
3. **Resource Management**
- Close EventSource connections when not needed
- Limit the number of concurrent connections
- Use filtered subscriptions when possible
4. **Performance**
- Process events efficiently
- Batch UI updates
- Consider debouncing frequent updates
## Common Issues
### Connection Drops
If the connection drops, the EventSource will automatically attempt to reconnect. You can customize this behavior:
```javascript
eventSource.addEventListener('error', (error) => {
if (eventSource.readyState === EventSource.CLOSED) {
// Connection closed, implement custom retry logic
}
});
```
### Memory Leaks
Always clean up EventSource connections:
```javascript
// In a React component
useEffect(() => {
const eventSource = new EventSource('http://localhost:3000/subscribe_events');
return () => {
eventSource.close(); // Cleanup on unmount
};
}, []);
```
## Related Resources
- [API Overview](index.md)
- [Core Functions](core.md)
- [WebSocket API](index.md#websocket-api)
- [Troubleshooting](../troubleshooting.md)