docs: Update environment configuration and README with comprehensive setup guide
- Enhance `.env.example` with more detailed and organized configuration options - Refactor README to provide clearer setup instructions and system architecture overview - Add new `scripts/setup-env.sh` for flexible environment configuration management - Update `docs/configuration.md` with detailed environment loading strategy and best practices - Improve documentation for speech features, client integration, and development workflows
This commit is contained in:
jango-blockchained
108
.env.example
108
.env.example
@@ -1,43 +1,15 @@
|
|||||||
# Home Assistant Configuration
|
|
||||||
# The URL of your Home Assistant instance
|
|
||||||
HASS_HOST=http://homeassistant.local:8123
|
|
||||||
|
|
||||||
# Long-lived access token from Home Assistant
|
|
||||||
# Generate from Profile -> Long-Lived Access Tokens
|
|
||||||
HASS_TOKEN=your_long_lived_token
|
|
||||||
|
|
||||||
# WebSocket URL for real-time updates
|
|
||||||
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
|
|
||||||
|
|
||||||
# Server Configuration
|
# Server Configuration
|
||||||
# Port for the MCP server (default: 3000)
|
|
||||||
PORT=3000
|
|
||||||
|
|
||||||
# Environment (development/production/test)
|
|
||||||
NODE_ENV=development
|
NODE_ENV=development
|
||||||
|
PORT=3000
|
||||||
# Debug mode (true/false)
|
|
||||||
DEBUG=false
|
DEBUG=false
|
||||||
|
|
||||||
# Logging level (debug/info/warn/error)
|
|
||||||
LOG_LEVEL=info
|
LOG_LEVEL=info
|
||||||
|
|
||||||
# AI Configuration
|
# Home Assistant Configuration
|
||||||
# Natural Language Processor type (claude/gpt4/custom)
|
HASS_HOST=http://homeassistant.local:8123
|
||||||
PROCESSOR_TYPE=claude
|
HASS_TOKEN=your_long_lived_token
|
||||||
|
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
|
||||||
# OpenAI API Key (required for GPT-4 analysis)
|
|
||||||
OPENAI_API_KEY=your_openai_api_key
|
|
||||||
|
|
||||||
# Rate Limiting
|
|
||||||
# Requests per minute per IP for regular endpoints
|
|
||||||
RATE_LIMIT_REGULAR=100
|
|
||||||
|
|
||||||
# Requests per minute per IP for WebSocket connections
|
|
||||||
RATE_LIMIT_WEBSOCKET=1000
|
|
||||||
|
|
||||||
# Security Configuration
|
# Security Configuration
|
||||||
# JWT Configuration
|
|
||||||
JWT_SECRET=your_jwt_secret_key_min_32_chars
|
JWT_SECRET=your_jwt_secret_key_min_32_chars
|
||||||
JWT_EXPIRY=86400000
|
JWT_EXPIRY=86400000
|
||||||
JWT_MAX_AGE=2592000000
|
JWT_MAX_AGE=2592000000
|
||||||
@@ -46,11 +18,8 @@ JWT_ALGORITHM=HS256
|
|||||||
# Rate Limiting
|
# Rate Limiting
|
||||||
RATE_LIMIT_WINDOW=900000
|
RATE_LIMIT_WINDOW=900000
|
||||||
RATE_LIMIT_MAX_REQUESTS=100
|
RATE_LIMIT_MAX_REQUESTS=100
|
||||||
|
RATE_LIMIT_REGULAR=100
|
||||||
# Token Security
|
RATE_LIMIT_WEBSOCKET=1000
|
||||||
TOKEN_MIN_LENGTH=32
|
|
||||||
MAX_FAILED_ATTEMPTS=5
|
|
||||||
LOCKOUT_DURATION=900000
|
|
||||||
|
|
||||||
# CORS Configuration
|
# CORS Configuration
|
||||||
CORS_ORIGINS=http://localhost:3000,http://localhost:8123
|
CORS_ORIGINS=http://localhost:3000,http://localhost:8123
|
||||||
@@ -60,17 +29,6 @@ CORS_EXPOSED_HEADERS=
|
|||||||
CORS_CREDENTIALS=true
|
CORS_CREDENTIALS=true
|
||||||
CORS_MAX_AGE=86400
|
CORS_MAX_AGE=86400
|
||||||
|
|
||||||
# Content Security Policy
|
|
||||||
CSP_ENABLED=true
|
|
||||||
CSP_REPORT_ONLY=false
|
|
||||||
CSP_REPORT_URI=
|
|
||||||
|
|
||||||
# SSL/TLS Configuration
|
|
||||||
REQUIRE_HTTPS=true
|
|
||||||
HSTS_MAX_AGE=31536000
|
|
||||||
HSTS_INCLUDE_SUBDOMAINS=true
|
|
||||||
HSTS_PRELOAD=true
|
|
||||||
|
|
||||||
# Cookie Security
|
# Cookie Security
|
||||||
COOKIE_SECRET=your_cookie_secret_key_min_32_chars
|
COOKIE_SECRET=your_cookie_secret_key_min_32_chars
|
||||||
COOKIE_SECURE=true
|
COOKIE_SECURE=true
|
||||||
@@ -81,27 +39,12 @@ COOKIE_SAME_SITE=Strict
|
|||||||
MAX_REQUEST_SIZE=1048576
|
MAX_REQUEST_SIZE=1048576
|
||||||
MAX_REQUEST_FIELDS=1000
|
MAX_REQUEST_FIELDS=1000
|
||||||
|
|
||||||
# SSE Configuration
|
# AI Configuration
|
||||||
SSE_MAX_CLIENTS=1000
|
PROCESSOR_TYPE=claude
|
||||||
SSE_PING_INTERVAL=30000
|
OPENAI_API_KEY=your_openai_api_key
|
||||||
|
OPENAI_MODEL=gpt-3.5-turbo
|
||||||
# Logging Configuration
|
MAX_RETRIES=3
|
||||||
LOG_LEVEL=info
|
ANALYSIS_TIMEOUT=30000
|
||||||
LOG_DIR=logs
|
|
||||||
LOG_MAX_SIZE=20m
|
|
||||||
LOG_MAX_DAYS=14d
|
|
||||||
LOG_COMPRESS=true
|
|
||||||
LOG_REQUESTS=true
|
|
||||||
|
|
||||||
# Version
|
|
||||||
VERSION=0.1.0
|
|
||||||
|
|
||||||
# Test Configuration
|
|
||||||
# Only needed if running tests
|
|
||||||
TEST_HASS_HOST=http://localhost:8123
|
|
||||||
TEST_HASS_TOKEN=test_token
|
|
||||||
TEST_HASS_SOCKET_URL=ws://localhost:8123/api/websocket
|
|
||||||
TEST_PORT=3001
|
|
||||||
|
|
||||||
# Speech Features Configuration
|
# Speech Features Configuration
|
||||||
ENABLE_SPEECH_FEATURES=false
|
ENABLE_SPEECH_FEATURES=false
|
||||||
@@ -110,5 +53,30 @@ ENABLE_SPEECH_TO_TEXT=false
|
|||||||
WHISPER_MODEL_PATH=/models
|
WHISPER_MODEL_PATH=/models
|
||||||
WHISPER_MODEL_TYPE=tiny
|
WHISPER_MODEL_TYPE=tiny
|
||||||
|
|
||||||
|
# Audio Configuration
|
||||||
|
NOISE_THRESHOLD=0.05
|
||||||
|
MIN_SPEECH_DURATION=1.0
|
||||||
|
SILENCE_DURATION=0.5
|
||||||
|
SAMPLE_RATE=16000
|
||||||
|
CHANNELS=1
|
||||||
|
CHUNK_SIZE=1024
|
||||||
|
PULSE_SERVER=unix:/run/user/1000/pulse/native
|
||||||
|
|
||||||
|
# SSE Configuration
|
||||||
|
SSE_MAX_CLIENTS=50
|
||||||
|
SSE_RECONNECT_TIMEOUT=5000
|
||||||
|
|
||||||
|
# Development Flags
|
||||||
|
HOT_RELOAD=true
|
||||||
|
|
||||||
|
# Test Configuration (only needed for running tests)
|
||||||
|
TEST_HASS_HOST=http://localhost:8123
|
||||||
|
TEST_HASS_TOKEN=test_token
|
||||||
|
TEST_HASS_SOCKET_URL=ws://localhost:8123/api/websocket
|
||||||
|
TEST_PORT=3001
|
||||||
|
|
||||||
|
# Version
|
||||||
|
VERSION=0.1.0
|
||||||
|
|
||||||
# Advanced (Docker)
|
# Advanced (Docker)
|
||||||
COMPOSE_PROJECT_NAME=mcp
|
COMPOSE_PROJECT_NAME=mcp
|
||||||
324
README.md
324
README.md
@@ -1,10 +1,42 @@
|
|||||||
# MCP Server for Home Assistant 🏠🤖
|
# MCP Server for Home Assistant 🏠🤖
|
||||||
|
|
||||||
[](LICENSE) [](https://bun.sh) [](https://www.typescriptlang.org) [](https://smithery.ai/server/@jango-blockchained/advanced-homeassistant-mcp)
|
[](LICENSE) [](https://bun.sh) [](https://www.typescriptlang.org)
|
||||||
|
|
||||||
## Overview 🌐
|
## Overview 🌐
|
||||||
|
|
||||||
MCP (Model Context Protocol) Server is a lightweight integration tool for Home Assistant, providing a flexible interface for device management and automation.
|
MCP (Model Context Protocol) Server is my lightweight integration tool for Home Assistant, providing a flexible interface for device management and automation. It's designed to be fast, secure, and easy to use. Built with Bun for maximum performance.
|
||||||
|
|
||||||
|
## Why Bun? 🚀
|
||||||
|
|
||||||
|
I chose Bun as the runtime for several key benefits:
|
||||||
|
|
||||||
|
- ⚡ **Blazing Fast Performance**
|
||||||
|
- Up to 4x faster than Node.js
|
||||||
|
- Built-in TypeScript support
|
||||||
|
- Optimized file system operations
|
||||||
|
|
||||||
|
- 🎯 **All-in-One Solution**
|
||||||
|
- Package manager (faster than npm/yarn)
|
||||||
|
- Bundler (no webpack needed)
|
||||||
|
- Test runner (built-in testing)
|
||||||
|
- TypeScript transpiler
|
||||||
|
|
||||||
|
- 🔋 **Built-in Features**
|
||||||
|
- SQLite3 driver
|
||||||
|
- .env file loading
|
||||||
|
- WebSocket client/server
|
||||||
|
- File watcher
|
||||||
|
- Test runner
|
||||||
|
|
||||||
|
- 💾 **Resource Efficient**
|
||||||
|
- Lower memory usage
|
||||||
|
- Faster cold starts
|
||||||
|
- Better CPU utilization
|
||||||
|
|
||||||
|
- 🔄 **Node.js Compatibility**
|
||||||
|
- Runs most npm packages
|
||||||
|
- Compatible with Express/Fastify
|
||||||
|
- Native Node.js APIs
|
||||||
|
|
||||||
## Core Features ✨
|
## Core Features ✨
|
||||||
|
|
||||||
@@ -12,95 +44,131 @@ MCP (Model Context Protocol) Server is a lightweight integration tool for Home A
|
|||||||
- 📡 WebSocket/Server-Sent Events (SSE) for state updates
|
- 📡 WebSocket/Server-Sent Events (SSE) for state updates
|
||||||
- 🤖 Simple automation rule management
|
- 🤖 Simple automation rule management
|
||||||
- 🔐 JWT-based authentication
|
- 🔐 JWT-based authentication
|
||||||
- 🎤 Real-time device control and monitoring
|
|
||||||
- 🎤 Server-Sent Events (SSE) for live updates
|
|
||||||
- 🎤 Comprehensive logging
|
|
||||||
- 🎤 Optional speech features:
|
- 🎤 Optional speech features:
|
||||||
- 🎤 Wake word detection ("hey jarvis", "ok google", "alexa")
|
- 🗣️ Wake word detection ("hey jarvis", "ok google", "alexa")
|
||||||
- 🎤 Speech-to-text using fast-whisper
|
- 🎯 Speech-to-text using fast-whisper
|
||||||
- 🎤 Multiple language support
|
- 🌍 Multiple language support
|
||||||
- 🎤 GPU acceleration support
|
- 🚀 GPU acceleration support
|
||||||
|
|
||||||
|
## System Architecture 📊
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
subgraph Client["Client Applications"]
|
||||||
|
direction TB
|
||||||
|
Web["Web Interface"]
|
||||||
|
Mobile["Mobile Apps"]
|
||||||
|
Voice["Voice Control"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph MCP["MCP Server"]
|
||||||
|
direction TB
|
||||||
|
API["REST API"]
|
||||||
|
WS["WebSocket/SSE"]
|
||||||
|
Auth["Authentication"]
|
||||||
|
|
||||||
|
subgraph Speech["Speech Processing (Optional)"]
|
||||||
|
direction TB
|
||||||
|
Wake["Wake Word Detection"]
|
||||||
|
STT["Speech-to-Text"]
|
||||||
|
|
||||||
|
subgraph STT_Options["STT Options"]
|
||||||
|
direction LR
|
||||||
|
Whisper["Whisper"]
|
||||||
|
FastWhisper["Fast Whisper"]
|
||||||
|
end
|
||||||
|
|
||||||
|
Wake --> STT
|
||||||
|
STT --> STT_Options
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph HA["Home Assistant"]
|
||||||
|
direction TB
|
||||||
|
HASS_API["HASS API"]
|
||||||
|
HASS_WS["HASS WebSocket"]
|
||||||
|
Devices["Smart Devices"]
|
||||||
|
end
|
||||||
|
|
||||||
|
Client --> MCP
|
||||||
|
MCP --> HA
|
||||||
|
HA --> Devices
|
||||||
|
|
||||||
|
style Speech fill:#f9f,stroke:#333,stroke-width:2px
|
||||||
|
style STT_Options fill:#bbf,stroke:#333,stroke-width:1px
|
||||||
|
```
|
||||||
|
|
||||||
## Prerequisites 📋
|
## Prerequisites 📋
|
||||||
|
|
||||||
- 🚀 Bun runtime (v1.0.26+)
|
- 🚀 [Bun runtime](https://bun.sh) (v1.0.26+)
|
||||||
- 🏡 Home Assistant instance
|
- 🏡 [Home Assistant](https://www.home-assistant.io/) instance
|
||||||
- 🐳 Docker (optional, recommended for deployment and speech features)
|
- 🐳 Docker (optional, recommended for deployment)
|
||||||
- 🖥️ Node.js 18+ (optional, for speech features)
|
- 🖥️ Node.js 18+ (optional, for speech features)
|
||||||
- 🖥️ NVIDIA GPU with CUDA support (optional, for faster speech processing)
|
- 🎮 NVIDIA GPU with CUDA support (optional, for faster speech processing)
|
||||||
|
|
||||||
## Installation 🛠️
|
## Quick Start 🚀
|
||||||
|
|
||||||
### Docker Deployment (Recommended)
|
|
||||||
|
|
||||||
|
1. Clone my repository:
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
|
||||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||||
cd homeassistant-mcp
|
cd homeassistant-mcp
|
||||||
|
|
||||||
# Copy environment template:
|
|
||||||
cp .env.example .env
|
|
||||||
# Edit .env with your Home Assistant credentials and speech features settings
|
|
||||||
|
|
||||||
# Build and start containers
|
|
||||||
docker compose up -d --build
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Bare Metal Installation
|
2. Set up the environment:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install Bun
|
# Make my setup script executable
|
||||||
curl -fsSL https://bun.sh/install | bash
|
chmod +x scripts/setup-env.sh
|
||||||
|
|
||||||
# Clone the repository
|
# Run setup (defaults to development)
|
||||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
./scripts/setup-env.sh
|
||||||
cd homeassistant-mcp
|
|
||||||
|
|
||||||
# Install dependencies
|
# Or specify an environment:
|
||||||
bun install
|
NODE_ENV=production ./scripts/setup-env.sh
|
||||||
|
|
||||||
# Start the server
|
# Force override existing files:
|
||||||
bun run dev
|
./scripts/setup-env.sh --force
|
||||||
```
|
```
|
||||||
|
|
||||||
## Basic Usage 🖥️
|
3. Configure your settings:
|
||||||
|
- Edit `.env` file with your Home Assistant details
|
||||||
|
- Required: Add your `HASS_TOKEN` (long-lived access token)
|
||||||
|
|
||||||
### Device Control Example
|
4. Launch with Docker:
|
||||||
|
```bash
|
||||||
```typescript
|
docker compose up -d
|
||||||
// Turn on a light
|
|
||||||
const response = await fetch('http://localhost:3000/api/devices/light.living_room', {
|
|
||||||
method: 'POST',
|
|
||||||
headers: {
|
|
||||||
'Content-Type': 'application/json',
|
|
||||||
'Authorization': `Bearer ${token}`
|
|
||||||
},
|
|
||||||
body: JSON.stringify({ state: 'on' })
|
|
||||||
});
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### WebSocket State Updates
|
## Environment Configuration 🔧
|
||||||
|
|
||||||
```typescript
|
I've implemented a hierarchical configuration system:
|
||||||
const ws = new WebSocket('ws://localhost:3000/devices');
|
|
||||||
ws.onmessage = (event) => {
|
|
||||||
const deviceState = JSON.parse(event.data);
|
|
||||||
console.log('Device state updated:', deviceState);
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
## Speech Features (Optional)
|
### File Structure 📁
|
||||||
|
1. `.env.example` - My template with all options
|
||||||
|
2. `.env` - Your configuration (copy from .env.example)
|
||||||
|
3. Environment overrides:
|
||||||
|
- `.env.dev` - Development settings
|
||||||
|
- `.env.prod` - Production settings
|
||||||
|
- `.env.test` - Test settings
|
||||||
|
|
||||||
The MCP Server includes optional speech processing capabilities:
|
### Loading Priority ⚡
|
||||||
|
Files load in this order:
|
||||||
|
1. `.env` (base config)
|
||||||
|
2. Environment-specific file:
|
||||||
|
- `NODE_ENV=development` → `.env.dev`
|
||||||
|
- `NODE_ENV=production` → `.env.prod`
|
||||||
|
- `NODE_ENV=test` → `.env.test`
|
||||||
|
|
||||||
|
Later files override earlier ones.
|
||||||
|
|
||||||
|
## Speech Features Setup 🎤
|
||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
1. Docker installed and running
|
1. 🐳 Docker installed and running
|
||||||
2. NVIDIA GPU with CUDA support (optional)
|
2. 🎮 NVIDIA GPU with CUDA (optional)
|
||||||
3. At least 4GB RAM (8GB+ recommended for larger models)
|
3. 💾 4GB+ RAM (8GB+ recommended)
|
||||||
|
|
||||||
### Setup
|
### Configuration
|
||||||
|
1. Enable speech in `.env`:
|
||||||
1. Enable speech features in your .env:
|
|
||||||
```bash
|
```bash
|
||||||
ENABLE_SPEECH_FEATURES=true
|
ENABLE_SPEECH_FEATURES=true
|
||||||
ENABLE_WAKE_WORD=true
|
ENABLE_WAKE_WORD=true
|
||||||
@@ -109,67 +177,65 @@ WHISPER_MODEL_PATH=/models
|
|||||||
WHISPER_MODEL_TYPE=base
|
WHISPER_MODEL_TYPE=base
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Start the speech services:
|
2. Choose your STT engine:
|
||||||
```bash
|
```bash
|
||||||
docker-compose up -d
|
# For standard Whisper
|
||||||
|
STT_ENGINE=whisper
|
||||||
|
|
||||||
|
# For Fast Whisper (GPU recommended)
|
||||||
|
STT_ENGINE=fast-whisper
|
||||||
|
CUDA_VISIBLE_DEVICES=0 # Set GPU device
|
||||||
```
|
```
|
||||||
|
|
||||||
### Available Models
|
### Available Models 🤖
|
||||||
|
Choose based on your needs:
|
||||||
Choose a model based on your needs:
|
|
||||||
- `tiny.en`: Fastest, basic accuracy
|
- `tiny.en`: Fastest, basic accuracy
|
||||||
- `base.en`: Good balance (recommended)
|
- `base.en`: Good balance (recommended)
|
||||||
- `small.en`: Better accuracy, slower
|
- `small.en`: Better accuracy, slower
|
||||||
- `medium.en`: High accuracy, resource intensive
|
- `medium.en`: High accuracy, resource intensive
|
||||||
- `large-v2`: Best accuracy, very resource intensive
|
- `large-v2`: Best accuracy, very resource intensive
|
||||||
|
|
||||||
### Usage
|
## Development 💻
|
||||||
|
|
||||||
1. Wake word detection listens for:
|
```bash
|
||||||
- "hey jarvis"
|
# Install dependencies
|
||||||
- "ok google"
|
bun install
|
||||||
- "alexa"
|
|
||||||
|
|
||||||
2. After wake word detection:
|
# Run in development mode
|
||||||
- Audio is automatically captured
|
bun run dev
|
||||||
- Speech is transcribed
|
|
||||||
- Commands are processed
|
|
||||||
|
|
||||||
3. Manual transcription is also available:
|
# Run tests
|
||||||
```typescript
|
bun test
|
||||||
const speech = speechService.getSpeechToText();
|
|
||||||
const text = await speech.transcribe(audioBuffer);
|
# Run with hot reload
|
||||||
|
bun --hot run dev
|
||||||
|
|
||||||
|
# Build for production
|
||||||
|
bun build ./src/index.ts --target=bun
|
||||||
|
|
||||||
|
# Run production build
|
||||||
|
bun run start
|
||||||
```
|
```
|
||||||
|
|
||||||
## Configuration
|
### Performance Comparison 📊
|
||||||
|
|
||||||
See [Configuration Guide](docs/configuration.md) for detailed settings.
|
| Operation | Bun | Node.js |
|
||||||
|
|-----------|-----|---------|
|
||||||
|
| Install Dependencies | ~2s | ~15s |
|
||||||
|
| Cold Start | 300ms | 1000ms |
|
||||||
|
| Build Time | 150ms | 4000ms |
|
||||||
|
| Memory Usage | ~150MB | ~400MB |
|
||||||
|
|
||||||
## API Documentation
|
## Documentation 📚
|
||||||
|
|
||||||
See [API Documentation](docs/api/index.md) for available endpoints.
|
- [Configuration Guide](docs/configuration.md)
|
||||||
|
- [API Documentation](docs/api.md)
|
||||||
|
- [Troubleshooting](docs/troubleshooting.md)
|
||||||
|
|
||||||
## Development
|
## Client Integration 🔗
|
||||||
|
|
||||||
See [Development Guide](docs/development/index.md) for contribution guidelines.
|
|
||||||
|
|
||||||
## License 📄
|
|
||||||
|
|
||||||
MIT License. See [LICENSE](LICENSE) for details.
|
|
||||||
|
|
||||||
## Support 🆘
|
|
||||||
|
|
||||||
- 🐞 [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues)
|
|
||||||
- 📖 Documentation: [Project Docs](https://jango-blockchained.github.io/homeassistant-mcp/)
|
|
||||||
|
|
||||||
## MCP Client Integration 🔗
|
|
||||||
|
|
||||||
This MCP server can be integrated with various clients that support the Model Context Protocol. Below are instructions for different client integrations:
|
|
||||||
|
|
||||||
### Cursor Integration 🖱️
|
### Cursor Integration 🖱️
|
||||||
|
Add to `.cursor/config/config.json`:
|
||||||
The server can be integrated with Cursor by adding the configuration to `.cursor/config/config.json`:
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
@@ -185,10 +251,8 @@ The server can be integrated with Cursor by adding the configuration to `.cursor
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Claude Desktop Integration 💬
|
### Claude Desktop 💬
|
||||||
|
Add to your Claude config:
|
||||||
For Claude Desktop, add the following to your Claude configuration file:
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
@@ -203,37 +267,15 @@ For Claude Desktop, add the following to your Claude configuration file:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Cline Integration 📟
|
### Command Line 💻
|
||||||
|
Windows users can use the provided script:
|
||||||
For Cline-based clients, add the following configuration:
|
1. Go to `scripts` directory
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mcpServers": {
|
|
||||||
"homeassistant-mcp": {
|
|
||||||
"command": "bun",
|
|
||||||
"args": [
|
|
||||||
"run",
|
|
||||||
"start",
|
|
||||||
"--enable-cline",
|
|
||||||
"--config",
|
|
||||||
"${configDir}/.env"
|
|
||||||
],
|
|
||||||
"env": {
|
|
||||||
"NODE_ENV": "production",
|
|
||||||
"CLINE_MODE": "true"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Command Line Usage 💻
|
|
||||||
|
|
||||||
#### Windows
|
|
||||||
A CMD script is provided in the `scripts` directory. To use it:
|
|
||||||
|
|
||||||
1. Navigate to the `scripts` directory
|
|
||||||
2. Run `start_mcp.cmd`
|
2. Run `start_mcp.cmd`
|
||||||
|
|
||||||
The script will start the MCP server with default configuration.
|
## License 📄
|
||||||
|
|
||||||
|
MIT License. See [LICENSE](LICENSE) for details.
|
||||||
|
|
||||||
|
## Author 👨💻
|
||||||
|
|
||||||
|
Created by [jango-blockchained](https://github.com/jango-blockchained)
|
||||||
|
|||||||
@@ -210,101 +210,220 @@ See the [Troubleshooting Guide](troubleshooting.md) for solutions.
|
|||||||
|
|
||||||
# Configuration Guide
|
# Configuration Guide
|
||||||
|
|
||||||
This document describes all available configuration options for the Home Assistant MCP Server.
|
This document describes the environment configuration system for the Home Assistant MCP Server.
|
||||||
|
|
||||||
## Environment Variables
|
## Environment Setup
|
||||||
|
|
||||||
|
### Using the Setup Script
|
||||||
|
|
||||||
|
The MCP Server provides a setup script to help manage your environment configuration:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Make the script executable
|
||||||
|
chmod +x scripts/setup-env.sh
|
||||||
|
|
||||||
|
# Basic usage (uses NODE_ENV or defaults to development)
|
||||||
|
./scripts/setup-env.sh
|
||||||
|
|
||||||
|
# Specify an environment
|
||||||
|
NODE_ENV=production ./scripts/setup-env.sh
|
||||||
|
|
||||||
|
# Force override existing files
|
||||||
|
./scripts/setup-env.sh --force
|
||||||
|
```
|
||||||
|
|
||||||
|
The setup script will:
|
||||||
|
1. Check for `.env.example` and create `.env` if it doesn't exist
|
||||||
|
2. Detect the environment (development/production/test)
|
||||||
|
3. Optionally override `.env` with environment-specific settings
|
||||||
|
4. Maintain your existing configuration unless forced to override
|
||||||
|
|
||||||
|
### Manual Setup
|
||||||
|
|
||||||
|
If you prefer to set up manually:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Copy the example configuration
|
||||||
|
cp .env.example .env
|
||||||
|
|
||||||
|
# Then copy the appropriate environment override
|
||||||
|
cp .env.dev .env # For development
|
||||||
|
cp .env.prod .env # For production
|
||||||
|
cp .env.test .env # For testing
|
||||||
|
```
|
||||||
|
|
||||||
|
## Environment File Hierarchy
|
||||||
|
|
||||||
|
### Base Configuration Files
|
||||||
|
- `.env.example` - Template with all available options and documentation
|
||||||
|
- `.env` - Your main configuration file (copied from .env.example)
|
||||||
|
|
||||||
|
### Environment-Specific Files
|
||||||
|
- `.env.dev` - Development environment settings
|
||||||
|
- `.env.prod` - Production environment settings
|
||||||
|
- `.env.test` - Test environment settings
|
||||||
|
|
||||||
|
### Loading Order and Priority
|
||||||
|
|
||||||
|
Files are loaded in the following sequence, with later files overriding earlier ones:
|
||||||
|
|
||||||
|
1. `.env` (base configuration)
|
||||||
|
2. Environment-specific file based on NODE_ENV:
|
||||||
|
- `NODE_ENV=development` → `.env.dev`
|
||||||
|
- `NODE_ENV=production` → `.env.prod`
|
||||||
|
- `NODE_ENV=test` → `.env.test`
|
||||||
|
|
||||||
|
### Docker Environment Handling
|
||||||
|
|
||||||
|
When using Docker, the environment is loaded as follows:
|
||||||
|
|
||||||
|
1. `.env` file (base configuration)
|
||||||
|
2. `.env.${NODE_ENV}` file (environment-specific overrides)
|
||||||
|
3. Environment variables from docker-compose.yml
|
||||||
|
4. Command-line environment variables
|
||||||
|
|
||||||
|
Example docker-compose.yml configuration:
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
homeassistant-mcp:
|
||||||
|
env_file:
|
||||||
|
- .env
|
||||||
|
- .env.${NODE_ENV:-development}
|
||||||
|
environment:
|
||||||
|
- NODE_ENV=${NODE_ENV:-development}
|
||||||
|
- PORT=4000
|
||||||
|
- HASS_HOST
|
||||||
|
- HASS_TOKEN
|
||||||
|
- LOG_LEVEL=${LOG_LEVEL:-info}
|
||||||
|
```
|
||||||
|
|
||||||
|
Override examples:
|
||||||
|
```bash
|
||||||
|
# Override NODE_ENV
|
||||||
|
NODE_ENV=production docker compose up -d
|
||||||
|
|
||||||
|
# Override multiple variables
|
||||||
|
NODE_ENV=production LOG_LEVEL=debug docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration Options
|
||||||
|
|
||||||
### Required Settings
|
### Required Settings
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Server Configuration
|
# Server Configuration
|
||||||
PORT=3000 # Server port
|
PORT=4000 # Server port number
|
||||||
HOST=localhost # Server host
|
NODE_ENV=development # Environment (development/production/test)
|
||||||
|
|
||||||
# Home Assistant
|
# Home Assistant
|
||||||
HASS_URL=http://localhost:8123 # Home Assistant URL
|
HASS_HOST=http://homeassistant.local:8123 # Home Assistant URL
|
||||||
HASS_TOKEN=your_token # Long-lived access token
|
HASS_TOKEN=your_token_here # Long-lived access token
|
||||||
|
|
||||||
# Security
|
# Security
|
||||||
JWT_SECRET=your_secret # JWT signing secret
|
JWT_SECRET=your_secret_key # JWT signing secret
|
||||||
```
|
```
|
||||||
|
|
||||||
### Optional Settings
|
### Optional Settings
|
||||||
|
|
||||||
|
#### Security
|
||||||
```bash
|
```bash
|
||||||
# Rate Limiting
|
# Rate Limiting
|
||||||
RATE_LIMIT_WINDOW=60000 # Time window in ms (default: 60000)
|
RATE_LIMIT_WINDOW=900000 # Time window in ms (15 minutes)
|
||||||
RATE_LIMIT_MAX=100 # Max requests per window (default: 100)
|
RATE_LIMIT_MAX_REQUESTS=100 # Max requests per window
|
||||||
|
RATE_LIMIT_REGULAR=100 # Regular endpoint rate limit
|
||||||
|
RATE_LIMIT_WEBSOCKET=1000 # WebSocket connection rate limit
|
||||||
|
|
||||||
# Logging
|
# CORS Configuration
|
||||||
LOG_LEVEL=info # debug, info, warn, error (default: info)
|
CORS_ORIGINS=http://localhost:3000,http://localhost:8123
|
||||||
LOG_DIR=logs # Log directory (default: logs)
|
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
|
||||||
LOG_MAX_SIZE=10m # Max log file size (default: 10m)
|
CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-Requested-With
|
||||||
LOG_MAX_FILES=5 # Max number of log files (default: 5)
|
CORS_EXPOSED_HEADERS=
|
||||||
|
CORS_CREDENTIALS=true
|
||||||
|
CORS_MAX_AGE=86400
|
||||||
|
|
||||||
# WebSocket/SSE
|
# Cookie Security
|
||||||
WS_HEARTBEAT=30000 # WebSocket heartbeat interval in ms (default: 30000)
|
COOKIE_SECRET=your_cookie_secret_key_min_32_chars
|
||||||
SSE_RETRY=3000 # SSE retry interval in ms (default: 3000)
|
COOKIE_SECURE=true
|
||||||
|
COOKIE_HTTP_ONLY=true
|
||||||
# Speech Features
|
COOKIE_SAME_SITE=Strict
|
||||||
ENABLE_SPEECH_FEATURES=false # Enable speech processing (default: false)
|
|
||||||
ENABLE_WAKE_WORD=false # Enable wake word detection (default: false)
|
|
||||||
ENABLE_SPEECH_TO_TEXT=false # Enable speech-to-text (default: false)
|
|
||||||
|
|
||||||
# Speech Model Configuration
|
|
||||||
WHISPER_MODEL_PATH=/models # Path to whisper models (default: /models)
|
|
||||||
WHISPER_MODEL_TYPE=base # Model type: tiny|base|small|medium|large-v2 (default: base)
|
|
||||||
WHISPER_LANGUAGE=en # Primary language (default: en)
|
|
||||||
WHISPER_TASK=transcribe # Task type: transcribe|translate (default: transcribe)
|
|
||||||
WHISPER_DEVICE=cuda # Processing device: cpu|cuda (default: cuda if available, else cpu)
|
|
||||||
|
|
||||||
# Wake Word Configuration
|
|
||||||
WAKE_WORDS=hey jarvis,ok google,alexa # Comma-separated wake words (default: hey jarvis)
|
|
||||||
WAKE_WORD_SENSITIVITY=0.5 # Detection sensitivity 0-1 (default: 0.5)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Speech Features
|
#### Logging
|
||||||
|
```bash
|
||||||
|
# Logging Configuration
|
||||||
|
LOG_LEVEL=info # debug, info, warn, error
|
||||||
|
LOG_DIR=logs # Log directory
|
||||||
|
LOG_MAX_SIZE=20m # Max log file size
|
||||||
|
LOG_MAX_DAYS=14d # Log retention period
|
||||||
|
LOG_COMPRESS=true # Enable log compression
|
||||||
|
LOG_REQUESTS=true # Log HTTP requests
|
||||||
|
```
|
||||||
|
|
||||||
### Model Selection
|
#### Speech Features
|
||||||
|
```bash
|
||||||
|
# Speech Processing
|
||||||
|
ENABLE_SPEECH_FEATURES=false # Master switch for speech features
|
||||||
|
ENABLE_WAKE_WORD=false # Enable wake word detection
|
||||||
|
ENABLE_SPEECH_TO_TEXT=false # Enable speech-to-text
|
||||||
|
WHISPER_MODEL_PATH=/models # Path to Whisper models
|
||||||
|
WHISPER_MODEL_TYPE=base # Whisper model type
|
||||||
|
|
||||||
Choose a model based on your needs:
|
# Audio Configuration
|
||||||
|
NOISE_THRESHOLD=0.05
|
||||||
|
MIN_SPEECH_DURATION=1.0
|
||||||
|
SILENCE_DURATION=0.5
|
||||||
|
SAMPLE_RATE=16000
|
||||||
|
CHANNELS=1
|
||||||
|
CHUNK_SIZE=1024
|
||||||
|
PULSE_SERVER=unix:/run/user/1000/pulse/native
|
||||||
|
```
|
||||||
|
|
||||||
| Model | Size | Memory Required | Speed | Accuracy |
|
## Best Practices
|
||||||
|------------|-------|-----------------|-------|----------|
|
|
||||||
| tiny.en | 75MB | 1GB | Fast | Basic |
|
|
||||||
| base.en | 150MB | 2GB | Good | Good |
|
|
||||||
| small.en | 500MB | 4GB | Med | Better |
|
|
||||||
| medium.en | 1.5GB | 8GB | Slow | High |
|
|
||||||
| large-v2 | 3GB | 16GB | Slow | Best |
|
|
||||||
|
|
||||||
### GPU Acceleration
|
1. **Version Control**
|
||||||
|
- Never commit `.env` files to version control
|
||||||
|
- Always commit `.env.example` with documentation
|
||||||
|
- Consider committing `.env.dev` and `.env.test` for team development
|
||||||
|
|
||||||
When `WHISPER_DEVICE=cuda`:
|
2. **Security**
|
||||||
- NVIDIA GPU with CUDA support required
|
- Use strong, unique values for secrets
|
||||||
- Significantly faster processing
|
- Enable HTTPS in production
|
||||||
- Higher memory requirements
|
- Keep tokens and secrets in `.env` only
|
||||||
|
|
||||||
### Wake Word Detection
|
3. **Development**
|
||||||
|
- Use `.env.dev` for shared development settings
|
||||||
|
- Keep `.env` for personal overrides
|
||||||
|
- Enable debug logging in development
|
||||||
|
|
||||||
- Multiple wake words supported via comma-separated list
|
4. **Production**
|
||||||
- Adjustable sensitivity (0-1):
|
- Use `.env.prod` for production defaults
|
||||||
- Lower values: Fewer false positives, may miss some triggers
|
- Set appropriate rate limits
|
||||||
- Higher values: More responsive, may have false triggers
|
- Configure proper logging
|
||||||
- Default (0.5): Balanced detection
|
- Enable all security features
|
||||||
|
|
||||||
### Best Practices
|
5. **Testing**
|
||||||
|
- Use `.env.test` for test configuration
|
||||||
|
- Use mock tokens and endpoints
|
||||||
|
- Enable detailed logging for debugging
|
||||||
|
|
||||||
1. Model Selection:
|
## Troubleshooting
|
||||||
- Start with `base.en` model
|
|
||||||
- Upgrade if better accuracy needed
|
|
||||||
- Downgrade if performance issues
|
|
||||||
|
|
||||||
2. Resource Management:
|
### Common Issues
|
||||||
- Monitor memory usage
|
|
||||||
- Use GPU acceleration when available
|
|
||||||
- Consider model size vs available resources
|
|
||||||
|
|
||||||
3. Wake Word Configuration:
|
1. **Missing Required Variables**
|
||||||
- Use distinct wake words
|
- Error: "Missing required environment variable: HASS_TOKEN"
|
||||||
- Adjust sensitivity based on environment
|
- Solution: Ensure HASS_TOKEN is set in your .env file
|
||||||
- Limit number of wake words for better performance
|
|
||||||
|
2. **Permission Issues**
|
||||||
|
- Error: "EACCES: permission denied, access '/app/logs'"
|
||||||
|
- Solution: Ensure proper permissions on the logs directory
|
||||||
|
|
||||||
|
3. **Invalid Configuration**
|
||||||
|
- Error: "Invalid configuration value for PORT"
|
||||||
|
- Solution: Check the value format in your .env file
|
||||||
|
|
||||||
|
4. **Environment Override Issues**
|
||||||
|
- Problem: Environment-specific settings not applying
|
||||||
|
- Solution: Check NODE_ENV value and file naming
|
||||||
|
|
||||||
|
See [Troubleshooting Guide](troubleshooting.md) for more solutions.
|
||||||
97
scripts/setup-env.sh
Executable file
97
scripts/setup-env.sh
Executable file
@@ -0,0 +1,97 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
# Colors for output
|
||||||
|
RED='\033[0;31m'
|
||||||
|
GREEN='\033[0;32m'
|
||||||
|
YELLOW='\033[1;33m'
|
||||||
|
NC='\033[0m' # No Color
|
||||||
|
|
||||||
|
# Function to print colored messages
|
||||||
|
print_message() {
|
||||||
|
local color=$1
|
||||||
|
local message=$2
|
||||||
|
echo -e "${color}${message}${NC}"
|
||||||
|
}
|
||||||
|
|
||||||
|
# Function to check if a file exists
|
||||||
|
check_file() {
|
||||||
|
if [ -f "$1" ]; then
|
||||||
|
return 0
|
||||||
|
else
|
||||||
|
return 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# Function to copy environment file
|
||||||
|
copy_env_file() {
|
||||||
|
local source=$1
|
||||||
|
local target=$2
|
||||||
|
if [ -f "$target" ]; then
|
||||||
|
print_message "$YELLOW" "Warning: $target already exists. Skipping..."
|
||||||
|
else
|
||||||
|
cp "$source" "$target"
|
||||||
|
if [ $? -eq 0 ]; then
|
||||||
|
print_message "$GREEN" "Created $target successfully"
|
||||||
|
else
|
||||||
|
print_message "$RED" "Error: Failed to create $target"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# Main script
|
||||||
|
print_message "$GREEN" "Setting up environment files..."
|
||||||
|
|
||||||
|
# Check if .env.example exists
|
||||||
|
if ! check_file ".env.example"; then
|
||||||
|
print_message "$RED" "Error: .env.example not found!"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Setup base environment file
|
||||||
|
if [ "$1" = "--force" ]; then
|
||||||
|
cp .env.example .env
|
||||||
|
print_message "$GREEN" "Forced creation of .env file"
|
||||||
|
else
|
||||||
|
copy_env_file ".env.example" ".env"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Determine environment
|
||||||
|
ENV=${NODE_ENV:-development}
|
||||||
|
case "$ENV" in
|
||||||
|
"development"|"dev")
|
||||||
|
ENV_FILE=".env.dev"
|
||||||
|
;;
|
||||||
|
"production"|"prod")
|
||||||
|
ENV_FILE=".env.prod"
|
||||||
|
;;
|
||||||
|
"test")
|
||||||
|
ENV_FILE=".env.test"
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
print_message "$RED" "Error: Invalid environment: $ENV"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
|
||||||
|
# Copy environment-specific file
|
||||||
|
if [ -f "$ENV_FILE" ]; then
|
||||||
|
if [ "$1" = "--force" ]; then
|
||||||
|
cp "$ENV_FILE" .env
|
||||||
|
print_message "$GREEN" "Forced override of .env with $ENV_FILE"
|
||||||
|
else
|
||||||
|
print_message "$YELLOW" "Do you want to override .env with $ENV_FILE? [y/N] "
|
||||||
|
read -r response
|
||||||
|
if [[ "$response" =~ ^([yY][eE][sS]|[yY])+$ ]]; then
|
||||||
|
cp "$ENV_FILE" .env
|
||||||
|
print_message "$GREEN" "Copied $ENV_FILE to .env"
|
||||||
|
else
|
||||||
|
print_message "$YELLOW" "Keeping existing .env file"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
print_message "$YELLOW" "Warning: $ENV_FILE not found. Using default .env"
|
||||||
|
fi
|
||||||
|
|
||||||
|
print_message "$GREEN" "Environment setup complete!"
|
||||||
|
print_message "$YELLOW" "Remember to set your HASS_TOKEN in .env"
|
||||||
Reference in New Issue
Block a user