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

docs: reorganize SSE API documentation and update navigation

Browse Source 
- Move SSE API documentation to a more structured location under `api/`
- Update references to SSE API in getting started and navigation
- Remove standalone SSE API markdown file
- Add FAQ section to troubleshooting documentation
This commit is contained in:
jango-blockchained
2025-02-05 03:07:22 +01:00
parent e3256682ba
commit a1cc54f01f
4 changed files with 65 additions and 367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/getting-started.md
View File

@@ -3,7 +3,7 @@
Begin your journey with the Home Assistant MCP Server by following these steps: Begin your journey with the Home Assistant MCP Server by following these steps:
- **API Documentation:** Read the [API Documentation](api.md) for available endpoints. - **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. - **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. - **Configuration:** Refer to the [Configuration Guide](getting-started/configuration.md) for setup and advanced settings.

364
docs/sse-api.md
View File

@@ -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);
```

59
docs/troubleshooting.md
View File

@@ -313,3 +313,62 @@ tar -czf mcp-backup-$(date +%Y%m%d).tar.gz \
config/ \ config/ \
data/ 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

5
mkdocs.yml
View File

@@ -91,7 +91,7 @@ nav:
- API Reference: - API Reference:
- Overview: api/index.md - Overview: api/index.md
- Core API: api.md - Core API: api.md
- SSE API: sse-api.md - SSE API: api/sse.md
- Core Functions: api/core.md - Core Functions: api/core.md
- Tools: - Tools:
- Overview: tools/tools.md - Overview: tools/tools.md
@@ -114,6 +114,9 @@ nav:
- SSE Statistics: tools/events/sse-stats.md - SSE Statistics: tools/events/sse-stats.md
- Development: - Development:
- Overview: development/development.md - Overview: development/development.md
- Best Practices: development/best-practices.md
- Interfaces: development/interfaces.md
- Tool Development: development/tools.md
- Testing Guide: testing.md - Testing Guide: testing.md
- Architecture: architecture.md - Architecture: architecture.md
- Contributing: contributing.md - Contributing: contributing.md