Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
10e895bb94 | ||
|
|
a1cc54f01f |
10
README.md
10
README.md
@@ -58,17 +58,17 @@ Our architecture is engineered for performance, scalability, and security. The f
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph Client
|
||||
A[Client Application<br>(Web / Mobile / Voice)]
|
||||
A["Client Application (Web/Mobile/Voice)"]
|
||||
end
|
||||
subgraph CDN
|
||||
B[CDN / Cache]
|
||||
B["CDN / Cache"]
|
||||
end
|
||||
subgraph Server
|
||||
C[Bun Native Server]
|
||||
E[NLP Engine &<br>Language Processing Module]
|
||||
C["Bun Native Server"]
|
||||
E["NLP Engine & Language Processing Module"]
|
||||
end
|
||||
subgraph Integration
|
||||
D[Home Assistant<br>(Devices, Lights, Thermostats)]
|
||||
D["Home Assistant (Devices, Lights, Thermostats)"]
|
||||
end
|
||||
|
||||
A -->|HTTP Request| B
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Begin your journey with the Home Assistant MCP Server by following these steps:
|
||||
|
||||
- **API Documentation:** Read the [API Documentation](api.md) for available endpoints.
|
||||
- **Real-Time Updates:** Learn about [Server-Sent Events](sse-api.md) for live communication.
|
||||
- **Real-Time Updates:** Learn about [Server-Sent Events](api/sse.md) for live communication.
|
||||
- **Tools:** Explore available [Tools](tools/tools.md) for device control and automation.
|
||||
- **Configuration:** Refer to the [Configuration Guide](getting-started/configuration.md) for setup and advanced settings.
|
||||
|
||||
|
||||
364
docs/sse-api.md
364
docs/sse-api.md
@@ -1,364 +0,0 @@
|
||||
# Home Assistant MCP Server-Sent Events (SSE) API Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The SSE API provides real-time updates from Home Assistant through a persistent connection. This allows clients to receive instant notifications about state changes, events, and other activities without polling.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Available Endpoints
|
||||
|
||||
| Endpoint | Method | Description | Authentication |
|
||||
|----------|---------|-------------|----------------|
|
||||
| `/subscribe_events` | POST | Subscribe to real-time events and state changes | Required |
|
||||
| `/get_sse_stats` | POST | Get statistics about current SSE connections | Required |
|
||||
|
||||
### Event Types Available
|
||||
|
||||
| Event Type | Description | Example Subscription |
|
||||
|------------|-------------|---------------------|
|
||||
| `state_changed` | Entity state changes | `events=state_changed` |
|
||||
| `service_called` | Service call events | `events=service_called` |
|
||||
| `automation_triggered` | Automation trigger events | `events=automation_triggered` |
|
||||
| `script_executed` | Script execution events | `events=script_executed` |
|
||||
| `ping` | Connection keepalive (system) | Automatic |
|
||||
| `error` | Error notifications (system) | Automatic |
|
||||
|
||||
### Subscription Options
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `entity_id` | Subscribe to specific entity | `entity_id=light.living_room` |
|
||||
| `domain` | Subscribe to entire domain | `domain=light` |
|
||||
| `events` | Subscribe to event types | `events=state_changed,automation_triggered` |
|
||||
|
||||
## Authentication
|
||||
|
||||
All SSE connections require authentication using your Home Assistant token.
|
||||
|
||||
```javascript
|
||||
const token = 'YOUR_HASS_TOKEN';
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Subscribe to Events
|
||||
|
||||
`POST /subscribe_events`
|
||||
|
||||
Subscribe to Home Assistant events and state changes.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|------------|----------|----------|-------------|
|
||||
| token | string | Yes | Your Home Assistant authentication token |
|
||||
| events | string[] | No | Array of event types to subscribe to |
|
||||
| entity_id | string | No | Specific entity ID to monitor |
|
||||
| domain | string | No | Domain to monitor (e.g., "light", "switch") |
|
||||
|
||||
#### Example Request
|
||||
|
||||
```javascript
|
||||
const eventSource = new EventSource(`http://localhost:3000/subscribe_events?token=${token}&entity_id=light.living_room&domain=switch&events=state_changed,automation_triggered`);
|
||||
|
||||
eventSource.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Received:', data);
|
||||
};
|
||||
|
||||
eventSource.onerror = (error) => {
|
||||
console.error('SSE Error:', error);
|
||||
eventSource.close();
|
||||
};
|
||||
```
|
||||
|
||||
### Get SSE Statistics
|
||||
|
||||
`POST /get_sse_stats`
|
||||
|
||||
Get current statistics about SSE connections and subscriptions.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|--------|----------|-------------|
|
||||
| token | string | Yes | Your Home Assistant authentication token |
|
||||
|
||||
#### Example Request
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/get_sse_stats \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token": "YOUR_HASS_TOKEN"}'
|
||||
```
|
||||
|
||||
## Event Types
|
||||
|
||||
### Standard Events
|
||||
|
||||
1. **connection**
|
||||
- Sent when a client connects successfully
|
||||
```json
|
||||
{
|
||||
"type": "connection",
|
||||
"status": "connected",
|
||||
"id": "client_uuid",
|
||||
"authenticated": true,
|
||||
"timestamp": "2024-02-10T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
2. **state_changed**
|
||||
- Sent when an entity's state changes
|
||||
```json
|
||||
{
|
||||
"type": "state_changed",
|
||||
"data": {
|
||||
"entity_id": "light.living_room",
|
||||
"state": "on",
|
||||
"attributes": {
|
||||
"brightness": 255,
|
||||
"color_temp": 370
|
||||
},
|
||||
"last_changed": "2024-02-10T12:00:00.000Z",
|
||||
"last_updated": "2024-02-10T12:00:00.000Z"
|
||||
},
|
||||
"timestamp": "2024-02-10T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
3. **service_called**
|
||||
- Sent when a Home Assistant service is called
|
||||
```json
|
||||
{
|
||||
"type": "service_called",
|
||||
"data": {
|
||||
"domain": "light",
|
||||
"service": "turn_on",
|
||||
"service_data": {
|
||||
"entity_id": "light.living_room",
|
||||
"brightness": 255
|
||||
}
|
||||
},
|
||||
"timestamp": "2024-02-10T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
4. **automation_triggered**
|
||||
- Sent when an automation is triggered
|
||||
```json
|
||||
{
|
||||
"type": "automation_triggered",
|
||||
"data": {
|
||||
"automation_id": "automation.morning_routine",
|
||||
"trigger": {
|
||||
"platform": "time",
|
||||
"at": "07:00:00"
|
||||
}
|
||||
},
|
||||
"timestamp": "2024-02-10T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
5. **script_executed**
|
||||
- Sent when a script is executed
|
||||
```json
|
||||
{
|
||||
"type": "script_executed",
|
||||
"data": {
|
||||
"script_id": "script.welcome_home",
|
||||
"execution_data": {
|
||||
"status": "completed"
|
||||
}
|
||||
},
|
||||
"timestamp": "2024-02-10T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### System Events
|
||||
|
||||
1. **ping**
|
||||
- Sent every 30 seconds to keep the connection alive
|
||||
```json
|
||||
{
|
||||
"type": "ping",
|
||||
"timestamp": "2024-02-10T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
2. **error**
|
||||
- Sent when an error occurs
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"error": "rate_limit_exceeded",
|
||||
"message": "Too many requests, please try again later",
|
||||
"timestamp": "2024-02-10T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
- Maximum 1000 requests per minute per client
|
||||
- Rate limits are reset every minute
|
||||
- Exceeding the rate limit will result in an error event
|
||||
|
||||
## Connection Management
|
||||
|
||||
- Maximum 100 concurrent clients
|
||||
- Connections timeout after 5 minutes of inactivity
|
||||
- Ping messages are sent every 30 seconds
|
||||
- Clients should handle reconnection on connection loss
|
||||
|
||||
## Example Implementation
|
||||
|
||||
```javascript
|
||||
class HomeAssistantSSE {
|
||||
constructor(baseUrl, token) {
|
||||
this.baseUrl = baseUrl;
|
||||
this.token = token;
|
||||
this.eventSource = null;
|
||||
this.reconnectAttempts = 0;
|
||||
this.maxReconnectAttempts = 5;
|
||||
this.reconnectDelay = 1000;
|
||||
}
|
||||
|
||||
connect(options = {}) {
|
||||
const params = new URLSearchParams({
|
||||
token: this.token,
|
||||
...(options.events && { events: options.events.join(',') }),
|
||||
...(options.entity_id && { entity_id: options.entity_id }),
|
||||
...(options.domain && { domain: options.domain })
|
||||
});
|
||||
|
||||
this.eventSource = new EventSource(`${this.baseUrl}/subscribe_events?${params}`);
|
||||
|
||||
this.eventSource.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
this.handleEvent(data);
|
||||
};
|
||||
|
||||
this.eventSource.onerror = (error) => {
|
||||
console.error('SSE Error:', error);
|
||||
this.handleError(error);
|
||||
};
|
||||
}
|
||||
|
||||
handleEvent(data) {
|
||||
switch (data.type) {
|
||||
case 'connection':
|
||||
this.reconnectAttempts = 0;
|
||||
console.log('Connected:', data);
|
||||
break;
|
||||
case 'ping':
|
||||
// Connection is alive
|
||||
break;
|
||||
case 'error':
|
||||
console.error('Server Error:', data);
|
||||
break;
|
||||
default:
|
||||
// Handle other event types
|
||||
console.log('Event:', data);
|
||||
}
|
||||
}
|
||||
|
||||
handleError(error) {
|
||||
this.eventSource?.close();
|
||||
|
||||
if (this.reconnectAttempts < this.maxReconnectAttempts) {
|
||||
this.reconnectAttempts++;
|
||||
const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
|
||||
console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
|
||||
setTimeout(() => this.connect(), delay);
|
||||
} else {
|
||||
console.error('Max reconnection attempts reached');
|
||||
}
|
||||
}
|
||||
|
||||
disconnect() {
|
||||
this.eventSource?.close();
|
||||
this.eventSource = null;
|
||||
}
|
||||
}
|
||||
|
||||
// Usage example
|
||||
const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
|
||||
client.connect({
|
||||
events: ['state_changed', 'automation_triggered'],
|
||||
domain: 'light'
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Error Handling**
|
||||
- Implement exponential backoff for reconnection attempts
|
||||
- Handle connection timeouts gracefully
|
||||
- Monitor for rate limit errors
|
||||
|
||||
2. **Resource Management**
|
||||
- Close EventSource when no longer needed
|
||||
- Limit subscriptions to necessary events/entities
|
||||
- Handle cleanup on page unload
|
||||
|
||||
3. **Security**
|
||||
- Never expose the authentication token in client-side code
|
||||
- Use HTTPS in production
|
||||
- Validate all incoming data
|
||||
|
||||
4. **Performance**
|
||||
- Subscribe only to needed events
|
||||
- Implement client-side event filtering
|
||||
- Monitor memory usage for long-running connections
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Connection Failures**
|
||||
- Verify your authentication token is valid
|
||||
- Check server URL is accessible
|
||||
- Ensure proper network connectivity
|
||||
- Verify SSL/TLS configuration if using HTTPS
|
||||
|
||||
2. **Missing Events**
|
||||
- Confirm subscription parameters are correct
|
||||
- Check rate limiting status
|
||||
- Verify entity/domain exists
|
||||
- Monitor client-side event handlers
|
||||
|
||||
3. **Performance Issues**
|
||||
- Reduce number of subscriptions
|
||||
- Implement client-side filtering
|
||||
- Monitor memory usage
|
||||
- Check network latency
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
1. Enable console logging:
|
||||
```javascript
|
||||
const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
|
||||
client.debug = true; // Enables detailed logging
|
||||
```
|
||||
|
||||
2. Monitor network traffic:
|
||||
```javascript
|
||||
// Add event listeners for connection states
|
||||
eventSource.addEventListener('open', () => {
|
||||
console.log('Connection opened');
|
||||
});
|
||||
|
||||
eventSource.addEventListener('error', (e) => {
|
||||
console.log('Connection error:', e);
|
||||
});
|
||||
```
|
||||
|
||||
3. Track subscription status:
|
||||
```javascript
|
||||
// Get current subscriptions
|
||||
const stats = await fetch('/get_sse_stats', {
|
||||
headers: { 'Authorization': `Bearer ${token}` }
|
||||
}).then(r => r.json());
|
||||
|
||||
console.log('Current subscriptions:', stats);
|
||||
```
|
||||
@@ -312,4 +312,63 @@ tar -czf mcp-backup-$(date +%Y%m%d).tar.gz \
|
||||
.env \
|
||||
config/ \
|
||||
data/
|
||||
```
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### General Questions
|
||||
|
||||
#### Q: What is MCP Server?
|
||||
A: MCP Server is a bridge between Home Assistant and Language Learning Models, enabling natural language control and automation of your smart home devices.
|
||||
|
||||
#### Q: What are the system requirements?
|
||||
A: MCP Server requires:
|
||||
- Node.js 16 or higher
|
||||
- Home Assistant instance
|
||||
- 1GB RAM minimum
|
||||
- 1GB disk space
|
||||
|
||||
#### Q: How do I update MCP Server?
|
||||
A: For Docker installation:
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
For manual installation:
|
||||
```bash
|
||||
git pull
|
||||
bun install
|
||||
bun run build
|
||||
```
|
||||
|
||||
### Integration Questions
|
||||
|
||||
#### Q: Can I use MCP Server with any Home Assistant instance?
|
||||
A: Yes, MCP Server works with any Home Assistant instance that has the REST API enabled and a valid long-lived access token.
|
||||
|
||||
#### Q: Does MCP Server support all Home Assistant integrations?
|
||||
A: MCP Server supports all Home Assistant devices and services that are accessible via the REST API.
|
||||
|
||||
### Security Questions
|
||||
|
||||
#### Q: Is my Home Assistant token secure?
|
||||
A: Yes, your Home Assistant token is stored securely and only used for authenticated communication between MCP Server and your Home Assistant instance.
|
||||
|
||||
#### Q: Can I use MCP Server remotely?
|
||||
A: Yes, but we recommend using a secure connection (HTTPS) and proper authentication when exposing MCP Server to the internet.
|
||||
|
||||
### Troubleshooting Questions
|
||||
|
||||
#### Q: Why are my device states not updating?
|
||||
A: Check:
|
||||
1. Home Assistant connection
|
||||
2. WebSocket connection status
|
||||
3. Device availability in Home Assistant
|
||||
4. Network connectivity
|
||||
|
||||
#### Q: Why are my commands not working?
|
||||
A: Verify:
|
||||
1. Command syntax
|
||||
2. Device availability
|
||||
3. User permissions
|
||||
4. Home Assistant API access
|
||||
@@ -91,7 +91,7 @@ nav:
|
||||
- API Reference:
|
||||
- Overview: api/index.md
|
||||
- Core API: api.md
|
||||
- SSE API: sse-api.md
|
||||
- SSE API: api/sse.md
|
||||
- Core Functions: api/core.md
|
||||
- Tools:
|
||||
- Overview: tools/tools.md
|
||||
@@ -114,6 +114,9 @@ nav:
|
||||
- SSE Statistics: tools/events/sse-stats.md
|
||||
- Development:
|
||||
- Overview: development/development.md
|
||||
- Best Practices: development/best-practices.md
|
||||
- Interfaces: development/interfaces.md
|
||||
- Tool Development: development/tools.md
|
||||
- Testing Guide: testing.md
|
||||
- Architecture: architecture.md
|
||||
- Contributing: contributing.md
|
||||
|
||||
Reference in New Issue
Block a user