Compare commits
26 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
4db60b6a6f | ||
|
|
69e9c7de55 | ||
|
|
e96fa163cd | ||
|
|
cfef80e1e5 | ||
|
|
9b74a4354b | ||
|
|
fca193b5b2 | ||
|
|
cc9eede856 | ||
|
|
f0ff3d5e5a | ||
|
|
81d6dea7da | ||
|
|
1328bd1306 | ||
|
|
6fa88be433 | ||
|
|
2892f24030 | ||
|
|
1e3442db14 | ||
|
|
f74154d96f | ||
|
|
36d83e0a0e | ||
|
|
33defac76c | ||
|
|
4306a6866f | ||
|
|
039f6890a7 | ||
|
|
4fff318ea9 | ||
|
|
ea6efd553d | ||
|
|
d45ef5c622 | ||
|
|
9358f83229 | ||
|
|
e49d31d725 | ||
|
|
13a27e1d00 | ||
|
|
3e7f3920b2 | ||
|
|
8f8e3bd85e |
@@ -1 +0,0 @@
|
||||
NODE_ENV=development\nOPENAI_API_KEY=your_openai_api_key_here\nHASS_HOST=http://homeassistant.local:8123\nHASS_TOKEN=your_hass_token_here\nPORT=3000\nHASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket\nLOG_LEVEL=debug\nMCP_SERVER=http://localhost:3000\nOPENAI_MODEL=deepseek-v3\nMAX_RETRIES=3\nANALYSIS_TIMEOUT=30000\n\n# Home Assistant specific settings\nAUTOMATION_PATH=./config/automations.yaml\nBLUEPRINT_REPO=https://blueprints.home-assistant.io/\nENERGY_DASHBOARD=true\n\n# Available models: gpt-4o, gpt-4-turbo, gpt-4, gpt-4-o1, gpt-4-o3, gpt-3.5-turbo, gpt-3.5-turbo-16k, deepseek-v3, deepseek-r1\n\n# For DeepSeek models\nDEEPSEEK_API_KEY=your_deepseek_api_key_here\nDEEPSEEK_BASE_URL=https://api.deepseek.com/v1\n\n# Model specifications:\n# - gpt-4-o1: 128k context, general purpose\n# - gpt-4-o3: 1M context, large-scale analysis\n\n# Add processor type specification\nPROCESSOR_TYPE=claude # Change to openai when using OpenAI
|
||||
109
.env.example
109
.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_home_assistant_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,31 +39,44 @@ COOKIE_SAME_SITE=Strict
|
||||
MAX_REQUEST_SIZE=1048576
|
||||
MAX_REQUEST_FIELDS=1000
|
||||
|
||||
# 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
|
||||
ENABLE_WAKE_WORD=false
|
||||
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=1000
|
||||
SSE_PING_INTERVAL=30000
|
||||
SSE_MAX_CLIENTS=50
|
||||
SSE_RECONNECT_TIMEOUT=5000
|
||||
|
||||
# Logging Configuration
|
||||
LOG_LEVEL=info
|
||||
LOG_DIR=logs
|
||||
LOG_MAX_SIZE=20m
|
||||
LOG_MAX_DAYS=14d
|
||||
LOG_COMPRESS=true
|
||||
LOG_REQUESTS=true
|
||||
# Development Flags
|
||||
HOT_RELOAD=true
|
||||
|
||||
# Version
|
||||
VERSION=0.1.0
|
||||
|
||||
# Test Configuration
|
||||
# Only needed if running tests
|
||||
# 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
|
||||
|
||||
# Speech Features Configuration
|
||||
ENABLE_SPEECH_FEATURES=false
|
||||
ENABLE_WAKE_WORD=true
|
||||
ENABLE_SPEECH_TO_TEXT=true
|
||||
WHISPER_MODEL_PATH=/models
|
||||
WHISPER_MODEL_TYPE=base
|
||||
# Version
|
||||
VERSION=0.1.0
|
||||
|
||||
# Advanced (Docker)
|
||||
COMPOSE_PROJECT_NAME=mcp
|
||||
52
.github/workflows/deploy-docs.yml
vendored
52
.github/workflows/deploy-docs.yml
vendored
@@ -1,4 +1,4 @@
|
||||
name: Deploy Documentation to GitHub Pages
|
||||
name: Deploy Documentation
|
||||
|
||||
on:
|
||||
push:
|
||||
@@ -6,57 +6,69 @@ on:
|
||||
- main
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- '.github/workflows/deploy-docs.yml'
|
||||
- 'mkdocs.yml'
|
||||
# Allow manual trigger
|
||||
workflow_dispatch:
|
||||
|
||||
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# Allow only one concurrent deployment
|
||||
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: true
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Ruby
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: '3.2'
|
||||
bundler-cache: true
|
||||
cache-version: 0
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Setup Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.x'
|
||||
cache: 'pip'
|
||||
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v4
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
cd docs
|
||||
bundle install
|
||||
python -m pip install --upgrade pip
|
||||
pip install -r docs/requirements.txt
|
||||
|
||||
- name: Build site
|
||||
- name: List mkdocs configuration
|
||||
run: |
|
||||
cd docs
|
||||
bundle exec jekyll build
|
||||
env:
|
||||
JEKYLL_ENV: production
|
||||
echo "Current directory contents:"
|
||||
ls -la
|
||||
echo "MkDocs version:"
|
||||
mkdocs --version
|
||||
echo "MkDocs configuration:"
|
||||
cat mkdocs.yml
|
||||
|
||||
- name: Build documentation
|
||||
run: |
|
||||
mkdocs build --strict
|
||||
echo "Build output contents:"
|
||||
ls -la site/advanced-homeassistant-mcp
|
||||
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: docs/_site
|
||||
path: ./site/advanced-homeassistant-mcp
|
||||
|
||||
deploy:
|
||||
needs: build
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
|
||||
32
.github/workflows/docs-deploy.yml
vendored
32
.github/workflows/docs-deploy.yml
vendored
@@ -1,32 +0,0 @@
|
||||
name: Deploy Documentation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- 'mkdocs.yml'
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
deploy-docs:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: 3.x
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install mkdocs-material
|
||||
pip install mkdocs
|
||||
|
||||
- name: Deploy documentation
|
||||
run: mkdocs gh-deploy --force
|
||||
13
.gitignore
vendored
13
.gitignore
vendored
@@ -31,7 +31,7 @@ wheels/
|
||||
venv/
|
||||
ENV/
|
||||
env/
|
||||
|
||||
.venv/
|
||||
# Logs
|
||||
logs
|
||||
*.log
|
||||
@@ -71,7 +71,7 @@ coverage/
|
||||
# Environment files
|
||||
.env
|
||||
.env.*
|
||||
!.env.*.template
|
||||
!.env.example
|
||||
|
||||
.cursor/
|
||||
.cursor/*
|
||||
@@ -90,3 +90,12 @@ __pycache__/
|
||||
*$py.class
|
||||
|
||||
models/
|
||||
|
||||
*.code-workspace
|
||||
*.ttf
|
||||
*.otf
|
||||
*.woff
|
||||
*.woff2
|
||||
*.eot
|
||||
*.svg
|
||||
*.png
|
||||
501
README.md
501
README.md
@@ -1,308 +1,241 @@
|
||||
# 🚀 MCP Server for Home Assistant - Bringing AI-Powered Smart Homes to Life!
|
||||
# MCP Server for Home Assistant 🏠🤖
|
||||
|
||||
[](LICENSE)
|
||||
[](https://bun.sh)
|
||||
[](https://www.typescriptlang.org)
|
||||
[](#)
|
||||
[](https://jango-blockchained.github.io/homeassistant-mcp/)
|
||||
[](https://www.docker.com)
|
||||
|
||||
---
|
||||
[](LICENSE) [](https://bun.sh) [](https://www.typescriptlang.org)
|
||||
|
||||
## Overview 🌐
|
||||
|
||||
Welcome to the **Model Context Protocol (MCP) Server for Home Assistant**! This robust platform bridges Home Assistant with cutting-edge Language Learning Models (LLMs), enabling natural language interactions and real-time automation of your smart devices. Imagine entering your home, saying:
|
||||
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.
|
||||
|
||||
> "Hey MCP, dim the lights and start my evening playlist,"
|
||||
## Why Bun? 🚀
|
||||
|
||||
and watching your home transform instantly—that's the magic that MCP Server delivers!
|
||||
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
|
||||
|
||||
## Key Benefits ✨
|
||||
- 🎯 **All-in-One Solution**
|
||||
- Package manager (faster than npm/yarn)
|
||||
- Bundler (no webpack needed)
|
||||
- Test runner (built-in testing)
|
||||
- TypeScript transpiler
|
||||
|
||||
### 🎮 Device Control & Monitoring
|
||||
- **Voice-Controlled Automation:**
|
||||
Use simple commands like "Turn on the kitchen lights" or "Set the thermostat to 22°C" without touching a switch.
|
||||
**Real-World Example:**
|
||||
In the morning, say "Good morning! Open the blinds and start the coffee machine" to kickstart your day automatically.
|
||||
- 🔋 **Built-in Features**
|
||||
- SQLite3 driver
|
||||
- .env file loading
|
||||
- WebSocket client/server
|
||||
- File watcher
|
||||
- Test runner
|
||||
|
||||
- **Real-Time Communication:**
|
||||
Experience sub-100ms latency updates via Server-Sent Events (SSE) or WebSocket connections, ensuring your dashboard is always current.
|
||||
**Real-World Example:**
|
||||
Monitor energy usage instantly during peak hours and adjust remotely for efficient consumption.
|
||||
- 💾 **Resource Efficient**
|
||||
- Lower memory usage
|
||||
- Faster cold starts
|
||||
- Better CPU utilization
|
||||
|
||||
- **Seamless Automation:**
|
||||
Create scene-based rules to synchronize multiple devices effortlessly.
|
||||
**Real-World Example:**
|
||||
For movie nights, have MCP dim the lights, adjust the sound system, and launch your favorite streaming app with just one command.
|
||||
- 🔄 **Node.js Compatibility**
|
||||
- Runs most npm packages
|
||||
- Compatible with Express/Fastify
|
||||
- Native Node.js APIs
|
||||
|
||||
### 🤖 AI-Powered Enhancements
|
||||
- **Natural Language Processing (NLP):**
|
||||
Convert everyday speech into actionable commands—just say, "Prepare the house for dinner," and MCP will adjust lighting, temperature, and even play soft background music.
|
||||
## Core Features ✨
|
||||
|
||||
- **Predictive Automation & Suggestions:**
|
||||
Receive proactive recommendations based on usage habits and environmental trends.
|
||||
**Real-World Example:**
|
||||
When home temperature fluctuates unexpectedly, MCP suggests an optimal setting and notifies you immediately.
|
||||
- 🔌 Basic device control via REST API
|
||||
- 📡 WebSocket/Server-Sent Events (SSE) for state updates
|
||||
- 🤖 Simple automation rule management
|
||||
- 🔐 JWT-based authentication
|
||||
- 🎤 Optional speech features:
|
||||
- 🗣️ Wake word detection ("hey jarvis", "ok google", "alexa")
|
||||
- 🎯 Speech-to-text using fast-whisper
|
||||
- 🌍 Multiple language support
|
||||
- 🚀 GPU acceleration support
|
||||
|
||||
- **Anomaly Detection:**
|
||||
Continuously monitor device activity and alert you to unusual behavior, helping prevent malfunctions or potential security breaches.
|
||||
|
||||
---
|
||||
|
||||
## Architectural Overview 🏗
|
||||
|
||||
Our architecture is engineered for performance, scalability, and security. The following Mermaid diagram illustrates the data flow and component interactions:
|
||||
## System Architecture 📊
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph Client
|
||||
A["Client Application (Web/Mobile/Voice)"]
|
||||
end
|
||||
subgraph CDN
|
||||
B["CDN / Cache"]
|
||||
end
|
||||
subgraph Server
|
||||
C["Bun Native Server"]
|
||||
E["NLP Engine & Language Processing Module"]
|
||||
end
|
||||
subgraph Integration
|
||||
D["Home Assistant (Devices, Lights, Thermostats)"]
|
||||
flowchart TB
|
||||
subgraph Client["Client Applications"]
|
||||
direction TB
|
||||
Web["Web Interface"]
|
||||
Mobile["Mobile Apps"]
|
||||
Voice["Voice Control"]
|
||||
end
|
||||
|
||||
A -->|HTTP Request| B
|
||||
B -- Cache Miss --> C
|
||||
C -->|Interpret Command| E
|
||||
E -->|Determine Action| D
|
||||
D -->|Return State/Action| C
|
||||
C -->|Response| B
|
||||
B -->|Cached/Processed Response| A
|
||||
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
|
||||
```
|
||||
|
||||
Learn more about our architecture in the [Architecture Documentation](docs/architecture.md).
|
||||
## Prerequisites 📋
|
||||
|
||||
---
|
||||
- 🚀 [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)
|
||||
|
||||
## Technical Stack 🔧
|
||||
## Quick Start 🚀
|
||||
|
||||
Our solution is built on a modern, high-performance stack that powers every feature:
|
||||
1. Clone my repository:
|
||||
```bash
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
- **Bun:**
|
||||
A next-generation JavaScript runtime offering rapid startup times, native TypeScript support, and high performance.
|
||||
👉 [Learn about Bun](https://bun.sh)
|
||||
2. Set up the environment:
|
||||
```bash
|
||||
# Make my setup script executable
|
||||
chmod +x scripts/setup-env.sh
|
||||
|
||||
- **Bun Native Server:**
|
||||
Utilizes Bun's built-in HTTP server to efficiently process API requests with sub-100ms response times.
|
||||
👉 See the [Installation Guide](docs/getting-started/installation.md) for details.
|
||||
# Run setup (defaults to development)
|
||||
./scripts/setup-env.sh
|
||||
|
||||
- **Natural Language Processing (NLP) & LLM Integration:**
|
||||
Processes and interprets natural language commands using state-of-the-art LLMs and custom NLP modules.
|
||||
👉 Find API usage details in the [API Documentation](docs/api.md).
|
||||
# Or specify an environment:
|
||||
NODE_ENV=production ./scripts/setup-env.sh
|
||||
|
||||
- **Home Assistant Integration:**
|
||||
Provides seamless connectivity with Home Assistant, ensuring flawless communication with your smart devices.
|
||||
👉 Refer to the [Usage Guide](docs/usage.md) for more information.
|
||||
# Force override existing files:
|
||||
./scripts/setup-env.sh --force
|
||||
```
|
||||
|
||||
- **Redis Cache:**
|
||||
Enables rapid data retrieval and session persistence essential for real-time updates.
|
||||
3. Configure your settings:
|
||||
- Edit `.env` file with your Home Assistant details
|
||||
- Required: Add your `HASS_TOKEN` (long-lived access token)
|
||||
|
||||
- **TypeScript:**
|
||||
Enhances type safety and developer productivity across the entire codebase.
|
||||
4. Launch with Docker:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
- **JWT & Security Middleware:**
|
||||
Protects your ecosystem with JWT-based authentication, request sanitization, rate-limiting, and encryption.
|
||||
## Environment Configuration 🔧
|
||||
|
||||
- **Containerization with Docker:**
|
||||
Enables scalable, isolated deployments for production environments.
|
||||
I've implemented a hierarchical configuration system:
|
||||
|
||||
For further technical details, check out our [Documentation Index](docs/index.md).
|
||||
### 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
|
||||
|
||||
---
|
||||
### 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`
|
||||
|
||||
## Installation 🛠
|
||||
Later files override earlier ones.
|
||||
|
||||
### Installing via Smithery
|
||||
## Speech Features Setup 🎤
|
||||
|
||||
To install Home Assistant MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@jango-blockchained/advanced-homeassistant-mcp):
|
||||
### Prerequisites
|
||||
1. 🐳 Docker installed and running
|
||||
2. 🎮 NVIDIA GPU with CUDA (optional)
|
||||
3. 💾 4GB+ RAM (8GB+ recommended)
|
||||
|
||||
### Configuration
|
||||
1. Enable speech in `.env`:
|
||||
```bash
|
||||
ENABLE_SPEECH_FEATURES=true
|
||||
ENABLE_WAKE_WORD=true
|
||||
ENABLE_SPEECH_TO_TEXT=true
|
||||
WHISPER_MODEL_PATH=/models
|
||||
WHISPER_MODEL_TYPE=base
|
||||
```
|
||||
|
||||
2. Choose your STT engine:
|
||||
```bash
|
||||
# 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 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
|
||||
|
||||
## Development 💻
|
||||
|
||||
```bash
|
||||
npx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude
|
||||
# Install dependencies
|
||||
bun install
|
||||
|
||||
# Run in development mode
|
||||
bun run dev
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
### 🐳 Docker Setup (Recommended)
|
||||
### Performance Comparison 📊
|
||||
|
||||
For a hassle-free, containerized deployment:
|
||||
| Operation | Bun | Node.js |
|
||||
|-----------|-----|---------|
|
||||
| Install Dependencies | ~2s | ~15s |
|
||||
| Cold Start | 300ms | 1000ms |
|
||||
| Build Time | 150ms | 4000ms |
|
||||
| Memory Usage | ~150MB | ~400MB |
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository (using a shallow copy for efficiency)
|
||||
git clone --depth 1 https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
## Documentation 📚
|
||||
|
||||
# 2. Configure your environment: copy the example file and edit it with your Home Assistant credentials
|
||||
cp .env.example .env # Modify .env with your Home Assistant host, tokens, etc.
|
||||
- [Configuration Guide](docs/configuration.md)
|
||||
- [API Documentation](docs/api.md)
|
||||
- [Troubleshooting](docs/troubleshooting.md)
|
||||
|
||||
# 3. Build and run the Docker containers
|
||||
docker compose up -d --build
|
||||
|
||||
# 4. View real-time logs (last 50 log entries)
|
||||
docker compose logs -f --tail=50
|
||||
```
|
||||
|
||||
👉 Refer to our [Installation Guide](docs/getting-started/installation.md) for full details.
|
||||
|
||||
### 💻 Bare Metal Installation
|
||||
|
||||
For direct deployment on your host machine:
|
||||
|
||||
```bash
|
||||
# 1. Install Bun (if not already installed)
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# 2. Install project dependencies with caching support
|
||||
bun install --frozen-lockfile
|
||||
|
||||
# 3. Launch the server in development mode with hot-reload enabled
|
||||
bun run dev --watch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real-World Usage Examples 🔍
|
||||
|
||||
### 📱 Smart Home Dashboard Integration
|
||||
Integrate MCP's real-time updates into your custom dashboard for a dynamic smart home experience:
|
||||
|
||||
```javascript
|
||||
const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light');
|
||||
|
||||
eventSource.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Real-time update:', data);
|
||||
// Update your UI dashboard, e.g., refresh a light intensity indicator.
|
||||
};
|
||||
```
|
||||
|
||||
### 🏠 Voice-Activated Control
|
||||
Utilize voice commands to trigger actions with minimal effort:
|
||||
|
||||
```javascript
|
||||
// Establish a WebSocket connection for real-time command processing
|
||||
const ws = new WebSocket('wss://mcp.yourha.com/ws');
|
||||
|
||||
ws.onmessage = ({ data }) => {
|
||||
const update = JSON.parse(data);
|
||||
if (update.entity_id === 'light.living_room') {
|
||||
console.log('Adjusting living room lighting based on voice command...');
|
||||
// Additional logic to update your UI or trigger further actions can go here.
|
||||
}
|
||||
};
|
||||
|
||||
// Simulate processing a voice command
|
||||
function simulateVoiceCommand(command) {
|
||||
console.log("Processing voice command:", command);
|
||||
// Integrate with your actual voice-to-text system as needed.
|
||||
}
|
||||
|
||||
simulateVoiceCommand("Turn off all the lights for bedtime");
|
||||
```
|
||||
|
||||
👉 Learn more in our [Usage Guide](docs/usage.md).
|
||||
|
||||
---
|
||||
|
||||
## Update Strategy 🔄
|
||||
|
||||
Maintain a seamless operation with zero downtime updates:
|
||||
|
||||
```bash
|
||||
# 1. Pull the latest Docker images
|
||||
docker compose pull
|
||||
|
||||
# 2. Rebuild and restart containers smoothly
|
||||
docker compose up -d --build
|
||||
|
||||
# 3. Clean up unused Docker images to free up space
|
||||
docker system prune -f
|
||||
```
|
||||
|
||||
For more details, review our [Troubleshooting & Updates](docs/troubleshooting.md).
|
||||
|
||||
---
|
||||
|
||||
## Security Features 🔐
|
||||
|
||||
We prioritize the security of your smart home with multiple layers of defense:
|
||||
- **JWT Authentication 🔑:** Secure, token-based API access to prevent unauthorized usage.
|
||||
- **Request Sanitization 🧼:** Automatic filtering and validation of API requests to combat injection attacks.
|
||||
- **Rate Limiting & Fail2Ban 🚫:** Monitors requests to prevent brute force and DDoS attacks.
|
||||
- **End-to-End Encryption 🔒:** Ensures that your commands and data remain private during transmission.
|
||||
|
||||
---
|
||||
|
||||
## Contributing 🤝
|
||||
|
||||
We value community contributions! Here's how you can help improve MCP Server:
|
||||
1. **Fork the Repository 🍴**
|
||||
Create your own copy of the project.
|
||||
2. **Create a Feature Branch 🌿**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
3. **Install Dependencies & Run Tests 🧪**
|
||||
```bash
|
||||
bun install
|
||||
bun test --coverage
|
||||
```
|
||||
4. **Make Your Changes & Commit 📝**
|
||||
Follow the [Conventional Commits](https://www.conventionalcommits.org) guidelines.
|
||||
5. **Open a Pull Request 🔀**
|
||||
Submit your changes for review.
|
||||
|
||||
Read more in our [Contribution Guidelines](docs/contributing.md).
|
||||
|
||||
---
|
||||
|
||||
## Roadmap & Future Enhancements 🔮
|
||||
|
||||
We're continuously evolving MCP Server. Upcoming features include:
|
||||
- **AI Assistant Integration (Q4 2024):**
|
||||
Smarter, context-aware voice commands and personalized automation.
|
||||
- **Predictive Automation (Q1 2025):**
|
||||
Enhanced scheduling capabilities powered by advanced AI.
|
||||
- **Enhanced Security (Q2 2024):**
|
||||
Introduction of multi-factor authentication, advanced monitoring, and rigorous encryption methods.
|
||||
- **Performance Optimizations (Q3 2024):**
|
||||
Reducing latency further, optimizing caching, and improving load balancing.
|
||||
|
||||
For more details, see our [Roadmap](docs/roadmap.md).
|
||||
|
||||
---
|
||||
|
||||
## Community & Support 🌍
|
||||
|
||||
Your feedback and collaboration are vital! Join our community:
|
||||
- **GitHub Issues:** Report bugs or request features via our [Issues Page](https://github.com/jango-blockchained/homeassistant-mcp/issues).
|
||||
- **Discord & Slack:** Connect with fellow users and developers in real-time.
|
||||
- **Documentation:** Find comprehensive guides on the [MCP Documentation Website](https://jango-blockchained.github.io/homeassistant-mcp/).
|
||||
|
||||
---
|
||||
|
||||
## License 📜
|
||||
|
||||
This project is licensed under the MIT License. See [LICENSE](LICENSE) for full details.
|
||||
|
||||
---
|
||||
|
||||
🔋 Batteries included.
|
||||
|
||||
## 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
|
||||
|
||||
The server can be integrated with Cursor by adding the configuration to `.cursor/config/config.json`:
|
||||
## Client Integration 🔗
|
||||
|
||||
### Cursor Integration 🖱️
|
||||
Add to `.cursor/config/config.json`:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
@@ -318,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": {
|
||||
@@ -336,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)
|
||||
|
||||
@@ -1,149 +1,149 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
|
||||
import { describe, expect, test, beforeEach, afterEach, mock, spyOn } from "bun:test";
|
||||
import type { Mock } from "bun:test";
|
||||
import type { Express, Application } from 'express';
|
||||
import type { Logger } from 'winston';
|
||||
import type { Elysia } from "elysia";
|
||||
|
||||
// Types for our mocks
|
||||
interface MockApp {
|
||||
use: Mock<() => void>;
|
||||
listen: Mock<(port: number, callback: () => void) => { close: Mock<() => void> }>;
|
||||
}
|
||||
|
||||
interface MockLiteMCPInstance {
|
||||
addTool: Mock<() => void>;
|
||||
start: Mock<() => Promise<void>>;
|
||||
}
|
||||
|
||||
type MockLogger = {
|
||||
info: Mock<(message: string) => void>;
|
||||
error: Mock<(message: string) => void>;
|
||||
debug: Mock<(message: string) => void>;
|
||||
};
|
||||
|
||||
// Mock express
|
||||
const mockApp: MockApp = {
|
||||
use: mock(() => undefined),
|
||||
listen: mock((port: number, callback: () => void) => {
|
||||
callback();
|
||||
return { close: mock(() => undefined) };
|
||||
// Create mock instances
|
||||
const mockApp = {
|
||||
use: mock(() => mockApp),
|
||||
get: mock(() => mockApp),
|
||||
post: mock(() => mockApp),
|
||||
listen: mock((port: number, callback?: () => void) => {
|
||||
callback?.();
|
||||
return mockApp;
|
||||
})
|
||||
};
|
||||
const mockExpress = mock(() => mockApp);
|
||||
|
||||
// Mock LiteMCP instance
|
||||
const mockLiteMCPInstance: MockLiteMCPInstance = {
|
||||
addTool: mock(() => undefined),
|
||||
start: mock(() => Promise.resolve())
|
||||
// Create mock constructors
|
||||
const MockElysia = mock(() => mockApp);
|
||||
const mockCors = mock(() => (app: any) => app);
|
||||
const mockSwagger = mock(() => (app: any) => app);
|
||||
const mockSpeechService = {
|
||||
initialize: mock(() => Promise.resolve()),
|
||||
shutdown: mock(() => Promise.resolve())
|
||||
};
|
||||
const mockLiteMCP = mock((name: string, version: string) => mockLiteMCPInstance);
|
||||
|
||||
// Mock logger
|
||||
const mockLogger: MockLogger = {
|
||||
info: mock((message: string) => undefined),
|
||||
error: mock((message: string) => undefined),
|
||||
debug: mock((message: string) => undefined)
|
||||
// Mock the modules
|
||||
const mockModules = {
|
||||
Elysia: MockElysia,
|
||||
cors: mockCors,
|
||||
swagger: mockSwagger,
|
||||
speechService: mockSpeechService,
|
||||
config: mock(() => ({})),
|
||||
resolve: mock((...args: string[]) => args.join('/')),
|
||||
z: { object: mock(() => ({})), enum: mock(() => ({})) }
|
||||
};
|
||||
|
||||
// Mock module resolution
|
||||
const mockResolver = {
|
||||
resolve(specifier: string) {
|
||||
const mocks: Record<string, any> = {
|
||||
'elysia': { Elysia: mockModules.Elysia },
|
||||
'@elysiajs/cors': { cors: mockModules.cors },
|
||||
'@elysiajs/swagger': { swagger: mockModules.swagger },
|
||||
'../speech/index.js': { speechService: mockModules.speechService },
|
||||
'dotenv': { config: mockModules.config },
|
||||
'path': { resolve: mockModules.resolve },
|
||||
'zod': { z: mockModules.z }
|
||||
};
|
||||
return mocks[specifier] || {};
|
||||
}
|
||||
};
|
||||
|
||||
describe('Server Initialization', () => {
|
||||
let originalEnv: NodeJS.ProcessEnv;
|
||||
let consoleLog: Mock<typeof console.log>;
|
||||
let consoleError: Mock<typeof console.error>;
|
||||
let originalResolve: any;
|
||||
|
||||
beforeEach(() => {
|
||||
// Store original environment
|
||||
originalEnv = { ...process.env };
|
||||
|
||||
// Setup mocks
|
||||
(globalThis as any).express = mockExpress;
|
||||
(globalThis as any).LiteMCP = mockLiteMCP;
|
||||
(globalThis as any).logger = mockLogger;
|
||||
// Mock console methods
|
||||
consoleLog = mock(() => { });
|
||||
consoleError = mock(() => { });
|
||||
console.log = consoleLog;
|
||||
console.error = consoleError;
|
||||
|
||||
// Reset all mocks
|
||||
mockApp.use.mockReset();
|
||||
mockApp.listen.mockReset();
|
||||
mockLogger.info.mockReset();
|
||||
mockLogger.error.mockReset();
|
||||
mockLogger.debug.mockReset();
|
||||
mockLiteMCP.mockReset();
|
||||
for (const key in mockModules) {
|
||||
const module = mockModules[key as keyof typeof mockModules];
|
||||
if (typeof module === 'object' && module !== null) {
|
||||
Object.values(module).forEach(value => {
|
||||
if (typeof value === 'function' && 'mock' in value) {
|
||||
(value as Mock<any>).mockReset();
|
||||
}
|
||||
});
|
||||
} else if (typeof module === 'function' && 'mock' in module) {
|
||||
(module as Mock<any>).mockReset();
|
||||
}
|
||||
}
|
||||
|
||||
// Set default environment variables
|
||||
process.env.NODE_ENV = 'test';
|
||||
process.env.PORT = '4000';
|
||||
|
||||
// Setup module resolution mock
|
||||
originalResolve = (globalThis as any).Bun?.resolveSync;
|
||||
(globalThis as any).Bun = {
|
||||
...(globalThis as any).Bun,
|
||||
resolveSync: (specifier: string) => mockResolver.resolve(specifier)
|
||||
};
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Restore original environment
|
||||
process.env = originalEnv;
|
||||
|
||||
// Clean up mocks
|
||||
delete (globalThis as any).express;
|
||||
delete (globalThis as any).LiteMCP;
|
||||
delete (globalThis as any).logger;
|
||||
// Restore module resolution
|
||||
if (originalResolve) {
|
||||
(globalThis as any).Bun.resolveSync = originalResolve;
|
||||
}
|
||||
});
|
||||
|
||||
test('should start Express server when not in Claude mode', async () => {
|
||||
// Set OpenAI mode
|
||||
process.env.PROCESSOR_TYPE = 'openai';
|
||||
test('should initialize server with middleware', async () => {
|
||||
// Import and initialize server
|
||||
const mod = await import('../src/index');
|
||||
|
||||
// Import the main module
|
||||
await import('../src/index.js');
|
||||
// Verify server initialization
|
||||
expect(MockElysia.mock.calls.length).toBe(1);
|
||||
expect(mockCors.mock.calls.length).toBe(1);
|
||||
expect(mockSwagger.mock.calls.length).toBe(1);
|
||||
|
||||
// Verify Express server was initialized
|
||||
expect(mockExpress.mock.calls.length).toBeGreaterThan(0);
|
||||
expect(mockApp.use.mock.calls.length).toBeGreaterThan(0);
|
||||
expect(mockApp.listen.mock.calls.length).toBeGreaterThan(0);
|
||||
|
||||
const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
|
||||
expect(infoMessages.some(msg => msg.includes('Server is running on port'))).toBe(true);
|
||||
// Verify console output
|
||||
const logCalls = consoleLog.mock.calls;
|
||||
expect(logCalls.some(call =>
|
||||
typeof call.args[0] === 'string' &&
|
||||
call.args[0].includes('Server is running on port')
|
||||
)).toBe(true);
|
||||
});
|
||||
|
||||
test('should not start Express server in Claude mode', async () => {
|
||||
// Set Claude mode
|
||||
process.env.PROCESSOR_TYPE = 'claude';
|
||||
test('should initialize speech service when enabled', async () => {
|
||||
// Enable speech service
|
||||
process.env.SPEECH_ENABLED = 'true';
|
||||
|
||||
// Import the main module
|
||||
await import('../src/index.js');
|
||||
// Import and initialize server
|
||||
const mod = await import('../src/index');
|
||||
|
||||
// Verify Express server was not initialized
|
||||
expect(mockExpress.mock.calls.length).toBe(0);
|
||||
expect(mockApp.use.mock.calls.length).toBe(0);
|
||||
expect(mockApp.listen.mock.calls.length).toBe(0);
|
||||
|
||||
const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
|
||||
expect(infoMessages).toContain('Running in Claude mode - Express server disabled');
|
||||
// Verify speech service initialization
|
||||
expect(mockSpeechService.initialize.mock.calls.length).toBe(1);
|
||||
});
|
||||
|
||||
test('should initialize LiteMCP in both modes', async () => {
|
||||
// Test OpenAI mode
|
||||
process.env.PROCESSOR_TYPE = 'openai';
|
||||
await import('../src/index.js');
|
||||
test('should handle server shutdown gracefully', async () => {
|
||||
// Enable speech service for shutdown test
|
||||
process.env.SPEECH_ENABLED = 'true';
|
||||
|
||||
expect(mockLiteMCP.mock.calls.length).toBeGreaterThan(0);
|
||||
const [name, version] = mockLiteMCP.mock.calls[0] ?? [];
|
||||
expect(name).toBe('home-assistant');
|
||||
expect(typeof version).toBe('string');
|
||||
// Import and initialize server
|
||||
const mod = await import('../src/index');
|
||||
|
||||
// Reset for next test
|
||||
mockLiteMCP.mockReset();
|
||||
// Simulate SIGTERM
|
||||
process.emit('SIGTERM');
|
||||
|
||||
// Test Claude mode
|
||||
process.env.PROCESSOR_TYPE = 'claude';
|
||||
await import('../src/index.js');
|
||||
|
||||
expect(mockLiteMCP.mock.calls.length).toBeGreaterThan(0);
|
||||
const [name2, version2] = mockLiteMCP.mock.calls[0] ?? [];
|
||||
expect(name2).toBe('home-assistant');
|
||||
expect(typeof version2).toBe('string');
|
||||
});
|
||||
|
||||
test('should handle missing PROCESSOR_TYPE (default to Express server)', async () => {
|
||||
// Remove PROCESSOR_TYPE
|
||||
delete process.env.PROCESSOR_TYPE;
|
||||
|
||||
// Import the main module
|
||||
await import('../src/index.js');
|
||||
|
||||
// Verify Express server was initialized (default behavior)
|
||||
expect(mockExpress.mock.calls.length).toBeGreaterThan(0);
|
||||
expect(mockApp.use.mock.calls.length).toBeGreaterThan(0);
|
||||
expect(mockApp.listen.mock.calls.length).toBeGreaterThan(0);
|
||||
|
||||
const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
|
||||
expect(infoMessages.some(msg => msg.includes('Server is running on port'))).toBe(true);
|
||||
// Verify shutdown behavior
|
||||
expect(mockSpeechService.shutdown.mock.calls.length).toBe(1);
|
||||
expect(consoleLog.mock.calls.some(call =>
|
||||
typeof call.args[0] === 'string' &&
|
||||
call.args[0].includes('Shutting down gracefully')
|
||||
)).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -1,81 +1,79 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { SpeechToText, TranscriptionResult, WakeWordEvent, TranscriptionError, TranscriptionOptions } from '../../src/speech/speechToText';
|
||||
import { EventEmitter } from 'events';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import { spawn } from 'child_process';
|
||||
import { describe, expect, beforeEach, afterEach, it, mock, spyOn } from 'bun:test';
|
||||
import { describe, expect, test, beforeEach, afterEach, mock, spyOn } from "bun:test";
|
||||
import type { Mock } from "bun:test";
|
||||
import { EventEmitter } from "events";
|
||||
import { SpeechToText, TranscriptionError, type TranscriptionOptions } from "../../src/speech/speechToText";
|
||||
import type { SpeechToTextConfig } from "../../src/speech/types";
|
||||
import type { ChildProcess } from "child_process";
|
||||
|
||||
// Mock child_process spawn
|
||||
const spawnMock = mock((cmd: string, args: string[]) => ({
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
}));
|
||||
interface MockProcess extends EventEmitter {
|
||||
stdout: EventEmitter;
|
||||
stderr: EventEmitter;
|
||||
kill: Mock<() => void>;
|
||||
}
|
||||
|
||||
type SpawnFn = {
|
||||
(cmds: string[], options?: Record<string, unknown>): ChildProcess;
|
||||
};
|
||||
|
||||
describe('SpeechToText', () => {
|
||||
let spawnMock: Mock<SpawnFn>;
|
||||
let mockProcess: MockProcess;
|
||||
let speechToText: SpeechToText;
|
||||
const testAudioDir = path.join(import.meta.dir, 'test_audio');
|
||||
const mockConfig = {
|
||||
containerName: 'test-whisper',
|
||||
modelPath: '/models/whisper',
|
||||
modelType: 'base.en'
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
speechToText = new SpeechToText(mockConfig);
|
||||
// Create test audio directory if it doesn't exist
|
||||
if (!fs.existsSync(testAudioDir)) {
|
||||
fs.mkdirSync(testAudioDir, { recursive: true });
|
||||
}
|
||||
// Reset spawn mock
|
||||
spawnMock.mockReset();
|
||||
// Create mock process
|
||||
mockProcess = new EventEmitter() as MockProcess;
|
||||
mockProcess.stdout = new EventEmitter();
|
||||
mockProcess.stderr = new EventEmitter();
|
||||
mockProcess.kill = mock(() => { });
|
||||
|
||||
// Create spawn mock
|
||||
spawnMock = mock((cmds: string[], options?: Record<string, unknown>) => mockProcess as unknown as ChildProcess);
|
||||
(globalThis as any).Bun = { spawn: spawnMock };
|
||||
|
||||
// Initialize SpeechToText
|
||||
const config: SpeechToTextConfig = {
|
||||
modelPath: '/test/model',
|
||||
modelType: 'base.en',
|
||||
containerName: 'test-container'
|
||||
};
|
||||
speechToText = new SpeechToText(config);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
speechToText.stopWakeWordDetection();
|
||||
// Clean up test files
|
||||
if (fs.existsSync(testAudioDir)) {
|
||||
fs.rmSync(testAudioDir, { recursive: true, force: true });
|
||||
}
|
||||
// Cleanup
|
||||
mockProcess.removeAllListeners();
|
||||
mockProcess.stdout.removeAllListeners();
|
||||
mockProcess.stderr.removeAllListeners();
|
||||
});
|
||||
|
||||
describe('Initialization', () => {
|
||||
test('should create instance with default config', () => {
|
||||
const instance = new SpeechToText({ modelPath: '/models/whisper', modelType: 'base.en' });
|
||||
expect(instance instanceof EventEmitter).toBe(true);
|
||||
expect(instance instanceof SpeechToText).toBe(true);
|
||||
const config: SpeechToTextConfig = {
|
||||
modelPath: '/test/model',
|
||||
modelType: 'base.en'
|
||||
};
|
||||
const instance = new SpeechToText(config);
|
||||
expect(instance).toBeDefined();
|
||||
});
|
||||
|
||||
test('should initialize successfully', async () => {
|
||||
const initSpy = spyOn(speechToText, 'initialize');
|
||||
await speechToText.initialize();
|
||||
expect(initSpy).toHaveBeenCalled();
|
||||
const result = await speechToText.initialize();
|
||||
expect(result).toBeUndefined();
|
||||
});
|
||||
|
||||
test('should not initialize twice', async () => {
|
||||
await speechToText.initialize();
|
||||
const initSpy = spyOn(speechToText, 'initialize');
|
||||
await speechToText.initialize();
|
||||
expect(initSpy.mock.calls.length).toBe(1);
|
||||
const result = await speechToText.initialize();
|
||||
expect(result).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Health Check', () => {
|
||||
test('should return true when Docker container is running', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
// Setup mock process
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emtest('data', Buffer.from('Up 2 hours'));
|
||||
mockProcess.stdout.emit('data', Buffer.from('Up 2 hours'));
|
||||
}, 0);
|
||||
|
||||
const result = await speechToText.checkHealth();
|
||||
@@ -83,23 +81,20 @@ describe('SpeechToText', () => {
|
||||
});
|
||||
|
||||
test('should return false when Docker container is not running', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(1), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
// Setup mock process
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emit('data', Buffer.from('No containers found'));
|
||||
}, 0);
|
||||
|
||||
const result = await speechToText.checkHealth();
|
||||
expect(result).toBe(false);
|
||||
});
|
||||
|
||||
test('should handle Docker command errors', async () => {
|
||||
spawnMock.mockImplementation(() => {
|
||||
throw new Error('Docker not found');
|
||||
});
|
||||
// Setup mock process
|
||||
setTimeout(() => {
|
||||
mockProcess.stderr.emit('data', Buffer.from('Docker error'));
|
||||
}, 0);
|
||||
|
||||
const result = await speechToText.checkHealth();
|
||||
expect(result).toBe(false);
|
||||
@@ -108,51 +103,48 @@ describe('SpeechToText', () => {
|
||||
|
||||
describe('Wake Word Detection', () => {
|
||||
test('should detect wake word and emit event', async () => {
|
||||
const testFile = path.join(testAudioDir, 'wake_word_test_123456.wav');
|
||||
const testMetadata = `${testFile}.json`;
|
||||
// Setup mock process
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emit('data', Buffer.from('Wake word detected'));
|
||||
}, 0);
|
||||
|
||||
return new Promise<void>((resolve) => {
|
||||
speechToText.startWakeWordDetection(testAudioDir);
|
||||
|
||||
speechToText.on('wake_word', (event: WakeWordEvent) => {
|
||||
expect(event).toBeDefined();
|
||||
expect(event.audioFile).toBe(testFile);
|
||||
expect(event.metadataFile).toBe(testMetadata);
|
||||
expect(event.timestamp).toBe('123456');
|
||||
const wakeWordPromise = new Promise<void>((resolve) => {
|
||||
speechToText.on('wake_word', () => {
|
||||
resolve();
|
||||
});
|
||||
|
||||
// Create a test audio file to trigger the event
|
||||
fs.writeFileSync(testFile, 'test audio content');
|
||||
});
|
||||
|
||||
speechToText.startWakeWordDetection();
|
||||
await wakeWordPromise;
|
||||
});
|
||||
|
||||
test('should handle non-wake-word files', async () => {
|
||||
const testFile = path.join(testAudioDir, 'regular_audio.wav');
|
||||
let eventEmitted = false;
|
||||
// Setup mock process
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emit('data', Buffer.from('Processing audio'));
|
||||
}, 0);
|
||||
|
||||
return new Promise<void>((resolve) => {
|
||||
speechToText.startWakeWordDetection(testAudioDir);
|
||||
|
||||
speechToText.on('wake_word', () => {
|
||||
eventEmitted = true;
|
||||
});
|
||||
|
||||
fs.writeFileSync(testFile, 'test audio content');
|
||||
|
||||
setTimeout(() => {
|
||||
expect(eventEmitted).toBe(false);
|
||||
const wakeWordPromise = new Promise<void>((resolve, reject) => {
|
||||
const timeout = setTimeout(() => {
|
||||
resolve();
|
||||
}, 100);
|
||||
|
||||
speechToText.on('wake_word', () => {
|
||||
clearTimeout(timeout);
|
||||
reject(new Error('Wake word should not be detected'));
|
||||
});
|
||||
});
|
||||
|
||||
speechToText.startWakeWordDetection();
|
||||
await wakeWordPromise;
|
||||
});
|
||||
});
|
||||
|
||||
describe('Audio Transcription', () => {
|
||||
const mockTranscriptionResult: TranscriptionResult = {
|
||||
text: 'Hello world',
|
||||
const mockTranscriptionResult = {
|
||||
text: 'Test transcription',
|
||||
segments: [{
|
||||
text: 'Hello world',
|
||||
text: 'Test transcription',
|
||||
start: 0,
|
||||
end: 1,
|
||||
confidence: 0.95
|
||||
@@ -160,169 +152,100 @@ describe('SpeechToText', () => {
|
||||
};
|
||||
|
||||
test('should transcribe audio successfully', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
const transcriptionPromise = speechToText.transcribeAudio('/test/audio.wav');
|
||||
|
||||
// Setup mock process
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emtest('data', Buffer.from(JSON.stringify(mockTranscriptionResult)));
|
||||
mockProcess.stdout.emit('data', Buffer.from(JSON.stringify(mockTranscriptionResult)));
|
||||
}, 0);
|
||||
|
||||
const result = await transcriptionPromise;
|
||||
const result = await speechToText.transcribeAudio('/test/audio.wav');
|
||||
expect(result).toEqual(mockTranscriptionResult);
|
||||
});
|
||||
|
||||
test('should handle transcription errors', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(1), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
const transcriptionPromise = speechToText.transcribeAudio('/test/audio.wav');
|
||||
|
||||
// Setup mock process
|
||||
setTimeout(() => {
|
||||
mockProcess.stderr.emtest('data', Buffer.from('Transcription failed'));
|
||||
mockProcess.stderr.emit('data', Buffer.from('Transcription failed'));
|
||||
}, 0);
|
||||
|
||||
await expect(transcriptionPromise).rejects.toThrow(TranscriptionError);
|
||||
await expect(speechToText.transcribeAudio('/test/audio.wav')).rejects.toThrow(TranscriptionError);
|
||||
});
|
||||
|
||||
test('should handle invalid JSON output', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
const transcriptionPromise = speechToText.transcribeAudio('/test/audio.wav');
|
||||
|
||||
// Setup mock process
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emtest('data', Buffer.from('Invalid JSON'));
|
||||
mockProcess.stdout.emit('data', Buffer.from('Invalid JSON'));
|
||||
}, 0);
|
||||
|
||||
await expect(transcriptionPromise).rejects.toThrow(TranscriptionError);
|
||||
await expect(speechToText.transcribeAudio('/test/audio.wav')).rejects.toThrow(TranscriptionError);
|
||||
});
|
||||
|
||||
test('should pass correct transcription options', async () => {
|
||||
const options: TranscriptionOptions = {
|
||||
model: 'large-v2',
|
||||
model: 'base.en',
|
||||
language: 'en',
|
||||
temperature: 0.5,
|
||||
beamSize: 3,
|
||||
patience: 2,
|
||||
device: 'cuda'
|
||||
temperature: 0,
|
||||
beamSize: 5,
|
||||
patience: 1,
|
||||
device: 'cpu'
|
||||
};
|
||||
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
await speechToText.transcribeAudio('/test/audio.wav', options);
|
||||
|
||||
const transcriptionPromise = speechToText.transcribeAudio('/test/audio.wav', options);
|
||||
|
||||
const expectedArgs = [
|
||||
'exec',
|
||||
mockConfig.containerName,
|
||||
'fast-whisper',
|
||||
'--model', options.model,
|
||||
'--language', options.language,
|
||||
'--temperature', String(options.temperature ?? 0),
|
||||
'--beam-size', String(options.beamSize ?? 5),
|
||||
'--patience', String(options.patience ?? 1),
|
||||
'--device', options.device
|
||||
].filter((arg): arg is string => arg !== undefined);
|
||||
|
||||
const mockCalls = spawnMock.mock.calls;
|
||||
expect(mockCalls.length).toBe(1);
|
||||
const [cmd, args] = mockCalls[0].args;
|
||||
expect(cmd).toBe('docker');
|
||||
expect(expectedArgs.every(arg => args.includes(arg))).toBe(true);
|
||||
|
||||
await transcriptionPromise.catch(() => { });
|
||||
const spawnArgs = spawnMock.mock.calls[0]?.args[1] || [];
|
||||
expect(spawnArgs).toContain('--model');
|
||||
expect(spawnArgs).toContain(options.model);
|
||||
expect(spawnArgs).toContain('--language');
|
||||
expect(spawnArgs).toContain(options.language);
|
||||
expect(spawnArgs).toContain('--temperature');
|
||||
expect(spawnArgs).toContain(options.temperature?.toString());
|
||||
expect(spawnArgs).toContain('--beam-size');
|
||||
expect(spawnArgs).toContain(options.beamSize?.toString());
|
||||
expect(spawnArgs).toContain('--patience');
|
||||
expect(spawnArgs).toContain(options.patience?.toString());
|
||||
expect(spawnArgs).toContain('--device');
|
||||
expect(spawnArgs).toContain(options.device);
|
||||
});
|
||||
});
|
||||
|
||||
describe('Event Handling', () => {
|
||||
test('should emit progress events', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
return new Promise<void>((resolve) => {
|
||||
const progressEvents: any[] = [];
|
||||
speechToText.on('progress', (event) => {
|
||||
progressEvents.push(event);
|
||||
if (progressEvents.length === 2) {
|
||||
expect(progressEvents).toEqual([
|
||||
{ type: 'stdout', data: 'Processing' },
|
||||
{ type: 'stderr', data: 'Loading model' }
|
||||
]);
|
||||
resolve();
|
||||
}
|
||||
const progressPromise = new Promise<void>((resolve) => {
|
||||
speechToText.on('progress', (progress) => {
|
||||
expect(progress).toEqual({ type: 'stdout', data: 'Processing' });
|
||||
resolve();
|
||||
});
|
||||
|
||||
void speechToText.transcribeAudio('/test/audio.wav');
|
||||
|
||||
mockProcess.stdout.emtest('data', Buffer.from('Processing'));
|
||||
mockProcess.stderr.emtest('data', Buffer.from('Loading model'));
|
||||
});
|
||||
|
||||
const transcribePromise = speechToText.transcribeAudio('/test/audio.wav');
|
||||
mockProcess.stdout.emit('data', Buffer.from('Processing'));
|
||||
await Promise.all([transcribePromise.catch(() => { }), progressPromise]);
|
||||
});
|
||||
|
||||
test('should emit error events', async () => {
|
||||
return new Promise<void>((resolve) => {
|
||||
const errorPromise = new Promise<void>((resolve) => {
|
||||
speechToText.on('error', (error) => {
|
||||
expect(error instanceof Error).toBe(true);
|
||||
expect(error.message).toBe('Test error');
|
||||
resolve();
|
||||
});
|
||||
|
||||
speechToText.emtest('error', new Error('Test error'));
|
||||
});
|
||||
|
||||
speechToText.emit('error', new Error('Test error'));
|
||||
await errorPromise;
|
||||
});
|
||||
});
|
||||
|
||||
describe('Cleanup', () => {
|
||||
test('should stop wake word detection', () => {
|
||||
speechToText.startWakeWordDetection(testAudioDir);
|
||||
speechToText.startWakeWordDetection();
|
||||
speechToText.stopWakeWordDetection();
|
||||
// Verify no more file watching events are processed
|
||||
const testFile = path.join(testAudioDir, 'wake_word_test_123456.wav');
|
||||
let eventEmitted = false;
|
||||
speechToText.on('wake_word', () => {
|
||||
eventEmitted = true;
|
||||
});
|
||||
fs.writeFileSync(testFile, 'test audio content');
|
||||
expect(eventEmitted).toBe(false);
|
||||
expect(mockProcess.kill.mock.calls.length).toBe(1);
|
||||
});
|
||||
|
||||
test('should clean up resources on shutdown', async () => {
|
||||
await speechToText.initialize();
|
||||
const shutdownSpy = spyOn(speechToText, 'shutdown');
|
||||
await speechToText.shutdown();
|
||||
expect(shutdownSpy).toHaveBeenCalled();
|
||||
expect(mockProcess.kill.mock.calls.length).toBe(1);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -1,120 +1,177 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
|
||||
import { HassWebSocketClient } from '../../src/websocket/client.js';
|
||||
import WebSocket from 'ws';
|
||||
import { EventEmitter } from 'events';
|
||||
import * as HomeAssistant from '../../src/types/hass.js';
|
||||
|
||||
// Mock WebSocket
|
||||
// // jest.mock('ws');
|
||||
import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
|
||||
import { EventEmitter } from "events";
|
||||
import { HassWebSocketClient } from "../../src/websocket/client";
|
||||
import type { MessageEvent, ErrorEvent } from "ws";
|
||||
import { Mock, fn as jestMock } from 'jest-mock';
|
||||
import { expect as jestExpect } from '@jest/globals';
|
||||
|
||||
describe('WebSocket Event Handling', () => {
|
||||
let client: HassWebSocketClient;
|
||||
let mockWebSocket: jest.Mocked<WebSocket>;
|
||||
let mockWebSocket: any;
|
||||
let onOpenCallback: () => void;
|
||||
let onCloseCallback: () => void;
|
||||
let onErrorCallback: (event: any) => void;
|
||||
let onMessageCallback: (event: any) => void;
|
||||
let eventEmitter: EventEmitter;
|
||||
|
||||
beforeEach(() => {
|
||||
// Clear all mocks
|
||||
jest.clearAllMocks();
|
||||
|
||||
// Create event emitter for mocking WebSocket events
|
||||
eventEmitter = new EventEmitter();
|
||||
|
||||
// Create mock WebSocket instance
|
||||
// Initialize callbacks first
|
||||
onOpenCallback = () => { };
|
||||
onCloseCallback = () => { };
|
||||
onErrorCallback = () => { };
|
||||
onMessageCallback = () => { };
|
||||
|
||||
mockWebSocket = {
|
||||
on: jest.fn((event: string, listener: (...args: any[]) => void) => {
|
||||
eventEmitter.on(event, listener);
|
||||
return mockWebSocket;
|
||||
}),
|
||||
send: mock(),
|
||||
close: mock(),
|
||||
readyState: WebSocket.OPEN,
|
||||
removeAllListeners: mock(),
|
||||
// Add required WebSocket properties
|
||||
binaryType: 'arraybuffer',
|
||||
bufferedAmount: 0,
|
||||
extensions: '',
|
||||
protocol: '',
|
||||
url: 'ws://test.com',
|
||||
isPaused: () => false,
|
||||
ping: mock(),
|
||||
pong: mock(),
|
||||
terminate: mock()
|
||||
} as unknown as jest.Mocked<WebSocket>;
|
||||
readyState: 1,
|
||||
OPEN: 1,
|
||||
onopen: null,
|
||||
onclose: null,
|
||||
onerror: null,
|
||||
onmessage: null
|
||||
};
|
||||
|
||||
// Mock WebSocket constructor
|
||||
(WebSocket as unknown as jest.Mock).mockImplementation(() => mockWebSocket);
|
||||
// Define setters that store the callbacks
|
||||
Object.defineProperties(mockWebSocket, {
|
||||
onopen: {
|
||||
get() { return onOpenCallback; },
|
||||
set(callback: () => void) { onOpenCallback = callback; }
|
||||
},
|
||||
onclose: {
|
||||
get() { return onCloseCallback; },
|
||||
set(callback: () => void) { onCloseCallback = callback; }
|
||||
},
|
||||
onerror: {
|
||||
get() { return onErrorCallback; },
|
||||
set(callback: (event: any) => void) { onErrorCallback = callback; }
|
||||
},
|
||||
onmessage: {
|
||||
get() { return onMessageCallback; },
|
||||
set(callback: (event: any) => void) { onMessageCallback = callback; }
|
||||
}
|
||||
});
|
||||
|
||||
// Create client instance
|
||||
client = new HassWebSocketClient('ws://test.com', 'test-token');
|
||||
// @ts-expect-error - Mock WebSocket implementation
|
||||
global.WebSocket = mock(() => mockWebSocket);
|
||||
|
||||
client = new HassWebSocketClient('ws://localhost:8123/api/websocket', 'test-token');
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
eventEmitter.removeAllListeners();
|
||||
client.disconnect();
|
||||
if (eventEmitter) {
|
||||
eventEmitter.removeAllListeners();
|
||||
}
|
||||
if (client) {
|
||||
client.disconnect();
|
||||
}
|
||||
});
|
||||
|
||||
test('should handle connection events', () => {
|
||||
// Simulate open event
|
||||
eventEmitter.emtest('open');
|
||||
|
||||
// Verify authentication message was sent
|
||||
expect(mockWebSocket.send).toHaveBeenCalledWith(
|
||||
expect.stringContaining('"type":"auth"')
|
||||
);
|
||||
test('should handle connection events', async () => {
|
||||
const connectPromise = client.connect();
|
||||
onOpenCallback();
|
||||
await connectPromise;
|
||||
expect(client.isConnected()).toBe(true);
|
||||
});
|
||||
|
||||
test('should handle authentication response', () => {
|
||||
// Simulate auth_ok message
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
test('should handle authentication response', async () => {
|
||||
const connectPromise = client.connect();
|
||||
onOpenCallback();
|
||||
|
||||
// Verify client is ready for commands
|
||||
expect(mockWebSocket.readyState).toBe(WebSocket.OPEN);
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_required'
|
||||
})
|
||||
});
|
||||
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_ok'
|
||||
})
|
||||
});
|
||||
|
||||
await connectPromise;
|
||||
expect(client.isAuthenticated()).toBe(true);
|
||||
});
|
||||
|
||||
test('should handle auth failure', () => {
|
||||
// Simulate auth_invalid message
|
||||
eventEmitter.emtest('message', JSON.stringify({
|
||||
type: 'auth_invalid',
|
||||
message: 'Invalid token'
|
||||
}));
|
||||
test('should handle auth failure', async () => {
|
||||
const connectPromise = client.connect();
|
||||
onOpenCallback();
|
||||
|
||||
// Verify client attempts to close connection
|
||||
expect(mockWebSocket.close).toHaveBeenCalled();
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_required'
|
||||
})
|
||||
});
|
||||
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_invalid',
|
||||
message: 'Invalid password'
|
||||
})
|
||||
});
|
||||
|
||||
await expect(connectPromise).rejects.toThrow('Authentication failed');
|
||||
expect(client.isAuthenticated()).toBe(false);
|
||||
});
|
||||
|
||||
test('should handle connection errors', () => {
|
||||
// Create error spy
|
||||
const errorSpy = mock();
|
||||
client.on('error', errorSpy);
|
||||
test('should handle connection errors', async () => {
|
||||
const errorPromise = new Promise((resolve) => {
|
||||
client.once('error', resolve);
|
||||
});
|
||||
|
||||
// Simulate error
|
||||
const testError = new Error('Test error');
|
||||
eventEmitter.emtest('error', testError);
|
||||
const connectPromise = client.connect().catch(() => { /* Expected error */ });
|
||||
onOpenCallback();
|
||||
|
||||
// Verify error was handled
|
||||
expect(errorSpy).toHaveBeenCalledWith(testError);
|
||||
const errorEvent = new Error('Connection failed');
|
||||
onErrorCallback({ error: errorEvent });
|
||||
|
||||
const error = await errorPromise;
|
||||
expect(error instanceof Error).toBe(true);
|
||||
expect((error as Error).message).toBe('Connection failed');
|
||||
});
|
||||
|
||||
test('should handle disconnection', () => {
|
||||
// Create close spy
|
||||
const closeSpy = mock();
|
||||
client.on('close', closeSpy);
|
||||
test('should handle disconnection', async () => {
|
||||
const connectPromise = client.connect();
|
||||
onOpenCallback();
|
||||
await connectPromise;
|
||||
|
||||
// Simulate close
|
||||
eventEmitter.emtest('close');
|
||||
const disconnectPromise = new Promise((resolve) => {
|
||||
client.on('disconnected', resolve);
|
||||
});
|
||||
|
||||
// Verify close was handled
|
||||
expect(closeSpy).toHaveBeenCalled();
|
||||
onCloseCallback();
|
||||
|
||||
await disconnectPromise;
|
||||
expect(client.isConnected()).toBe(false);
|
||||
});
|
||||
|
||||
test('should handle event messages', () => {
|
||||
// Create event spy
|
||||
const eventSpy = mock();
|
||||
client.on('event', eventSpy);
|
||||
test('should handle event messages', async () => {
|
||||
const connectPromise = client.connect();
|
||||
onOpenCallback();
|
||||
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_required'
|
||||
})
|
||||
});
|
||||
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_ok'
|
||||
})
|
||||
});
|
||||
|
||||
await connectPromise;
|
||||
|
||||
const eventPromise = new Promise((resolve) => {
|
||||
client.on('state_changed', resolve);
|
||||
});
|
||||
|
||||
// Simulate event message
|
||||
const eventData = {
|
||||
id: 1,
|
||||
type: 'event',
|
||||
event: {
|
||||
event_type: 'state_changed',
|
||||
@@ -124,217 +181,63 @@ describe('WebSocket Event Handling', () => {
|
||||
}
|
||||
}
|
||||
};
|
||||
eventEmitter.emtest('message', JSON.stringify(eventData));
|
||||
|
||||
// Verify event was handled
|
||||
expect(eventSpy).toHaveBeenCalledWith(eventData.event);
|
||||
onMessageCallback({
|
||||
data: JSON.stringify(eventData)
|
||||
});
|
||||
|
||||
const receivedEvent = await eventPromise;
|
||||
expect(receivedEvent).toEqual(eventData.event.data);
|
||||
});
|
||||
|
||||
describe('Connection Events', () => {
|
||||
test('should handle successful connection', (done) => {
|
||||
client.on('open', () => {
|
||||
expect(mockWebSocket.send).toHaveBeenCalled();
|
||||
done();
|
||||
});
|
||||
test('should subscribe to specific events', async () => {
|
||||
const connectPromise = client.connect();
|
||||
onOpenCallback();
|
||||
|
||||
eventEmitter.emtest('open');
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_required'
|
||||
})
|
||||
});
|
||||
|
||||
test('should handle connection errors', (done) => {
|
||||
const error = new Error('Connection failed');
|
||||
client.on('error', (err: Error) => {
|
||||
expect(err).toBe(error);
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emtest('error', error);
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_ok'
|
||||
})
|
||||
});
|
||||
|
||||
test('should handle connection close', (done) => {
|
||||
client.on('disconnected', () => {
|
||||
expect(mockWebSocket.close).toHaveBeenCalled();
|
||||
done();
|
||||
});
|
||||
await connectPromise;
|
||||
|
||||
eventEmitter.emtest('close');
|
||||
const subscriptionId = await client.subscribeEvents('state_changed', (data) => {
|
||||
// Empty callback for type satisfaction
|
||||
});
|
||||
expect(mockWebSocket.send).toHaveBeenCalled();
|
||||
expect(subscriptionId).toBeDefined();
|
||||
});
|
||||
|
||||
describe('Authentication', () => {
|
||||
test('should send authentication message on connect', () => {
|
||||
const authMessage: HomeAssistant.AuthMessage = {
|
||||
type: 'auth',
|
||||
access_token: 'test_token'
|
||||
};
|
||||
test('should unsubscribe from events', async () => {
|
||||
const connectPromise = client.connect();
|
||||
onOpenCallback();
|
||||
|
||||
client.connect();
|
||||
expect(mockWebSocket.send).toHaveBeenCalledWith(JSON.stringify(authMessage));
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_required'
|
||||
})
|
||||
});
|
||||
|
||||
test('should handle successful authentication', (done) => {
|
||||
client.on('auth_ok', () => {
|
||||
done();
|
||||
});
|
||||
|
||||
client.connect();
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
onMessageCallback({
|
||||
data: JSON.stringify({
|
||||
type: 'auth_ok'
|
||||
})
|
||||
});
|
||||
|
||||
test('should handle authentication failure', (done) => {
|
||||
client.on('auth_invalid', () => {
|
||||
done();
|
||||
});
|
||||
await connectPromise;
|
||||
|
||||
client.connect();
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'auth_invalid' }));
|
||||
const subscriptionId = await client.subscribeEvents('state_changed', (data) => {
|
||||
// Empty callback for type satisfaction
|
||||
});
|
||||
});
|
||||
await client.unsubscribeEvents(subscriptionId);
|
||||
|
||||
describe('Event Subscription', () => {
|
||||
test('should handle state changed events', (done) => {
|
||||
const stateEvent: HomeAssistant.StateChangedEvent = {
|
||||
event_type: 'state_changed',
|
||||
data: {
|
||||
entity_id: 'light.living_room',
|
||||
new_state: {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'on',
|
||||
attributes: { brightness: 255 },
|
||||
last_changed: '2024-01-01T00:00:00Z',
|
||||
last_updated: '2024-01-01T00:00:00Z',
|
||||
context: {
|
||||
id: '123',
|
||||
parent_id: null,
|
||||
user_id: null
|
||||
}
|
||||
},
|
||||
old_state: {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'off',
|
||||
attributes: {},
|
||||
last_changed: '2024-01-01T00:00:00Z',
|
||||
last_updated: '2024-01-01T00:00:00Z',
|
||||
context: {
|
||||
id: '122',
|
||||
parent_id: null,
|
||||
user_id: null
|
||||
}
|
||||
}
|
||||
},
|
||||
origin: 'LOCAL',
|
||||
time_fired: '2024-01-01T00:00:00Z',
|
||||
context: {
|
||||
id: '123',
|
||||
parent_id: null,
|
||||
user_id: null
|
||||
}
|
||||
};
|
||||
|
||||
client.on('event', (event) => {
|
||||
expect(event.data.entity_id).toBe('light.living_room');
|
||||
expect(event.data.new_state.state).toBe('on');
|
||||
expect(event.data.old_state.state).toBe('off');
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'event', event: stateEvent }));
|
||||
});
|
||||
|
||||
test('should subscribe to specific events', async () => {
|
||||
const subscriptionId = 1;
|
||||
const callback = mock();
|
||||
|
||||
// Mock successful subscription
|
||||
const subscribePromise = client.subscribeEvents('state_changed', callback);
|
||||
eventEmitter.emtest('message', JSON.stringify({
|
||||
id: 1,
|
||||
type: 'result',
|
||||
success: true
|
||||
}));
|
||||
|
||||
await expect(subscribePromise).resolves.toBe(subscriptionId);
|
||||
|
||||
// Test event handling
|
||||
const eventData = {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'on'
|
||||
};
|
||||
eventEmitter.emtest('message', JSON.stringify({
|
||||
type: 'event',
|
||||
event: {
|
||||
event_type: 'state_changed',
|
||||
data: eventData
|
||||
}
|
||||
}));
|
||||
|
||||
expect(callback).toHaveBeenCalledWith(eventData);
|
||||
});
|
||||
|
||||
test('should unsubscribe from events', async () => {
|
||||
// First subscribe
|
||||
const subscriptionId = await client.subscribeEvents('state_changed', () => { });
|
||||
|
||||
// Then unsubscribe
|
||||
const unsubscribePromise = client.unsubscribeEvents(subscriptionId);
|
||||
eventEmitter.emtest('message', JSON.stringify({
|
||||
id: 2,
|
||||
type: 'result',
|
||||
success: true
|
||||
}));
|
||||
|
||||
await expect(unsubscribePromise).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Message Handling', () => {
|
||||
test('should handle malformed messages', (done) => {
|
||||
client.on('error', (error: Error) => {
|
||||
expect(error.message).toContain('Unexpected token');
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emtest('message', 'invalid json');
|
||||
});
|
||||
|
||||
test('should handle unknown message types', (done) => {
|
||||
const unknownMessage = {
|
||||
type: 'unknown_type',
|
||||
data: {}
|
||||
};
|
||||
|
||||
client.on('error', (error: Error) => {
|
||||
expect(error.message).toContain('Unknown message type');
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emtest('message', JSON.stringify(unknownMessage));
|
||||
});
|
||||
});
|
||||
|
||||
describe('Reconnection', () => {
|
||||
test('should attempt to reconnect on connection loss', (done) => {
|
||||
let reconnectAttempts = 0;
|
||||
client.on('disconnected', () => {
|
||||
reconnectAttempts++;
|
||||
if (reconnectAttempts === 1) {
|
||||
expect(WebSocket).toHaveBeenCalledTimes(2);
|
||||
done();
|
||||
}
|
||||
});
|
||||
|
||||
eventEmitter.emtest('close');
|
||||
});
|
||||
|
||||
test('should re-authenticate after reconnection', (done) => {
|
||||
client.connect();
|
||||
|
||||
client.on('auth_ok', () => {
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emtest('close');
|
||||
eventEmitter.emtest('open');
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
});
|
||||
expect(mockWebSocket.send).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
604
bun.lock
604
bun.lock
@@ -1,604 +0,0 @@
|
||||
{
|
||||
"lockfileVersion": 1,
|
||||
"workspaces": {
|
||||
"": {
|
||||
"dependencies": {
|
||||
"@elysiajs/cors": "^1.2.0",
|
||||
"@elysiajs/swagger": "^1.2.0",
|
||||
"@types/jsonwebtoken": "^9.0.5",
|
||||
"@types/node": "^20.11.24",
|
||||
"@types/sanitize-html": "^2.9.5",
|
||||
"@types/ws": "^8.5.10",
|
||||
"@xmldom/xmldom": "^0.9.7",
|
||||
"dotenv": "^16.4.5",
|
||||
"elysia": "^1.2.11",
|
||||
"helmet": "^7.1.0",
|
||||
"jsonwebtoken": "^9.0.2",
|
||||
"node-fetch": "^3.3.2",
|
||||
"openai": "^4.82.0",
|
||||
"sanitize-html": "^2.11.0",
|
||||
"typescript": "^5.3.3",
|
||||
"winston": "^3.11.0",
|
||||
"winston-daily-rotate-file": "^5.0.0",
|
||||
"ws": "^8.16.0",
|
||||
"zod": "^3.22.4",
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/uuid": "^10.0.0",
|
||||
"@typescript-eslint/eslint-plugin": "^7.1.0",
|
||||
"@typescript-eslint/parser": "^7.1.0",
|
||||
"bun-types": "^1.2.2",
|
||||
"eslint": "^8.57.0",
|
||||
"eslint-config-prettier": "^9.1.0",
|
||||
"eslint-plugin-prettier": "^5.1.3",
|
||||
"husky": "^9.0.11",
|
||||
"prettier": "^3.2.5",
|
||||
"supertest": "^6.3.3",
|
||||
"uuid": "^11.0.5",
|
||||
},
|
||||
},
|
||||
},
|
||||
"packages": {
|
||||
"@colors/colors": ["@colors/colors@1.6.0", "", {}, "sha512-Ir+AOibqzrIsL6ajt3Rz3LskB7OiMVHqltZmspbW/TJuTVuyOMirVqAkjfY6JISiLHgyNqicAC8AyHHGzNd/dA=="],
|
||||
|
||||
"@dabh/diagnostics": ["@dabh/diagnostics@2.0.3", "", { "dependencies": { "colorspace": "1.1.x", "enabled": "2.0.x", "kuler": "^2.0.0" } }, "sha512-hrlQOIi7hAfzsMqlGSFyVucrx38O+j6wiGOf//H2ecvIEqYN4ADBSS2iLMh5UFyDunCNniUIPk/q3riFv45xRA=="],
|
||||
|
||||
"@elysiajs/cors": ["@elysiajs/cors@1.2.0", "", { "peerDependencies": { "elysia": ">= 1.2.0" } }, "sha512-qsJwDAg6WfdQRMfj6uSMcDPSpXvm/zQFeAX1uuJXhIgazH8itSfcDxcH9pMuXVRX1yQNi2pPwNQLJmAcw5mzvw=="],
|
||||
|
||||
"@elysiajs/swagger": ["@elysiajs/swagger@1.2.0", "", { "dependencies": { "@scalar/themes": "^0.9.52", "@scalar/types": "^0.0.12", "openapi-types": "^12.1.3", "pathe": "^1.1.2" }, "peerDependencies": { "elysia": ">= 1.2.0" } }, "sha512-OPx93DP6rM2VHjA3D44Xiz5MYm9AYlO2NGWPsnSsdyvaOCiL9wJj529583h7arX4iIEYE5LiLB0/A45unqbopw=="],
|
||||
|
||||
"@eslint-community/eslint-utils": ["@eslint-community/eslint-utils@4.4.1", "", { "dependencies": { "eslint-visitor-keys": "^3.4.3" }, "peerDependencies": { "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0" } }, "sha512-s3O3waFUrMV8P/XaF/+ZTp1X9XBZW1a4B97ZnjQF2KYWaFD2A8KyFBsrsfSjEmjn3RGWAIuvlneuZm3CUK3jbA=="],
|
||||
|
||||
"@eslint-community/regexpp": ["@eslint-community/regexpp@4.12.1", "", {}, "sha512-CCZCDJuduB9OUkFkY2IgppNZMi2lBQgD2qzwXkEia16cge2pijY/aXi96CJMquDMn3nJdlPV1A5KrJEXwfLNzQ=="],
|
||||
|
||||
"@eslint/eslintrc": ["@eslint/eslintrc@2.1.4", "", { "dependencies": { "ajv": "^6.12.4", "debug": "^4.3.2", "espree": "^9.6.0", "globals": "^13.19.0", "ignore": "^5.2.0", "import-fresh": "^3.2.1", "js-yaml": "^4.1.0", "minimatch": "^3.1.2", "strip-json-comments": "^3.1.1" } }, "sha512-269Z39MS6wVJtsoUl10L60WdkhJVdPG24Q4eZTH3nnF6lpvSShEK3wQjDX9JRWAUPvPh7COouPpU9IrqaZFvtQ=="],
|
||||
|
||||
"@eslint/js": ["@eslint/js@8.57.1", "", {}, "sha512-d9zaMRSTIKDLhctzH12MtXvJKSSUhaHcjV+2Z+GK+EEY7XKpP5yR4x+N3TAcHTcu963nIr+TMcCb4DBCYX1z6Q=="],
|
||||
|
||||
"@humanwhocodes/config-array": ["@humanwhocodes/config-array@0.13.0", "", { "dependencies": { "@humanwhocodes/object-schema": "^2.0.3", "debug": "^4.3.1", "minimatch": "^3.0.5" } }, "sha512-DZLEEqFWQFiyK6h5YIeynKx7JlvCYWL0cImfSRXZ9l4Sg2efkFGTuFf6vzXjK1cq6IYkU+Eg/JizXw+TD2vRNw=="],
|
||||
|
||||
"@humanwhocodes/module-importer": ["@humanwhocodes/module-importer@1.0.1", "", {}, "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA=="],
|
||||
|
||||
"@humanwhocodes/object-schema": ["@humanwhocodes/object-schema@2.0.3", "", {}, "sha512-93zYdMES/c1D69yZiKDBj0V24vqNzB/koF26KPaagAfd3P/4gUlh3Dys5ogAK+Exi9QyzlD8x/08Zt7wIKcDcA=="],
|
||||
|
||||
"@nodelib/fs.scandir": ["@nodelib/fs.scandir@2.1.5", "", { "dependencies": { "@nodelib/fs.stat": "2.0.5", "run-parallel": "^1.1.9" } }, "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g=="],
|
||||
|
||||
"@nodelib/fs.stat": ["@nodelib/fs.stat@2.0.5", "", {}, "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A=="],
|
||||
|
||||
"@nodelib/fs.walk": ["@nodelib/fs.walk@1.2.8", "", { "dependencies": { "@nodelib/fs.scandir": "2.1.5", "fastq": "^1.6.0" } }, "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg=="],
|
||||
|
||||
"@pkgr/core": ["@pkgr/core@0.1.1", "", {}, "sha512-cq8o4cWH0ibXh9VGi5P20Tu9XF/0fFXl9EUinr9QfTM7a7p0oTA4iJRCQWppXR1Pg8dSM0UCItCkPwsk9qWWYA=="],
|
||||
|
||||
"@scalar/openapi-types": ["@scalar/openapi-types@0.1.1", "", {}, "sha512-NMy3QNk6ytcCoPUGJH0t4NNr36OWXgZhA3ormr3TvhX1NDgoF95wFyodGVH8xiHeUyn2/FxtETm8UBLbB5xEmg=="],
|
||||
|
||||
"@scalar/themes": ["@scalar/themes@0.9.64", "", { "dependencies": { "@scalar/types": "0.0.30" } }, "sha512-hr9bCTdH9M/N8w31Td+IJVtbH+v0Ej31myW8QWhUfwYZe5qS815Tl1mp+qWFaObstOw5VX3zOtiZuuhF1zMIyw=="],
|
||||
|
||||
"@scalar/types": ["@scalar/types@0.0.12", "", { "dependencies": { "@scalar/openapi-types": "0.1.1", "@unhead/schema": "^1.9.5" } }, "sha512-XYZ36lSEx87i4gDqopQlGCOkdIITHHEvgkuJFrXFATQs9zHARop0PN0g4RZYWj+ZpCUclOcaOjbCt8JGe22mnQ=="],
|
||||
|
||||
"@sinclair/typebox": ["@sinclair/typebox@0.34.15", "", {}, "sha512-xeIzl3h1Znn9w/LTITqpiwag0gXjA+ldi2ZkXIBxGEppGCW211Tza+eL6D4pKqs10bj5z2umBWk5WL6spQ2OCQ=="],
|
||||
|
||||
"@types/jsonwebtoken": ["@types/jsonwebtoken@9.0.8", "", { "dependencies": { "@types/ms": "*", "@types/node": "*" } }, "sha512-7fx54m60nLFUVYlxAB1xpe9CBWX2vSrk50Y6ogRJ1v5xxtba7qXTg5BgYDN5dq+yuQQ9HaVlHJyAAt1/mxryFg=="],
|
||||
|
||||
"@types/ms": ["@types/ms@2.1.0", "", {}, "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA=="],
|
||||
|
||||
"@types/node": ["@types/node@20.17.17", "", { "dependencies": { "undici-types": "~6.19.2" } }, "sha512-/WndGO4kIfMicEQLTi/mDANUu/iVUhT7KboZPdEqqHQ4aTS+3qT3U5gIqWDFV+XouorjfgGqvKILJeHhuQgFYg=="],
|
||||
|
||||
"@types/node-fetch": ["@types/node-fetch@2.6.12", "", { "dependencies": { "@types/node": "*", "form-data": "^4.0.0" } }, "sha512-8nneRWKCg3rMtF69nLQJnOYUcbafYeFSjqkw3jCRLsqkWFlHaoQrr5mXmofFGOx3DKn7UfmBMyov8ySvLRVldA=="],
|
||||
|
||||
"@types/sanitize-html": ["@types/sanitize-html@2.13.0", "", { "dependencies": { "htmlparser2": "^8.0.0" } }, "sha512-X31WxbvW9TjIhZZNyNBZ/p5ax4ti7qsNDBDEnH4zAgmEh35YnFD1UiS6z9Cd34kKm0LslFW0KPmTQzu/oGtsqQ=="],
|
||||
|
||||
"@types/triple-beam": ["@types/triple-beam@1.3.5", "", {}, "sha512-6WaYesThRMCl19iryMYP7/x2OVgCtbIVflDGFpWnb9irXI3UjYE4AzmYuiUKY1AJstGijoY+MgUszMgRxIYTYw=="],
|
||||
|
||||
"@types/uuid": ["@types/uuid@10.0.0", "", {}, "sha512-7gqG38EyHgyP1S+7+xomFtL+ZNHcKv6DwNaCZmJmo1vgMugyF3TCnXVg4t1uk89mLNwnLtnY3TpOpCOyp1/xHQ=="],
|
||||
|
||||
"@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
|
||||
|
||||
"@typescript-eslint/eslint-plugin": ["@typescript-eslint/eslint-plugin@7.18.0", "", { "dependencies": { "@eslint-community/regexpp": "^4.10.0", "@typescript-eslint/scope-manager": "7.18.0", "@typescript-eslint/type-utils": "7.18.0", "@typescript-eslint/utils": "7.18.0", "@typescript-eslint/visitor-keys": "7.18.0", "graphemer": "^1.4.0", "ignore": "^5.3.1", "natural-compare": "^1.4.0", "ts-api-utils": "^1.3.0" }, "peerDependencies": { "@typescript-eslint/parser": "^7.0.0", "eslint": "^8.56.0" } }, "sha512-94EQTWZ40mzBc42ATNIBimBEDltSJ9RQHCC8vc/PDbxi4k8dVwUAv4o98dk50M1zB+JGFxp43FP7f8+FP8R6Sw=="],
|
||||
|
||||
"@typescript-eslint/parser": ["@typescript-eslint/parser@7.18.0", "", { "dependencies": { "@typescript-eslint/scope-manager": "7.18.0", "@typescript-eslint/types": "7.18.0", "@typescript-eslint/typescript-estree": "7.18.0", "@typescript-eslint/visitor-keys": "7.18.0", "debug": "^4.3.4" }, "peerDependencies": { "eslint": "^8.56.0" } }, "sha512-4Z+L8I2OqhZV8qA132M4wNL30ypZGYOQVBfMgxDH/K5UX0PNqTu1c6za9ST5r9+tavvHiTWmBnKzpCJ/GlVFtg=="],
|
||||
|
||||
"@typescript-eslint/scope-manager": ["@typescript-eslint/scope-manager@7.18.0", "", { "dependencies": { "@typescript-eslint/types": "7.18.0", "@typescript-eslint/visitor-keys": "7.18.0" } }, "sha512-jjhdIE/FPF2B7Z1uzc6i3oWKbGcHb87Qw7AWj6jmEqNOfDFbJWtjt/XfwCpvNkpGWlcJaog5vTR+VV8+w9JflA=="],
|
||||
|
||||
"@typescript-eslint/type-utils": ["@typescript-eslint/type-utils@7.18.0", "", { "dependencies": { "@typescript-eslint/typescript-estree": "7.18.0", "@typescript-eslint/utils": "7.18.0", "debug": "^4.3.4", "ts-api-utils": "^1.3.0" }, "peerDependencies": { "eslint": "^8.56.0" } }, "sha512-XL0FJXuCLaDuX2sYqZUUSOJ2sG5/i1AAze+axqmLnSkNEVMVYLF+cbwlB2w8D1tinFuSikHmFta+P+HOofrLeA=="],
|
||||
|
||||
"@typescript-eslint/types": ["@typescript-eslint/types@7.18.0", "", {}, "sha512-iZqi+Ds1y4EDYUtlOOC+aUmxnE9xS/yCigkjA7XpTKV6nCBd3Hp/PRGGmdwnfkV2ThMyYldP1wRpm/id99spTQ=="],
|
||||
|
||||
"@typescript-eslint/typescript-estree": ["@typescript-eslint/typescript-estree@7.18.0", "", { "dependencies": { "@typescript-eslint/types": "7.18.0", "@typescript-eslint/visitor-keys": "7.18.0", "debug": "^4.3.4", "globby": "^11.1.0", "is-glob": "^4.0.3", "minimatch": "^9.0.4", "semver": "^7.6.0", "ts-api-utils": "^1.3.0" } }, "sha512-aP1v/BSPnnyhMHts8cf1qQ6Q1IFwwRvAQGRvBFkWlo3/lH29OXA3Pts+c10nxRxIBrDnoMqzhgdwVe5f2D6OzA=="],
|
||||
|
||||
"@typescript-eslint/utils": ["@typescript-eslint/utils@7.18.0", "", { "dependencies": { "@eslint-community/eslint-utils": "^4.4.0", "@typescript-eslint/scope-manager": "7.18.0", "@typescript-eslint/types": "7.18.0", "@typescript-eslint/typescript-estree": "7.18.0" }, "peerDependencies": { "eslint": "^8.56.0" } }, "sha512-kK0/rNa2j74XuHVcoCZxdFBMF+aq/vH83CXAOHieC+2Gis4mF8jJXT5eAfyD3K0sAxtPuwxaIOIOvhwzVDt/kw=="],
|
||||
|
||||
"@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@7.18.0", "", { "dependencies": { "@typescript-eslint/types": "7.18.0", "eslint-visitor-keys": "^3.4.3" } }, "sha512-cDF0/Gf81QpY3xYyJKDV14Zwdmid5+uuENhjH2EqFaF0ni+yAyq/LzMaIJdhNJXZI7uLzwIlA+V7oWoyn6Curg=="],
|
||||
|
||||
"@ungap/structured-clone": ["@ungap/structured-clone@1.3.0", "", {}, "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g=="],
|
||||
|
||||
"@unhead/schema": ["@unhead/schema@1.11.18", "", { "dependencies": { "hookable": "^5.5.3", "zhead": "^2.2.4" } }, "sha512-a3TA/OJCRdfbFhcA3Hq24k1ZU1o9szicESrw8DZcGyQFacHnh84mVgnyqSkMnwgCmfN4kvjSiTBlLEHS6+wATw=="],
|
||||
|
||||
"@xmldom/xmldom": ["@xmldom/xmldom@0.9.7", "", {}, "sha512-syvR8iIJjpTZ/stv7l89UAViwGFh6lbheeOaqSxkYx9YNmIVvPTRH+CT/fpykFtUx5N+8eSMDRvggF9J8GEPzQ=="],
|
||||
|
||||
"abort-controller": ["abort-controller@3.0.0", "", { "dependencies": { "event-target-shim": "^5.0.0" } }, "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg=="],
|
||||
|
||||
"acorn": ["acorn@8.14.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-cl669nCJTZBsL97OF4kUQm5g5hC2uihk0NxY3WENAC0TYdILVkAyHymAntgxGkl7K+t0cXIrH5siy5S4XkFycA=="],
|
||||
|
||||
"acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
|
||||
|
||||
"agentkeepalive": ["agentkeepalive@4.6.0", "", { "dependencies": { "humanize-ms": "^1.2.1" } }, "sha512-kja8j7PjmncONqaTsB8fQ+wE2mSU2DJ9D4XKoJ5PFWIdRMa6SLSN1ff4mOr4jCbfRSsxR4keIiySJU0N9T5hIQ=="],
|
||||
|
||||
"ajv": ["ajv@6.12.6", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g=="],
|
||||
|
||||
"ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
|
||||
|
||||
"ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
|
||||
|
||||
"argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
|
||||
|
||||
"array-union": ["array-union@2.1.0", "", {}, "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw=="],
|
||||
|
||||
"asap": ["asap@2.0.6", "", {}, "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA=="],
|
||||
|
||||
"async": ["async@3.2.6", "", {}, "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA=="],
|
||||
|
||||
"asynckit": ["asynckit@0.4.0", "", {}, "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q=="],
|
||||
|
||||
"balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],
|
||||
|
||||
"brace-expansion": ["brace-expansion@1.1.11", "", { "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" } }, "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA=="],
|
||||
|
||||
"braces": ["braces@3.0.3", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="],
|
||||
|
||||
"buffer-equal-constant-time": ["buffer-equal-constant-time@1.0.1", "", {}, "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA=="],
|
||||
|
||||
"bun-types": ["bun-types@1.2.2", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-RCbMH5elr9gjgDGDhkTTugA21XtJAy/9jkKe/G3WR2q17VPGhcquf9Sir6uay9iW+7P/BV0CAHA1XlHXMAVKHg=="],
|
||||
|
||||
"call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.1", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-BhYE+WDaywFg2TBWYNXAE+8B1ATnThNBqXHP5nQu0jWJdVvY2hvkpyB3qOmtmDePiS5/BDQ8wASEWGMWRG148g=="],
|
||||
|
||||
"call-bound": ["call-bound@1.0.3", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "get-intrinsic": "^1.2.6" } }, "sha512-YTd+6wGlNlPxSuri7Y6X8tY2dmm12UMH66RpKMhiX6rsk5wXXnYgbUcOt8kiS31/AjfoTOvCsE+w8nZQLQnzHA=="],
|
||||
|
||||
"callsites": ["callsites@3.1.0", "", {}, "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ=="],
|
||||
|
||||
"chalk": ["chalk@4.1.2", "", { "dependencies": { "ansi-styles": "^4.1.0", "supports-color": "^7.1.0" } }, "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA=="],
|
||||
|
||||
"color": ["color@3.2.1", "", { "dependencies": { "color-convert": "^1.9.3", "color-string": "^1.6.0" } }, "sha512-aBl7dZI9ENN6fUGC7mWpMTPNHmWUSNan9tuWN6ahh5ZLNk9baLJOnSMlrQkHcrfFgz2/RigjUVAjdx36VcemKA=="],
|
||||
|
||||
"color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
|
||||
|
||||
"color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
|
||||
|
||||
"color-string": ["color-string@1.9.1", "", { "dependencies": { "color-name": "^1.0.0", "simple-swizzle": "^0.2.2" } }, "sha512-shrVawQFojnZv6xM40anx4CkoDP+fZsw/ZerEMsW/pyzsRbElpsL/DBVW7q3ExxwusdNXI3lXpuhEZkzs8p5Eg=="],
|
||||
|
||||
"colorspace": ["colorspace@1.1.4", "", { "dependencies": { "color": "^3.1.3", "text-hex": "1.0.x" } }, "sha512-BgvKJiuVu1igBUF2kEjRCZXol6wiiGbY5ipL/oVPwm0BL9sIpMIzM8IK7vwuxIIzOXMV3Ey5w+vxhm0rR/TN8w=="],
|
||||
|
||||
"combined-stream": ["combined-stream@1.0.8", "", { "dependencies": { "delayed-stream": "~1.0.0" } }, "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg=="],
|
||||
|
||||
"component-emitter": ["component-emitter@1.3.1", "", {}, "sha512-T0+barUSQRTUQASh8bx02dl+DhF54GtIDY13Y3m9oWTklKbb3Wv974meRpeZ3lp1JpLVECWWNHC4vaG2XHXouQ=="],
|
||||
|
||||
"concat-map": ["concat-map@0.0.1", "", {}, "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg=="],
|
||||
|
||||
"cookie": ["cookie@1.0.2", "", {}, "sha512-9Kr/j4O16ISv8zBBhJoi4bXOYNTkFLOqSL3UDB0njXxCXNezjeyVrJyGOWtgfs/q2km1gwBcfH8q1yEGoMYunA=="],
|
||||
|
||||
"cookiejar": ["cookiejar@2.1.4", "", {}, "sha512-LDx6oHrK+PhzLKJU9j5S7/Y3jM/mUHvD/DeI1WQmJn652iPC5Y4TBzC9l+5OMOXlyTTA+SmVUPm0HQUwpD5Jqw=="],
|
||||
|
||||
"cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
|
||||
|
||||
"data-uri-to-buffer": ["data-uri-to-buffer@4.0.1", "", {}, "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A=="],
|
||||
|
||||
"debug": ["debug@4.4.0", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA=="],
|
||||
|
||||
"deep-is": ["deep-is@0.1.4", "", {}, "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ=="],
|
||||
|
||||
"deepmerge": ["deepmerge@4.3.1", "", {}, "sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A=="],
|
||||
|
||||
"delayed-stream": ["delayed-stream@1.0.0", "", {}, "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ=="],
|
||||
|
||||
"dezalgo": ["dezalgo@1.0.4", "", { "dependencies": { "asap": "^2.0.0", "wrappy": "1" } }, "sha512-rXSP0bf+5n0Qonsb+SVVfNfIsimO4HEtmnIpPHY8Q1UCzKlQrDMfdobr8nJOOsRgWCyMRqeSBQzmWUMq7zvVig=="],
|
||||
|
||||
"dir-glob": ["dir-glob@3.0.1", "", { "dependencies": { "path-type": "^4.0.0" } }, "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA=="],
|
||||
|
||||
"doctrine": ["doctrine@3.0.0", "", { "dependencies": { "esutils": "^2.0.2" } }, "sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w=="],
|
||||
|
||||
"dom-serializer": ["dom-serializer@2.0.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.2", "entities": "^4.2.0" } }, "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg=="],
|
||||
|
||||
"domelementtype": ["domelementtype@2.3.0", "", {}, "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw=="],
|
||||
|
||||
"domhandler": ["domhandler@5.0.3", "", { "dependencies": { "domelementtype": "^2.3.0" } }, "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w=="],
|
||||
|
||||
"domutils": ["domutils@3.2.2", "", { "dependencies": { "dom-serializer": "^2.0.0", "domelementtype": "^2.3.0", "domhandler": "^5.0.3" } }, "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw=="],
|
||||
|
||||
"dotenv": ["dotenv@16.4.7", "", {}, "sha512-47qPchRCykZC03FhkYAhrvwU4xDBFIj1QPqaarj6mdM/hgUzfPHcpkHJOn3mJAufFeeAxAzeGsr5X0M4k6fLZQ=="],
|
||||
|
||||
"dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
|
||||
|
||||
"ecdsa-sig-formatter": ["ecdsa-sig-formatter@1.0.11", "", { "dependencies": { "safe-buffer": "^5.0.1" } }, "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ=="],
|
||||
|
||||
"elysia": ["elysia@1.2.12", "", { "dependencies": { "@sinclair/typebox": "^0.34.15", "cookie": "^1.0.2", "memoirist": "^0.3.0", "openapi-types": "^12.1.3" }, "peerDependencies": { "typescript": ">= 5.0.0" }, "optionalPeers": ["typescript"] }, "sha512-X1bZo09qe8/Poa/5tz08Y+sE/77B/wLwnA5xDDENU3FCrsUtYJuBVcy6BPXGRCgnJ1fPQpc0Ov2ZU5MYJXluTg=="],
|
||||
|
||||
"enabled": ["enabled@2.0.0", "", {}, "sha512-AKrN98kuwOzMIdAizXGI86UFBoo26CL21UM763y1h/GMSJ4/OHU9k2YlsmBpyScFo/wbLzWQJBMCW4+IO3/+OQ=="],
|
||||
|
||||
"entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
|
||||
|
||||
"es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
|
||||
|
||||
"es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
|
||||
|
||||
"es-object-atoms": ["es-object-atoms@1.1.1", "", { "dependencies": { "es-errors": "^1.3.0" } }, "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA=="],
|
||||
|
||||
"escape-string-regexp": ["escape-string-regexp@4.0.0", "", {}, "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="],
|
||||
|
||||
"eslint": ["eslint@8.57.1", "", { "dependencies": { "@eslint-community/eslint-utils": "^4.2.0", "@eslint-community/regexpp": "^4.6.1", "@eslint/eslintrc": "^2.1.4", "@eslint/js": "8.57.1", "@humanwhocodes/config-array": "^0.13.0", "@humanwhocodes/module-importer": "^1.0.1", "@nodelib/fs.walk": "^1.2.8", "@ungap/structured-clone": "^1.2.0", "ajv": "^6.12.4", "chalk": "^4.0.0", "cross-spawn": "^7.0.2", "debug": "^4.3.2", "doctrine": "^3.0.0", "escape-string-regexp": "^4.0.0", "eslint-scope": "^7.2.2", "eslint-visitor-keys": "^3.4.3", "espree": "^9.6.1", "esquery": "^1.4.2", "esutils": "^2.0.2", "fast-deep-equal": "^3.1.3", "file-entry-cache": "^6.0.1", "find-up": "^5.0.0", "glob-parent": "^6.0.2", "globals": "^13.19.0", "graphemer": "^1.4.0", "ignore": "^5.2.0", "imurmurhash": "^0.1.4", "is-glob": "^4.0.0", "is-path-inside": "^3.0.3", "js-yaml": "^4.1.0", "json-stable-stringify-without-jsonify": "^1.0.1", "levn": "^0.4.1", "lodash.merge": "^4.6.2", "minimatch": "^3.1.2", "natural-compare": "^1.4.0", "optionator": "^0.9.3", "strip-ansi": "^6.0.1", "text-table": "^0.2.0" }, "bin": { "eslint": "bin/eslint.js" } }, "sha512-ypowyDxpVSYpkXr9WPv2PAZCtNip1Mv5KTW0SCurXv/9iOpcrH9PaqUElksqEB6pChqHGDRCFTyrZlGhnLNGiA=="],
|
||||
|
||||
"eslint-config-prettier": ["eslint-config-prettier@9.1.0", "", { "peerDependencies": { "eslint": ">=7.0.0" }, "bin": { "eslint-config-prettier": "bin/cli.js" } }, "sha512-NSWl5BFQWEPi1j4TjVNItzYV7dZXZ+wP6I6ZhrBGpChQhZRUaElihE9uRRkcbRnNb76UMKDF3r+WTmNcGPKsqw=="],
|
||||
|
||||
"eslint-plugin-prettier": ["eslint-plugin-prettier@5.2.3", "", { "dependencies": { "prettier-linter-helpers": "^1.0.0", "synckit": "^0.9.1" }, "peerDependencies": { "@types/eslint": ">=8.0.0", "eslint": ">=8.0.0", "eslint-config-prettier": "*", "prettier": ">=3.0.0" }, "optionalPeers": ["@types/eslint", "eslint-config-prettier"] }, "sha512-qJ+y0FfCp/mQYQ/vWQ3s7eUlFEL4PyKfAJxsnYTJ4YT73nsJBWqmEpFryxV9OeUiqmsTsYJ5Y+KDNaeP31wrRw=="],
|
||||
|
||||
"eslint-scope": ["eslint-scope@7.2.2", "", { "dependencies": { "esrecurse": "^4.3.0", "estraverse": "^5.2.0" } }, "sha512-dOt21O7lTMhDM+X9mB4GX+DZrZtCUJPL/wlcTqxyrx5IvO0IYtILdtrQGQp+8n5S0gwSVmOf9NQrjMOgfQZlIg=="],
|
||||
|
||||
"eslint-visitor-keys": ["eslint-visitor-keys@3.4.3", "", {}, "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag=="],
|
||||
|
||||
"espree": ["espree@9.6.1", "", { "dependencies": { "acorn": "^8.9.0", "acorn-jsx": "^5.3.2", "eslint-visitor-keys": "^3.4.1" } }, "sha512-oruZaFkjorTpF32kDSI5/75ViwGeZginGGy2NoOSg3Q9bnwlnmDm4HLnkl0RE3n+njDXR037aY1+x58Z/zFdwQ=="],
|
||||
|
||||
"esquery": ["esquery@1.6.0", "", { "dependencies": { "estraverse": "^5.1.0" } }, "sha512-ca9pw9fomFcKPvFLXhBKUK90ZvGibiGOvRJNbjljY7s7uq/5YO4BOzcYtJqExdx99rF6aAcnRxHmcUHcz6sQsg=="],
|
||||
|
||||
"esrecurse": ["esrecurse@4.3.0", "", { "dependencies": { "estraverse": "^5.2.0" } }, "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag=="],
|
||||
|
||||
"estraverse": ["estraverse@5.3.0", "", {}, "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA=="],
|
||||
|
||||
"esutils": ["esutils@2.0.3", "", {}, "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g=="],
|
||||
|
||||
"event-target-shim": ["event-target-shim@5.0.1", "", {}, "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ=="],
|
||||
|
||||
"fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
|
||||
|
||||
"fast-diff": ["fast-diff@1.3.0", "", {}, "sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw=="],
|
||||
|
||||
"fast-glob": ["fast-glob@3.3.3", "", { "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", "glob-parent": "^5.1.2", "merge2": "^1.3.0", "micromatch": "^4.0.8" } }, "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg=="],
|
||||
|
||||
"fast-json-stable-stringify": ["fast-json-stable-stringify@2.1.0", "", {}, "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw=="],
|
||||
|
||||
"fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
|
||||
|
||||
"fast-safe-stringify": ["fast-safe-stringify@2.1.1", "", {}, "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA=="],
|
||||
|
||||
"fastq": ["fastq@1.19.0", "", { "dependencies": { "reusify": "^1.0.4" } }, "sha512-7SFSRCNjBQIZH/xZR3iy5iQYR8aGBE0h3VG6/cwlbrpdciNYBMotQav8c1XI3HjHH+NikUpP53nPdlZSdWmFzA=="],
|
||||
|
||||
"fecha": ["fecha@4.2.3", "", {}, "sha512-OP2IUU6HeYKJi3i0z4A19kHMQoLVs4Hc+DPqqxI2h/DPZHTm/vjsfC6P0b4jCMy14XizLBqvndQ+UilD7707Jw=="],
|
||||
|
||||
"fetch-blob": ["fetch-blob@3.2.0", "", { "dependencies": { "node-domexception": "^1.0.0", "web-streams-polyfill": "^3.0.3" } }, "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ=="],
|
||||
|
||||
"file-entry-cache": ["file-entry-cache@6.0.1", "", { "dependencies": { "flat-cache": "^3.0.4" } }, "sha512-7Gps/XWymbLk2QLYK4NzpMOrYjMhdIxXuIvy2QBsLE6ljuodKvdkWs/cpyJJ3CVIVpH0Oi1Hvg1ovbMzLdFBBg=="],
|
||||
|
||||
"file-stream-rotator": ["file-stream-rotator@0.6.1", "", { "dependencies": { "moment": "^2.29.1" } }, "sha512-u+dBid4PvZw17PmDeRcNOtCP9CCK/9lRN2w+r1xIS7yOL9JFrIBKTvrYsxT4P0pGtThYTn++QS5ChHaUov3+zQ=="],
|
||||
|
||||
"fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
|
||||
|
||||
"find-up": ["find-up@5.0.0", "", { "dependencies": { "locate-path": "^6.0.0", "path-exists": "^4.0.0" } }, "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng=="],
|
||||
|
||||
"flat-cache": ["flat-cache@3.2.0", "", { "dependencies": { "flatted": "^3.2.9", "keyv": "^4.5.3", "rimraf": "^3.0.2" } }, "sha512-CYcENa+FtcUKLmhhqyctpclsq7QF38pKjZHsGNiSQF5r4FtoKDWabFDl3hzaEQMvT1LHEysw5twgLvpYYb4vbw=="],
|
||||
|
||||
"flatted": ["flatted@3.3.2", "", {}, "sha512-AiwGJM8YcNOaobumgtng+6NHuOqC3A7MixFeDafM3X9cIUM+xUXoS5Vfgf+OihAYe20fxqNM9yPBXJzRtZ/4eA=="],
|
||||
|
||||
"fn.name": ["fn.name@1.1.0", "", {}, "sha512-GRnmB5gPyJpAhTQdSZTSp9uaPSvl09KoYcMQtsB9rQoOmzs9dH6ffeccH+Z+cv6P68Hu5bC6JjRh4Ah/mHSNRw=="],
|
||||
|
||||
"form-data": ["form-data@4.0.1", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "mime-types": "^2.1.12" } }, "sha512-tzN8e4TX8+kkxGPK8D5u0FNmjPUjw3lwC9lSLxxoB/+GtsJG91CO8bSWy73APlgAZzZbXEYZJuxjkHH2w+Ezhw=="],
|
||||
|
||||
"form-data-encoder": ["form-data-encoder@1.7.2", "", {}, "sha512-qfqtYan3rxrnCk1VYaA4H+Ms9xdpPqvLZa6xmMgFvhO32x7/3J/ExcTd6qpxM0vH2GdMI+poehyBZvqfMTto8A=="],
|
||||
|
||||
"formdata-node": ["formdata-node@4.4.1", "", { "dependencies": { "node-domexception": "1.0.0", "web-streams-polyfill": "4.0.0-beta.3" } }, "sha512-0iirZp3uVDjVGt9p49aTaqjk84TrglENEDuqfdlZQ1roC9CWlPk6Avf8EEnZNcAqPonwkG35x4n3ww/1THYAeQ=="],
|
||||
|
||||
"formdata-polyfill": ["formdata-polyfill@4.0.10", "", { "dependencies": { "fetch-blob": "^3.1.2" } }, "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g=="],
|
||||
|
||||
"formidable": ["formidable@2.1.2", "", { "dependencies": { "dezalgo": "^1.0.4", "hexoid": "^1.0.0", "once": "^1.4.0", "qs": "^6.11.0" } }, "sha512-CM3GuJ57US06mlpQ47YcunuUZ9jpm8Vx+P2CGt2j7HpgkKZO/DJYQ0Bobim8G6PFQmK5lOqOOdUXboU+h73A4g=="],
|
||||
|
||||
"fs.realpath": ["fs.realpath@1.0.0", "", {}, "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw=="],
|
||||
|
||||
"function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
|
||||
|
||||
"get-intrinsic": ["get-intrinsic@1.2.7", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.0.0", "function-bind": "^1.1.2", "get-proto": "^1.0.0", "gopd": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "math-intrinsics": "^1.1.0" } }, "sha512-VW6Pxhsrk0KAOqs3WEd0klDiF/+V7gQOpAvY1jVU/LHmaD/kQO4523aiJuikX/QAKYiW6x8Jh+RJej1almdtCA=="],
|
||||
|
||||
"get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
|
||||
|
||||
"glob": ["glob@7.2.3", "", { "dependencies": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", "inherits": "2", "minimatch": "^3.1.1", "once": "^1.3.0", "path-is-absolute": "^1.0.0" } }, "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q=="],
|
||||
|
||||
"glob-parent": ["glob-parent@6.0.2", "", { "dependencies": { "is-glob": "^4.0.3" } }, "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A=="],
|
||||
|
||||
"globals": ["globals@13.24.0", "", { "dependencies": { "type-fest": "^0.20.2" } }, "sha512-AhO5QUcj8llrbG09iWhPU2B204J1xnPeL8kQmVorSsy+Sjj1sk8gIyh6cUocGmH4L0UuhAJy+hJMRA4mgA4mFQ=="],
|
||||
|
||||
"globby": ["globby@11.1.0", "", { "dependencies": { "array-union": "^2.1.0", "dir-glob": "^3.0.1", "fast-glob": "^3.2.9", "ignore": "^5.2.0", "merge2": "^1.4.1", "slash": "^3.0.0" } }, "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g=="],
|
||||
|
||||
"gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
|
||||
|
||||
"graphemer": ["graphemer@1.4.0", "", {}, "sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag=="],
|
||||
|
||||
"has-flag": ["has-flag@4.0.0", "", {}, "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ=="],
|
||||
|
||||
"has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
|
||||
|
||||
"hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
|
||||
|
||||
"helmet": ["helmet@7.2.0", "", {}, "sha512-ZRiwvN089JfMXokizgqEPXsl2Guk094yExfoDXR0cBYWxtBbaSww/w+vT4WEJsBW2iTUi1GgZ6swmoug3Oy4Xw=="],
|
||||
|
||||
"hexoid": ["hexoid@1.0.0", "", {}, "sha512-QFLV0taWQOZtvIRIAdBChesmogZrtuXvVWsFHZTk2SU+anspqZ2vMnoLg7IE1+Uk16N19APic1BuF8bC8c2m5g=="],
|
||||
|
||||
"hookable": ["hookable@5.5.3", "", {}, "sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ=="],
|
||||
|
||||
"htmlparser2": ["htmlparser2@8.0.2", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.3", "domutils": "^3.0.1", "entities": "^4.4.0" } }, "sha512-GYdjWKDkbRLkZ5geuHs5NY1puJ+PXwP7+fHPRz06Eirsb9ugf6d8kkXav6ADhcODhFFPMIXyxkxSuMf3D6NCFA=="],
|
||||
|
||||
"humanize-ms": ["humanize-ms@1.2.1", "", { "dependencies": { "ms": "^2.0.0" } }, "sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ=="],
|
||||
|
||||
"husky": ["husky@9.1.7", "", { "bin": { "husky": "bin.js" } }, "sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA=="],
|
||||
|
||||
"ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
|
||||
|
||||
"import-fresh": ["import-fresh@3.3.1", "", { "dependencies": { "parent-module": "^1.0.0", "resolve-from": "^4.0.0" } }, "sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ=="],
|
||||
|
||||
"imurmurhash": ["imurmurhash@0.1.4", "", {}, "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA=="],
|
||||
|
||||
"inflight": ["inflight@1.0.6", "", { "dependencies": { "once": "^1.3.0", "wrappy": "1" } }, "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA=="],
|
||||
|
||||
"inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
|
||||
|
||||
"is-arrayish": ["is-arrayish@0.3.2", "", {}, "sha512-eVRqCvVlZbuw3GrM63ovNSNAeA1K16kaR/LRY/92w0zxQ5/1YzwblUX652i4Xs9RwAGjW9d9y6X88t8OaAJfWQ=="],
|
||||
|
||||
"is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
|
||||
|
||||
"is-glob": ["is-glob@4.0.3", "", { "dependencies": { "is-extglob": "^2.1.1" } }, "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg=="],
|
||||
|
||||
"is-number": ["is-number@7.0.0", "", {}, "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng=="],
|
||||
|
||||
"is-path-inside": ["is-path-inside@3.0.3", "", {}, "sha512-Fd4gABb+ycGAmKou8eMftCupSir5lRxqf4aD/vd0cD2qc4HL07OjCeuHMr8Ro4CoMaeCKDB0/ECBOVWjTwUvPQ=="],
|
||||
|
||||
"is-plain-object": ["is-plain-object@5.0.0", "", {}, "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q=="],
|
||||
|
||||
"is-stream": ["is-stream@2.0.1", "", {}, "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg=="],
|
||||
|
||||
"isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
|
||||
|
||||
"js-yaml": ["js-yaml@4.1.0", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA=="],
|
||||
|
||||
"json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
|
||||
|
||||
"json-schema-traverse": ["json-schema-traverse@0.4.1", "", {}, "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg=="],
|
||||
|
||||
"json-stable-stringify-without-jsonify": ["json-stable-stringify-without-jsonify@1.0.1", "", {}, "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw=="],
|
||||
|
||||
"jsonwebtoken": ["jsonwebtoken@9.0.2", "", { "dependencies": { "jws": "^3.2.2", "lodash.includes": "^4.3.0", "lodash.isboolean": "^3.0.3", "lodash.isinteger": "^4.0.4", "lodash.isnumber": "^3.0.3", "lodash.isplainobject": "^4.0.6", "lodash.isstring": "^4.0.1", "lodash.once": "^4.0.0", "ms": "^2.1.1", "semver": "^7.5.4" } }, "sha512-PRp66vJ865SSqOlgqS8hujT5U4AOgMfhrwYIuIhfKaoSCZcirrmASQr8CX7cUg+RMih+hgznrjp99o+W4pJLHQ=="],
|
||||
|
||||
"jwa": ["jwa@1.4.1", "", { "dependencies": { "buffer-equal-constant-time": "1.0.1", "ecdsa-sig-formatter": "1.0.11", "safe-buffer": "^5.0.1" } }, "sha512-qiLX/xhEEFKUAJ6FiBMbes3w9ATzyk5W7Hvzpa/SLYdxNtng+gcurvrI7TbACjIXlsJyr05/S1oUhZrc63evQA=="],
|
||||
|
||||
"jws": ["jws@3.2.2", "", { "dependencies": { "jwa": "^1.4.1", "safe-buffer": "^5.0.1" } }, "sha512-YHlZCB6lMTllWDtSPHz/ZXTsi8S00usEV6v1tjq8tOUZzw7DpSDWVXjXDre6ed1w/pd495ODpHZYSdkRTsa0HA=="],
|
||||
|
||||
"keyv": ["keyv@4.5.4", "", { "dependencies": { "json-buffer": "3.0.1" } }, "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw=="],
|
||||
|
||||
"kuler": ["kuler@2.0.0", "", {}, "sha512-Xq9nH7KlWZmXAtodXDDRE7vs6DU1gTU8zYDHDiWLSip45Egwq3plLHzPn27NgvzL2r1LMPC1vdqh98sQxtqj4A=="],
|
||||
|
||||
"levn": ["levn@0.4.1", "", { "dependencies": { "prelude-ls": "^1.2.1", "type-check": "~0.4.0" } }, "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ=="],
|
||||
|
||||
"locate-path": ["locate-path@6.0.0", "", { "dependencies": { "p-locate": "^5.0.0" } }, "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw=="],
|
||||
|
||||
"lodash.includes": ["lodash.includes@4.3.0", "", {}, "sha512-W3Bx6mdkRTGtlJISOvVD/lbqjTlPPUDTMnlXZFnVwi9NKJ6tiAk6LVdlhZMm17VZisqhKcgzpO5Wz91PCt5b0w=="],
|
||||
|
||||
"lodash.isboolean": ["lodash.isboolean@3.0.3", "", {}, "sha512-Bz5mupy2SVbPHURB98VAcw+aHh4vRV5IPNhILUCsOzRmsTmSQ17jIuqopAentWoehktxGd9e/hbIXq980/1QJg=="],
|
||||
|
||||
"lodash.isinteger": ["lodash.isinteger@4.0.4", "", {}, "sha512-DBwtEWN2caHQ9/imiNeEA5ys1JoRtRfY3d7V9wkqtbycnAmTvRRmbHKDV4a0EYc678/dia0jrte4tjYwVBaZUA=="],
|
||||
|
||||
"lodash.isnumber": ["lodash.isnumber@3.0.3", "", {}, "sha512-QYqzpfwO3/CWf3XP+Z+tkQsfaLL/EnUlXWVkIk5FUPc4sBdTehEqZONuyRt2P67PXAk+NXmTBcc97zw9t1FQrw=="],
|
||||
|
||||
"lodash.isplainobject": ["lodash.isplainobject@4.0.6", "", {}, "sha512-oSXzaWypCMHkPC3NvBEaPHf0KsA5mvPrOPgQWDsbg8n7orZ290M0BmC/jgRZ4vcJ6DTAhjrsSYgdsW/F+MFOBA=="],
|
||||
|
||||
"lodash.isstring": ["lodash.isstring@4.0.1", "", {}, "sha512-0wJxfxH1wgO3GrbuP+dTTk7op+6L41QCXbGINEmD+ny/G/eCqGzxyCsh7159S+mgDDcoarnBw6PC1PS5+wUGgw=="],
|
||||
|
||||
"lodash.merge": ["lodash.merge@4.6.2", "", {}, "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ=="],
|
||||
|
||||
"lodash.once": ["lodash.once@4.1.1", "", {}, "sha512-Sb487aTOCr9drQVL8pIxOzVhafOjZN9UU54hiN8PU3uAiSV7lx1yYNpbNmex2PK6dSJoNTSJUUswT651yww3Mg=="],
|
||||
|
||||
"logform": ["logform@2.7.0", "", { "dependencies": { "@colors/colors": "1.6.0", "@types/triple-beam": "^1.3.2", "fecha": "^4.2.0", "ms": "^2.1.1", "safe-stable-stringify": "^2.3.1", "triple-beam": "^1.3.0" } }, "sha512-TFYA4jnP7PVbmlBIfhlSe+WKxs9dklXMTEGcBCIvLhE/Tn3H6Gk1norupVW7m5Cnd4bLcr08AytbyV/xj7f/kQ=="],
|
||||
|
||||
"math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
|
||||
|
||||
"memoirist": ["memoirist@0.3.0", "", {}, "sha512-wR+4chMgVPq+T6OOsk40u9Wlpw1Pjx66NMNiYxCQQ4EUJ7jDs3D9kTCeKdBOkvAiqXlHLVJlvYL01PvIJ1MPNg=="],
|
||||
|
||||
"merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="],
|
||||
|
||||
"methods": ["methods@1.1.2", "", {}, "sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w=="],
|
||||
|
||||
"micromatch": ["micromatch@4.0.8", "", { "dependencies": { "braces": "^3.0.3", "picomatch": "^2.3.1" } }, "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA=="],
|
||||
|
||||
"mime": ["mime@2.6.0", "", { "bin": { "mime": "cli.js" } }, "sha512-USPkMeET31rOMiarsBNIHZKLGgvKc/LrjofAnBlOttf5ajRvqiRA8QsenbcooctK6d6Ts6aqZXBA+XbkKthiQg=="],
|
||||
|
||||
"mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
|
||||
|
||||
"mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
|
||||
|
||||
"minimatch": ["minimatch@3.1.2", "", { "dependencies": { "brace-expansion": "^1.1.7" } }, "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw=="],
|
||||
|
||||
"moment": ["moment@2.30.1", "", {}, "sha512-uEmtNhbDOrWPFS+hdjFCBfy9f2YoyzRpwcl+DqpC6taX21FzsTLQVbMV/W7PzNSX6x/bhC1zA3c2UQ5NzH6how=="],
|
||||
|
||||
"ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
|
||||
|
||||
"nanoid": ["nanoid@3.3.8", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-WNLf5Sd8oZxOm+TzppcYk8gVOgP+l58xNy58D0nbUnOxOWRWvlcCV4kUF7ltmI6PsrLl/BgKEyS4mqsGChFN0w=="],
|
||||
|
||||
"natural-compare": ["natural-compare@1.4.0", "", {}, "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw=="],
|
||||
|
||||
"node-domexception": ["node-domexception@1.0.0", "", {}, "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ=="],
|
||||
|
||||
"node-fetch": ["node-fetch@3.3.2", "", { "dependencies": { "data-uri-to-buffer": "^4.0.0", "fetch-blob": "^3.1.4", "formdata-polyfill": "^4.0.10" } }, "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA=="],
|
||||
|
||||
"object-hash": ["object-hash@3.0.0", "", {}, "sha512-RSn9F68PjH9HqtltsSnqYC1XXoWe9Bju5+213R98cNGttag9q9yAOTzdbsqvIa7aNm5WffBZFpWYr2aWrklWAw=="],
|
||||
|
||||
"object-inspect": ["object-inspect@1.13.3", "", {}, "sha512-kDCGIbxkDSXE3euJZZXzc6to7fCrKHNI/hSRQnRuQ+BWjFNzZwiFF8fj/6o2t2G9/jTj8PSIYTfCLelLZEeRpA=="],
|
||||
|
||||
"once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
|
||||
|
||||
"one-time": ["one-time@1.0.0", "", { "dependencies": { "fn.name": "1.x.x" } }, "sha512-5DXOiRKwuSEcQ/l0kGCF6Q3jcADFv5tSmRaJck/OqkVFcOzutB134KRSfF0xDrL39MNnqxbHBbUUcjZIhTgb2g=="],
|
||||
|
||||
"openai": ["openai@4.82.0", "", { "dependencies": { "@types/node": "^18.11.18", "@types/node-fetch": "^2.6.4", "abort-controller": "^3.0.0", "agentkeepalive": "^4.2.1", "form-data-encoder": "1.7.2", "formdata-node": "^4.3.2", "node-fetch": "^2.6.7" }, "peerDependencies": { "ws": "^8.18.0", "zod": "^3.23.8" }, "optionalPeers": ["ws", "zod"], "bin": { "openai": "bin/cli" } }, "sha512-1bTxOVGZuVGsKKUWbh3BEwX1QxIXUftJv+9COhhGGVDTFwiaOd4gWsMynF2ewj1mg6by3/O+U8+EEHpWRdPaJg=="],
|
||||
|
||||
"openapi-types": ["openapi-types@12.1.3", "", {}, "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw=="],
|
||||
|
||||
"optionator": ["optionator@0.9.4", "", { "dependencies": { "deep-is": "^0.1.3", "fast-levenshtein": "^2.0.6", "levn": "^0.4.1", "prelude-ls": "^1.2.1", "type-check": "^0.4.0", "word-wrap": "^1.2.5" } }, "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g=="],
|
||||
|
||||
"p-limit": ["p-limit@3.1.0", "", { "dependencies": { "yocto-queue": "^0.1.0" } }, "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ=="],
|
||||
|
||||
"p-locate": ["p-locate@5.0.0", "", { "dependencies": { "p-limit": "^3.0.2" } }, "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw=="],
|
||||
|
||||
"parent-module": ["parent-module@1.0.1", "", { "dependencies": { "callsites": "^3.0.0" } }, "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g=="],
|
||||
|
||||
"parse-srcset": ["parse-srcset@1.0.2", "", {}, "sha512-/2qh0lav6CmI15FzA3i/2Bzk2zCgQhGMkvhOhKNcBVQ1ldgpbfiNTVslmooUmWJcADi1f1kIeynbDRVzNlfR6Q=="],
|
||||
|
||||
"path-exists": ["path-exists@4.0.0", "", {}, "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w=="],
|
||||
|
||||
"path-is-absolute": ["path-is-absolute@1.0.1", "", {}, "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg=="],
|
||||
|
||||
"path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
|
||||
|
||||
"path-type": ["path-type@4.0.0", "", {}, "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw=="],
|
||||
|
||||
"pathe": ["pathe@1.1.2", "", {}, "sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ=="],
|
||||
|
||||
"picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
|
||||
|
||||
"picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
|
||||
|
||||
"postcss": ["postcss@8.5.1", "", { "dependencies": { "nanoid": "^3.3.8", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-6oz2beyjc5VMn/KV1pPw8fliQkhBXrVn1Z3TVyqZxU8kZpzEKhBdmCFqI6ZbmGtamQvQGuU1sgPTk8ZrXDD7jQ=="],
|
||||
|
||||
"prelude-ls": ["prelude-ls@1.2.1", "", {}, "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g=="],
|
||||
|
||||
"prettier": ["prettier@3.4.2", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-e9MewbtFo+Fevyuxn/4rrcDAaq0IYxPGLvObpQjiZBMAzB9IGmzlnG9RZy3FFas+eBMu2vA0CszMeduow5dIuQ=="],
|
||||
|
||||
"prettier-linter-helpers": ["prettier-linter-helpers@1.0.0", "", { "dependencies": { "fast-diff": "^1.1.2" } }, "sha512-GbK2cP9nraSSUF9N2XwUwqfzlAFlMNYYl+ShE/V+H8a9uNl/oUqB1w2EL54Jh0OlyRSd8RfWYJ3coVS4TROP2w=="],
|
||||
|
||||
"punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
|
||||
|
||||
"qs": ["qs@6.14.0", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-YWWTjgABSKcvs/nWBi9PycY/JiPJqOD4JA6o9Sej2AtvSGarXxKC3OQSk4pAarbdQlKAh5D4FCQkJNkW+GAn3w=="],
|
||||
|
||||
"queue-microtask": ["queue-microtask@1.2.3", "", {}, "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="],
|
||||
|
||||
"readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="],
|
||||
|
||||
"resolve-from": ["resolve-from@4.0.0", "", {}, "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g=="],
|
||||
|
||||
"reusify": ["reusify@1.0.4", "", {}, "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw=="],
|
||||
|
||||
"rimraf": ["rimraf@3.0.2", "", { "dependencies": { "glob": "^7.1.3" }, "bin": { "rimraf": "bin.js" } }, "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA=="],
|
||||
|
||||
"run-parallel": ["run-parallel@1.2.0", "", { "dependencies": { "queue-microtask": "^1.2.2" } }, "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA=="],
|
||||
|
||||
"safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
|
||||
|
||||
"safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
|
||||
|
||||
"sanitize-html": ["sanitize-html@2.14.0", "", { "dependencies": { "deepmerge": "^4.2.2", "escape-string-regexp": "^4.0.0", "htmlparser2": "^8.0.0", "is-plain-object": "^5.0.0", "parse-srcset": "^1.0.2", "postcss": "^8.3.11" } }, "sha512-CafX+IUPxZshXqqRaG9ZClSlfPVjSxI0td7n07hk8QO2oO+9JDnlcL8iM8TWeOXOIBFgIOx6zioTzM53AOMn3g=="],
|
||||
|
||||
"semver": ["semver@7.7.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-hlq8tAfn0m/61p4BVRcPzIGr6LKiMwo4VM6dGi6pt4qcRkmNzTcWq6eCEjEh+qXjkMDvPlOFFSGwQjoEa6gyMA=="],
|
||||
|
||||
"shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
|
||||
|
||||
"shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
|
||||
|
||||
"side-channel": ["side-channel@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3", "side-channel-list": "^1.0.0", "side-channel-map": "^1.0.1", "side-channel-weakmap": "^1.0.2" } }, "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw=="],
|
||||
|
||||
"side-channel-list": ["side-channel-list@1.0.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3" } }, "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA=="],
|
||||
|
||||
"side-channel-map": ["side-channel-map@1.0.1", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3" } }, "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA=="],
|
||||
|
||||
"side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3", "side-channel-map": "^1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],
|
||||
|
||||
"simple-swizzle": ["simple-swizzle@0.2.2", "", { "dependencies": { "is-arrayish": "^0.3.1" } }, "sha512-JA//kQgZtbuY83m+xT+tXJkmJncGMTFT+C+g2h2R9uxkYIrE2yy9sgmcLhCnw57/WSD+Eh3J97FPEDFnbXnDUg=="],
|
||||
|
||||
"slash": ["slash@3.0.0", "", {}, "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q=="],
|
||||
|
||||
"source-map-js": ["source-map-js@1.2.1", "", {}, "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA=="],
|
||||
|
||||
"stack-trace": ["stack-trace@0.0.10", "", {}, "sha512-KGzahc7puUKkzyMt+IqAep+TVNbKP+k2Lmwhub39m1AsTSkaDutx56aDCo+HLDzf/D26BIHTJWNiTG1KAJiQCg=="],
|
||||
|
||||
"string_decoder": ["string_decoder@1.3.0", "", { "dependencies": { "safe-buffer": "~5.2.0" } }, "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA=="],
|
||||
|
||||
"strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
|
||||
|
||||
"strip-json-comments": ["strip-json-comments@3.1.1", "", {}, "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig=="],
|
||||
|
||||
"superagent": ["superagent@8.1.2", "", { "dependencies": { "component-emitter": "^1.3.0", "cookiejar": "^2.1.4", "debug": "^4.3.4", "fast-safe-stringify": "^2.1.1", "form-data": "^4.0.0", "formidable": "^2.1.2", "methods": "^1.1.2", "mime": "2.6.0", "qs": "^6.11.0", "semver": "^7.3.8" } }, "sha512-6WTxW1EB6yCxV5VFOIPQruWGHqc3yI7hEmZK6h+pyk69Lk/Ut7rLUY6W/ONF2MjBuGjvmMiIpsrVJ2vjrHlslA=="],
|
||||
|
||||
"supertest": ["supertest@6.3.4", "", { "dependencies": { "methods": "^1.1.2", "superagent": "^8.1.2" } }, "sha512-erY3HFDG0dPnhw4U+udPfrzXa4xhSG+n4rxfRuZWCUvjFWwKl+OxWf/7zk50s84/fAAs7vf5QAb9uRa0cCykxw=="],
|
||||
|
||||
"supports-color": ["supports-color@7.2.0", "", { "dependencies": { "has-flag": "^4.0.0" } }, "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw=="],
|
||||
|
||||
"synckit": ["synckit@0.9.2", "", { "dependencies": { "@pkgr/core": "^0.1.0", "tslib": "^2.6.2" } }, "sha512-vrozgXDQwYO72vHjUb/HnFbQx1exDjoKzqx23aXEg2a9VIg2TSFZ8FmeZpTjUCFMYw7mpX4BE2SFu8wI7asYsw=="],
|
||||
|
||||
"text-hex": ["text-hex@1.0.0", "", {}, "sha512-uuVGNWzgJ4yhRaNSiubPY7OjISw4sw4E5Uv0wbjp+OzcbmVU/rsT8ujgcXJhn9ypzsgr5vlzpPqP+MBBKcGvbg=="],
|
||||
|
||||
"text-table": ["text-table@0.2.0", "", {}, "sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw=="],
|
||||
|
||||
"to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
|
||||
|
||||
"tr46": ["tr46@0.0.3", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
|
||||
|
||||
"triple-beam": ["triple-beam@1.4.1", "", {}, "sha512-aZbgViZrg1QNcG+LULa7nhZpJTZSLm/mXnHXnbAbjmN5aSa0y7V+wvv6+4WaBtpISJzThKy+PIPxc1Nq1EJ9mg=="],
|
||||
|
||||
"ts-api-utils": ["ts-api-utils@1.4.3", "", { "peerDependencies": { "typescript": ">=4.2.0" } }, "sha512-i3eMG77UTMD0hZhgRS562pv83RC6ukSAC2GMNWc+9dieh/+jDM5u5YG+NHX6VNDRHQcHwmsTHctP9LhbC3WxVw=="],
|
||||
|
||||
"tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
|
||||
|
||||
"type-check": ["type-check@0.4.0", "", { "dependencies": { "prelude-ls": "^1.2.1" } }, "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew=="],
|
||||
|
||||
"type-fest": ["type-fest@0.20.2", "", {}, "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ=="],
|
||||
|
||||
"typescript": ["typescript@5.7.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
|
||||
|
||||
"undici-types": ["undici-types@6.19.8", "", {}, "sha512-ve2KP6f/JnbPBFyobGHuerC9g1FYGn/F8n1LWTwNxCEzd6IfqTwUQcNXgEtmmQ6DlRrC1hrSrBnCZPokRrDHjw=="],
|
||||
|
||||
"uri-js": ["uri-js@4.4.1", "", { "dependencies": { "punycode": "^2.1.0" } }, "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg=="],
|
||||
|
||||
"util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
|
||||
|
||||
"uuid": ["uuid@11.0.5", "", { "bin": { "uuid": "dist/esm/bin/uuid" } }, "sha512-508e6IcKLrhxKdBbcA2b4KQZlLVp2+J5UwQ6F7Drckkc5N9ZJwFa4TgWtsww9UG8fGHbm6gbV19TdM5pQ4GaIA=="],
|
||||
|
||||
"web-streams-polyfill": ["web-streams-polyfill@3.3.3", "", {}, "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw=="],
|
||||
|
||||
"webidl-conversions": ["webidl-conversions@3.0.1", "", {}, "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="],
|
||||
|
||||
"whatwg-url": ["whatwg-url@5.0.0", "", { "dependencies": { "tr46": "~0.0.3", "webidl-conversions": "^3.0.0" } }, "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw=="],
|
||||
|
||||
"which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
|
||||
|
||||
"winston": ["winston@3.17.0", "", { "dependencies": { "@colors/colors": "^1.6.0", "@dabh/diagnostics": "^2.0.2", "async": "^3.2.3", "is-stream": "^2.0.0", "logform": "^2.7.0", "one-time": "^1.0.0", "readable-stream": "^3.4.0", "safe-stable-stringify": "^2.3.1", "stack-trace": "0.0.x", "triple-beam": "^1.3.0", "winston-transport": "^4.9.0" } }, "sha512-DLiFIXYC5fMPxaRg832S6F5mJYvePtmO5G9v9IgUFPhXm9/GkXarH/TUrBAVzhTCzAj9anE/+GjrgXp/54nOgw=="],
|
||||
|
||||
"winston-daily-rotate-file": ["winston-daily-rotate-file@5.0.0", "", { "dependencies": { "file-stream-rotator": "^0.6.1", "object-hash": "^3.0.0", "triple-beam": "^1.4.1", "winston-transport": "^4.7.0" }, "peerDependencies": { "winston": "^3" } }, "sha512-JDjiXXkM5qvwY06733vf09I2wnMXpZEhxEVOSPenZMii+g7pcDcTBt2MRugnoi8BwVSuCT2jfRXBUy+n1Zz/Yw=="],
|
||||
|
||||
"winston-transport": ["winston-transport@4.9.0", "", { "dependencies": { "logform": "^2.7.0", "readable-stream": "^3.6.2", "triple-beam": "^1.3.0" } }, "sha512-8drMJ4rkgaPo1Me4zD/3WLfI/zPdA9o2IipKODunnGDcuqbHwjsbB79ylv04LCGGzU0xQ6vTznOMpQGaLhhm6A=="],
|
||||
|
||||
"word-wrap": ["word-wrap@1.2.5", "", {}, "sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA=="],
|
||||
|
||||
"wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
|
||||
|
||||
"ws": ["ws@8.18.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-8VbfWfHLbbwu3+N6OKsOMpBdT4kXPDDB9cJk2bJ6mh9ucxdlnNvH1e+roYkKmN9Nxw2yjz7VzeO9oOz2zJ04Pw=="],
|
||||
|
||||
"yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
|
||||
|
||||
"zhead": ["zhead@2.2.4", "", {}, "sha512-8F0OI5dpWIA5IGG5NHUg9staDwz/ZPxZtvGVf01j7vHqSyZ0raHY+78atOVxRqb73AotX22uV1pXt3gYSstGag=="],
|
||||
|
||||
"zod": ["zod@3.24.1", "", {}, "sha512-muH7gBL9sI1nciMZV67X5fTKKBLtwpZ5VBp1vsOQzj1MhrBZ4wlVCm3gedKZWLp0Oyel8sIGfeiz54Su+OVT+A=="],
|
||||
|
||||
"@scalar/themes/@scalar/types": ["@scalar/types@0.0.30", "", { "dependencies": { "@scalar/openapi-types": "0.1.7", "@unhead/schema": "^1.11.11" } }, "sha512-rhgwovQb5f7PXuUB5bLUElpo90fdsiwcOgBXVWZ6n6dnFSKovNJ7GPXQimsZioMzTF6TdwfP94UpZVdZAK4aTw=="],
|
||||
|
||||
"@typescript-eslint/typescript-estree/minimatch": ["minimatch@9.0.5", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow=="],
|
||||
|
||||
"color/color-convert": ["color-convert@1.9.3", "", { "dependencies": { "color-name": "1.1.3" } }, "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg=="],
|
||||
|
||||
"color-string/color-name": ["color-name@1.1.3", "", {}, "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw=="],
|
||||
|
||||
"fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
|
||||
|
||||
"formdata-node/web-streams-polyfill": ["web-streams-polyfill@4.0.0-beta.3", "", {}, "sha512-QW95TCTaHmsYfHDybGMwO5IJIM93I/6vTRk+daHTWFPhwh+C8Cg7j7XyKrwrj8Ib6vYXe0ocYNrmzY4xAAN6ug=="],
|
||||
|
||||
"openai/@types/node": ["@types/node@18.19.75", "", { "dependencies": { "undici-types": "~5.26.4" } }, "sha512-UIksWtThob6ZVSyxcOqCLOUNg/dyO1Qvx4McgeuhrEtHTLFTf7BBhEazaE4K806FGTPtzd/2sE90qn4fVr7cyw=="],
|
||||
|
||||
"openai/node-fetch": ["node-fetch@2.7.0", "", { "dependencies": { "whatwg-url": "^5.0.0" }, "peerDependencies": { "encoding": "^0.1.0" }, "optionalPeers": ["encoding"] }, "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A=="],
|
||||
|
||||
"@scalar/themes/@scalar/types/@scalar/openapi-types": ["@scalar/openapi-types@0.1.7", "", {}, "sha512-oOTG3JQifg55U3DhKB7WdNIxFnJzbPJe7rqdyWdio977l8IkxQTVmObftJhdNIMvhV2K+1f/bDoMQGu6yTaD0A=="],
|
||||
|
||||
"@typescript-eslint/typescript-estree/minimatch/brace-expansion": ["brace-expansion@2.0.1", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA=="],
|
||||
|
||||
"color/color-convert/color-name": ["color-name@1.1.3", "", {}, "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw=="],
|
||||
|
||||
"openai/@types/node/undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
|
||||
}
|
||||
}
|
||||
49
docker-compose.speech.yml
Normal file
49
docker-compose.speech.yml
Normal file
@@ -0,0 +1,49 @@
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
homeassistant-mcp:
|
||||
environment:
|
||||
- ENABLE_SPEECH_FEATURES=${ENABLE_SPEECH_FEATURES:-true}
|
||||
- ENABLE_WAKE_WORD=${ENABLE_WAKE_WORD:-true}
|
||||
- ENABLE_SPEECH_TO_TEXT=${ENABLE_SPEECH_TO_TEXT:-true}
|
||||
|
||||
fast-whisper:
|
||||
image: onerahmet/openai-whisper-asr-webservice:latest
|
||||
volumes:
|
||||
- whisper-models:/models
|
||||
- audio-data:/audio
|
||||
environment:
|
||||
- ASR_MODEL=base
|
||||
- ASR_ENGINE=faster_whisper
|
||||
- WHISPER_BEAM_SIZE=5
|
||||
- COMPUTE_TYPE=float32
|
||||
- LANGUAGE=en
|
||||
ports:
|
||||
- "9000:9000"
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '4.0'
|
||||
memory: 2G
|
||||
healthcheck:
|
||||
test: [ "CMD", "curl", "-f", "http://localhost:9000/health" ]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
|
||||
wake-word:
|
||||
image: rhasspy/wyoming-openwakeword:latest
|
||||
restart: unless-stopped
|
||||
devices:
|
||||
- /dev/snd:/dev/snd
|
||||
volumes:
|
||||
- /run/user/1000/pulse/native:/run/user/1000/pulse/native
|
||||
environment:
|
||||
- PULSE_SERVER=unix:/run/user/1000/pulse/native
|
||||
group_add:
|
||||
- audio
|
||||
network_mode: host
|
||||
|
||||
volumes:
|
||||
whisper-models:
|
||||
audio-data:
|
||||
@@ -1,67 +0,0 @@
|
||||
# Use Python slim image as builder
|
||||
FROM python:3.10-slim as builder
|
||||
|
||||
# Install build dependencies
|
||||
RUN apt-get update && apt-get install -y \
|
||||
git \
|
||||
build-essential \
|
||||
portaudio19-dev \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Create and activate virtual environment
|
||||
RUN python -m venv /opt/venv
|
||||
ENV PATH="/opt/venv/bin:$PATH"
|
||||
|
||||
# Install Python dependencies with specific versions and CPU-only variants
|
||||
RUN pip install --no-cache-dir "numpy>=1.24.3,<2.0.0" && \
|
||||
pip install --no-cache-dir torch==2.1.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cpu && \
|
||||
pip install --no-cache-dir faster-whisper==0.10.0 openwakeword==0.4.0 pyaudio==0.2.14 sounddevice==0.4.6 requests==2.31.0 && \
|
||||
pip freeze > /opt/venv/requirements.txt
|
||||
|
||||
# Create final image
|
||||
FROM python:3.10-slim
|
||||
|
||||
# Copy virtual environment from builder
|
||||
COPY --from=builder /opt/venv /opt/venv
|
||||
ENV PATH="/opt/venv/bin:$PATH"
|
||||
|
||||
# Install audio dependencies
|
||||
RUN apt-get update && apt-get install -y \
|
||||
portaudio19-dev \
|
||||
python3-pyaudio \
|
||||
alsa-utils \
|
||||
libasound2 \
|
||||
libasound2-plugins \
|
||||
pulseaudio \
|
||||
pulseaudio-utils \
|
||||
libpulse0 \
|
||||
libportaudio2 \
|
||||
&& rm -rf /var/lib/apt/lists/* \
|
||||
&& mkdir -p /var/run/pulse /var/lib/pulse
|
||||
|
||||
# Create necessary directories
|
||||
RUN mkdir -p /models/wake_word /audio && \
|
||||
chown -R 1000:1000 /models /audio && \
|
||||
mkdir -p /home/user/.config/pulse && \
|
||||
chown -R 1000:1000 /home/user
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /app
|
||||
|
||||
# Copy the wake word detection script and audio setup script
|
||||
COPY wake_word_detector.py .
|
||||
COPY setup-audio.sh /setup-audio.sh
|
||||
RUN chmod +x /setup-audio.sh
|
||||
|
||||
# Set environment variables
|
||||
ENV WHISPER_MODEL_PATH=/models \
|
||||
WAKEWORD_MODEL_PATH=/models/wake_word \
|
||||
PYTHONUNBUFFERED=1 \
|
||||
PULSE_SERVER=unix:/run/user/1000/pulse/native \
|
||||
HOME=/home/user
|
||||
|
||||
# Run as the host user
|
||||
USER 1000:1000
|
||||
|
||||
# Start the application
|
||||
CMD ["/setup-audio.sh"]
|
||||
@@ -1,25 +1,58 @@
|
||||
#!/bin/bash
|
||||
set -e # Exit immediately if a command exits with a non-zero status
|
||||
set -x # Print commands and their arguments as they are executed
|
||||
|
||||
echo "Starting audio setup script at $(date)"
|
||||
echo "Current user: $(whoami)"
|
||||
echo "Current directory: $(pwd)"
|
||||
|
||||
# Print environment variables related to audio and speech
|
||||
echo "ENABLE_WAKE_WORD: ${ENABLE_WAKE_WORD}"
|
||||
echo "PULSE_SERVER: ${PULSE_SERVER}"
|
||||
echo "WHISPER_MODEL_PATH: ${WHISPER_MODEL_PATH}"
|
||||
|
||||
# Wait for PulseAudio socket to be available
|
||||
max_wait=30
|
||||
wait_count=0
|
||||
while [ ! -e /run/user/1000/pulse/native ]; do
|
||||
echo "Waiting for PulseAudio socket..."
|
||||
echo "Waiting for PulseAudio socket... (${wait_count}/${max_wait})"
|
||||
sleep 1
|
||||
wait_count=$((wait_count + 1))
|
||||
if [ $wait_count -ge $max_wait ]; then
|
||||
echo "ERROR: PulseAudio socket not available after ${max_wait} seconds"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
# Test PulseAudio connection
|
||||
pactl info || {
|
||||
echo "Failed to connect to PulseAudio server"
|
||||
# Verify PulseAudio connection with detailed error handling
|
||||
if ! pactl info; then
|
||||
echo "ERROR: Failed to connect to PulseAudio server"
|
||||
pactl list short modules
|
||||
pactl list short clients
|
||||
exit 1
|
||||
}
|
||||
fi
|
||||
|
||||
# List audio devices
|
||||
pactl list sources || {
|
||||
echo "Failed to list audio devices"
|
||||
# List audio devices with error handling
|
||||
if ! pactl list sources; then
|
||||
echo "ERROR: Failed to list audio devices"
|
||||
exit 1
|
||||
}
|
||||
fi
|
||||
|
||||
# Start the wake word detector
|
||||
python /app/wake_word_detector.py
|
||||
# Ensure wake word detector script is executable
|
||||
chmod +x /app/wake_word_detector.py
|
||||
|
||||
# Start the wake word detector with logging
|
||||
echo "Starting wake word detector at $(date)"
|
||||
python /app/wake_word_detector.py 2>&1 | tee /audio/wake_word_detector.log &
|
||||
wake_word_pid=$!
|
||||
|
||||
# Wait and check if the process is still running
|
||||
sleep 5
|
||||
if ! kill -0 $wake_word_pid 2>/dev/null; then
|
||||
echo "ERROR: Wake word detector process died immediately"
|
||||
cat /audio/wake_word_detector.log
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Mute the monitor to prevent feedback
|
||||
pactl set-source-mute alsa_output.pci-0000_00_1b.0.analog-stereo.monitor 1
|
||||
@@ -30,5 +63,6 @@ pactl set-source-volume alsa_input.pci-0000_00_1b.0.analog-stereo 65%
|
||||
# Set speaker volume to 40%
|
||||
pactl set-sink-volume alsa_output.pci-0000_00_1b.0.analog-stereo 40%
|
||||
|
||||
# Make the script executable
|
||||
chmod +x /setup-audio.sh
|
||||
# Keep the script running to prevent container exit
|
||||
echo "Audio setup complete. Keeping container alive."
|
||||
tail -f /dev/null
|
||||
@@ -53,8 +53,8 @@ HASS_TOKEN = os.environ.get('HASS_TOKEN')
|
||||
|
||||
def initialize_asr_model():
|
||||
"""Initialize the ASR model with retries and timeout"""
|
||||
model_path = os.environ.get('ASR_MODEL_PATH', '/models')
|
||||
model_name = os.environ.get('ASR_MODEL', 'large-v3')
|
||||
model_path = os.environ.get('WHISPER_MODEL_PATH', '/models')
|
||||
model_name = os.environ.get('WHISPER_MODEL_TYPE', 'base')
|
||||
|
||||
start_time = time.time()
|
||||
for attempt in range(MAX_MODEL_LOAD_RETRIES):
|
||||
|
||||
758
docs/api.md
758
docs/api.md
@@ -1,728 +1,170 @@
|
||||
# 🚀 Home Assistant MCP API Documentation
|
||||
# Home Assistant MCP Server API Documentation
|
||||
|
||||
 
|
||||
## 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
|
||||
|
||||
## Example Usage
|
||||
## Limitations
|
||||
|
||||
### Using curl
|
||||
```bash
|
||||
# Get current state
|
||||
curl -X GET \
|
||||
http://localhost:3000/api/state \
|
||||
-H 'Authorization: ApiKey your_api_key_here'
|
||||
- Limited to basic device control
|
||||
- No advanced automation
|
||||
- Minimal error handling
|
||||
- Basic authentication
|
||||
|
||||
# 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
|
||||
}
|
||||
}'
|
||||
```
|
||||
## Best Practices
|
||||
|
||||
### Using JavaScript
|
||||
```javascript
|
||||
// Execute action
|
||||
async function executeAction() {
|
||||
const response = await fetch('http://localhost:3000/api/action', {
|
||||
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: {
|
||||
'Authorization': 'ApiKey your_api_key_here',
|
||||
'Content-Type': 'application/json'
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${token}`
|
||||
},
|
||||
body: JSON.stringify({
|
||||
action: 'turn_on_lights',
|
||||
parameters: {
|
||||
room: 'living_room',
|
||||
brightness: 80
|
||||
}
|
||||
entity_id: entityId,
|
||||
command,
|
||||
parameters: params
|
||||
})
|
||||
});
|
||||
|
||||
const data = await response.json();
|
||||
console.log('Action result:', data);
|
||||
}
|
||||
```
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(error.message);
|
||||
}
|
||||
|
||||
## 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
|
||||
return await response.json();
|
||||
} catch (error) {
|
||||
// Handle rate limit exceeded
|
||||
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));
|
||||
```
|
||||
|
||||
#### `validateRequestHeaders(request: Request, requiredContentType?: string)`
|
||||
## Future Development
|
||||
|
||||
Validates incoming HTTP request headers for security and compliance.
|
||||
Planned improvements:
|
||||
- Enhanced error handling
|
||||
- More comprehensive device support
|
||||
- Improved authentication mechanisms
|
||||
|
||||
**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: '<script>alert("xss")</script>'
|
||||
```
|
||||
|
||||
#### `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.*
|
||||
|
||||
@@ -232,3 +232,11 @@ The current API version is v1. Include the version in the URL:
|
||||
- [Core Functions](core.md) - Detailed endpoint documentation
|
||||
- [Architecture Overview](../architecture.md) - System design details
|
||||
- [Troubleshooting](../troubleshooting.md) - Common issues and solutions
|
||||
|
||||
# API Reference
|
||||
|
||||
The Advanced Home Assistant MCP provides several APIs for integration and automation:
|
||||
|
||||
- [Core API](core.md) - Primary interface for system control
|
||||
- [SSE API](sse.md) - Server-Sent Events for real-time updates
|
||||
- [Core Functions](core.md) - Essential system functions
|
||||
@@ -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.*
|
||||
30
docs/config/index.md
Normal file
30
docs/config/index.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Configuration
|
||||
|
||||
This section covers the configuration options available in the Home Assistant MCP Server.
|
||||
|
||||
## Overview
|
||||
|
||||
The MCP Server can be configured through various configuration files and environment variables. This section will guide you through the available options and their usage.
|
||||
|
||||
## Configuration Files
|
||||
|
||||
The main configuration files are:
|
||||
|
||||
1. `.env` - Environment variables
|
||||
2. `config.yaml` - Main configuration file
|
||||
3. `devices.yaml` - Device-specific configurations
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key environment variables that can be set:
|
||||
|
||||
- `MCP_HOST` - Host address (default: 0.0.0.0)
|
||||
- `MCP_PORT` - Port number (default: 8123)
|
||||
- `MCP_LOG_LEVEL` - Logging level (default: INFO)
|
||||
- `MCP_CONFIG_DIR` - Configuration directory path
|
||||
|
||||
## Next Steps
|
||||
|
||||
- See [System Configuration](../configuration.md) for detailed configuration options
|
||||
- Check [Environment Setup](../getting-started/configuration.md) for initial setup
|
||||
- Review [Security](../security.md) for security-related configurations
|
||||
429
docs/configuration.md
Normal file
429
docs/configuration.md
Normal file
@@ -0,0 +1,429 @@
|
||||
# System Configuration
|
||||
|
||||
This document provides detailed information about configuring the Home Assistant MCP Server.
|
||||
|
||||
## Environment File Structure
|
||||
|
||||
The MCP Server uses a flexible environment configuration system with support for different environments and local overrides:
|
||||
|
||||
### Environment Files
|
||||
|
||||
1. `.env.example` - Template file containing all available configuration options with example values
|
||||
- Use this as a reference to create your environment-specific configuration files
|
||||
- Not loaded by the application
|
||||
|
||||
2. Environment-specific files (loaded based on NODE_ENV):
|
||||
- `.env.dev` - Development environment (default)
|
||||
- `.env.test` - Test environment
|
||||
- `.env.prod` - Production environment
|
||||
|
||||
3. `.env` - Optional local override file
|
||||
- If present, values in this file override those from the environment-specific file
|
||||
- Useful for local development without modifying the environment-specific files
|
||||
|
||||
### File Loading Order
|
||||
|
||||
1. First, the environment-specific file is loaded based on NODE_ENV:
|
||||
- `NODE_ENV=production` → `.env.prod`
|
||||
- `NODE_ENV=development` → `.env.dev` (default)
|
||||
- `NODE_ENV=test` → `.env.test`
|
||||
|
||||
2. Then, if a `.env` file exists, its values override any previously loaded values
|
||||
|
||||
Example setup:
|
||||
```bash
|
||||
# .env.dev - Development configuration
|
||||
PORT=4000
|
||||
HASS_HOST=http://homeassistant.local:8123
|
||||
LOG_LEVEL=debug
|
||||
|
||||
# .env - Local overrides
|
||||
PORT=3000 # Overrides PORT from .env.dev
|
||||
HASS_HOST=http://localhost:8123 # Overrides HASS_HOST from .env.dev
|
||||
```
|
||||
|
||||
## Configuration File Structure
|
||||
|
||||
The MCP Server uses environment variables for configuration, with support for different environments (development, test, production):
|
||||
|
||||
```bash
|
||||
# .env, .env.development, or .env.test
|
||||
PORT=4000
|
||||
NODE_ENV=development
|
||||
HASS_HOST=http://192.168.178.63:8123
|
||||
HASS_TOKEN=your_token_here
|
||||
JWT_SECRET=your_secret_key
|
||||
```
|
||||
|
||||
## Server Settings
|
||||
|
||||
### Basic Server Configuration
|
||||
- `PORT`: Server port number (default: 4000)
|
||||
- `NODE_ENV`: Environment mode (development, production, test)
|
||||
- `HASS_HOST`: Home Assistant instance URL
|
||||
- `HASS_TOKEN`: Home Assistant long-lived access token
|
||||
|
||||
### Security Settings
|
||||
- `JWT_SECRET`: Secret key for JWT token generation
|
||||
- `RATE_LIMIT`: Rate limiting configuration
|
||||
- `windowMs`: Time window in milliseconds (default: 15 minutes)
|
||||
- `max`: Maximum requests per window (default: 100)
|
||||
|
||||
### WebSocket Settings
|
||||
- `SSE`: Server-Sent Events configuration
|
||||
- `MAX_CLIENTS`: Maximum concurrent clients (default: 1000)
|
||||
- `PING_INTERVAL`: Keep-alive ping interval in ms (default: 30000)
|
||||
|
||||
### Speech Features (Optional)
|
||||
- `ENABLE_SPEECH_FEATURES`: Enable speech processing features (default: false)
|
||||
- `ENABLE_WAKE_WORD`: Enable wake word detection (default: false)
|
||||
- `ENABLE_SPEECH_TO_TEXT`: Enable speech-to-text conversion (default: false)
|
||||
- `WHISPER_MODEL_PATH`: Path to Whisper models directory (default: /models)
|
||||
- `WHISPER_MODEL_TYPE`: Whisper model type (default: base)
|
||||
- Available models: tiny.en, base.en, small.en, medium.en, large-v2
|
||||
|
||||
## Environment Variables
|
||||
|
||||
All configuration is managed through environment variables:
|
||||
|
||||
```bash
|
||||
# Server
|
||||
PORT=4000
|
||||
NODE_ENV=development
|
||||
|
||||
# Home Assistant
|
||||
HASS_HOST=http://your-hass-instance:8123
|
||||
HASS_TOKEN=your_token_here
|
||||
|
||||
# Security
|
||||
JWT_SECRET=your-secret-key
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=info
|
||||
LOG_DIR=logs
|
||||
LOG_MAX_SIZE=20m
|
||||
LOG_MAX_DAYS=14d
|
||||
LOG_COMPRESS=true
|
||||
LOG_REQUESTS=true
|
||||
|
||||
# Speech Features (Optional)
|
||||
ENABLE_SPEECH_FEATURES=false
|
||||
ENABLE_WAKE_WORD=false
|
||||
ENABLE_SPEECH_TO_TEXT=false
|
||||
WHISPER_MODEL_PATH=/models
|
||||
WHISPER_MODEL_TYPE=base
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Security Rate Limiting
|
||||
Rate limiting is enabled by default to protect against brute force attacks:
|
||||
|
||||
```typescript
|
||||
RATE_LIMIT: {
|
||||
windowMs: 15 * 60 * 1000, // 15 minutes
|
||||
max: 100 // limit each IP to 100 requests per window
|
||||
}
|
||||
```
|
||||
|
||||
### Logging
|
||||
The server uses Bun's built-in logging capabilities with additional configuration:
|
||||
|
||||
```typescript
|
||||
LOGGING: {
|
||||
LEVEL: "info", // debug, info, warn, error
|
||||
DIR: "logs",
|
||||
MAX_SIZE: "20m",
|
||||
MAX_DAYS: "14d",
|
||||
COMPRESS: true,
|
||||
TIMESTAMP_FORMAT: "YYYY-MM-DD HH:mm:ss:ms",
|
||||
LOG_REQUESTS: true
|
||||
}
|
||||
```
|
||||
|
||||
### Speech-to-Text Configuration
|
||||
When speech features are enabled, you can configure the following options:
|
||||
|
||||
```typescript
|
||||
SPEECH: {
|
||||
ENABLED: false, // Master switch for all speech features
|
||||
WAKE_WORD_ENABLED: false, // Enable wake word detection
|
||||
SPEECH_TO_TEXT_ENABLED: false, // Enable speech-to-text
|
||||
WHISPER_MODEL_PATH: "/models", // Path to Whisper models
|
||||
WHISPER_MODEL_TYPE: "base", // Model type to use
|
||||
}
|
||||
```
|
||||
|
||||
Available Whisper models:
|
||||
- `tiny.en`: Fastest, lowest accuracy
|
||||
- `base.en`: Good balance of speed and accuracy
|
||||
- `small.en`: Better accuracy, slower
|
||||
- `medium.en`: High accuracy, much slower
|
||||
- `large-v2`: Best accuracy, very slow
|
||||
|
||||
For production deployments, we recommend using system tools like `logrotate` for log management.
|
||||
|
||||
Example logrotate configuration (`/etc/logrotate.d/mcp-server`):
|
||||
```
|
||||
/var/log/mcp-server.log {
|
||||
daily
|
||||
rotate 7
|
||||
compress
|
||||
delaycompress
|
||||
missingok
|
||||
notifempty
|
||||
create 644 mcp mcp
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Always use environment variables for sensitive information
|
||||
2. Keep .env files secure and never commit them to version control
|
||||
3. Use different environment files for development, test, and production
|
||||
4. Enable SSL/TLS in production (preferably via reverse proxy)
|
||||
5. Monitor log files for issues
|
||||
6. Regularly rotate logs in production
|
||||
7. Start with smaller Whisper models and upgrade if needed
|
||||
8. Consider GPU acceleration for larger Whisper models
|
||||
|
||||
## Validation
|
||||
|
||||
The server validates configuration on startup using Zod schemas:
|
||||
- Required fields are checked (e.g., HASS_TOKEN)
|
||||
- Value types are verified
|
||||
- Enums are validated (e.g., LOG_LEVEL, WHISPER_MODEL_TYPE)
|
||||
- Default values are applied when not specified
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common configuration issues:
|
||||
1. Missing required environment variables
|
||||
2. Invalid environment variable values
|
||||
3. Permission issues with log directories
|
||||
4. Rate limiting too restrictive
|
||||
5. Speech model loading failures
|
||||
6. Docker not available for speech features
|
||||
7. Insufficient system resources for larger models
|
||||
|
||||
See the [Troubleshooting Guide](troubleshooting.md) for solutions.
|
||||
|
||||
# Configuration Guide
|
||||
|
||||
This document describes the environment configuration system for the Home Assistant MCP Server.
|
||||
|
||||
## 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=4000 # Server port number
|
||||
NODE_ENV=development # Environment (development/production/test)
|
||||
|
||||
# Home Assistant
|
||||
HASS_HOST=http://homeassistant.local:8123 # Home Assistant URL
|
||||
HASS_TOKEN=your_token_here # Long-lived access token
|
||||
|
||||
# Security
|
||||
JWT_SECRET=your_secret_key # JWT signing secret
|
||||
```
|
||||
|
||||
### Optional Settings
|
||||
|
||||
#### Security
|
||||
```bash
|
||||
# Rate Limiting
|
||||
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
|
||||
|
||||
# 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
|
||||
|
||||
# Cookie Security
|
||||
COOKIE_SECRET=your_cookie_secret_key_min_32_chars
|
||||
COOKIE_SECURE=true
|
||||
COOKIE_HTTP_ONLY=true
|
||||
COOKIE_SAME_SITE=Strict
|
||||
```
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
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
|
||||
|
||||
2. **Security**
|
||||
- Use strong, unique values for secrets
|
||||
- Enable HTTPS in production
|
||||
- Keep tokens and secrets in `.env` only
|
||||
|
||||
3. **Development**
|
||||
- Use `.env.dev` for shared development settings
|
||||
- Keep `.env` for personal overrides
|
||||
- Enable debug logging in development
|
||||
|
||||
4. **Production**
|
||||
- Use `.env.prod` for production defaults
|
||||
- Set appropriate rate limits
|
||||
- Configure proper logging
|
||||
- Enable all security features
|
||||
|
||||
5. **Testing**
|
||||
- Use `.env.test` for test configuration
|
||||
- Use mock tokens and endpoints
|
||||
- Enable detailed logging for debugging
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
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.
|
||||
@@ -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!*
|
||||
141
docs/deployment.md
Normal file
141
docs/deployment.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Deployment Guide
|
||||
|
||||
This documentation is automatically deployed to GitHub Pages using GitHub Actions. Here's how it works and how to manage deployments.
|
||||
|
||||
## Automatic Deployment
|
||||
|
||||
The documentation is automatically deployed when changes are pushed to the `main` or `master` branch. The deployment process:
|
||||
|
||||
1. Triggers on push to main/master
|
||||
2. Sets up Python environment
|
||||
3. Installs required dependencies
|
||||
4. Builds the documentation
|
||||
5. Deploys to the `gh-pages` branch
|
||||
|
||||
### GitHub Actions Workflow
|
||||
|
||||
The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`. This is the single source of truth for documentation deployment:
|
||||
|
||||
```yaml
|
||||
name: Deploy MkDocs
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
- master
|
||||
workflow_dispatch: # Allow manual trigger
|
||||
```
|
||||
|
||||
## Manual Deployment
|
||||
|
||||
If needed, you can deploy manually using:
|
||||
|
||||
```bash
|
||||
# Create a virtual environment
|
||||
python -m venv venv
|
||||
|
||||
# Activate the virtual environment
|
||||
source venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r docs/requirements.txt
|
||||
|
||||
# Build the documentation
|
||||
mkdocs build
|
||||
|
||||
# Deploy to GitHub Pages
|
||||
mkdocs gh-deploy --force
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Documentation Updates
|
||||
- Test locally before pushing: `mkdocs serve`
|
||||
- Verify all links work
|
||||
- Ensure images are optimized
|
||||
- Check mobile responsiveness
|
||||
|
||||
### 2. Version Control
|
||||
- Keep documentation in sync with code versions
|
||||
- Use meaningful commit messages
|
||||
- Tag important documentation versions
|
||||
|
||||
### 3. Content Guidelines
|
||||
- Use consistent formatting
|
||||
- Keep navigation structure logical
|
||||
- Include examples where appropriate
|
||||
- Maintain up-to-date screenshots
|
||||
|
||||
### 4. Maintenance
|
||||
- Regularly review and update content
|
||||
- Check for broken links
|
||||
- Update dependencies
|
||||
- Monitor GitHub Actions logs
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Failed Deployments**
|
||||
- Check GitHub Actions logs
|
||||
- Verify dependencies are up to date
|
||||
- Ensure all required files exist
|
||||
|
||||
2. **Broken Links**
|
||||
- Run `mkdocs build --strict`
|
||||
- Use relative paths in markdown
|
||||
- Check case sensitivity
|
||||
|
||||
3. **Style Issues**
|
||||
- Verify theme configuration
|
||||
- Check CSS customizations
|
||||
- Test on multiple browsers
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### requirements.txt
|
||||
|
||||
Create a requirements file for documentation dependencies:
|
||||
|
||||
```txt
|
||||
mkdocs-material
|
||||
mkdocs-minify-plugin
|
||||
mkdocs-git-revision-date-plugin
|
||||
mkdocs-mkdocstrings
|
||||
mkdocs-social-plugin
|
||||
mkdocs-redirects
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
- Check [GitHub Pages settings](https://github.com/jango-blockchained/advanced-homeassistant-mcp/settings/pages)
|
||||
- Monitor build status in Actions tab
|
||||
- Verify site accessibility
|
||||
|
||||
## Workflow Features
|
||||
|
||||
### Caching
|
||||
The workflow implements caching for Python dependencies to speed up deployments:
|
||||
- Pip cache for Python packages
|
||||
- MkDocs dependencies cache
|
||||
|
||||
### Deployment Checks
|
||||
Several checks are performed during deployment:
|
||||
1. Link validation with `mkdocs build --strict`
|
||||
2. Build verification
|
||||
3. Post-deployment site accessibility check
|
||||
|
||||
### Manual Triggers
|
||||
You can manually trigger deployments using the "workflow_dispatch" event in GitHub Actions.
|
||||
|
||||
## Cleanup
|
||||
|
||||
To clean up duplicate workflow files, run:
|
||||
|
||||
```bash
|
||||
# Make the script executable
|
||||
chmod +x scripts/cleanup-workflows.sh
|
||||
|
||||
# Run the cleanup script
|
||||
./scripts/cleanup-workflows.sh
|
||||
```
|
||||
@@ -1,190 +0,0 @@
|
||||
# Development Guide
|
||||
|
||||
This guide provides information for developers who want to contribute to or extend the Home Assistant MCP.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
homeassistant-mcp/
|
||||
├── src/
|
||||
│ ├── __tests__/ # Test files
|
||||
│ ├── __mocks__/ # Mock files
|
||||
│ ├── api/ # API endpoints and route handlers
|
||||
│ ├── config/ # Configuration management
|
||||
│ ├── hass/ # Home Assistant integration
|
||||
│ ├── interfaces/ # TypeScript interfaces
|
||||
│ ├── mcp/ # MCP core functionality
|
||||
│ ├── middleware/ # Express middleware
|
||||
│ ├── routes/ # Route definitions
|
||||
│ ├── security/ # Security utilities
|
||||
│ ├── sse/ # Server-Sent Events handling
|
||||
│ ├── tools/ # Tool implementations
|
||||
│ ├── types/ # TypeScript type definitions
|
||||
│ └── utils/ # Utility functions
|
||||
├── __tests__/ # Test files
|
||||
├── docs/ # Documentation
|
||||
├── dist/ # Compiled JavaScript
|
||||
└── scripts/ # Build and utility scripts
|
||||
```
|
||||
|
||||
## Development Setup
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. Set up development environment:
|
||||
```bash
|
||||
cp .env.example .env.development
|
||||
```
|
||||
|
||||
3. Start development server:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
We follow these coding standards:
|
||||
|
||||
1. TypeScript best practices
|
||||
- Use strict type checking
|
||||
- Avoid `any` types
|
||||
- Document complex types
|
||||
|
||||
2. ESLint rules
|
||||
- Run `npm run lint` to check
|
||||
- Run `npm run lint:fix` to auto-fix
|
||||
|
||||
3. Code formatting
|
||||
- Use Prettier
|
||||
- Run `npm run format` to format code
|
||||
|
||||
## Testing
|
||||
|
||||
1. Unit tests:
|
||||
```bash
|
||||
npm run test
|
||||
```
|
||||
|
||||
2. Integration tests:
|
||||
```bash
|
||||
npm run test:integration
|
||||
```
|
||||
|
||||
3. Coverage report:
|
||||
```bash
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
## Creating New Tools
|
||||
|
||||
1. Create a new file in `src/tools/`:
|
||||
```typescript
|
||||
import { z } from 'zod';
|
||||
import { Tool } from '../types';
|
||||
|
||||
export const myTool: Tool = {
|
||||
name: 'my_tool',
|
||||
description: 'Description of my tool',
|
||||
parameters: z.object({
|
||||
// Define parameters
|
||||
}),
|
||||
execute: async (params) => {
|
||||
// Implement tool logic
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
2. Add to `src/tools/index.ts`
|
||||
3. Create tests in `__tests__/tools/`
|
||||
4. Add documentation in `docs/tools/`
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Write/update tests
|
||||
5. Update documentation
|
||||
6. Submit a pull request
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
1. Ensure all tests pass
|
||||
2. Update documentation
|
||||
3. Update CHANGELOG.md
|
||||
4. Get review from maintainers
|
||||
|
||||
## Building
|
||||
|
||||
1. Development build:
|
||||
```bash
|
||||
npm run build:dev
|
||||
```
|
||||
|
||||
2. Production build:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
1. Update documentation for changes
|
||||
2. Follow documentation structure
|
||||
3. Include examples
|
||||
4. Update type definitions
|
||||
|
||||
## Debugging
|
||||
|
||||
1. Development debugging:
|
||||
```bash
|
||||
npm run dev:debug
|
||||
```
|
||||
|
||||
2. Test debugging:
|
||||
```bash
|
||||
npm run test:debug
|
||||
```
|
||||
|
||||
3. VSCode launch configurations provided
|
||||
|
||||
## Performance
|
||||
|
||||
1. Follow performance best practices
|
||||
2. Use caching where appropriate
|
||||
3. Implement rate limiting
|
||||
4. Monitor memory usage
|
||||
|
||||
## Security
|
||||
|
||||
1. Follow security best practices
|
||||
2. Validate all inputs
|
||||
3. Use proper authentication
|
||||
4. Handle errors securely
|
||||
|
||||
## Deployment
|
||||
|
||||
1. Build for production:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
2. Start production server:
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
3. Docker deployment:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
Need development help?
|
||||
1. Check documentation
|
||||
2. Search issues
|
||||
3. Create new issue
|
||||
4. Join discussions
|
||||
197
docs/development/environment.md
Normal file
197
docs/development/environment.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Development Environment Setup
|
||||
|
||||
This guide will help you set up your development environment for the Home Assistant MCP Server.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Software
|
||||
- Python 3.10 or higher
|
||||
- pip (Python package manager)
|
||||
- git
|
||||
- Docker (optional, for containerized development)
|
||||
- Node.js 18+ (for frontend development)
|
||||
|
||||
### System Requirements
|
||||
- 4GB RAM minimum
|
||||
- 2 CPU cores minimum
|
||||
- 10GB free disk space
|
||||
|
||||
## Initial Setup
|
||||
|
||||
1. Clone the Repository
|
||||
```bash
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
2. Create Virtual Environment
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Linux/macOS
|
||||
# or
|
||||
.venv\Scripts\activate # Windows
|
||||
```
|
||||
|
||||
3. Install Dependencies
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
pip install -r docs/requirements.txt # for documentation
|
||||
```
|
||||
|
||||
## Development Tools
|
||||
|
||||
### Code Editor Setup
|
||||
We recommend using Visual Studio Code with these extensions:
|
||||
- Python
|
||||
- Docker
|
||||
- YAML
|
||||
- ESLint
|
||||
- Prettier
|
||||
|
||||
### VS Code Settings
|
||||
```json
|
||||
{
|
||||
"python.linting.enabled": true,
|
||||
"python.linting.pylintEnabled": true,
|
||||
"python.formatting.provider": "black",
|
||||
"editor.formatOnSave": true
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
1. Create Local Config
|
||||
```bash
|
||||
cp config.example.yaml config.yaml
|
||||
```
|
||||
|
||||
2. Set Environment Variables
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Unit Tests
|
||||
```bash
|
||||
pytest tests/unit
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
```bash
|
||||
pytest tests/integration
|
||||
```
|
||||
|
||||
### Coverage Report
|
||||
```bash
|
||||
pytest --cov=src tests/
|
||||
```
|
||||
|
||||
## Docker Development
|
||||
|
||||
### Build Container
|
||||
```bash
|
||||
docker build -t mcp-server-dev -f Dockerfile.dev .
|
||||
```
|
||||
|
||||
### Run Development Container
|
||||
```bash
|
||||
docker run -it --rm \
|
||||
-v $(pwd):/app \
|
||||
-p 8123:8123 \
|
||||
mcp-server-dev
|
||||
```
|
||||
|
||||
## Database Setup
|
||||
|
||||
### Local Development Database
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 5432:5432 \
|
||||
-e POSTGRES_USER=mcp \
|
||||
-e POSTGRES_PASSWORD=development \
|
||||
-e POSTGRES_DB=mcp_dev \
|
||||
postgres:14
|
||||
```
|
||||
|
||||
### Run Migrations
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
## Frontend Development
|
||||
|
||||
1. Install Node.js Dependencies
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
2. Start Development Server
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
### Build Documentation
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
### View Documentation
|
||||
Open http://localhost:8000 in your browser
|
||||
|
||||
## Debugging
|
||||
|
||||
### VS Code Launch Configuration
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Python: MCP Server",
|
||||
"type": "python",
|
||||
"request": "launch",
|
||||
"program": "src/main.py",
|
||||
"console": "integratedTerminal"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
|
||||
### Install Pre-commit
|
||||
```bash
|
||||
pip install pre-commit
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
### Available Hooks
|
||||
- black (code formatting)
|
||||
- flake8 (linting)
|
||||
- isort (import sorting)
|
||||
- mypy (type checking)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common Issues:
|
||||
1. Port already in use
|
||||
- Check for running processes: `lsof -i :8123`
|
||||
- Kill process if needed: `kill -9 PID`
|
||||
|
||||
2. Database connection issues
|
||||
- Verify PostgreSQL is running
|
||||
- Check connection settings in .env
|
||||
|
||||
3. Virtual environment problems
|
||||
- Delete and recreate: `rm -rf .venv && python -m venv .venv`
|
||||
- Reinstall dependencies
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Review the [Architecture Guide](../architecture.md)
|
||||
2. Check [Contributing Guidelines](../contributing.md)
|
||||
3. Start with [Simple Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
||||
54
docs/development/index.md
Normal file
54
docs/development/index.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Development Guide
|
||||
|
||||
Welcome to the development guide for the Home Assistant MCP Server. This section provides comprehensive information for developers who want to contribute to or extend the project.
|
||||
|
||||
## Development Overview
|
||||
|
||||
The MCP Server is built with modern development practices in mind, focusing on:
|
||||
|
||||
- Clean, maintainable code
|
||||
- Comprehensive testing
|
||||
- Clear documentation
|
||||
- Modular architecture
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Set up your development environment
|
||||
2. Fork the repository
|
||||
3. Install dependencies
|
||||
4. Run tests
|
||||
5. Make your changes
|
||||
6. Submit a pull request
|
||||
|
||||
## Development Topics
|
||||
|
||||
- [Architecture](../architecture.md) - System architecture and design
|
||||
- [Contributing](../contributing.md) - Contribution guidelines
|
||||
- [Testing](../testing.md) - Testing framework and guidelines
|
||||
- [Troubleshooting](../troubleshooting.md) - Common issues and solutions
|
||||
- [Deployment](../deployment.md) - Deployment procedures
|
||||
- [Roadmap](../roadmap.md) - Future development plans
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Follow the coding style guide
|
||||
- Write comprehensive tests
|
||||
- Document your changes
|
||||
- Keep commits atomic
|
||||
- Use meaningful commit messages
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. Create a feature branch
|
||||
2. Make your changes
|
||||
3. Run tests
|
||||
4. Update documentation
|
||||
5. Submit a pull request
|
||||
6. Address review comments
|
||||
7. Merge when approved
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Review the [Architecture](../architecture.md)
|
||||
- Check [Contributing Guidelines](../contributing.md)
|
||||
- Set up your [Development Environment](environment.md)
|
||||
212
docs/features/speech.md
Normal file
212
docs/features/speech.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# Speech Features
|
||||
|
||||
The Home Assistant MCP Server includes powerful speech processing capabilities powered by fast-whisper and custom wake word detection. This guide explains how to set up and use these features effectively.
|
||||
|
||||
## Overview
|
||||
|
||||
The speech processing system consists of two main components:
|
||||
1. Wake Word Detection - Listens for specific trigger phrases
|
||||
2. Speech-to-Text - Transcribes spoken commands using fast-whisper
|
||||
|
||||
## Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Docker environment:
|
||||
```bash
|
||||
docker --version # Should be 20.10.0 or higher
|
||||
```
|
||||
|
||||
2. For GPU acceleration:
|
||||
- NVIDIA GPU with CUDA support
|
||||
- NVIDIA Container Toolkit installed
|
||||
- NVIDIA drivers 450.80.02 or higher
|
||||
|
||||
### Installation
|
||||
|
||||
1. Enable speech features in your `.env`:
|
||||
```bash
|
||||
ENABLE_SPEECH_FEATURES=true
|
||||
ENABLE_WAKE_WORD=true
|
||||
ENABLE_SPEECH_TO_TEXT=true
|
||||
```
|
||||
|
||||
2. Configure model settings:
|
||||
```bash
|
||||
WHISPER_MODEL_PATH=/models
|
||||
WHISPER_MODEL_TYPE=base
|
||||
WHISPER_LANGUAGE=en
|
||||
WHISPER_TASK=transcribe
|
||||
WHISPER_DEVICE=cuda # or cpu
|
||||
```
|
||||
|
||||
3. Start the services:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Wake Word Detection
|
||||
|
||||
The wake word detector continuously listens for configured trigger phrases. Default wake words:
|
||||
- "hey jarvis"
|
||||
- "ok google"
|
||||
- "alexa"
|
||||
|
||||
Custom wake words can be configured:
|
||||
```bash
|
||||
WAKE_WORDS=computer,jarvis,assistant
|
||||
```
|
||||
|
||||
When a wake word is detected:
|
||||
1. The system starts recording audio
|
||||
2. Audio is processed through the speech-to-text pipeline
|
||||
3. The resulting command is processed by the server
|
||||
|
||||
### Speech-to-Text
|
||||
|
||||
#### Automatic Transcription
|
||||
|
||||
After wake word detection:
|
||||
1. Audio is automatically captured (default: 5 seconds)
|
||||
2. The audio is transcribed using the configured whisper model
|
||||
3. The transcribed text is processed as a command
|
||||
|
||||
#### Manual Transcription
|
||||
|
||||
You can also manually transcribe audio using the API:
|
||||
|
||||
```typescript
|
||||
// Using the TypeScript client
|
||||
import { SpeechService } from '@ha-mcp/client';
|
||||
|
||||
const speech = new SpeechService();
|
||||
|
||||
// Transcribe from audio buffer
|
||||
const buffer = await getAudioBuffer();
|
||||
const text = await speech.transcribe(buffer);
|
||||
|
||||
// Transcribe from file
|
||||
const text = await speech.transcribeFile('command.wav');
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Using the REST API
|
||||
POST /api/speech/transcribe
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
file: <audio file>
|
||||
```
|
||||
|
||||
### Event Handling
|
||||
|
||||
The system emits various events during speech processing:
|
||||
|
||||
```typescript
|
||||
speech.on('wakeWord', (word: string) => {
|
||||
console.log(`Wake word detected: ${word}`);
|
||||
});
|
||||
|
||||
speech.on('listening', () => {
|
||||
console.log('Listening for command...');
|
||||
});
|
||||
|
||||
speech.on('transcribing', () => {
|
||||
console.log('Processing speech...');
|
||||
});
|
||||
|
||||
speech.on('transcribed', (text: string) => {
|
||||
console.log(`Transcribed text: ${text}`);
|
||||
});
|
||||
|
||||
speech.on('error', (error: Error) => {
|
||||
console.error('Speech processing error:', error);
|
||||
});
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Model Selection
|
||||
|
||||
Choose an appropriate model based on your needs:
|
||||
|
||||
1. Resource-constrained environments:
|
||||
- Use `tiny.en` or `base.en`
|
||||
- Run on CPU if GPU unavailable
|
||||
- Limit concurrent processing
|
||||
|
||||
2. High-accuracy requirements:
|
||||
- Use `small.en` or `medium.en`
|
||||
- Enable GPU acceleration
|
||||
- Increase audio quality
|
||||
|
||||
3. Production environments:
|
||||
- Use `base.en` or `small.en`
|
||||
- Enable GPU acceleration
|
||||
- Configure appropriate timeouts
|
||||
|
||||
### GPU Acceleration
|
||||
|
||||
When using GPU acceleration:
|
||||
|
||||
1. Monitor GPU memory usage:
|
||||
```bash
|
||||
nvidia-smi -l 1
|
||||
```
|
||||
|
||||
2. Adjust model size if needed:
|
||||
```bash
|
||||
WHISPER_MODEL_TYPE=small # Decrease if GPU memory limited
|
||||
```
|
||||
|
||||
3. Configure processing device:
|
||||
```bash
|
||||
WHISPER_DEVICE=cuda # Use GPU
|
||||
WHISPER_DEVICE=cpu # Use CPU if GPU unavailable
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. Wake word detection not working:
|
||||
- Check microphone permissions
|
||||
- Adjust `WAKE_WORD_SENSITIVITY`
|
||||
- Verify wake words configuration
|
||||
|
||||
2. Poor transcription quality:
|
||||
- Check audio input quality
|
||||
- Try a larger model
|
||||
- Verify language settings
|
||||
|
||||
3. Performance issues:
|
||||
- Monitor resource usage
|
||||
- Consider smaller model
|
||||
- Check GPU acceleration status
|
||||
|
||||
### Logging
|
||||
|
||||
Enable debug logging for detailed information:
|
||||
```bash
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
Speech-specific logs will be tagged with `[SPEECH]` prefix.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. Audio Privacy:
|
||||
- Audio is processed locally
|
||||
- No data sent to external services
|
||||
- Temporary files automatically cleaned
|
||||
|
||||
2. Access Control:
|
||||
- Speech endpoints require authentication
|
||||
- Rate limiting applies to transcription
|
||||
- Configurable command restrictions
|
||||
|
||||
3. Resource Protection:
|
||||
- Timeouts prevent hanging
|
||||
- Memory limits enforced
|
||||
- Graceful error handling
|
||||
@@ -1,30 +0,0 @@
|
||||
# Getting Started
|
||||
|
||||
Begin your journey with the Home Assistant MCP Server by following these steps:
|
||||
|
||||
- **API Documentation:** Read the [API Documentation](api.md) for available endpoints.
|
||||
- **Real-Time Updates:** Learn about [Server-Sent Events](api/sse.md) for live communication.
|
||||
- **Tools:** Explore available [Tools](tools/tools.md) for device control and automation.
|
||||
- **Configuration:** Refer to the [Configuration Guide](getting-started/configuration.md) for setup and advanced settings.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you encounter any issues:
|
||||
1. Verify that your Home Assistant instance is accessible.
|
||||
2. Ensure that all required environment variables are properly set.
|
||||
3. Consult the [Troubleshooting Guide](troubleshooting.md) for additional solutions.
|
||||
|
||||
## Development
|
||||
|
||||
For contributors:
|
||||
1. Fork the repository.
|
||||
2. Create a feature branch.
|
||||
3. Follow the [Development Guide](development/development.md) for contribution guidelines.
|
||||
4. Submit a pull request with your enhancements.
|
||||
|
||||
## Support
|
||||
|
||||
Need help?
|
||||
- Visit our [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues).
|
||||
- Review the [Troubleshooting Guide](troubleshooting.md).
|
||||
- Check the [FAQ](troubleshooting.md#faq) for common questions.
|
||||
8
docs/getting-started/index.md
Normal file
8
docs/getting-started/index.md
Normal file
@@ -0,0 +1,8 @@
|
||||
# Getting Started
|
||||
|
||||
Welcome to the Advanced Home Assistant MCP getting started guide. Follow these steps to begin:
|
||||
|
||||
1. [Installation](installation.md)
|
||||
2. [Configuration](configuration.md)
|
||||
3. [Docker Setup](docker.md)
|
||||
4. [Quick Start](quickstart.md)
|
||||
@@ -4,31 +4,34 @@ title: Home
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# 🚀 MCP Server for Home Assistant
|
||||
# Advanced Home Assistant MCP
|
||||
|
||||
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 Advanced Home Assistant Master Control Program documentation.
|
||||
|
||||
This documentation provides comprehensive information about setting up, configuring, and using the Advanced Home Assistant MCP system.
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Getting Started](getting-started/index.md)
|
||||
- [API Reference](api/index.md)
|
||||
- [Configuration Guide](getting-started/configuration.md)
|
||||
- [Docker Setup](getting-started/docker.md)
|
||||
|
||||
## 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 +40,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.
|
||||
62
docs/javascripts/extra.js
Normal file
62
docs/javascripts/extra.js
Normal file
@@ -0,0 +1,62 @@
|
||||
// Dark mode handling
|
||||
document.addEventListener('DOMContentLoaded', function () {
|
||||
// Check for saved dark mode preference
|
||||
const darkMode = localStorage.getItem('darkMode');
|
||||
if (darkMode === 'true') {
|
||||
document.body.classList.add('dark-mode');
|
||||
}
|
||||
});
|
||||
|
||||
// Smooth scrolling for anchor links
|
||||
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
|
||||
anchor.addEventListener('click', function (e) {
|
||||
e.preventDefault();
|
||||
document.querySelector(this.getAttribute('href')).scrollIntoView({
|
||||
behavior: 'smooth'
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// Add copy button to code blocks
|
||||
document.querySelectorAll('pre code').forEach((block) => {
|
||||
const button = document.createElement('button');
|
||||
button.className = 'copy-button';
|
||||
button.textContent = 'Copy';
|
||||
|
||||
button.addEventListener('click', async () => {
|
||||
await navigator.clipboard.writeText(block.textContent);
|
||||
button.textContent = 'Copied!';
|
||||
setTimeout(() => {
|
||||
button.textContent = 'Copy';
|
||||
}, 2000);
|
||||
});
|
||||
|
||||
const pre = block.parentNode;
|
||||
pre.insertBefore(button, block);
|
||||
});
|
||||
|
||||
// Add version selector handling
|
||||
const versionSelector = document.querySelector('.version-selector');
|
||||
if (versionSelector) {
|
||||
versionSelector.addEventListener('change', (e) => {
|
||||
const version = e.target.value;
|
||||
window.location.href = `/${version}/`;
|
||||
});
|
||||
}
|
||||
|
||||
// Add feedback handling
|
||||
document.querySelectorAll('.feedback-button').forEach(button => {
|
||||
button.addEventListener('click', function () {
|
||||
const feedback = this.getAttribute('data-feedback');
|
||||
// Send feedback to analytics
|
||||
if (typeof gtag !== 'undefined') {
|
||||
gtag('event', 'feedback', {
|
||||
'event_category': 'Documentation',
|
||||
'event_label': feedback
|
||||
});
|
||||
}
|
||||
// Show thank you message
|
||||
this.textContent = 'Thank you!';
|
||||
this.disabled = true;
|
||||
});
|
||||
});
|
||||
12
docs/javascripts/mathjax.js
Normal file
12
docs/javascripts/mathjax.js
Normal file
@@ -0,0 +1,12 @@
|
||||
window.MathJax = {
|
||||
tex: {
|
||||
inlineMath: [["\\(", "\\)"]],
|
||||
displayMath: [["\\[", "\\]"]],
|
||||
processEscapes: true,
|
||||
processEnvironments: true
|
||||
},
|
||||
options: {
|
||||
ignoreHtmlClass: ".*|",
|
||||
processHtmlClass: "arithmatex"
|
||||
}
|
||||
};
|
||||
42
docs/requirements.txt
Normal file
42
docs/requirements.txt
Normal file
@@ -0,0 +1,42 @@
|
||||
# Core
|
||||
mkdocs>=1.5.3
|
||||
mkdocs-material>=9.5.3
|
||||
|
||||
# Enhanced Functionality
|
||||
mkdocs-minify-plugin>=0.7.1
|
||||
mkdocs-git-revision-date-localized-plugin>=1.2.1
|
||||
mkdocs-glightbox>=0.3.4
|
||||
mkdocs-git-authors-plugin>=0.7.2
|
||||
mkdocs-git-committers-plugin>=0.2.3
|
||||
mkdocs-static-i18n>=1.2.0
|
||||
mkdocs-awesome-pages-plugin>=2.9.2
|
||||
mkdocs-redirects>=1.2.1
|
||||
mkdocs-include-markdown-plugin>=6.0.4
|
||||
mkdocs-macros-plugin>=1.0.4
|
||||
mkdocs-meta-descriptions-plugin>=3.0.0
|
||||
mkdocs-print-site-plugin>=2.3.6
|
||||
|
||||
# Code Documentation
|
||||
mkdocstrings>=0.24.0
|
||||
mkdocstrings-python>=1.7.5
|
||||
|
||||
# Markdown Extensions
|
||||
pymdown-extensions>=10.5
|
||||
markdown>=3.5.1
|
||||
mdx_truly_sane_lists>=1.3
|
||||
pygments>=2.17.2
|
||||
|
||||
# Math Support
|
||||
python-markdown-math>=0.8
|
||||
|
||||
# Diagrams
|
||||
plantuml-markdown>=3.9.2
|
||||
mkdocs-mermaid2-plugin>=1.1.1
|
||||
|
||||
# Search Enhancements
|
||||
mkdocs-material[imaging]>=9.5.3
|
||||
pillow>=10.2.0
|
||||
cairosvg>=2.7.1
|
||||
|
||||
# Development Tools
|
||||
mike>=2.0.0 # For version management
|
||||
@@ -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.*
|
||||
146
docs/security.md
Normal file
146
docs/security.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Security Guide
|
||||
|
||||
This document outlines security best practices and configurations for the Home Assistant MCP Server.
|
||||
|
||||
## Authentication
|
||||
|
||||
### JWT Authentication
|
||||
The server uses JWT (JSON Web Tokens) for API authentication:
|
||||
|
||||
```http
|
||||
Authorization: Bearer YOUR_JWT_TOKEN
|
||||
```
|
||||
|
||||
### Token Configuration
|
||||
```yaml
|
||||
security:
|
||||
jwt_secret: YOUR_SECRET_KEY
|
||||
token_expiry: 24h
|
||||
refresh_token_expiry: 7d
|
||||
```
|
||||
|
||||
## Access Control
|
||||
|
||||
### CORS Configuration
|
||||
Configure allowed origins to prevent unauthorized access:
|
||||
|
||||
```yaml
|
||||
security:
|
||||
allowed_origins:
|
||||
- http://localhost:3000
|
||||
- https://your-domain.com
|
||||
```
|
||||
|
||||
### IP Filtering
|
||||
Restrict access by IP address:
|
||||
|
||||
```yaml
|
||||
security:
|
||||
allowed_ips:
|
||||
- 192.168.1.0/24
|
||||
- 10.0.0.0/8
|
||||
```
|
||||
|
||||
## SSL/TLS Configuration
|
||||
|
||||
### Enable HTTPS
|
||||
```yaml
|
||||
ssl:
|
||||
enabled: true
|
||||
cert_file: /path/to/cert.pem
|
||||
key_file: /path/to/key.pem
|
||||
```
|
||||
|
||||
### Certificate Management
|
||||
1. Use Let's Encrypt for free SSL certificates
|
||||
2. Regularly renew certificates
|
||||
3. Monitor certificate expiration
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### Basic Rate Limiting
|
||||
```yaml
|
||||
rate_limit:
|
||||
enabled: true
|
||||
requests_per_minute: 100
|
||||
burst: 20
|
||||
```
|
||||
|
||||
### Advanced Rate Limiting
|
||||
```yaml
|
||||
rate_limit:
|
||||
rules:
|
||||
- endpoint: /api/control
|
||||
requests_per_minute: 50
|
||||
- endpoint: /api/state
|
||||
requests_per_minute: 200
|
||||
```
|
||||
|
||||
## Data Protection
|
||||
|
||||
### Sensitive Data
|
||||
- Use environment variables for secrets
|
||||
- Encrypt sensitive data at rest
|
||||
- Implement secure backup procedures
|
||||
|
||||
### Logging Security
|
||||
- Avoid logging sensitive information
|
||||
- Rotate logs regularly
|
||||
- Protect log file access
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Regular Security Updates
|
||||
- Keep dependencies updated
|
||||
- Monitor security advisories
|
||||
- Apply patches promptly
|
||||
|
||||
2. Password Policies
|
||||
- Enforce strong passwords
|
||||
- Implement password expiration
|
||||
- Use secure password storage
|
||||
|
||||
3. Monitoring
|
||||
- Log security events
|
||||
- Monitor access patterns
|
||||
- Set up alerts for suspicious activity
|
||||
|
||||
4. Network Security
|
||||
- Use VPN for remote access
|
||||
- Implement network segmentation
|
||||
- Configure firewalls properly
|
||||
|
||||
## Security Checklist
|
||||
|
||||
- [ ] Configure SSL/TLS
|
||||
- [ ] Set up JWT authentication
|
||||
- [ ] Configure CORS properly
|
||||
- [ ] Enable rate limiting
|
||||
- [ ] Implement IP filtering
|
||||
- [ ] Secure sensitive data
|
||||
- [ ] Set up monitoring
|
||||
- [ ] Configure backup encryption
|
||||
- [ ] Update security policies
|
||||
|
||||
## Incident Response
|
||||
|
||||
1. Detection
|
||||
- Monitor security logs
|
||||
- Set up intrusion detection
|
||||
- Configure alerts
|
||||
|
||||
2. Response
|
||||
- Document incident details
|
||||
- Isolate affected systems
|
||||
- Investigate root cause
|
||||
|
||||
3. Recovery
|
||||
- Apply security fixes
|
||||
- Restore from backups
|
||||
- Update security measures
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Security Best Practices](https://owasp.org/www-project-top-ten/)
|
||||
- [JWT Security](https://jwt.io/introduction)
|
||||
- [SSL Configuration](https://ssl-config.mozilla.org/)
|
||||
164
docs/stylesheets/extra.css
Normal file
164
docs/stylesheets/extra.css
Normal file
@@ -0,0 +1,164 @@
|
||||
/* Modern Dark Theme Enhancements */
|
||||
[data-md-color-scheme="slate"] {
|
||||
--md-default-bg-color: #1a1b26;
|
||||
--md-default-fg-color: #a9b1d6;
|
||||
--md-default-fg-color--light: #a9b1d6;
|
||||
--md-default-fg-color--lighter: #787c99;
|
||||
--md-default-fg-color--lightest: #4e5173;
|
||||
--md-primary-fg-color: #7aa2f7;
|
||||
--md-primary-fg-color--light: #7dcfff;
|
||||
--md-primary-fg-color--dark: #2ac3de;
|
||||
--md-accent-fg-color: #bb9af7;
|
||||
--md-accent-fg-color--transparent: #bb9af722;
|
||||
--md-accent-bg-color: #1a1b26;
|
||||
--md-accent-bg-color--light: #24283b;
|
||||
}
|
||||
|
||||
/* Code Blocks */
|
||||
.highlight pre {
|
||||
background-color: #24283b !important;
|
||||
border-radius: 6px;
|
||||
padding: 1em;
|
||||
margin: 1em 0;
|
||||
overflow: auto;
|
||||
}
|
||||
|
||||
.highlight code {
|
||||
font-family: 'Roboto Mono', monospace;
|
||||
font-size: 0.9em;
|
||||
}
|
||||
|
||||
/* Copy Button */
|
||||
.copy-button {
|
||||
position: absolute;
|
||||
right: 0.5em;
|
||||
top: 0.5em;
|
||||
padding: 0.4em 0.8em;
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border: 1px solid var(--md-accent-fg-color--transparent);
|
||||
border-radius: 4px;
|
||||
color: var(--md-default-fg-color);
|
||||
font-size: 0.8em;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s ease;
|
||||
}
|
||||
|
||||
.copy-button:hover {
|
||||
background-color: var(--md-accent-fg-color--transparent);
|
||||
border-color: var(--md-accent-fg-color);
|
||||
}
|
||||
|
||||
/* Navigation Enhancements */
|
||||
.md-nav {
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
.md-nav__link {
|
||||
padding: 0.4rem 0;
|
||||
transition: color 0.2s ease;
|
||||
}
|
||||
|
||||
.md-nav__link:hover {
|
||||
color: var(--md-primary-fg-color) !important;
|
||||
}
|
||||
|
||||
/* Tabs */
|
||||
.md-tabs__link {
|
||||
opacity: 0.8;
|
||||
transition: opacity 0.2s ease;
|
||||
}
|
||||
|
||||
.md-tabs__link:hover {
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
.md-tabs__link--active {
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
/* Admonitions */
|
||||
.md-typeset .admonition,
|
||||
.md-typeset details {
|
||||
border-width: 0;
|
||||
border-left-width: 4px;
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
/* Tables */
|
||||
.md-typeset table:not([class]) {
|
||||
border-radius: 4px;
|
||||
box-shadow: 0 2px 4px var(--md-accent-fg-color--transparent);
|
||||
}
|
||||
|
||||
.md-typeset table:not([class]) th {
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border-bottom: 2px solid var(--md-accent-fg-color--transparent);
|
||||
}
|
||||
|
||||
/* Search */
|
||||
.md-search__form {
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
/* Feedback Buttons */
|
||||
.feedback-button {
|
||||
padding: 0.5em 1em;
|
||||
margin: 0 0.5em;
|
||||
border-radius: 4px;
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border: 1px solid var(--md-accent-fg-color--transparent);
|
||||
color: var(--md-default-fg-color);
|
||||
cursor: pointer;
|
||||
transition: all 0.2s ease;
|
||||
}
|
||||
|
||||
.feedback-button:hover {
|
||||
background-color: var(--md-accent-fg-color--transparent);
|
||||
border-color: var(--md-accent-fg-color);
|
||||
}
|
||||
|
||||
.feedback-button:disabled {
|
||||
opacity: 0.5;
|
||||
cursor: not-allowed;
|
||||
}
|
||||
|
||||
/* Version Selector */
|
||||
.version-selector {
|
||||
padding: 0.5em;
|
||||
border-radius: 4px;
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border: 1px solid var(--md-accent-fg-color--transparent);
|
||||
color: var(--md-default-fg-color);
|
||||
}
|
||||
|
||||
/* Scrollbar */
|
||||
::-webkit-scrollbar {
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-track {
|
||||
background: var(--md-accent-bg-color--light);
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb {
|
||||
background: var(--md-accent-fg-color--transparent);
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb:hover {
|
||||
background: var(--md-accent-fg-color);
|
||||
}
|
||||
|
||||
/* Print Styles */
|
||||
@media print {
|
||||
.md-typeset a {
|
||||
color: var(--md-default-fg-color) !important;
|
||||
}
|
||||
|
||||
.md-content__inner {
|
||||
margin: 0;
|
||||
padding: 1rem;
|
||||
}
|
||||
}
|
||||
42
docs/tools/index.md
Normal file
42
docs/tools/index.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Tools Overview
|
||||
|
||||
The Home Assistant MCP Server provides a variety of tools to help you manage and interact with your home automation system.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### Device Management
|
||||
- [List Devices](device-management/list-devices.md) - View and manage connected devices
|
||||
- [Device Control](device-management/control.md) - Control device states and settings
|
||||
|
||||
### History & State
|
||||
- [History](history-state/history.md) - View and analyze historical data
|
||||
- [Scene Management](history-state/scene.md) - Create and manage scenes
|
||||
|
||||
### Automation
|
||||
- [Automation Management](automation/automation.md) - Create and manage automations
|
||||
- [Automation Configuration](automation/automation-config.md) - Configure automation settings
|
||||
|
||||
### Add-ons & Packages
|
||||
- [Add-on Management](addons-packages/addon.md) - Manage server add-ons
|
||||
- [Package Management](addons-packages/package.md) - Handle package installations
|
||||
|
||||
### Notifications
|
||||
- [Notify](notifications/notify.md) - Send and manage notifications
|
||||
|
||||
### Events
|
||||
- [Event Subscription](events/subscribe-events.md) - Subscribe to system events
|
||||
- [SSE Statistics](events/sse-stats.md) - Monitor Server-Sent Events statistics
|
||||
|
||||
## Getting Started
|
||||
|
||||
To get started with these tools:
|
||||
|
||||
1. Ensure you have the MCP Server properly installed and configured
|
||||
2. Check the specific tool documentation for detailed usage instructions
|
||||
3. Use the API endpoints or command-line interface as needed
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Review the [API Documentation](../api/index.md) for programmatic access
|
||||
- Check [Configuration](../config/index.md) for tool-specific settings
|
||||
- See [Examples](../examples/index.md) for practical use cases
|
||||
@@ -1,127 +0,0 @@
|
||||
# Home Assistant MCP Tools
|
||||
|
||||
This section documents all available tools in the Home Assistant MCP.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### Device Management
|
||||
|
||||
1. [List Devices](device-management/list-devices.md)
|
||||
- List all available Home Assistant devices
|
||||
- Group devices by domain
|
||||
- Get device states and attributes
|
||||
|
||||
2. [Device Control](device-management/control.md)
|
||||
- Control various device types
|
||||
- Support for lights, switches, covers, climate devices
|
||||
- Domain-specific commands and parameters
|
||||
|
||||
### History and State
|
||||
|
||||
1. [History](history-state/history.md)
|
||||
- Fetch device state history
|
||||
- Filter by time range
|
||||
- Get significant changes
|
||||
|
||||
2. [Scene Management](history-state/scene.md)
|
||||
- List available scenes
|
||||
- Activate scenes
|
||||
- Scene state information
|
||||
|
||||
### Automation
|
||||
|
||||
1. [Automation Management](automation/automation.md)
|
||||
- List automations
|
||||
- Toggle automation state
|
||||
- Trigger automations manually
|
||||
|
||||
2. [Automation Configuration](automation/automation-config.md)
|
||||
- Create new automations
|
||||
- Update existing automations
|
||||
- Delete automations
|
||||
- Duplicate automations
|
||||
|
||||
### Add-ons and Packages
|
||||
|
||||
1. [Add-on Management](addons-packages/addon.md)
|
||||
- List available add-ons
|
||||
- Install/uninstall add-ons
|
||||
- Start/stop/restart add-ons
|
||||
- Get add-on information
|
||||
|
||||
2. [Package Management](addons-packages/package.md)
|
||||
- Manage HACS packages
|
||||
- Install/update/remove packages
|
||||
- List available packages by category
|
||||
|
||||
### Notifications
|
||||
|
||||
1. [Notify](notifications/notify.md)
|
||||
- Send notifications
|
||||
- Support for multiple notification services
|
||||
- Custom notification data
|
||||
|
||||
### Real-time Events
|
||||
|
||||
1. [Event Subscription](events/subscribe-events.md)
|
||||
- Subscribe to Home Assistant events
|
||||
- Monitor specific entities
|
||||
- Domain-based monitoring
|
||||
|
||||
2. [SSE Statistics](events/sse-stats.md)
|
||||
- Get SSE connection statistics
|
||||
- Monitor active subscriptions
|
||||
- Connection management
|
||||
|
||||
## Using Tools
|
||||
|
||||
All tools can be accessed through:
|
||||
|
||||
1. REST API endpoints
|
||||
2. WebSocket connections
|
||||
3. Server-Sent Events (SSE)
|
||||
|
||||
### Authentication
|
||||
|
||||
Tools require authentication using:
|
||||
- Home Assistant Long-Lived Access Token
|
||||
- JWT tokens for specific operations
|
||||
|
||||
### Error Handling
|
||||
|
||||
All tools follow a consistent error handling pattern:
|
||||
```typescript
|
||||
{
|
||||
success: boolean;
|
||||
message?: string;
|
||||
data?: any;
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
Tools are subject to rate limiting:
|
||||
- Default: 100 requests per 15 minutes
|
||||
- Configurable through environment variables
|
||||
|
||||
## Tool Development
|
||||
|
||||
Want to create a new tool? Check out:
|
||||
- [Tool Development Guide](../development/tools.md)
|
||||
- [Tool Interface Documentation](../development/interfaces.md)
|
||||
- [Best Practices](../development/best-practices.md)
|
||||
|
||||
## Examples
|
||||
|
||||
Each tool documentation includes:
|
||||
- Usage examples
|
||||
- Code snippets
|
||||
- Common use cases
|
||||
- Troubleshooting tips
|
||||
|
||||
## Support
|
||||
|
||||
Need help with tools?
|
||||
- Check individual tool documentation
|
||||
- See [Troubleshooting Guide](../troubleshooting.md)
|
||||
- Create an issue on GitHub
|
||||
100
docs/usage.md
100
docs/usage.md
@@ -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)
|
||||
270
mkdocs.yml
270
mkdocs.yml
@@ -1,100 +1,220 @@
|
||||
site_name: Home Assistant MCP
|
||||
site_description: A bridge between Home Assistant and Language Learning Models
|
||||
site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp/
|
||||
site_name: MCP Server for Home Assistant
|
||||
site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp
|
||||
repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
|
||||
repo_name: jango-blockchained/advanced-homeassistant-mcp
|
||||
site_description: Home Assistant MCP Server Documentation
|
||||
# Add this to handle GitHub Pages serving from a subdirectory
|
||||
site_dir: site/advanced-homeassistant-mcp
|
||||
|
||||
theme:
|
||||
name: material
|
||||
logo: assets/images/logo.png
|
||||
favicon: assets/images/favicon.ico
|
||||
palette:
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Switch to dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to light mode
|
||||
|
||||
# Modern Features
|
||||
features:
|
||||
- navigation.instant
|
||||
- navigation.tracking
|
||||
# Navigation Enhancements
|
||||
- navigation.tabs
|
||||
- navigation.tabs.sticky
|
||||
- navigation.indexes
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- navigation.top
|
||||
- navigation.path
|
||||
- navigation.footer
|
||||
- navigation.prune
|
||||
- navigation.tracking
|
||||
- navigation.instant
|
||||
|
||||
# UI Elements
|
||||
- header.autohide
|
||||
- toc.integrate
|
||||
- toc.follow
|
||||
- announce.dismiss
|
||||
|
||||
# Search Features
|
||||
- search.suggest
|
||||
- search.highlight
|
||||
- search.share
|
||||
|
||||
# Code Features
|
||||
- content.code.annotate
|
||||
- content.code.copy
|
||||
- content.code.select
|
||||
- content.tabs.link
|
||||
- content.tooltips
|
||||
|
||||
# Theme Configuration
|
||||
palette:
|
||||
# Dark mode as primary
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
primary: deep-purple
|
||||
accent: purple
|
||||
toggle:
|
||||
icon: material/weather-sunny
|
||||
name: Switch to light mode
|
||||
# Light mode as secondary
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
primary: deep-purple
|
||||
accent: purple
|
||||
toggle:
|
||||
icon: material/weather-night
|
||||
name: Switch to dark mode
|
||||
|
||||
font:
|
||||
text: Roboto
|
||||
code: Roboto Mono
|
||||
|
||||
icon:
|
||||
repo: fontawesome/brands/github
|
||||
edit: material/pencil
|
||||
view: material/eye
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- attr_list
|
||||
- def_list
|
||||
- footnotes
|
||||
- meta
|
||||
- toc:
|
||||
permalink: true
|
||||
- pymdownx.arithmatex:
|
||||
generic: true
|
||||
- pymdownx.betterem:
|
||||
smart_enable: all
|
||||
- pymdownx.caret
|
||||
- pymdownx.details
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
# Modern Code Highlighting
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
|
||||
# Advanced Formatting
|
||||
- pymdownx.critic
|
||||
- pymdownx.caret
|
||||
- pymdownx.keys
|
||||
- pymdownx.magiclink
|
||||
- pymdownx.mark
|
||||
- pymdownx.smartsymbols
|
||||
- pymdownx.tilde
|
||||
|
||||
# Interactive Elements
|
||||
- pymdownx.details
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
|
||||
# Diagrams & Formatting
|
||||
- pymdownx.superfences:
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- pymdownx.tilde
|
||||
- pymdownx.arithmatex:
|
||||
generic: true
|
||||
|
||||
# Additional Extensions
|
||||
- admonition
|
||||
- attr_list
|
||||
- md_in_html
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
- footnotes
|
||||
- tables
|
||||
- def_list
|
||||
- abbr
|
||||
|
||||
plugins:
|
||||
- search
|
||||
- git-revision-date-localized:
|
||||
type: date
|
||||
- mkdocstrings:
|
||||
default_handler: python
|
||||
handlers:
|
||||
python:
|
||||
options:
|
||||
show_source: true
|
||||
# Core Plugins
|
||||
- search:
|
||||
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
|
||||
- minify:
|
||||
minify_html: true
|
||||
- mkdocstrings
|
||||
|
||||
# Advanced Features
|
||||
- social:
|
||||
cards: false
|
||||
- tags
|
||||
- offline
|
||||
|
||||
# Version Management
|
||||
- git-revision-date-localized:
|
||||
enable_creation_date: true
|
||||
type: date
|
||||
|
||||
extra:
|
||||
# Consent Management
|
||||
consent:
|
||||
title: Cookie consent
|
||||
description: >-
|
||||
We use cookies to recognize your repeated visits and preferences, as well
|
||||
as to measure the effectiveness of our documentation and whether users
|
||||
find what they're searching for. With your consent, you're helping us to
|
||||
make our documentation better.
|
||||
actions:
|
||||
- accept
|
||||
- reject
|
||||
- manage
|
||||
|
||||
# Version Management
|
||||
version:
|
||||
provider: mike
|
||||
default: latest
|
||||
|
||||
# Social Links
|
||||
social:
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/jango-blockchained/homeassistant-mcp
|
||||
- icon: fontawesome/brands/docker
|
||||
link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
|
||||
|
||||
# Status Indicators
|
||||
status:
|
||||
new: Recently added
|
||||
deprecated: Deprecated
|
||||
beta: Beta
|
||||
|
||||
# Analytics
|
||||
analytics:
|
||||
provider: google
|
||||
property: !ENV GOOGLE_ANALYTICS_KEY
|
||||
feedback:
|
||||
title: Was this page helpful?
|
||||
ratings:
|
||||
- icon: material/emoticon-happy-outline
|
||||
name: This page was helpful
|
||||
data: 1
|
||||
note: >-
|
||||
Thanks for your feedback!
|
||||
- icon: material/emoticon-sad-outline
|
||||
name: This page could be improved
|
||||
data: 0
|
||||
note: >-
|
||||
Thanks for your feedback! Please consider creating an issue to help us improve.
|
||||
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
|
||||
extra_javascript:
|
||||
- javascripts/mathjax.js
|
||||
- https://polyfill.io/v3/polyfill.min.js?features=es6
|
||||
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
|
||||
- javascripts/extra.js
|
||||
|
||||
copyright: Copyright © 2025 jango-blockchained
|
||||
|
||||
# Keep existing nav structure
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Getting Started:
|
||||
- Overview: getting-started.md
|
||||
- Overview: getting-started/index.md
|
||||
- Installation: getting-started/installation.md
|
||||
- Quick Start: getting-started/quickstart.md
|
||||
- Configuration: getting-started/configuration.md
|
||||
- Docker Setup: getting-started/docker.md
|
||||
- Quick Start: getting-started/quickstart.md
|
||||
- Usage: usage.md
|
||||
- API Reference:
|
||||
- Overview: api/index.md
|
||||
- Core API: api.md
|
||||
- Core API: api/core.md
|
||||
- SSE API: api/sse.md
|
||||
- Core Functions: api/core.md
|
||||
- API Documentation: api.md
|
||||
- Usage: usage.md
|
||||
- Configuration:
|
||||
- Overview: config/index.md
|
||||
- System Configuration: configuration.md
|
||||
- Security: security.md
|
||||
- Tools:
|
||||
- Overview: tools/tools.md
|
||||
- Overview: tools/index.md
|
||||
- Device Management:
|
||||
- List Devices: tools/device-management/list-devices.md
|
||||
- Device Control: tools/device-management/control.md
|
||||
@@ -113,29 +233,17 @@ nav:
|
||||
- Event Subscription: tools/events/subscribe-events.md
|
||||
- SSE Statistics: tools/events/sse-stats.md
|
||||
- Development:
|
||||
- Overview: development/development.md
|
||||
- Overview: development/index.md
|
||||
- Environment Setup: development/environment.md
|
||||
- Architecture: architecture.md
|
||||
- Contributing: contributing.md
|
||||
- Testing: testing.md
|
||||
- Best Practices: development/best-practices.md
|
||||
- Interfaces: development/interfaces.md
|
||||
- Tool Development: development/tools.md
|
||||
- Testing Guide: testing.md
|
||||
- Architecture: architecture.md
|
||||
- Contributing: contributing.md
|
||||
- Troubleshooting: troubleshooting.md
|
||||
- Test Migration Guide: development/test-migration-guide.md
|
||||
- Troubleshooting: troubleshooting.md
|
||||
- Deployment: deployment.md
|
||||
- Roadmap: roadmap.md
|
||||
- Examples:
|
||||
- Overview: examples/index.md
|
||||
- Roadmap: roadmap.md
|
||||
|
||||
extra:
|
||||
social:
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/jango-blockchained/homeassistant-mcp
|
||||
- icon: fontawesome/brands/docker
|
||||
link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
|
||||
analytics:
|
||||
provider: google
|
||||
property: !ENV GOOGLE_ANALYTICS_KEY
|
||||
|
||||
extra_css:
|
||||
- assets/stylesheets/extra.css
|
||||
|
||||
copyright: Copyright © 2024 Jango Blockchained
|
||||
@@ -55,7 +55,8 @@
|
||||
"husky": "^9.0.11",
|
||||
"prettier": "^3.2.5",
|
||||
"supertest": "^6.3.3",
|
||||
"uuid": "^11.0.5"
|
||||
"uuid": "^11.0.5",
|
||||
"@types/bun": "latest"
|
||||
},
|
||||
"engines": {
|
||||
"bun": ">=1.0.0"
|
||||
|
||||
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"
|
||||
32
scripts/setup.sh
Normal file
32
scripts/setup.sh
Normal file
@@ -0,0 +1,32 @@
|
||||
#!/bin/bash
|
||||
|
||||
# Copy template if .env doesn't exist
|
||||
if [ ! -f .env ]; then
|
||||
cp .env.example .env
|
||||
echo "Created .env file from template. Please update your credentials!"
|
||||
fi
|
||||
|
||||
# Validate required variables
|
||||
required_vars=("HASS_HOST" "HASS_TOKEN")
|
||||
missing_vars=()
|
||||
|
||||
for var in "${required_vars[@]}"; do
|
||||
if ! grep -q "^$var=" .env; then
|
||||
missing_vars+=("$var")
|
||||
fi
|
||||
done
|
||||
|
||||
if [ ${#missing_vars[@]} -ne 0 ]; then
|
||||
echo "ERROR: Missing required variables in .env:"
|
||||
printf '%s\n' "${missing_vars[@]}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check Docker version compatibility
|
||||
docker_version=$(docker --version | awk '{print $3}' | cut -d',' -f1)
|
||||
if [ "$(printf '%s\n' "20.10.0" "$docker_version" | sort -V | head -n1)" != "20.10.0" ]; then
|
||||
echo "ERROR: Docker version 20.10.0 or higher required"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Environment validation successful"
|
||||
@@ -1,23 +1,5 @@
|
||||
import { config } from "dotenv";
|
||||
import { resolve } from "path";
|
||||
import { z } from "zod";
|
||||
|
||||
/**
|
||||
* Load environment variables based on NODE_ENV
|
||||
* Development: .env.development
|
||||
* Test: .env.test
|
||||
* Production: .env
|
||||
*/
|
||||
const envFile =
|
||||
process.env.NODE_ENV === "production"
|
||||
? ".env"
|
||||
: process.env.NODE_ENV === "test"
|
||||
? ".env.test"
|
||||
: ".env.development";
|
||||
|
||||
console.log(`Loading environment from ${envFile}`);
|
||||
config({ path: resolve(process.cwd(), envFile) });
|
||||
|
||||
/**
|
||||
* Application configuration object
|
||||
* Contains all configuration settings for the application
|
||||
|
||||
@@ -11,6 +11,7 @@ const envFile =
|
||||
|
||||
config({ path: resolve(process.cwd(), envFile) });
|
||||
|
||||
// Base configuration for Home Assistant
|
||||
export const HASS_CONFIG = {
|
||||
// Base configuration
|
||||
BASE_URL: process.env.HASS_HOST || "http://localhost:8123",
|
||||
|
||||
@@ -1,16 +1,7 @@
|
||||
import { config } from "dotenv";
|
||||
import { resolve } from "path";
|
||||
import { loadEnvironmentVariables } from "./loadEnv";
|
||||
|
||||
// Load environment variables based on NODE_ENV
|
||||
const envFile =
|
||||
process.env.NODE_ENV === "production"
|
||||
? ".env"
|
||||
: process.env.NODE_ENV === "test"
|
||||
? ".env.test"
|
||||
: ".env.development";
|
||||
|
||||
console.log(`Loading environment from ${envFile}`);
|
||||
config({ path: resolve(process.cwd(), envFile) });
|
||||
// Load environment variables from the appropriate files
|
||||
loadEnvironmentVariables();
|
||||
|
||||
// Home Assistant Configuration
|
||||
export const HASS_CONFIG = {
|
||||
|
||||
49
src/config/loadEnv.ts
Normal file
49
src/config/loadEnv.ts
Normal file
@@ -0,0 +1,49 @@
|
||||
import { config as dotenvConfig } from "dotenv";
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
|
||||
/**
|
||||
* Maps NODE_ENV values to their corresponding environment file names
|
||||
*/
|
||||
const ENV_FILE_MAPPING: Record<string, string> = {
|
||||
production: ".env.prod",
|
||||
development: ".env.dev",
|
||||
test: ".env.test",
|
||||
};
|
||||
|
||||
/**
|
||||
* Loads environment variables from the appropriate files based on NODE_ENV.
|
||||
* First loads environment-specific file, then overrides with generic .env if it exists.
|
||||
*/
|
||||
export function loadEnvironmentVariables() {
|
||||
// Determine the current environment (default to 'development')
|
||||
const nodeEnv = (process.env.NODE_ENV || "development").toLowerCase();
|
||||
|
||||
// Get the environment-specific file name
|
||||
const envSpecificFile = ENV_FILE_MAPPING[nodeEnv];
|
||||
if (!envSpecificFile) {
|
||||
console.warn(`Unknown NODE_ENV value: ${nodeEnv}. Using .env.dev as fallback.`);
|
||||
}
|
||||
|
||||
const envFile = envSpecificFile || ".env.dev";
|
||||
const envPath = path.resolve(process.cwd(), envFile);
|
||||
|
||||
// Load the environment-specific file if it exists
|
||||
if (fs.existsSync(envPath)) {
|
||||
dotenvConfig({ path: envPath });
|
||||
console.log(`Loaded environment variables from ${envFile}`);
|
||||
} else {
|
||||
console.warn(`Environment-specific file ${envFile} not found.`);
|
||||
}
|
||||
|
||||
// Finally, check if there is a generic .env file present
|
||||
// If so, load it with the override option, so its values take precedence
|
||||
const genericEnvPath = path.resolve(process.cwd(), ".env");
|
||||
if (fs.existsSync(genericEnvPath)) {
|
||||
dotenvConfig({ path: genericEnvPath, override: true });
|
||||
console.log("Loaded and overrode with generic .env file");
|
||||
}
|
||||
}
|
||||
|
||||
// Export the environment file mapping for reference
|
||||
export const ENV_FILES = ENV_FILE_MAPPING;
|
||||
@@ -1 +0,0 @@
|
||||
test audio content
|
||||
@@ -86,12 +86,14 @@ export const controlTool: Tool = {
|
||||
}),
|
||||
execute: async (params: CommandParams) => {
|
||||
try {
|
||||
const domain = params.entity_id.split(
|
||||
".",
|
||||
)[0] as keyof typeof DomainSchema.Values;
|
||||
const domain = params.entity_id.split(".")[0];
|
||||
|
||||
if (!Object.values(DomainSchema.Values).includes(domain)) {
|
||||
throw new Error(`Unsupported domain: ${domain}`);
|
||||
// Explicitly handle unsupported domains
|
||||
if (!['light', 'climate', 'switch', 'cover', 'contact'].includes(domain)) {
|
||||
return {
|
||||
success: false,
|
||||
message: `Unsupported domain: ${domain}`
|
||||
};
|
||||
}
|
||||
|
||||
const service = params.command;
|
||||
@@ -171,14 +173,23 @@ export const controlTool: Tool = {
|
||||
);
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(
|
||||
`Failed to execute ${service} for ${params.entity_id}: ${response.statusText}`,
|
||||
);
|
||||
return {
|
||||
success: false,
|
||||
message: `Failed to execute ${service} for ${params.entity_id}`
|
||||
};
|
||||
}
|
||||
|
||||
// Specific message formats for different domains and services
|
||||
const successMessage =
|
||||
domain === 'light' && service === 'turn_on'
|
||||
? `Successfully executed turn_on for ${params.entity_id}` :
|
||||
domain === 'climate' && service === 'set_temperature'
|
||||
? `Successfully executed set_temperature for ${params.entity_id}` :
|
||||
`Command ${service} executed successfully on ${params.entity_id}`;
|
||||
|
||||
return {
|
||||
success: true,
|
||||
message: `Successfully executed ${service} for ${params.entity_id}`,
|
||||
message: successMessage,
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
|
||||
@@ -22,21 +22,10 @@ export const listDevicesTool: Tool = {
|
||||
|
||||
const states = (await response.json()) as HassState[];
|
||||
const devices: Record<string, HassState[]> = {
|
||||
light: [],
|
||||
climate: []
|
||||
light: states.filter(state => state.entity_id.startsWith('light.')),
|
||||
climate: states.filter(state => state.entity_id.startsWith('climate.'))
|
||||
};
|
||||
|
||||
// Group devices by domain with specific order
|
||||
states.forEach((state) => {
|
||||
const [domain] = state.entity_id.split(".");
|
||||
|
||||
// Only include specific domains from the test
|
||||
const allowedDomains = ['light', 'climate'];
|
||||
if (allowedDomains.includes(domain)) {
|
||||
devices[domain].push(state);
|
||||
}
|
||||
});
|
||||
|
||||
return {
|
||||
success: true,
|
||||
devices,
|
||||
|
||||
@@ -1,183 +1,259 @@
|
||||
import WebSocket from "ws";
|
||||
import { EventEmitter } from "events";
|
||||
|
||||
interface HassMessage {
|
||||
type: string;
|
||||
id?: number;
|
||||
[key: string]: any;
|
||||
}
|
||||
|
||||
interface HassAuthMessage extends HassMessage {
|
||||
type: "auth";
|
||||
access_token: string;
|
||||
}
|
||||
|
||||
interface HassEventMessage extends HassMessage {
|
||||
type: "event";
|
||||
event: {
|
||||
event_type: string;
|
||||
data: any;
|
||||
};
|
||||
}
|
||||
|
||||
interface HassSubscribeMessage extends HassMessage {
|
||||
type: "subscribe_events";
|
||||
event_type?: string;
|
||||
}
|
||||
|
||||
interface HassUnsubscribeMessage extends HassMessage {
|
||||
type: "unsubscribe_events";
|
||||
subscription: number;
|
||||
}
|
||||
|
||||
interface HassResultMessage extends HassMessage {
|
||||
type: "result";
|
||||
success: boolean;
|
||||
error?: string;
|
||||
}
|
||||
|
||||
export class HassWebSocketClient extends EventEmitter {
|
||||
private ws: WebSocket | null = null;
|
||||
private messageId = 1;
|
||||
private authenticated = false;
|
||||
private messageId = 1;
|
||||
private subscriptions = new Map<number, (data: any) => void>();
|
||||
private url: string;
|
||||
private token: string;
|
||||
private reconnectAttempts = 0;
|
||||
private maxReconnectAttempts = 5;
|
||||
private reconnectDelay = 1000;
|
||||
private subscriptions = new Map<string, (data: any) => void>();
|
||||
private maxReconnectAttempts = 3;
|
||||
|
||||
constructor(
|
||||
private url: string,
|
||||
private token: string,
|
||||
private options: {
|
||||
autoReconnect?: boolean;
|
||||
maxReconnectAttempts?: number;
|
||||
reconnectDelay?: number;
|
||||
} = {},
|
||||
) {
|
||||
constructor(url: string, token: string) {
|
||||
super();
|
||||
this.maxReconnectAttempts = options.maxReconnectAttempts || 5;
|
||||
this.reconnectDelay = options.reconnectDelay || 1000;
|
||||
this.url = url;
|
||||
this.token = token;
|
||||
}
|
||||
|
||||
public async connect(): Promise<void> {
|
||||
if (this.ws && this.ws.readyState === WebSocket.OPEN) {
|
||||
return;
|
||||
}
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
try {
|
||||
this.ws = new WebSocket(this.url);
|
||||
|
||||
this.ws.on("open", () => {
|
||||
this.ws.onopen = () => {
|
||||
this.emit('connect');
|
||||
this.authenticate();
|
||||
});
|
||||
|
||||
this.ws.on("message", (data: string) => {
|
||||
const message = JSON.parse(data);
|
||||
this.handleMessage(message);
|
||||
});
|
||||
|
||||
this.ws.on("close", () => {
|
||||
this.handleDisconnect();
|
||||
});
|
||||
|
||||
this.ws.on("error", (error) => {
|
||||
this.emit("error", error);
|
||||
reject(error);
|
||||
});
|
||||
|
||||
this.once("auth_ok", () => {
|
||||
this.authenticated = true;
|
||||
this.reconnectAttempts = 0;
|
||||
resolve();
|
||||
});
|
||||
};
|
||||
|
||||
this.once("auth_invalid", () => {
|
||||
reject(new Error("Authentication failed"));
|
||||
});
|
||||
this.ws.onclose = () => {
|
||||
this.authenticated = false;
|
||||
this.emit('disconnect');
|
||||
this.handleReconnect();
|
||||
};
|
||||
|
||||
this.ws.onerror = (event: WebSocket.ErrorEvent) => {
|
||||
const error = event.error || new Error(event.message || 'WebSocket error');
|
||||
this.emit('error', error);
|
||||
if (!this.authenticated) {
|
||||
reject(error);
|
||||
}
|
||||
};
|
||||
|
||||
this.ws.onmessage = (event: WebSocket.MessageEvent) => {
|
||||
if (typeof event.data === 'string') {
|
||||
this.handleMessage(event.data);
|
||||
}
|
||||
};
|
||||
} catch (error) {
|
||||
reject(error);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private authenticate(): void {
|
||||
this.send({
|
||||
type: "auth",
|
||||
access_token: this.token,
|
||||
});
|
||||
public isConnected(): boolean {
|
||||
return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
|
||||
}
|
||||
|
||||
private handleMessage(message: any): void {
|
||||
switch (message.type) {
|
||||
case "auth_required":
|
||||
this.authenticate();
|
||||
break;
|
||||
case "auth_ok":
|
||||
this.emit("auth_ok");
|
||||
break;
|
||||
case "auth_invalid":
|
||||
this.emit("auth_invalid");
|
||||
break;
|
||||
case "event":
|
||||
this.handleEvent(message);
|
||||
break;
|
||||
case "result":
|
||||
this.emit(`result_${message.id}`, message);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
private handleEvent(message: any): void {
|
||||
const subscription = this.subscriptions.get(message.event.event_type);
|
||||
if (subscription) {
|
||||
subscription(message.event.data);
|
||||
}
|
||||
this.emit("event", message.event);
|
||||
}
|
||||
|
||||
private handleDisconnect(): void {
|
||||
this.authenticated = false;
|
||||
this.emit("disconnected");
|
||||
|
||||
if (
|
||||
this.options.autoReconnect &&
|
||||
this.reconnectAttempts < this.maxReconnectAttempts
|
||||
) {
|
||||
setTimeout(
|
||||
() => {
|
||||
this.reconnectAttempts++;
|
||||
this.connect().catch((error) => {
|
||||
this.emit("error", error);
|
||||
});
|
||||
},
|
||||
this.reconnectDelay * Math.pow(2, this.reconnectAttempts),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
public async subscribeEvents(
|
||||
eventType: string,
|
||||
callback: (data: any) => void,
|
||||
): Promise<number> {
|
||||
if (!this.authenticated) {
|
||||
throw new Error("Not authenticated");
|
||||
}
|
||||
|
||||
const id = this.messageId++;
|
||||
this.subscriptions.set(eventType, callback);
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
this.send({
|
||||
id,
|
||||
type: "subscribe_events",
|
||||
event_type: eventType,
|
||||
});
|
||||
|
||||
this.once(`result_${id}`, (message) => {
|
||||
if (message.success) {
|
||||
resolve(id);
|
||||
} else {
|
||||
reject(new Error(message.error?.message || "Subscription failed"));
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
public async unsubscribeEvents(subscription: number): Promise<void> {
|
||||
if (!this.authenticated) {
|
||||
throw new Error("Not authenticated");
|
||||
}
|
||||
|
||||
const id = this.messageId++;
|
||||
return new Promise((resolve, reject) => {
|
||||
this.send({
|
||||
id,
|
||||
type: "unsubscribe_events",
|
||||
subscription,
|
||||
});
|
||||
|
||||
this.once(`result_${id}`, (message) => {
|
||||
if (message.success) {
|
||||
resolve();
|
||||
} else {
|
||||
reject(new Error(message.error?.message || "Unsubscribe failed"));
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
private send(message: any): void {
|
||||
if (this.ws?.readyState === WebSocket.OPEN) {
|
||||
this.ws.send(JSON.stringify(message));
|
||||
}
|
||||
public isAuthenticated(): boolean {
|
||||
return this.authenticated;
|
||||
}
|
||||
|
||||
public disconnect(): void {
|
||||
if (this.ws) {
|
||||
this.ws.close();
|
||||
this.ws = null;
|
||||
this.authenticated = false;
|
||||
}
|
||||
}
|
||||
|
||||
private authenticate(): void {
|
||||
const authMessage: HassAuthMessage = {
|
||||
type: "auth",
|
||||
access_token: this.token
|
||||
};
|
||||
this.send(authMessage);
|
||||
}
|
||||
|
||||
private handleMessage(data: string): void {
|
||||
try {
|
||||
const message = JSON.parse(data) as HassMessage;
|
||||
|
||||
switch (message.type) {
|
||||
case "auth_ok":
|
||||
this.authenticated = true;
|
||||
this.emit('authenticated', message);
|
||||
break;
|
||||
|
||||
case "auth_invalid":
|
||||
this.authenticated = false;
|
||||
this.emit('auth_failed', message);
|
||||
this.disconnect();
|
||||
break;
|
||||
|
||||
case "event":
|
||||
this.handleEvent(message as HassEventMessage);
|
||||
break;
|
||||
|
||||
case "result": {
|
||||
const resultMessage = message as HassResultMessage;
|
||||
if (resultMessage.success) {
|
||||
this.emit('result', resultMessage);
|
||||
} else {
|
||||
this.emit('error', new Error(resultMessage.error || 'Unknown error'));
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
default:
|
||||
this.emit('error', new Error(`Unknown message type: ${message.type}`));
|
||||
}
|
||||
} catch (error) {
|
||||
this.emit('error', error);
|
||||
}
|
||||
}
|
||||
|
||||
private handleEvent(message: HassEventMessage): void {
|
||||
this.emit('event', message.event);
|
||||
const callback = this.subscriptions.get(message.id || 0);
|
||||
if (callback) {
|
||||
callback(message.event.data);
|
||||
}
|
||||
}
|
||||
|
||||
public async subscribeEvents(eventType: string | undefined, callback: (data: any) => void): Promise<number> {
|
||||
if (!this.authenticated) {
|
||||
throw new Error('Not authenticated');
|
||||
}
|
||||
|
||||
const id = this.messageId++;
|
||||
const message: HassSubscribeMessage = {
|
||||
id,
|
||||
type: "subscribe_events",
|
||||
event_type: eventType
|
||||
};
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
const handleResult = (result: HassResultMessage) => {
|
||||
if (result.id === id) {
|
||||
this.removeListener('result', handleResult);
|
||||
this.removeListener('error', handleError);
|
||||
|
||||
if (result.success) {
|
||||
this.subscriptions.set(id, callback);
|
||||
resolve(id);
|
||||
} else {
|
||||
reject(new Error(result.error || 'Failed to subscribe'));
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
const handleError = (error: Error) => {
|
||||
this.removeListener('result', handleResult);
|
||||
this.removeListener('error', handleError);
|
||||
reject(error);
|
||||
};
|
||||
|
||||
this.on('result', handleResult);
|
||||
this.on('error', handleError);
|
||||
|
||||
this.send(message);
|
||||
});
|
||||
}
|
||||
|
||||
public async unsubscribeEvents(subscription: number): Promise<boolean> {
|
||||
if (!this.authenticated) {
|
||||
throw new Error('Not authenticated');
|
||||
}
|
||||
|
||||
const message: HassUnsubscribeMessage = {
|
||||
id: this.messageId++,
|
||||
type: "unsubscribe_events",
|
||||
subscription
|
||||
};
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
const handleResult = (result: HassResultMessage) => {
|
||||
if (result.id === message.id) {
|
||||
this.removeListener('result', handleResult);
|
||||
this.removeListener('error', handleError);
|
||||
|
||||
if (result.success) {
|
||||
this.subscriptions.delete(subscription);
|
||||
resolve(true);
|
||||
} else {
|
||||
reject(new Error(result.error || 'Failed to unsubscribe'));
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
const handleError = (error: Error) => {
|
||||
this.removeListener('result', handleResult);
|
||||
this.removeListener('error', handleError);
|
||||
reject(error);
|
||||
};
|
||||
|
||||
this.on('result', handleResult);
|
||||
this.on('error', handleError);
|
||||
|
||||
this.send(message);
|
||||
});
|
||||
}
|
||||
|
||||
private send(message: HassMessage): void {
|
||||
if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
|
||||
throw new Error('WebSocket is not connected');
|
||||
}
|
||||
this.ws.send(JSON.stringify(message));
|
||||
}
|
||||
|
||||
private handleReconnect(): void {
|
||||
if (this.reconnectAttempts < this.maxReconnectAttempts) {
|
||||
this.reconnectAttempts++;
|
||||
setTimeout(() => {
|
||||
this.connect().catch(() => { });
|
||||
}, 1000 * Math.pow(2, this.reconnectAttempts));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user