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

docs: update project documentation with simplified, focused content

Browse Source 
- Streamline README, API, architecture, and usage documentation
- Reduce complexity and focus on core functionality
- Update roadmap with more pragmatic, near-term goals
- Simplify contributing guidelines
- Improve overall documentation clarity and readability
This commit is contained in:
jango-blockchained
2025-02-05 10:40:27 +01:00
parent 8f8e3bd85e
commit 3e7f3920b2
10 changed files with 502 additions and 1451 deletions
Download Patch File Download Diff File Expand all files Collapse all files

269
docs/architecture.md
View File

@@ -6,7 +6,7 @@ nav_order: 4
# Architecture Overview 🏗️
This document describes the architecture of the MCP Server, explaining how different components work together to provide a bridge between Home Assistant and Language Learning Models.
This document describes the architecture of the MCP Server, explaining how different components work together to provide a bridge between Home Assistant and custom automation tools.
## System Architecture
@@ -15,17 +15,13 @@ graph TD
subgraph "Client Layer"
WC[Web Clients]
MC[Mobile Clients]
VC[Voice Assistants]
end
subgraph "MCP Server"
API[API Gateway]
NLP[NLP Engine]
SSE[SSE Manager]
WS[WebSocket Server]
CM[Command Manager]
SC[Scene Controller]
Cache[Redis Cache]
end
subgraph "Home Assistant"
@@ -33,251 +29,60 @@ graph TD
Dev[Devices & Services]
end
subgraph "AI Layer"
LLM[Language Models]
IC[Intent Classifier]
NER[Named Entity Recognition]
end
WC --> |HTTP/WS| API
MC --> |HTTP/WS| API
VC --> |HTTP| API
API --> |Events| SSE
API --> |Real-time| WS
API --> |Process| NLP
NLP --> |Query| LLM
NLP --> |Extract| IC
NLP --> |Identify| NER
CM --> |Execute| HA
HA --> |Control| Dev
SSE --> |State Updates| WC
SSE --> |State Updates| MC
WS --> |Bi-directional| WC
Cache --> |Fast Access| API
HA --> |Events| Cache
API --> HA
HA --> API
```
## Component Details
## Core Components
### 1. Client Layer
### API Gateway
- Handles incoming HTTP and WebSocket requests
- Provides endpoints for device management
- Implements basic authentication and request validation
The client layer consists of various interfaces that interact with the MCP Server:
### SSE Manager
- Manages Server-Sent Events for real-time updates
- Broadcasts device state changes to connected clients
- **Web Clients**: Browser-based dashboards and control panels
- **Mobile Clients**: Native mobile applications
- **Voice Assistants**: Voice-enabled devices and interfaces
### WebSocket Server
- Provides real-time, bidirectional communication
- Supports basic device control and state monitoring
### 2. MCP Server Core
### Command Manager
- Processes device control requests
- Translates API commands to Home Assistant compatible formats
#### API Gateway
- Handles all incoming HTTP requests
- Manages authentication and rate limiting
- Routes requests to appropriate handlers
## Communication Flow
```typescript
interface APIGateway {
authenticate(): Promise<boolean>;
rateLimit(): Promise<boolean>;
route(request: Request): Promise<Response>;
}
```
1. Client sends a request to the MCP Server API
2. API Gateway authenticates the request
3. Command Manager processes the request
4. Request is forwarded to Home Assistant
5. Response is sent back to the client via API or WebSocket
#### NLP Engine
- Processes natural language commands
- Integrates with Language Models
- Extracts intents and entities
## Key Design Principles
```typescript
interface NLPEngine {
processCommand(text: string): Promise<CommandIntent>;
extractEntities(text: string): Promise<Entity[]>;
validateIntent(intent: CommandIntent): boolean;
}
```
- **Simplicity:** Lightweight, focused design
- **Flexibility:** Easily extendable architecture
- **Performance:** Efficient request handling
- **Security:** Basic authentication and validation
#### Event Management
- **SSE Manager**: Handles Server-Sent Events
- **WebSocket Server**: Manages bi-directional communication
- **Command Manager**: Processes and executes commands
## Limitations
### 3. Home Assistant Integration
- Basic device control capabilities
- Limited advanced automation features
- Minimal third-party integrations
The server maintains a robust connection to Home Assistant through:
## Future Improvements
- REST API calls
- WebSocket connections
- Event subscriptions
- Enhanced error handling
- More robust authentication
- Expanded device type support
```typescript
interface HomeAssistantClient {
connect(): Promise<void>;
getState(entityId: string): Promise<EntityState>;
executeCommand(command: Command): Promise<CommandResult>;
subscribeToEvents(callback: EventCallback): Subscription;
}
```
### 4. AI Layer
#### Language Model Integration
- Processes natural language input
- Understands context and user intent
- Generates appropriate responses
#### Intent Classification
- Identifies command types
- Extracts parameters
- Validates requests
## Data Flow
### 1. Command Processing
```mermaid
sequenceDiagram
participant Client
participant API
participant NLP
participant LLM
participant HA
Client->>API: Send command
API->>NLP: Process text
NLP->>LLM: Get intent
LLM-->>NLP: Return structured intent
NLP->>HA: Execute command
HA-->>API: Return result
API-->>Client: Send response
```
### 2. Real-time Updates
```mermaid
sequenceDiagram
participant HA
participant Cache
participant SSE
participant Client
HA->>Cache: State change
Cache->>SSE: Notify change
SSE->>Client: Send update
Note over Client: Update UI
```
### 3. [SSE API](api/sse.md)
- Event Subscriptions
- Real-time Updates
- Connection Management
## Security Architecture
### Authentication Flow
1. **JWT-based Authentication**
```typescript
interface AuthToken {
token: string;
expires: number;
scope: string[];
}
```
2. **Rate Limiting**
```typescript
interface RateLimit {
window: number;
max: number;
current: number;
}
```
### Security Measures
- TLS encryption for all communications
- Input sanitization
- Request validation
- Token-based authentication
- Rate limiting
- IP filtering
## Performance Optimizations
### Caching Strategy
```mermaid
graph LR
Request --> Cache{Cache?}
Cache -->|Hit| Response
Cache -->|Miss| HA[Home Assistant]
HA --> Cache
Cache --> Response
```
### Connection Management
- Connection pooling
- Automatic reconnection
- Load balancing
- Request queuing
## Configuration
The system is highly configurable through environment variables and configuration files:
```yaml
server:
port: 3000
host: '0.0.0.0'
homeAssistant:
url: 'http://homeassistant:8123'
token: 'YOUR_TOKEN'
security:
jwtSecret: 'your-secret'
rateLimit: 100
ai:
model: 'gpt-4'
temperature: 0.7
cache:
ttl: 300
maxSize: '100mb'
```
## Deployment Architecture
### Docker Deployment
```mermaid
graph TD
subgraph "Docker Compose"
MCP[MCP Server]
Redis[Redis Cache]
HA[Home Assistant]
end
MCP --> Redis
MCP --> HA
```
### Scaling Considerations
- Horizontal scaling capabilities
- Load balancing support
- Redis cluster support
- Multiple HA instance support
## Further Reading
- [API Documentation](api/index.md)
- [Installation Guide](getting-started/installation.md)
- [Contributing Guidelines](contributing.md)
- [Troubleshooting](troubleshooting.md)
*Architecture is subject to change as the project evolves.*