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

782
docs/api.md
View File

@@ -1,728 +1,170 @@
# 🚀 Home Assistant MCP API Documentation
# Home Assistant MCP Server API Documentation
![API Version](https://img.shields.io/badge/API-v2.1-blueviolet) ![Rate Limit](https://img.shields.io/badge/Rate%20Limit-100%2Fmin-brightgreen)
## Overview
## 🌟 Quick Start
This document provides a reference for the MCP Server API, which offers basic device control and state management for Home Assistant.
```bash
# Get API schema with caching
curl -X GET http://localhost:3000/mcp \
-H "Cache-Control: max-age=3600" # Cache for 1 hour
```
## Authentication
## 🔌 Core Functions ⚙️
All API requests require a valid JWT token in the Authorization header:
### State Management (`/api/state`)
```http
GET /api/state?cache=true # Enable client-side caching
POST /api/state
Authorization: Bearer YOUR_TOKEN
```
**Example Request:**
## Core Endpoints
### Device State Management
#### Get Device State
```http
GET /api/state/{entity_id}
```
**Response:**
```json
{
"context": "living_room",
"state": {
"lights": "on",
"temperature": 22
},
"_cache": { // Optional caching config
"ttl": 300, // 5 minutes
"tags": ["lights", "climate"]
}
}
```
## ⚡ Action Endpoints
### Execute Action with Cache Validation
```http
POST /api/action
If-None-Match: "etag_value" // Prevent duplicate actions
```
**Batch Processing:**
```json
{
"actions": [
{ "action": "🌞 Morning Routine", "params": { "brightness": 80 } },
{ "action": "❄️ AC Control", "params": { "temp": 21 } }
],
"_parallel": true // Execute actions concurrently
}
```
## 🔍 Query Functions
### Available Actions with ETag
```http
GET /api/actions
ETag: "a1b2c3d4" // Client-side cache validation
```
**Response Headers:**
```
Cache-Control: public, max-age=86400 // 24-hour cache
ETag: "a1b2c3d4"
```
## 🌐 WebSocket Events
```javascript
const ws = new WebSocket('wss://ha-mcp/ws');
ws.onmessage = ({ data }) => {
const event = JSON.parse(data);
if(event.type === 'STATE_UPDATE') {
updateUI(event.payload); // 🎨 Real-time UI sync
}
};
```
## 🗃️ Caching Strategies
### Client-Side Caching
```http
GET /api/devices
Cache-Control: max-age=300, stale-while-revalidate=60
```
### Server-Side Cache-Control
```typescript
// Example middleware configuration
app.use(
cacheMiddleware({
ttl: 60 * 5, // 5 minutes
paths: ['/api/devices', '/mcp'],
vary: ['Authorization'] // User-specific caching
})
);
```
## ❌ Error Handling
**429 Too Many Requests:**
```json
{
"error": {
"code": "RATE_LIMITED",
"message": "Slow down! 🐢",
"retry_after": 30,
"docs": "https://ha-mcp/docs/rate-limits"
}
}
```
## 🚦 Rate Limiting Tiers
| Tier | Requests/min | Features |
|---------------|--------------|------------------------|
| Guest | 10 | Basic read-only |
| User | 100 | Full access |
| Power User | 500 | Priority queue |
| Integration | 1000 | Bulk operations |
## 🛠️ Example Usage
### Smart Cache Refresh
```javascript
async function getDevices() {
const response = await fetch('/api/devices', {
headers: {
'If-None-Match': localStorage.getItem('devicesETag')
}
});
if(response.status === 304) { // Not Modified
return JSON.parse(localStorage.devicesCache);
}
const data = await response.json();
localStorage.setItem('devicesETag', response.headers.get('ETag'));
localStorage.setItem('devicesCache', JSON.stringify(data));
return data;
}
```
## 🔒 Security Middleware (Enhanced)
### Cache-Aware Rate Limiting
```typescript
app.use(
rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 100, // Limit each IP to 100 requests per window
cache: new RedisStore(), // Distributed cache
keyGenerator: (req) => {
return `${req.ip}-${req.headers.authorization}`;
}
})
);
```
### Security Headers
```http
Content-Security-Policy: default-src 'self';
Strict-Transport-Security: max-age=31536000;
X-Content-Type-Options: nosniff;
Cache-Control: public, max-age=600;
ETag: "abc123"
```
## 📘 Best Practices
1. **Cache Wisely:** Use `ETag` and `Cache-Control` headers for state data
2. **Batch Operations:** Combine requests using `/api/actions/batch`
3. **WebSocket First:** Prefer real-time updates over polling
4. **Error Recovery:** Implement exponential backoff with jitter
5. **Cache Invalidation:** Use tags for bulk invalidation
```mermaid
graph LR
A[Client] -->|Cached Request| B{CDN}
B -->|Cache Hit| C[Return 304]
B -->|Cache Miss| D[Origin Server]
D -->|Response| B
B -->|Response| A
```
> Pro Tip: Use `curl -I` to inspect cache headers! 🔍
## Device Control
### Common Entity Controls
```json
{
"tool": "control",
"command": "turn_on", // Options: "turn_on", "turn_off", "toggle"
"entity_id": "light.living_room"
}
```
### Light Control
```json
{
"tool": "control",
"command": "turn_on",
"entity_id": "light.living_room",
"brightness": 128,
"color_temp": 4000,
"rgb_color": [255, 0, 0]
}
```
## Add-on Management
### List Available Add-ons
```json
{
"tool": "addon",
"action": "list"
}
```
### Install Add-on
```json
{
"tool": "addon",
"action": "install",
"slug": "core_configurator",
"version": "5.6.0"
}
```
### Manage Add-on State
```json
{
"tool": "addon",
"action": "start", // Options: "start", "stop", "restart"
"slug": "core_configurator"
}
```
## Package Management
### List HACS Packages
```json
{
"tool": "package",
"action": "list",
"category": "integration" // Options: "integration", "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}
```
### Install Package
```json
{
"tool": "package",
"action": "install",
"category": "integration",
"repository": "hacs/integration",
"version": "1.32.0"
}
```
## Automation Management
For automation management details and endpoints, please refer to the [Tools Documentation](tools/tools.md).
## Security Considerations
- Validate and sanitize all user inputs.
- Enforce rate limiting to prevent abuse.
- Apply proper security headers.
- Gracefully handle errors based on the environment.
## Troubleshooting
If you experience issues with the API:
- Verify the endpoint and request payload.
- Check authentication tokens and required headers.
- Consult the [Troubleshooting Guide](troubleshooting.md) for further guidance.
## MCP Schema Endpoint
The server exposes an MCP (Model Context Protocol) schema endpoint that describes all available tools and their parameters:
```http
GET /mcp
```
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.
Example response:
```json
{
"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", ...]
},
"area": { "type": "string" },
"floor": { "type": "string" }
}
}
},
// ... other tools
],
"prompts": [],
"resources": [
{
"name": "Home Assistant API",
"url": "https://developers.home-assistant.io/docs/api/rest/"
}
]
}
```
Note: The `/mcp` endpoint is publicly accessible and does not require authentication, as it only provides schema information.
## 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
"state": "on",
"attributes": {
"brightness": 128
}
}
```
### Context Updates
#### Update Device State
```http
POST /api/context
```
POST /api/state
Content-Type: application/json
Updates the current context with new information.
**Example Request:**
```json
POST /api/context
{
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 128
}
}
```
## Action Endpoints
### Device Control
### Execute Action
#### Execute Device Command
```http
POST /api/action
```
POST /api/control
Content-Type: application/json
Executes a specified action with given parameters.
**Example Request:**
```json
POST /api/action
{
"action": "turn_on_lights",
"entity_id": "light.living_room",
"command": "turn_on",
"parameters": {
"room": "living_room",
"brightness": 80
"brightness": 50
}
}
```
### Batch Actions
```http
POST /api/actions/batch
```
## Real-Time Updates
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
}
}
]
}
```
## Query Functions
### Get Available Actions
```http
GET /api/actions
```
Returns a list of all available actions.
**Example Response:**
```json
{
"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.
### WebSocket Connection
Connect to real-time updates:
```javascript
// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');
const ws = new WebSocket('ws://localhost:3000/events');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received update:', data);
const deviceUpdate = JSON.parse(event.data);
console.log('Device state changed:', deviceUpdate);
};
```
### 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 standard HTTP status codes:
### Common Error Responses
- 200: Success
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
**Error Response Format:**
```json
{
"error": {
"code": "INVALID_PARAMETERS",
"message": "Missing required parameter: room",
"details": {
"missing_fields": ["room"]
}
"code": "INVALID_REQUEST",
"message": "Invalid request parameters",
"details": "Entity ID not found or invalid command"
}
}
```
## Rate Limiting
The API implements rate limiting to prevent abuse:
Basic rate limiting is implemented:
- Maximum of 100 requests per minute
- Excess requests will receive a 429 Too Many Requests response
- 100 requests per minute per IP for regular endpoints
- 1000 requests per minute per IP for WebSocket connections
## Supported Operations
When rate limit is exceeded, the server returns:
### Supported Commands
- `turn_on`
- `turn_off`
- `toggle`
- `set_brightness`
- `set_color`
```json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"reset_time": "2024-03-20T10:31:00Z"
### Supported Entities
- Lights
- Switches
- Climate controls
- Media players
## Limitations
- Limited to basic device control
- No advanced automation
- Minimal error handling
- Basic authentication
## Best Practices
1. Always include a valid JWT token
2. Handle potential errors in your client code
3. Use WebSocket for real-time updates when possible
4. Validate entity IDs before sending commands
## Example Client Usage
```typescript
async function controlDevice(entityId: string, command: string, params?: Record<string, unknown>) {
try {
const response = await fetch('/api/control', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({
entity_id: entityId,
command,
parameters: params
})
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message);
}
return await response.json();
} catch (error) {
console.error('Device control failed:', error);
throw error;
}
}
// Usage example
controlDevice('light.living_room', 'turn_on', { brightness: 50 })
.then(result => console.log('Device controlled successfully'))
.catch(error => console.error('Control failed', error));
```
## Example Usage
## Future Development
### Using curl
```bash
# Get current state
curl -X GET \
http://localhost:3000/api/state \
-H 'Authorization: ApiKey your_api_key_here'
Planned improvements:
- Enhanced error handling
- More comprehensive device support
- Improved authentication mechanisms
# 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
// 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);
}
```
## Security Middleware
### Overview
The security middleware provides a comprehensive set of utility functions to enhance the security of the Home Assistant MCP application. These functions cover various aspects of web security, including:
- Rate limiting
- Request validation
- Input sanitization
- Security headers
- Error handling
### Utility Functions
#### `checkRateLimit(ip: string, maxRequests?: number, windowMs?: number)`
Manages rate limiting for IP addresses to prevent abuse.
**Parameters**:
- `ip`: IP address to track
- `maxRequests`: Maximum number of requests allowed (default: 100)
- `windowMs`: Time window for rate limiting (default: 15 minutes)
**Returns**: `boolean` or throws an error if limit is exceeded
**Example**:
```typescript
try {
checkRateLimit('127.0.0.1'); // Checks rate limit with default settings
} catch (error) {
// Handle rate limit exceeded
}
```
#### `validateRequestHeaders(request: Request, requiredContentType?: string)`
Validates incoming HTTP request headers for security and compliance.
**Parameters**:
- `request`: The incoming HTTP request
- `requiredContentType`: Expected content type (default: 'application/json')
**Checks**:
- Content type
- Request body size
- Authorization header (optional)
**Example**:
```typescript
try {
validateRequestHeaders(request);
} catch (error) {
// Handle validation errors
}
```
#### `sanitizeValue(value: unknown)`
Sanitizes input values to prevent XSS attacks.
**Features**:
- Escapes HTML tags
- Handles nested objects and arrays
- Preserves non-string values
**Example**:
```typescript
const sanitized = sanitizeValue('<script>alert("xss")</script>');
// Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
```
#### `applySecurityHeaders(request: Request, helmetConfig?: HelmetOptions)`
Applies security headers to HTTP requests using Helmet.
**Security Headers**:
- Content Security Policy
- X-Frame-Options
- X-Content-Type-Options
- Referrer Policy
- HSTS (in production)
**Example**:
```typescript
const headers = applySecurityHeaders(request);
```
#### `handleError(error: Error, env?: string)`
Handles error responses with environment-specific details.
**Modes**:
- Production: Generic error message
- Development: Detailed error with stack trace
**Example**:
```typescript
const errorResponse = handleError(error, process.env.NODE_ENV);
```
### Middleware Usage
These utility functions are integrated into Elysia middleware:
```typescript
const app = new Elysia()
.use(rateLimiter) // Rate limiting
.use(validateRequest) // Request validation
.use(sanitizeInput) // Input sanitization
.use(securityHeaders) // Security headers
.use(errorHandler) // Error handling
```
### Best Practices
1. Always validate and sanitize user inputs
2. Use rate limiting to prevent abuse
3. Apply security headers
4. Handle errors gracefully
5. Keep environment-specific error handling
### Security Considerations
- Configurable rate limits
- XSS protection
- Content security policies
- Token validation
- Error information exposure control
### Troubleshooting
- Ensure `JWT_SECRET` is set in environment
- Check content type in requests
- Monitor rate limit errors
- Review error handling in different environments
*API is subject to change. Always refer to the latest documentation.*

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.*

218
docs/contributing.md
View File

@@ -6,249 +6,119 @@ nav_order: 5
# Contributing Guide 🤝
Thank you for your interest in contributing to the MCP Server project! This guide will help you get started with contributing to the project.
Thank you for your interest in contributing to the MCP Server project!
## Getting Started
### Prerequisites
Before you begin, ensure you have:
- [Bun](https://bun.sh) >= 1.0.26
- [Node.js](https://nodejs.org) >= 18
- [Docker](https://www.docker.com) (optional, for containerized development)
- A running Home Assistant instance for testing
- Home Assistant instance
- Basic understanding of TypeScript
### Development Setup
1. Fork and clone the repository:
1. Fork the repository
2. Clone your fork:
```bash
git clone https://github.com/YOUR_USERNAME/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
git clone https://github.com/YOUR_USERNAME/homeassistant-mcp.git
cd homeassistant-mcp
```
2. Install dependencies:
3. Install dependencies:
```bash
bun install
```
3. Set up your development environment:
4. Configure environment:
```bash
cp .env.example .env
# Edit .env with your Home Assistant details
```
4. Start the development server:
```bash
bun run dev
```
## Development Workflow
### Branch Naming Convention
### Branch Naming
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation updates
- `refactor/` - Code refactoring
- `test/` - Test improvements
Example:
```bash
git checkout -b feature/voice-commands
git checkout -b feature/device-control-improvements
```
### Commit Messages
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
Follow simple, clear commit messages:
```
type(scope): description
type: brief description
[optional body]
[optional footer]
[optional detailed explanation]
```
Types:
- `feat:` - New features
- `fix:` - Bug fixes
- `docs:` - Documentation changes
- `style:` - Code style changes (formatting, etc.)
- `refactor:` - Code refactoring
- `test:` - Test updates
- `chore:` - Maintenance tasks
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation
- `chore:` - Maintenance
Examples:
```bash
feat(api): add voice command endpoint
fix(sse): resolve connection timeout issue
docs(readme): update installation instructions
```
### Code Style
### Testing
- Use TypeScript
- Follow existing code structure
- Keep changes focused and minimal
Run tests before submitting your changes:
## Testing
Run tests before submitting:
```bash
# Run all tests
bun test
# Run specific test file
bun test test/api/command.test.ts
# Run tests with coverage
bun test --coverage
```
### Code Style
We use ESLint and Prettier for code formatting:
```bash
# Check code style
bun run lint
# Fix code style issues
bun run lint:fix
# Run specific test
bun test test/api/control.test.ts
```
## Pull Request Process
1. **Update Documentation**
- Add/update relevant documentation
- Include inline code comments where necessary
- Update API documentation if endpoints change
2. **Write Tests**
- Add tests for new features
- Update existing tests if needed
- Ensure all tests pass
3. **Create Pull Request**
- Fill out the PR template
- Link related issues
- Provide clear description of changes
4. **Code Review**
- Address review comments
- Keep discussions focused
- Be patient and respectful
1. Ensure tests pass
2. Update documentation if needed
3. Provide clear description of changes
### PR Template
```markdown
## Description
Brief description of the changes
Brief explanation of the changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## How Has This Been Tested?
Describe your test process
## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code follows style guidelines
- [ ] All tests passing
## Testing
Describe how you tested these changes
```
## Development Guidelines
## Reporting Issues
### Code Organization
- Use GitHub Issues
- Provide clear, reproducible steps
- Include environment details
```
src/
├── api/ # API endpoints
├── core/ # Core functionality
├── models/ # Data models
├── services/ # Business logic
├── utils/ # Utility functions
└── types/ # TypeScript types
```
## Code of Conduct
### Best Practices
1. **Type Safety**
```typescript
// Use explicit types
interface CommandRequest {
command: string;
parameters?: Record<string, unknown>;
}
function processCommand(request: CommandRequest): Promise<CommandResponse> {
// Implementation
}
```
2. **Error Handling**
```typescript
try {
await processCommand(request);
} catch (error) {
if (error instanceof ValidationError) {
// Handle validation errors
}
throw error;
}
```
3. **Async/Await**
```typescript
// Prefer async/await over promises
async function handleRequest() {
const result = await processData();
return result;
}
```
## Documentation
### API Documentation
Update API documentation when adding/modifying endpoints:
```typescript
/**
* Process a voice command
* @param command - The voice command to process
* @returns Promise<CommandResult>
* @throws {ValidationError} If command is invalid
*/
async function processVoiceCommand(command: string): Promise<CommandResult> {
// Implementation
}
```
### README Updates
Keep the README up to date with:
- New features
- Changed requirements
- Updated examples
- Modified configuration
## Getting Help
- Check [Discussions](https://github.com/jango-blockchained/advanced-homeassistant-mcp/discussions)
- Review existing [Issues](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues)
## Community Guidelines
We expect all contributors to:
- Be respectful and inclusive
- Be respectful
- Focus on constructive feedback
- Help maintain a positive environment
- Follow our code style guidelines
- Write clear documentation
- Test their code thoroughly
## License
## Resources
By contributing, you agree that your contributions will be licensed under the MIT License.
- [API Documentation](api.md)
- [Troubleshooting Guide](troubleshooting.md)
*Thank you for contributing!*

39
docs/index.md
View File

@@ -4,31 +4,25 @@ title: Home
nav_order: 1
---
# 🚀 MCP Server for Home Assistant
# 🏠 MCP Server for Home Assistant
Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating AI-powered natural language processing into your Home Assistant setup.
Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating a lightweight automation tool with your Home Assistant setup.
## What is MCP Server?
MCP Server is a bridge between Home Assistant and Language Learning Models (LLMs), enabling natural language interactions and real-time automation of your smart devices. It allows you to control your home automation setup using natural language commands while maintaining high performance and security.
MCP Server is a bridge between Home Assistant and custom automation tools, enabling basic device control and real-time monitoring of your smart home environment. It provides a flexible interface for managing and interacting with your home automation setup.
## Key Features
### 🎮 Device Control & Monitoring
- Voice-controlled automation
- Real-time updates via SSE/WebSocket
- Scene-based automation rules
### 🤖 AI-Powered Features
- Natural Language Processing (NLP)
- Predictive automation
- Anomaly detection
### 🎮 Device Control
- Basic REST API for device management
- WebSocket and Server-Sent Events (SSE) for real-time updates
- Simple automation rule support
### 🛡️ Security & Performance
- JWT authentication
- Request sanitization
- Sub-100ms latency
- Rate limiting
- Basic request validation
- Lightweight server design
## Documentation Structure
@@ -37,19 +31,18 @@ MCP Server is a bridge between Home Assistant and Language Learning Models (LLMs
- [Quick Start Tutorial](getting-started/quickstart.md) - Basic usage examples
### Core Documentation
- [API Documentation](api/index.md) - Complete API reference
- [Architecture Overview](architecture.md) - System design and components
- [API Documentation](api/index.md) - API reference
- [Architecture Overview](architecture.md) - System design
- [Contributing Guidelines](contributing.md) - How to contribute
- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
- [Troubleshooting Guide](troubleshooting.md) - Common issues
## Support
If you need help or want to report issues:
Need help or want to report issues?
- [GitHub Issues](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues)
- [GitHub Discussions](https://github.com/jango-blockchained/advanced-homeassistant-mcp/discussions)
- [Contributing Guidelines](contributing.md)
- [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues)
- [GitHub Discussions](https://github.com/jango-blockchained/homeassistant-mcp/discussions)
## License
This project is licensed under the MIT License. See the [LICENSE](https://github.com/jango-blockchained/advanced-homeassistant-mcp/blob/main/LICENSE) file for details.
This project is licensed under the MIT License. See the [LICENSE](https://github.com/jango-blockchained/homeassistant-mcp/blob/main/LICENSE) file for details.

61
docs/roadmap.md
View File

@@ -1,51 +1,52 @@
# Roadmap for MCP Server
The following roadmap outlines our planned enhancements and future directions for the Home Assistant MCP Server. This document is a living guide that will be updated as new features are planned and developed.
The following roadmap outlines our planned enhancements and future directions for the Home Assistant MCP Server. This document is a living guide that will be updated as new features are developed.
## Near-Term Goals
- **Advanced Automation Capabilities:**
- Integrate sophisticated automation rules with conditional logic and multi-step execution.
- Introduce a visual automation builder for simplified rule creation.
- **Core Functionality Improvements:**
- Enhance REST API capabilities
- Improve WebSocket and SSE reliability
- Develop more robust error handling
- **Enhanced Security Features:**
- Implement multi-factor authentication for critical actions.
- Strengthen encryption methods and data handling practices.
- Expand monitoring and alerting for potential security breaches.
- **Security Enhancements:**
- Strengthen JWT authentication
- Improve input validation
- Add basic logging for security events
- **Performance Optimizations:**
- Refine resource utilization to reduce latency.
- Optimize real-time data streaming via SSE.
- Introduce advanced caching mechanisms for frequently requested data.
- Optimize server response times
- Improve resource utilization
- Implement basic caching mechanisms
## Mid-Term Goals
- **User Interface Improvements:**
- Develop an intuitive web-based dashboard for device management and monitoring.
- Provide real-time analytics and performance metrics.
- **Device Integration:**
- Expand support for additional Home Assistant device types
- Improve device state synchronization
- Develop more flexible automation rule support
- **Expanded Integrations:**
- Support a broader range of smart home devices and brands.
- Integrate with additional home automation platforms and third-party services.
- **Developer Experience Enhancements:**
- Improve documentation and developer tooling.
- Streamline contribution guidelines and testing setups.
- **Developer Experience:**
- Improve documentation
- Create more comprehensive examples
- Develop basic CLI tools for configuration
## Long-Term Vision
- **Ecosystem Expansion:**
- Build a modular plugin system for community-driven extensions and integrations.
- Enable seamless integration with future technologies in smart home and AI domains.
- **Extensibility:**
- Design a simple plugin system
- Create guidelines for community contributions
- Establish a clear extension mechanism
- **Scalability and Resilience:**
- Architect the system to support large-scale deployments.
- Incorporate advanced load balancing and failover mechanisms.
- **Reliability:**
- Implement comprehensive testing
- Develop monitoring and basic health check features
- Improve overall system stability
## How to Follow the Roadmap
- **Community Involvement:** We welcome and encourage feedback.
- **Regular Updates:** This document is updated regularly with new goals and milestones.
- **Transparency:** Check our GitHub repository and issue tracker for ongoing discussions.
- **Community Involvement:** We welcome feedback and contributions.
- **Transparency:** Check our GitHub repository for ongoing discussions.
- **Iterative Development:** Goals may change based on community needs and technical feasibility.
*This roadmap is intended as a guide and may evolve based on community needs, technological advancements, and strategic priorities.*

100
docs/usage.md
View File

@@ -1,34 +1,96 @@
# Usage Guide
This guide explains how to use the Home Assistant MCP Server for smart home device management and integration with language learning systems.
This guide explains how to use the Home Assistant MCP Server for basic device management and integration.
## Basic Usage
## Basic Setup
1. **Starting the Server:**
- For development: run `npm run dev`.
- For production: run `npm run build` followed by `npm start`.
- Development mode: `bun run dev`
- Production mode: `bun run start`
2. **Accessing the Web Interface:**
- Open [http://localhost:3000](http://localhost:3000) in your browser.
2. **Accessing the Server:**
- Default URL: `http://localhost:3000`
- Ensure Home Assistant credentials are configured in `.env`
3. **Real-Time Updates:**
- Connect to the SSE endpoint at `/subscribe_events?token=YOUR_TOKEN&domain=light` to receive live updates.
## Device Control
## Advanced Features
### REST API Interactions
1. **API Interactions:**
- Use the REST API for operations such as device control, automation, and add-on management.
- See [API Documentation](api.md) for details.
Basic device control can be performed via the REST API:
2. **Tool Integrations:**
- Multiple tools are available (see [Tools Documentation](tools/tools.md)), for tasks like automation management and notifications.
```typescript
// Turn on a light
fetch('http://localhost:3000/api/control', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({
entity_id: 'light.living_room',
command: 'turn_on',
parameters: { brightness: 50 }
})
});
```
3. **Security Settings:**
- Configure token-based authentication and environment variables as per the [Configuration Guide](getting-started/configuration.md).
### Supported Commands
4. **Customization and Extensions:**
- Extend server functionality by developing new tools as outlined in the [Development Guide](development/development.md).
- `turn_on`
- `turn_off`
- `toggle`
- `set_brightness`
### Supported Entities
- Lights
- Switches
- Climate controls
- Media players
## Real-Time Updates
### WebSocket Connection
Subscribe to real-time device state changes:
```typescript
const ws = new WebSocket('ws://localhost:3000/events');
ws.onmessage = (event) => {
const deviceUpdate = JSON.parse(event.data);
console.log('Device state changed:', deviceUpdate);
};
```
## Authentication
All API requests require a valid JWT token in the Authorization header.
## Limitations
- Basic device control only
- Limited error handling
- Minimal third-party integrations
## Troubleshooting
If you experience issues, review the [Troubleshooting Guide](troubleshooting.md).
1. Verify Home Assistant connection
2. Check JWT token validity
3. Ensure correct entity IDs
4. Review server logs for detailed errors
## Configuration
Configure the server using environment variables in `.env`:
```
HA_URL=http://homeassistant:8123
HA_TOKEN=your_home_assistant_token
JWT_SECRET=your_jwt_secret
```
## Next Steps
- Explore the [API Documentation](api.md)
- Check [Troubleshooting Guide](troubleshooting.md)
- Review [Contributing Guidelines](contributing.md)