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
|
||||
# Port for the MCP server (default: 3000)
|
||||
PORT=3000
|
||||
|
||||
# Environment (development/production/test)
|
||||
NODE_ENV=development
|
||||
|
||||
# Debug mode (true/false)
|
||||
PORT=3000
|
||||
DEBUG=false
|
||||
|
||||
# Logging level (debug/info/warn/error)
|
||||
LOG_LEVEL=info
|
||||
|
||||
# AI Configuration
|
||||
# Natural Language Processor type (claude/gpt4/custom)
|
||||
PROCESSOR_TYPE=claude
|
||||
|
||||
# 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
|
||||
# Home Assistant Configuration
|
||||
HASS_HOST=http://homeassistant.local:8123
|
||||
HASS_TOKEN=your_long_lived_token
|
||||
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
|
||||
|
||||
# Security Configuration
|
||||
# JWT Configuration
|
||||
JWT_SECRET=your_jwt_secret_key_min_32_chars
|
||||
JWT_EXPIRY=86400000
|
||||
JWT_MAX_AGE=2592000000
|
||||
@@ -46,11 +18,8 @@ JWT_ALGORITHM=HS256
|
||||
# Rate Limiting
|
||||
RATE_LIMIT_WINDOW=900000
|
||||
RATE_LIMIT_MAX_REQUESTS=100
|
||||
|
||||
# Token Security
|
||||
TOKEN_MIN_LENGTH=32
|
||||
MAX_FAILED_ATTEMPTS=5
|
||||
LOCKOUT_DURATION=900000
|
||||
RATE_LIMIT_REGULAR=100
|
||||
RATE_LIMIT_WEBSOCKET=1000
|
||||
|
||||
# CORS Configuration
|
||||
CORS_ORIGINS=http://localhost:3000,http://localhost:8123
|
||||
@@ -60,17 +29,6 @@ CORS_EXPOSED_HEADERS=
|
||||
CORS_CREDENTIALS=true
|
||||
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_SECRET=your_cookie_secret_key_min_32_chars
|
||||
COOKIE_SECURE=true
|
||||
@@ -81,27 +39,12 @@ COOKIE_SAME_SITE=Strict
|
||||
MAX_REQUEST_SIZE=1048576
|
||||
MAX_REQUEST_FIELDS=1000
|
||||
|
||||
# SSE Configuration
|
||||
SSE_MAX_CLIENTS=1000
|
||||
SSE_PING_INTERVAL=30000
|
||||
|
||||
# Logging Configuration
|
||||
LOG_LEVEL=info
|
||||
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
|
||||
# AI Configuration
|
||||
PROCESSOR_TYPE=claude
|
||||
OPENAI_API_KEY=your_openai_api_key
|
||||
OPENAI_MODEL=gpt-3.5-turbo
|
||||
MAX_RETRIES=3
|
||||
ANALYSIS_TIMEOUT=30000
|
||||
|
||||
# Speech Features Configuration
|
||||
ENABLE_SPEECH_FEATURES=false
|
||||
@@ -110,5 +53,30 @@ ENABLE_SPEECH_TO_TEXT=false
|
||||
WHISPER_MODEL_PATH=/models
|
||||
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)
|
||||
COMPOSE_PROJECT_NAME=mcp
|
||||
324
README.md
324
README.md
@@ -1,10 +1,42 @@
|
||||
# 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 🌐
|
||||
|
||||
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 ✨
|
||||
|
||||
@@ -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
|
||||
- 🤖 Simple automation rule management
|
||||
- 🔐 JWT-based authentication
|
||||
- 🎤 Real-time device control and monitoring
|
||||
- 🎤 Server-Sent Events (SSE) for live updates
|
||||
- 🎤 Comprehensive logging
|
||||
- 🎤 Optional speech features:
|
||||
- 🎤 Wake word detection ("hey jarvis", "ok google", "alexa")
|
||||
- 🎤 Speech-to-text using fast-whisper
|
||||
- 🎤 Multiple language support
|
||||
- 🎤 GPU acceleration support
|
||||
- 🗣️ Wake word detection ("hey jarvis", "ok google", "alexa")
|
||||
- 🎯 Speech-to-text using fast-whisper
|
||||
- 🌍 Multiple language 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 📋
|
||||
|
||||
- 🚀 Bun runtime (v1.0.26+)
|
||||
- 🏡 Home Assistant instance
|
||||
- 🐳 Docker (optional, recommended for deployment and speech features)
|
||||
- 🚀 [Bun runtime](https://bun.sh) (v1.0.26+)
|
||||
- 🏡 [Home Assistant](https://www.home-assistant.io/) instance
|
||||
- 🐳 Docker (optional, recommended for deployment)
|
||||
- 🖥️ 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 🛠️
|
||||
|
||||
### Docker Deployment (Recommended)
|
||||
## Quick Start 🚀
|
||||
|
||||
1. Clone my repository:
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
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
|
||||
# Install Bun
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
# Make my setup script executable
|
||||
chmod +x scripts/setup-env.sh
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
# Run setup (defaults to development)
|
||||
./scripts/setup-env.sh
|
||||
|
||||
# Install dependencies
|
||||
bun install
|
||||
# Or specify an environment:
|
||||
NODE_ENV=production ./scripts/setup-env.sh
|
||||
|
||||
# Start the server
|
||||
bun run dev
|
||||
# Force override existing files:
|
||||
./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
|
||||
|
||||
```typescript
|
||||
// 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' })
|
||||
});
|
||||
4. Launch with Docker:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### WebSocket State Updates
|
||||
## Environment Configuration 🔧
|
||||
|
||||
```typescript
|
||||
const ws = new WebSocket('ws://localhost:3000/devices');
|
||||
ws.onmessage = (event) => {
|
||||
const deviceState = JSON.parse(event.data);
|
||||
console.log('Device state updated:', deviceState);
|
||||
};
|
||||
```
|
||||
I've implemented a hierarchical configuration system:
|
||||
|
||||
## 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
|
||||
1. Docker installed and running
|
||||
2. NVIDIA GPU with CUDA support (optional)
|
||||
3. At least 4GB RAM (8GB+ recommended for larger models)
|
||||
1. 🐳 Docker installed and running
|
||||
2. 🎮 NVIDIA GPU with CUDA (optional)
|
||||
3. 💾 4GB+ RAM (8GB+ recommended)
|
||||
|
||||
### Setup
|
||||
|
||||
1. Enable speech features in your .env:
|
||||
### Configuration
|
||||
1. Enable speech in `.env`:
|
||||
```bash
|
||||
ENABLE_SPEECH_FEATURES=true
|
||||
ENABLE_WAKE_WORD=true
|
||||
@@ -109,67 +177,65 @@ WHISPER_MODEL_PATH=/models
|
||||
WHISPER_MODEL_TYPE=base
|
||||
```
|
||||
|
||||
2. Start the speech services:
|
||||
2. Choose your STT engine:
|
||||
```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
|
||||
|
||||
Choose a model based on your needs:
|
||||
### Available Models 🤖
|
||||
Choose based on your needs:
|
||||
- `tiny.en`: Fastest, basic accuracy
|
||||
- `base.en`: Good balance (recommended)
|
||||
- `small.en`: Better accuracy, slower
|
||||
- `medium.en`: High accuracy, resource intensive
|
||||
- `large-v2`: Best accuracy, very resource intensive
|
||||
|
||||
### Usage
|
||||
## Development 💻
|
||||
|
||||
1. Wake word detection listens for:
|
||||
- "hey jarvis"
|
||||
- "ok google"
|
||||
- "alexa"
|
||||
```bash
|
||||
# Install dependencies
|
||||
bun install
|
||||
|
||||
2. After wake word detection:
|
||||
- Audio is automatically captured
|
||||
- Speech is transcribed
|
||||
- Commands are processed
|
||||
# Run in development mode
|
||||
bun run dev
|
||||
|
||||
3. Manual transcription is also available:
|
||||
```typescript
|
||||
const speech = speechService.getSpeechToText();
|
||||
const text = await speech.transcribe(audioBuffer);
|
||||
# Run tests
|
||||
bun test
|
||||
|
||||
# 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
|
||||
|
||||
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:
|
||||
## Client Integration 🔗
|
||||
|
||||
### Cursor Integration 🖱️
|
||||
|
||||
The server can be integrated with Cursor by adding the configuration to `.cursor/config/config.json`:
|
||||
|
||||
Add to `.cursor/config/config.json`:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
@@ -185,10 +251,8 @@ The server can be integrated with Cursor by adding the configuration to `.cursor
|
||||
}
|
||||
```
|
||||
|
||||
### Claude Desktop Integration 💬
|
||||
|
||||
For Claude Desktop, add the following to your Claude configuration file:
|
||||
|
||||
### Claude Desktop 💬
|
||||
Add to your Claude config:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
@@ -203,37 +267,15 @@ For Claude Desktop, add the following to your Claude configuration file:
|
||||
}
|
||||
```
|
||||
|
||||
### Cline Integration 📟
|
||||
|
||||
For Cline-based clients, add the following configuration:
|
||||
|
||||
```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
|
||||
### Command Line 💻
|
||||
Windows users can use the provided script:
|
||||
1. Go to `scripts` directory
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
```bash
|
||||
# Server Configuration
|
||||
PORT=3000 # Server port
|
||||
HOST=localhost # Server host
|
||||
PORT=4000 # Server port number
|
||||
NODE_ENV=development # Environment (development/production/test)
|
||||
|
||||
# Home Assistant
|
||||
HASS_URL=http://localhost:8123 # Home Assistant URL
|
||||
HASS_TOKEN=your_token # Long-lived access token
|
||||
HASS_HOST=http://homeassistant.local:8123 # Home Assistant URL
|
||||
HASS_TOKEN=your_token_here # Long-lived access token
|
||||
|
||||
# Security
|
||||
JWT_SECRET=your_secret # JWT signing secret
|
||||
JWT_SECRET=your_secret_key # JWT signing secret
|
||||
```
|
||||
|
||||
### Optional Settings
|
||||
|
||||
#### Security
|
||||
```bash
|
||||
# Rate Limiting
|
||||
RATE_LIMIT_WINDOW=60000 # Time window in ms (default: 60000)
|
||||
RATE_LIMIT_MAX=100 # Max requests per window (default: 100)
|
||||
RATE_LIMIT_WINDOW=900000 # Time window in ms (15 minutes)
|
||||
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
|
||||
LOG_LEVEL=info # debug, info, warn, error (default: info)
|
||||
LOG_DIR=logs # Log directory (default: logs)
|
||||
LOG_MAX_SIZE=10m # Max log file size (default: 10m)
|
||||
LOG_MAX_FILES=5 # Max number of log files (default: 5)
|
||||
# CORS Configuration
|
||||
CORS_ORIGINS=http://localhost:3000,http://localhost:8123
|
||||
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
|
||||
CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-Requested-With
|
||||
CORS_EXPOSED_HEADERS=
|
||||
CORS_CREDENTIALS=true
|
||||
CORS_MAX_AGE=86400
|
||||
|
||||
# WebSocket/SSE
|
||||
WS_HEARTBEAT=30000 # WebSocket heartbeat interval in ms (default: 30000)
|
||||
SSE_RETRY=3000 # SSE retry interval in ms (default: 3000)
|
||||
|
||||
# Speech Features
|
||||
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)
|
||||
# Cookie Security
|
||||
COOKIE_SECRET=your_cookie_secret_key_min_32_chars
|
||||
COOKIE_SECURE=true
|
||||
COOKIE_HTTP_ONLY=true
|
||||
COOKIE_SAME_SITE=Strict
|
||||
```
|
||||
|
||||
## 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 |
|
||||
|------------|-------|-----------------|-------|----------|
|
||||
| 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 |
|
||||
## Best Practices
|
||||
|
||||
### 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`:
|
||||
- NVIDIA GPU with CUDA support required
|
||||
- Significantly faster processing
|
||||
- Higher memory requirements
|
||||
2. **Security**
|
||||
- Use strong, unique values for secrets
|
||||
- Enable HTTPS in production
|
||||
- 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
|
||||
- Adjustable sensitivity (0-1):
|
||||
- Lower values: Fewer false positives, may miss some triggers
|
||||
- Higher values: More responsive, may have false triggers
|
||||
- Default (0.5): Balanced detection
|
||||
4. **Production**
|
||||
- Use `.env.prod` for production defaults
|
||||
- Set appropriate rate limits
|
||||
- Configure proper logging
|
||||
- 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:
|
||||
- Start with `base.en` model
|
||||
- Upgrade if better accuracy needed
|
||||
- Downgrade if performance issues
|
||||
## Troubleshooting
|
||||
|
||||
2. Resource Management:
|
||||
- Monitor memory usage
|
||||
- Use GPU acceleration when available
|
||||
- Consider model size vs available resources
|
||||
### Common Issues
|
||||
|
||||
3. Wake Word Configuration:
|
||||
- Use distinct wake words
|
||||
- Adjust sensitivity based on environment
|
||||
- Limit number of wake words for better performance
|
||||
1. **Missing Required Variables**
|
||||
- Error: "Missing required environment variable: HASS_TOKEN"
|
||||
- Solution: Ensure HASS_TOKEN is set in your .env file
|
||||
|
||||
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