test: migrate test suite from Jest to Bun test framework

- Convert test files to use Bun's test framework and mocking utilities
- Update import statements and test syntax
- Add comprehensive test utilities and mock implementations
- Create test migration guide documentation
- Implement helper functions for consistent test setup and teardown
- Add type definitions for improved type safety in tests

.dockerignore

@@ -7,7 +7,6 @@ yarn-error.log*
 package-lock.json
 yarn.lock
 pnpm-lock.yaml
-bun.lockb
 
 # Build output
 dist/
@@ -74,3 +73,6 @@ temp/
 .cloud/
 *.db
 *.db-* 
+.cursor/
+.cursor*
+.cursorconfig

.env.example

@@ -36,26 +36,50 @@ RATE_LIMIT_REGULAR=100
 # Requests per minute per IP for WebSocket connections
 RATE_LIMIT_WEBSOCKET=1000
 
-# Security
-# JWT secret for token generation (change this in production!)
-JWT_SECRET=your_jwt_secret_key
-
-# CORS configuration (comma-separated list of allowed origins)
-CORS_ORIGINS=http://localhost:3000,http://localhost:8123
-
-# Test Configuration
-# Only needed if running tests
-TEST_HASS_HOST=http://localhost:8123
-TEST_HASS_TOKEN=test_token
-TEST_HASS_SOCKET_URL=ws://localhost:8123/api/websocket
-TEST_PORT=3001
-
 # Security Configuration
-JWT_SECRET=your-secret-key
+# JWT Configuration
+JWT_SECRET=your_jwt_secret_key_min_32_chars
+JWT_EXPIRY=86400000
+JWT_MAX_AGE=2592000000
+JWT_ALGORITHM=HS256
 
 # Rate Limiting
-RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
+RATE_LIMIT_WINDOW=900000
-RATE_LIMIT_MAX=100
+RATE_LIMIT_MAX_REQUESTS=100
+
+# Token Security
+TOKEN_MIN_LENGTH=32
+MAX_FAILED_ATTEMPTS=5
+LOCKOUT_DURATION=900000
+
+# 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
+
+# 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
+COOKIE_HTTP_ONLY=true
+COOKIE_SAME_SITE=Strict
+
+# Request Limits
+MAX_REQUEST_SIZE=1048576
+MAX_REQUEST_FIELDS=1000
 
 # SSE Configuration
 SSE_MAX_CLIENTS=1000
@@ -71,3 +95,17 @@ LOG_REQUESTS=true
 
 # Version
 VERSION=0.1.0
+
+# Test Configuration
+# Only needed if running tests
+TEST_HASS_HOST=http://localhost:8123
+TEST_HASS_TOKEN=test_token
+TEST_HASS_SOCKET_URL=ws://localhost:8123/api/websocket
+TEST_PORT=3001
+
+# Speech Features Configuration
+ENABLE_SPEECH_FEATURES=false
+ENABLE_WAKE_WORD=true
+ENABLE_SPEECH_TO_TEXT=true
+WHISPER_MODEL_PATH=/models
+WHISPER_MODEL_TYPE=base

.github/workflows/deploy-docs.yml

@@ -0,0 +1,64 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+          cache-version: 0
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: |
+          cd docs
+          bundle install
+
+      - name: Build site
+        run: |
+          cd docs
+          bundle exec jekyll build
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 

.github/workflows/docker-build-push.yml

@@ -0,0 +1,65 @@
+name: Docker Build and Push
+
+on:
+  push:
+    branches: [ "main" ]
+    tags:
+      - 'v*.*.*'  # Triggers on version tags like v1.0.0
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for version detection
+
+      - name: Bump version and push tag
+        id: tag_version
+        uses: mathieudutour/github-tag-action@v6.1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          default_bump: patch
+
+      - name: Create Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ steps.tag_version.outputs.new_tag }}
+          release_name: Release ${{ steps.tag_version.outputs.new_tag }}
+          body: ${{ steps.tag_version.outputs.changelog }}
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=${{ steps.tag_version.outputs.new_tag }}
+            type=raw,value=latest
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }} 

.github/workflows/docs-deploy.yml

@@ -0,0 +1,32 @@
+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 

.gitignore

@@ -65,7 +65,6 @@ home-assistant_v2.db-*
 package-lock.json
 yarn.lock
 pnpm-lock.yaml
-bun.lockb
 
 coverage/*
 coverage/
@@ -73,3 +72,21 @@ coverage/
 .env
 .env.*
 !.env.*.template
+
+.cursor/
+.cursor/*
+
+.bun/
+.cursorconfig
+bun.lockb
+
+# MkDocs
+site/
+.site/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+models/

Dockerfile

@@ -1,20 +1,70 @@
-# Use Bun as the base image
+# Use Node.js as base for building
-FROM oven/bun:1.0.26
+FROM node:20-slim as builder
 
 # Set working directory
 WORKDIR /app
 
-# Copy source code
+# Install bun
-COPY . .
+RUN npm install -g bun@1.0.25
 
-# Install dependencies
+# Install only the minimal dependencies needed and clean up in the same layer
-RUN bun install
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean \
+    && rm -rf /var/cache/apt/*
 
-# Build TypeScript
+# Set build-time environment variables
-RUN bun run build
+ENV NODE_ENV=production \
+    NODE_OPTIONS="--max-old-space-size=2048" \
+    BUN_INSTALL_CACHE=0
 
-# Expose the port the app runs on
+# Copy only package files first
-EXPOSE 3000
+COPY package.json ./
 
-# Start the application
+# Install dependencies with a clean slate
-CMD ["bun", "run", "start"] 
+RUN rm -rf node_modules .bun bun.lockb && \
+    bun install --no-save
+
+# Copy source files and build
+COPY src ./src
+COPY tsconfig*.json ./
+RUN bun build ./src/index.ts --target=bun --minify --outdir=./dist
+
+# Create a smaller production image
+FROM node:20-slim as runner
+
+# Install bun in production image
+RUN npm install -g bun@1.0.25
+
+# Set production environment variables
+ENV NODE_ENV=production \
+    NODE_OPTIONS="--max-old-space-size=1024"
+
+# Create a non-root user
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 bunjs
+
+WORKDIR /app
+
+# Copy only the necessary files from builder
+COPY --from=builder --chown=bunjs:nodejs /app/dist ./dist
+COPY --from=builder --chown=bunjs:nodejs /app/node_modules ./node_modules
+COPY --chown=bunjs:nodejs package.json ./
+
+# Create logs directory with proper permissions
+RUN mkdir -p /app/logs && chown -R bunjs:nodejs /app/logs
+
+# Switch to non-root user
+USER bunjs
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:4000/health || exit 1
+
+# Expose port
+EXPOSE 4000
+
+# Start the application with optimized flags
+CMD ["bun", "--smol", "run", "start"] 

README.md

@@ -1,400 +1,372 @@
-# Model Context Protocol Server for Home Assistant
+# 🚀 MCP Server for Home Assistant - Bringing AI-Powered Smart Homes to Life!
 
-The server uses the MCP protocol to share access to a local Home Assistant instance with an LLM application.
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)  
+[![Bun](https://img.shields.io/badge/bun-%3E%3D1.0.26-black)](https://bun.sh)  
+[![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg)](https://www.typescriptlang.org)  
+[![Test Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)](#)  
+[![Documentation](https://img.shields.io/badge/docs-github.io-blue.svg)](https://jango-blockchained.github.io/homeassistant-mcp/)  
+[![Docker](https://img.shields.io/badge/docker-%3E%3D20.10.8-blue)](https://www.docker.com)
 
-A powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP). This server provides a comprehensive API for managing your entire Home Assistant ecosystem, from device control to system administration.
+---
 
-![License](https://img.shields.io/badge/license-MIT-blue.svg)
+## Overview 🌐
-![Node.js](https://img.shields.io/badge/node-%3E%3D20.10.0-green.svg)
-![Docker Compose](https://img.shields.io/badge/docker-compose-%3E%3D1.27.0-blue.svg)
-![NPM](https://img.shields.io/badge/npm-%3E%3D7.0.0-orange.svg)
-![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg)
-![Test Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)
 
-## Features
+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:  
 
-- 🎮 **Device Control**: Control any Home Assistant device through natural language
+> "Hey MCP, dim the lights and start my evening playlist,"  
-- 🔄 **Real-time Updates**: Get instant updates through Server-Sent Events (SSE)
-- 🤖 **Automation Management**: Create, update, and manage automations
-- 📊 **State Monitoring**: Track and query device states
-- 🔐 **Secure**: Token-based authentication and rate limiting
-- 📱 **Mobile Ready**: Works with any HTTP-capable client
 
-## Real-time Updates with SSE
+and watching your home transform instantly—that's the magic that MCP Server delivers!
 
-The server includes a powerful Server-Sent Events (SSE) system that provides real-time updates from your Home Assistant instance. This allows you to:
+---
 
-- 🔄 Get instant state changes for any device
+## Key Benefits ✨
-- 📡 Monitor automation triggers and executions
-- 🎯 Subscribe to specific domains or entities
-- 📊 Track service calls and script executions
 
-### Quick SSE Example
+### 🎮 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.
+
+- **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.
+
+- **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.
+
+### 🤖 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.
+
+- **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.
+
+- **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:
+
+```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)"]
+    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
+```
+
+Learn more about our architecture in the [Architecture Documentation](docs/architecture.md).
+
+---
+
+## Technical Stack 🔧
+
+Our solution is built on a modern, high-performance stack that powers every feature:
+
+- **Bun:**  
+  A next-generation JavaScript runtime offering rapid startup times, native TypeScript support, and high performance.  
+  👉 [Learn about Bun](https://bun.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.
+
+- **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).
+
+- **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.
+
+- **Redis Cache:**  
+  Enables rapid data retrieval and session persistence essential for real-time updates.
+
+- **TypeScript:**  
+  Enhances type safety and developer productivity across the entire codebase.
+
+- **JWT & Security Middleware:**  
+  Protects your ecosystem with JWT-based authentication, request sanitization, rate-limiting, and encryption.
+
+- **Containerization with Docker:**  
+  Enables scalable, isolated deployments for production environments.
+
+For further technical details, check out our [Documentation Index](docs/index.md).
+
+---
+
+## Installation 🛠
+
+### Installing via Smithery
+
+To install Home Assistant MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@jango-blockchained/advanced-homeassistant-mcp):
+
+```bash
+npx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude
+```
+
+### 🐳 Docker Setup (Recommended)
+
+For a hassle-free, containerized deployment:
+
+```bash
+# 1. Clone the repository (using a shallow copy for efficiency)
+git clone --depth 1 https://github.com/jango-blockchained/homeassistant-mcp.git
+
+# 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.
+
+# 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(
+const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light');
-  'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
-);
 
 eventSource.onmessage = (event) => {
     const data = JSON.parse(event.data);
-  console.log('Update received:', data);
+    console.log('Real-time update:', data);
+    // Update your UI dashboard, e.g., refresh a light intensity indicator.
 };
 ```
 
-See [SSE_API.md](docs/SSE_API.md) for complete documentation of the SSE system.
+### 🏠 Voice-Activated Control
+Utilize voice commands to trigger actions with minimal effort:
 
-## Table of Contents
+```javascript
+// Establish a WebSocket connection for real-time command processing
+const ws = new WebSocket('wss://mcp.yourha.com/ws');
 
-- [Key Features](#key-features)
+ws.onmessage = ({ data }) => {
-- [Prerequisites](#prerequisites)
+    const update = JSON.parse(data);
-- [Installation](#installation)
+    if (update.entity_id === 'light.living_room') {
-  - [Basic Setup](#basic-setup)
+        console.log('Adjusting living room lighting based on voice command...');
-  - [Docker Setup (Recommended)](#docker-setup-recommended)
+        // Additional logic to update your UI or trigger further actions can go here.
-- [Configuration](#configuration)
+    }
-- [Development](#development)
+};
-- [API Reference](#api-reference)
-- [OpenAI Integration](#openai-integration)
-- [Natural Language Integration](#natural-language-integration)
-- [Troubleshooting](#troubleshooting)
-- [Project Status](#project-status)
-- [Contributing](#contributing)
-- [Resources](#resources)
-- [License](#license)
 
-## Key Features
+// Simulate processing a voice command
+function simulateVoiceCommand(command) {
+    console.log("Processing voice command:", command);
+    // Integrate with your actual voice-to-text system as needed.
+}
 
-### Core Functionality 🎮
+simulateVoiceCommand("Turn off all the lights for bedtime");
-- **Smart Device Control**
-  - 💡 **Lights**: Brightness, color temperature, RGB color
-  - 🌡️ **Climate**: Temperature, HVAC modes, fan modes, humidity
-  - 🚪 **Covers**: Position and tilt control
-  - 🔌 **Switches**: On/off control
-  - 🚨 **Sensors & Contacts**: State monitoring
-  - 🎵 **Media Players**: Playback control, volume, source selection
-  - 🌪️ **Fans**: Speed, oscillation, direction
-  - 🔒 **Locks**: Lock/unlock control
-  - 🧹 **Vacuums**: Start, stop, return to base
-  - 📹 **Cameras**: Motion detection, snapshots
-
-### System Management 🛠️
-- **Add-on Management**
-  - Browse available add-ons
-  - Install/uninstall add-ons
-  - Start/stop/restart add-ons
-  - Version management
-  - Configuration access
-
-- **Package Management (HACS)**
-  - Integration with Home Assistant Community Store
-  - Multiple package types support:
-    - Custom integrations
-    - Frontend themes
-    - Python scripts
-    - AppDaemon apps
-    - NetDaemon apps
-  - Version control and updates
-  - Repository management
-
-- **Automation Management**
-  - Create and edit automations
-  - Advanced configuration options:
-    - Multiple trigger types
-    - Complex conditions
-    - Action sequences
-    - Execution modes
-  - Duplicate and modify existing automations
-  - Enable/disable automation rules
-  - Trigger automation manually
-
-### Architecture Features 🏗️
-- **Intelligent Organization**
-  - Area and floor-based device grouping
-  - State monitoring and querying
-  - Smart context awareness
-  - Historical data access
-
-- **Robust Architecture**
-  - Comprehensive error handling
-  - State validation
-  - Secure API integration
-  - TypeScript type safety
-  - Extensive test coverage
-
-## Prerequisites
-
-- **Node.js** 20.10.0 or higher
-- **NPM** package manager
-- **Docker Compose** for containerization
-- Running **Home Assistant** instance
-- Home Assistant long-lived access token ([How to get token](https://community.home-assistant.io/t/how-to-get-long-lived-access-token/162159))
-- **HACS** installed for package management features
-- **Supervisor** access for add-on management
-
-## Installation
-
-### Basic Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/jango-blockchained/homeassistant-mcp.git
-cd homeassistant-mcp
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
 ```
 
-### Docker Setup (Recommended)
+👉 Learn more in our [Usage Guide](docs/usage.md).
 
-The project includes Docker support for easy deployment and consistent environments across different platforms.
+---
+
+## Update Strategy 🔄
+
+Maintain a seamless operation with zero downtime updates:
 
-1. **Clone the repository:**
 ```bash
-    git clone https://github.com/jango-blockchained/homeassistant-mcp.git
+# 1. Pull the latest Docker images
-    cd homeassistant-mcp
+docker compose pull
-    ```
 
-2. **Configure environment:**
+# 2. Rebuild and restart containers smoothly
-    ```bash
-    cp .env.example .env
-    ```
-    Edit the `.env` file with your Home Assistant configuration:
-    ```env
-    # Home Assistant Configuration
-    HASS_HOST=http://homeassistant.local:8123
-    HASS_TOKEN=your_home_assistant_token
-    HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
-
-    # Server Configuration
-    PORT=3000
-    NODE_ENV=production
-    DEBUG=false
-    ```
-
-3. **Build and run with Docker Compose:**
-    ```bash
-    # Build and start the containers
-    docker compose up -d
-
-    # View logs
-    docker compose logs -f
-
-    # Stop the service
-    docker compose down
-    ```
-
-4. **Verify the installation:**
-    The server should now be running at `http://localhost:3000`. You can check the health endpoint at `http://localhost:3000/health`.
-
-5. **Update the application:**
-    ```bash
-    # Pull the latest changes
-    git pull
-
-    # Rebuild and restart the containers
 docker compose up -d --build
+
+# 3. Clean up unused Docker images to free up space
+docker system prune -f
 ```
 
-#### Docker Configuration
+For more details, review our [Troubleshooting & Updates](docs/troubleshooting.md).
 
-The Docker setup includes:
+---
-- Multi-stage build for optimal image size
-- Health checks for container monitoring
-- Volume mounting for environment configuration
-- Automatic container restart on failure
-- Exposed port 3000 for API access
 
-#### Docker Compose Environment Variables
+## Security Features 🔐
 
-All environment variables can be configured in the `.env` file. The following variables are supported:
+We prioritize the security of your smart home with multiple layers of defense:
-- `HASS_HOST`: Your Home Assistant instance URL
+- **JWT Authentication 🔑:** Secure, token-based API access to prevent unauthorized usage.
-- `HASS_TOKEN`: Long-lived access token for Home Assistant
+- **Request Sanitization 🧼:** Automatic filtering and validation of API requests to combat injection attacks.
-- `HASS_SOCKET_URL`: WebSocket URL for Home Assistant
+- **Rate Limiting & Fail2Ban 🚫:** Monitors requests to prevent brute force and DDoS attacks.
-- `PORT`: Server port (default: 3000)
+- **End-to-End Encryption 🔒:** Ensures that your commands and data remain private during transmission.
-- `NODE_ENV`: Environment (production/development)
-- `DEBUG`: Enable debug mode (true/false)
 
-## Configuration
+---
 
-### Environment Variables
+## Contributing 🤝
-
-```env
-# Home Assistant Configuration
-HASS_HOST=http://homeassistant.local:8123  # Your Home Assistant instance URL
-HASS_TOKEN=your_home_assistant_token       # Long-lived access token
-HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL
-
-# Server Configuration
-PORT=3000                # Server port (default: 3000)
-NODE_ENV=production     # Environment (production/development)
-DEBUG=false            # Enable debug mode
-
-# Test Configuration
-TEST_HASS_HOST=http://localhost:8123  # Test instance URL
-TEST_HASS_TOKEN=test_token           # Test token
-```
-
-### Configuration Files
-
-1. **Development**: Copy `.env.example` to `.env.development`
-2. **Production**: Copy `.env.example` to `.env.production`
-3. **Testing**: Copy `.env.example` to `.env.test`
-
-## Development
 
+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
-# Development mode with hot reload
+    git checkout -b feature/your-feature-name
-npm run dev
-
-# Build project
-npm run build
-
-# Production mode
-npm run start
-
-# Run tests
-npx jest --config=jest.config.cjs
-
-# Run tests with coverage
-npx jest --coverage
-
-# Lint code
-npm run lint
-
-# Format code
-npm run format
     ```
-
+3. **Install Dependencies & Run Tests 🧪**
-## API Reference
-
-For detailed API documentation, please refer to:
-- [API Documentation](docs/API.md) - Complete API reference
-- [SSE API Documentation](docs/SSE_API.md) - Server-Sent Events documentation
-
-## OpenAI Integration
-
-The server includes powerful AI analysis capabilities powered by OpenAI's GPT-4 model. This feature provides intelligent analysis of your Home Assistant setup through two main modes:
-
-### 1. Standard Analysis
-
-Performs a comprehensive system analysis including:
-- System Overview
-- Performance Analysis
-- Security Assessment
-- Optimization Recommendations
-- Maintenance Tasks
-
     ```bash
-# Run standard analysis
+    bun install
-npm run test:openai
+    bun test --coverage
-# Select option 1 when prompted
+    ```
+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`:
+
+```json
+{
+  "mcpServers": {
+    "homeassistant-mcp": {
+      "command": "bun",
+      "args": ["run", "start"],
+      "cwd": "${workspaceRoot}",
+      "env": {
+        "NODE_ENV": "development"
+      }
+    }
+  }
+}
 ```
 
-### 2. Custom Prompt Analysis
+### Claude Desktop Integration
 
-Allows you to ask specific questions about your Home Assistant setup. The analysis can include:
+For Claude Desktop, add the following to your Claude configuration file:
-- Device States
-- Configuration Details
-- Active Devices
-- Device Attributes (brightness, temperature, etc.)
 
-```bash
+```json
-# Run custom analysis
+{
-npm run test:openai
+  "mcpServers": {
-# Select option 2 when prompted
+    "homeassistant-mcp": {
+      "command": "bun",
+      "args": ["run", "start", "--port", "8080"],
+      "env": {
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}
 ```
 
-### Configuration
+### Cline Integration
 
-To use the OpenAI integration, you need to set up your OpenAI API key in the `.env` file:
+For Cline-based clients, add the following configuration:
-```env
+
-OPENAI_API_KEY=your_openai_api_key
+```json
+{
+  "mcpServers": {
+    "homeassistant-mcp": {
+      "command": "bun",
+      "args": [
+        "run",
+        "start",
+        "--enable-cline",
+        "--config",
+        "${configDir}/.env"
+      ],
+      "env": {
+        "NODE_ENV": "production",
+        "CLINE_MODE": "true"
+      }
+    }
+  }
+}
 ```
 
-## Troubleshooting
+### Command Line Usage
 
-### Common Issues
+#### Windows
+A CMD script is provided in the `scripts` directory. To use it:
 
-1. **Node.js Version (`toSorted is not a function`)**
+1. Navigate to the `scripts` directory
-   - **Solution:** Update to Node.js 20.10.0+
+2. Run `start_mcp.cmd`
-   ```bash
-   nvm install 20.10.0
-   nvm use 20.10.0
-   ```
 
-2. **Connection Issues**
+The script will start the MCP server with default configuration.
-   - Verify Home Assistant is running
-   - Check `HASS_HOST` accessibility
-   - Validate token permissions
-   - Ensure WebSocket connection for real-time updates
-
-3. **Add-on Management Issues**
-   - Verify Supervisor access
-   - Check add-on compatibility
-   - Validate system resources
-
-4. **HACS Integration Issues**
-   - Verify HACS installation
-   - Check HACS integration status
-   - Validate repository access
-
-5. **Automation Issues**
-   - Verify entity availability
-   - Check trigger conditions
-   - Validate service calls
-   - Monitor execution logs
-
-## Project Status
-
-✅ **Complete**
-- Entity, Floor, and Area access
-- Device control (Lights, Climate, Covers, Switches, Contacts)
-- Add-on management system
-- Package management through HACS
-- Advanced automation configuration
-- Basic state management
-- Error handling and validation
-- Docker containerization
-- Jest testing setup
-- TypeScript integration
-- Environment variable management
-- Home Assistant API integration
-- Project documentation
-
-🚧 **In Progress**
-- WebSocket implementation for real-time updates
-- Enhanced security features
-- Tool organization optimization
-- Performance optimization
-- Resource context integration
-- API documentation generation
-- Multi-platform desktop integration
-- Advanced error recovery
-- Custom prompt testing
-- Enhanced macOS integration
-- Type safety improvements
-- Testing coverage expansion
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Implement your changes
-4. Add tests for new functionality
-5. Ensure all tests pass
-6. Submit a pull request
-
-## Resources
-
-- [MCP Documentation](https://modelcontextprotocol.io/introduction)
-- [Home Assistant Docs](https://www.home-assistant.io)
-- [HA REST API](https://developers.home-assistant.io/docs/api/rest)
-- [HACS Documentation](https://hacs.xyz)
-- [TypeScript Documentation](https://www.typescriptlang.org/docs)
-
-## License
-
-MIT License - See [LICENSE](LICENSE) file

__tests__/core/server.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import {
+    type MockLiteMCPInstance,
+    type Tool,
+    createMockLiteMCPInstance,
+    createMockServices,
+    setupTestEnvironment,
+    cleanupMocks
+} from '../utils/test-utils';
+
+describe('Home Assistant MCP Server', () => {
+    let liteMcpInstance: MockLiteMCPInstance;
+    let addToolCalls: Tool[];
+    let mocks: ReturnType<typeof setupTestEnvironment>;
+
+    beforeEach(async () => {
+        // Setup test environment
+        mocks = setupTestEnvironment();
+        liteMcpInstance = createMockLiteMCPInstance();
+
+        // Import the module which will execute the main function
+        await import('../../src/index.js');
+
+        // Get the mock instance and tool calls
+        addToolCalls = liteMcpInstance.addTool.mock.calls.map(call => call.args[0]);
+    });
+
+    afterEach(() => {
+        cleanupMocks({ liteMcpInstance, ...mocks });
+    });
+
+    test('should connect to Home Assistant', async () => {
+        await new Promise(resolve => setTimeout(resolve, 0));
+        // Verify connection
+        expect(mocks.mockFetch.mock.calls.length).toBeGreaterThan(0);
+        expect(liteMcpInstance.start.mock.calls.length).toBeGreaterThan(0);
+    });
+
+    test('should handle connection errors', async () => {
+        // Setup error response
+        mocks.mockFetch = mock(() => Promise.reject(new Error('Connection failed')));
+        globalThis.fetch = mocks.mockFetch;
+
+        // Import module again with error mock
+        await import('../../src/index.js');
+
+        // Verify error handling
+        expect(mocks.mockFetch.mock.calls.length).toBeGreaterThan(0);
+        expect(liteMcpInstance.start.mock.calls.length).toBe(0);
+    });
+
+    describe('Tool Registration', () => {
+        test('should register all required tools', () => {
+            const toolNames = addToolCalls.map(tool => tool.name);
+
+            expect(toolNames).toContain('list_devices');
+            expect(toolNames).toContain('control');
+            expect(toolNames).toContain('get_history');
+            expect(toolNames).toContain('scene');
+            expect(toolNames).toContain('notify');
+            expect(toolNames).toContain('automation');
+            expect(toolNames).toContain('addon');
+            expect(toolNames).toContain('package');
+            expect(toolNames).toContain('automation_config');
+        });
+
+        test('should configure tools with correct parameters', () => {
+            const listDevicesTool = addToolCalls.find(tool => tool.name === 'list_devices');
+            expect(listDevicesTool).toBeDefined();
+            expect(listDevicesTool?.parameters).toBeDefined();
+
+            const controlTool = addToolCalls.find(tool => tool.name === 'control');
+            expect(controlTool).toBeDefined();
+            expect(controlTool?.parameters).toBeDefined();
+        });
+    });
+}); 

__tests__/helpers.test.ts

@@ -1,15 +1,9 @@
-import { jest, describe, it, expect } from '@jest/globals';
+import { describe, expect, test } from "bun:test";
-
+import { formatToolCall } from "../src/utils/helpers";
-// Helper function moved from src/helpers.ts
-const formatToolCall = (obj: any, isError: boolean = false) => {
-    return {
-        content: [{ type: "text", text: JSON.stringify(obj, null, 2), isError }],
-    };
-};
 
 describe('helpers', () => {
     describe('formatToolCall', () => {
-        it('should format an object into the correct structure', () => {
+        test('should format an object into the correct structure', () => {
             const testObj = { name: 'test', value: 123 };
             const result = formatToolCall(testObj);
 
@@ -22,7 +16,7 @@ describe('helpers', () => {
             });
         });
 
-        it('should handle error cases correctly', () => {
+        test('should handle error cases correctly', () => {
             const testObj = { error: 'test error' };
             const result = formatToolCall(testObj, true);
 
@@ -35,7 +29,7 @@ describe('helpers', () => {
             });
         });
 
-        it('should handle empty objects', () => {
+        test('should handle empty objects', () => {
             const testObj = {};
             const result = formatToolCall(testObj);
 
@@ -47,5 +41,26 @@ describe('helpers', () => {
                 }]
             });
         });
+
+        test('should handle null and undefined', () => {
+            const nullResult = formatToolCall(null);
+            const undefinedResult = formatToolCall(undefined);
+
+            expect(nullResult).toEqual({
+                content: [{
+                    type: 'text',
+                    text: 'null',
+                    isError: false
+                }]
+            });
+
+            expect(undefinedResult).toEqual({
+                content: [{
+                    type: 'text',
+                    text: 'undefined',
+                    isError: false
+                }]
+            });
+        });
     });
 }); 

__tests__/index.test.ts

@@ -1,42 +1,15 @@
-import { jest, describe, beforeEach, afterEach, it, expect } from '@jest/globals';
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
-import { LiteMCP } from 'litemcp';
+import type { Mock } from "bun:test";
-import { get_hass } from '../src/hass/index.js';
 import type { WebSocket } from 'ws';
+import type { LiteMCP } from 'litemcp';
 
-// Load test environment variables with defaults
+// Extend the global scope
-const TEST_HASS_HOST = process.env.TEST_HASS_HOST || 'http://localhost:8123';
+declare global {
-const TEST_HASS_TOKEN = process.env.TEST_HASS_TOKEN || 'test_token';
+    // eslint-disable-next-line no-var
-const TEST_HASS_SOCKET_URL = process.env.TEST_HASS_SOCKET_URL || 'ws://localhost:8123/api/websocket';
+    var mockResponse: Response;
+}
 
-// Set environment variables for testing
+// Types
-process.env.HASS_HOST = TEST_HASS_HOST;
-process.env.HASS_TOKEN = TEST_HASS_TOKEN;
-process.env.HASS_SOCKET_URL = TEST_HASS_SOCKET_URL;
-
-// Mock fetch
-const mockFetchResponse = {
-    ok: true,
-    status: 200,
-    statusText: 'OK',
-    json: async () => ({ automation_id: 'test_automation' }),
-    text: async () => '{"automation_id":"test_automation"}',
-    headers: new Headers(),
-    body: null,
-    bodyUsed: false,
-    arrayBuffer: async () => new ArrayBuffer(0),
-    blob: async () => new Blob([]),
-    formData: async () => new FormData(),
-    clone: function () { return { ...this }; },
-    type: 'default',
-    url: '',
-    redirected: false,
-    redirect: () => Promise.resolve(new Response())
-} as Response;
-
-const mockFetch = jest.fn(async (_input: string | URL | Request, _init?: RequestInit) => mockFetchResponse);
-(global as any).fetch = mockFetch;
-
-// Mock LiteMCP
 interface Tool {
     name: string;
     description: string;
@@ -44,30 +17,18 @@ interface Tool {
     execute: (params: Record<string, unknown>) => Promise<unknown>;
 }
 
-type MockFunction<T = any> = jest.Mock<Promise<T>, any[]>;
-
 interface MockLiteMCPInstance {
-    addTool: ReturnType<typeof jest.fn>;
+    addTool: Mock<(tool: Tool) => void>;
-    start: ReturnType<typeof jest.fn>;
+    start: Mock<() => Promise<void>>;
 }
 
-const mockLiteMCPInstance: MockLiteMCPInstance = {
-    addTool: jest.fn(),
-    start: jest.fn().mockResolvedValue(undefined)
-};
-
-jest.mock('litemcp', () => ({
-    LiteMCP: jest.fn(() => mockLiteMCPInstance)
-}));
-
-// Mock get_hass
 interface MockServices {
     light: {
-        turn_on: jest.Mock;
+        turn_on: Mock<() => Promise<{ success: boolean }>>;
-        turn_off: jest.Mock;
+        turn_off: Mock<() => Promise<{ success: boolean }>>;
     };
     climate: {
-        set_temperature: jest.Mock;
+        set_temperature: Mock<() => Promise<{ success: boolean }>>;
     };
 }
 
@@ -75,21 +36,6 @@ interface MockHassInstance {
     services: MockServices;
 }
 
-// Create mock services
-const mockServices: MockServices = {
-    light: {
-        turn_on: jest.fn().mockResolvedValue({ success: true }),
-        turn_off: jest.fn().mockResolvedValue({ success: true })
-    },
-    climate: {
-        set_temperature: jest.fn().mockResolvedValue({ success: true })
-    }
-};
-
-jest.unstable_mockModule('../src/hass/index.js', () => ({
-    get_hass: jest.fn().mockResolvedValue({ services: mockServices })
-}));
-
 interface TestResponse {
     success: boolean;
     message?: string;
@@ -103,99 +49,212 @@ interface TestResponse {
     new_automation_id?: string;
 }
 
-type WebSocketEventMap = {
+// Test configuration
-    message: MessageEvent;
+const TEST_CONFIG = {
-    open: Event;
+    HASS_HOST: process.env.TEST_HASS_HOST || 'http://localhost:8123',
-    close: Event;
+    HASS_TOKEN: process.env.TEST_HASS_TOKEN || 'test_token',
-    error: Event;
+    HASS_SOCKET_URL: process.env.TEST_HASS_SOCKET_URL || 'ws://localhost:8123/api/websocket'
+} as const;
+
+// Setup test environment
+Object.entries(TEST_CONFIG).forEach(([key, value]) => {
+    process.env[key] = value;
+});
+
+// Mock instances
+const mockLiteMCPInstance: MockLiteMCPInstance = {
+    addTool: mock((tool: Tool) => undefined),
+    start: mock(() => Promise.resolve())
 };
 
-type WebSocketEventListener = (event: Event) => void;
+const mockServices: MockServices = {
-type WebSocketMessageListener = (event: MessageEvent) => void;
+    light: {
+        turn_on: mock(() => Promise.resolve({ success: true })),
+        turn_off: mock(() => Promise.resolve({ success: true }))
+    },
+    climate: {
+        set_temperature: mock(() => Promise.resolve({ success: true }))
+    }
+};
 
-interface MockWebSocketInstance {
+// Mock WebSocket
-    addEventListener: jest.Mock;
+class MockWebSocket implements Partial<WebSocket> {
-    removeEventListener: jest.Mock;
+    public static readonly CONNECTING = 0;
-    send: jest.Mock;
+    public static readonly OPEN = 1;
-    close: jest.Mock;
+    public static readonly CLOSING = 2;
-    readyState: number;
+    public static readonly CLOSED = 3;
-    binaryType: 'blob' | 'arraybuffer';
+
-    bufferedAmount: number;
+    public readyState: 0 | 1 | 2 | 3 = MockWebSocket.OPEN;
-    extensions: string;
+    public bufferedAmount = 0;
-    protocol: string;
+    public extensions = '';
-    url: string;
+    public protocol = '';
-    onopen: WebSocketEventListener | null;
+    public url = '';
-    onerror: WebSocketEventListener | null;
+    public binaryType: 'arraybuffer' | 'nodebuffer' | 'fragments' = 'arraybuffer';
-    onclose: WebSocketEventListener | null;
+
-    onmessage: WebSocketMessageListener | null;
+    public onopen: ((event: any) => void) | null = null;
-    CONNECTING: number;
+    public onerror: ((event: any) => void) | null = null;
-    OPEN: number;
+    public onclose: ((event: any) => void) | null = null;
-    CLOSING: number;
+    public onmessage: ((event: any) => void) | null = null;
-    CLOSED: number;
+
+    public addEventListener = mock(() => undefined);
+    public removeEventListener = mock(() => undefined);
+    public send = mock(() => undefined);
+    public close = mock(() => undefined);
+    public ping = mock(() => undefined);
+    public pong = mock(() => undefined);
+    public terminate = mock(() => undefined);
+    public dispatchEvent = mock(() => true);
+
+    constructor(url: string | URL, protocols?: string | string[]) {
+        this.url = url.toString();
+        if (protocols) {
+            this.protocol = Array.isArray(protocols) ? protocols[0] : protocols;
+        }
+    }
 }
 
-const createMockWebSocket = (): MockWebSocketInstance => ({
+// Create fetch mock with implementation
-    addEventListener: jest.fn(),
+let mockFetch = mock(() => {
-    removeEventListener: jest.fn(),
+    return Promise.resolve(new Response());
-    send: jest.fn(),
-    close: jest.fn(),
-    readyState: 0,
-    binaryType: 'blob',
-    bufferedAmount: 0,
-    extensions: '',
-    protocol: '',
-    url: '',
-    onopen: null,
-    onerror: null,
-    onclose: null,
-    onmessage: null,
-    CONNECTING: 0,
-    OPEN: 1,
-    CLOSING: 2,
-    CLOSED: 3
 });
 
+// Override globals
+globalThis.fetch = mockFetch;
+// Use type assertion to handle WebSocket compatibility
+globalThis.WebSocket = MockWebSocket as any;
+
 describe('Home Assistant MCP Server', () => {
     let mockHass: MockHassInstance;
     let liteMcpInstance: MockLiteMCPInstance;
-    let addToolCalls: Array<[Tool]>;
+    let addToolCalls: Tool[];
 
     beforeEach(async () => {
         mockHass = {
             services: mockServices
         };
 
-        // Reset all mocks
+        // Reset mocks
-        jest.clearAllMocks();
+        mockLiteMCPInstance.addTool.mock.calls = [];
-        mockFetch.mockClear();
+        mockLiteMCPInstance.start.mock.calls = [];
+
+        // Setup default response
+        mockFetch = mock(() => {
+            return Promise.resolve(new Response(
+                JSON.stringify({ state: 'connected' }),
+                { status: 200 }
+            ));
+        });
+        globalThis.fetch = mockFetch;
 
         // Import the module which will execute the main function
         await import('../src/index.js');
 
-        // Mock WebSocket
-        const mockWs = createMockWebSocket();
-        (global as any).WebSocket = jest.fn(() => mockWs);
-
         // Get the mock instance
         liteMcpInstance = mockLiteMCPInstance;
-        addToolCalls = liteMcpInstance.addTool.mock.calls as Array<[Tool]>;
+        addToolCalls = mockLiteMCPInstance.addTool.mock.calls.map(call => call.args[0]);
     });
 
     afterEach(() => {
-        jest.resetModules();
+        // Clean up
+        mockLiteMCPInstance.addTool.mock.calls = [];
+        mockLiteMCPInstance.start.mock.calls = [];
+        mockFetch = mock(() => Promise.resolve(new Response()));
+        globalThis.fetch = mockFetch;
     });
 
-    it('should connect to Home Assistant', async () => {
+    test('should connect to Home Assistant', async () => {
-        const hass = await get_hass();
+        await new Promise(resolve => setTimeout(resolve, 0));
-        expect(hass).toBeDefined();
+        // Verify connection
-        expect(hass.services).toBeDefined();
+        expect(mockFetch.mock.calls.length).toBeGreaterThan(0);
-        expect(typeof hass.services.light.turn_on).toBe('function');
+        expect(mockLiteMCPInstance.start.mock.calls.length).toBeGreaterThan(0);
     });
 
-    it('should reuse the same instance on subsequent calls', async () => {
+    test('should handle connection errors', async () => {
-        const firstInstance = await get_hass();
+        // Setup error response
-        const secondInstance = await get_hass();
+        mockFetch = mock(() => Promise.reject(new Error('Connection failed')));
-        expect(firstInstance).toBe(secondInstance);
+        globalThis.fetch = mockFetch;
+
+        // Import module again with error mock
+        await import('../src/index.js');
+
+        // Verify error handling
+        expect(mockFetch.mock.calls.length).toBeGreaterThan(0);
+        expect(mockLiteMCPInstance.start.mock.calls.length).toBe(0);
+    });
+
+    describe('Tool Registration', () => {
+        test('should register all required tools', () => {
+            const toolNames = addToolCalls.map(tool => tool.name);
+
+            expect(toolNames).toContain('list_devices');
+            expect(toolNames).toContain('control');
+            expect(toolNames).toContain('get_history');
+            expect(toolNames).toContain('scene');
+            expect(toolNames).toContain('notify');
+            expect(toolNames).toContain('automation');
+            expect(toolNames).toContain('addon');
+            expect(toolNames).toContain('package');
+            expect(toolNames).toContain('automation_config');
+        });
+
+        test('should configure tools with correct parameters', () => {
+            const listDevicesTool = addToolCalls.find(tool => tool.name === 'list_devices');
+            expect(listDevicesTool).toBeDefined();
+            expect(listDevicesTool?.parameters).toBeDefined();
+
+            const controlTool = addToolCalls.find(tool => tool.name === 'control');
+            expect(controlTool).toBeDefined();
+            expect(controlTool?.parameters).toBeDefined();
+        });
+    });
+
+    describe('Tool Execution', () => {
+        test('should execute list_devices tool', async () => {
+            const listDevicesTool = addToolCalls.find(tool => tool.name === 'list_devices');
+            expect(listDevicesTool).toBeDefined();
+
+            if (listDevicesTool) {
+                const mockDevices = [
+                    {
+                        entity_id: 'light.living_room',
+                        state: 'on',
+                        attributes: { brightness: 255 }
+                    }
+                ];
+
+                // Setup response for this test
+                mockFetch = mock(() => Promise.resolve(new Response(
+                    JSON.stringify(mockDevices)
+                )));
+                globalThis.fetch = mockFetch;
+
+                const result = await listDevicesTool.execute({}) as TestResponse;
+                expect(result.success).toBe(true);
+                expect(result.devices).toBeDefined();
+            }
+        });
+
+        test('should execute control tool', async () => {
+            const controlTool = addToolCalls.find(tool => tool.name === 'control');
+            expect(controlTool).toBeDefined();
+
+            if (controlTool) {
+                // Setup response for this test
+                mockFetch = mock(() => Promise.resolve(new Response(
+                    JSON.stringify({ success: true })
+                )));
+                globalThis.fetch = mockFetch;
+
+                const result = await controlTool.execute({
+                    command: 'turn_on',
+                    entity_id: 'light.living_room',
+                    brightness: 255
+                }) as TestResponse;
+
+                expect(result.success).toBe(true);
+                expect(mockFetch.mock.calls.length).toBeGreaterThan(0);
+            }
+        });
     });
 
     describe('list_devices tool', () => {
@@ -220,7 +279,7 @@ describe('Home Assistant MCP Server', () => {
             } as Response);
 
             // Get the tool registration
-            const listDevicesTool = addToolCalls.find(call => call[0].name === 'list_devices')?.[0];
+            const listDevicesTool = addToolCalls.find(call => call.name === 'list_devices');
             expect(listDevicesTool).toBeDefined();
 
             if (!listDevicesTool) {
@@ -251,7 +310,7 @@ describe('Home Assistant MCP Server', () => {
             mockFetch.mockRejectedValueOnce(new Error('Network error'));
 
             // Get the tool registration
-            const listDevicesTool = addToolCalls.find(call => call[0].name === 'list_devices')?.[0];
+            const listDevicesTool = addToolCalls.find(call => call.name === 'list_devices');
             expect(listDevicesTool).toBeDefined();
 
             if (!listDevicesTool) {
@@ -276,7 +335,7 @@ describe('Home Assistant MCP Server', () => {
             } as Response);
 
             // Get the tool registration
-            const controlTool = addToolCalls.find(call => call[0].name === 'control')?.[0];
+            const controlTool = addToolCalls.find(call => call.name === 'control');
             expect(controlTool).toBeDefined();
 
             if (!controlTool) {
@@ -296,11 +355,11 @@ describe('Home Assistant MCP Server', () => {
 
             // Verify the fetch call
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/services/light/turn_on`,
+                `${TEST_CONFIG.HASS_HOST}/api/services/light/turn_on`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
@@ -313,7 +372,7 @@ describe('Home Assistant MCP Server', () => {
 
         it('should handle unsupported domains', async () => {
             // Get the tool registration
-            const controlTool = addToolCalls.find(call => call[0].name === 'control')?.[0];
+            const controlTool = addToolCalls.find(call => call.name === 'control');
             expect(controlTool).toBeDefined();
 
             if (!controlTool) {
@@ -339,7 +398,7 @@ describe('Home Assistant MCP Server', () => {
             } as Response);
 
             // Get the tool registration
-            const controlTool = addToolCalls.find(call => call[0].name === 'control')?.[0];
+            const controlTool = addToolCalls.find(call => call.name === 'control');
             expect(controlTool).toBeDefined();
 
             if (!controlTool) {
@@ -365,7 +424,7 @@ describe('Home Assistant MCP Server', () => {
             } as Response);
 
             // Get the tool registration
-            const controlTool = addToolCalls.find(call => call[0].name === 'control')?.[0];
+            const controlTool = addToolCalls.find(call => call.name === 'control');
             expect(controlTool).toBeDefined();
 
             if (!controlTool) {
@@ -387,11 +446,11 @@ describe('Home Assistant MCP Server', () => {
 
             // Verify the fetch call
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/services/climate/set_temperature`,
+                `${TEST_CONFIG.HASS_HOST}/api/services/climate/set_temperature`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
@@ -412,7 +471,7 @@ describe('Home Assistant MCP Server', () => {
             } as Response);
 
             // Get the tool registration
-            const controlTool = addToolCalls.find(call => call[0].name === 'control')?.[0];
+            const controlTool = addToolCalls.find(call => call.name === 'control');
             expect(controlTool).toBeDefined();
 
             if (!controlTool) {
@@ -432,11 +491,11 @@ describe('Home Assistant MCP Server', () => {
 
             // Verify the fetch call
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/services/cover/set_position`,
+                `${TEST_CONFIG.HASS_HOST}/api/services/cover/set_position`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
@@ -449,36 +508,29 @@ describe('Home Assistant MCP Server', () => {
     });
 
     describe('get_history tool', () => {
-        it('should successfully fetch history', async () => {
+        test('should successfully fetch history', async () => {
             const mockHistory = [
                 {
                     entity_id: 'light.living_room',
                     state: 'on',
                     last_changed: '2024-01-01T00:00:00Z',
                     attributes: { brightness: 255 }
-                },
-                {
-                    entity_id: 'light.living_room',
-                    state: 'off',
-                    last_changed: '2024-01-01T01:00:00Z',
-                    attributes: { brightness: 0 }
                 }
             ];
 
-            mockFetch.mockResolvedValueOnce({
+            // Setup response for this test
-                ok: true,
+            mockFetch = mock(() => Promise.resolve(new Response(
-                json: async () => mockHistory
+                JSON.stringify(mockHistory)
-            } as Response);
+            )));
+            globalThis.fetch = mockFetch;
 
-            // Get the tool registration
+            const historyTool = addToolCalls.find(call => call.name === 'get_history');
-            const historyTool = addToolCalls.find(call => call[0].name === 'get_history')?.[0];
             expect(historyTool).toBeDefined();
 
             if (!historyTool) {
                 throw new Error('get_history tool not found');
             }
 
-            // Execute the tool
             const result = (await historyTool.execute({
                 entity_id: 'light.living_room',
                 start_time: '2024-01-01T00:00:00Z',
@@ -491,29 +543,36 @@ describe('Home Assistant MCP Server', () => {
             expect(result.success).toBe(true);
             expect(result.history).toEqual(mockHistory);
 
-            // Verify the fetch call
+            // Verify the fetch call was made with correct URL and parameters
-            expect(mockFetch).toHaveBeenCalledWith(
+            const calls = mockFetch.mock.calls;
-                expect.stringContaining('/api/history/period/2024-01-01T00:00:00Z?'),
+            expect(calls.length).toBeGreaterThan(0);
-                expect.objectContaining({
+
+            const firstCall = calls[0];
+            if (!firstCall?.args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = firstCall.args;
+            const url = new URL(urlStr);
+            expect(url.pathname).toContain('/api/history/period/2024-01-01T00:00:00Z');
+            expect(url.searchParams.get('filter_entity_id')).toBe('light.living_room');
+            expect(url.searchParams.get('minimal_response')).toBe('true');
+            expect(url.searchParams.get('significant_changes_only')).toBe('true');
+
+            expect(options).toEqual({
                 headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                     'Content-Type': 'application/json'
                 }
-                })
+            });
-            );
-
-            // Verify query parameters
-            const url = mockFetch.mock.calls[0][0] as string;
-            const queryParams = new URL(url).searchParams;
-            expect(queryParams.get('filter_entity_id')).toBe('light.living_room');
-            expect(queryParams.get('minimal_response')).toBe('true');
-            expect(queryParams.get('significant_changes_only')).toBe('true');
         });
 
-        it('should handle fetch errors', async () => {
+        test('should handle fetch errors', async () => {
-            mockFetch.mockRejectedValueOnce(new Error('Network error'));
+            // Setup error response
+            mockFetch = mock(() => Promise.reject(new Error('Network error')));
+            globalThis.fetch = mockFetch;
 
-            const historyTool = addToolCalls.find(call => call[0].name === 'get_history')?.[0];
+            const historyTool = addToolCalls.find(call => call.name === 'get_history');
             expect(historyTool).toBeDefined();
 
             if (!historyTool) {
@@ -555,7 +614,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => mockScenes
             } as Response);
 
-            const sceneTool = addToolCalls.find(call => call[0].name === 'scene')?.[0];
+            const sceneTool = addToolCalls.find(call => call.name === 'scene');
             expect(sceneTool).toBeDefined();
 
             if (!sceneTool) {
@@ -587,7 +646,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => ({})
             } as Response);
 
-            const sceneTool = addToolCalls.find(call => call[0].name === 'scene')?.[0];
+            const sceneTool = addToolCalls.find(call => call.name === 'scene');
             expect(sceneTool).toBeDefined();
 
             if (!sceneTool) {
@@ -603,11 +662,11 @@ describe('Home Assistant MCP Server', () => {
             expect(result.message).toBe('Successfully activated scene scene.movie_time');
 
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/services/scene/turn_on`,
+                `${TEST_CONFIG.HASS_HOST}/api/services/scene/turn_on`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
@@ -625,7 +684,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => ({})
             } as Response);
 
-            const notifyTool = addToolCalls.find(call => call[0].name === 'notify')?.[0];
+            const notifyTool = addToolCalls.find(call => call.name === 'notify');
             expect(notifyTool).toBeDefined();
 
             if (!notifyTool) {
@@ -643,11 +702,11 @@ describe('Home Assistant MCP Server', () => {
             expect(result.message).toBe('Notification sent successfully');
 
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/services/notify/mobile_app_phone`,
+                `${TEST_CONFIG.HASS_HOST}/api/services/notify/mobile_app_phone`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
@@ -660,12 +719,13 @@ describe('Home Assistant MCP Server', () => {
         });
 
         it('should use default notification service when no target is specified', async () => {
-            mockFetch.mockResolvedValueOnce({
+            // Setup response for this test
-                ok: true,
+            mockFetch = mock(() => Promise.resolve(new Response(
-                json: async () => ({})
+                JSON.stringify({})
-            } as Response);
+            )));
+            globalThis.fetch = mockFetch;
 
-            const notifyTool = addToolCalls.find(call => call[0].name === 'notify')?.[0];
+            const notifyTool = addToolCalls.find(call => call.name === 'notify');
             expect(notifyTool).toBeDefined();
 
             if (!notifyTool) {
@@ -676,10 +736,11 @@ describe('Home Assistant MCP Server', () => {
                 message: 'Test notification'
             });
 
-            expect(mockFetch).toHaveBeenCalledWith(
+            const calls = mockFetch.mock.calls;
-                `${TEST_HASS_HOST}/api/services/notify/notify`,
+            expect(calls.length).toBeGreaterThan(0);
-                expect.any(Object)
+
-            );
+            const [url, _options] = calls[0].args;
+            expect(url.toString()).toBe(`${TEST_CONFIG.HASS_HOST}/api/services/notify/notify`);
         });
     });
 
@@ -709,7 +770,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => mockAutomations
             } as Response);
 
-            const automationTool = addToolCalls.find(call => call[0].name === 'automation')?.[0];
+            const automationTool = addToolCalls.find(call => call.name === 'automation');
             expect(automationTool).toBeDefined();
 
             if (!automationTool) {
@@ -743,7 +804,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => ({})
             } as Response);
 
-            const automationTool = addToolCalls.find(call => call[0].name === 'automation')?.[0];
+            const automationTool = addToolCalls.find(call => call.name === 'automation');
             expect(automationTool).toBeDefined();
 
             if (!automationTool) {
@@ -759,11 +820,11 @@ describe('Home Assistant MCP Server', () => {
             expect(result.message).toBe('Successfully toggled automation automation.morning_routine');
 
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/services/automation/toggle`,
+                `${TEST_CONFIG.HASS_HOST}/api/services/automation/toggle`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
@@ -779,7 +840,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => ({})
             } as Response);
 
-            const automationTool = addToolCalls.find(call => call[0].name === 'automation')?.[0];
+            const automationTool = addToolCalls.find(call => call.name === 'automation');
             expect(automationTool).toBeDefined();
 
             if (!automationTool) {
@@ -795,11 +856,11 @@ describe('Home Assistant MCP Server', () => {
             expect(result.message).toBe('Successfully triggered automation automation.morning_routine');
 
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/services/automation/trigger`,
+                `${TEST_CONFIG.HASS_HOST}/api/services/automation/trigger`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
@@ -810,7 +871,7 @@ describe('Home Assistant MCP Server', () => {
         });
 
         it('should require automation_id for toggle and trigger actions', async () => {
-            const automationTool = addToolCalls.find(call => call[0].name === 'automation')?.[0];
+            const automationTool = addToolCalls.find(call => call.name === 'automation');
             expect(automationTool).toBeDefined();
 
             if (!automationTool) {
@@ -858,7 +919,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => mockAddons
             } as Response);
 
-            const addonTool = addToolCalls.find(call => call[0].name === 'addon')?.[0];
+            const addonTool = addToolCalls.find(call => call.name === 'addon');
             expect(addonTool).toBeDefined();
 
             if (!addonTool) {
@@ -879,7 +940,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => ({ data: { state: 'installing' } })
             } as Response);
 
-            const addonTool = addToolCalls.find(call => call[0].name === 'addon')?.[0];
+            const addonTool = addToolCalls.find(call => call.name === 'addon');
             expect(addonTool).toBeDefined();
 
             if (!addonTool) {
@@ -896,11 +957,11 @@ describe('Home Assistant MCP Server', () => {
             expect(result.message).toBe('Successfully installed add-on core_configurator');
 
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/hassio/addons/core_configurator/install`,
+                `${TEST_CONFIG.HASS_HOST}/api/hassio/addons/core_configurator/install`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({ version: '5.6.0' })
@@ -931,7 +992,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => mockPackages
             } as Response);
 
-            const packageTool = addToolCalls.find(call => call[0].name === 'package')?.[0];
+            const packageTool = addToolCalls.find(call => call.name === 'package');
             expect(packageTool).toBeDefined();
 
             if (!packageTool) {
@@ -953,7 +1014,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => ({})
             } as Response);
 
-            const packageTool = addToolCalls.find(call => call[0].name === 'package')?.[0];
+            const packageTool = addToolCalls.find(call => call.name === 'package');
             expect(packageTool).toBeDefined();
 
             if (!packageTool) {
@@ -971,11 +1032,11 @@ describe('Home Assistant MCP Server', () => {
             expect(result.message).toBe('Successfully installed package hacs/integration');
 
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/hacs/repository/install`,
+                `${TEST_CONFIG.HASS_HOST}/api/hacs/repository/install`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
@@ -1016,7 +1077,7 @@ describe('Home Assistant MCP Server', () => {
                 json: async () => ({ automation_id: 'new_automation_1' })
             } as Response);
 
-            const automationConfigTool = addToolCalls.find(call => call[0].name === 'automation_config')?.[0];
+            const automationConfigTool = addToolCalls.find(call => call.name === 'automation_config');
             expect(automationConfigTool).toBeDefined();
 
             if (!automationConfigTool) {
@@ -1033,11 +1094,11 @@ describe('Home Assistant MCP Server', () => {
             expect(result.automation_id).toBe('new_automation_1');
 
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/config/automation/config`,
+                `${TEST_CONFIG.HASS_HOST}/api/config/automation/config`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify(mockAutomationConfig)
@@ -1058,7 +1119,7 @@ describe('Home Assistant MCP Server', () => {
                     json: async () => ({ automation_id: 'new_automation_2' })
                 } as Response);
 
-            const automationConfigTool = addToolCalls.find(call => call[0].name === 'automation_config')?.[0];
+            const automationConfigTool = addToolCalls.find(call => call.name === 'automation_config');
             expect(automationConfigTool).toBeDefined();
 
             if (!automationConfigTool) {
@@ -1076,17 +1137,17 @@ describe('Home Assistant MCP Server', () => {
 
             // Verify both API calls
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/config/automation/config/automation.test`,
+                `${TEST_CONFIG.HASS_HOST}/api/config/automation/config/automation.test`,
                 expect.any(Object)
             );
 
             const duplicateConfig = { ...mockAutomationConfig, alias: 'Test Automation (Copy)' };
             expect(mockFetch).toHaveBeenCalledWith(
-                `${TEST_HASS_HOST}/api/config/automation/config`,
+                `${TEST_CONFIG.HASS_HOST}/api/config/automation/config`,
                 {
                     method: 'POST',
                     headers: {
-                        Authorization: `Bearer ${TEST_HASS_TOKEN}`,
+                        Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
                         'Content-Type': 'application/json'
                     },
                     body: JSON.stringify(duplicateConfig)
@@ -1095,7 +1156,7 @@ describe('Home Assistant MCP Server', () => {
         });
 
         it('should require config for create action', async () => {
-            const automationConfigTool = addToolCalls.find(call => call[0].name === 'automation_config')?.[0];
+            const automationConfigTool = addToolCalls.find(call => call.name === 'automation_config');
             expect(automationConfigTool).toBeDefined();
 
             if (!automationConfigTool) {

__tests__/security/index.test.ts

@@ -1,212 +1,314 @@
-import { TokenManager, validateRequest, sanitizeInput, errorHandler } from '../../src/security/index.js';
+import { TokenManager, validateRequest, sanitizeInput, errorHandler, rateLimiter, securityHeaders } from '../../src/security/index.js';
-import { Request, Response } from 'express';
+import { mock, describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import jwt from 'jsonwebtoken';
+
+const TEST_SECRET = 'test-secret-that-is-long-enough-for-testing-purposes';
 
 describe('Security Module', () => {
+    beforeEach(() => {
+        process.env.JWT_SECRET = TEST_SECRET;
+    });
+
+    afterEach(() => {
+        delete process.env.JWT_SECRET;
+    });
+
     describe('TokenManager', () => {
-        const testToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNzE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
+        const testToken = 'test-token';
-        const encryptionKey = 'test_encryption_key';
+        const encryptionKey = 'test-encryption-key-that-is-long-enough';
 
         it('should encrypt and decrypt tokens', () => {
             const encrypted = TokenManager.encryptToken(testToken, encryptionKey);
-            const decrypted = TokenManager.decryptToken(encrypted, encryptionKey);
+            expect(encrypted).toContain('aes-256-gcm:');
 
+            const decrypted = TokenManager.decryptToken(encrypted, encryptionKey);
             expect(decrypted).toBe(testToken);
         });
 
         it('should validate tokens correctly', () => {
-            expect(TokenManager.validateToken(testToken)).toBe(true);
+            const validToken = jwt.sign({ data: 'test' }, TEST_SECRET, { expiresIn: '1h' });
-            expect(TokenManager.validateToken('invalid_token')).toBe(false);
+            const result = TokenManager.validateToken(validToken);
-            expect(TokenManager.validateToken('')).toBe(false);
+            expect(result.valid).toBe(true);
+            expect(result.error).toBeUndefined();
+        });
+
+        it('should handle empty tokens', () => {
+            const result = TokenManager.validateToken('');
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Invalid token format');
         });
 
         it('should handle expired tokens', () => {
-            const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
+            const now = Math.floor(Date.now() / 1000);
-            expect(TokenManager.validateToken(expiredToken)).toBe(false);
+            const payload = {
+                data: 'test',
+                iat: now - 7200,  // 2 hours ago
+                exp: now - 3600   // expired 1 hour ago
+            };
+            const token = jwt.sign(payload, TEST_SECRET);
+            const result = TokenManager.validateToken(token);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Token has expired');
+        });
+
+        it('should handle invalid token format', () => {
+            const result = TokenManager.validateToken('invalid-token');
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Invalid token format');
+        });
+
+        it('should handle missing JWT secret', () => {
+            delete process.env.JWT_SECRET;
+            const payload = { data: 'test' };
+            const token = jwt.sign(payload, 'some-secret');
+            const result = TokenManager.validateToken(token);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('JWT secret not configured');
+        });
+
+        it('should handle rate limiting for failed attempts', () => {
+            const invalidToken = 'x'.repeat(64);
+            const testIp = '127.0.0.1';
+
+            // First attempt
+            const firstResult = TokenManager.validateToken(invalidToken, testIp);
+            expect(firstResult.valid).toBe(false);
+
+            // Multiple failed attempts
+            for (let i = 0; i < 4; i++) {
+                TokenManager.validateToken(invalidToken, testIp);
+            }
+
+            // Next attempt should be rate limited
+            const limitedResult = TokenManager.validateToken(invalidToken, testIp);
+            expect(limitedResult.valid).toBe(false);
+            expect(limitedResult.error).toBe('Too many failed attempts. Please try again later.');
         });
     });
 
     describe('Request Validation', () => {
-        let mockRequest: Partial<Request>;
+        let mockRequest: any;
-        let mockResponse: Partial<Response>;
+        let mockResponse: any;
-        let mockNext: jest.Mock;
+        let mockNext: any;
 
         beforeEach(() => {
             mockRequest = {
                 method: 'POST',
                 headers: {
-                    'content-type': 'application/json',
+                    'content-type': 'application/json'
-                    authorization: 'Bearer validToken'
                 },
-                is: jest.fn().mockReturnValue(true),
+                body: {},
-                body: { test: 'data' }
+                ip: '127.0.0.1'
             };
+
             mockResponse = {
-                status: jest.fn().mockReturnThis(),
+                status: mock(() => mockResponse),
-                json: jest.fn()
+                json: mock(() => mockResponse),
+                setHeader: mock(() => mockResponse),
+                removeHeader: mock(() => mockResponse)
             };
-            mockNext = jest.fn();
+
+            mockNext = mock(() => { });
         });
 
         it('should pass valid requests', () => {
-            validateRequest(
+            if (mockRequest.headers) {
-                mockRequest as Request,
+                mockRequest.headers.authorization = 'Bearer valid-token';
-                mockResponse as Response,
+            }
-                mockNext
+            const validateTokenSpy = mock(() => ({ valid: true }));
-            );
+            TokenManager.validateToken = validateTokenSpy;
+
+            validateRequest(mockRequest, mockResponse, mockNext);
 
             expect(mockNext).toHaveBeenCalled();
-            expect(mockResponse.status).not.toHaveBeenCalled();
         });
 
         it('should reject invalid content type', () => {
-            mockRequest.is = jest.fn().mockReturnValue(false);
+            if (mockRequest.headers) {
+                mockRequest.headers['content-type'] = 'text/plain';
+            }
 
-            validateRequest(
+            validateRequest(mockRequest, mockResponse, mockNext);
-                mockRequest as Request,
-                mockResponse as Response,
-                mockNext
-            );
 
             expect(mockResponse.status).toHaveBeenCalledWith(415);
             expect(mockResponse.json).toHaveBeenCalledWith({
-                error: 'Unsupported Media Type - Content-Type must be application/json'
+                success: false,
+                message: 'Unsupported Media Type',
+                error: 'Content-Type must be application/json',
+                timestamp: expect.any(String)
             });
         });
 
         it('should reject missing token', () => {
-            mockRequest.headers = {};
+            if (mockRequest.headers) {
+                delete mockRequest.headers.authorization;
+            }
 
-            validateRequest(
+            validateRequest(mockRequest, mockResponse, mockNext);
-                mockRequest as Request,
-                mockResponse as Response,
-                mockNext
-            );
 
             expect(mockResponse.status).toHaveBeenCalledWith(401);
             expect(mockResponse.json).toHaveBeenCalledWith({
-                error: 'Invalid or expired token'
+                success: false,
+                message: 'Unauthorized',
+                error: 'Missing or invalid authorization header',
+                timestamp: expect.any(String)
             });
         });
 
         it('should reject invalid request body', () => {
             mockRequest.body = null;
 
-            validateRequest(
+            validateRequest(mockRequest, mockResponse, mockNext);
-                mockRequest as Request,
-                mockResponse as Response,
-                mockNext
-            );
 
             expect(mockResponse.status).toHaveBeenCalledWith(400);
             expect(mockResponse.json).toHaveBeenCalledWith({
-                error: 'Invalid request body'
+                success: false,
+                message: 'Bad Request',
+                error: 'Invalid request body structure',
+                timestamp: expect.any(String)
             });
         });
     });
 
     describe('Input Sanitization', () => {
-        let mockRequest: Partial<Request>;
+        let mockRequest: any;
-        let mockResponse: Partial<Response>;
+        let mockResponse: any;
-        let mockNext: jest.Mock;
+        let mockNext: any;
 
         beforeEach(() => {
             mockRequest = {
-                body: {}
+                method: 'POST',
-            };
+                headers: {
-            mockResponse = {};
+                    'content-type': 'application/json'
-            mockNext = jest.fn();
+                },
-        });
+                body: {
-
-        it('should sanitize HTML tags from request body', () => {
-            mockRequest.body = {
-                text: 'Test <script>alert("xss")</script>',
-                nested: {
-                    html: '<img src="x" onerror="alert(1)">'
-                }
-            };
-
-            sanitizeInput(
-                mockRequest as Request,
-                mockResponse as Response,
-                mockNext
-            );
-
-            expect(mockRequest.body).toEqual({
                     text: 'Test alert("xss")',
                     nested: {
                         html: 'img src="x" onerror="alert(1)"'
                     }
+                }
+            };
+
+            mockResponse = {
+                status: mock(() => mockResponse),
+                json: mock(() => mockResponse)
+            };
+
+            mockNext = mock(() => { });
+        });
+
+        it('should sanitize HTML tags from request body', () => {
+            sanitizeInput(mockRequest, mockResponse, mockNext);
+
+            expect(mockRequest.body).toEqual({
+                text: 'Test',
+                nested: {
+                    html: ''
+                }
             });
             expect(mockNext).toHaveBeenCalled();
         });
 
         it('should handle non-object body', () => {
             mockRequest.body = 'string body';
-
+            sanitizeInput(mockRequest, mockResponse, mockNext);
-            sanitizeInput(
-                mockRequest as Request,
-                mockResponse as Response,
-                mockNext
-            );
-
-            expect(mockRequest.body).toBe('string body');
             expect(mockNext).toHaveBeenCalled();
         });
     });
 
     describe('Error Handler', () => {
-        let mockRequest: Partial<Request>;
+        let mockRequest: any;
-        let mockResponse: Partial<Response>;
+        let mockResponse: any;
-        let mockNext: jest.Mock;
+        let mockNext: any;
-        const originalEnv = process.env.NODE_ENV;
 
         beforeEach(() => {
-            mockRequest = {};
+            mockRequest = {
-            mockResponse = {
+                method: 'POST',
-                status: jest.fn().mockReturnThis(),
+                ip: '127.0.0.1'
-                json: jest.fn()
             };
-            mockNext = jest.fn();
-        });
 
-        afterAll(() => {
+            mockResponse = {
-            process.env.NODE_ENV = originalEnv;
+                status: mock(() => mockResponse),
+                json: mock(() => mockResponse)
+            };
+
+            mockNext = mock(() => { });
         });
 
         it('should handle errors in production mode', () => {
             process.env.NODE_ENV = 'production';
             const error = new Error('Test error');
-
+            errorHandler(error, mockRequest, mockResponse, mockNext);
-            errorHandler(
-                error,
-                mockRequest as Request,
-                mockResponse as Response,
-                mockNext
-            );
 
             expect(mockResponse.status).toHaveBeenCalledWith(500);
             expect(mockResponse.json).toHaveBeenCalledWith({
-                error: 'Internal Server Error',
+                success: false,
-                message: undefined
+                message: 'Internal Server Error',
+                timestamp: expect.any(String)
             });
         });
 
         it('should include error message in development mode', () => {
             process.env.NODE_ENV = 'development';
             const error = new Error('Test error');
-
+            errorHandler(error, mockRequest, mockResponse, mockNext);
-            errorHandler(
-                error,
-                mockRequest as Request,
-                mockResponse as Response,
-                mockNext
-            );
 
             expect(mockResponse.status).toHaveBeenCalledWith(500);
             expect(mockResponse.json).toHaveBeenCalledWith({
-                error: 'Internal Server Error',
+                success: false,
-                message: 'Test error'
+                message: 'Internal Server Error',
+                error: 'Test error',
+                stack: expect.any(String),
+                timestamp: expect.any(String)
             });
         });
     });
+
+    describe('Rate Limiter', () => {
+        it('should limit requests after threshold', async () => {
+            const mockContext = {
+                request: new Request('http://localhost', {
+                    headers: new Headers({
+                        'x-forwarded-for': '127.0.0.1'
+                    })
+                }),
+                set: mock(() => { })
+            };
+
+            // Test multiple requests
+            for (let i = 0; i < 100; i++) {
+                await rateLimiter.derive(mockContext);
+            }
+
+            // The next request should throw
+            try {
+                await rateLimiter.derive(mockContext);
+                expect(false).toBe(true); // Should not reach here
+            } catch (error) {
+                expect(error instanceof Error).toBe(true);
+                expect(error.message).toBe('Too many requests from this IP, please try again later');
+            }
+        });
+    });
+
+    describe('Security Headers', () => {
+        it('should set security headers', async () => {
+            const mockHeaders = new Headers();
+            const mockContext = {
+                request: new Request('http://localhost', {
+                    headers: mockHeaders
+                }),
+                set: mock(() => { })
+            };
+
+            await securityHeaders.derive(mockContext);
+
+            // Verify that security headers were set
+            const headers = mockContext.request.headers;
+            expect(headers.has('content-security-policy')).toBe(true);
+            expect(headers.has('x-frame-options')).toBe(true);
+            expect(headers.has('x-content-type-options')).toBe(true);
+            expect(headers.has('referrer-policy')).toBe(true);
+        });
+    });
 }); 

__tests__/security/middleware.test.ts

@@ -1,177 +1,156 @@
-import { jest, describe, it, expect, beforeEach } from '@jest/globals';
+import { describe, it, expect } from 'bun:test';
-import { Request, Response, NextFunction } from 'express';
 import {
-    validateRequest,
+    checkRateLimit,
-    sanitizeInput,
+    validateRequestHeaders,
-    errorHandler,
+    sanitizeValue,
-    rateLimiter,
+    applySecurityHeaders,
-    securityHeaders
+    handleError
 } from '../../src/security/index.js';
 
-type MockRequest = {
+describe('Security Middleware Utilities', () => {
-    headers: {
+    describe('Rate Limiter', () => {
-        'content-type'?: string;
+        it('should allow requests under threshold', () => {
-        authorization?: string;
+            const ip = '127.0.0.1';
-    };
+            expect(() => checkRateLimit(ip, 10)).not.toThrow();
-    body?: any;
+        });
-    is: jest.MockInstance<string | false | null, [type: string | string[]]>;
-};
 
-type MockResponse = {
+        it('should throw when requests exceed threshold', () => {
-    status: jest.MockInstance<MockResponse, [code: number]>;
+            const ip = '127.0.0.2';
-    json: jest.MockInstance<MockResponse, [body: any]>;
-    setHeader: jest.MockInstance<MockResponse, [name: string, value: string]>;
-};
 
-describe('Security Middleware', () => {
+            // Simulate multiple requests
-    let mockRequest: MockRequest;
+            for (let i = 0; i < 11; i++) {
-    let mockResponse: MockResponse;
+                if (i < 10) {
-    let nextFunction: jest.Mock;
+                    expect(() => checkRateLimit(ip, 10)).not.toThrow();
+                } else {
+                    expect(() => checkRateLimit(ip, 10)).toThrow('Too many requests from this IP, please try again later');
+                }
+            }
+        });
 
-    beforeEach(() => {
+        it('should reset rate limit after window expires', async () => {
-        mockRequest = {
+            const ip = '127.0.0.3';
-            headers: {},
-            body: {},
-            is: jest.fn<string | false | null, [string | string[]]>().mockReturnValue('json')
-        };
 
-        mockResponse = {
+            // Simulate multiple requests
-            status: jest.fn<MockResponse, [number]>().mockReturnThis(),
+            for (let i = 0; i < 11; i++) {
-            json: jest.fn<MockResponse, [any]>().mockReturnThis(),
+                if (i < 10) {
-            setHeader: jest.fn<MockResponse, [string, string]>().mockReturnThis()
+                    expect(() => checkRateLimit(ip, 10, 50)).not.toThrow();
-        };
+                }
+            }
 
-        nextFunction = jest.fn();
+            // Wait for rate limit window to expire
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            // Should be able to make requests again
+            expect(() => checkRateLimit(ip, 10, 50)).not.toThrow();
+        });
     });
 
     describe('Request Validation', () => {
-        it('should pass valid requests', () => {
+        it('should validate content type', () => {
-            mockRequest.headers.authorization = 'Bearer valid-token';
+            const mockRequest = new Request('http://localhost', {
-            validateRequest(mockRequest as unknown as Request, mockResponse as unknown as Response, nextFunction);
+                method: 'POST',
-            expect(nextFunction).toHaveBeenCalled();
+                headers: {
+                    'content-type': 'application/json'
+                }
             });
 
-        it('should reject requests without authorization header', () => {
+            expect(() => validateRequestHeaders(mockRequest)).not.toThrow();
-            validateRequest(mockRequest as unknown as Request, mockResponse as unknown as Response, nextFunction);
-            expect(mockResponse.status).toHaveBeenCalledWith(401);
-            expect(mockResponse.json).toHaveBeenCalledWith(expect.objectContaining({
-                error: expect.stringContaining('authorization')
-            }));
         });
 
-        it('should reject requests with invalid authorization format', () => {
+        it('should reject invalid content type', () => {
-            mockRequest.headers.authorization = 'invalid-format';
+            const mockRequest = new Request('http://localhost', {
-            validateRequest(mockRequest as unknown as Request, mockResponse as unknown as Response, nextFunction);
+                method: 'POST',
-            expect(mockResponse.status).toHaveBeenCalledWith(401);
+                headers: {
-            expect(mockResponse.json).toHaveBeenCalledWith(expect.objectContaining({
+                    'content-type': 'text/plain'
-                error: expect.stringContaining('Bearer')
+                }
-            }));
+            });
+
+            expect(() => validateRequestHeaders(mockRequest)).toThrow('Content-Type must be application/json');
+        });
+
+        it('should reject large request bodies', () => {
+            const mockRequest = new Request('http://localhost', {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'content-length': '2000000'
+                }
+            });
+
+            expect(() => validateRequestHeaders(mockRequest)).toThrow('Request body too large');
         });
     });
 
     describe('Input Sanitization', () => {
-        it('should pass requests without body', () => {
+        it('should sanitize HTML tags', () => {
-            delete mockRequest.body;
+            const input = '<script>alert("xss")</script>Hello';
-            sanitizeInput(mockRequest as unknown as Request, mockResponse as unknown as Response, nextFunction);
+            const sanitized = sanitizeValue(input);
-            expect(nextFunction).toHaveBeenCalled();
+            expect(sanitized).toBe('&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;Hello');
         });
 
-        it('should sanitize HTML in request body', () => {
+        it('should sanitize nested objects', () => {
-            mockRequest.body = {
+            const input = {
                 text: '<script>alert("xss")</script>Hello',
                 nested: {
                     html: '<img src="x" onerror="alert(1)">World'
                 }
             };
-            sanitizeInput(mockRequest as unknown as Request, mockResponse as unknown as Response, nextFunction);
+            const sanitized = sanitizeValue(input);
-            expect(mockRequest.body.text).toBe('Hello');
+            expect(sanitized).toEqual({
-            expect(mockRequest.body.nested.html).toBe('World');
+                text: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;Hello',
-            expect(nextFunction).toHaveBeenCalled();
+                nested: {
+                    html: '&lt;img src=&quot;x&quot; onerror=&quot;alert(1)&quot;&gt;World'
+                }
             });
-
-        it('should handle non-object bodies', () => {
-            mockRequest.body = '<p>text</p>';
-            sanitizeInput(mockRequest as unknown as Request, mockResponse as unknown as Response, nextFunction);
-            expect(mockRequest.body).toBe('text');
-            expect(nextFunction).toHaveBeenCalled();
         });
 
         it('should preserve non-string values', () => {
-            mockRequest.body = {
+            const input = {
-                number: 42,
+                number: 123,
                 boolean: true,
-                null: null,
                 array: [1, 2, 3]
             };
-            sanitizeInput(mockRequest as unknown as Request, mockResponse as unknown as Response, nextFunction);
+            const sanitized = sanitizeValue(input);
-            expect(mockRequest.body).toEqual({
+            expect(sanitized).toEqual(input);
-                number: 42,
-                boolean: true,
-                null: null,
-                array: [1, 2, 3]
-            });
-            expect(nextFunction).toHaveBeenCalled();
-        });
-    });
-
-    describe('Error Handler', () => {
-        const originalEnv = process.env.NODE_ENV;
-
-        afterAll(() => {
-            process.env.NODE_ENV = originalEnv;
-        });
-
-        it('should handle errors in production mode', () => {
-            process.env.NODE_ENV = 'production';
-            const error = new Error('Test error');
-            errorHandler(error, mockRequest as Request, mockResponse as Response, nextFunction);
-            expect(mockResponse.status).toHaveBeenCalledWith(500);
-            expect(mockResponse.json).toHaveBeenCalledWith({
-                error: 'Internal Server Error'
-            });
-        });
-
-        it('should include error details in development mode', () => {
-            process.env.NODE_ENV = 'development';
-            const error = new Error('Test error');
-            errorHandler(error, mockRequest as Request, mockResponse as Response, nextFunction);
-            expect(mockResponse.status).toHaveBeenCalledWith(500);
-            expect(mockResponse.json).toHaveBeenCalledWith({
-                error: 'Test error',
-                stack: expect.any(String)
-            });
-        });
-
-        it('should handle non-Error objects', () => {
-            const error = 'String error message';
-
-            errorHandler(
-                error as any,
-                mockRequest as Request,
-                mockResponse as Response,
-                nextFunction
-            );
-
-            expect(mockResponse.status).toHaveBeenCalledWith(500);
-        });
-    });
-
-    describe('Rate Limiter', () => {
-        it('should be configured with correct options', () => {
-            expect(rateLimiter).toBeDefined();
-            const middleware = rateLimiter as any;
-            expect(middleware.windowMs).toBeDefined();
-            expect(middleware.max).toBeDefined();
         });
     });
 
     describe('Security Headers', () => {
-        it('should set appropriate security headers', () => {
+        it('should apply security headers', () => {
-            securityHeaders(mockRequest as Request, mockResponse as Response, nextFunction);
+            const mockRequest = new Request('http://localhost');
-            expect(mockResponse.setHeader).toHaveBeenCalledWith('X-Content-Type-Options', 'nosniff');
+            const headers = applySecurityHeaders(mockRequest);
-            expect(mockResponse.setHeader).toHaveBeenCalledWith('X-Frame-Options', 'DENY');
+
-            expect(mockResponse.setHeader).toHaveBeenCalledWith('X-XSS-Protection', '1; mode=block');
+            expect(headers).toBeDefined();
-            expect(nextFunction).toHaveBeenCalled();
+            expect(headers['content-security-policy']).toBeDefined();
+            expect(headers['x-frame-options']).toBeDefined();
+            expect(headers['x-content-type-options']).toBeDefined();
+            expect(headers['referrer-policy']).toBeDefined();
+        });
+    });
+
+    describe('Error Handling', () => {
+        it('should handle errors in production mode', () => {
+            const error = new Error('Test error');
+            const result = handleError(error, 'production');
+
+            expect(result).toEqual({
+                error: true,
+                message: 'Internal server error',
+                timestamp: expect.any(String)
+            });
+        });
+
+        it('should include error details in development mode', () => {
+            const error = new Error('Test error');
+            const result = handleError(error, 'development');
+
+            expect(result).toEqual({
+                error: true,
+                message: 'Internal server error',
+                timestamp: expect.any(String),
+                error: 'Test error',
+                stack: expect.any(String)
+            });
         });
     });
 }); 

__tests__/security/token-manager.test.ts

@@ -1,6 +1,17 @@
 import { TokenManager } from '../../src/security/index.js';
+import jwt from 'jsonwebtoken';
+
+const TEST_SECRET = 'test-secret-that-is-long-enough-for-testing-purposes';
 
 describe('TokenManager', () => {
+    beforeAll(() => {
+        process.env.JWT_SECRET = TEST_SECRET;
+    });
+
+    afterAll(() => {
+        delete process.env.JWT_SECRET;
+    });
+
     const encryptionKey = 'test-encryption-key-32-chars-long!!';
     const validToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNjE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
 
@@ -35,27 +46,51 @@ describe('TokenManager', () => {
 
     describe('Token Validation', () => {
         it('should validate correct tokens', () => {
-            const validJwt = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNjcyNTI3OTk5fQ.Q6cm_sZS6uqfGqO3LQ-0VqNXhqXR6mFh6IP7s0NPnSQ';
+            const payload = { sub: '123', name: 'Test User', iat: Math.floor(Date.now() / 1000), exp: Math.floor(Date.now() / 1000) + 3600 };
-            expect(TokenManager.validateToken(validJwt)).toBe(true);
+            const token = jwt.sign(payload, TEST_SECRET);
+            const result = TokenManager.validateToken(token);
+            expect(result.valid).toBe(true);
+            expect(result.error).toBeUndefined();
         });
 
         it('should reject expired tokens', () => {
-            const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
+            const payload = { sub: '123', name: 'Test User', iat: Math.floor(Date.now() / 1000) - 7200, exp: Math.floor(Date.now() / 1000) - 3600 };
-            expect(TokenManager.validateToken(expiredToken)).toBe(false);
+            const token = jwt.sign(payload, TEST_SECRET);
+            const result = TokenManager.validateToken(token);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Token has expired');
         });
 
         it('should reject malformed tokens', () => {
-            expect(TokenManager.validateToken('invalid-token')).toBe(false);
+            const result = TokenManager.validateToken('invalid-token');
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Token length below minimum requirement');
         });
 
         it('should reject tokens with invalid signature', () => {
-            const tamperedToken = validToken.slice(0, -5) + 'xxxxx';
+            const payload = { sub: '123', name: 'Test User', iat: Math.floor(Date.now() / 1000), exp: Math.floor(Date.now() / 1000) + 3600 };
-            expect(TokenManager.validateToken(tamperedToken)).toBe(false);
+            const token = jwt.sign(payload, 'different-secret');
+            const result = TokenManager.validateToken(token);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Invalid token signature');
         });
 
         it('should handle tokens with missing expiration', () => {
-            const noExpToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0.Q6cm_sZS6uqfGqO3LQ-0VqNXhqXR6mFh6IP7s0NPnSQ';
+            const payload = { sub: '123', name: 'Test User' };
-            expect(TokenManager.validateToken(noExpToken)).toBe(false);
+            const token = jwt.sign(payload, TEST_SECRET);
+            const result = TokenManager.validateToken(token);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Token missing required claims');
+        });
+
+        it('should handle undefined and null inputs', () => {
+            const undefinedResult = TokenManager.validateToken(undefined);
+            expect(undefinedResult.valid).toBe(false);
+            expect(undefinedResult.error).toBe('Invalid token format');
+
+            const nullResult = TokenManager.validateToken(null);
+            expect(nullResult.valid).toBe(false);
+            expect(nullResult.error).toBe('Invalid token format');
         });
     });
 
@@ -103,10 +138,5 @@ describe('TokenManager', () => {
         it('should handle invalid base64 input', () => {
             expect(() => TokenManager.decryptToken('not-base64!@#$%^', encryptionKey)).toThrow();
         });
-
-        it('should handle undefined and null inputs', () => {
-            expect(TokenManager.validateToken(undefined as any)).toBe(false);
-            expect(TokenManager.validateToken(null as any)).toBe(false);
-        });
     });
 }); 

__tests__/server.test.ts

@@ -1,61 +1,81 @@
-import { jest, describe, beforeEach, afterEach, it, expect } from '@jest/globals';
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
-import express from 'express';
+import type { Mock } from "bun:test";
-import { LiteMCP } from 'litemcp';
+import type { Express, Application } from 'express';
-import { logger } from '../src/utils/logger.js';
+import type { Logger } from 'winston';
+
+// 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
-jest.mock('express', () => {
+const mockApp: MockApp = {
-    const mockApp = {
+    use: mock(() => undefined),
-        use: jest.fn(),
+    listen: mock((port: number, callback: () => void) => {
-        listen: jest.fn((port: number, callback: () => void) => {
         callback();
-            return { close: jest.fn() };
+        return { close: mock(() => undefined) };
     })
 };
-    return jest.fn(() => mockApp);
+const mockExpress = mock(() => mockApp);
-});
 
-// Mock LiteMCP
+// Mock LiteMCP instance
-jest.mock('litemcp', () => ({
+const mockLiteMCPInstance: MockLiteMCPInstance = {
-    LiteMCP: jest.fn(() => ({
+    addTool: mock(() => undefined),
-        addTool: jest.fn(),
+    start: mock(() => Promise.resolve())
-        start: jest.fn().mockImplementation(async () => { })
+};
-    }))
+const mockLiteMCP = mock((name: string, version: string) => mockLiteMCPInstance);
-}));
 
 // Mock logger
-jest.mock('../src/utils/logger.js', () => ({
+const mockLogger: MockLogger = {
-    logger: {
+    info: mock((message: string) => undefined),
-        info: jest.fn(),
+    error: mock((message: string) => undefined),
-        error: jest.fn(),
+    debug: mock((message: string) => undefined)
-        debug: jest.fn()
+};
-    }
-}));
 
 describe('Server Initialization', () => {
     let originalEnv: NodeJS.ProcessEnv;
-    let mockApp: ReturnType<typeof express>;
 
     beforeEach(() => {
         // Store original environment
         originalEnv = { ...process.env };
 
-        // Reset all mocks
+        // Setup mocks
-        jest.clearAllMocks();
+        (globalThis as any).express = mockExpress;
+        (globalThis as any).LiteMCP = mockLiteMCP;
+        (globalThis as any).logger = mockLogger;
 
-        // Get the mock express app
+        // Reset all mocks
-        mockApp = express();
+        mockApp.use.mockReset();
+        mockApp.listen.mockReset();
+        mockLogger.info.mockReset();
+        mockLogger.error.mockReset();
+        mockLogger.debug.mockReset();
+        mockLiteMCP.mockReset();
     });
 
     afterEach(() => {
         // Restore original environment
         process.env = originalEnv;
 
-        // Clear module cache to ensure fresh imports
+        // Clean up mocks
-        jest.resetModules();
+        delete (globalThis as any).express;
+        delete (globalThis as any).LiteMCP;
+        delete (globalThis as any).logger;
     });
 
-    it('should start Express server when not in Claude mode', async () => {
+    test('should start Express server when not in Claude mode', async () => {
         // Set OpenAI mode
         process.env.PROCESSOR_TYPE = 'openai';
 
@@ -63,13 +83,15 @@ describe('Server Initialization', () => {
         await import('../src/index.js');
 
         // Verify Express server was initialized
-        expect(express).toHaveBeenCalled();
+        expect(mockExpress.mock.calls.length).toBeGreaterThan(0);
-        expect(mockApp.use).toHaveBeenCalled();
+        expect(mockApp.use.mock.calls.length).toBeGreaterThan(0);
-        expect(mockApp.listen).toHaveBeenCalled();
+        expect(mockApp.listen.mock.calls.length).toBeGreaterThan(0);
-        expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('Server is running on port'));
+
+        const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
+        expect(infoMessages.some(msg => msg.includes('Server is running on port'))).toBe(true);
     });
 
-    it('should not start Express server in Claude mode', async () => {
+    test('should not start Express server in Claude mode', async () => {
         // Set Claude mode
         process.env.PROCESSOR_TYPE = 'claude';
 
@@ -77,28 +99,38 @@ describe('Server Initialization', () => {
         await import('../src/index.js');
 
         // Verify Express server was not initialized
-        expect(express).not.toHaveBeenCalled();
+        expect(mockExpress.mock.calls.length).toBe(0);
-        expect(mockApp.use).not.toHaveBeenCalled();
+        expect(mockApp.use.mock.calls.length).toBe(0);
-        expect(mockApp.listen).not.toHaveBeenCalled();
+        expect(mockApp.listen.mock.calls.length).toBe(0);
-        expect(logger.info).toHaveBeenCalledWith('Running in Claude mode - Express server disabled');
+
+        const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
+        expect(infoMessages).toContain('Running in Claude mode - Express server disabled');
     });
 
-    it('should initialize LiteMCP in both modes', async () => {
+    test('should initialize LiteMCP in both modes', async () => {
         // Test OpenAI mode
         process.env.PROCESSOR_TYPE = 'openai';
         await import('../src/index.js');
-        expect(LiteMCP).toHaveBeenCalledWith('home-assistant', expect.any(String));
 
-        // Reset modules
+        expect(mockLiteMCP.mock.calls.length).toBeGreaterThan(0);
-        jest.resetModules();
+        const [name, version] = mockLiteMCP.mock.calls[0] ?? [];
+        expect(name).toBe('home-assistant');
+        expect(typeof version).toBe('string');
+
+        // Reset for next test
+        mockLiteMCP.mockReset();
 
         // Test Claude mode
         process.env.PROCESSOR_TYPE = 'claude';
         await import('../src/index.js');
-        expect(LiteMCP).toHaveBeenCalledWith('home-assistant', expect.any(String));
+
+        expect(mockLiteMCP.mock.calls.length).toBeGreaterThan(0);
+        const [name2, version2] = mockLiteMCP.mock.calls[0] ?? [];
+        expect(name2).toBe('home-assistant');
+        expect(typeof version2).toBe('string');
     });
 
-    it('should handle missing PROCESSOR_TYPE (default to Express server)', async () => {
+    test('should handle missing PROCESSOR_TYPE (default to Express server)', async () => {
         // Remove PROCESSOR_TYPE
         delete process.env.PROCESSOR_TYPE;
 
@@ -106,9 +138,11 @@ describe('Server Initialization', () => {
         await import('../src/index.js');
 
         // Verify Express server was initialized (default behavior)
-        expect(express).toHaveBeenCalled();
+        expect(mockExpress.mock.calls.length).toBeGreaterThan(0);
-        expect(mockApp.use).toHaveBeenCalled();
+        expect(mockApp.use.mock.calls.length).toBeGreaterThan(0);
-        expect(mockApp.listen).toHaveBeenCalled();
+        expect(mockApp.listen.mock.calls.length).toBeGreaterThan(0);
-        expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('Server is running on port'));
+
+        const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
+        expect(infoMessages.some(msg => msg.includes('Server is running on port'))).toBe(true);
     });
 }); 

__tests__/speech/speechToText.test.ts

@@ -0,0 +1,327 @@
+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';
+
+// 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);
+    }
+}));
+
+describe('SpeechToText', () => {
+    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();
+    });
+
+    afterEach(() => {
+        speechToText.stopWakeWordDetection();
+        // Clean up test files
+        if (fs.existsSync(testAudioDir)) {
+            fs.rmSync(testAudioDir, { recursive: true, force: true });
+        }
+    });
+
+    describe('Initialization', () => {
+        it('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);
+        });
+
+        it('should initialize successfully', async () => {
+            const initSpy = spyOn(speechToText, 'initialize');
+            await speechToText.initialize();
+            expect(initSpy).toHaveBeenCalled();
+        });
+
+        it('should not initialize twice', async () => {
+            await speechToText.initialize();
+            const initSpy = spyOn(speechToText, 'initialize');
+            await speechToText.initialize();
+            expect(initSpy.mock.calls.length).toBe(1);
+        });
+    });
+
+    describe('Health Check', () => {
+        it('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);
+
+            setTimeout(() => {
+                mockProcess.stdout.emit('data', Buffer.from('Up 2 hours'));
+            }, 0);
+
+            const result = await speechToText.checkHealth();
+            expect(result).toBe(true);
+        });
+
+        it('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);
+
+            const result = await speechToText.checkHealth();
+            expect(result).toBe(false);
+        });
+
+        it('should handle Docker command errors', async () => {
+            spawnMock.mockImplementation(() => {
+                throw new Error('Docker not found');
+            });
+
+            const result = await speechToText.checkHealth();
+            expect(result).toBe(false);
+        });
+    });
+
+    describe('Wake Word Detection', () => {
+        it('should detect wake word and emit event', async () => {
+            const testFile = path.join(testAudioDir, 'wake_word_test_123456.wav');
+            const testMetadata = `${testFile}.json`;
+
+            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');
+                    resolve();
+                });
+
+                // Create a test audio file to trigger the event
+                fs.writeFileSync(testFile, 'test audio content');
+            });
+        });
+
+        it('should handle non-wake-word files', async () => {
+            const testFile = path.join(testAudioDir, 'regular_audio.wav');
+            let eventEmitted = false;
+
+            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);
+                    resolve();
+                }, 100);
+            });
+        });
+    });
+
+    describe('Audio Transcription', () => {
+        const mockTranscriptionResult: TranscriptionResult = {
+            text: 'Hello world',
+            segments: [{
+                text: 'Hello world',
+                start: 0,
+                end: 1,
+                confidence: 0.95
+            }]
+        };
+
+        it('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');
+
+            setTimeout(() => {
+                mockProcess.stdout.emit('data', Buffer.from(JSON.stringify(mockTranscriptionResult)));
+            }, 0);
+
+            const result = await transcriptionPromise;
+            expect(result).toEqual(mockTranscriptionResult);
+        });
+
+        it('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');
+
+            setTimeout(() => {
+                mockProcess.stderr.emit('data', Buffer.from('Transcription failed'));
+            }, 0);
+
+            await expect(transcriptionPromise).rejects.toThrow(TranscriptionError);
+        });
+
+        it('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');
+
+            setTimeout(() => {
+                mockProcess.stdout.emit('data', Buffer.from('Invalid JSON'));
+            }, 0);
+
+            await expect(transcriptionPromise).rejects.toThrow(TranscriptionError);
+        });
+
+        it('should pass correct transcription options', async () => {
+            const options: TranscriptionOptions = {
+                model: 'large-v2',
+                language: 'en',
+                temperature: 0.5,
+                beamSize: 3,
+                patience: 2,
+                device: 'cuda'
+            };
+
+            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', 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(() => { });
+        });
+    });
+
+    describe('Event Handling', () => {
+        it('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();
+                    }
+                });
+
+                void speechToText.transcribeAudio('/test/audio.wav');
+
+                mockProcess.stdout.emit('data', Buffer.from('Processing'));
+                mockProcess.stderr.emit('data', Buffer.from('Loading model'));
+            });
+        });
+
+        it('should emit error events', async () => {
+            return new Promise<void>((resolve) => {
+                speechToText.on('error', (error) => {
+                    expect(error instanceof Error).toBe(true);
+                    expect(error.message).toBe('Test error');
+                    resolve();
+                });
+
+                speechToText.emit('error', new Error('Test error'));
+            });
+        });
+    });
+
+    describe('Cleanup', () => {
+        it('should stop wake word detection', () => {
+            speechToText.startWakeWordDetection(testAudioDir);
+            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);
+        });
+
+        it('should clean up resources on shutdown', async () => {
+            await speechToText.initialize();
+            const shutdownSpy = spyOn(speechToText, 'shutdown');
+            await speechToText.shutdown();
+            expect(shutdownSpy).toHaveBeenCalled();
+        });
+    });
+}); 

__tests__/tools/automation-config.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import {
+    type MockLiteMCPInstance,
+    type Tool,
+    type TestResponse,
+    TEST_CONFIG,
+    createMockLiteMCPInstance,
+    setupTestEnvironment,
+    cleanupMocks,
+    createMockResponse,
+    getMockCallArgs
+} from '../utils/test-utils';
+
+describe('Automation Configuration Tools', () => {
+    let liteMcpInstance: MockLiteMCPInstance;
+    let addToolCalls: Tool[];
+    let mocks: ReturnType<typeof setupTestEnvironment>;
+
+    const mockAutomationConfig = {
+        alias: 'Test Automation',
+        description: 'Test automation description',
+        mode: 'single',
+        trigger: [
+            {
+                platform: 'state',
+                entity_id: 'binary_sensor.motion',
+                to: 'on'
+            }
+        ],
+        action: [
+            {
+                service: 'light.turn_on',
+                target: {
+                    entity_id: 'light.living_room'
+                }
+            }
+        ]
+    };
+
+    beforeEach(async () => {
+        // Setup test environment
+        mocks = setupTestEnvironment();
+        liteMcpInstance = createMockLiteMCPInstance();
+
+        // Import the module which will execute the main function
+        await import('../../src/index.js');
+
+        // Get the mock instance and tool calls
+        addToolCalls = liteMcpInstance.addTool.mock.calls.map(call => call.args[0]);
+    });
+
+    afterEach(() => {
+        cleanupMocks({ liteMcpInstance, ...mocks });
+    });
+
+    describe('automation_config tool', () => {
+        test('should successfully create an automation', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse({
+                automation_id: 'new_automation_1'
+            })));
+            globalThis.fetch = mocks.mockFetch;
+
+            const automationConfigTool = addToolCalls.find(tool => tool.name === 'automation_config');
+            expect(automationConfigTool).toBeDefined();
+
+            if (!automationConfigTool) {
+                throw new Error('automation_config tool not found');
+            }
+
+            const result = await automationConfigTool.execute({
+                action: 'create',
+                config: mockAutomationConfig
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully created automation');
+            expect(result.automation_id).toBe('new_automation_1');
+
+            // Verify the fetch call
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/config/automation/config`);
+            expect(options).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(mockAutomationConfig)
+            });
+        });
+
+        test('should successfully duplicate an automation', async () => {
+            // Setup responses for get and create
+            let callCount = 0;
+            mocks.mockFetch = mock(() => {
+                callCount++;
+                return Promise.resolve(
+                    callCount === 1
+                        ? createMockResponse(mockAutomationConfig)
+                        : createMockResponse({ automation_id: 'new_automation_2' })
+                );
+            });
+            globalThis.fetch = mocks.mockFetch;
+
+            const automationConfigTool = addToolCalls.find(tool => tool.name === 'automation_config');
+            expect(automationConfigTool).toBeDefined();
+
+            if (!automationConfigTool) {
+                throw new Error('automation_config tool not found');
+            }
+
+            const result = await automationConfigTool.execute({
+                action: 'duplicate',
+                automation_id: 'automation.test'
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully duplicated automation automation.test');
+            expect(result.new_automation_id).toBe('new_automation_2');
+
+            // Verify both API calls
+            type FetchArgs = [url: string, init: RequestInit];
+            const calls = mocks.mockFetch.mock.calls;
+            expect(calls.length).toBe(2);
+
+            // Verify get call
+            const getArgs = getMockCallArgs<FetchArgs>(mocks.mockFetch, 0);
+            expect(getArgs).toBeDefined();
+            if (!getArgs) throw new Error('No get call recorded');
+
+            const [getUrl, getOptions] = getArgs;
+            expect(getUrl).toBe(`${TEST_CONFIG.HASS_HOST}/api/config/automation/config/automation.test`);
+            expect(getOptions).toEqual({
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+
+            // Verify create call
+            const createArgs = getMockCallArgs<FetchArgs>(mocks.mockFetch, 1);
+            expect(createArgs).toBeDefined();
+            if (!createArgs) throw new Error('No create call recorded');
+
+            const [createUrl, createOptions] = createArgs;
+            expect(createUrl).toBe(`${TEST_CONFIG.HASS_HOST}/api/config/automation/config`);
+            expect(createOptions).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    ...mockAutomationConfig,
+                    alias: 'Test Automation (Copy)'
+                })
+            });
+        });
+
+        test('should require config for create action', async () => {
+            const automationConfigTool = addToolCalls.find(tool => tool.name === 'automation_config');
+            expect(automationConfigTool).toBeDefined();
+
+            if (!automationConfigTool) {
+                throw new Error('automation_config tool not found');
+            }
+
+            const result = await automationConfigTool.execute({
+                action: 'create'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Configuration is required for creating automation');
+        });
+
+        test('should require automation_id for update action', async () => {
+            const automationConfigTool = addToolCalls.find(tool => tool.name === 'automation_config');
+            expect(automationConfigTool).toBeDefined();
+
+            if (!automationConfigTool) {
+                throw new Error('automation_config tool not found');
+            }
+
+            const result = await automationConfigTool.execute({
+                action: 'update',
+                config: mockAutomationConfig
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Automation ID and configuration are required for updating automation');
+        });
+    });
+}); 

__tests__/tools/automation.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import {
+    type MockLiteMCPInstance,
+    type Tool,
+    type TestResponse,
+    TEST_CONFIG,
+    createMockLiteMCPInstance,
+    setupTestEnvironment,
+    cleanupMocks,
+    createMockResponse,
+    getMockCallArgs
+} from '../utils/test-utils';
+
+describe('Automation Tools', () => {
+    let liteMcpInstance: MockLiteMCPInstance;
+    let addToolCalls: Tool[];
+    let mocks: ReturnType<typeof setupTestEnvironment>;
+
+    beforeEach(async () => {
+        // Setup test environment
+        mocks = setupTestEnvironment();
+        liteMcpInstance = createMockLiteMCPInstance();
+
+        // Import the module which will execute the main function
+        await import('../../src/index.js');
+
+        // Get the mock instance and tool calls
+        addToolCalls = liteMcpInstance.addTool.mock.calls.map(call => call.args[0]);
+    });
+
+    afterEach(() => {
+        cleanupMocks({ liteMcpInstance, ...mocks });
+    });
+
+    describe('automation tool', () => {
+        const mockAutomations = [
+            {
+                entity_id: 'automation.morning_routine',
+                state: 'on',
+                attributes: {
+                    friendly_name: 'Morning Routine',
+                    last_triggered: '2024-01-01T07:00:00Z'
+                }
+            },
+            {
+                entity_id: 'automation.night_mode',
+                state: 'off',
+                attributes: {
+                    friendly_name: 'Night Mode',
+                    last_triggered: '2024-01-01T22:00:00Z'
+                }
+            }
+        ];
+
+        test('should successfully list automations', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse(mockAutomations)));
+            globalThis.fetch = mocks.mockFetch;
+
+            const automationTool = addToolCalls.find(tool => tool.name === 'automation');
+            expect(automationTool).toBeDefined();
+
+            if (!automationTool) {
+                throw new Error('automation tool not found');
+            }
+
+            const result = await automationTool.execute({
+                action: 'list'
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.automations).toEqual([
+                {
+                    entity_id: 'automation.morning_routine',
+                    name: 'Morning Routine',
+                    state: 'on',
+                    last_triggered: '2024-01-01T07:00:00Z'
+                },
+                {
+                    entity_id: 'automation.night_mode',
+                    name: 'Night Mode',
+                    state: 'off',
+                    last_triggered: '2024-01-01T22:00:00Z'
+                }
+            ]);
+        });
+
+        test('should successfully toggle an automation', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse({})));
+            globalThis.fetch = mocks.mockFetch;
+
+            const automationTool = addToolCalls.find(tool => tool.name === 'automation');
+            expect(automationTool).toBeDefined();
+
+            if (!automationTool) {
+                throw new Error('automation tool not found');
+            }
+
+            const result = await automationTool.execute({
+                action: 'toggle',
+                automation_id: 'automation.morning_routine'
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully toggled automation automation.morning_routine');
+
+            // Verify the fetch call
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/services/automation/toggle`);
+            expect(options).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    entity_id: 'automation.morning_routine'
+                })
+            });
+        });
+
+        test('should successfully trigger an automation', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse({})));
+            globalThis.fetch = mocks.mockFetch;
+
+            const automationTool = addToolCalls.find(tool => tool.name === 'automation');
+            expect(automationTool).toBeDefined();
+
+            if (!automationTool) {
+                throw new Error('automation tool not found');
+            }
+
+            const result = await automationTool.execute({
+                action: 'trigger',
+                automation_id: 'automation.morning_routine'
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully triggered automation automation.morning_routine');
+
+            // Verify the fetch call
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/services/automation/trigger`);
+            expect(options).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    entity_id: 'automation.morning_routine'
+                })
+            });
+        });
+
+        test('should require automation_id for toggle and trigger actions', async () => {
+            const automationTool = addToolCalls.find(tool => tool.name === 'automation');
+            expect(automationTool).toBeDefined();
+
+            if (!automationTool) {
+                throw new Error('automation tool not found');
+            }
+
+            const result = await automationTool.execute({
+                action: 'toggle'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Automation ID is required for toggle and trigger actions');
+        });
+    });
+}); 

__tests__/tools/device-control.test.ts

@@ -0,0 +1,361 @@
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import {
+    type MockLiteMCPInstance,
+    type Tool,
+    type TestResponse,
+    TEST_CONFIG,
+    createMockLiteMCPInstance,
+    createMockServices,
+    setupTestEnvironment,
+    cleanupMocks,
+    createMockResponse,
+    getMockCallArgs
+} from '../utils/test-utils';
+
+describe('Device Control Tools', () => {
+    let liteMcpInstance: MockLiteMCPInstance;
+    let addToolCalls: Tool[];
+    let mocks: ReturnType<typeof setupTestEnvironment>;
+
+    beforeEach(async () => {
+        // Setup test environment
+        mocks = setupTestEnvironment();
+        liteMcpInstance = createMockLiteMCPInstance();
+
+        // Import the module which will execute the main function
+        await import('../../src/index.js');
+
+        // Get the mock instance and tool calls
+        addToolCalls = liteMcpInstance.addTool.mock.calls.map(call => call.args[0]);
+    });
+
+    afterEach(() => {
+        cleanupMocks({ liteMcpInstance, ...mocks });
+    });
+
+    describe('list_devices tool', () => {
+        test('should successfully list devices', async () => {
+            const mockDevices = [
+                {
+                    entity_id: 'light.living_room',
+                    state: 'on',
+                    attributes: { brightness: 255 }
+                },
+                {
+                    entity_id: 'climate.bedroom',
+                    state: 'heat',
+                    attributes: { temperature: 22 }
+                }
+            ];
+
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse(mockDevices)));
+            globalThis.fetch = mocks.mockFetch;
+
+            const listDevicesTool = addToolCalls.find(tool => tool.name === 'list_devices');
+            expect(listDevicesTool).toBeDefined();
+
+            if (!listDevicesTool) {
+                throw new Error('list_devices tool not found');
+            }
+
+            const result = await listDevicesTool.execute({}) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.devices).toEqual({
+                light: [{
+                    entity_id: 'light.living_room',
+                    state: 'on',
+                    attributes: { brightness: 255 }
+                }],
+                climate: [{
+                    entity_id: 'climate.bedroom',
+                    state: 'heat',
+                    attributes: { temperature: 22 }
+                }]
+            });
+        });
+
+        test('should handle fetch errors', async () => {
+            // Setup error response
+            mocks.mockFetch = mock(() => Promise.reject(new Error('Network error')));
+            globalThis.fetch = mocks.mockFetch;
+
+            const listDevicesTool = addToolCalls.find(tool => tool.name === 'list_devices');
+            expect(listDevicesTool).toBeDefined();
+
+            if (!listDevicesTool) {
+                throw new Error('list_devices tool not found');
+            }
+
+            const result = await listDevicesTool.execute({}) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Network error');
+        });
+    });
+
+    describe('control tool', () => {
+        test('should successfully control a light device', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse({})));
+            globalThis.fetch = mocks.mockFetch;
+
+            const controlTool = addToolCalls.find(tool => tool.name === 'control');
+            expect(controlTool).toBeDefined();
+
+            if (!controlTool) {
+                throw new Error('control tool not found');
+            }
+
+            const result = await controlTool.execute({
+                command: 'turn_on',
+                entity_id: 'light.living_room',
+                brightness: 255
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully executed turn_on for light.living_room');
+
+            // Verify the fetch call
+            const calls = mocks.mockFetch.mock.calls;
+            expect(calls.length).toBeGreaterThan(0);
+
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/services/light/turn_on`);
+            expect(options).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    entity_id: 'light.living_room',
+                    brightness: 255
+                })
+            });
+        });
+
+        test('should handle unsupported domains', async () => {
+            const controlTool = addToolCalls.find(tool => tool.name === 'control');
+            expect(controlTool).toBeDefined();
+
+            if (!controlTool) {
+                throw new Error('control tool not found');
+            }
+
+            const result = await controlTool.execute({
+                command: 'turn_on',
+                entity_id: 'unsupported.device'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Unsupported domain: unsupported');
+        });
+
+        test('should handle service call errors', async () => {
+            // Setup error response
+            mocks.mockFetch = mock(() => Promise.resolve(new Response(null, {
+                status: 503,
+                statusText: 'Service unavailable'
+            })));
+            globalThis.fetch = mocks.mockFetch;
+
+            const controlTool = addToolCalls.find(tool => tool.name === 'control');
+            expect(controlTool).toBeDefined();
+
+            if (!controlTool) {
+                throw new Error('control tool not found');
+            }
+
+            const result = await controlTool.execute({
+                command: 'turn_on',
+                entity_id: 'light.living_room'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toContain('Failed to execute turn_on for light.living_room');
+        });
+
+        test('should handle climate device controls', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse({})));
+            globalThis.fetch = mocks.mockFetch;
+
+            const controlTool = addToolCalls.find(tool => tool.name === 'control');
+            expect(controlTool).toBeDefined();
+
+            if (!controlTool) {
+                throw new Error('control tool not found');
+            }
+
+            const result = await controlTool.execute({
+                command: 'set_temperature',
+                entity_id: 'climate.bedroom',
+                temperature: 22,
+                target_temp_high: 24,
+                target_temp_low: 20
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully executed set_temperature for climate.bedroom');
+
+            // Verify the fetch call
+            const calls = mocks.mockFetch.mock.calls;
+            expect(calls.length).toBeGreaterThan(0);
+
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/services/climate/set_temperature`);
+            expect(options).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    entity_id: 'climate.bedroom',
+                    temperature: 22,
+                    target_temp_high: 24,
+                    target_temp_low: 20
+                })
+            });
+        });
+    });
+
+    describe('device_control tool', () => {
+        test('should successfully control a device', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse({ success: true })));
+            globalThis.fetch = mocks.mockFetch;
+
+            const deviceControlTool = addToolCalls.find(tool => tool.name === 'device_control');
+            expect(deviceControlTool).toBeDefined();
+
+            if (!deviceControlTool) {
+                throw new Error('device_control tool not found');
+            }
+
+            const result = await deviceControlTool.execute({
+                entity_id: 'light.living_room',
+                service: 'turn_on',
+                data: {
+                    brightness: 255,
+                    color_temp: 400
+                }
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully controlled device light.living_room');
+
+            // Verify the fetch call
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/services/light/turn_on`);
+            expect(options).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    entity_id: 'light.living_room',
+                    brightness: 255,
+                    color_temp: 400
+                })
+            });
+        });
+
+        test('should handle device control failure', async () => {
+            // Setup error response
+            mocks.mockFetch = mock(() => Promise.reject(new Error('Failed to control device')));
+            globalThis.fetch = mocks.mockFetch;
+
+            const deviceControlTool = addToolCalls.find(tool => tool.name === 'device_control');
+            expect(deviceControlTool).toBeDefined();
+
+            if (!deviceControlTool) {
+                throw new Error('device_control tool not found');
+            }
+
+            const result = await deviceControlTool.execute({
+                entity_id: 'light.living_room',
+                service: 'turn_on'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Failed to control device: Failed to control device');
+        });
+
+        test('should require entity_id', async () => {
+            const deviceControlTool = addToolCalls.find(tool => tool.name === 'device_control');
+            expect(deviceControlTool).toBeDefined();
+
+            if (!deviceControlTool) {
+                throw new Error('device_control tool not found');
+            }
+
+            const result = await deviceControlTool.execute({
+                service: 'turn_on'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Entity ID is required');
+        });
+
+        test('should require service', async () => {
+            const deviceControlTool = addToolCalls.find(tool => tool.name === 'device_control');
+            expect(deviceControlTool).toBeDefined();
+
+            if (!deviceControlTool) {
+                throw new Error('device_control tool not found');
+            }
+
+            const result = await deviceControlTool.execute({
+                entity_id: 'light.living_room'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Service is required');
+        });
+
+        test('should handle invalid service domain', async () => {
+            const deviceControlTool = addToolCalls.find(tool => tool.name === 'device_control');
+            expect(deviceControlTool).toBeDefined();
+
+            if (!deviceControlTool) {
+                throw new Error('device_control tool not found');
+            }
+
+            const result = await deviceControlTool.execute({
+                entity_id: 'light.living_room',
+                service: 'invalid_domain.turn_on'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Invalid service domain: invalid_domain');
+        });
+    });
+}); 

__tests__/tools/entity-state.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import {
+    type MockLiteMCPInstance,
+    type Tool,
+    type TestResponse,
+    TEST_CONFIG,
+    createMockLiteMCPInstance,
+    setupTestEnvironment,
+    cleanupMocks,
+    createMockResponse,
+    getMockCallArgs
+} from '../utils/test-utils';
+
+describe('Entity State Tools', () => {
+    let liteMcpInstance: MockLiteMCPInstance;
+    let addToolCalls: Tool[];
+    let mocks: ReturnType<typeof setupTestEnvironment>;
+
+    const mockEntityState = {
+        entity_id: 'light.living_room',
+        state: 'on',
+        attributes: {
+            brightness: 255,
+            color_temp: 400,
+            friendly_name: 'Living Room Light'
+        },
+        last_changed: '2024-03-20T12:00:00Z',
+        last_updated: '2024-03-20T12:00:00Z',
+        context: {
+            id: 'test_context_id',
+            parent_id: null,
+            user_id: null
+        }
+    };
+
+    beforeEach(async () => {
+        // Setup test environment
+        mocks = setupTestEnvironment();
+        liteMcpInstance = createMockLiteMCPInstance();
+
+        // Import the module which will execute the main function
+        await import('../../src/index.js');
+
+        // Get the mock instance and tool calls
+        addToolCalls = liteMcpInstance.addTool.mock.calls.map(call => call.args[0]);
+    });
+
+    afterEach(() => {
+        cleanupMocks({ liteMcpInstance, ...mocks });
+    });
+
+    describe('entity_state tool', () => {
+        test('should successfully get entity state', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse(mockEntityState)));
+            globalThis.fetch = mocks.mockFetch;
+
+            const entityStateTool = addToolCalls.find(tool => tool.name === 'entity_state');
+            expect(entityStateTool).toBeDefined();
+
+            if (!entityStateTool) {
+                throw new Error('entity_state tool not found');
+            }
+
+            const result = await entityStateTool.execute({
+                entity_id: 'light.living_room'
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.state).toBe('on');
+            expect(result.attributes).toEqual(mockEntityState.attributes);
+
+            // Verify the fetch call
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/states/light.living_room`);
+            expect(options).toEqual({
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+        });
+
+        test('should handle entity not found', async () => {
+            // Setup error response
+            mocks.mockFetch = mock(() => Promise.reject(new Error('Entity not found')));
+            globalThis.fetch = mocks.mockFetch;
+
+            const entityStateTool = addToolCalls.find(tool => tool.name === 'entity_state');
+            expect(entityStateTool).toBeDefined();
+
+            if (!entityStateTool) {
+                throw new Error('entity_state tool not found');
+            }
+
+            const result = await entityStateTool.execute({
+                entity_id: 'light.non_existent'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Failed to get entity state: Entity not found');
+        });
+
+        test('should require entity_id', async () => {
+            const entityStateTool = addToolCalls.find(tool => tool.name === 'entity_state');
+            expect(entityStateTool).toBeDefined();
+
+            if (!entityStateTool) {
+                throw new Error('entity_state tool not found');
+            }
+
+            const result = await entityStateTool.execute({}) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Entity ID is required');
+        });
+
+        test('should handle invalid entity_id format', async () => {
+            const entityStateTool = addToolCalls.find(tool => tool.name === 'entity_state');
+            expect(entityStateTool).toBeDefined();
+
+            if (!entityStateTool) {
+                throw new Error('entity_state tool not found');
+            }
+
+            const result = await entityStateTool.execute({
+                entity_id: 'invalid_entity_id'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Invalid entity ID format: invalid_entity_id');
+        });
+
+        test('should successfully get multiple entity states', async () => {
+            // Setup response
+            const mockStates = [
+                { ...mockEntityState },
+                {
+                    ...mockEntityState,
+                    entity_id: 'light.kitchen',
+                    attributes: { ...mockEntityState.attributes, friendly_name: 'Kitchen Light' }
+                }
+            ];
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse(mockStates)));
+            globalThis.fetch = mocks.mockFetch;
+
+            const entityStateTool = addToolCalls.find(tool => tool.name === 'entity_state');
+            expect(entityStateTool).toBeDefined();
+
+            if (!entityStateTool) {
+                throw new Error('entity_state tool not found');
+            }
+
+            const result = await entityStateTool.execute({
+                entity_id: ['light.living_room', 'light.kitchen']
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(Array.isArray(result.states)).toBe(true);
+            expect(result.states).toHaveLength(2);
+            expect(result.states[0].entity_id).toBe('light.living_room');
+            expect(result.states[1].entity_id).toBe('light.kitchen');
+
+            // Verify the fetch call
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/states`);
+            expect(options).toEqual({
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+        });
+    });
+}); 

__tests__/tools/scene-control.test.ts

@@ -0,0 +1 @@
+ 

__tests__/tools/script-control.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import {
+    type MockLiteMCPInstance,
+    type Tool,
+    type TestResponse,
+    TEST_CONFIG,
+    createMockLiteMCPInstance,
+    setupTestEnvironment,
+    cleanupMocks,
+    createMockResponse,
+    getMockCallArgs
+} from '../utils/test-utils';
+
+describe('Script Control Tools', () => {
+    let liteMcpInstance: MockLiteMCPInstance;
+    let addToolCalls: Tool[];
+    let mocks: ReturnType<typeof setupTestEnvironment>;
+
+    beforeEach(async () => {
+        // Setup test environment
+        mocks = setupTestEnvironment();
+        liteMcpInstance = createMockLiteMCPInstance();
+
+        // Import the module which will execute the main function
+        await import('../../src/index.js');
+
+        // Get the mock instance and tool calls
+        addToolCalls = liteMcpInstance.addTool.mock.calls.map(call => call.args[0]);
+    });
+
+    afterEach(() => {
+        cleanupMocks({ liteMcpInstance, ...mocks });
+    });
+
+    describe('script_control tool', () => {
+        test('should successfully execute a script', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse({ success: true })));
+            globalThis.fetch = mocks.mockFetch;
+
+            const scriptControlTool = addToolCalls.find(tool => tool.name === 'script_control');
+            expect(scriptControlTool).toBeDefined();
+
+            if (!scriptControlTool) {
+                throw new Error('script_control tool not found');
+            }
+
+            const result = await scriptControlTool.execute({
+                script_id: 'script.welcome_home',
+                action: 'start',
+                variables: {
+                    brightness: 100,
+                    color_temp: 300
+                }
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully executed script script.welcome_home');
+
+            // Verify the fetch call
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/services/script/turn_on`);
+            expect(options).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    entity_id: 'script.welcome_home',
+                    variables: {
+                        brightness: 100,
+                        color_temp: 300
+                    }
+                })
+            });
+        });
+
+        test('should successfully stop a script', async () => {
+            // Setup response
+            mocks.mockFetch = mock(() => Promise.resolve(createMockResponse({ success: true })));
+            globalThis.fetch = mocks.mockFetch;
+
+            const scriptControlTool = addToolCalls.find(tool => tool.name === 'script_control');
+            expect(scriptControlTool).toBeDefined();
+
+            if (!scriptControlTool) {
+                throw new Error('script_control tool not found');
+            }
+
+            const result = await scriptControlTool.execute({
+                script_id: 'script.welcome_home',
+                action: 'stop'
+            }) as TestResponse;
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Successfully stopped script script.welcome_home');
+
+            // Verify the fetch call
+            type FetchArgs = [url: string, init: RequestInit];
+            const args = getMockCallArgs<FetchArgs>(mocks.mockFetch);
+            expect(args).toBeDefined();
+
+            if (!args) {
+                throw new Error('No fetch calls recorded');
+            }
+
+            const [urlStr, options] = args;
+            expect(urlStr).toBe(`${TEST_CONFIG.HASS_HOST}/api/services/script/turn_off`);
+            expect(options).toEqual({
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${TEST_CONFIG.HASS_TOKEN}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    entity_id: 'script.welcome_home'
+                })
+            });
+        });
+
+        test('should handle script execution failure', async () => {
+            // Setup error response
+            mocks.mockFetch = mock(() => Promise.reject(new Error('Failed to execute script')));
+            globalThis.fetch = mocks.mockFetch;
+
+            const scriptControlTool = addToolCalls.find(tool => tool.name === 'script_control');
+            expect(scriptControlTool).toBeDefined();
+
+            if (!scriptControlTool) {
+                throw new Error('script_control tool not found');
+            }
+
+            const result = await scriptControlTool.execute({
+                script_id: 'script.welcome_home',
+                action: 'start'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Failed to execute script: Failed to execute script');
+        });
+
+        test('should require script_id', async () => {
+            const scriptControlTool = addToolCalls.find(tool => tool.name === 'script_control');
+            expect(scriptControlTool).toBeDefined();
+
+            if (!scriptControlTool) {
+                throw new Error('script_control tool not found');
+            }
+
+            const result = await scriptControlTool.execute({
+                action: 'start'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Script ID is required');
+        });
+
+        test('should require action', async () => {
+            const scriptControlTool = addToolCalls.find(tool => tool.name === 'script_control');
+            expect(scriptControlTool).toBeDefined();
+
+            if (!scriptControlTool) {
+                throw new Error('script_control tool not found');
+            }
+
+            const result = await scriptControlTool.execute({
+                script_id: 'script.welcome_home'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Action is required');
+        });
+
+        test('should handle invalid script_id format', async () => {
+            const scriptControlTool = addToolCalls.find(tool => tool.name === 'script_control');
+            expect(scriptControlTool).toBeDefined();
+
+            if (!scriptControlTool) {
+                throw new Error('script_control tool not found');
+            }
+
+            const result = await scriptControlTool.execute({
+                script_id: 'invalid_script_id',
+                action: 'start'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Invalid script ID format: invalid_script_id');
+        });
+
+        test('should handle invalid action', async () => {
+            const scriptControlTool = addToolCalls.find(tool => tool.name === 'script_control');
+            expect(scriptControlTool).toBeDefined();
+
+            if (!scriptControlTool) {
+                throw new Error('script_control tool not found');
+            }
+
+            const result = await scriptControlTool.execute({
+                script_id: 'script.welcome_home',
+                action: 'invalid_action'
+            }) as TestResponse;
+
+            expect(result.success).toBe(false);
+            expect(result.message).toBe('Invalid action: invalid_action');
+        });
+    });
+}); 

__tests__/types/litemcp.d.ts

@@ -0,0 +1,19 @@
+declare module 'litemcp' {
+    export interface Tool {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        execute: (params: Record<string, unknown>) => Promise<unknown>;
+    }
+
+    export interface LiteMCPOptions {
+        name: string;
+        version: string;
+    }
+
+    export class LiteMCP {
+        constructor(options: LiteMCPOptions);
+        addTool(tool: Tool): void;
+        start(): Promise<void>;
+    }
+} 

__tests__/utils/test-utils.ts

@@ -0,0 +1,148 @@
+import { mock } from "bun:test";
+import type { Mock } from "bun:test";
+import type { WebSocket } from 'ws';
+
+// Common Types
+export interface Tool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (params: Record<string, unknown>) => Promise<unknown>;
+}
+
+export interface MockLiteMCPInstance {
+    addTool: Mock<(tool: Tool) => void>;
+    start: Mock<() => Promise<void>>;
+}
+
+export interface MockServices {
+    light: {
+        turn_on: Mock<() => Promise<{ success: boolean }>>;
+        turn_off: Mock<() => Promise<{ success: boolean }>>;
+    };
+    climate: {
+        set_temperature: Mock<() => Promise<{ success: boolean }>>;
+    };
+}
+
+export interface MockHassInstance {
+    services: MockServices;
+}
+
+export type TestResponse = {
+    success: boolean;
+    message?: string;
+    automation_id?: string;
+    new_automation_id?: string;
+    state?: string;
+    attributes?: Record<string, any>;
+    states?: Array<{
+        entity_id: string;
+        state: string;
+        attributes: Record<string, any>;
+        last_changed: string;
+        last_updated: string;
+        context: {
+            id: string;
+            parent_id: string | null;
+            user_id: string | null;
+        };
+    }>;
+};
+
+// Test Configuration
+export const TEST_CONFIG = {
+    HASS_HOST: process.env.TEST_HASS_HOST || 'http://localhost:8123',
+    HASS_TOKEN: process.env.TEST_HASS_TOKEN || 'test_token',
+    HASS_SOCKET_URL: process.env.TEST_HASS_SOCKET_URL || 'ws://localhost:8123/api/websocket'
+} as const;
+
+// Mock WebSocket Implementation
+export class MockWebSocket {
+    public static readonly CONNECTING = 0;
+    public static readonly OPEN = 1;
+    public static readonly CLOSING = 2;
+    public static readonly CLOSED = 3;
+
+    public readyState: 0 | 1 | 2 | 3 = MockWebSocket.OPEN;
+    public bufferedAmount = 0;
+    public extensions = '';
+    public protocol = '';
+    public url = '';
+    public binaryType: 'arraybuffer' | 'nodebuffer' | 'fragments' = 'arraybuffer';
+
+    public onopen: ((event: any) => void) | null = null;
+    public onerror: ((event: any) => void) | null = null;
+    public onclose: ((event: any) => void) | null = null;
+    public onmessage: ((event: any) => void) | null = null;
+
+    public addEventListener = mock(() => undefined);
+    public removeEventListener = mock(() => undefined);
+    public send = mock(() => undefined);
+    public close = mock(() => undefined);
+    public ping = mock(() => undefined);
+    public pong = mock(() => undefined);
+    public terminate = mock(() => undefined);
+
+    constructor(url: string | URL, protocols?: string | string[]) {
+        this.url = url.toString();
+        if (protocols) {
+            this.protocol = Array.isArray(protocols) ? protocols[0] : protocols;
+        }
+    }
+}
+
+// Mock Service Instances
+export const createMockServices = (): MockServices => ({
+    light: {
+        turn_on: mock(() => Promise.resolve({ success: true })),
+        turn_off: mock(() => Promise.resolve({ success: true }))
+    },
+    climate: {
+        set_temperature: mock(() => Promise.resolve({ success: true }))
+    }
+});
+
+export const createMockLiteMCPInstance = (): MockLiteMCPInstance => ({
+    addTool: mock((tool: Tool) => undefined),
+    start: mock(() => Promise.resolve())
+});
+
+// Helper Functions
+export const createMockResponse = <T>(data: T, status = 200): Response => {
+    return new Response(JSON.stringify(data), { status });
+};
+
+export const getMockCallArgs = <T extends unknown[]>(
+    mock: Mock<(...args: any[]) => any>,
+    callIndex = 0
+): T | undefined => {
+    const call = mock.mock.calls[callIndex];
+    return call?.args as T | undefined;
+};
+
+export const setupTestEnvironment = () => {
+    // Setup test environment variables
+    Object.entries(TEST_CONFIG).forEach(([key, value]) => {
+        process.env[key] = value;
+    });
+
+    // Create fetch mock
+    const mockFetch = mock(() => Promise.resolve(createMockResponse({ state: 'connected' })));
+
+    // Override globals
+    globalThis.fetch = mockFetch;
+    globalThis.WebSocket = MockWebSocket as any;
+
+    return { mockFetch };
+};
+
+export const cleanupMocks = (mocks: {
+    liteMcpInstance: MockLiteMCPInstance;
+    mockFetch: Mock<() => Promise<Response>>;
+}) => {
+    mocks.liteMcpInstance.addTool.mock.calls = [];
+    mocks.liteMcpInstance.start.mock.calls = [];
+    mocks.mockFetch = mock(() => Promise.resolve(new Response()));
+    globalThis.fetch = mocks.mockFetch;
+}; 

bun.lock

@@ -0,0 +1,604 @@
+{
+  "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=="],
+  }
+}

bunfig.toml

@@ -0,0 +1,50 @@
+[test]
+preload = ["./src/__tests__/setup.ts"]
+coverage = true
+coverageThreshold = {
+  statements = 80,
+  branches = 70,
+  functions = 80,
+  lines = 80
+}
+timeout = 30000
+testMatch = ["**/__tests__/**/*.test.ts"]
+testPathIgnorePatterns = ["/node_modules/", "/dist/"]
+collectCoverageFrom = [
+  "src/**/*.{ts,tsx}",
+  "!src/**/*.d.ts",
+  "!src/**/*.test.ts",
+  "!src/types/**/*",
+  "!src/mocks/**/*"
+]
+
+[build]
+target = "node"
+outdir = "./dist"
+minify = true
+sourcemap = "external"
+
+[install]
+production = false
+frozen = true
+peer = false
+
+[install.cache]
+dir = ".bun"
+disable = false
+
+[debug]
+port = 9229
+
+[env]
+# Environment-specific configurations
+development.LOG_LEVEL = "debug"
+production.LOG_LEVEL = "warn"
+
+[hot]
+restart = true
+reload = true
+
+[performance]
+gc = true
+optimize = true 

docker-build.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+
+# Enable error handling
+set -euo pipefail
+
+# Function to clean up on script exit
+cleanup() {
+    echo "Cleaning up..."
+    docker builder prune -f --filter until=24h
+    docker image prune -f
+}
+trap cleanup EXIT
+
+# Clean up Docker system
+echo "Cleaning up Docker system..."
+docker system prune -f --volumes
+
+# Set build arguments for better performance
+export DOCKER_BUILDKIT=1
+export COMPOSE_DOCKER_CLI_BUILD=1
+export BUILDKIT_PROGRESS=plain
+
+# Calculate available memory and CPU
+TOTAL_MEM=$(free -m | awk '/^Mem:/{print $2}')
+BUILD_MEM=$(( TOTAL_MEM / 2 ))  # Use half of available memory
+CPU_COUNT=$(nproc)
+CPU_QUOTA=$(( CPU_COUNT * 50000 ))  # Allow 50% CPU usage per core
+
+echo "Building with ${BUILD_MEM}MB memory limit and CPU quota ${CPU_QUOTA}"
+
+# Remove any existing lockfile
+rm -f bun.lockb
+
+# Build with resource limits, optimizations, and timeout
+echo "Building Docker image..."
+DOCKER_BUILDKIT=1 docker build \
+    --memory="${BUILD_MEM}m" \
+    --memory-swap="${BUILD_MEM}m" \
+    --cpu-quota="${CPU_QUOTA}" \
+    --build-arg BUILDKIT_INLINE_CACHE=1 \
+    --build-arg DOCKER_BUILDKIT=1 \
+    --build-arg NODE_ENV=production \
+    --progress=plain \
+    --no-cache \
+    --compress \
+    -t homeassistant-mcp:latest \
+    -t homeassistant-mcp:$(date +%Y%m%d) \
+    .
+
+# Check if build was successful
+BUILD_EXIT_CODE=$?
+if [ $BUILD_EXIT_CODE -eq 124 ]; then
+    echo "Build timed out after 15 minutes!"
+    exit 1
+elif [ $BUILD_EXIT_CODE -ne 0 ]; then
+    echo "Build failed with exit code ${BUILD_EXIT_CODE}!"
+    exit 1
+else
+    echo "Build completed successfully!"
+    
+    # Show image size and layers
+    docker image ls homeassistant-mcp:latest --format "Image size: {{.Size}}"
+    echo "Layer count: $(docker history homeassistant-mcp:latest | wc -l)"
+fi 

docker/speech/Dockerfile

@@ -0,0 +1,67 @@
+# 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"] 

docker/speech/setup-audio.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+# Wait for PulseAudio socket to be available
+while [ ! -e /run/user/1000/pulse/native ]; do
+    echo "Waiting for PulseAudio socket..."
+    sleep 1
+done
+
+# Test PulseAudio connection
+pactl info || {
+    echo "Failed to connect to PulseAudio server"
+    exit 1
+}
+
+# List audio devices
+pactl list sources || {
+    echo "Failed to list audio devices"
+    exit 1
+}
+
+# Start the wake word detector
+python /app/wake_word_detector.py
+
+# Mute the monitor to prevent feedback
+pactl set-source-mute alsa_output.pci-0000_00_1b.0.analog-stereo.monitor 1
+
+# Set microphone sensitivity to 65%
+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 

docker/speech/wake_word_detector.py

@@ -0,0 +1,415 @@
+import os
+import json
+import queue
+import threading
+import numpy as np
+import sounddevice as sd
+from openwakeword import Model
+from datetime import datetime
+import wave
+from faster_whisper import WhisperModel
+import requests
+import logging
+import time
+
+# Set up logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Configuration
+SAMPLE_RATE = 16000
+CHANNELS = 1
+CHUNK_SIZE = 1024
+BUFFER_DURATION = 10  # seconds to keep in buffer
+DETECTION_THRESHOLD = 0.5
+CONTINUOUS_TRANSCRIPTION_INTERVAL = 3  # seconds between transcriptions
+MAX_MODEL_LOAD_RETRIES = 3
+MODEL_LOAD_RETRY_DELAY = 5  # seconds
+MODEL_DOWNLOAD_TIMEOUT = 600  # 10 minutes timeout for model download
+
+# Audio processing parameters
+NOISE_THRESHOLD = 0.08  # Increased threshold for better noise filtering
+MIN_SPEECH_DURATION = 2.0  # Longer minimum duration to avoid fragments
+SILENCE_DURATION = 1.0  # Longer silence duration
+MAX_REPETITIONS = 1  # More aggressive repetition filtering
+ECHO_THRESHOLD = 0.75  # More sensitive echo detection
+MIN_SEGMENT_DURATION = 1.0  # Longer minimum segment duration
+FEEDBACK_WINDOW = 5  # Window size for feedback detection in seconds
+
+# Feature flags from environment
+WAKE_WORD_ENABLED = os.environ.get('ENABLE_WAKE_WORD', 'false').lower() == 'true'
+SPEECH_ENABLED = os.environ.get('ENABLE_SPEECH_FEATURES', 'true').lower() == 'true'
+
+# Wake word models to use (only if wake word is enabled)
+WAKE_WORDS = ["alexa"]  # Using 'alexa' as temporary replacement for 'gaja'
+WAKE_WORD_ALIAS = "gaja"  # What we print when wake word is detected
+
+# Home Assistant Configuration
+HASS_HOST = os.environ.get('HASS_HOST', 'http://homeassistant.local:8123')
+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')
+    
+    start_time = time.time()
+    for attempt in range(MAX_MODEL_LOAD_RETRIES):
+        try:
+            if time.time() - start_time > MODEL_DOWNLOAD_TIMEOUT:
+                logger.error("Model download timeout exceeded")
+                raise TimeoutError("Model download took too long")
+                
+            logger.info(f"Loading ASR model (attempt {attempt + 1}/{MAX_MODEL_LOAD_RETRIES})")
+            model = WhisperModel(
+                model_size_or_path=model_name,
+                device="cpu",
+                compute_type="int8",
+                download_root=model_path,
+                num_workers=1  # Reduce concurrent downloads
+            )
+            logger.info("ASR model loaded successfully")
+            return model
+        except Exception as e:
+            logger.error(f"Failed to load ASR model (attempt {attempt + 1}): {e}")
+            if attempt < MAX_MODEL_LOAD_RETRIES - 1:
+                logger.info(f"Retrying in {MODEL_LOAD_RETRY_DELAY} seconds...")
+                time.sleep(MODEL_LOAD_RETRY_DELAY)
+            else:
+                logger.error("Failed to load ASR model after all retries")
+                raise
+
+# Initialize the ASR model with retries
+try:
+    asr_model = initialize_asr_model()
+except Exception as e:
+    logger.error(f"Critical error initializing ASR model: {e}")
+    raise
+
+def send_command_to_hass(domain, service, entity_id):
+    """Send command to Home Assistant"""
+    if not HASS_TOKEN:
+        logger.error("Error: HASS_TOKEN not set")
+        return False
+
+    headers = {
+        "Authorization": f"Bearer {HASS_TOKEN}",
+        "Content-Type": "application/json",
+    }
+
+    url = f"{HASS_HOST}/api/services/{domain}/{service}"
+    data = {"entity_id": entity_id}
+
+    try:
+        response = requests.post(url, headers=headers, json=data)
+        response.raise_for_status()
+        logger.info(f"Command sent: {domain}.{service} for {entity_id}")
+        return True
+    except Exception as e:
+        logger.error(f"Error sending command to Home Assistant: {e}")
+        return False
+
+def is_speech(audio_data, threshold=NOISE_THRESHOLD):
+    """Detect if audio segment contains speech based on amplitude and frequency content"""
+    # Calculate RMS amplitude
+    rms = np.sqrt(np.mean(np.square(audio_data)))
+    
+    # Calculate signal energy in speech frequency range (100-4000 Hz)
+    fft = np.fft.fft(audio_data)
+    freqs = np.fft.fftfreq(len(audio_data), 1/SAMPLE_RATE)
+    speech_mask = (np.abs(freqs) >= 100) & (np.abs(freqs) <= 4000)
+    speech_energy = np.sum(np.abs(fft[speech_mask])) / len(audio_data)
+    
+    # Enhanced echo detection
+    # 1. Check for periodic patterns in the signal
+    autocorr = np.correlate(audio_data, audio_data, mode='full')
+    autocorr = autocorr[len(autocorr)//2:]  # Use only positive lags
+    peaks = np.where(autocorr > ECHO_THRESHOLD * np.max(autocorr))[0]
+    peak_spacing = np.diff(peaks)
+    has_periodic_echo = len(peak_spacing) > 2 and np.std(peak_spacing) < 0.1 * np.mean(peak_spacing)
+    
+    # 2. Check for sudden amplitude changes
+    amplitude_envelope = np.abs(audio_data)
+    amplitude_changes = np.diff(amplitude_envelope)
+    has_feedback_spikes = np.any(np.abs(amplitude_changes) > threshold * 2)
+    
+    # 3. Check frequency distribution
+    freq_magnitudes = np.abs(fft)[:len(fft)//2]
+    peak_freqs = freqs[:len(fft)//2][np.argsort(freq_magnitudes)[-3:]]
+    has_feedback_freqs = np.any((peak_freqs > 2000) & (peak_freqs < 4000))
+    
+    # Combine all criteria
+    is_valid_speech = (
+        rms > threshold and
+        speech_energy > threshold and
+        not has_periodic_echo and
+        not has_feedback_spikes and
+        not has_feedback_freqs
+    )
+    
+    return is_valid_speech
+
+def process_command(text):
+    """Process the transcribed command and execute appropriate action"""
+    text = text.lower().strip()
+    
+    # Skip if text is too short or contains numbers (likely noise)
+    if len(text) < 5 or any(char.isdigit() for char in text):
+        logger.debug("Text too short or contains numbers, skipping")
+        return
+    
+    # Enhanced noise pattern detection
+    noise_patterns = ["lei", "los", "und", "aber", "nicht mehr", "das das", "und und"]
+    for pattern in noise_patterns:
+        if text.count(pattern) > 1:  # More aggressive pattern filtering
+            logger.debug(f"Detected noise pattern '{pattern}', skipping")
+            return
+    
+    # More aggressive repetition detection
+    words = text.split()
+    if len(words) >= 2:
+        # Check for immediate word repetitions
+        for i in range(len(words)-1):
+            if words[i] == words[i+1]:
+                logger.debug(f"Detected immediate word repetition: '{words[i]}', skipping")
+                return
+        
+        # Check for phrase repetitions
+        phrases = [' '.join(words[i:i+2]) for i in range(len(words)-1)]
+        phrase_counts = {}
+        for phrase in phrases:
+            phrase_counts[phrase] = phrase_counts.get(phrase, 0) + 1
+            if phrase_counts[phrase] > MAX_REPETITIONS:
+                logger.debug(f"Skipping due to excessive repetition: '{phrase}'")
+                return
+    
+    # German command mappings
+    commands = {
+        "ausschalten": "turn_off",
+        "einschalten": "turn_on",
+        "an": "turn_on",
+        "aus": "turn_off"
+    }
+    
+    rooms = {
+        "wohnzimmer": "living_room",
+        "küche": "kitchen",
+        "schlafzimmer": "bedroom",
+        "bad": "bathroom"
+    }
+    
+    # Detect room
+    detected_room = None
+    for german_room, english_room in rooms.items():
+        if german_room in text:
+            detected_room = english_room
+            break
+    
+    # Detect command
+    detected_command = None
+    for german_cmd, english_cmd in commands.items():
+        if german_cmd in text:
+            detected_command = english_cmd
+            break
+    
+    if detected_room and detected_command:
+        # Construct entity ID (assuming light)
+        entity_id = f"light.{detected_room}"
+        
+        # Send command to Home Assistant
+        if send_command_to_hass("light", detected_command, entity_id):
+            logger.info(f"Executed: {detected_command} for {entity_id}")
+        else:
+            logger.error("Failed to execute command")
+    else:
+        logger.debug(f"No command found in text: '{text}'")
+
+class AudioProcessor:
+    def __init__(self):
+        logger.info("Initializing AudioProcessor...")
+        self.audio_buffer = queue.Queue()
+        self.recording = False
+        self.buffer = np.zeros(SAMPLE_RATE * BUFFER_DURATION)
+        self.buffer_lock = threading.Lock()
+        self.last_transcription_time = 0
+        self.stream = None
+        self.speech_detected = False
+        self.silence_frames = 0
+        self.speech_frames = 0
+
+        # Initialize wake word detection only if enabled
+        if WAKE_WORD_ENABLED:
+            try:
+                logger.info("Initializing wake word model...")
+                self.wake_word_model = Model(vad_threshold=0.5)
+                self.last_prediction = None
+                logger.info("Wake word model initialized successfully")
+            except Exception as e:
+                logger.error(f"Failed to initialize wake word model: {e}")
+                raise
+        else:
+            self.wake_word_model = None
+            self.last_prediction = None
+            logger.info("Wake word detection disabled")
+
+    def should_transcribe(self):
+        """Determine if we should transcribe based on mode and timing"""
+        current_time = datetime.now().timestamp()
+        if not WAKE_WORD_ENABLED:
+            # Check if enough time has passed since last transcription
+            time_since_last = current_time - self.last_transcription_time
+            if time_since_last >= CONTINUOUS_TRANSCRIPTION_INTERVAL:
+                # Only transcribe if we detect speech
+                frames_per_chunk = CHUNK_SIZE
+                min_speech_frames = int(MIN_SPEECH_DURATION * SAMPLE_RATE / frames_per_chunk)
+                
+                if self.speech_frames >= min_speech_frames:
+                    self.last_transcription_time = current_time
+                    self.speech_frames = 0  # Reset counter
+                    return True
+        return False
+
+    def audio_callback(self, indata, frames, time, status):
+        """Callback for audio input"""
+        if status:
+            logger.warning(f"Audio callback status: {status}")
+        
+        # Convert to mono if necessary
+        if CHANNELS > 1:
+            audio_data = np.mean(indata, axis=1)
+        else:
+            audio_data = indata.flatten()
+
+        # Check for speech
+        if is_speech(audio_data):
+            self.speech_frames += 1
+            self.silence_frames = 0
+        else:
+            self.silence_frames += 1
+            frames_per_chunk = CHUNK_SIZE
+            silence_frames_threshold = int(SILENCE_DURATION * SAMPLE_RATE / frames_per_chunk)
+            
+            if self.silence_frames >= silence_frames_threshold:
+                self.speech_frames = 0
+
+        # Update circular buffer
+        with self.buffer_lock:
+            self.buffer = np.roll(self.buffer, -len(audio_data))
+            self.buffer[-len(audio_data):] = audio_data
+
+        if WAKE_WORD_ENABLED:
+            # Process for wake word detection
+            self.last_prediction = self.wake_word_model.predict(audio_data)
+            
+            # Check if wake word detected
+            for wake_word in WAKE_WORDS:
+                confidence = self.last_prediction[wake_word]
+                if confidence > DETECTION_THRESHOLD:
+                    logger.info(
+                        f"Wake word: {WAKE_WORD_ALIAS} (confidence: {confidence:.2f})"
+                    )
+                    self.process_audio()
+                    break
+        else:
+            # Continuous transcription mode
+            if self.should_transcribe():
+                self.process_audio()
+
+    def process_audio(self):
+        """Process the current audio buffer (save and transcribe)"""
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        filename = f"/audio/audio_segment_{timestamp}.wav"
+        
+        # Save the audio buffer to a WAV file
+        with wave.open(filename, 'wb') as wf:
+            wf.setnchannels(CHANNELS)
+            wf.setsampwidth(2)  # 16-bit audio
+            wf.setframerate(SAMPLE_RATE)
+            
+            # Convert float32 to int16
+            audio_data = (self.buffer * 32767).astype(np.int16)
+            wf.writeframes(audio_data.tobytes())
+        
+        logger.info(f"Saved audio segment to {filename}")
+
+        # Transcribe the audio with German language preference
+        try:
+            segments, info = asr_model.transcribe(
+                filename,
+                language="de",  # Set German as preferred language
+                beam_size=5,
+                temperature=0
+            )
+            
+            # Get the full transcribed text
+            transcribed_text = " ".join(segment.text for segment in segments)
+            logger.info(f"Transcribed text: {transcribed_text}")
+            
+            # Process the command
+            process_command(transcribed_text)
+                
+        except Exception as e:
+            logger.error(f"Error during transcription or processing: {e}")
+
+    def start(self):
+        """Start audio processing"""
+        try:
+            logger.info("Starting audio processor...")
+            
+            # Log configuration
+            logger.debug(f"Sample Rate: {SAMPLE_RATE}")
+            logger.debug(f"Channels: {CHANNELS}")
+            logger.debug(f"Chunk Size: {CHUNK_SIZE}")
+            logger.debug(f"Buffer Duration: {BUFFER_DURATION}")
+            logger.debug(f"Wake Word Enabled: {WAKE_WORD_ENABLED}")
+            logger.debug(f"Speech Enabled: {SPEECH_ENABLED}")
+            logger.debug(f"ASR Model: {os.environ.get('ASR_MODEL')}")
+            
+            if WAKE_WORD_ENABLED:
+                logger.info("Initializing wake word detection...")
+                logger.info(f"Loaded wake words: {', '.join(WAKE_WORDS)}")
+            else:
+                logger.info("Starting continuous transcription mode...")
+                interval = CONTINUOUS_TRANSCRIPTION_INTERVAL
+                logger.info(f"Will transcribe every {interval} seconds")
+            
+            try:
+                logger.debug("Setting up audio input stream...")
+                with sd.InputStream(
+                    channels=CHANNELS,
+                    samplerate=SAMPLE_RATE,
+                    blocksize=CHUNK_SIZE,
+                    callback=self.audio_callback
+                ):
+                    logger.info("Audio input stream started successfully")
+                    logger.info("Listening for audio input...")
+                    logger.info("Press Ctrl+C to stop")
+                    
+                    while True:
+                        sd.sleep(1000)  # Sleep for 1 second
+                        
+            except sd.PortAudioError as e:
+                logger.error(f"Error setting up audio stream: {e}")
+                logger.error("Check if microphone is connected and accessible")
+                raise
+            except Exception as e:
+                logger.error(f"Unexpected error in audio stream: {e}")
+                raise
+                    
+        except KeyboardInterrupt:
+            logger.info("\nStopping audio processing...")
+        except Exception as e:
+            logger.error("Critical error in audio processing", exc_info=True)
+            raise
+
+if __name__ == "__main__":
+    try:
+        logger.info("Initializing AudioProcessor...")
+        processor = AudioProcessor()
+        processor.start()
+    except Exception as e:
+        logger.error("Failed to start AudioProcessor", exc_info=True)
+        raise 

docs/API.md

@@ -1,419 +0,0 @@
-# API Reference
-
-## 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.
-
-## Device Control
-
-### Common Entity Controls
-```json
-{
-  "tool": "control",
-  "command": "turn_on",  // or "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",  // or "stop", "restart"
-  "slug": "core_configurator"
-}
-```
-
-## Package Management
-
-### List HACS Packages
-```json
-{
-  "tool": "package",
-  "action": "list",
-  "category": "integration"  // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
-}
-```
-
-### Install Package
-```json
-{
-  "tool": "package",
-  "action": "install",
-  "category": "integration",
-  "repository": "hacs/integration",
-  "version": "1.32.0"
-}
-```
-
-## Automation Management
-
-### Create Automation
-```json
-{
-  "tool": "automation_config",
-  "action": "create",
-  "config": {
-    "alias": "Motion Light",
-    "description": "Turn on light when motion detected",
-    "mode": "single",
-    "trigger": [
-      {
-        "platform": "state",
-        "entity_id": "binary_sensor.motion",
-        "to": "on"
-      }
-    ],
-    "action": [
-      {
-        "service": "light.turn_on",
-        "target": {
-          "entity_id": "light.living_room"
-        }
-      }
-    ]
-  }
-}
-```
-
-### Duplicate Automation
-```json
-{
-  "tool": "automation_config",
-  "action": "duplicate",
-  "automation_id": "automation.motion_light"
-}
-```
-
-## 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
-  }
-}
-```
-
-### Context Updates
-```http
-POST /api/context
-```
-
-Updates the current context with new information.
-
-**Example Request:**
-```json
-POST /api/context
-{
-  "user": "john",
-  "location": "kitchen",
-  "time": "morning",
-  "activity": "cooking"
-}
-```
-
-## Action Endpoints
-
-### Execute Action
-```http
-POST /api/action
-```
-
-Executes a specified action with given parameters.
-
-**Example Request:**
-```json
-POST /api/action
-{
-  "action": "turn_on_lights",
-  "parameters": {
-    "room": "living_room",
-    "brightness": 80
-  }
-}
-```
-
-### Batch Actions
-```http
-POST /api/actions/batch
-```
-
-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.
-
-```javascript
-// Client-side connection example
-const ws = new WebSocket('ws://localhost:3000/ws');
-
-ws.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  console.log('Received update:', data);
-};
-```
-
-### 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:
-
-- 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"]
-    }
-  }
-}
-```
-
-## Rate Limiting
-
-The API implements rate limiting to prevent abuse:
-
-- 100 requests per minute per IP for regular endpoints
-- 1000 requests per minute per IP for WebSocket connections
-
-When rate limit is exceeded, the server returns:
-
-```json
-{
-  "error": {
-    "code": "RATE_LIMIT_EXCEEDED",
-    "message": "Too many requests",
-    "reset_time": "2024-03-20T10:31:00Z"
-  }
-}
-```
-
-## Example Usage
-
-### Using curl
-```bash
-# Get current state
-curl -X GET \
-  http://localhost:3000/api/state \
-  -H 'Authorization: ApiKey your_api_key_here'
-
-# Execute action
-curl -X POST \
-  http://localhost:3000/api/action \
-  -H 'Authorization: ApiKey your_api_key_here' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "action": "turn_on_lights",
-    "parameters": {
-      "room": "living_room",
-      "brightness": 80
-    }
-  }'
-```
-
-### Using JavaScript
-```javascript
-// Execute action
-async function executeAction() {
-  const response = await fetch('http://localhost:3000/api/action', {
-    method: 'POST',
-    headers: {
-      'Authorization': 'ApiKey your_api_key_here',
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify({
-      action: 'turn_on_lights',
-      parameters: {
-        room: 'living_room',
-        brightness: 80
-      }
-    })
-  });
-  
-  const data = await response.json();
-  console.log('Action result:', data);
-}
-``` 

docs/Gemfile

@@ -0,0 +1,23 @@
+source "https://rubygems.org"
+
+gem "github-pages", group: :jekyll_plugins
+gem "jekyll-theme-minimal"
+gem "jekyll-relative-links"
+gem "jekyll-seo-tag"
+gem "jekyll-remote-theme"
+gem "jekyll-github-metadata"
+gem "faraday-retry"
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1"
+  gem "tzinfo-data"
+end
+
+# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
+# do not have a Java counterpart.
+gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
+
+# Add webrick for Ruby 3.0+
+gem "webrick", "~> 1.7" 

docs/README.md

@@ -1,60 +0,0 @@
-# Home Assistant MCP Documentation
-
-Welcome to the Home Assistant MCP (Master Control Program) documentation. This documentation provides comprehensive information about setting up, configuring, and using the Home Assistant MCP.
-
-## Table of Contents
-
-1. [Getting Started](./getting-started.md)
-   - Installation
-   - Configuration
-   - First Steps
-
-2. [API Reference](./API.md)
-   - REST API Endpoints
-   - Authentication
-   - Error Handling
-
-3. [SSE (Server-Sent Events)](./SSE_API.md)
-   - Event Subscriptions
-   - Real-time Updates
-   - Connection Management
-
-4. [Tools](./tools/README.md)
-   - Device Control
-   - Automation Management
-   - Add-on Management
-   - Package Management
-
-5. [Configuration](./configuration/README.md)
-   - Environment Variables
-   - Security Settings
-   - Performance Tuning
-
-6. [Development](./development/README.md)
-   - Project Structure
-   - Contributing Guidelines
-   - Testing
-
-7. [Troubleshooting](./troubleshooting.md)
-   - Common Issues
-   - Debugging
-   - FAQ
-
-## Quick Links
-
-- [GitHub Repository](https://github.com/yourusername/homeassistant-mcp)
-- [Issue Tracker](https://github.com/yourusername/homeassistant-mcp/issues)
-- [Change Log](./CHANGELOG.md)
-- [Security Policy](./SECURITY.md)
-
-## Support
-
-If you need help or have questions:
-
-1. Check the [Troubleshooting Guide](./troubleshooting.md)
-2. Search existing [Issues](https://github.com/yourusername/homeassistant-mcp/issues)
-3. Create a new issue if your problem isn't already reported
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details. 

docs/SSE_API.md

@@ -1,364 +0,0 @@
-# Home Assistant MCP Server-Sent Events (SSE) API Documentation
-
-## Overview
-
-The SSE API provides real-time updates from Home Assistant through a persistent connection. This allows clients to receive instant notifications about state changes, events, and other activities without polling.
-
-## Quick Reference
-
-### Available Endpoints
-
-| Endpoint | Method | Description | Authentication |
-|----------|---------|-------------|----------------|
-| `/subscribe_events` | POST | Subscribe to real-time events and state changes | Required |
-| `/get_sse_stats` | POST | Get statistics about current SSE connections | Required |
-
-### Event Types Available
-
-| Event Type | Description | Example Subscription |
-|------------|-------------|---------------------|
-| `state_changed` | Entity state changes | `events=state_changed` |
-| `service_called` | Service call events | `events=service_called` |
-| `automation_triggered` | Automation trigger events | `events=automation_triggered` |
-| `script_executed` | Script execution events | `events=script_executed` |
-| `ping` | Connection keepalive (system) | Automatic |
-| `error` | Error notifications (system) | Automatic |
-
-### Subscription Options
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `entity_id` | Subscribe to specific entity | `entity_id=light.living_room` |
-| `domain` | Subscribe to entire domain | `domain=light` |
-| `events` | Subscribe to event types | `events=state_changed,automation_triggered` |
-
-## Authentication
-
-All SSE connections require authentication using your Home Assistant token.
-
-```javascript
-const token = 'YOUR_HASS_TOKEN';
-```
-
-## Endpoints
-
-### Subscribe to Events
-
-`POST /subscribe_events`
-
-Subscribe to Home Assistant events and state changes.
-
-#### Parameters
-
-| Parameter  | Type     | Required | Description |
-|------------|----------|----------|-------------|
-| token      | string   | Yes      | Your Home Assistant authentication token |
-| events     | string[] | No       | Array of event types to subscribe to |
-| entity_id  | string   | No       | Specific entity ID to monitor |
-| domain     | string   | No       | Domain to monitor (e.g., "light", "switch") |
-
-#### Example Request
-
-```javascript
-const eventSource = new EventSource(`http://localhost:3000/subscribe_events?token=${token}&entity_id=light.living_room&domain=switch&events=state_changed,automation_triggered`);
-
-eventSource.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  console.log('Received:', data);
-};
-
-eventSource.onerror = (error) => {
-  console.error('SSE Error:', error);
-  eventSource.close();
-};
-```
-
-### Get SSE Statistics
-
-`POST /get_sse_stats`
-
-Get current statistics about SSE connections and subscriptions.
-
-#### Parameters
-
-| Parameter | Type   | Required | Description |
-|-----------|--------|----------|-------------|
-| token     | string | Yes      | Your Home Assistant authentication token |
-
-#### Example Request
-
-```bash
-curl -X POST http://localhost:3000/get_sse_stats \
-  -H "Content-Type: application/json" \
-  -d '{"token": "YOUR_HASS_TOKEN"}'
-```
-
-## Event Types
-
-### Standard Events
-
-1. **connection**
-   - Sent when a client connects successfully
-   ```json
-   {
-     "type": "connection",
-     "status": "connected",
-     "id": "client_uuid",
-     "authenticated": true,
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-2. **state_changed**
-   - Sent when an entity's state changes
-   ```json
-   {
-     "type": "state_changed",
-     "data": {
-       "entity_id": "light.living_room",
-       "state": "on",
-       "attributes": {
-         "brightness": 255,
-         "color_temp": 370
-       },
-       "last_changed": "2024-02-10T12:00:00.000Z",
-       "last_updated": "2024-02-10T12:00:00.000Z"
-     },
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-3. **service_called**
-   - Sent when a Home Assistant service is called
-   ```json
-   {
-     "type": "service_called",
-     "data": {
-       "domain": "light",
-       "service": "turn_on",
-       "service_data": {
-         "entity_id": "light.living_room",
-         "brightness": 255
-       }
-     },
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-4. **automation_triggered**
-   - Sent when an automation is triggered
-   ```json
-   {
-     "type": "automation_triggered",
-     "data": {
-       "automation_id": "automation.morning_routine",
-       "trigger": {
-         "platform": "time",
-         "at": "07:00:00"
-       }
-     },
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-5. **script_executed**
-   - Sent when a script is executed
-   ```json
-   {
-     "type": "script_executed",
-     "data": {
-       "script_id": "script.welcome_home",
-       "execution_data": {
-         "status": "completed"
-       }
-     },
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-### System Events
-
-1. **ping**
-   - Sent every 30 seconds to keep the connection alive
-   ```json
-   {
-     "type": "ping",
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-2. **error**
-   - Sent when an error occurs
-   ```json
-   {
-     "type": "error",
-     "error": "rate_limit_exceeded",
-     "message": "Too many requests, please try again later",
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-## Rate Limiting
-
-- Maximum 1000 requests per minute per client
-- Rate limits are reset every minute
-- Exceeding the rate limit will result in an error event
-
-## Connection Management
-
-- Maximum 100 concurrent clients
-- Connections timeout after 5 minutes of inactivity
-- Ping messages are sent every 30 seconds
-- Clients should handle reconnection on connection loss
-
-## Example Implementation
-
-```javascript
-class HomeAssistantSSE {
-  constructor(baseUrl, token) {
-    this.baseUrl = baseUrl;
-    this.token = token;
-    this.eventSource = null;
-    this.reconnectAttempts = 0;
-    this.maxReconnectAttempts = 5;
-    this.reconnectDelay = 1000;
-  }
-
-  connect(options = {}) {
-    const params = new URLSearchParams({
-      token: this.token,
-      ...(options.events && { events: options.events.join(',') }),
-      ...(options.entity_id && { entity_id: options.entity_id }),
-      ...(options.domain && { domain: options.domain })
-    });
-
-    this.eventSource = new EventSource(`${this.baseUrl}/subscribe_events?${params}`);
-
-    this.eventSource.onmessage = (event) => {
-      const data = JSON.parse(event.data);
-      this.handleEvent(data);
-    };
-
-    this.eventSource.onerror = (error) => {
-      console.error('SSE Error:', error);
-      this.handleError(error);
-    };
-  }
-
-  handleEvent(data) {
-    switch (data.type) {
-      case 'connection':
-        this.reconnectAttempts = 0;
-        console.log('Connected:', data);
-        break;
-      case 'ping':
-        // Connection is alive
-        break;
-      case 'error':
-        console.error('Server Error:', data);
-        break;
-      default:
-        // Handle other event types
-        console.log('Event:', data);
-    }
-  }
-
-  handleError(error) {
-    this.eventSource?.close();
-    
-    if (this.reconnectAttempts < this.maxReconnectAttempts) {
-      this.reconnectAttempts++;
-      const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
-      console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
-      setTimeout(() => this.connect(), delay);
-    } else {
-      console.error('Max reconnection attempts reached');
-    }
-  }
-
-  disconnect() {
-    this.eventSource?.close();
-    this.eventSource = null;
-  }
-}
-
-// Usage example
-const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
-client.connect({
-  events: ['state_changed', 'automation_triggered'],
-  domain: 'light'
-});
-```
-
-## Best Practices
-
-1. **Error Handling**
-   - Implement exponential backoff for reconnection attempts
-   - Handle connection timeouts gracefully
-   - Monitor for rate limit errors
-
-2. **Resource Management**
-   - Close EventSource when no longer needed
-   - Limit subscriptions to necessary events/entities
-   - Handle cleanup on page unload
-
-3. **Security**
-   - Never expose the authentication token in client-side code
-   - Use HTTPS in production
-   - Validate all incoming data
-
-4. **Performance**
-   - Subscribe only to needed events
-   - Implement client-side event filtering
-   - Monitor memory usage for long-running connections
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Connection Failures**
-   - Verify your authentication token is valid
-   - Check server URL is accessible
-   - Ensure proper network connectivity
-   - Verify SSL/TLS configuration if using HTTPS
-
-2. **Missing Events**
-   - Confirm subscription parameters are correct
-   - Check rate limiting status
-   - Verify entity/domain exists
-   - Monitor client-side event handlers
-
-3. **Performance Issues**
-   - Reduce number of subscriptions
-   - Implement client-side filtering
-   - Monitor memory usage
-   - Check network latency
-
-### Debugging Tips
-
-1. Enable console logging:
-```javascript
-const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
-client.debug = true; // Enables detailed logging
-```
-
-2. Monitor network traffic:
-```javascript
-// Add event listeners for connection states
-eventSource.addEventListener('open', () => {
-  console.log('Connection opened');
-});
-
-eventSource.addEventListener('error', (e) => {
-  console.log('Connection error:', e);
-});
-```
-
-3. Track subscription status:
-```javascript
-// Get current subscriptions
-const stats = await fetch('/get_sse_stats', {
-  headers: { 'Authorization': `Bearer ${token}` }
-}).then(r => r.json());
-
-console.log('Current subscriptions:', stats);
-``` 

docs/_config.yml

@@ -0,0 +1,78 @@
+title: Model Context Protocol (MCP)
+description: A bridge between Home Assistant and Language Learning Models
+theme: jekyll-theme-minimal
+markdown: kramdown
+
+# Repository settings
+repository: jango-blockchained/advanced-homeassistant-mcp
+github: [metadata]
+
+# Add base URL and URL settings
+baseurl: "/advanced-homeassistant-mcp" # the subpath of your site
+url: "https://jango-blockchained.github.io" # the base hostname & protocol
+
+# Theme settings
+logo: /assets/img/logo.png # path to logo (create this if you want a logo)
+show_downloads: true # show download buttons for your repo
+
+plugins:
+  - jekyll-relative-links
+  - jekyll-seo-tag
+  - jekyll-remote-theme
+  - jekyll-github-metadata
+
+# Enable relative links
+relative_links:
+  enabled: true
+  collections: true
+
+# Navigation structure
+header_pages:
+  - index.md
+  - getting-started.md
+  - api.md
+  - usage.md
+  - tools/tools.md
+  - development/development.md
+  - troubleshooting.md
+  - contributing.md
+  - roadmap.md
+
+# Collections
+collections:
+  tools:
+    output: true
+    permalink: /:collection/:name
+  development:
+    output: true
+    permalink: /:collection/:name
+
+# Default layouts
+defaults:
+  - scope:
+      path: ""
+      type: "pages"
+    values:
+      layout: "default"
+  - scope:
+      path: "tools"
+      type: "tools"
+    values:
+      layout: "default"
+  - scope:
+      path: "development"
+      type: "development"
+    values:
+      layout: "default"
+
+# Exclude files from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - node_modules
+  - vendor
+
+# Sass settings
+sass:
+  style: compressed
+  sass_dir: _sass 

docs/_layouts/default.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="{{ site.lang | default: " en-US" }}">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    {% seo %}
+    <link rel="stylesheet" href="{{ " /assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
+</head>
+
+<body>
+    <div class="wrapper">
+        <header>
+            <h1><a href="{{ " /" | absolute_url }}">{{ site.title | default: site.github.repository_name }}</a></h1>
+
+            {% if site.logo %}
+            <img src="{{site.logo | relative_url}}" alt="Logo" />
+            {% endif %}
+
+            <p>{{ site.description | default: site.github.project_tagline }}</p>
+
+            <p class="view"><a href="{{ site.github.repository_url }}">View the Project on GitHub <small>{{
+                        site.github.repository_nwo }}</small></a></p>
+
+            <nav class="main-nav">
+                <h3>Documentation</h3>
+                <ul>
+                    <li><a href="{{ '/getting-started' | relative_url }}">Getting Started</a></li>
+                    <li><a href="{{ '/api' | relative_url }}">API Reference</a></li>
+                    <li><a href="{{ '/sse-api' | relative_url }}">SSE API</a></li>
+                    <li><a href="{{ '/architecture' | relative_url }}">Architecture</a></li>
+                    <li><a href="{{ '/contributing' | relative_url }}">Contributing</a></li>
+                    <li><a href="{{ '/troubleshooting' | relative_url }}">Troubleshooting</a></li>
+                </ul>
+            </nav>
+        </header>
+        <section>
+            {{ content }}
+        </section>
+        <footer>
+            {% if site.github.is_project_page %}
+            <p>This project is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
+            {% endif %}
+            <p><small>Hosted on GitHub Pages &mdash; Theme by <a
+                        href="https://github.com/orderedlist">orderedlist</a></small></p>
+        </footer>
+    </div>
+    <script src="{{ " /assets/js/scale.fix.js" | relative_url }}"></script>
+</body>
+
+</html>

docs/api.md

@@ -0,0 +1,728 @@
+# 🚀 Home Assistant MCP API Documentation
+
+![API Version](https://img.shields.io/badge/API-v2.1-blueviolet) ![Rate Limit](https://img.shields.io/badge/Rate%20Limit-100%2Fmin-brightgreen)
+
+## 🌟 Quick Start
+
+```bash
+# Get API schema with caching
+curl -X GET http://localhost:3000/mcp \
+  -H "Cache-Control: max-age=3600" # Cache for 1 hour
+```
+
+## 🔌 Core Functions ⚙️
+
+### State Management (`/api/state`)
+```http
+GET /api/state?cache=true  # Enable client-side caching
+POST /api/state
+```
+
+**Example Request:**
+```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
+  }
+}
+```
+
+### Context Updates
+```http
+POST /api/context
+```
+
+Updates the current context with new information.
+
+**Example Request:**
+```json
+POST /api/context
+{
+  "user": "john",
+  "location": "kitchen",
+  "time": "morning",
+  "activity": "cooking"
+}
+```
+
+## Action Endpoints
+
+### Execute Action
+```http
+POST /api/action
+```
+
+Executes a specified action with given parameters.
+
+**Example Request:**
+```json
+POST /api/action
+{
+  "action": "turn_on_lights",
+  "parameters": {
+    "room": "living_room",
+    "brightness": 80
+  }
+}
+```
+
+### Batch Actions
+```http
+POST /api/actions/batch
+```
+
+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.
+
+```javascript
+// Client-side connection example
+const ws = new WebSocket('ws://localhost:3000/ws');
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('Received update:', data);
+};
+```
+
+### 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:
+
+- 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"]
+    }
+  }
+}
+```
+
+## Rate Limiting
+
+The API implements rate limiting to prevent abuse:
+
+- 100 requests per minute per IP for regular endpoints
+- 1000 requests per minute per IP for WebSocket connections
+
+When rate limit is exceeded, the server returns:
+
+```json
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Too many requests",
+    "reset_time": "2024-03-20T10:31:00Z"
+  }
+}
+```
+
+## Example Usage
+
+### Using curl
+```bash
+# Get current state
+curl -X GET \
+  http://localhost:3000/api/state \
+  -H 'Authorization: ApiKey your_api_key_here'
+
+# Execute action
+curl -X POST \
+  http://localhost:3000/api/action \
+  -H 'Authorization: ApiKey your_api_key_here' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "action": "turn_on_lights",
+    "parameters": {
+      "room": "living_room",
+      "brightness": 80
+    }
+  }'
+```
+
+### Using JavaScript
+```javascript
+// Execute action
+async function executeAction() {
+  const response = await fetch('http://localhost:3000/api/action', {
+    method: 'POST',
+    headers: {
+      'Authorization': 'ApiKey your_api_key_here',
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      action: 'turn_on_lights',
+      parameters: {
+        room: 'living_room',
+        brightness: 80
+      }
+    })
+  });
+  
+  const data = await response.json();
+  console.log('Action result:', data);
+}
+```
+
+## Security Middleware
+
+### Overview
+
+The security middleware provides a comprehensive set of utility functions to enhance the security of the Home Assistant MCP application. These functions cover various aspects of web security, including:
+
+- Rate limiting
+- Request validation
+- Input sanitization
+- Security headers
+- Error handling
+
+### Utility Functions
+
+#### `checkRateLimit(ip: string, maxRequests?: number, windowMs?: number)`
+
+Manages rate limiting for IP addresses to prevent abuse.
+
+**Parameters**:
+- `ip`: IP address to track
+- `maxRequests`: Maximum number of requests allowed (default: 100)
+- `windowMs`: Time window for rate limiting (default: 15 minutes)
+
+**Returns**: `boolean` or throws an error if limit is exceeded
+
+**Example**:
+```typescript
+try {
+  checkRateLimit('127.0.0.1'); // Checks rate limit with default settings
+} catch (error) {
+  // Handle rate limit exceeded
+}
+```
+
+#### `validateRequestHeaders(request: Request, requiredContentType?: string)`
+
+Validates incoming HTTP request headers for security and compliance.
+
+**Parameters**:
+- `request`: The incoming HTTP request
+- `requiredContentType`: Expected content type (default: 'application/json')
+
+**Checks**:
+- Content type
+- Request body size
+- Authorization header (optional)
+
+**Example**:
+```typescript
+try {
+  validateRequestHeaders(request);
+} catch (error) {
+  // Handle validation errors
+}
+```
+
+#### `sanitizeValue(value: unknown)`
+
+Sanitizes input values to prevent XSS attacks.
+
+**Features**:
+- Escapes HTML tags
+- Handles nested objects and arrays
+- Preserves non-string values
+
+**Example**:
+```typescript
+const sanitized = sanitizeValue('<script>alert("xss")</script>');
+// Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+```
+
+#### `applySecurityHeaders(request: Request, helmetConfig?: HelmetOptions)`
+
+Applies security headers to HTTP requests using Helmet.
+
+**Security Headers**:
+- Content Security Policy
+- X-Frame-Options
+- X-Content-Type-Options
+- Referrer Policy
+- HSTS (in production)
+
+**Example**:
+```typescript
+const headers = applySecurityHeaders(request);
+```
+
+#### `handleError(error: Error, env?: string)`
+
+Handles error responses with environment-specific details.
+
+**Modes**:
+- Production: Generic error message
+- Development: Detailed error with stack trace
+
+**Example**:
+```typescript
+const errorResponse = handleError(error, process.env.NODE_ENV);
+```
+
+### Middleware Usage
+
+These utility functions are integrated into Elysia middleware:
+
+```typescript
+const app = new Elysia()
+  .use(rateLimiter)      // Rate limiting
+  .use(validateRequest)  // Request validation
+  .use(sanitizeInput)    // Input sanitization
+  .use(securityHeaders)  // Security headers
+  .use(errorHandler)     // Error handling
+```
+
+### Best Practices
+
+1. Always validate and sanitize user inputs
+2. Use rate limiting to prevent abuse
+3. Apply security headers
+4. Handle errors gracefully
+5. Keep environment-specific error handling
+
+### Security Considerations
+
+- Configurable rate limits
+- XSS protection
+- Content security policies
+- Token validation
+- Error information exposure control
+
+### Troubleshooting
+
+- Ensure `JWT_SECRET` is set in environment
+- Check content type in requests
+- Monitor rate limit errors
+- Review error handling in different environments 

docs/api/core.md

@@ -0,0 +1,326 @@
+---
+layout: default
+title: Core Functions
+parent: API Reference
+nav_order: 3
+---
+
+# Core Functions API 🔧
+
+The Core Functions API provides the fundamental operations for interacting with Home Assistant devices and services through MCP Server.
+
+## Device Control
+
+### Get Device State
+
+Retrieve the current state of devices.
+
+```http
+GET /api/state
+GET /api/state/{entity_id}
+```
+
+Parameters:
+- `entity_id` (optional): Specific device ID to query
+
+```bash
+# Get all states
+curl http://localhost:3000/api/state
+
+# Get specific device state
+curl http://localhost:3000/api/state/light.living_room
+```
+
+Response:
+```json
+{
+  "entity_id": "light.living_room",
+  "state": "on",
+  "attributes": {
+    "brightness": 255,
+    "color_temp": 370,
+    "friendly_name": "Living Room Light"
+  },
+  "last_changed": "2024-01-20T15:30:00Z"
+}
+```
+
+### Control Device
+
+Execute device commands.
+
+```http
+POST /api/device/control
+```
+
+Request body:
+```json
+{
+  "entity_id": "light.living_room",
+  "action": "turn_on",
+  "parameters": {
+    "brightness": 200,
+    "color_temp": 400
+  }
+}
+```
+
+Available actions:
+- `turn_on`
+- `turn_off`
+- `toggle`
+- `set_value`
+
+Example with curl:
+```bash
+curl -X POST http://localhost:3000/api/device/control \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "entity_id": "light.living_room",
+    "action": "turn_on",
+    "parameters": {
+      "brightness": 200
+    }
+  }'
+```
+
+## Natural Language Commands
+
+### Execute Command
+
+Process natural language commands.
+
+```http
+POST /api/command
+```
+
+Request body:
+```json
+{
+  "command": "Turn on the living room lights and set them to 50% brightness"
+}
+```
+
+Example usage:
+```bash
+curl -X POST http://localhost:3000/api/command \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "command": "Turn on the living room lights and set them to 50% brightness"
+  }'
+```
+
+Response:
+```json
+{
+  "success": true,
+  "actions": [
+    {
+      "entity_id": "light.living_room",
+      "action": "turn_on",
+      "parameters": {
+        "brightness": 127
+      },
+      "status": "completed"
+    }
+  ],
+  "message": "Command executed successfully"
+}
+```
+
+## Scene Management
+
+### Create Scene
+
+Define a new scene with multiple actions.
+
+```http
+POST /api/scene
+```
+
+Request body:
+```json
+{
+  "name": "Movie Night",
+  "description": "Perfect lighting for movie watching",
+  "actions": [
+    {
+      "entity_id": "light.living_room",
+      "action": "turn_on",
+      "parameters": {
+        "brightness": 50,
+        "color_temp": 500
+      }
+    },
+    {
+      "entity_id": "cover.living_room",
+      "action": "close"
+    }
+  ]
+}
+```
+
+### Activate Scene
+
+Trigger a predefined scene.
+
+```http
+POST /api/scene/{scene_name}/activate
+```
+
+Example:
+```bash
+curl -X POST http://localhost:3000/api/scene/movie_night/activate \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+## Groups
+
+### Create Device Group
+
+Create a group of devices for collective control.
+
+```http
+POST /api/group
+```
+
+Request body:
+```json
+{
+  "name": "Living Room",
+  "entities": [
+    "light.living_room_main",
+    "light.living_room_accent",
+    "switch.living_room_fan"
+  ]
+}
+```
+
+### Control Group
+
+Control multiple devices in a group.
+
+```http
+POST /api/group/{group_name}/control
+```
+
+Request body:
+```json
+{
+  "action": "turn_off"
+}
+```
+
+## System Operations
+
+### Health Check
+
+Check server status and connectivity.
+
+```http
+GET /health
+```
+
+Response:
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "uptime": 3600,
+  "homeAssistant": {
+    "connected": true,
+    "version": "2024.1.0"
+  }
+}
+```
+
+### Configuration
+
+Get current server configuration.
+
+```http
+GET /api/config
+```
+
+Response:
+```json
+{
+  "server": {
+    "port": 3000,
+    "host": "0.0.0.0",
+    "version": "1.0.0"
+  },
+  "homeAssistant": {
+    "url": "http://homeassistant:8123",
+    "connected": true
+  },
+  "features": {
+    "nlp": true,
+    "scenes": true,
+    "groups": true
+  }
+}
+```
+
+## Error Handling
+
+All endpoints follow standard HTTP status codes and return detailed error messages:
+
+```json
+{
+  "error": true,
+  "code": "INVALID_ENTITY",
+  "message": "Device 'light.nonexistent' not found",
+  "details": {
+    "entity_id": "light.nonexistent",
+    "available_entities": [
+      "light.living_room",
+      "light.kitchen"
+    ]
+  }
+}
+```
+
+Common error codes:
+- `INVALID_ENTITY`: Device not found
+- `INVALID_ACTION`: Unsupported action
+- `INVALID_PARAMETERS`: Invalid command parameters
+- `AUTHENTICATION_ERROR`: Invalid or missing token
+- `CONNECTION_ERROR`: Home Assistant connection issue
+
+## TypeScript Interfaces
+
+```typescript
+interface DeviceState {
+  entity_id: string;
+  state: string;
+  attributes: Record<string, any>;
+  last_changed: string;
+}
+
+interface DeviceCommand {
+  entity_id: string;
+  action: 'turn_on' | 'turn_off' | 'toggle' | 'set_value';
+  parameters?: Record<string, any>;
+}
+
+interface Scene {
+  name: string;
+  description?: string;
+  actions: DeviceCommand[];
+}
+
+interface Group {
+  name: string;
+  entities: string[];
+}
+```
+
+## Related Resources
+
+- [API Overview](index.md)
+- [SSE API](sse.md)
+- [Architecture](../architecture.md)
+- [Examples](https://github.com/jango-blockchained/advanced-homeassistant-mcp/tree/main/examples) 

docs/api/index.md

@@ -0,0 +1,234 @@
+---
+layout: default
+title: API Overview
+parent: API Reference
+nav_order: 1
+has_children: false
+---
+
+# API Documentation 📚
+
+Welcome to the MCP Server API documentation. This guide covers all available endpoints, authentication methods, and integration patterns.
+
+## API Overview
+
+The MCP Server provides several API categories:
+
+1. **Core API** - Basic device control and state management
+2. **SSE API** - Real-time event subscriptions
+3. **Scene API** - Scene management and automation
+4. **Voice API** - Natural language command processing
+
+## Authentication
+
+All API endpoints require authentication using JWT tokens:
+
+```bash
+# Include the token in your requests
+curl -H "Authorization: Bearer YOUR_JWT_TOKEN" http://localhost:3000/api/state
+```
+
+To obtain a token:
+
+```bash
+curl -X POST http://localhost:3000/auth/token \
+  -H "Content-Type: application/json" \
+  -d '{"username": "your_username", "password": "your_password"}'
+```
+
+## Core Endpoints
+
+### Device State
+
+```http
+GET /api/state
+```
+
+Retrieve the current state of all devices:
+
+```bash
+curl http://localhost:3000/api/state
+```
+
+Response:
+```json
+{
+  "devices": [
+    {
+      "id": "light.living_room",
+      "state": "on",
+      "attributes": {
+        "brightness": 255,
+        "color_temp": 370
+      }
+    }
+  ]
+}
+```
+
+### Command Execution
+
+```http
+POST /api/command
+```
+
+Execute a natural language command:
+
+```bash
+curl -X POST http://localhost:3000/api/command \
+  -H "Content-Type: application/json" \
+  -d '{"command": "Turn on the kitchen lights"}'
+```
+
+Response:
+```json
+{
+  "success": true,
+  "action": "turn_on",
+  "device": "light.kitchen",
+  "message": "Kitchen lights turned on"
+}
+```
+
+## Real-Time Events
+
+### Event Subscription
+
+```http
+GET /subscribe_events
+```
+
+Subscribe to device state changes:
+
+```javascript
+const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN');
+
+eventSource.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    console.log('State changed:', data);
+};
+```
+
+### Filtered Subscriptions
+
+Subscribe to specific device types:
+
+```http
+GET /subscribe_events?domain=light
+GET /subscribe_events?entity_id=light.living_room
+```
+
+## Scene Management
+
+### Create Scene
+
+```http
+POST /api/scene
+```
+
+Create a new scene:
+
+```bash
+curl -X POST http://localhost:3000/api/scene \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Movie Night",
+    "actions": [
+      {"device": "light.living_room", "action": "dim", "value": 20},
+      {"device": "media_player.tv", "action": "on"}
+    ]
+  }'
+```
+
+### Activate Scene
+
+```http
+POST /api/scene/activate
+```
+
+Activate an existing scene:
+
+```bash
+curl -X POST http://localhost:3000/api/scene/activate \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Movie Night"}'
+```
+
+## Error Handling
+
+The API uses standard HTTP status codes:
+
+- `200` - Success
+- `400` - Bad Request
+- `401` - Unauthorized
+- `404` - Not Found
+- `500` - Server Error
+
+Error responses include detailed messages:
+
+```json
+{
+  "error": true,
+  "message": "Device not found",
+  "code": "DEVICE_NOT_FOUND",
+  "details": {
+    "device_id": "light.nonexistent"
+  }
+}
+```
+
+## Rate Limiting
+
+API requests are rate-limited to prevent abuse:
+
+```http
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 99
+X-RateLimit-Reset: 1640995200
+```
+
+When exceeded, returns `429 Too Many Requests`:
+
+```json
+{
+  "error": true,
+  "message": "Rate limit exceeded",
+  "reset": 1640995200
+}
+```
+
+## WebSocket API
+
+For bi-directional communication:
+
+```javascript
+const ws = new WebSocket('ws://localhost:3000/ws');
+
+ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    console.log('Received:', data);
+};
+
+ws.send(JSON.stringify({
+    type: 'command',
+    payload: {
+        command: 'Turn on lights'
+    }
+}));
+```
+
+## API Versioning
+
+The current API version is v1. Include the version in the URL:
+
+```http
+/api/v1/state
+/api/v1/command
+```
+
+## Further Reading
+
+- [SSE API Details](sse.md) - In-depth SSE documentation
+- [Core Functions](core.md) - Detailed endpoint documentation
+- [Architecture Overview](../architecture.md) - System design details
+- [Troubleshooting](../troubleshooting.md) - Common issues and solutions 

docs/api/sse.md

@@ -0,0 +1,266 @@
+---
+layout: default
+title: SSE API
+parent: API Reference
+nav_order: 2
+---
+
+# Server-Sent Events (SSE) API 📡
+
+The SSE API provides real-time updates about device states and events from your Home Assistant setup. This guide covers how to use and implement SSE connections in your applications.
+
+## Overview
+
+Server-Sent Events (SSE) is a standard that enables servers to push real-time updates to clients over HTTP connections. MCP Server uses SSE to provide:
+
+- Real-time device state updates
+- Event notifications
+- System status changes
+- Command execution results
+
+## Basic Usage
+
+### Establishing a Connection
+
+Create an EventSource connection to receive updates:
+
+```javascript
+const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_JWT_TOKEN');
+
+eventSource.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    console.log('Received update:', data);
+};
+```
+
+### Connection States
+
+Handle different connection states:
+
+```javascript
+eventSource.onopen = () => {
+    console.log('Connection established');
+};
+
+eventSource.onerror = (error) => {
+    console.error('Connection error:', error);
+    // Implement reconnection logic if needed
+};
+```
+
+## Event Types
+
+### Device State Events
+
+Subscribe to all device state changes:
+
+```javascript
+const stateEvents = new EventSource('http://localhost:3000/subscribe_events?type=state');
+
+stateEvents.onmessage = (event) => {
+    const state = JSON.parse(event.data);
+    console.log('Device state changed:', state);
+};
+```
+
+Example state event:
+```json
+{
+  "type": "state_changed",
+  "entity_id": "light.living_room",
+  "state": "on",
+  "attributes": {
+    "brightness": 255,
+    "color_temp": 370
+  },
+  "timestamp": "2024-01-20T15:30:00Z"
+}
+```
+
+### Filtered Subscriptions
+
+#### By Domain
+Subscribe to specific device types:
+
+```javascript
+// Subscribe to only light events
+const lightEvents = new EventSource('http://localhost:3000/subscribe_events?domain=light');
+
+// Subscribe to multiple domains
+const multiEvents = new EventSource('http://localhost:3000/subscribe_events?domain=light,switch,sensor');
+```
+
+#### By Entity ID
+Subscribe to specific devices:
+
+```javascript
+// Single entity
+const livingRoomLight = new EventSource(
+    'http://localhost:3000/subscribe_events?entity_id=light.living_room'
+);
+
+// Multiple entities
+const kitchenDevices = new EventSource(
+    'http://localhost:3000/subscribe_events?entity_id=light.kitchen,switch.coffee_maker'
+);
+```
+
+## Advanced Usage
+
+### Connection Management
+
+Implement robust connection handling:
+
+```javascript
+class SSEManager {
+    constructor(url, options = {}) {
+        this.url = url;
+        this.options = {
+            maxRetries: 3,
+            retryDelay: 1000,
+            ...options
+        };
+        this.retryCount = 0;
+        this.connect();
+    }
+
+    connect() {
+        this.eventSource = new EventSource(this.url);
+        
+        this.eventSource.onopen = () => {
+            this.retryCount = 0;
+            console.log('Connected to SSE stream');
+        };
+
+        this.eventSource.onerror = (error) => {
+            this.handleError(error);
+        };
+
+        this.eventSource.onmessage = (event) => {
+            this.handleMessage(event);
+        };
+    }
+
+    handleError(error) {
+        console.error('SSE Error:', error);
+        this.eventSource.close();
+
+        if (this.retryCount < this.options.maxRetries) {
+            this.retryCount++;
+            setTimeout(() => {
+                console.log(`Retrying connection (${this.retryCount}/${this.options.maxRetries})`);
+                this.connect();
+            }, this.options.retryDelay * this.retryCount);
+        }
+    }
+
+    handleMessage(event) {
+        try {
+            const data = JSON.parse(event.data);
+            // Handle the event data
+            console.log('Received:', data);
+        } catch (error) {
+            console.error('Error parsing SSE data:', error);
+        }
+    }
+
+    disconnect() {
+        if (this.eventSource) {
+            this.eventSource.close();
+        }
+    }
+}
+
+// Usage
+const sseManager = new SSEManager('http://localhost:3000/subscribe_events?token=YOUR_TOKEN');
+```
+
+### Event Filtering
+
+Filter events on the client side:
+
+```javascript
+class EventFilter {
+    constructor(conditions) {
+        this.conditions = conditions;
+    }
+
+    matches(event) {
+        return Object.entries(this.conditions).every(([key, value]) => {
+            if (Array.isArray(value)) {
+                return value.includes(event[key]);
+            }
+            return event[key] === value;
+        });
+    }
+}
+
+// Usage
+const filter = new EventFilter({
+    domain: ['light', 'switch'],
+    state: 'on'
+});
+
+eventSource.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    if (filter.matches(data)) {
+        console.log('Matched event:', data);
+    }
+};
+```
+
+## Best Practices
+
+1. **Authentication**
+   - Always include authentication tokens
+   - Implement token refresh mechanisms
+   - Handle authentication errors gracefully
+
+2. **Error Handling**
+   - Implement progressive retry logic
+   - Log connection issues
+   - Notify users of connection status
+
+3. **Resource Management**
+   - Close EventSource connections when not needed
+   - Limit the number of concurrent connections
+   - Use filtered subscriptions when possible
+
+4. **Performance**
+   - Process events efficiently
+   - Batch UI updates
+   - Consider debouncing frequent updates
+
+## Common Issues
+
+### Connection Drops
+If the connection drops, the EventSource will automatically attempt to reconnect. You can customize this behavior:
+
+```javascript
+eventSource.addEventListener('error', (error) => {
+    if (eventSource.readyState === EventSource.CLOSED) {
+        // Connection closed, implement custom retry logic
+    }
+});
+```
+
+### Memory Leaks
+Always clean up EventSource connections:
+
+```javascript
+// In a React component
+useEffect(() => {
+    const eventSource = new EventSource('http://localhost:3000/subscribe_events');
+    
+    return () => {
+        eventSource.close(); // Cleanup on unmount
+    };
+}, []);
+```
+
+## Related Resources
+
+- [API Overview](index.md)
+- [Core Functions](core.md)
+- [WebSocket API](index.md#websocket-api)
+- [Troubleshooting](../troubleshooting.md) 

docs/architecture.md

@@ -0,0 +1,283 @@
+---
+layout: default
+title: Architecture
+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.
+
+## System Architecture
+
+```mermaid
+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"
+        HA[Home Assistant Core]
+        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
+```
+
+## Component Details
+
+### 1. Client Layer
+
+The client layer consists of various interfaces that interact with the MCP Server:
+
+- **Web Clients**: Browser-based dashboards and control panels
+- **Mobile Clients**: Native mobile applications
+- **Voice Assistants**: Voice-enabled devices and interfaces
+
+### 2. MCP Server Core
+
+#### API Gateway
+- Handles all incoming HTTP requests
+- Manages authentication and rate limiting
+- Routes requests to appropriate handlers
+
+```typescript
+interface APIGateway {
+    authenticate(): Promise<boolean>;
+    rateLimit(): Promise<boolean>;
+    route(request: Request): Promise<Response>;
+}
+```
+
+#### NLP Engine
+- Processes natural language commands
+- Integrates with Language Models
+- Extracts intents and entities
+
+```typescript
+interface NLPEngine {
+    processCommand(text: string): Promise<CommandIntent>;
+    extractEntities(text: string): Promise<Entity[]>;
+    validateIntent(intent: CommandIntent): boolean;
+}
+```
+
+#### Event Management
+- **SSE Manager**: Handles Server-Sent Events
+- **WebSocket Server**: Manages bi-directional communication
+- **Command Manager**: Processes and executes commands
+
+### 3. Home Assistant Integration
+
+The server maintains a robust connection to Home Assistant through:
+
+- REST API calls
+- WebSocket connections
+- Event subscriptions
+
+```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) 

docs/assets/css/style.scss

@@ -0,0 +1,54 @@
+@import "{{ site.theme }}";
+
+// Custom styles
+.main-nav {
+    margin-top: 20px;
+
+    ul {
+        list-style: none;
+        padding: 0;
+        margin: 0;
+    }
+
+    li {
+        margin-bottom: 8px;
+    }
+
+    a {
+        color: #267CB9;
+        text-decoration: none;
+
+        &:hover {
+            text-decoration: underline;
+        }
+    }
+}
+
+h1,
+h2,
+h3 {
+    color: #333;
+}
+
+code {
+    background-color: #f8f8f8;
+    border: 1px solid #ddd;
+    border-radius: 3px;
+    padding: 2px 5px;
+}
+
+pre {
+    background-color: #f8f8f8;
+    border: 1px solid #ddd;
+    border-radius: 3px;
+    padding: 10px;
+    overflow-x: auto;
+}
+
+.wrapper {
+    max-width: 960px;
+}
+
+section {
+    max-width: 700px;
+}

docs/assets/stylesheets/extra.css

@@ -0,0 +1,28 @@
+:root {
+  --md-primary-fg-color: #1a73e8;
+  --md-primary-fg-color--light: #5195ee;
+  --md-primary-fg-color--dark: #0d47a1;
+}
+
+.md-header {
+  box-shadow: 0 0 0.2rem rgba(0,0,0,.1), 0 0.2rem 0.4rem rgba(0,0,0,.2);
+}
+
+.md-main__inner {
+  margin-top: 1.5rem;
+}
+
+.md-typeset h1 {
+  font-weight: 700;
+  color: var(--md-primary-fg-color);
+}
+
+.md-typeset .admonition {
+  font-size: .8rem;
+}
+
+code {
+  background-color: rgba(175,184,193,0.2);
+  padding: .2em .4em;
+  border-radius: 6px;
+} 

docs/claude_desktop_config.json

@@ -0,0 +1,16 @@
+{
+    "mcpServers": {
+        "homeassistant-mcp": {
+            "command": "bun",
+            "args": [
+                "run",
+                "start",
+                "--port",
+                "8080"
+            ],
+            "env": {
+                "NODE_ENV": "production"
+            }
+        }
+    }
+}

docs/cline_config.json

@@ -0,0 +1,18 @@
+{
+    "mcpServers": {
+        "homeassistant-mcp": {
+            "command": "bun",
+            "args": [
+                "run",
+                "start",
+                "--enable-cline",
+                "--config",
+                "${configDir}/.env"
+            ],
+            "env": {
+                "NODE_ENV": "production",
+                "CLINE_MODE": "true"
+            }
+        }
+    }
+}

docs/contributing.md

@@ -0,0 +1,254 @@
+---
+layout: default
+title: Contributing
+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.
+
+## 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
+
+### Development Setup
+
+1. Fork and clone the repository:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/advanced-homeassistant-mcp.git
+   cd advanced-homeassistant-mcp
+   ```
+
+2. Install dependencies:
+   ```bash
+   bun install
+   ```
+
+3. Set up your development 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
+
+- `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation updates
+- `refactor/` - Code refactoring
+- `test/` - Test improvements
+
+Example:
+```bash
+git checkout -b feature/voice-commands
+```
+
+### Commit Messages
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+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
+
+Examples:
+```bash
+feat(api): add voice command endpoint
+fix(sse): resolve connection timeout issue
+docs(readme): update installation instructions
+```
+
+### Testing
+
+Run tests before submitting your changes:
+
+```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
+```
+
+## 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
+
+### PR Template
+
+```markdown
+## Description
+Brief description 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
+```
+
+## Development Guidelines
+
+### Code Organization
+
+```
+src/
+├── api/          # API endpoints
+├── core/         # Core functionality
+├── models/       # Data models
+├── services/     # Business logic
+├── utils/        # Utility functions
+└── types/        # TypeScript types
+```
+
+### 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
+- Focus on constructive feedback
+- Help maintain a positive environment
+- Follow our code style guidelines
+- Write clear documentation
+- Test their code thoroughly
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License. 

docs/development/best-practices.md

@@ -0,0 +1,310 @@
+# Development Best Practices
+
+This guide outlines the best practices for developing tools and features for the Home Assistant MCP.
+
+## Code Style
+
+### TypeScript
+
+1. Use TypeScript for all new code
+2. Enable strict mode
+3. Use explicit types
+4. Avoid `any` type
+5. Use interfaces over types
+6. Document with JSDoc comments
+
+```typescript
+/** 
+ * Represents a device in the system.
+ * @interface
+ */
+interface Device {
+    /** Unique device identifier */
+    id: string;
+    
+    /** Human-readable device name */
+    name: string;
+    
+    /** Device state */
+    state: DeviceState;
+}
+```
+
+### Naming Conventions
+
+1. Use PascalCase for:
+   - Classes
+   - Interfaces
+   - Types
+   - Enums
+
+2. Use camelCase for:
+   - Variables
+   - Functions
+   - Methods
+   - Properties
+
+3. Use UPPER_SNAKE_CASE for:
+   - Constants
+   - Enum values
+
+```typescript
+class DeviceManager {
+    private readonly DEFAULT_TIMEOUT = 5000;
+    
+    async getDeviceState(deviceId: string): Promise<DeviceState> {
+        // Implementation
+    }
+}
+```
+
+## Architecture
+
+### SOLID Principles
+
+1. Single Responsibility
+   - Each class/module has one job
+   - Split complex functionality
+
+2. Open/Closed
+   - Open for extension
+   - Closed for modification
+
+3. Liskov Substitution
+   - Subtypes must be substitutable
+   - Use interfaces properly
+
+4. Interface Segregation
+   - Keep interfaces focused
+   - Split large interfaces
+
+5. Dependency Inversion
+   - Depend on abstractions
+   - Use dependency injection
+
+### Example
+
+```typescript
+// Bad
+class DeviceManager {
+    async getState() { /* ... */ }
+    async setState() { /* ... */ }
+    async sendNotification() { /* ... */ }  // Wrong responsibility
+}
+
+// Good
+class DeviceManager {
+    constructor(
+        private notifier: NotificationService
+    ) {}
+
+    async getState() { /* ... */ }
+    async setState() { /* ... */ }
+}
+
+class NotificationService {
+    async send() { /* ... */ }
+}
+```
+
+## Error Handling
+
+### Best Practices
+
+1. Use custom error classes
+2. Include error codes
+3. Provide meaningful messages
+4. Include error context
+5. Handle async errors
+6. Log appropriately
+
+```typescript
+class DeviceError extends Error {
+    constructor(
+        message: string,
+        public code: string,
+        public context: Record<string, any>
+    ) {
+        super(message);
+        this.name = 'DeviceError';
+    }
+}
+
+try {
+    await device.connect();
+} catch (error) {
+    throw new DeviceError(
+        'Failed to connect to device',
+        'DEVICE_CONNECTION_ERROR',
+        { deviceId: device.id, attempt: 1 }
+    );
+}
+```
+
+## Testing
+
+### Guidelines
+
+1. Write unit tests first
+2. Use meaningful descriptions
+3. Test edge cases
+4. Mock external dependencies
+5. Keep tests focused
+6. Use test fixtures
+
+```typescript
+describe('DeviceManager', () => {
+    let manager: DeviceManager;
+    let mockDevice: jest.Mocked<Device>;
+
+    beforeEach(() => {
+        mockDevice = {
+            id: 'test_device',
+            getState: jest.fn()
+        };
+        manager = new DeviceManager(mockDevice);
+    });
+
+    it('should get device state', async () => {
+        mockDevice.getState.mockResolvedValue('on');
+        const state = await manager.getDeviceState();
+        expect(state).toBe('on');
+    });
+});
+```
+
+## Performance
+
+### Optimization
+
+1. Use caching
+2. Implement pagination
+3. Optimize database queries
+4. Use connection pooling
+5. Implement rate limiting
+6. Batch operations
+
+```typescript
+class DeviceCache {
+    private cache = new Map<string, CacheEntry>();
+    private readonly TTL = 60000;  // 1 minute
+
+    async getDevice(id: string): Promise<Device> {
+        const cached = this.cache.get(id);
+        if (cached && Date.now() - cached.timestamp < this.TTL) {
+            return cached.device;
+        }
+        
+        const device = await this.fetchDevice(id);
+        this.cache.set(id, {
+            device,
+            timestamp: Date.now()
+        });
+        
+        return device;
+    }
+}
+```
+
+## Security
+
+### Guidelines
+
+1. Validate all input
+2. Use parameterized queries
+3. Implement rate limiting
+4. Use proper authentication
+5. Follow OWASP guidelines
+6. Sanitize output
+
+```typescript
+class InputValidator {
+    static validateDeviceId(id: string): boolean {
+        return /^[a-zA-Z0-9_-]{1,64}$/.test(id);
+    }
+
+    static sanitizeOutput(data: any): any {
+        // Implement output sanitization
+        return data;
+    }
+}
+```
+
+## Documentation
+
+### Standards
+
+1. Use JSDoc comments
+2. Document interfaces
+3. Include examples
+4. Document errors
+5. Keep docs updated
+6. Use markdown
+
+```typescript
+/**
+ * Manages device operations.
+ * @class
+ */
+class DeviceManager {
+    /**
+     * Gets the current state of a device.
+     * @param {string} deviceId - The device identifier.
+     * @returns {Promise<DeviceState>} The current device state.
+     * @throws {DeviceError} If device is not found or unavailable.
+     * @example
+     * const state = await deviceManager.getDeviceState('living_room_light');
+     */
+    async getDeviceState(deviceId: string): Promise<DeviceState> {
+        // Implementation
+    }
+}
+```
+
+## Logging
+
+### Best Practices
+
+1. Use appropriate levels
+2. Include context
+3. Structure log data
+4. Handle sensitive data
+5. Implement rotation
+6. Use correlation IDs
+
+```typescript
+class Logger {
+    info(message: string, context: Record<string, any>) {
+        console.log(JSON.stringify({
+            level: 'info',
+            message,
+            context,
+            timestamp: new Date().toISOString(),
+            correlationId: context.correlationId
+        }));
+    }
+}
+```
+
+## Version Control
+
+### Guidelines
+
+1. Use meaningful commits
+2. Follow branching strategy
+3. Write good PR descriptions
+4. Review code thoroughly
+5. Keep changes focused
+6. Use conventional commits
+
+```bash
+# Good commit messages
+git commit -m "feat(device): add support for zigbee devices"
+git commit -m "fix(api): handle timeout errors properly"
+```
+
+## See Also
+
+- [Tool Development Guide](tools.md)
+- [Interface Documentation](interfaces.md)
+- [Testing Guide](../testing.md) 

docs/development/development.md

@@ -7,6 +7,8 @@ This guide provides information for developers who want to contribute to or exte
 ```
 homeassistant-mcp/
 ├── src/
+│   ├── __tests__/        # Test files
+│   ├── __mocks__/       # Mock files
 │   ├── api/           # API endpoints and route handlers
 │   ├── config/        # Configuration management
 │   ├── hass/         # Home Assistant integration

docs/development/interfaces.md

@@ -0,0 +1,296 @@
+# Interface Documentation
+
+This document describes the core interfaces used throughout the Home Assistant MCP.
+
+## Core Interfaces
+
+### Tool Interface
+
+```typescript
+interface Tool {
+    /** Unique identifier for the tool */
+    id: string;
+    
+    /** Human-readable name */
+    name: string;
+    
+    /** Detailed description */
+    description: string;
+    
+    /** Semantic version */
+    version: string;
+    
+    /** Tool category */
+    category: ToolCategory;
+    
+    /** Execute tool functionality */
+    execute(params: any): Promise<ToolResult>;
+}
+```
+
+### Tool Result
+
+```typescript
+interface ToolResult {
+    /** Operation success status */
+    success: boolean;
+    
+    /** Response data */
+    data?: any;
+    
+    /** Error message if failed */
+    message?: string;
+    
+    /** Error code if failed */
+    error_code?: string;
+}
+```
+
+### Tool Category
+
+```typescript
+enum ToolCategory {
+    DeviceManagement = 'device_management',
+    HistoryState = 'history_state',
+    Automation = 'automation',
+    AddonsPackages = 'addons_packages',
+    Notifications = 'notifications',
+    Events = 'events',
+    Utility = 'utility'
+}
+```
+
+## Event Interfaces
+
+### Event Subscription
+
+```typescript
+interface EventSubscription {
+    /** Unique subscription ID */
+    id: string;
+    
+    /** Event type to subscribe to */
+    event_type: string;
+    
+    /** Optional entity ID filter */
+    entity_id?: string;
+    
+    /** Optional domain filter */
+    domain?: string;
+    
+    /** Subscription creation timestamp */
+    created_at: string;
+    
+    /** Last event timestamp */
+    last_event?: string;
+}
+```
+
+### Event Message
+
+```typescript
+interface EventMessage {
+    /** Event type */
+    event_type: string;
+    
+    /** Entity ID if applicable */
+    entity_id?: string;
+    
+    /** Event data */
+    data: any;
+    
+    /** Event origin */
+    origin: 'LOCAL' | 'REMOTE';
+    
+    /** Event timestamp */
+    time_fired: string;
+    
+    /** Event context */
+    context: EventContext;
+}
+```
+
+## Device Interfaces
+
+### Device
+
+```typescript
+interface Device {
+    /** Device ID */
+    id: string;
+    
+    /** Device name */
+    name: string;
+    
+    /** Device domain */
+    domain: string;
+    
+    /** Current state */
+    state: string;
+    
+    /** Device attributes */
+    attributes: Record<string, any>;
+    
+    /** Device capabilities */
+    capabilities: DeviceCapabilities;
+}
+```
+
+### Device Capabilities
+
+```typescript
+interface DeviceCapabilities {
+    /** Supported features */
+    features: string[];
+    
+    /** Supported commands */
+    commands: string[];
+    
+    /** State attributes */
+    attributes: {
+        /** Attribute name */
+        [key: string]: {
+            /** Attribute type */
+            type: 'string' | 'number' | 'boolean' | 'object';
+            /** Attribute description */
+            description: string;
+            /** Optional value constraints */
+            constraints?: {
+                min?: number;
+                max?: number;
+                enum?: any[];
+            };
+        };
+    };
+}
+```
+
+## Authentication Interfaces
+
+### Auth Token
+
+```typescript
+interface AuthToken {
+    /** Token value */
+    token: string;
+    
+    /** Token type */
+    type: 'bearer' | 'jwt';
+    
+    /** Expiration timestamp */
+    expires_at: string;
+    
+    /** Token refresh info */
+    refresh?: {
+        token: string;
+        expires_at: string;
+    };
+}
+```
+
+### User
+
+```typescript
+interface User {
+    /** User ID */
+    id: string;
+    
+    /** Username */
+    username: string;
+    
+    /** User type */
+    type: 'admin' | 'user' | 'service';
+    
+    /** User permissions */
+    permissions: string[];
+}
+```
+
+## Error Interfaces
+
+### Tool Error
+
+```typescript
+interface ToolError extends Error {
+    /** Error code */
+    code: string;
+    
+    /** HTTP status code */
+    status: number;
+    
+    /** Error details */
+    details?: Record<string, any>;
+}
+```
+
+### Validation Error
+
+```typescript
+interface ValidationError {
+    /** Error path */
+    path: string;
+    
+    /** Error message */
+    message: string;
+    
+    /** Error code */
+    code: string;
+}
+```
+
+## Configuration Interfaces
+
+### Tool Configuration
+
+```typescript
+interface ToolConfig {
+    /** Enable/disable tool */
+    enabled: boolean;
+    
+    /** Tool-specific settings */
+    settings: Record<string, any>;
+    
+    /** Rate limiting */
+    rate_limit?: {
+        /** Max requests */
+        max: number;
+        /** Time window in seconds */
+        window: number;
+    };
+}
+```
+
+### System Configuration
+
+```typescript
+interface SystemConfig {
+    /** System name */
+    name: string;
+    
+    /** Environment */
+    environment: 'development' | 'production';
+    
+    /** Log level */
+    log_level: 'debug' | 'info' | 'warn' | 'error';
+    
+    /** Tool configurations */
+    tools: Record<string, ToolConfig>;
+}
+```
+
+## Best Practices
+
+1. Use TypeScript for all interfaces
+2. Include JSDoc comments
+3. Use strict typing
+4. Keep interfaces focused
+5. Use consistent naming
+6. Document constraints
+7. Version interfaces
+8. Include examples
+
+## See Also
+
+- [Tool Development Guide](tools.md)
+- [Best Practices](best-practices.md)
+- [Testing Guide](../testing.md) 

docs/development/test-migration-guide.md

@@ -0,0 +1,323 @@
+# Migrating Tests from Jest to Bun
+
+This guide provides instructions for migrating test files from Jest to Bun's test framework.
+
+## Table of Contents
+- [Basic Setup](#basic-setup)
+- [Import Changes](#import-changes)
+- [API Changes](#api-changes)
+- [Mocking](#mocking)
+- [Common Patterns](#common-patterns)
+- [Examples](#examples)
+
+## Basic Setup
+
+1. Remove Jest-related dependencies from `package.json`:
+```json
+{
+  "devDependencies": {
+    "@jest/globals": "...",
+    "jest": "...",
+    "ts-jest": "..."
+  }
+}
+```
+
+2. Remove Jest configuration files:
+- `jest.config.js`
+- `jest.setup.js`
+
+3. Update test scripts in `package.json`:
+```json
+{
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  }
+}
+```
+
+## Import Changes
+
+### Before (Jest):
+```typescript
+import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+```
+
+### After (Bun):
+```typescript
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import type { Mock } from "bun:test";
+```
+
+Note: `it` is replaced with `test` in Bun.
+
+## API Changes
+
+### Test Structure
+```typescript
+// Jest
+describe('Suite', () => {
+  it('should do something', () => {
+    // test
+  });
+});
+
+// Bun
+describe('Suite', () => {
+  test('should do something', () => {
+    // test
+  });
+});
+```
+
+### Assertions
+Most Jest assertions work the same in Bun:
+
+```typescript
+// These work the same in both:
+expect(value).toBe(expected);
+expect(value).toEqual(expected);
+expect(value).toBeDefined();
+expect(value).toBeUndefined();
+expect(value).toBeTruthy();
+expect(value).toBeFalsy();
+expect(array).toContain(item);
+expect(value).toBeInstanceOf(Class);
+expect(spy).toHaveBeenCalled();
+expect(spy).toHaveBeenCalledWith(...args);
+```
+
+## Mocking
+
+### Function Mocking
+
+#### Before (Jest):
+```typescript
+const mockFn = jest.fn();
+mockFn.mockImplementation(() => 'result');
+mockFn.mockResolvedValue('result');
+mockFn.mockRejectedValue(new Error());
+```
+
+#### After (Bun):
+```typescript
+const mockFn = mock(() => 'result');
+const mockAsyncFn = mock(() => Promise.resolve('result'));
+const mockErrorFn = mock(() => Promise.reject(new Error()));
+```
+
+### Module Mocking
+
+#### Before (Jest):
+```typescript
+jest.mock('module-name', () => ({
+  default: jest.fn(),
+  namedExport: jest.fn()
+}));
+```
+
+#### After (Bun):
+```typescript
+// Option 1: Using vi.mock (if available)
+vi.mock('module-name', () => ({
+  default: mock(() => {}),
+  namedExport: mock(() => {})
+}));
+
+// Option 2: Using dynamic imports
+const mockModule = {
+  default: mock(() => {}),
+  namedExport: mock(() => {})
+};
+```
+
+### Mock Reset/Clear
+
+#### Before (Jest):
+```typescript
+jest.clearAllMocks();
+mockFn.mockClear();
+jest.resetModules();
+```
+
+#### After (Bun):
+```typescript
+mockFn.mockReset();
+// or for specific calls
+mockFn.mock.calls = [];
+```
+
+### Spy on Methods
+
+#### Before (Jest):
+```typescript
+jest.spyOn(object, 'method');
+```
+
+#### After (Bun):
+```typescript
+const spy = mock(((...args) => object.method(...args)));
+object.method = spy;
+```
+
+## Common Patterns
+
+### Async Tests
+```typescript
+// Works the same in both Jest and Bun:
+test('async test', async () => {
+  const result = await someAsyncFunction();
+  expect(result).toBe(expected);
+});
+```
+
+### Setup and Teardown
+```typescript
+describe('Suite', () => {
+  beforeEach(() => {
+    // setup
+  });
+
+  afterEach(() => {
+    // cleanup
+  });
+
+  test('test', () => {
+    // test
+  });
+});
+```
+
+### Mocking Fetch
+```typescript
+// Before (Jest)
+global.fetch = jest.fn(() => Promise.resolve(new Response()));
+
+// After (Bun)
+const mockFetch = mock(() => Promise.resolve(new Response()));
+global.fetch = mockFetch as unknown as typeof fetch;
+```
+
+### Mocking WebSocket
+```typescript
+// Create a MockWebSocket class implementing WebSocket interface
+class MockWebSocket implements WebSocket {
+  public static readonly CONNECTING = 0;
+  public static readonly OPEN = 1;
+  public static readonly CLOSING = 2;
+  public static readonly CLOSED = 3;
+
+  public readyState: 0 | 1 | 2 | 3 = MockWebSocket.OPEN;
+  public addEventListener = mock(() => undefined);
+  public removeEventListener = mock(() => undefined);
+  public send = mock(() => undefined);
+  public close = mock(() => undefined);
+  // ... implement other required methods
+}
+
+// Use it in tests
+global.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+```
+
+## Examples
+
+### Basic Test
+```typescript
+import { describe, expect, test } from "bun:test";
+
+describe('formatToolCall', () => {
+  test('should format an object into the correct structure', () => {
+    const testObj = { name: 'test', value: 123 };
+    const result = formatToolCall(testObj);
+
+    expect(result).toEqual({
+      content: [{
+        type: 'text',
+        text: JSON.stringify(testObj, null, 2),
+        isError: false
+      }]
+    });
+  });
+});
+```
+
+### Async Test with Mocking
+```typescript
+import { describe, expect, test, mock } from "bun:test";
+
+describe('API Client', () => {
+  test('should fetch data', async () => {
+    const mockResponse = { data: 'test' };
+    const mockFetch = mock(() => Promise.resolve(new Response(
+      JSON.stringify(mockResponse),
+      { status: 200, headers: new Headers() }
+    )));
+    global.fetch = mockFetch as unknown as typeof fetch;
+
+    const result = await apiClient.getData();
+    expect(result).toEqual(mockResponse);
+  });
+});
+```
+
+### Complex Mocking Example
+```typescript
+import { describe, expect, test, mock } from "bun:test";
+import type { Mock } from "bun:test";
+
+interface MockServices {
+  light: {
+    turn_on: Mock<() => Promise<{ success: boolean }>>;
+    turn_off: Mock<() => Promise<{ success: boolean }>>;
+  };
+}
+
+const mockServices: MockServices = {
+  light: {
+    turn_on: mock(() => Promise.resolve({ success: true })),
+    turn_off: mock(() => Promise.resolve({ success: true }))
+  }
+};
+
+describe('Home Assistant Service', () => {
+  test('should control lights', async () => {
+    const result = await mockServices.light.turn_on();
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+## Best Practices
+
+1. Use TypeScript for better type safety in mocks
+2. Keep mocks as simple as possible
+3. Prefer interface-based mocks over concrete implementations
+4. Use proper type assertions when necessary
+5. Clean up mocks in `afterEach` blocks
+6. Use descriptive test names
+7. Group related tests using `describe` blocks
+
+## Common Issues and Solutions
+
+### Issue: Type Errors with Mocks
+```typescript
+// Solution: Use proper typing with Mock type
+import type { Mock } from "bun:test";
+const mockFn: Mock<() => string> = mock(() => "result");
+```
+
+### Issue: Global Object Mocking
+```typescript
+// Solution: Use type assertions carefully
+global.someGlobal = mockImplementation as unknown as typeof someGlobal;
+```
+
+### Issue: Module Mocking
+```typescript
+// Solution: Use dynamic imports or vi.mock if available
+const mockModule = {
+  default: mock(() => mockImplementation)
+};
+``` 

docs/development/tools.md

@@ -0,0 +1,226 @@
+# Tool Development Guide
+
+This guide explains how to create new tools for the Home Assistant MCP.
+
+## Tool Structure
+
+Each tool should follow this basic structure:
+
+```typescript
+interface Tool {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    category: ToolCategory;
+    execute(params: any): Promise<ToolResult>;
+}
+```
+
+## Creating a New Tool
+
+1. Create a new file in the appropriate category directory
+2. Implement the Tool interface
+3. Add API endpoints
+4. Add WebSocket handlers
+5. Add documentation
+6. Add tests
+
+### Example Tool Implementation
+
+```typescript
+import { Tool, ToolCategory, ToolResult } from '../interfaces';
+
+export class MyCustomTool implements Tool {
+    id = 'my_custom_tool';
+    name = 'My Custom Tool';
+    description = 'Description of what the tool does';
+    version = '1.0.0';
+    category = ToolCategory.Utility;
+
+    async execute(params: any): Promise<ToolResult> {
+        // Tool implementation
+        return {
+            success: true,
+            data: {
+                // Tool-specific response data
+            }
+        };
+    }
+}
+```
+
+## Tool Categories
+
+- Device Management
+- History & State
+- Automation
+- Add-ons & Packages
+- Notifications
+- Events
+- Utility
+
+## API Integration
+
+### REST Endpoint
+
+```typescript
+import { Router } from 'express';
+import { MyCustomTool } from './my-custom-tool';
+
+const router = Router();
+const tool = new MyCustomTool();
+
+router.post('/api/tools/custom', async (req, res) => {
+    try {
+        const result = await tool.execute(req.body);
+        res.json(result);
+    } catch (error) {
+        res.status(500).json({
+            success: false,
+            message: error.message
+        });
+    }
+});
+```
+
+### WebSocket Handler
+
+```typescript
+import { WebSocketServer } from 'ws';
+import { MyCustomTool } from './my-custom-tool';
+
+const tool = new MyCustomTool();
+
+wss.on('connection', (ws) => {
+    ws.on('message', async (message) => {
+        const { type, params } = JSON.parse(message);
+        if (type === 'my_custom_tool') {
+            const result = await tool.execute(params);
+            ws.send(JSON.stringify(result));
+        }
+    });
+});
+```
+
+## Error Handling
+
+```typescript
+class ToolError extends Error {
+    constructor(
+        message: string,
+        public code: string,
+        public status: number = 500
+    ) {
+        super(message);
+        this.name = 'ToolError';
+    }
+}
+
+// Usage in tool
+async execute(params: any): Promise<ToolResult> {
+    try {
+        // Tool implementation
+    } catch (error) {
+        throw new ToolError(
+            'Operation failed',
+            'TOOL_ERROR',
+            500
+        );
+    }
+}
+```
+
+## Testing
+
+```typescript
+import { MyCustomTool } from './my-custom-tool';
+
+describe('MyCustomTool', () => {
+    let tool: MyCustomTool;
+
+    beforeEach(() => {
+        tool = new MyCustomTool();
+    });
+
+    it('should execute successfully', async () => {
+        const result = await tool.execute({
+            // Test parameters
+        });
+        expect(result.success).toBe(true);
+    });
+
+    it('should handle errors', async () => {
+        // Error test cases
+    });
+});
+```
+
+## Documentation
+
+1. Create tool documentation in `docs/tools/category/tool-name.md`
+2. Update `tools/tools.md` with tool reference
+3. Add tool to navigation in `mkdocs.yml`
+
+### Documentation Template
+
+```markdown
+# Tool Name
+
+Description of the tool.
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Usage
+
+### REST API
+
+```typescript
+// API endpoints
+```
+
+### WebSocket
+
+```typescript
+// WebSocket usage
+```
+
+## Examples
+
+### Example 1
+
+```typescript
+// Usage example
+```
+
+## Response Format
+
+```json
+{
+    "success": true,
+    "data": {
+        // Response data structure
+    }
+}
+```
+```
+
+## Best Practices
+
+1. Follow consistent naming conventions
+2. Implement proper error handling
+3. Add comprehensive documentation
+4. Write thorough tests
+5. Use TypeScript for type safety
+6. Follow SOLID principles
+7. Implement rate limiting
+8. Add proper logging
+
+## See Also
+
+- [Interface Documentation](interfaces.md)
+- [Best Practices](best-practices.md)
+- [Testing Guide](../testing.md) 

docs/examples/index.md

@@ -0,0 +1,22 @@
+---
+layout: default
+title: Examples
+nav_order: 7
+has_children: true
+---
+
+# Example Projects 📚
+
+This section contains examples and tutorials for common MCP Server integrations.
+
+## Speech-to-Text Integration
+
+Example of integrating speech recognition with MCP Server:
+
+```typescript
+// From examples/speech-to-text-example.ts
+// Add example code and explanation
+```
+
+## More Examples Coming Soon
+... 

docs/getting-started.md

@@ -1,122 +1,30 @@
-# Getting Started with Home Assistant MCP
+# Getting Started
 
-This guide will help you get started with the Home Assistant MCP (Master Control Program).
+Begin your journey with the Home Assistant MCP Server by following these steps:
 
-## Prerequisites
+- **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.
-Before you begin, ensure you have:
+- **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.
-1. Node.js (v16 or higher)
-2. A running Home Assistant instance
-3. A Home Assistant Long-Lived Access Token
-
-## Installation
-
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/yourusername/homeassistant-mcp.git
-   cd homeassistant-mcp
-   ```
-
-2. Install dependencies:
-   ```bash
-   npm install
-   ```
-
-3. Copy the example environment file:
-   ```bash
-   cp .env.example .env
-   ```
-
-4. Edit the `.env` file with your configuration:
-   ```env
-   # Server Configuration
-   PORT=3000
-   NODE_ENV=development
-
-   # Home Assistant Configuration
-   HASS_HOST=http://your-hass-instance:8123
-   HASS_TOKEN=your-long-lived-access-token
-
-   # Security Configuration
-   JWT_SECRET=your-secret-key
-   ```
-
-## Configuration
-
-### Environment Variables
-
-- `PORT`: The port number for the MCP server (default: 3000)
-- `NODE_ENV`: The environment mode (development, production, test)
-- `HASS_HOST`: Your Home Assistant instance URL
-- `HASS_TOKEN`: Your Home Assistant Long-Lived Access Token
-- `JWT_SECRET`: Secret key for JWT token generation
-
-### Development Mode
-
-For development, you can use:
-
-```bash
-npm run dev
-```
-
-This will start the server in development mode with hot reloading.
-
-### Production Mode
-
-For production, build and start the server:
-
-```bash
-npm run build
-npm start
-```
-
-## First Steps
-
-1. Check the server is running:
-   ```bash
-   curl http://localhost:3000/api/health
-   ```
-
-2. List available devices:
-   ```bash
-   curl -H "Authorization: Bearer your-token" http://localhost:3000/api/tools/devices
-   ```
-
-3. Subscribe to events:
-   ```bash
-   curl -H "Authorization: Bearer your-token" http://localhost:3000/api/sse/subscribe?events=state_changed
-   ```
-
-## Next Steps
-
-- Read the [API Documentation](./API.md) for available endpoints
-- Learn about [Server-Sent Events](./SSE_API.md) for real-time updates
-- Explore available [Tools](./tools/README.md) for device control
-- Check the [Configuration Guide](./configuration/README.md) for advanced settings
 
 ## Troubleshooting
 
-If you encounter issues:
+If you encounter any issues:
-
+1. Verify that your Home Assistant instance is accessible.
-1. Verify your Home Assistant instance is accessible
+2. Ensure that all required environment variables are properly set.
-2. Check your environment variables are correctly set
+3. Consult the [Troubleshooting Guide](troubleshooting.md) for additional solutions.
-3. Look for errors in the server logs
-4. Consult the [Troubleshooting Guide](./troubleshooting.md)
 
 ## Development
 
-For development and contributing:
+For contributors:
-
+1. Fork the repository.
-1. Fork the repository
+2. Create a feature branch.
-2. Create a feature branch
+3. Follow the [Development Guide](development/development.md) for contribution guidelines.
-3. Follow the [Development Guide](./development/README.md)
+4. Submit a pull request with your enhancements.
-4. Submit a pull request
 
 ## Support
 
-Need help? Check out:
+Need help?
-
+- Visit our [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues).
-- [GitHub Issues](https://github.com/yourusername/homeassistant-mcp/issues)
+- Review the [Troubleshooting Guide](troubleshooting.md).
-- [Troubleshooting Guide](./troubleshooting.md)
+- Check the [FAQ](troubleshooting.md#faq) for common questions. 
-- [FAQ](./troubleshooting.md#faq) 

docs/getting-started/configuration.md

@@ -0,0 +1,5 @@
+# Configuration
+
+## Basic Configuration
+
+## Advanced Settings 

docs/getting-started/docker.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: Docker Deployment
+parent: Getting Started
+nav_order: 3
+---
+
+# Docker Deployment Guide 🐳
+
+Detailed guide for deploying MCP Server with Docker... 

docs/getting-started/installation.md

@@ -0,0 +1,181 @@
+---
+layout: default
+title: Installation
+parent: Getting Started
+nav_order: 1
+---
+
+# Installation Guide 🛠️
+
+This guide covers different methods to install and set up the MCP Server for Home Assistant. Choose the installation method that best suits your needs.
+
+## Prerequisites
+
+Before installing MCP Server, ensure you have:
+
+- Home Assistant instance running and accessible
+- Node.js 18+ or Docker installed
+- Home Assistant Long-Lived Access Token ([How to get one](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token))
+
+## Installation Methods
+
+### 1. 🔧 Smithery Installation (Recommended)
+
+The easiest way to install MCP Server is through Smithery:
+
+#### Smithery Configuration
+
+The project includes a `smithery.yaml` configuration:
+
+```yaml
+# Add smithery.yaml contents and explanation
+```
+
+#### Installation Steps
+
+```bash
+npx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude
+```
+
+### 2. 🐳 Docker Installation
+
+For a containerized deployment:
+
+```bash
+# Clone the repository
+git clone --depth 1 https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
+cd advanced-homeassistant-mcp
+
+# Configure environment variables
+cp .env.example .env
+# Edit .env with your Home Assistant details:
+# - HA_URL: Your Home Assistant URL
+# - HA_TOKEN: Your Long-Lived Access Token
+# - Other configuration options
+
+# Build and start containers
+docker compose up -d --build
+
+# View logs (optional)
+docker compose logs -f --tail=50
+```
+
+### 3. 💻 Manual Installation
+
+For direct installation on your system:
+
+```bash
+# Install Bun runtime
+curl -fsSL https://bun.sh/install | bash
+
+# Clone and install
+git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
+cd advanced-homeassistant-mcp
+bun install --frozen-lockfile
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your configuration
+
+# Start the server
+bun run dev --watch
+```
+
+## Configuration
+
+### Environment Variables
+
+Key configuration options in your `.env` file:
+
+```env
+# Home Assistant Configuration
+HA_URL=http://your-homeassistant:8123
+HA_TOKEN=your_long_lived_access_token
+
+# Server Configuration
+PORT=3000
+HOST=0.0.0.0
+NODE_ENV=production
+
+# Security Settings
+JWT_SECRET=your_secure_jwt_secret
+RATE_LIMIT=100
+```
+
+### Client Integration
+
+#### Cursor Integration
+
+Add to `.cursor/config/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "homeassistant-mcp": {
+      "command": "bun",
+      "args": ["run", "start"],
+      "cwd": "${workspaceRoot}",
+      "env": {
+        "NODE_ENV": "development"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop Integration
+
+Add to your Claude configuration:
+
+```json
+{
+  "mcpServers": {
+    "homeassistant-mcp": {
+      "command": "bun",
+      "args": ["run", "start", "--port", "8080"],
+      "env": {
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}
+```
+
+## Verification
+
+To verify your installation:
+
+1. Check server status:
+   ```bash
+   curl http://localhost:3000/health
+   ```
+
+2. Test Home Assistant connection:
+   ```bash
+   curl http://localhost:3000/api/state
+   ```
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Check the [Troubleshooting Guide](../troubleshooting.md)
+2. Verify your environment variables
+3. Check server logs:
+   ```bash
+   # For Docker installation
+   docker compose logs -f
+   
+   # For manual installation
+   bun run dev
+   ```
+
+## Next Steps
+
+- Follow the [Quick Start Guide](quickstart.md) to begin using MCP Server
+- Read the [API Documentation](../api/index.md) for integration details
+- Check the [Architecture Overview](../architecture.md) to understand the system
+
+## Support
+
+Need help? Check our [Support Resources](../index.md#support) or [open an issue](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues). 

docs/getting-started/quickstart.md

@@ -0,0 +1,219 @@
+---
+layout: default
+title: Quick Start
+parent: Getting Started
+nav_order: 2
+---
+
+# Quick Start Guide 🚀
+
+This guide will help you get started with MCP Server after installation. We'll cover basic usage, common commands, and simple integrations.
+
+## First Steps
+
+### 1. Verify Connection
+
+After installation, verify your MCP Server is running and connected to Home Assistant:
+
+```bash
+# Check server health
+curl http://localhost:3000/health
+
+# Verify Home Assistant connection
+curl http://localhost:3000/api/state
+```
+
+### 2. Basic Voice Commands
+
+Try these basic voice commands to test your setup:
+
+```bash
+# Example using curl for testing
+curl -X POST http://localhost:3000/api/command \
+  -H "Content-Type: application/json" \
+  -d '{"command": "Turn on the living room lights"}'
+```
+
+Common voice commands:
+- "Turn on/off [device name]"
+- "Set [device] to [value]"
+- "What's the temperature in [room]?"
+- "Is [device] on or off?"
+
+## Real-World Examples
+
+### 1. Smart Lighting Control
+
+```javascript
+// Browser example using fetch
+const response = await fetch('http://localhost:3000/api/command', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    command: 'Set living room lights to 50% brightness and warm white color'
+  })
+});
+```
+
+### 2. Real-Time Updates
+
+Subscribe to device state changes using Server-Sent Events (SSE):
+
+```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('Device state changed:', data);
+    // Update your UI here
+};
+```
+
+### 3. Scene Automation
+
+Create and trigger scenes for different activities:
+
+```javascript
+// Create a "Movie Night" scene
+const createScene = async () => {
+  await fetch('http://localhost:3000/api/scene', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      name: 'Movie Night',
+      actions: [
+        { device: 'living_room_lights', action: 'dim', value: 20 },
+        { device: 'tv', action: 'on' },
+        { device: 'soundbar', action: 'on' }
+      ]
+    })
+  });
+};
+
+// Trigger the scene with voice command:
+// "Hey MCP, activate movie night scene"
+```
+
+## Integration Examples
+
+### 1. Web Dashboard Integration
+
+```javascript
+// React component example
+function SmartHomeControl() {
+    const [devices, setDevices] = useState([]);
+    
+    useEffect(() => {
+        // Subscribe to device updates
+        const events = new EventSource('http://localhost:3000/subscribe_events');
+        events.onmessage = (event) => {
+            const data = JSON.parse(event.data);
+            setDevices(currentDevices => 
+                currentDevices.map(device => 
+                    device.id === data.id ? {...device, ...data} : device
+                )
+            );
+        };
+        
+        return () => events.close();
+    }, []);
+
+    return (
+        <div className="dashboard">
+            {devices.map(device => (
+                <DeviceCard key={device.id} device={device} />
+            ))}
+        </div>
+    );
+}
+```
+
+### 2. Voice Assistant Integration
+
+```typescript
+// Example using speech-to-text with MCP
+async function handleVoiceCommand(audioBlob: Blob) {
+    // First, convert speech to text
+    const text = await speechToText(audioBlob);
+    
+    // Then send command to MCP
+    const response = await fetch('http://localhost:3000/api/command', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ command: text })
+    });
+    
+    return response.json();
+}
+```
+
+## Best Practices
+
+1. **Error Handling**
+   ```javascript
+   try {
+       const response = await fetch('http://localhost:3000/api/command', {
+           method: 'POST',
+           headers: {
+               'Content-Type': 'application/json',
+           },
+           body: JSON.stringify({ command: 'Turn on lights' })
+       });
+       
+       if (!response.ok) {
+           throw new Error(`HTTP error! status: ${response.status}`);
+       }
+       
+       const data = await response.json();
+   } catch (error) {
+       console.error('Error:', error);
+       // Handle error appropriately
+   }
+   ```
+
+2. **Connection Management**
+   ```javascript
+   class MCPConnection {
+       constructor() {
+           this.eventSource = null;
+           this.reconnectAttempts = 0;
+       }
+       
+       connect() {
+           this.eventSource = new EventSource('http://localhost:3000/subscribe_events');
+           this.eventSource.onerror = this.handleError.bind(this);
+       }
+       
+       handleError() {
+           if (this.reconnectAttempts < 3) {
+               setTimeout(() => {
+                   this.reconnectAttempts++;
+                   this.connect();
+               }, 1000 * this.reconnectAttempts);
+           }
+       }
+   }
+   ```
+
+## Next Steps
+
+- Explore the [API Documentation](../api/index.md) for advanced features
+- Learn about [SSE API](../api/sse.md) for real-time updates
+- Check out [Architecture](../architecture.md) for system design details
+- Read the [Contributing Guide](../contributing.md) to get involved
+
+## Troubleshooting
+
+If you encounter issues:
+- Verify your authentication token
+- Check server logs for errors
+- Ensure Home Assistant is accessible
+- Review the [Troubleshooting Guide](../troubleshooting.md)
+
+Need more help? Visit our [Support Resources](../index.md#support). 

docs/index.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: Home
+nav_order: 1
+---
+
+# 🚀 MCP Server for Home Assistant
+
+Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating AI-powered natural language processing into your Home Assistant setup.
+
+## 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.
+
+## 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
+
+### 🛡️ Security & Performance
+- JWT authentication
+- Request sanitization
+- Sub-100ms latency
+- Rate limiting
+
+## Documentation Structure
+
+### Getting Started
+- [Installation Guide](getting-started/installation.md) - Set up MCP Server
+- [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
+- [Contributing Guidelines](contributing.md) - How to contribute
+- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
+
+## Support
+
+If you 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)
+
+## 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. 

docs/roadmap.md

@@ -0,0 +1,51 @@
+# 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.
+
+## 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.
+
+- **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.
+
+- **Performance Optimizations:**
+  - Refine resource utilization to reduce latency.
+  - Optimize real-time data streaming via SSE.
+  - Introduce advanced caching mechanisms for frequently requested data.
+
+## Mid-Term Goals
+
+- **User Interface Improvements:**
+  - Develop an intuitive web-based dashboard for device management and monitoring.
+  - Provide real-time analytics and performance metrics.
+
+- **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.
+
+## 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.
+
+- **Scalability and Resilience:**
+  - Architect the system to support large-scale deployments.
+  - Incorporate advanced load balancing and failover mechanisms.
+
+## 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.
+
+*This roadmap is intended as a guide and may evolve based on community needs, technological advancements, and strategic priorities.* 

docs/testing.md

@@ -0,0 +1,422 @@
+# Testing Documentation
+
+## Quick Reference
+
+```bash
+# Most Common Commands
+bun test                    # Run all tests
+bun test --watch           # Run tests in watch mode
+bun test --coverage        # Run tests with coverage
+bun test path/to/test.ts   # Run a specific test file
+
+# Additional Options
+DEBUG=true bun test        # Run with debug output
+bun test --pattern "auth"  # Run tests matching a pattern
+bun test --timeout 60000   # Run with a custom timeout
+```
+
+## Overview
+
+This document describes the testing setup and practices used in the Home Assistant MCP project. We use Bun's test runner for both unit and integration testing, ensuring comprehensive coverage across modules.
+
+## Test Structure
+
+Tests are organized in two main locations:
+
+1. **Root Level Integration Tests** (`/__tests__/`):
+
+```
+__tests__/
+├── ai/              # AI/ML component tests
+├── api/             # API integration tests
+├── context/         # Context management tests
+├── hass/            # Home Assistant integration tests
+├── schemas/         # Schema validation tests
+├── security/        # Security integration tests
+├── tools/           # Tools and utilities tests
+├── websocket/       # WebSocket integration tests
+├── helpers.test.ts  # Helper function tests
+├── index.test.ts    # Main application tests
+└── server.test.ts   # Server integration tests
+```
+
+2. **Component Level Unit Tests** (`src/**/`):
+
+```
+src/
+├── __tests__/   # Global test setup and utilities
+│   └── setup.ts # Global test configuration
+├── component/
+│   ├── __tests__/   # Component-specific unit tests
+│   └── component.ts
+```
+
+## Test Configuration
+
+### Bun Test Configuration (`bunfig.toml`)
+
+```toml
+[test]
+preload = ["./src/__tests__/setup.ts"]  # Global test setup
+coverage = true                         # Enable coverage by default
+timeout = 30000                         # Test timeout in milliseconds
+testMatch = ["**/__tests__/**/*.test.ts"] # Test file patterns
+```
+
+### Bun Scripts
+
+Available test commands in `package.json`:
+
+```bash
+# Run all tests
+bun test
+
+# Watch mode for development
+bun test --watch
+
+# Generate coverage report
+bun test --coverage
+
+# Run linting
+bun run lint
+
+# Format code
+bun run format
+```
+
+## Test Setup
+
+### Global Configuration
+
+A global test setup file (`src/__tests__/setup.ts`) provides:
+- Environment configuration
+- Mock utilities
+- Test helper functions
+- Global lifecycle hooks
+
+### Test Environment
+
+- Environment variables are loaded from `.env.test`.
+- Console output is minimized unless `DEBUG=true`.
+- JWT secrets and tokens are preconfigured for testing.
+- Rate limiting and security features are initialized appropriately.
+
+## Running Tests
+
+```bash
+# Basic test run
+bun test
+
+# Run tests with coverage
+bun test --coverage
+
+# Run a specific test file
+bun test path/to/test.test.ts
+
+# Run tests in watch mode
+bun test --watch
+
+# Run tests with debug output
+DEBUG=true bun test
+
+# Run tests with increased timeout
+bun test --timeout 60000
+
+# Run tests matching a pattern
+bun test --pattern "auth"
+```
+
+## Advanced Debugging
+
+### Using Node Inspector
+
+```bash
+# Start tests with inspector
+bun test --inspect
+
+# Start tests with inspector and break on first line
+bun test --inspect-brk
+```
+
+### Using VS Code
+
+Create a launch configuration in `.vscode/launch.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "bun",
+      "request": "launch",
+      "name": "Debug Tests",
+      "program": "${workspaceFolder}/node_modules/bun/bin/bun",
+      "args": ["test", "${file}"],
+      "cwd": "${workspaceFolder}",
+      "env": { "DEBUG": "true" }
+    }
+  ]
+}
+```
+
+### Test Isolation
+
+To run a single test in isolation:
+
+```typescript
+describe.only("specific test suite", () => {
+  it.only("specific test case", () => {
+    // Only this test will run
+  });
+});
+```
+
+## Writing Tests
+
+### Test File Naming
+
+- Place test files in a `__tests__` directory adjacent to the code being tested.
+- Name files with the pattern `*.test.ts`.
+- Mirror the structure of the source code in your test organization.
+
+### Example Test Structure
+
+```typescript
+describe("Security Features", () => {
+  it("should validate tokens correctly", () => {
+    const payload = { userId: "123", role: "user" };
+    const token = jwt.sign(payload, validSecret, { expiresIn: "1h" });
+    const result = TokenManager.validateToken(token, testIp);
+    expect(result.valid).toBe(true);
+  });
+});
+```
+
+## Coverage
+
+The project maintains strict coverage:
+- Overall coverage: at least 80%
+- Critical paths: 90%+
+- New features: ≥85% coverage
+
+Generate a coverage report with:
+
+```bash
+bun test --coverage
+```
+
+## Security Middleware Testing
+
+### Utility Function Testing
+
+The security middleware now uses a utility-first approach, which allows for more granular and comprehensive testing. Each security function is now independently testable, improving code reliability and maintainability.
+
+#### Key Utility Functions
+
+1. **Rate Limiting (`checkRateLimit`)**
+   - Tests multiple scenarios:
+     - Requests under threshold
+     - Requests exceeding threshold
+     - Rate limit reset after window expiration
+   
+   ```typescript
+   // Example test
+   it('should throw when requests exceed threshold', () => {
+     const ip = '127.0.0.2';
+     for (let i = 0; i < 11; i++) {
+       if (i < 10) {
+         expect(() => checkRateLimit(ip, 10)).not.toThrow();
+       } else {
+         expect(() => checkRateLimit(ip, 10)).toThrow('Too many requests from this IP');
+       }
+     }
+   });
+   ```
+
+2. **Request Validation (`validateRequestHeaders`)**
+   - Tests content type validation
+   - Checks request size limits
+   - Validates authorization headers
+   
+   ```typescript
+   it('should reject invalid content type', () => {
+     const mockRequest = new Request('http://localhost', {
+       method: 'POST',
+       headers: { 'content-type': 'text/plain' }
+     });
+     expect(() => validateRequestHeaders(mockRequest)).toThrow('Content-Type must be application/json');
+   });
+   ```
+
+3. **Input Sanitization (`sanitizeValue`)**
+   - Sanitizes HTML tags
+   - Handles nested objects
+   - Preserves non-string values
+   
+   ```typescript
+   it('should sanitize HTML tags', () => {
+     const input = '<script>alert("xss")</script>Hello';
+     const sanitized = sanitizeValue(input);
+     expect(sanitized).toBe('&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;Hello');
+   });
+   ```
+
+4. **Security Headers (`applySecurityHeaders`)**
+   - Verifies correct security header application
+   - Checks CSP, frame options, and other security headers
+   
+   ```typescript
+   it('should apply security headers', () => {
+     const mockRequest = new Request('http://localhost');
+     const headers = applySecurityHeaders(mockRequest);
+     expect(headers['content-security-policy']).toBeDefined();
+     expect(headers['x-frame-options']).toBeDefined();
+   });
+   ```
+
+5. **Error Handling (`handleError`)**
+   - Tests error responses in production and development modes
+   - Verifies error message and stack trace inclusion
+   
+   ```typescript
+   it('should include error details in development mode', () => {
+     const error = new Error('Test error');
+     const result = handleError(error, 'development');
+     expect(result).toEqual({
+       error: true,
+       message: 'Internal server error',
+       error: 'Test error',
+       stack: expect.any(String)
+     });
+   });
+   ```
+
+### Testing Philosophy
+
+- **Isolation**: Each utility function is tested independently
+- **Comprehensive Coverage**: Multiple scenarios for each function
+- **Predictable Behavior**: Clear expectations for input and output
+- **Error Handling**: Robust testing of error conditions
+
+### Best Practices
+
+1. Use minimal, focused test cases
+2. Test both successful and failure scenarios
+3. Verify input sanitization and security measures
+4. Mock external dependencies when necessary
+
+### Running Security Tests
+
+```bash
+# Run all tests
+bun test
+
+# Run specific security tests
+bun test __tests__/security/
+```
+
+### Continuous Improvement
+
+- Regularly update test cases
+- Add new test scenarios as security requirements evolve
+- Perform periodic security audits
+
+## Best Practices
+
+1. **Isolation**: Each test should be independent and not rely on the state of other tests.
+2. **Mocking**: Use the provided mock utilities for external dependencies.
+3. **Cleanup**: Clean up any resources or state modifications in `afterEach` or `afterAll` hooks.
+4. **Descriptive Names**: Use clear, descriptive test names that explain the expected behavior.
+5. **Assertions**: Make specific, meaningful assertions rather than general ones.
+6. **Setup**: Use `beforeEach` for common test setup to avoid repetition.
+7. **Error Cases**: Test both success and error cases for complete coverage.
+
+## Coverage
+
+The project aims for high test coverage, particularly focusing on:
+- Security-critical code paths
+- API endpoints
+- Data validation
+- Error handling
+- Event broadcasting
+
+Run coverage reports using:
+```bash
+bun test --coverage
+```
+
+## Debugging Tests
+
+To debug tests:
+1. Set `DEBUG=true` to enable console output during tests
+2. Use the `--watch` flag for development
+3. Add `console.log()` statements (they're only shown when DEBUG is true)
+4. Use the test utilities' debugging helpers
+
+### Advanced Debugging
+
+1. **Using Node Inspector**:
+   ```bash
+   # Start tests with inspector
+   bun test --inspect
+   
+   # Start tests with inspector and break on first line
+   bun test --inspect-brk
+   ```
+
+2. **Using VS Code**:
+   ```jsonc
+   // .vscode/launch.json
+   {
+     "version": "0.2.0",
+     "configurations": [
+       {
+         "type": "bun",
+         "request": "launch",
+         "name": "Debug Tests",
+         "program": "${workspaceFolder}/node_modules/bun/bin/bun",
+         "args": ["test", "${file}"],
+         "cwd": "${workspaceFolder}",
+         "env": { "DEBUG": "true" }
+       }
+     ]
+   }
+   ```
+
+3. **Test Isolation**:
+   To run a single test in isolation:
+   ```typescript
+   describe.only("specific test suite", () => {
+     it.only("specific test case", () => {
+       // Only this test will run
+     });
+   });
+   ```
+
+## Contributing
+
+When contributing new code:
+1. Add tests for new features
+2. Ensure existing tests pass
+3. Maintain or improve coverage
+4. Follow the existing test patterns and naming conventions
+5. Document any new test utilities or patterns 
+
+## Coverage Requirements
+
+The project maintains strict coverage requirements:
+
+- Minimum overall coverage: 80%
+- Critical paths (security, API, data validation): 90%
+- New features must include tests with >= 85% coverage
+
+Coverage reports are generated in multiple formats:
+- Console summary
+- HTML report (./coverage/index.html)
+- LCOV report (./coverage/lcov.info)
+
+To view detailed coverage:
+```bash
+# Generate and open coverage report
+bun test --coverage && open coverage/index.html
+``` 

docs/tools/addons-packages/addon.md

@@ -0,0 +1,240 @@
+# Add-on Management Tool
+
+The Add-on Management tool provides functionality to manage Home Assistant add-ons through the MCP interface.
+
+## Features
+
+- List available add-ons
+- Install/uninstall add-ons
+- Start/stop/restart add-ons
+- Get add-on information
+- Update add-ons
+- Configure add-ons
+- View add-on logs
+- Monitor add-on status
+
+## Usage
+
+### REST API
+
+```typescript
+GET /api/addons
+GET /api/addons/{addon_slug}
+POST /api/addons/{addon_slug}/install
+POST /api/addons/{addon_slug}/uninstall
+POST /api/addons/{addon_slug}/start
+POST /api/addons/{addon_slug}/stop
+POST /api/addons/{addon_slug}/restart
+GET /api/addons/{addon_slug}/logs
+PUT /api/addons/{addon_slug}/config
+GET /api/addons/{addon_slug}/stats
+```
+
+### WebSocket
+
+```typescript
+// List add-ons
+{
+    "type": "get_addons"
+}
+
+// Get add-on info
+{
+    "type": "get_addon_info",
+    "addon_slug": "required_addon_slug"
+}
+
+// Install add-on
+{
+    "type": "install_addon",
+    "addon_slug": "required_addon_slug",
+    "version": "optional_version"
+}
+
+// Control add-on
+{
+    "type": "control_addon",
+    "addon_slug": "required_addon_slug",
+    "action": "start|stop|restart"
+}
+```
+
+## Examples
+
+### List All Add-ons
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/addons', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const addons = await response.json();
+```
+
+### Install Add-on
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/addons/mosquitto/install', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "version": "latest"
+    })
+});
+```
+
+### Configure Add-on
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/addons/mosquitto/config', {
+    method: 'PUT',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "logins": [
+            {
+                "username": "mqtt_user",
+                "password": "mqtt_password"
+            }
+        ],
+        "customize": {
+            "active": true,
+            "folder": "mosquitto"
+        }
+    })
+});
+```
+
+## Response Format
+
+### Add-on List Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "addons": [
+            {
+                "slug": "addon_slug",
+                "name": "Add-on Name",
+                "version": "1.0.0",
+                "state": "started",
+                "repository": "core",
+                "installed": true,
+                "update_available": false
+            }
+        ]
+    }
+}
+```
+
+### Add-on Info Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "addon": {
+            "slug": "addon_slug",
+            "name": "Add-on Name",
+            "version": "1.0.0",
+            "description": "Add-on description",
+            "long_description": "Detailed description",
+            "repository": "core",
+            "installed": true,
+            "state": "started",
+            "webui": "http://[HOST]:[PORT:80]",
+            "boot": "auto",
+            "options": {
+                // Add-on specific options
+            },
+            "schema": {
+                // Add-on options schema
+            },
+            "ports": {
+                "80/tcp": 8080
+            },
+            "ingress": true,
+            "ingress_port": 8099
+        }
+    }
+}
+```
+
+### Add-on Stats Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "stats": {
+            "cpu_percent": 2.5,
+            "memory_usage": 128974848,
+            "memory_limit": 536870912,
+            "network_rx": 1234,
+            "network_tx": 5678,
+            "blk_read": 12345,
+            "blk_write": 67890
+        }
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Add-on not found
+- `401`: Unauthorized
+- `400`: Invalid request
+- `409`: Add-on operation failed
+- `422`: Invalid configuration
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limit: 50 requests per 15 minutes
+- Configurable through environment variables:
+  - `ADDON_RATE_LIMIT`
+  - `ADDON_RATE_WINDOW`
+
+## Best Practices
+
+1. Always check add-on compatibility
+2. Back up configurations before updates
+3. Monitor resource usage
+4. Use appropriate update strategies
+5. Implement proper error handling
+6. Test configurations in safe environment
+7. Handle rate limiting gracefully
+8. Keep add-ons updated
+
+## Add-on Security
+
+- Use secure passwords
+- Regularly update add-ons
+- Monitor add-on logs
+- Restrict network access
+- Use SSL/TLS when available
+- Follow principle of least privilege
+
+## See Also
+
+- [Package Management](package.md)
+- [Device Control](../device-management/control.md)
+- [Event Subscription](../events/subscribe-events.md) 

docs/tools/addons-packages/package.md

@@ -0,0 +1,236 @@
+# Package Management Tool
+
+The Package Management tool provides functionality to manage Home Assistant Community Store (HACS) packages through the MCP interface.
+
+## Features
+
+- List available packages
+- Install/update/remove packages
+- Search packages
+- Get package information
+- Manage package repositories
+- Track package updates
+- View package documentation
+- Monitor package status
+
+## Usage
+
+### REST API
+
+```typescript
+GET /api/packages
+GET /api/packages/{package_id}
+POST /api/packages/{package_id}/install
+POST /api/packages/{package_id}/uninstall
+POST /api/packages/{package_id}/update
+GET /api/packages/search
+GET /api/packages/categories
+GET /api/packages/repositories
+```
+
+### WebSocket
+
+```typescript
+// List packages
+{
+    "type": "get_packages",
+    "category": "optional_category"
+}
+
+// Search packages
+{
+    "type": "search_packages",
+    "query": "search_query",
+    "category": "optional_category"
+}
+
+// Install package
+{
+    "type": "install_package",
+    "package_id": "required_package_id",
+    "version": "optional_version"
+}
+```
+
+## Package Categories
+
+- Integrations
+- Frontend
+- Themes
+- AppDaemon Apps
+- NetDaemon Apps
+- Python Scripts
+- Plugins
+
+## Examples
+
+### List All Packages
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/packages', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const packages = await response.json();
+```
+
+### Search Packages
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/packages/search?q=weather&category=integrations', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const searchResults = await response.json();
+```
+
+### Install Package
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/packages/custom-weather-card/install', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "version": "latest"
+    })
+});
+```
+
+## Response Format
+
+### Package List Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "packages": [
+            {
+                "id": "package_id",
+                "name": "Package Name",
+                "category": "integrations",
+                "description": "Package description",
+                "version": "1.0.0",
+                "installed": true,
+                "update_available": false,
+                "stars": 150,
+                "downloads": 10000
+            }
+        ]
+    }
+}
+```
+
+### Package Info Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "package": {
+            "id": "package_id",
+            "name": "Package Name",
+            "category": "integrations",
+            "description": "Package description",
+            "long_description": "Detailed description",
+            "version": "1.0.0",
+            "installed_version": "0.9.0",
+            "available_version": "1.0.0",
+            "installed": true,
+            "update_available": true,
+            "stars": 150,
+            "downloads": 10000,
+            "repository": "https://github.com/author/repo",
+            "author": {
+                "name": "Author Name",
+                "url": "https://github.com/author"
+            },
+            "documentation": "https://github.com/author/repo/wiki",
+            "dependencies": [
+                "dependency1",
+                "dependency2"
+            ]
+        }
+    }
+}
+```
+
+### Search Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "results": [
+            {
+                "id": "package_id",
+                "name": "Package Name",
+                "category": "integrations",
+                "description": "Package description",
+                "version": "1.0.0",
+                "score": 0.95
+            }
+        ],
+        "total": 42
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Package not found
+- `401`: Unauthorized
+- `400`: Invalid request
+- `409`: Package operation failed
+- `422`: Invalid configuration
+- `424`: Dependency error
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limit: 50 requests per 15 minutes
+- Configurable through environment variables:
+  - `PACKAGE_RATE_LIMIT`
+  - `PACKAGE_RATE_WINDOW`
+
+## Best Practices
+
+1. Check package compatibility
+2. Review package documentation
+3. Verify package dependencies
+4. Back up before updates
+5. Test in safe environment
+6. Monitor resource usage
+7. Keep packages updated
+8. Handle rate limiting gracefully
+
+## Package Security
+
+- Verify package sources
+- Review package permissions
+- Check package reputation
+- Monitor package activity
+- Keep dependencies updated
+- Follow security advisories
+
+## See Also
+
+- [Add-on Management](addon.md)
+- [Device Control](../device-management/control.md)
+- [Event Subscription](../events/subscribe-events.md) 

docs/tools/automation/automation-config.md

@@ -0,0 +1,321 @@
+# Automation Configuration Tool
+
+The Automation Configuration tool provides functionality to create, update, and manage Home Assistant automation configurations.
+
+## Features
+
+- Create new automations
+- Update existing automations
+- Delete automations
+- Duplicate automations
+- Import/Export automation configurations
+- Validate automation configurations
+
+## Usage
+
+### REST API
+
+```typescript
+POST /api/automations
+PUT /api/automations/{automation_id}
+DELETE /api/automations/{automation_id}
+POST /api/automations/{automation_id}/duplicate
+POST /api/automations/validate
+```
+
+### WebSocket
+
+```typescript
+// Create automation
+{
+    "type": "create_automation",
+    "automation": {
+        // Automation configuration
+    }
+}
+
+// Update automation
+{
+    "type": "update_automation",
+    "automation_id": "required_automation_id",
+    "automation": {
+        // Updated configuration
+    }
+}
+
+// Delete automation
+{
+    "type": "delete_automation",
+    "automation_id": "required_automation_id"
+}
+```
+
+## Automation Configuration
+
+### Basic Structure
+
+```json
+{
+    "id": "morning_routine",
+    "alias": "Morning Routine",
+    "description": "Turn on lights and adjust temperature in the morning",
+    "trigger": [
+        {
+            "platform": "time",
+            "at": "07:00:00"
+        }
+    ],
+    "condition": [
+        {
+            "condition": "time",
+            "weekday": ["mon", "tue", "wed", "thu", "fri"]
+        }
+    ],
+    "action": [
+        {
+            "service": "light.turn_on",
+            "target": {
+                "entity_id": "light.bedroom"
+            },
+            "data": {
+                "brightness": 255,
+                "transition": 300
+            }
+        }
+    ],
+    "mode": "single"
+}
+```
+
+### Trigger Types
+
+```json
+// Time-based trigger
+{
+    "platform": "time",
+    "at": "07:00:00"
+}
+
+// State-based trigger
+{
+    "platform": "state",
+    "entity_id": "binary_sensor.motion",
+    "to": "on"
+}
+
+// Event-based trigger
+{
+    "platform": "event",
+    "event_type": "custom_event"
+}
+
+// Numeric state trigger
+{
+    "platform": "numeric_state",
+    "entity_id": "sensor.temperature",
+    "above": 25
+}
+```
+
+### Condition Types
+
+```json
+// Time condition
+{
+    "condition": "time",
+    "after": "07:00:00",
+    "before": "22:00:00"
+}
+
+// State condition
+{
+    "condition": "state",
+    "entity_id": "device_tracker.phone",
+    "state": "home"
+}
+
+// Numeric state condition
+{
+    "condition": "numeric_state",
+    "entity_id": "sensor.temperature",
+    "below": 25
+}
+```
+
+### Action Types
+
+```json
+// Service call action
+{
+    "service": "light.turn_on",
+    "target": {
+        "entity_id": "light.bedroom"
+    }
+}
+
+// Delay action
+{
+    "delay": "00:00:30"
+}
+
+// Scene activation
+{
+    "scene": "scene.evening_mode"
+}
+
+// Conditional action
+{
+    "choose": [
+        {
+            "conditions": [
+                {
+                    "condition": "state",
+                    "entity_id": "sun.sun",
+                    "state": "below_horizon"
+                }
+            ],
+            "sequence": [
+                {
+                    "service": "light.turn_on",
+                    "target": {
+                        "entity_id": "light.living_room"
+                    }
+                }
+            ]
+        }
+    ]
+}
+```
+
+## Examples
+
+### Create New Automation
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/automations', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "alias": "Morning Routine",
+        "description": "Turn on lights in the morning",
+        "trigger": [
+            {
+                "platform": "time",
+                "at": "07:00:00"
+            }
+        ],
+        "action": [
+            {
+                "service": "light.turn_on",
+                "target": {
+                    "entity_id": "light.bedroom"
+                }
+            }
+        ]
+    })
+});
+```
+
+### Update Existing Automation
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/automations/morning_routine', {
+    method: 'PUT',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "alias": "Morning Routine",
+        "trigger": [
+            {
+                "platform": "time",
+                "at": "07:30:00"  // Updated time
+            }
+        ],
+        "action": [
+            {
+                "service": "light.turn_on",
+                "target": {
+                    "entity_id": "light.bedroom"
+                }
+            }
+        ]
+    })
+});
+```
+
+## Response Format
+
+### Success Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "automation": {
+            "id": "created_automation_id",
+            // Full automation configuration
+        }
+    }
+}
+```
+
+### Validation Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "valid": true,
+        "warnings": [
+            "No conditions specified"
+        ]
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Automation not found
+- `401`: Unauthorized
+- `400`: Invalid configuration
+- `409`: Automation creation/update failed
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE",
+    "validation_errors": [
+        {
+            "path": "trigger[0].platform",
+            "message": "Invalid trigger platform"
+        }
+    ]
+}
+```
+
+## Best Practices
+
+1. Always validate configurations before saving
+2. Use descriptive aliases and descriptions
+3. Group related automations
+4. Test automations in a safe environment
+5. Document automation dependencies
+6. Use variables for reusable values
+7. Implement proper error handling
+8. Consider automation modes carefully
+
+## See Also
+
+- [Automation Management](automation.md)
+- [Event Subscription](../events/subscribe-events.md)
+- [Scene Management](../history-state/scene.md) 

docs/tools/automation/automation.md

@@ -0,0 +1,211 @@
+# Automation Management Tool
+
+The Automation Management tool provides functionality to manage and control Home Assistant automations.
+
+## Features
+
+- List all automations
+- Get automation details
+- Toggle automation state (enable/disable)
+- Trigger automations manually
+- Monitor automation execution
+- View automation history
+
+## Usage
+
+### REST API
+
+```typescript
+GET /api/automations
+GET /api/automations/{automation_id}
+POST /api/automations/{automation_id}/toggle
+POST /api/automations/{automation_id}/trigger
+GET /api/automations/{automation_id}/history
+```
+
+### WebSocket
+
+```typescript
+// List automations
+{
+    "type": "get_automations"
+}
+
+// Toggle automation
+{
+    "type": "toggle_automation",
+    "automation_id": "required_automation_id"
+}
+
+// Trigger automation
+{
+    "type": "trigger_automation",
+    "automation_id": "required_automation_id",
+    "variables": {
+        // Optional variables
+    }
+}
+```
+
+## Examples
+
+### List All Automations
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/automations', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const automations = await response.json();
+```
+
+### Toggle Automation State
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/automations/morning_routine/toggle', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+```
+
+### Trigger Automation Manually
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/automations/morning_routine/trigger', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "variables": {
+            "brightness": 100,
+            "temperature": 22
+        }
+    })
+});
+```
+
+## Response Format
+
+### Automation List Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "automations": [
+            {
+                "id": "automation_id",
+                "name": "Automation Name",
+                "enabled": true,
+                "last_triggered": "2024-02-05T12:00:00Z",
+                "trigger_count": 42
+            }
+        ]
+    }
+}
+```
+
+### Automation Details Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "automation": {
+            "id": "automation_id",
+            "name": "Automation Name",
+            "enabled": true,
+            "triggers": [
+                {
+                    "platform": "time",
+                    "at": "07:00:00"
+                }
+            ],
+            "conditions": [],
+            "actions": [
+                {
+                    "service": "light.turn_on",
+                    "target": {
+                        "entity_id": "light.bedroom"
+                    }
+                }
+            ],
+            "mode": "single",
+            "max": 10,
+            "last_triggered": "2024-02-05T12:00:00Z",
+            "trigger_count": 42
+        }
+    }
+}
+```
+
+### Automation History Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "history": [
+            {
+                "timestamp": "2024-02-05T12:00:00Z",
+                "trigger": {
+                    "platform": "time",
+                    "at": "07:00:00"
+                },
+                "context": {
+                    "user_id": "user_123",
+                    "variables": {}
+                },
+                "result": "success"
+            }
+        ]
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Automation not found
+- `401`: Unauthorized
+- `400`: Invalid request
+- `409`: Automation execution failed
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limit: 50 requests per 15 minutes
+- Configurable through environment variables:
+  - `AUTOMATION_RATE_LIMIT`
+  - `AUTOMATION_RATE_WINDOW`
+
+## Best Practices
+
+1. Monitor automation execution history
+2. Use descriptive automation names
+3. Implement proper error handling
+4. Cache automation configurations when possible
+5. Handle rate limiting gracefully
+6. Test automations before enabling
+7. Use variables for flexible automation behavior
+
+## See Also
+
+- [Automation Configuration](automation-config.md)
+- [Event Subscription](../events/subscribe-events.md)
+- [Device Control](../device-management/control.md) 

docs/tools/device-management/control.md

@@ -0,0 +1,195 @@
+# Device Control Tool
+
+The Device Control tool provides functionality to control various types of devices in your Home Assistant instance.
+
+## Supported Device Types
+
+- Lights
+- Switches
+- Covers
+- Climate devices
+- Media players
+- And more...
+
+## Usage
+
+### REST API
+
+```typescript
+POST /api/devices/{device_id}/control
+```
+
+### WebSocket
+
+```typescript
+{
+    "type": "control_device",
+    "device_id": "required_device_id",
+    "domain": "required_domain",
+    "service": "required_service",
+    "data": {
+        // Service-specific data
+    }
+}
+```
+
+## Domain-Specific Commands
+
+### Lights
+
+```typescript
+// Turn on/off
+POST /api/devices/light/{device_id}/control
+{
+    "service": "turn_on",  // or "turn_off"
+}
+
+// Set brightness
+{
+    "service": "turn_on",
+    "data": {
+        "brightness": 255  // 0-255
+    }
+}
+
+// Set color
+{
+    "service": "turn_on",
+    "data": {
+        "rgb_color": [255, 0, 0]  // Red
+    }
+}
+```
+
+### Covers
+
+```typescript
+// Open/close
+POST /api/devices/cover/{device_id}/control
+{
+    "service": "open_cover",  // or "close_cover"
+}
+
+// Set position
+{
+    "service": "set_cover_position",
+    "data": {
+        "position": 50  // 0-100
+    }
+}
+```
+
+### Climate
+
+```typescript
+// Set temperature
+POST /api/devices/climate/{device_id}/control
+{
+    "service": "set_temperature",
+    "data": {
+        "temperature": 22.5
+    }
+}
+
+// Set mode
+{
+    "service": "set_hvac_mode",
+    "data": {
+        "hvac_mode": "heat"  // heat, cool, auto, off
+    }
+}
+```
+
+## Examples
+
+### Control Light Brightness
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/devices/light/living_room/control', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "service": "turn_on",
+        "data": {
+            "brightness": 128
+        }
+    })
+});
+```
+
+### Control Cover Position
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/devices/cover/bedroom/control', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "service": "set_cover_position",
+        "data": {
+            "position": 75
+        }
+    })
+});
+```
+
+## Response Format
+
+### Success Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "state": "on",
+        "attributes": {
+            // Updated device attributes
+        }
+    }
+}
+```
+
+### Error Response
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Device not found
+- `401`: Unauthorized
+- `400`: Invalid service or parameters
+- `409`: Device unavailable or offline
+
+## Rate Limiting
+
+- Default limit: 100 requests per 15 minutes
+- Configurable through environment variables:
+  - `DEVICE_CONTROL_RATE_LIMIT`
+  - `DEVICE_CONTROL_RATE_WINDOW`
+
+## Best Practices
+
+1. Validate device availability before sending commands
+2. Implement proper error handling
+3. Use appropriate retry strategies for failed commands
+4. Cache device capabilities when possible
+5. Handle rate limiting gracefully
+
+## See Also
+
+- [List Devices](list-devices.md)
+- [Device History](../history-state/history.md)
+- [Event Subscription](../events/subscribe-events.md) 

docs/tools/device-management/list-devices.md

@@ -0,0 +1,139 @@
+# List Devices Tool
+
+The List Devices tool provides functionality to retrieve and manage device information from your Home Assistant instance.
+
+## Features
+
+- List all available Home Assistant devices
+- Group devices by domain
+- Get device states and attributes
+- Filter devices by various criteria
+
+## Usage
+
+### REST API
+
+```typescript
+GET /api/devices
+GET /api/devices/{domain}
+GET /api/devices/{device_id}/state
+```
+
+### WebSocket
+
+```typescript
+// List all devices
+{
+    "type": "list_devices",
+    "domain": "optional_domain"
+}
+
+// Get device state
+{
+    "type": "get_device_state",
+    "device_id": "required_device_id"
+}
+```
+
+### Examples
+
+#### List All Devices
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/devices', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const devices = await response.json();
+```
+
+#### Get Devices by Domain
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/devices/light', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const lightDevices = await response.json();
+```
+
+## Response Format
+
+### Device List Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "devices": [
+            {
+                "id": "device_id",
+                "name": "Device Name",
+                "domain": "light",
+                "state": "on",
+                "attributes": {
+                    "brightness": 255,
+                    "color_temp": 370
+                }
+            }
+        ]
+    }
+}
+```
+
+### Device State Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "state": "on",
+        "attributes": {
+            "brightness": 255,
+            "color_temp": 370
+        },
+        "last_changed": "2024-02-05T12:00:00Z",
+        "last_updated": "2024-02-05T12:00:00Z"
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Device not found
+- `401`: Unauthorized
+- `400`: Invalid request parameters
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limit: 100 requests per 15 minutes
+- Configurable through environment variables:
+  - `DEVICE_LIST_RATE_LIMIT`
+  - `DEVICE_LIST_RATE_WINDOW`
+
+## Best Practices
+
+1. Cache device lists when possible
+2. Use domain filtering for better performance
+3. Implement proper error handling
+4. Handle rate limiting gracefully
+
+## See Also
+
+- [Device Control](control.md)
+- [Device History](../history-state/history.md)
+- [Event Subscription](../events/subscribe-events.md) 

docs/tools/events/sse-stats.md

@@ -0,0 +1,251 @@
+# SSE Statistics Tool
+
+The SSE Statistics tool provides functionality to monitor and analyze Server-Sent Events (SSE) connections and performance in your Home Assistant MCP instance.
+
+## Features
+
+- Monitor active SSE connections
+- Track connection statistics
+- Analyze event delivery
+- Monitor resource usage
+- Connection management
+- Performance metrics
+- Historical data
+- Alert configuration
+
+## Usage
+
+### REST API
+
+```typescript
+GET /api/sse/stats
+GET /api/sse/connections
+GET /api/sse/connections/{connection_id}
+GET /api/sse/metrics
+GET /api/sse/history
+```
+
+### WebSocket
+
+```typescript
+// Get SSE stats
+{
+    "type": "get_sse_stats"
+}
+
+// Get connection details
+{
+    "type": "get_sse_connection",
+    "connection_id": "required_connection_id"
+}
+
+// Get performance metrics
+{
+    "type": "get_sse_metrics",
+    "period": "1h|24h|7d|30d"
+}
+```
+
+## Examples
+
+### Get Current Statistics
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/sse/stats', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const stats = await response.json();
+```
+
+### Get Connection Details
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/sse/connections/conn_123', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const connection = await response.json();
+```
+
+### Get Performance Metrics
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/sse/metrics?period=24h', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const metrics = await response.json();
+```
+
+## Response Format
+
+### Statistics Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "active_connections": 42,
+        "total_events_sent": 12345,
+        "events_per_second": 5.2,
+        "memory_usage": 128974848,
+        "cpu_usage": 2.5,
+        "uptime": "PT24H",
+        "event_backlog": 0
+    }
+}
+```
+
+### Connection Details Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "connection": {
+            "id": "conn_123",
+            "client_id": "client_456",
+            "user_id": "user_789",
+            "connected_at": "2024-02-05T12:00:00Z",
+            "last_event_at": "2024-02-05T12:05:00Z",
+            "events_sent": 150,
+            "subscriptions": [
+                {
+                    "event_type": "state_changed",
+                    "entity_id": "light.living_room"
+                }
+            ],
+            "state": "active",
+            "ip_address": "192.168.1.100",
+            "user_agent": "Mozilla/5.0 ..."
+        }
+    }
+}
+```
+
+### Performance Metrics Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "metrics": {
+            "connections": {
+                "current": 42,
+                "max": 100,
+                "average": 35.5
+            },
+            "events": {
+                "total": 12345,
+                "rate": {
+                    "current": 5.2,
+                    "max": 15.0,
+                    "average": 4.8
+                }
+            },
+            "latency": {
+                "p50": 15,
+                "p95": 45,
+                "p99": 100
+            },
+            "resources": {
+                "memory": {
+                    "current": 128974848,
+                    "max": 536870912
+                },
+                "cpu": {
+                    "current": 2.5,
+                    "max": 10.0,
+                    "average": 3.2
+                }
+            }
+        },
+        "period": "24h",
+        "timestamp": "2024-02-05T12:00:00Z"
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Connection not found
+- `401`: Unauthorized
+- `400`: Invalid request parameters
+- `503`: Service overloaded
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Monitoring Metrics
+
+### Connection Metrics
+- Active connections
+- Connection duration
+- Connection state
+- Client information
+- Geographic distribution
+- Protocol version
+
+### Event Metrics
+- Events per second
+- Event types distribution
+- Delivery success rate
+- Event latency
+- Queue size
+- Backlog size
+
+### Resource Metrics
+- Memory usage
+- CPU usage
+- Network bandwidth
+- Disk I/O
+- Connection pool status
+- Thread pool status
+
+## Alert Thresholds
+
+- Connection limits
+- Event rate limits
+- Resource usage limits
+- Latency thresholds
+- Error rate thresholds
+- Backlog thresholds
+
+## Best Practices
+
+1. Monitor connection health
+2. Track resource usage
+3. Set up alerts
+4. Analyze usage patterns
+5. Optimize performance
+6. Plan capacity
+7. Implement failover
+8. Regular maintenance
+
+## Performance Optimization
+
+- Connection pooling
+- Event batching
+- Resource throttling
+- Load balancing
+- Cache optimization
+- Connection cleanup
+
+## See Also
+
+- [Event Subscription](subscribe-events.md)
+- [Device Control](../device-management/control.md)
+- [Automation Management](../automation/automation.md) 

docs/tools/events/subscribe-events.md

@@ -0,0 +1,253 @@
+# Event Subscription Tool
+
+The Event Subscription tool provides functionality to subscribe to and monitor real-time events from your Home Assistant instance.
+
+## Features
+
+- Subscribe to Home Assistant events
+- Monitor specific entities
+- Domain-based monitoring
+- Event filtering
+- Real-time updates
+- Event history
+- Custom event handling
+- Connection management
+
+## Usage
+
+### REST API
+
+```typescript
+POST /api/events/subscribe
+DELETE /api/events/unsubscribe
+GET /api/events/subscriptions
+GET /api/events/history
+```
+
+### WebSocket
+
+```typescript
+// Subscribe to events
+{
+    "type": "subscribe_events",
+    "event_type": "optional_event_type",
+    "entity_id": "optional_entity_id",
+    "domain": "optional_domain"
+}
+
+// Unsubscribe from events
+{
+    "type": "unsubscribe_events",
+    "subscription_id": "required_subscription_id"
+}
+```
+
+### Server-Sent Events (SSE)
+
+```typescript
+GET /api/events/stream?event_type=state_changed&entity_id=light.living_room
+```
+
+## Event Types
+
+- `state_changed`: Entity state changes
+- `automation_triggered`: Automation executions
+- `scene_activated`: Scene activations
+- `device_registered`: New device registrations
+- `service_registered`: New service registrations
+- `homeassistant_start`: System startup
+- `homeassistant_stop`: System shutdown
+- Custom events
+
+## Examples
+
+### Subscribe to All State Changes
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "event_type": "state_changed"
+    })
+});
+```
+
+### Monitor Specific Entity
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "event_type": "state_changed",
+        "entity_id": "light.living_room"
+    })
+});
+```
+
+### Domain-Based Monitoring
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "event_type": "state_changed",
+        "domain": "light"
+    })
+});
+```
+
+### SSE Connection Example
+
+```typescript
+const eventSource = new EventSource(
+    'http://your-ha-mcp/api/events/stream?event_type=state_changed&entity_id=light.living_room',
+    {
+        headers: {
+            'Authorization': 'Bearer your_access_token'
+        }
+    }
+);
+
+eventSource.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    console.log('Event received:', data);
+};
+
+eventSource.onerror = (error) => {
+    console.error('SSE error:', error);
+    eventSource.close();
+};
+```
+
+## Response Format
+
+### Subscription Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "subscription_id": "sub_123",
+        "event_type": "state_changed",
+        "entity_id": "light.living_room",
+        "created_at": "2024-02-05T12:00:00Z"
+    }
+}
+```
+
+### Event Message Format
+
+```json
+{
+    "event_type": "state_changed",
+    "entity_id": "light.living_room",
+    "data": {
+        "old_state": {
+            "state": "off",
+            "attributes": {},
+            "last_changed": "2024-02-05T11:55:00Z"
+        },
+        "new_state": {
+            "state": "on",
+            "attributes": {
+                "brightness": 255
+            },
+            "last_changed": "2024-02-05T12:00:00Z"
+        }
+    },
+    "origin": "LOCAL",
+    "time_fired": "2024-02-05T12:00:00Z",
+    "context": {
+        "id": "context_123",
+        "parent_id": null,
+        "user_id": "user_123"
+    }
+}
+```
+
+### Subscriptions List Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "subscriptions": [
+            {
+                "id": "sub_123",
+                "event_type": "state_changed",
+                "entity_id": "light.living_room",
+                "created_at": "2024-02-05T12:00:00Z",
+                "last_event": "2024-02-05T12:05:00Z"
+            }
+        ]
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Event type not found
+- `401`: Unauthorized
+- `400`: Invalid subscription parameters
+- `409`: Subscription already exists
+- `429`: Too many subscriptions
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limits:
+  - Maximum subscriptions: 100 per client
+  - Maximum event rate: 1000 events per minute
+- Configurable through environment variables:
+  - `EVENT_SUB_MAX_SUBSCRIPTIONS`
+  - `EVENT_SUB_RATE_LIMIT`
+  - `EVENT_SUB_RATE_WINDOW`
+
+## Best Practices
+
+1. Use specific event types when possible
+2. Implement proper error handling
+3. Handle connection interruptions
+4. Process events asynchronously
+5. Implement backoff strategies
+6. Monitor subscription health
+7. Clean up unused subscriptions
+8. Handle rate limiting gracefully
+
+## Connection Management
+
+- Implement heartbeat monitoring
+- Use reconnection strategies
+- Handle connection timeouts
+- Monitor connection quality
+- Implement fallback mechanisms
+- Clean up resources properly
+
+## See Also
+
+- [SSE Statistics](sse-stats.md)
+- [Device Control](../device-management/control.md)
+- [Automation Management](../automation/automation.md) 

docs/tools/history-state/history.md

@@ -0,0 +1,167 @@
+# Device History Tool
+
+The Device History tool allows you to retrieve historical state information for devices in your Home Assistant instance.
+
+## Features
+
+- Fetch device state history
+- Filter by time range
+- Get significant changes
+- Aggregate data by time periods
+- Export historical data
+
+## Usage
+
+### REST API
+
+```typescript
+GET /api/history/{device_id}
+GET /api/history/{device_id}/period/{start_time}
+GET /api/history/{device_id}/period/{start_time}/{end_time}
+```
+
+### WebSocket
+
+```typescript
+{
+    "type": "get_history",
+    "device_id": "required_device_id",
+    "start_time": "optional_iso_timestamp",
+    "end_time": "optional_iso_timestamp",
+    "significant_changes_only": false
+}
+```
+
+## Query Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `start_time` | ISO timestamp | Start of the period to fetch history for |
+| `end_time` | ISO timestamp | End of the period to fetch history for |
+| `significant_changes_only` | boolean | Only return significant state changes |
+| `minimal_response` | boolean | Return minimal state information |
+| `no_attributes` | boolean | Exclude attribute data from response |
+
+## Examples
+
+### Get Recent History
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/history/light.living_room', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const history = await response.json();
+```
+
+### Get History for Specific Period
+
+```typescript
+const startTime = '2024-02-01T00:00:00Z';
+const endTime = '2024-02-02T00:00:00Z';
+const response = await fetch(
+    `http://your-ha-mcp/api/history/light.living_room/period/${startTime}/${endTime}`, 
+    {
+        headers: {
+            'Authorization': 'Bearer your_access_token'
+        }
+    }
+);
+const history = await response.json();
+```
+
+## Response Format
+
+### History Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "history": [
+            {
+                "state": "on",
+                "attributes": {
+                    "brightness": 255
+                },
+                "last_changed": "2024-02-05T12:00:00Z",
+                "last_updated": "2024-02-05T12:00:00Z"
+            },
+            {
+                "state": "off",
+                "last_changed": "2024-02-05T13:00:00Z",
+                "last_updated": "2024-02-05T13:00:00Z"
+            }
+        ]
+    }
+}
+```
+
+### Aggregated History Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "aggregates": {
+            "daily": [
+                {
+                    "date": "2024-02-05",
+                    "on_time": "PT5H30M",
+                    "off_time": "PT18H30M",
+                    "changes": 10
+                }
+            ]
+        }
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Device not found
+- `401`: Unauthorized
+- `400`: Invalid parameters
+- `416`: Time range too large
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limit: 50 requests per 15 minutes
+- Configurable through environment variables:
+  - `HISTORY_RATE_LIMIT`
+  - `HISTORY_RATE_WINDOW`
+
+## Data Retention
+
+- Default retention period: 30 days
+- Configurable through environment variables:
+  - `HISTORY_RETENTION_DAYS`
+- Older data may be automatically aggregated
+
+## Best Practices
+
+1. Use appropriate time ranges to avoid large responses
+2. Enable `significant_changes_only` for better performance
+3. Use `minimal_response` when full state data isn't needed
+4. Implement proper error handling
+5. Cache frequently accessed historical data
+6. Handle rate limiting gracefully
+
+## See Also
+
+- [List Devices](../device-management/list-devices.md)
+- [Device Control](../device-management/control.md)
+- [Scene Management](scene.md) 

docs/tools/history-state/scene.md

@@ -0,0 +1,215 @@
+# Scene Management Tool
+
+The Scene Management tool provides functionality to manage and control scenes in your Home Assistant instance.
+
+## Features
+
+- List available scenes
+- Activate scenes
+- Create new scenes
+- Update existing scenes
+- Delete scenes
+- Get scene state information
+
+## Usage
+
+### REST API
+
+```typescript
+GET /api/scenes
+GET /api/scenes/{scene_id}
+POST /api/scenes/{scene_id}/activate
+POST /api/scenes
+PUT /api/scenes/{scene_id}
+DELETE /api/scenes/{scene_id}
+```
+
+### WebSocket
+
+```typescript
+// List scenes
+{
+    "type": "get_scenes"
+}
+
+// Activate scene
+{
+    "type": "activate_scene",
+    "scene_id": "required_scene_id"
+}
+
+// Create/Update scene
+{
+    "type": "create_scene",
+    "scene": {
+        "name": "required_scene_name",
+        "entities": {
+            // Entity states
+        }
+    }
+}
+```
+
+## Scene Configuration
+
+### Scene Definition
+
+```json
+{
+    "name": "Movie Night",
+    "entities": {
+        "light.living_room": {
+            "state": "on",
+            "brightness": 50,
+            "color_temp": 2700
+        },
+        "cover.living_room": {
+            "state": "closed"
+        },
+        "media_player.tv": {
+            "state": "on",
+            "source": "HDMI 1"
+        }
+    }
+}
+```
+
+## Examples
+
+### List All Scenes
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/scenes', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const scenes = await response.json();
+```
+
+### Activate a Scene
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/scenes/movie_night/activate', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+```
+
+### Create a New Scene
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/scenes', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "name": "Movie Night",
+        "entities": {
+            "light.living_room": {
+                "state": "on",
+                "brightness": 50
+            },
+            "cover.living_room": {
+                "state": "closed"
+            }
+        }
+    })
+});
+```
+
+## Response Format
+
+### Scene List Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "scenes": [
+            {
+                "id": "scene_id",
+                "name": "Scene Name",
+                "entities": {
+                    // Entity configurations
+                }
+            }
+        ]
+    }
+}
+```
+
+### Scene Activation Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "scene_id": "activated_scene_id",
+        "status": "activated",
+        "timestamp": "2024-02-05T12:00:00Z"
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Scene not found
+- `401`: Unauthorized
+- `400`: Invalid scene configuration
+- `409`: Scene activation failed
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limit: 50 requests per 15 minutes
+- Configurable through environment variables:
+  - `SCENE_RATE_LIMIT`
+  - `SCENE_RATE_WINDOW`
+
+## Best Practices
+
+1. Validate entity availability before creating scenes
+2. Use meaningful scene names
+3. Group related entities in scenes
+4. Implement proper error handling
+5. Cache scene configurations when possible
+6. Handle rate limiting gracefully
+
+## Scene Transitions
+
+Scenes can include transition settings for smooth state changes:
+
+```json
+{
+    "name": "Sunset Mode",
+    "entities": {
+        "light.living_room": {
+            "state": "on",
+            "brightness": 128,
+            "transition": 5  // 5 seconds
+        }
+    }
+}
+```
+
+## See Also
+
+- [Device Control](../device-management/control.md)
+- [Device History](history.md)
+- [Automation Management](../automation/automation.md) 

docs/tools/notifications/notify.md

@@ -0,0 +1,249 @@
+# Notification Tool
+
+The Notification tool provides functionality to send notifications through various services in your Home Assistant instance.
+
+## Features
+
+- Send notifications
+- Support for multiple notification services
+- Custom notification data
+- Rich media support
+- Notification templates
+- Delivery tracking
+- Priority levels
+- Notification groups
+
+## Usage
+
+### REST API
+
+```typescript
+POST /api/notify
+POST /api/notify/{service_id}
+GET /api/notify/services
+GET /api/notify/history
+```
+
+### WebSocket
+
+```typescript
+// Send notification
+{
+    "type": "send_notification",
+    "service": "required_service_id",
+    "message": "required_message",
+    "title": "optional_title",
+    "data": {
+        // Service-specific data
+    }
+}
+
+// Get notification services
+{
+    "type": "get_notification_services"
+}
+```
+
+## Supported Services
+
+- Mobile App
+- Email
+- SMS
+- Telegram
+- Discord
+- Slack
+- Push Notifications
+- Custom Services
+
+## Examples
+
+### Basic Notification
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/notify/mobile_app', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "message": "Motion detected in living room",
+        "title": "Security Alert"
+    })
+});
+```
+
+### Rich Notification
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/notify/mobile_app', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "message": "Motion detected in living room",
+        "title": "Security Alert",
+        "data": {
+            "image": "https://your-camera-snapshot.jpg",
+            "actions": [
+                {
+                    "action": "view_camera",
+                    "title": "View Camera"
+                },
+                {
+                    "action": "dismiss",
+                    "title": "Dismiss"
+                }
+            ],
+            "priority": "high",
+            "ttl": 3600,
+            "group": "security"
+        }
+    })
+});
+```
+
+### Service-Specific Example (Telegram)
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/notify/telegram', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "message": "Temperature is too high!",
+        "title": "Climate Alert",
+        "data": {
+            "parse_mode": "markdown",
+            "inline_keyboard": [
+                [
+                    {
+                        "text": "Turn On AC",
+                        "callback_data": "turn_on_ac"
+                    }
+                ]
+            ]
+        }
+    })
+});
+```
+
+## Response Format
+
+### Success Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "notification_id": "notification_123",
+        "status": "sent",
+        "timestamp": "2024-02-05T12:00:00Z",
+        "service": "mobile_app"
+    }
+}
+```
+
+### Services List Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "services": [
+            {
+                "id": "mobile_app",
+                "name": "Mobile App",
+                "enabled": true,
+                "features": [
+                    "actions",
+                    "images",
+                    "sound"
+                ]
+            }
+        ]
+    }
+}
+```
+
+### Notification History Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "history": [
+            {
+                "id": "notification_123",
+                "service": "mobile_app",
+                "message": "Motion detected",
+                "title": "Security Alert",
+                "timestamp": "2024-02-05T12:00:00Z",
+                "status": "delivered"
+            }
+        ]
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Service not found
+- `401`: Unauthorized
+- `400`: Invalid request
+- `408`: Delivery timeout
+- `422`: Invalid notification data
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limit: 100 notifications per hour
+- Configurable through environment variables:
+  - `NOTIFY_RATE_LIMIT`
+  - `NOTIFY_RATE_WINDOW`
+
+## Best Practices
+
+1. Use appropriate priority levels
+2. Group related notifications
+3. Include relevant context
+4. Implement proper error handling
+5. Use templates for consistency
+6. Consider time zones
+7. Respect user preferences
+8. Handle rate limiting gracefully
+
+## Notification Templates
+
+```typescript
+// Template example
+{
+    "template": "security_alert",
+    "data": {
+        "location": "living_room",
+        "event_type": "motion",
+        "timestamp": "2024-02-05T12:00:00Z"
+    }
+}
+```
+
+## See Also
+
+- [Event Subscription](../events/subscribe-events.md)
+- [Device Control](../device-management/control.md)
+- [Automation Management](../automation/automation.md) 

docs/tools/tools.md

@@ -6,36 +6,36 @@ This section documents all available tools in the Home Assistant MCP.
 
 ### Device Management
 
-1. [List Devices](./list-devices.md)
+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](./control.md)
+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.md)
+1. [History](history-state/history.md)
    - Fetch device state history
    - Filter by time range
    - Get significant changes
 
-2. [Scene Management](./scene.md)
+2. [Scene Management](history-state/scene.md)
    - List available scenes
    - Activate scenes
    - Scene state information
 
 ### Automation
 
-1. [Automation Management](./automation.md)
+1. [Automation Management](automation/automation.md)
    - List automations
    - Toggle automation state
    - Trigger automations manually
 
-2. [Automation Configuration](./automation-config.md)
+2. [Automation Configuration](automation/automation-config.md)
    - Create new automations
    - Update existing automations
    - Delete automations
@@ -43,32 +43,32 @@ This section documents all available tools in the Home Assistant MCP.
 
 ### Add-ons and Packages
 
-1. [Add-on Management](./addon.md)
+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](./package.md)
+2. [Package Management](addons-packages/package.md)
    - Manage HACS packages
    - Install/update/remove packages
    - List available packages by category
 
 ### Notifications
 
-1. [Notify](./notify.md)
+1. [Notify](notifications/notify.md)
    - Send notifications
    - Support for multiple notification services
    - Custom notification data
 
 ### Real-time Events
 
-1. [Event Subscription](./subscribe-events.md)
+1. [Event Subscription](events/subscribe-events.md)
    - Subscribe to Home Assistant events
    - Monitor specific entities
    - Domain-based monitoring
 
-2. [SSE Statistics](./sse-stats.md)
+2. [SSE Statistics](events/sse-stats.md)
    - Get SSE connection statistics
    - Monitor active subscriptions
    - Connection management

docs/troubleshooting.md

@@ -1,193 +1,374 @@
-# Troubleshooting Guide
+---
+layout: default
+title: Troubleshooting
+nav_order: 6
+---
 
-This guide helps you diagnose and fix common issues with the Home Assistant MCP.
+# Troubleshooting Guide 🔧
+
+This guide helps you diagnose and resolve common issues with MCP Server.
+
+## Quick Diagnostics
+
+### Health Check
+
+First, verify the server's health:
+
+```bash
+curl http://localhost:3000/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "uptime": 3600,
+  "homeAssistant": {
+    "connected": true,
+    "version": "2024.1.0"
+  }
+}
+```
 
 ## Common Issues
 
-### Connection Issues
+### 1. Connection Issues
 
-#### Cannot Connect to Home Assistant
+#### Cannot Connect to MCP Server
 
 **Symptoms:**
-- Connection timeout errors
+- Server not responding
-- "Failed to connect to Home Assistant" messages
+- Connection refused errors
-- 401 Unauthorized errors
+- Timeout errors
 
 **Solutions:**
-1. Verify Home Assistant is running
-2. Check HASS_HOST environment variable
-3. Validate HASS_TOKEN is correct
-4. Ensure network connectivity
-5. Check firewall settings
 
-#### SSE Connection Drops
+1. Check if the server is running:
+   ```bash
+   # For Docker installation
+   docker compose ps
+   
+   # For manual installation
+   ps aux | grep mcp
+   ```
+
+2. Verify port availability:
+   ```bash
+   # Check if port is in use
+   netstat -tuln | grep 3000
+   ```
+
+3. Check logs:
+   ```bash
+   # Docker logs
+   docker compose logs mcp
+   
+   # Manual installation logs
+   bun run dev
+   ```
+
+#### Home Assistant Connection Failed
 
 **Symptoms:**
-- Frequent disconnections
+- "Connection Error" in health check
-- Missing events
+- Cannot control devices
-- Connection reset errors
+- State updates not working
 
 **Solutions:**
-1. Check network stability
-2. Increase connection timeout
-3. Implement reconnection logic
-4. Monitor server resources
 
-### Authentication Issues
+1. Verify Home Assistant URL and token in `.env`:
+   ```env
+   HA_URL=http://homeassistant:8123
+   HA_TOKEN=your_long_lived_access_token
+   ```
+
+2. Test Home Assistant connection:
+   ```bash
+   curl -H "Authorization: Bearer YOUR_HA_TOKEN" \
+        http://your-homeassistant:8123/api/
+   ```
+
+3. Check network connectivity:
+   ```bash
+   # For Docker setup
+   docker compose exec mcp ping homeassistant
+   ```
+
+### 2. Authentication Issues
 
 #### Invalid Token
 
 **Symptoms:**
 - 401 Unauthorized responses
-- "Invalid token" messages
+- "Invalid token" errors
-- Authentication failures
 
 **Solutions:**
-1. Generate new Long-Lived Access Token
+
-2. Check token expiration
+1. Generate a new token:
-3. Verify token format
+   ```bash
-4. Update environment variables
+   curl -X POST http://localhost:3000/auth/token \
+     -H "Content-Type: application/json" \
+     -d '{"username": "your_username", "password": "your_password"}'
+   ```
+
+2. Verify token format:
+   ```javascript
+   // Token should be in format:
+   Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+   ```
 
 #### Rate Limiting
 
 **Symptoms:**
 - 429 Too Many Requests
-- "Rate limit exceeded" messages
+- "Rate limit exceeded" errors
 
 **Solutions:**
-1. Implement request throttling
-2. Adjust rate limit settings
-3. Cache responses
-4. Optimize request patterns
 
-### Tool Issues
+1. Check current rate limit status:
+   ```bash
+   curl -I http://localhost:3000/api/state
+   ```
 
-#### Tool Not Found
+2. Adjust rate limits in configuration:
+   ```yaml
+   security:
+     rateLimit: 100  # Increase if needed
+     rateLimitWindow: 60000  # Window in milliseconds
+   ```
+
+### 3. Real-time Updates Issues
+
+#### SSE Connection Drops
 
 **Symptoms:**
-- "Tool not found" errors
+- Frequent disconnections
-- 404 Not Found responses
+- Missing state updates
+- EventSource errors
 
 **Solutions:**
-1. Check tool name spelling
-2. Verify tool registration
-3. Update tool imports
-4. Check tool availability
 
-#### Tool Execution Fails
+1. Implement proper reconnection logic:
+   ```javascript
+   class SSEClient {
+       constructor() {
+           this.connect();
+       }
+   
+       connect() {
+           this.eventSource = new EventSource('/subscribe_events');
+           this.eventSource.onerror = this.handleError.bind(this);
+       }
+   
+       handleError(error) {
+           console.error('SSE Error:', error);
+           this.eventSource.close();
+           setTimeout(() => this.connect(), 1000);
+       }
+   }
+   ```
+
+2. Check network stability:
+   ```bash
+   # Monitor connection stability
+   ping -c 100 localhost
+   ```
+
+### 4. Performance Issues
+
+#### High Latency
 
 **Symptoms:**
-- Tool execution errors
+- Slow response times
-- Unexpected responses
+- Command execution delays
-- Timeout issues
+- UI lag
 
 **Solutions:**
-1. Validate input parameters
-2. Check error logs
-3. Debug tool implementation
-4. Verify Home Assistant permissions
 
-## Debugging
+1. Enable Redis caching:
+   ```env
+   REDIS_ENABLED=true
+   REDIS_URL=redis://localhost:6379
+   ```
 
-### Server Logs
+2. Monitor system resources:
+   ```bash
+   # Check CPU and memory usage
+   docker stats
+   
+   # Or for manual installation
+   top -p $(pgrep -f mcp)
+   ```
+
+3. Optimize database queries and caching:
+   ```typescript
+   // Use batch operations
+   const results = await Promise.all([
+       cache.get('key1'),
+       cache.get('key2')
+   ]);
+   ```
+
+### 5. Device Control Issues
+
+#### Commands Not Executing
+
+**Symptoms:**
+- Commands appear successful but no device response
+- Inconsistent device states
+- Error messages from Home Assistant
+
+**Solutions:**
+
+1. Verify device availability:
+   ```bash
+   curl http://localhost:3000/api/state/light.living_room
+   ```
+
+2. Check command syntax:
+   ```bash
+   # Test basic command
+   curl -X POST http://localhost:3000/api/command \
+     -H "Content-Type: application/json" \
+     -d '{"command": "Turn on living room lights"}'
+   ```
+
+3. Review Home Assistant logs:
+   ```bash
+   docker compose exec homeassistant journalctl -f
+   ```
+
+## Debugging Tools
+
+### Log Analysis
+
+Enable debug logging:
 
-1. Enable debug logging:
 ```env
 LOG_LEVEL=debug
-   ```
+DEBUG=mcp:*
-
-2. Check logs:
-   ```bash
-   npm run logs
-   ```
-
-3. Filter logs:
-   ```bash
-   npm run logs | grep "error"
 ```
 
 ### Network Debugging
 
-1. Check API endpoints:
+Monitor network traffic:
+
 ```bash
-   curl -v http://localhost:3000/api/health
+# TCP dump for API traffic
+tcpdump -i any port 3000 -w debug.pcap
 ```
 
-2. Monitor SSE connections:
+### Performance Profiling
-   ```bash
+
-   curl -N http://localhost:3000/api/sse/stats
+Enable performance monitoring:
+
+```env
+ENABLE_METRICS=true
+METRICS_PORT=9090
 ```
 
-3. Test WebSocket:
+## Getting Help
+
+If you're still experiencing issues:
+
+1. Check the [GitHub Issues](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues)
+2. Search [Discussions](https://github.com/jango-blockchained/advanced-homeassistant-mcp/discussions)
+3. Create a new issue with:
+   - Detailed description
+   - Logs
+   - Configuration (sanitized)
+   - Steps to reproduce
+
+## Maintenance
+
+### Regular Health Checks
+
+Run periodic health checks:
+
 ```bash
-   wscat -c ws://localhost:3000
+# Create a cron job
+*/5 * * * * curl -f http://localhost:3000/health || notify-admin
 ```
 
-### Performance Issues
+### Log Rotation
 
-1. Monitor memory usage:
+Configure log rotation:
-   ```bash
+
-   npm run stats
+```yaml
+logging:
+  maxSize: "100m"
+  maxFiles: "7d"
+  compress: true
 ```
 
-2. Check response times:
+### Backup Configuration
-   ```bash
+
-   curl -w "%{time_total}\n" -o /dev/null -s http://localhost:3000/api/health
+Regularly backup your configuration:
-   ```
 
-3. Profile code:
 ```bash
-   npm run profile
+# Backup script
+tar -czf mcp-backup-$(date +%Y%m%d).tar.gz \
+    .env \
+    config/ \
+    data/
 ```
 
 ## FAQ
 
-### Q: How do I reset my configuration?
+### General Questions
-A: Delete `.env` and copy `.env.example` to start fresh.
 
-### Q: Why are my events delayed?
+#### Q: What is MCP Server?
-A: Check network latency and server load. Consider adjusting buffer sizes.
+A: MCP Server is a bridge between Home Assistant and Language Learning Models, enabling natural language control and automation of your smart home devices.
 
-### Q: How do I update my token?
+#### Q: What are the system requirements?
-A: Generate a new token in Home Assistant and update HASS_TOKEN.
+A: MCP Server requires:
+- Node.js 16 or higher
+- Home Assistant instance
+- 1GB RAM minimum
+- 1GB disk space
 
-### Q: Why do I get "Maximum clients reached"?
+#### Q: How do I update MCP Server?
-A: Adjust SSE_MAX_CLIENTS in configuration or clean up stale connections.
+A: For Docker installation:
+```bash
+docker compose pull
+docker compose up -d
+```
+For manual installation:
+```bash
+git pull
+bun install
+bun run build
+```
 
-## Error Codes
+### Integration Questions
 
-- `E001`: Connection Error
+#### Q: Can I use MCP Server with any Home Assistant instance?
-- `E002`: Authentication Error
+A: Yes, MCP Server works with any Home Assistant instance that has the REST API enabled and a valid long-lived access token.
-- `E003`: Rate Limit Error
-- `E004`: Tool Error
-- `E005`: Configuration Error
 
-## Support Resources
+#### Q: Does MCP Server support all Home Assistant integrations?
+A: MCP Server supports all Home Assistant devices and services that are accessible via the REST API.
 
-1. Documentation
+### Security Questions
-   - [API Reference](./API.md)
-   - [Configuration Guide](./configuration/README.md)
-   - [Development Guide](./development/README.md)
 
-2. Community
+#### Q: Is my Home Assistant token secure?
-   - GitHub Issues
+A: Yes, your Home Assistant token is stored securely and only used for authenticated communication between MCP Server and your Home Assistant instance.
-   - Discussion Forums
-   - Stack Overflow
 
-3. Tools
+#### Q: Can I use MCP Server remotely?
-   - Diagnostic Scripts
+A: Yes, but we recommend using a secure connection (HTTPS) and proper authentication when exposing MCP Server to the internet.
-   - Testing Tools
-   - Monitoring Tools
 
-## Still Need Help?
+### Troubleshooting Questions
 
-1. Create a detailed issue:
+#### Q: Why are my device states not updating?
-   - Error messages
+A: Check:
-   - Steps to reproduce
+1. Home Assistant connection
-   - Environment details
+2. WebSocket connection status
-   - Logs
+3. Device availability in Home Assistant
+4. Network connectivity
 
-2. Contact support:
+#### Q: Why are my commands not working?
-   - GitHub Issues
+A: Verify:
-   - Email Support
+1. Command syntax
-   - Community Forums 
+2. Device availability
+3. User permissions
+4. Home Assistant API access 

docs/usage.md

@@ -0,0 +1,34 @@
+# Usage Guide
+
+This guide explains how to use the Home Assistant MCP Server for smart home device management and integration with language learning systems.
+
+## Basic Usage
+
+1. **Starting the Server:**
+   - For development: run `npm run dev`.
+   - For production: run `npm run build` followed by `npm start`.
+
+2. **Accessing the Web Interface:**
+   - Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+3. **Real-Time Updates:**
+   - Connect to the SSE endpoint at `/subscribe_events?token=YOUR_TOKEN&domain=light` to receive live updates.
+
+## Advanced Features
+
+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.
+
+2. **Tool Integrations:**
+   - Multiple tools are available (see [Tools Documentation](tools/tools.md)), for tasks like automation management and notifications.
+
+3. **Security Settings:**
+   - Configure token-based authentication and environment variables as per the [Configuration Guide](getting-started/configuration.md).
+
+4. **Customization and Extensions:**
+   - Extend server functionality by developing new tools as outlined in the [Development Guide](development/development.md).
+
+## Troubleshooting
+
+If you experience issues, review the [Troubleshooting Guide](troubleshooting.md). 

examples/README.md

@@ -0,0 +1,91 @@
+# Speech-to-Text Examples
+
+This directory contains examples demonstrating how to use the speech-to-text integration with wake word detection.
+
+## Prerequisites
+
+1. Make sure you have Docker installed and running
+2. Build and start the services:
+   ```bash
+   docker-compose up -d
+   ```
+
+## Running the Example
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Run the example:
+   ```bash
+   npm run example:speech
+   ```
+
+   Or using `ts-node` directly:
+   ```bash
+   npx ts-node examples/speech-to-text-example.ts
+   ```
+
+## Features Demonstrated
+
+1. **Wake Word Detection**
+   - Listens for wake words: "hey jarvis", "ok google", "alexa"
+   - Automatically saves audio when wake word is detected
+   - Transcribes the detected speech
+
+2. **Manual Transcription**
+   - Example of how to transcribe audio files manually
+   - Supports different models and configurations
+
+3. **Event Handling**
+   - Wake word detection events
+   - Transcription results
+   - Progress updates
+   - Error handling
+
+## Example Output
+
+When a wake word is detected, you'll see output like this:
+
+```
+🎤 Wake word detected!
+  Timestamp: 20240203_123456
+  Audio file: /path/to/audio/wake_word_20240203_123456.wav
+  Metadata file: /path/to/audio/wake_word_20240203_123456.wav.json
+
+📝 Transcription result:
+  Full text: This is what was said after the wake word.
+
+  Segments:
+    1. [0.00s - 1.52s] (95.5% confidence)
+       "This is what was said"
+    2. [1.52s - 2.34s] (98.2% confidence)
+       "after the wake word."
+```
+
+## Customization
+
+You can customize the behavior by:
+
+1. Changing the wake word models in `docker/speech/Dockerfile`
+2. Modifying transcription options in the example file
+3. Adding your own event handlers
+4. Implementing different audio processing logic
+
+## Troubleshooting
+
+1. **Docker Issues**
+   - Make sure Docker is running
+   - Check container logs: `docker-compose logs fast-whisper`
+   - Verify container is up: `docker ps`
+
+2. **Audio Issues**
+   - Check audio device permissions
+   - Verify audio file format (WAV files recommended)
+   - Check audio file permissions
+
+3. **Performance Issues**
+   - Try using a smaller model (tiny.en or base.en)
+   - Adjust beam size and patience parameters
+   - Consider using GPU acceleration if available 

examples/speech-to-text-example.ts

@@ -0,0 +1,91 @@
+import { SpeechToText, TranscriptionResult, WakeWordEvent } from '../src/speech/speechToText';
+import path from 'path';
+
+async function main() {
+    // Initialize the speech-to-text service
+    const speech = new SpeechToText('fast-whisper');
+
+    // Check if the service is available
+    const isHealthy = await speech.checkHealth();
+    if (!isHealthy) {
+        console.error('Speech service is not available. Make sure Docker is running and the fast-whisper container is up.');
+        console.error('Run: docker-compose up -d');
+        process.exit(1);
+    }
+
+    console.log('Speech service is ready!');
+    console.log('Listening for wake words: "hey jarvis", "ok google", "alexa"');
+    console.log('Press Ctrl+C to exit');
+
+    // Set up event handlers
+    speech.on('wake_word', (event: WakeWordEvent) => {
+        console.log('\n🎤 Wake word detected!');
+        console.log('  Timestamp:', event.timestamp);
+        console.log('  Audio file:', event.audioFile);
+        console.log('  Metadata file:', event.metadataFile);
+    });
+
+    speech.on('transcription', (event: { audioFile: string; result: TranscriptionResult }) => {
+        console.log('\n📝 Transcription result:');
+        console.log('  Full text:', event.result.text);
+        console.log('\n  Segments:');
+        event.result.segments.forEach((segment, index) => {
+            console.log(`    ${index + 1}. [${segment.start.toFixed(2)}s - ${segment.end.toFixed(2)}s] (${(segment.confidence * 100).toFixed(1)}% confidence)`);
+            console.log(`       "${segment.text}"`);
+        });
+    });
+
+    speech.on('progress', (event: { type: string; data: string }) => {
+        if (event.type === 'stderr' && !event.data.includes('Loading model')) {
+            console.error('❌ Error:', event.data);
+        }
+    });
+
+    speech.on('error', (error: Error) => {
+        console.error('❌ Error:', error.message);
+    });
+
+    // Example of manual transcription
+    async function transcribeFile(filepath: string) {
+        try {
+            console.log(`\n🎯 Manually transcribing: ${filepath}`);
+            const result = await speech.transcribeAudio(filepath, {
+                model: 'base.en',  // You can change this to tiny.en, small.en, medium.en, or large-v2
+                language: 'en',
+                temperature: 0,
+                beamSize: 5
+            });
+
+            console.log('\n📝 Transcription result:');
+            console.log('  Text:', result.text);
+        } catch (error) {
+            console.error('❌ Transcription failed:', error instanceof Error ? error.message : error);
+        }
+    }
+
+    // Create audio directory if it doesn't exist
+    const audioDir = path.join(__dirname, '..', 'audio');
+    if (!require('fs').existsSync(audioDir)) {
+        require('fs').mkdirSync(audioDir, { recursive: true });
+    }
+
+    // Start wake word detection
+    speech.startWakeWordDetection(audioDir);
+
+    // Example: You can also manually transcribe files
+    // Uncomment the following line and replace with your audio file:
+    // await transcribeFile('/path/to/your/audio.wav');
+
+    // Keep the process running
+    process.on('SIGINT', () => {
+        console.log('\nStopping speech service...');
+        speech.stopWakeWordDetection();
+        process.exit(0);
+    });
+}
+
+// Run the example
+main().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+}); 

extra/claude-desktop-macos-setup.sh

@@ -327,3 +327,7 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
         echo -e "${GREEN}Home Assistant MCP test successful!${NC}"
     fi
 fi
+
+# macOS environment configuration
+HASS_SOCKET_URL="${HASS_HOST/http/ws}/api/websocket" # WebSocket URL conversion
+chmod 600 "$CLAUDE_CONFIG_DIR/claude_desktop_config.json" # Security hardening 

jest-resolver.cjs

@@ -1,85 +0,0 @@
-const path = require('path');
-
-module.exports = (request, options) => {
-    // Handle chalk and related packages
-    if (request === 'chalk' || request === '#ansi-styles' || request === '#supports-color') {
-        return path.resolve(__dirname, 'node_modules', request.replace('#', ''));
-    }
-
-    // Handle source files with .js extension
-    if (request.endsWith('.js')) {
-        const tsRequest = request.replace(/\.js$/, '.ts');
-        try {
-            return options.defaultResolver(tsRequest, {
-                ...options,
-                packageFilter: pkg => {
-                    if (pkg.type === 'module') {
-                        if (pkg.exports && pkg.exports.import) {
-                            pkg.main = pkg.exports.import;
-                        } else if (pkg.module) {
-                            pkg.main = pkg.module;
-                        }
-                    }
-                    return pkg;
-                }
-            });
-        } catch (e) {
-            // If the .ts file doesn't exist, try resolving without extension
-            try {
-                return options.defaultResolver(request.replace(/\.js$/, ''), options);
-            } catch (e2) {
-                // If that fails too, try resolving with .ts extension
-                try {
-                    return options.defaultResolver(tsRequest, options);
-                } catch (e3) {
-                    // If all attempts fail, try resolving the original request
-                    return options.defaultResolver(request, options);
-                }
-            }
-        }
-    }
-
-    // Handle @digital-alchemy packages
-    if (request.startsWith('@digital-alchemy/')) {
-        try {
-            const packagePath = path.resolve(__dirname, 'node_modules', request);
-            return options.defaultResolver(packagePath, {
-                ...options,
-                packageFilter: pkg => {
-                    if (pkg.type === 'module') {
-                        if (pkg.exports && pkg.exports.import) {
-                            pkg.main = pkg.exports.import;
-                        } else if (pkg.module) {
-                            pkg.main = pkg.module;
-                        }
-                    }
-                    return pkg;
-                }
-            });
-        } catch (e) {
-            // If resolution fails, continue with default resolver
-        }
-    }
-
-    // Call the default resolver with enhanced module resolution
-    return options.defaultResolver(request, {
-        ...options,
-        // Handle ESM modules
-        packageFilter: pkg => {
-            if (pkg.type === 'module') {
-                if (pkg.exports) {
-                    if (pkg.exports.import) {
-                        pkg.main = pkg.exports.import;
-                    } else if (typeof pkg.exports === 'string') {
-                        pkg.main = pkg.exports;
-                    }
-                } else if (pkg.module) {
-                    pkg.main = pkg.module;
-                }
-            }
-            return pkg;
-        },
-        extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
-        paths: [...(options.paths || []), path.resolve(__dirname, 'src')]
-    });
-}; 

jest.config.cjs

@@ -1,17 +0,0 @@
-/** @type {import('bun:test').BunTestConfig} */
-module.exports = {
-    testEnvironment: 'node',
-    moduleFileExtensions: ['ts', 'js', 'json', 'node'],
-    testMatch: ['**/__tests__/**/*.test.ts'],
-    collectCoverage: true,
-    coverageDirectory: 'coverage',
-    coverageThreshold: {
-        global: {
-            statements: 50,
-            branches: 50,
-            functions: 50,
-            lines: 50
-        }
-    },
-    setupFilesAfterEnv: ['./jest.setup.ts']
-}; 

jest.setup.ts

@@ -1,87 +0,0 @@
-import { jest } from '@jest/globals';
-import dotenv from 'dotenv';
-import { TextEncoder, TextDecoder } from 'util';
-
-// Load test environment variables
-dotenv.config({ path: '.env.test' });
-
-// Set test environment
-process.env.NODE_ENV = 'test';
-process.env.ENCRYPTION_KEY = 'test-encryption-key-32-bytes-long!!!';
-process.env.JWT_SECRET = 'test-jwt-secret';
-process.env.HASS_URL = 'http://localhost:8123';
-process.env.HASS_TOKEN = 'test-token';
-process.env.CLAUDE_API_KEY = 'test_api_key';
-process.env.CLAUDE_MODEL = 'test_model';
-
-// Add TextEncoder and TextDecoder to global scope
-Object.defineProperty(global, 'TextEncoder', {
-    value: TextEncoder,
-    writable: true
-});
-
-Object.defineProperty(global, 'TextDecoder', {
-    value: TextDecoder,
-    writable: true
-});
-
-// Configure console for tests
-const originalConsole = { ...console };
-global.console = {
-    ...console,
-    log: jest.fn(),
-    error: jest.fn(),
-    warn: jest.fn(),
-    info: jest.fn(),
-    debug: jest.fn(),
-};
-
-// Increase test timeout
-jest.setTimeout(30000);
-
-// Mock WebSocket
-jest.mock('ws', () => {
-    return {
-        WebSocket: jest.fn().mockImplementation(() => ({
-            on: jest.fn(),
-            send: jest.fn(),
-            close: jest.fn(),
-            removeAllListeners: jest.fn()
-        }))
-    };
-});
-
-// Mock chalk
-const createChalkMock = () => {
-    const handler = {
-        get(target: any, prop: string) {
-            if (prop === 'default') {
-                return createChalkMock();
-            }
-            return typeof prop === 'string' ? createChalkMock() : target[prop];
-        },
-        apply(target: any, thisArg: any, args: any[]) {
-            return args[0];
-        }
-    };
-    return new Proxy(() => { }, handler);
-};
-
-jest.mock('chalk', () => createChalkMock());
-
-// Mock ansi-styles
-jest.mock('ansi-styles', () => ({}), { virtual: true });
-
-// Mock supports-color
-jest.mock('supports-color', () => ({}), { virtual: true });
-
-// Reset mocks between tests
-beforeEach(() => {
-    jest.clearAllMocks();
-});
-
-// Cleanup after tests
-afterEach(() => {
-    jest.clearAllTimers();
-    jest.clearAllMocks();
-}); 

mkdocs.yml

@@ -0,0 +1,141 @@
+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/
+repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
+repo_name: jango-blockchained/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
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+
+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
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - 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
+
+plugins:
+  - search
+  - git-revision-date-localized:
+      type: date
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            show_source: true
+
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Overview: getting-started.md
+    - Installation: getting-started/installation.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
+    - SSE API: api/sse.md
+    - Core Functions: api/core.md
+  - Tools:
+    - Overview: tools/tools.md
+    - Device Management:
+      - List Devices: tools/device-management/list-devices.md
+      - Device Control: tools/device-management/control.md
+    - History & State:
+      - History: tools/history-state/history.md
+      - Scene Management: tools/history-state/scene.md
+    - Automation:
+      - Automation Management: tools/automation/automation.md
+      - Automation Configuration: tools/automation/automation-config.md
+    - Add-ons & Packages:
+      - Add-on Management: tools/addons-packages/addon.md
+      - Package Management: tools/addons-packages/package.md
+    - Notifications:
+      - Notify: tools/notifications/notify.md
+    - Events:
+      - Event Subscription: tools/events/subscribe-events.md
+      - SSE Statistics: tools/events/sse-stats.md
+  - Development:
+    - Overview: development/development.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
+  - 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 

package.json

@@ -1,66 +1,63 @@
 {
   "name": "homeassistant-mcp",
-  "version": "0.1.0",
+  "version": "1.0.0",
-  "description": "Model Context Protocol Server for Home Assistant",
+  "description": "Home Assistant Model Context Protocol",
-  "type": "module",
   "main": "dist/index.js",
+  "type": "module",
   "scripts": {
-    "build": "bun run tsc",
+    "start": "bun run dist/index.js",
-    "start": "bun run dist/src/index.js",
+    "dev": "bun --hot --watch src/index.ts",
-    "dev": "bun --watch src/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --minify",
     "test": "bun test",
-    "test:coverage": "bun test --coverage",
     "test:watch": "bun test --watch",
-    "test:openai": "bun run openai_test.ts",
+    "test:coverage": "bun test --coverage",
-    "lint": "eslint src --ext .ts",
+    "test:ci": "bun test --coverage --bail",
-    "lint:fix": "eslint src --ext .ts --fix",
+    "test:update": "bun test --update-snapshots",
-    "prepare": "bun run build",
+    "test:clear": "bun test --clear-cache",
-    "clean": "rimraf dist",
+    "test:staged": "bun test --findRelatedTests",
-    "types:check": "tsc --noEmit",
+    "lint": "eslint . --ext .ts",
-    "types:install": "bun add -d @types/node @types/jest"
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepare": "husky install",
+    "profile": "bun --inspect src/index.ts",
+    "clean": "rm -rf dist .bun coverage",
+    "typecheck": "bun x tsc --noEmit",
+    "example:speech": "bun run examples/speech-to-text-example.ts"
   },
   "dependencies": {
-    "@digital-alchemy/core": "^24.11.4",
+    "@elysiajs/cors": "^1.2.0",
-    "@digital-alchemy/hass": "^24.11.4",
+    "@elysiajs/swagger": "^1.2.0",
-    "@types/chalk": "^0.4.31",
+    "@types/jsonwebtoken": "^9.0.5",
-    "@types/jsonwebtoken": "^9.0.8",
+    "@types/node": "^20.11.24",
-    "@types/xmldom": "^0.1.34",
+    "@types/sanitize-html": "^2.9.5",
+    "@types/ws": "^8.5.10",
     "@xmldom/xmldom": "^0.9.7",
-    "ajv": "^8.12.0",
+    "dotenv": "^16.4.5",
-    "chalk": "^5.4.1",
+    "elysia": "^1.2.11",
-    "dotenv": "^16.3.1",
-    "express": "^4.18.2",
-    "express-rate-limit": "^7.1.5",
     "helmet": "^7.1.0",
     "jsonwebtoken": "^9.0.2",
-    "litemcp": "^0.7.0",
+    "node-fetch": "^3.3.2",
-    "uuid": "^9.0.1",
+    "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/ajv": "^1.0.0",
+    "@types/uuid": "^10.0.0",
-    "@types/express": "^4.17.21",
+    "@typescript-eslint/eslint-plugin": "^7.1.0",
-    "@types/express-rate-limit": "^6.0.0",
+    "@typescript-eslint/parser": "^7.1.0",
-    "@types/glob": "^8.1.0",
+    "bun-types": "^1.2.2",
-    "@types/helmet": "^4.0.0",
+    "eslint": "^8.57.0",
-    "@types/jest": "^29.5.14",
+    "eslint-config-prettier": "^9.1.0",
-    "@types/node": "^20.17.16",
+    "eslint-plugin-prettier": "^5.1.3",
-    "@types/supertest": "^6.0.2",
+    "husky": "^9.0.11",
-    "@types/uuid": "^9.0.8",
+    "prettier": "^3.2.5",
-    "@types/winston": "^2.4.4",
+    "supertest": "^6.3.3",
-    "@types/ws": "^8.5.10",
+    "uuid": "^11.0.5"
-    "jest": "^29.7.0",
-    "node-fetch": "^3.3.2",
-    "openai": "^4.82.0",
-    "rimraf": "^5.0.10",
-    "supertest": "^6.3.4",
-    "ts-jest": "^29.1.2",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.3"
   },
-  "author": "Jango Blockchained",
+  "engines": {
-  "license": "MIT",
+    "bun": ">=1.0.0"
-  "packageManager": "bun@1.0.26"
+  }
 }

scripts/start_mcp.cmd

@@ -0,0 +1,21 @@
+@echo off
+setlocal
+
+:: Set environment variables
+set NODE_ENV=production
+
+:: Change to the script's directory
+cd /d "%~dp0"
+cd ..
+
+:: Start the MCP server
+echo Starting Home Assistant MCP Server...
+bun run start --port 8080
+
+if errorlevel 1 (
+    echo Error starting MCP server
+    pause
+    exit /b 1
+)
+
+pause 

smithery.yaml

@@ -0,0 +1,28 @@
+# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
+
+startCommand:
+  type: stdio
+  configSchema:
+    # JSON Schema defining the configuration options for the MCP.
+    type: object
+    required:
+      - hassToken
+    properties:
+      hassToken:
+        type: string
+        description: The token for connecting to Home Assistant API.
+      port:
+        type: number
+        default: 4000
+        description: The port on which the MCP server will run.
+  commandFunction:
+    # A function that produces the CLI command to start the MCP on stdio.
+    |-
+    config => ({
+      command: 'bun', 
+      args: ['--smol', 'run', 'start'], 
+      env: { 
+        HASS_TOKEN: config.hassToken,
+        PORT: config.port.toString()
+      }
+    })

src/__mocks__/@digital-alchemy/hass.ts

@@ -0,0 +1,77 @@
+import { mock } from "bun:test";
+
+export const LIB_HASS = {
+  configuration: {
+    name: "Home Assistant",
+    version: "2024.2.0",
+    location_name: "Home",
+    time_zone: "UTC",
+    components: ["automation", "script", "light", "switch"],
+    unit_system: {
+      temperature: "°C",
+      length: "m",
+      mass: "kg",
+      pressure: "hPa",
+      volume: "L",
+    },
+  },
+  services: {
+    light: {
+      turn_on: mock(() => Promise.resolve()),
+      turn_off: mock(() => Promise.resolve()),
+      toggle: mock(() => Promise.resolve()),
+    },
+    switch: {
+      turn_on: mock(() => Promise.resolve()),
+      turn_off: mock(() => Promise.resolve()),
+      toggle: mock(() => Promise.resolve()),
+    },
+    automation: {
+      trigger: mock(() => Promise.resolve()),
+      turn_on: mock(() => Promise.resolve()),
+      turn_off: mock(() => Promise.resolve()),
+    },
+    script: {
+      turn_on: mock(() => Promise.resolve()),
+      turn_off: mock(() => Promise.resolve()),
+      toggle: mock(() => Promise.resolve()),
+    },
+  },
+  states: {
+    light: {
+      "light.living_room": {
+        state: "on",
+        attributes: {
+          brightness: 255,
+          color_temp: 300,
+          friendly_name: "Living Room Light",
+        },
+      },
+      "light.bedroom": {
+        state: "off",
+        attributes: {
+          friendly_name: "Bedroom Light",
+        },
+      },
+    },
+    switch: {
+      "switch.tv": {
+        state: "off",
+        attributes: {
+          friendly_name: "TV",
+        },
+      },
+    },
+  },
+  events: {
+    subscribe: mock(() => Promise.resolve()),
+    unsubscribe: mock(() => Promise.resolve()),
+    fire: mock(() => Promise.resolve()),
+  },
+  connection: {
+    subscribeEvents: mock(() => Promise.resolve()),
+    subscribeMessage: mock(() => Promise.resolve()),
+    sendMessage: mock(() => Promise.resolve()),
+    close: mock(() => Promise.resolve()),
+  },
+};

src/__mocks__/litemcp.ts

@@ -0,0 +1,61 @@
+export class LiteMCP {
+  name: string;
+  version: string;
+  config: any;
+
+  constructor(config: any = {}) {
+    this.name = "home-assistant";
+    this.version = "1.0.0";
+    this.config = config;
+  }
+
+  async start() {
+    return Promise.resolve();
+  }
+
+  async stop() {
+    return Promise.resolve();
+  }
+
+  async connect() {
+    return Promise.resolve();
+  }
+
+  async disconnect() {
+    return Promise.resolve();
+  }
+
+  async callService(domain: string, service: string, data: any = {}) {
+    return Promise.resolve({ success: true });
+  }
+
+  async getStates() {
+    return Promise.resolve([]);
+  }
+
+  async getState(entityId: string) {
+    return Promise.resolve({
+      entity_id: entityId,
+      state: "unknown",
+      attributes: {},
+      last_changed: new Date().toISOString(),
+      last_updated: new Date().toISOString(),
+    });
+  }
+
+  async setState(entityId: string, state: string, attributes: any = {}) {
+    return Promise.resolve({ success: true });
+  }
+
+  onStateChanged(callback: (event: any) => void) {
+    // Mock implementation
+  }
+
+  onEvent(eventType: string, callback: (event: any) => void) {
+    // Mock implementation
+  }
+}
+
+export const createMCP = (config: any = {}) => {
+  return new LiteMCP(config);
+};

src/__tests__/setup.ts

@@ -0,0 +1,143 @@
+import { config } from "dotenv";
+import path from "path";
+import {
+  beforeAll,
+  afterAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  mock,
+  test,
+} from "bun:test";
+
+// Type definitions for mocks
+type MockFn = ReturnType<typeof mock>;
+
+interface MockInstance {
+  mock: {
+    calls: unknown[][];
+    results: unknown[];
+    instances: unknown[];
+    lastCall?: unknown[];
+  };
+}
+
+// Test configuration
+const TEST_CONFIG = {
+  TEST_JWT_SECRET: "test_jwt_secret_key_that_is_at_least_32_chars",
+  TEST_TOKEN: "test_token_that_is_at_least_32_chars_long",
+  TEST_CLIENT_IP: "127.0.0.1",
+};
+
+// Load test environment variables
+config({ path: path.resolve(process.cwd(), ".env.test") });
+
+// Global test setup
+beforeAll(() => {
+  // Set required environment variables
+  process.env.NODE_ENV = "test";
+  process.env.JWT_SECRET = TEST_CONFIG.TEST_JWT_SECRET;
+  process.env.TEST_TOKEN = TEST_CONFIG.TEST_TOKEN;
+
+  // Configure console output for tests
+  if (!process.env.DEBUG) {
+    console.error = mock(() => { });
+    console.warn = mock(() => { });
+    console.log = mock(() => { });
+  }
+});
+
+// Reset mocks between tests
+beforeEach(() => {
+  // Clear all mock function calls
+  const mockFns = Object.values(mock).filter(
+    (value): value is MockFn => typeof value === "function" && "mock" in value,
+  );
+  mockFns.forEach((mockFn) => {
+    if (mockFn.mock) {
+      mockFn.mock.calls = [];
+      mockFn.mock.results = [];
+      mockFn.mock.instances = [];
+      mockFn.mock.lastCall = undefined;
+    }
+  });
+});
+
+// Custom test utilities
+const testUtils = {
+  // Mock WebSocket for SSE tests
+  mockWebSocket: () => ({
+    on: mock(() => { }),
+    send: mock(() => { }),
+    close: mock(() => { }),
+    readyState: 1,
+    OPEN: 1,
+    removeAllListeners: mock(() => { }),
+  }),
+
+  // Mock HTTP response for API tests
+  mockResponse: () => {
+    const res = {
+      status: mock(() => res),
+      json: mock(() => res),
+      send: mock(() => res),
+      end: mock(() => res),
+      setHeader: mock(() => res),
+      writeHead: mock(() => res),
+      write: mock(() => true),
+      removeHeader: mock(() => res),
+    };
+    return res;
+  },
+
+  // Mock HTTP request for API tests
+  mockRequest: (overrides: Record<string, unknown> = {}) => ({
+    headers: { "content-type": "application/json" },
+    body: {},
+    query: {},
+    params: {},
+    ip: TEST_CONFIG.TEST_CLIENT_IP,
+    method: "GET",
+    path: "/api/test",
+    is: mock((type: string) => type === "application/json"),
+    ...overrides,
+  }),
+
+  // Create test client for SSE tests
+  createTestClient: (id = "test-client") => ({
+    id,
+    ip: TEST_CONFIG.TEST_CLIENT_IP,
+    connectedAt: new Date(),
+    send: mock(() => { }),
+    rateLimit: {
+      count: 0,
+      lastReset: Date.now(),
+    },
+    connectionTime: Date.now(),
+  }),
+
+  // Create test event for SSE tests
+  createTestEvent: (type = "test_event", data: unknown = {}) => ({
+    event_type: type,
+    data,
+    origin: "test",
+    time_fired: new Date().toISOString(),
+    context: { id: "test" },
+  }),
+
+  // Create test entity for Home Assistant tests
+  createTestEntity: (entityId = "test.entity", state = "on") => ({
+    entity_id: entityId,
+    state,
+    attributes: {},
+    last_changed: new Date().toISOString(),
+    last_updated: new Date().toISOString(),
+  }),
+
+  // Helper to wait for async operations
+  wait: (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+
+// Export test utilities and Bun test functions
+export { beforeAll, afterAll, beforeEach, describe, expect, it, mock, test, testUtils };

src/ai/endpoints/ai-router.ts

@@ -1,8 +1,14 @@
-import express from 'express';
+import express from "express";
-import { z } from 'zod';
+import { z } from "zod";
-import { NLPProcessor } from '../nlp/processor.js';
+import { NLPProcessor } from "../nlp/processor.js";
-import { AIRateLimit, AIContext, AIResponse, AIError, AIModel } from '../types/index.js';
+import {
-import rateLimit from 'express-rate-limit';
+  AIRateLimit,
+  AIContext,
+  AIResponse,
+  AIError,
+  AIModel,
+} from "../types/index.js";
+import rateLimit from "express-rate-limit";
 
 const router = express.Router();
 const nlpProcessor = new NLPProcessor();
@@ -15,17 +21,17 @@ const rateLimitConfig: AIRateLimit = {
   model_specific_limits: {
     claude: {
       requests_per_minute: 100,
-            requests_per_hour: 1000
+      requests_per_hour: 1000,
     },
     gpt4: {
       requests_per_minute: 50,
-            requests_per_hour: 500
+      requests_per_hour: 500,
     },
     custom: {
       requests_per_minute: 200,
-            requests_per_hour: 2000
+      requests_per_hour: 2000,
-        }
+    },
-    }
+  },
 };
 
 // Request validation schemas
@@ -37,21 +43,23 @@ const interpretRequestSchema = z.object({
     timestamp: z.string(),
     location: z.string(),
     previous_actions: z.array(z.any()),
-        environment_state: z.record(z.any())
+    environment_state: z.record(z.any()),
   }),
-    model: z.enum(['claude', 'gpt4', 'custom']).optional()
+  model: z.enum(["claude", "gpt4", "custom"]).optional(),
 });
 
 // Rate limiters
 const globalLimiter = rateLimit({
   windowMs: 60 * 1000, // 1 minute
-    max: rateLimitConfig.requests_per_minute
+  max: rateLimitConfig.requests_per_minute,
 });
 
-const modelSpecificLimiter = (model: string) => rateLimit({
+const modelSpecificLimiter = (model: string) =>
+  rateLimit({
     windowMs: 60 * 1000,
-    max: rateLimitConfig.model_specific_limits[model as AIModel]?.requests_per_minute ||
+    max:
-        rateLimitConfig.requests_per_minute
+      rateLimitConfig.model_specific_limits[model as AIModel]
+        ?.requests_per_minute || rateLimitConfig.requests_per_minute,
   });
 
 // Error handler middleware
@@ -59,18 +67,18 @@ const errorHandler = (
   error: Error,
   req: express.Request,
   res: express.Response,
-    next: express.NextFunction
+  next: express.NextFunction,
 ) => {
   const aiError: AIError = {
-        code: 'PROCESSING_ERROR',
+    code: "PROCESSING_ERROR",
     message: error.message,
-        suggestion: 'Please try again with a different command format',
+    suggestion: "Please try again with a different command format",
     recovery_options: [
-            'Simplify your command',
+      "Simplify your command",
-            'Use standard command patterns',
+      "Use standard command patterns",
-            'Check device names and parameters'
+      "Check device names and parameters",
     ],
-        context: req.body.context
+    context: req.body.context,
   };
 
   res.status(500).json({ error: aiError });
@@ -78,15 +86,26 @@ const errorHandler = (
 
 // Endpoints
 router.post(
-    '/interpret',
+  "/interpret",
   globalLimiter,
-    async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+  async (
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction,
+  ) => {
     try {
-            const { input, context, model = 'claude' } = interpretRequestSchema.parse(req.body);
+      const {
+        input,
+        context,
+        model = "claude",
+      } = interpretRequestSchema.parse(req.body);
 
       // Apply model-specific rate limiting
       modelSpecificLimiter(model)(req, res, async () => {
-                const { intent, confidence, error } = await nlpProcessor.processCommand(input, context);
+        const { intent, confidence, error } = await nlpProcessor.processCommand(
+          input,
+          context,
+        );
 
         if (error) {
           return res.status(400).json({ error });
@@ -96,39 +115,39 @@ router.post(
 
         if (!isValid) {
           const suggestions = await nlpProcessor.suggestCorrections(input, {
-                        code: 'INVALID_INTENT',
+            code: "INVALID_INTENT",
-                        message: 'Could not understand the command with high confidence',
+            message: "Could not understand the command with high confidence",
-                        suggestion: 'Please try rephrasing your command',
+            suggestion: "Please try rephrasing your command",
             recovery_options: [],
-                        context
+            context,
           });
 
           return res.status(400).json({
             error: {
-                            code: 'INVALID_INTENT',
+              code: "INVALID_INTENT",
-                            message: 'Could not understand the command with high confidence',
+              message: "Could not understand the command with high confidence",
-                            suggestion: 'Please try rephrasing your command',
+              suggestion: "Please try rephrasing your command",
               recovery_options: suggestions,
-                            context
+              context,
-                        }
+            },
           });
         }
 
         const response: AIResponse = {
-                    natural_language: `I'll ${intent.action} the ${intent.target.split('.').pop()}`,
+          natural_language: `I'll ${intent.action} the ${intent.target.split(".").pop()}`,
           structured_data: {
             success: true,
             action_taken: intent.action,
             entities_affected: [intent.target],
-                        state_changes: intent.parameters
+            state_changes: intent.parameters,
           },
           next_suggestions: [
-                        'Would you like to adjust any settings?',
+            "Would you like to adjust any settings?",
-                        'Should I perform this action in other rooms?',
+            "Should I perform this action in other rooms?",
-                        'Would you like to schedule this action?'
+            "Would you like to schedule this action?",
           ],
           confidence,
-                    context
+          context,
         };
 
         res.json(response);
@@ -136,15 +155,19 @@ router.post(
     } catch (error) {
       next(error);
     }
-    }
+  },
 );
 
 router.post(
-    '/execute',
+  "/execute",
   globalLimiter,
-    async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+  async (
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction,
+  ) => {
     try {
-            const { intent, context, model = 'claude' } = req.body;
+      const { intent, context, model = "claude" } = req.body;
 
       // Apply model-specific rate limiting
       modelSpecificLimiter(model)(req, res, async () => {
@@ -157,15 +180,15 @@ router.post(
             success: true,
             action_taken: intent.action,
             entities_affected: [intent.target],
-                        state_changes: intent.parameters
+            state_changes: intent.parameters,
           },
           next_suggestions: [
-                        'Would you like to verify the state?',
+            "Would you like to verify the state?",
-                        'Should I perform any related actions?',
+            "Should I perform any related actions?",
-                        'Would you like to undo this action?'
+            "Would you like to undo this action?",
           ],
           confidence: { overall: 1, intent: 1, entities: 1, context: 1 },
-                    context
+          context,
         };
 
         res.json(response);
@@ -173,24 +196,28 @@ router.post(
     } catch (error) {
       next(error);
     }
-    }
+  },
 );
 
 router.get(
-    '/suggestions',
+  "/suggestions",
   globalLimiter,
-    async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+  async (
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction,
+  ) => {
     try {
-            const { context, model = 'claude' } = req.body;
+      const { context, model = "claude" } = req.body;
 
       // Apply model-specific rate limiting
       modelSpecificLimiter(model)(req, res, async () => {
         // Generate context-aware suggestions
         const suggestions = [
-                    'Turn on the lights in the living room',
+          "Turn on the lights in the living room",
-                    'Set the temperature to 72 degrees',
+          "Set the temperature to 72 degrees",
-                    'Show me the current state of all devices',
+          "Show me the current state of all devices",
-                    'Start the evening routine'
+          "Start the evening routine",
         ];
 
         res.json({ suggestions });
@@ -198,7 +225,7 @@ router.get(
     } catch (error) {
       next(error);
     }
-    }
+  },
 );
 
 // Apply error handler

src/ai/nlp/context-analyzer.ts

@@ -1,4 +1,4 @@
-import { AIContext, AIIntent } from '../types/index.js';
+import { AIContext, AIIntent } from "../types/index.js";
 
 interface ContextAnalysis {
   confidence: number;
@@ -19,9 +19,12 @@ export class ContextAnalyzer {
       // Location-based context
       {
         condition: (context, intent) =>
-                    Boolean(context.location && intent.target.includes(context.location.toLowerCase())),
+          Boolean(
+            context.location &&
+              intent.target.includes(context.location.toLowerCase()),
+          ),
         relevance: 0.8,
-                params: (context) => ({ location: context.location })
+        params: (context) => ({ location: context.location }),
       },
 
       // Time-based context
@@ -32,40 +35,46 @@ export class ContextAnalyzer {
         },
         relevance: 0.6,
         params: (context) => ({
-                    time_of_day: this.getTimeOfDay(new Date(context.timestamp))
+          time_of_day: this.getTimeOfDay(new Date(context.timestamp)),
-                })
+        }),
       },
 
       // Previous action context
       {
         condition: (context, intent) => {
           const recentActions = context.previous_actions.slice(-3);
-                    return recentActions.some(action =>
+          return recentActions.some(
+            (action) =>
               action.target === intent.target ||
-                        action.action === intent.action
+              action.action === intent.action,
           );
         },
         relevance: 0.7,
         params: (context) => ({
-                    recent_action: context.previous_actions[context.previous_actions.length - 1]
+          recent_action:
-                })
+            context.previous_actions[context.previous_actions.length - 1],
+        }),
       },
 
       // Environment state context
       {
         condition: (context, intent) => {
-                    return Object.keys(context.environment_state).some(key =>
+          return Object.keys(context.environment_state).some(
+            (key) =>
               intent.target.includes(key) ||
-                        intent.parameters[key] !== undefined
+              intent.parameters[key] !== undefined,
           );
         },
         relevance: 0.9,
-                params: (context) => ({ environment: context.environment_state })
+        params: (context) => ({ environment: context.environment_state }),
-            }
+      },
     ];
   }
 
-    async analyze(intent: AIIntent, context: AIContext): Promise<ContextAnalysis> {
+  async analyze(
+    intent: AIIntent,
+    context: AIContext,
+  ): Promise<ContextAnalysis> {
     let totalConfidence = 0;
     let relevantParams: Record<string, any> = {};
     let applicableRules = 0;
@@ -78,30 +87,29 @@ export class ContextAnalyzer {
         if (rule.params) {
           relevantParams = {
             ...relevantParams,
-                        ...rule.params(context)
+            ...rule.params(context),
           };
         }
       }
     }
 
     // Calculate normalized confidence
-        const confidence = applicableRules > 0
+    const confidence =
-            ? totalConfidence / applicableRules
+      applicableRules > 0 ? totalConfidence / applicableRules : 0.5; // Default confidence if no rules apply
-            : 0.5; // Default confidence if no rules apply
 
     return {
       confidence,
-            relevant_params: relevantParams
+      relevant_params: relevantParams,
     };
   }
 
   private getTimeOfDay(date: Date): string {
     const hour = date.getHours();
 
-        if (hour >= 5 && hour < 12) return 'morning';
+    if (hour >= 5 && hour < 12) return "morning";
-        if (hour >= 12 && hour < 17) return 'afternoon';
+    if (hour >= 12 && hour < 17) return "afternoon";
-        if (hour >= 17 && hour < 22) return 'evening';
+    if (hour >= 17 && hour < 22) return "evening";
-        return 'night';
+    return "night";
   }
 
   async updateContextRules(newRules: ContextRule[]): Promise<void> {
@@ -126,7 +134,10 @@ export class ContextAnalyzer {
     }
 
     // Validate environment state
-        if (typeof context.environment_state !== 'object' || context.environment_state === null) {
+    if (
+      typeof context.environment_state !== "object" ||
+      context.environment_state === null
+    ) {
       return false;
     }
 

src/ai/nlp/entity-extractor.ts

@@ -1,4 +1,4 @@
-import { AIContext } from '../types/index.js';
+import { AIContext } from "../types/index.js";
 
 interface ExtractedEntities {
   primary_target: string;
@@ -18,21 +18,24 @@ export class EntityExtractor {
 
   private initializePatterns(): void {
     // Device name variations
-        this.deviceNameMap.set('living room light', 'light.living_room');
+    this.deviceNameMap.set("living room light", "light.living_room");
-        this.deviceNameMap.set('kitchen light', 'light.kitchen');
+    this.deviceNameMap.set("kitchen light", "light.kitchen");
-        this.deviceNameMap.set('bedroom light', 'light.bedroom');
+    this.deviceNameMap.set("bedroom light", "light.bedroom");
 
     // Parameter patterns
-        this.parameterPatterns.set('brightness', /(\d+)\s*(%|percent)|bright(ness)?\s+(\d+)/i);
+    this.parameterPatterns.set(
-        this.parameterPatterns.set('temperature', /(\d+)\s*(degrees?|°)[CF]?/i);
+      "brightness",
-        this.parameterPatterns.set('color', /(red|green|blue|white|warm|cool)/i);
+      /(\d+)\s*(%|percent)|bright(ness)?\s+(\d+)/i,
+    );
+    this.parameterPatterns.set("temperature", /(\d+)\s*(degrees?|°)[CF]?/i);
+    this.parameterPatterns.set("color", /(red|green|blue|white|warm|cool)/i);
   }
 
   async extract(input: string): Promise<ExtractedEntities> {
     const entities: ExtractedEntities = {
-            primary_target: '',
+      primary_target: "",
       parameters: {},
-            confidence: 0
+      confidence: 0,
     };
 
     try {
@@ -48,7 +51,10 @@ export class EntityExtractor {
       for (const [param, pattern] of this.parameterPatterns) {
         const match = input.match(pattern);
         if (match) {
-                    entities.parameters[param] = this.normalizeParameterValue(param, match[1]);
+          entities.parameters[param] = this.normalizeParameterValue(
+            param,
+            match[1],
+          );
         }
       }
 
@@ -57,29 +63,35 @@ export class EntityExtractor {
 
       return entities;
     } catch (error) {
-            console.error('Entity extraction error:', error);
+      console.error("Entity extraction error:", error);
       return {
-                primary_target: '',
+        primary_target: "",
         parameters: {},
-                confidence: 0
+        confidence: 0,
       };
     }
   }
 
-    private normalizeParameterValue(parameter: string, value: string): number | string {
+  private normalizeParameterValue(
+    parameter: string,
+    value: string,
+  ): number | string {
     switch (parameter) {
-            case 'brightness':
+      case "brightness":
         return Math.min(100, Math.max(0, parseInt(value)));
-            case 'temperature':
+      case "temperature":
         return parseInt(value);
-            case 'color':
+      case "color":
         return value.toLowerCase();
       default:
         return value;
     }
   }
 
-    private calculateConfidence(entities: ExtractedEntities, input: string): number {
+  private calculateConfidence(
+    entities: ExtractedEntities,
+    input: string,
+  ): number {
     let confidence = 0;
 
     // Device confidence

src/ai/nlp/intent-classifier.ts

@@ -18,54 +18,47 @@ export class IntentClassifier {
   constructor() {
     this.actionPatterns = [
       {
-                action: 'turn_on',
+        action: "turn_on",
-                patterns: [
+        patterns: [/turn\s+on/i, /switch\s+on/i, /enable/i, /activate/i],
-                    /turn\s+on/i,
-                    /switch\s+on/i,
-                    /enable/i,
-                    /activate/i
-                ]
       },
       {
-                action: 'turn_off',
+        action: "turn_off",
-                patterns: [
+        patterns: [/turn\s+off/i, /switch\s+off/i, /disable/i, /deactivate/i],
-                    /turn\s+off/i,
-                    /switch\s+off/i,
-                    /disable/i,
-                    /deactivate/i
-                ]
       },
       {
-                action: 'set',
+        action: "set",
         patterns: [
           /set\s+(?:the\s+)?(.+)\s+to/i,
           /change\s+(?:the\s+)?(.+)\s+to/i,
-                    /adjust\s+(?:the\s+)?(.+)\s+to/i
+          /adjust\s+(?:the\s+)?(.+)\s+to/i,
         ],
-                parameters: ['brightness', 'temperature', 'color']
+        parameters: ["brightness", "temperature", "color"],
       },
       {
-                action: 'query',
+        action: "query",
         patterns: [
           /what\s+is/i,
           /get\s+(?:the\s+)?(.+)/i,
           /show\s+(?:the\s+)?(.+)/i,
-                    /tell\s+me/i
+          /tell\s+me/i,
-                ]
+        ],
-            }
+      },
     ];
   }
 
   async classify(
     input: string,
-        extractedEntities: { parameters: Record<string, any>; primary_target: string }
+    extractedEntities: {
+      parameters: Record<string, any>;
+      primary_target: string;
+    },
   ): Promise<ClassifiedIntent> {
     let bestMatch: ClassifiedIntent = {
-            action: '',
+      action: "",
-            target: '',
+      target: "",
       confidence: 0,
       parameters: {},
-            raw_input: input
+      raw_input: input,
     };
 
     for (const actionPattern of this.actionPatterns) {
@@ -78,8 +71,12 @@ export class IntentClassifier {
               action: actionPattern.action,
               target: extractedEntities.primary_target,
               confidence,
-                            parameters: this.extractActionParameters(actionPattern, match, extractedEntities),
+              parameters: this.extractActionParameters(
-                            raw_input: input
+                actionPattern,
+                match,
+                extractedEntities,
+              ),
+              raw_input: input,
             };
           }
         }
@@ -105,7 +102,7 @@ export class IntentClassifier {
     }
 
     // Additional confidence for specific keywords
-        const keywords = ['please', 'can you', 'would you'];
+    const keywords = ["please", "can you", "would you"];
     for (const keyword of keywords) {
       if (input.toLowerCase().includes(keyword)) {
         confidence += 0.1;
@@ -118,7 +115,10 @@ export class IntentClassifier {
   private extractActionParameters(
     actionPattern: ActionPattern,
     match: RegExpMatchArray,
-        extractedEntities: { parameters: Record<string, any>; primary_target: string }
+    extractedEntities: {
+      parameters: Record<string, any>;
+      primary_target: string;
+    },
   ): Record<string, any> {
     const parameters: Record<string, any> = {};
 
@@ -141,37 +141,40 @@ export class IntentClassifier {
 
   private inferFromContext(
     input: string,
-        extractedEntities: { parameters: Record<string, any>; primary_target: string }
+    extractedEntities: {
+      parameters: Record<string, any>;
+      primary_target: string;
+    },
   ): ClassifiedIntent {
     // Default to 'set' action if parameters are present
     if (Object.keys(extractedEntities.parameters).length > 0) {
       return {
-                action: 'set',
+        action: "set",
         target: extractedEntities.primary_target,
         confidence: 0.5,
         parameters: extractedEntities.parameters,
-                raw_input: input
+        raw_input: input,
       };
     }
 
     // Default to 'query' for question-like inputs
     if (input.match(/^(what|when|where|who|how|why)/i)) {
       return {
-                action: 'query',
+        action: "query",
-                target: extractedEntities.primary_target || 'system',
+        target: extractedEntities.primary_target || "system",
         confidence: 0.6,
         parameters: {},
-                raw_input: input
+        raw_input: input,
       };
     }
 
     // Fallback with low confidence
     return {
-            action: 'unknown',
+      action: "unknown",
-            target: extractedEntities.primary_target || 'system',
+      target: extractedEntities.primary_target || "system",
       confidence: 0.3,
       parameters: {},
-            raw_input: input
+      raw_input: input,
     };
   }
 }

src/ai/nlp/processor.ts

@@ -1,7 +1,7 @@
-import { AIIntent, AIContext, AIConfidence, AIError } from '../types/index.js';
+import { AIIntent, AIContext, AIConfidence, AIError } from "../types/index.js";
-import { EntityExtractor } from './entity-extractor.js';
+import { EntityExtractor } from "./entity-extractor.js";
-import { IntentClassifier } from './intent-classifier.js';
+import { IntentClassifier } from "./intent-classifier.js";
-import { ContextAnalyzer } from './context-analyzer.js';
+import { ContextAnalyzer } from "./context-analyzer.js";
 
 export class NLPProcessor {
   private entityExtractor: EntityExtractor;
@@ -16,7 +16,7 @@ export class NLPProcessor {
 
   async processCommand(
     input: string,
-        context: AIContext
+    context: AIContext,
   ): Promise<{
     intent: AIIntent;
     confidence: AIConfidence;
@@ -30,14 +30,21 @@ export class NLPProcessor {
       const intent = await this.intentClassifier.classify(input, entities);
 
       // Analyze context relevance
-            const contextRelevance = await this.contextAnalyzer.analyze(intent, context);
+      const contextRelevance = await this.contextAnalyzer.analyze(
+        intent,
+        context,
+      );
 
       // Calculate confidence scores
       const confidence: AIConfidence = {
-                overall: (intent.confidence + entities.confidence + contextRelevance.confidence) / 3,
+        overall:
+          (intent.confidence +
+            entities.confidence +
+            contextRelevance.confidence) /
+          3,
         intent: intent.confidence,
         entities: entities.confidence,
-                context: contextRelevance.confidence
+        context: contextRelevance.confidence,
       };
 
       // Create structured intent
@@ -47,41 +54,42 @@ export class NLPProcessor {
         parameters: {
           ...entities.parameters,
           ...intent.parameters,
-                    context_parameters: contextRelevance.relevant_params
+          context_parameters: contextRelevance.relevant_params,
         },
-                raw_input: input
+        raw_input: input,
       };
 
       return {
         intent: structuredIntent,
-                confidence
+        confidence,
       };
     } catch (error: unknown) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error occurred";
       return {
         intent: {
-                    action: 'error',
+          action: "error",
-                    target: 'system',
+          target: "system",
           parameters: {},
-                    raw_input: input
+          raw_input: input,
         },
         confidence: {
           overall: 0,
           intent: 0,
           entities: 0,
-                    context: 0
+          context: 0,
         },
         error: {
-                    code: 'NLP_PROCESSING_ERROR',
+          code: "NLP_PROCESSING_ERROR",
           message: errorMessage,
-                    suggestion: 'Please try rephrasing your command',
+          suggestion: "Please try rephrasing your command",
           recovery_options: [
-                        'Use simpler language',
+            "Use simpler language",
-                        'Break down the command into smaller parts',
+            "Break down the command into smaller parts",
-                        'Specify the target device explicitly'
+            "Specify the target device explicitly",
           ],
-                    context
+          context,
-                }
+        },
       };
     }
   }
@@ -89,7 +97,7 @@ export class NLPProcessor {
   async validateIntent(
     intent: AIIntent,
     confidence: AIConfidence,
-        threshold = 0.7
+    threshold = 0.7,
   ): Promise<boolean> {
     return (
       confidence.overall >= threshold &&
@@ -99,31 +107,28 @@ export class NLPProcessor {
     );
   }
 
-    async suggestCorrections(
+  async suggestCorrections(input: string, error: AIError): Promise<string[]> {
-        input: string,
-        error: AIError
-    ): Promise<string[]> {
     // Implement correction suggestions based on the error
     const suggestions: string[] = [];
 
-        if (error.code === 'ENTITY_NOT_FOUND') {
+    if (error.code === "ENTITY_NOT_FOUND") {
       suggestions.push(
-                'Try specifying the device name more clearly',
+        "Try specifying the device name more clearly",
-                'Use the exact device name from your Home Assistant setup'
+        "Use the exact device name from your Home Assistant setup",
       );
     }
 
-        if (error.code === 'AMBIGUOUS_INTENT') {
+    if (error.code === "AMBIGUOUS_INTENT") {
       suggestions.push(
-                'Please specify what you want to do with the device',
+        "Please specify what you want to do with the device",
-                'Use action words like "turn on", "set", "adjust"'
+        'Use action words like "turn on", "set", "adjust"',
       );
     }
 
-        if (error.code === 'CONTEXT_MISMATCH') {
+    if (error.code === "CONTEXT_MISMATCH") {
       suggestions.push(
-                'Specify the location if referring to a device',
+        "Specify the location if referring to a device",
-                'Clarify which device you mean in the current context'
+        "Clarify which device you mean in the current context",
       );
     }
 

src/ai/templates/prompt-templates.ts

@@ -1,4 +1,4 @@
-import { AIModel } from '../types/index.js';
+import { AIModel } from "../types/index.js";
 
 interface PromptTemplate {
   system: string;
@@ -33,13 +33,15 @@ Current context: {context}`,
         examples: [
           {
             user: "Turn on the living room lights",
-                        assistant: "I'll turn on the lights in the living room. Would you like me to set a specific brightness level?"
+            assistant:
+              "I'll turn on the lights in the living room. Would you like me to set a specific brightness level?",
           },
           {
             user: "Set the temperature to 72 degrees",
-                        assistant: "I'll set the temperature to 72°F. I'll monitor the temperature and let you know when it reaches the target."
+            assistant:
-                    }
+              "I'll set the temperature to 72°F. I'll monitor the temperature and let you know when it reaches the target.",
-                ]
+          },
+        ],
       },
       [AIModel.GPT4]: {
         system: `You are a home automation assistant powered by GPT-4.
@@ -52,13 +54,15 @@ Context: {context}`,
         examples: [
           {
             user: "Dim the bedroom lights to 50%",
-                        assistant: "Setting bedroom light brightness to 50%. The change has been applied successfully."
+            assistant:
+              "Setting bedroom light brightness to 50%. The change has been applied successfully.",
           },
           {
             user: "Start the evening routine",
-                        assistant: "Initiating evening routine: dimming lights, adjusting temperature, and enabling security system."
+            assistant:
-                    }
+              "Initiating evening routine: dimming lights, adjusting temperature, and enabling security system.",
-                ]
+          },
+        ],
       },
       [AIModel.CUSTOM]: {
         system: `Custom home automation assistant configuration.
@@ -73,14 +77,16 @@ Current context: {context}`,
         examples: [
           {
             user: "Make it cooler in here",
-                        assistant: "Based on your preferences, I'll lower the temperature by 2 degrees. Current temperature is 74°F, adjusting to 72°F."
+            assistant:
+              "Based on your preferences, I'll lower the temperature by 2 degrees. Current temperature is 74°F, adjusting to 72°F.",
           },
           {
             user: "Set up movie mode",
-                        assistant: "Activating movie mode: dimming lights to 20%, closing blinds, setting TV input to HDMI 1, and adjusting sound system."
+            assistant:
-                    }
+              "Activating movie mode: dimming lights to 20%, closing blinds, setting TV input to HDMI 1, and adjusting sound system.",
-                ]
+          },
-            }
+        ],
+      },
     };
   }
 
@@ -95,7 +101,7 @@ Current context: {context}`,
     // Replace variables in the prompt
     for (const [key, value] of Object.entries(variables)) {
       const placeholder = `{${key}}`;
-            if (typeof value === 'object') {
+      if (typeof value === "object") {
         prompt = prompt.replace(placeholder, JSON.stringify(value));
       } else {
         prompt = prompt.replace(placeholder, String(value));
@@ -115,7 +121,7 @@ Current context: {context}`,
 
   addExample(
     model: AIModel,
-        example: { user: string; assistant: string }
+    example: { user: string; assistant: string },
   ): void {
     this.templates[model].examples.push(example);
   }
@@ -124,10 +130,7 @@ Current context: {context}`,
     this.templates[model].system = newPrompt;
   }
 
-    createCustomTemplate(
+  createCustomTemplate(model: AIModel.CUSTOM, template: PromptTemplate): void {
-        model: AIModel.CUSTOM,
-        template: PromptTemplate
-    ): void {
     this.templates[model] = template;
   }
 }

src/ai/types/index.ts

@@ -1,10 +1,10 @@
-import { z } from 'zod';
+import { z } from "zod";
 
 // AI Model Types
 export enum AIModel {
-    CLAUDE = 'claude',
+  CLAUDE = "claude",
-    GPT4 = 'gpt4',
+  GPT4 = "gpt4",
-    CUSTOM = 'custom'
+  CUSTOM = "custom",
 }
 
 // AI Confidence Level
@@ -61,10 +61,13 @@ export interface AIRateLimit {
   requests_per_minute: number;
   requests_per_hour: number;
   concurrent_requests: number;
-    model_specific_limits: Record<AIModel, {
+  model_specific_limits: Record<
+    AIModel,
+    {
       requests_per_minute: number;
       requests_per_hour: number;
-    }>;
+    }
+  >;
 }
 
 // Zod Schemas
@@ -72,14 +75,14 @@ export const AIConfidenceSchema = z.object({
   overall: z.number().min(0).max(1),
   intent: z.number().min(0).max(1),
   entities: z.number().min(0).max(1),
-    context: z.number().min(0).max(1)
+  context: z.number().min(0).max(1),
 });
 
 export const AIIntentSchema = z.object({
   action: z.string(),
   target: z.string(),
   parameters: z.record(z.any()),
-    raw_input: z.string()
+  raw_input: z.string(),
 });
 
 export const AIContextSchema = z.object({
@@ -88,7 +91,7 @@ export const AIContextSchema = z.object({
   timestamp: z.string(),
   location: z.string(),
   previous_actions: z.array(AIIntentSchema),
-    environment_state: z.record(z.any())
+  environment_state: z.record(z.any()),
 });
 
 export const AIResponseSchema = z.object({
@@ -97,11 +100,11 @@ export const AIResponseSchema = z.object({
     success: z.boolean(),
     action_taken: z.string(),
     entities_affected: z.array(z.string()),
-        state_changes: z.record(z.any())
+    state_changes: z.record(z.any()),
   }),
   next_suggestions: z.array(z.string()),
   confidence: AIConfidenceSchema,
-    context: AIContextSchema
+  context: AIContextSchema,
 });
 
 export const AIErrorSchema = z.object({
@@ -109,15 +112,17 @@ export const AIErrorSchema = z.object({
   message: z.string(),
   suggestion: z.string(),
   recovery_options: z.array(z.string()),
-    context: AIContextSchema
+  context: AIContextSchema,
 });
 
 export const AIRateLimitSchema = z.object({
   requests_per_minute: z.number(),
   requests_per_hour: z.number(),
   concurrent_requests: z.number(),
-    model_specific_limits: z.record(z.object({
+  model_specific_limits: z.record(
+    z.object({
       requests_per_minute: z.number(),
-        requests_per_hour: z.number()
+      requests_per_hour: z.number(),
-    }))
+    }),
+  ),
 });

src/api/routes.ts

@@ -1,21 +1,21 @@
-import { Router } from 'express';
+import { Router } from "express";
-import { MCP_SCHEMA } from '../mcp/schema.js';
+import { MCP_SCHEMA } from "../mcp/schema.js";
-import { middleware } from '../middleware/index.js';
+import { middleware } from "../middleware/index.js";
-import { sseManager } from '../sse/index.js';
+import { sseManager } from "../sse/index.js";
-import { v4 as uuidv4 } from 'uuid';
+import { v4 as uuidv4 } from "uuid";
-import { TokenManager } from '../security/index.js';
+import { TokenManager } from "../security/index.js";
-import { tools } from '../tools/index.js';
+import { tools } from "../tools/index.js";
-import { Tool } from '../interfaces/index.js';
+import { Tool } from "../interfaces/index.js";
 
 const router = Router();
 
 // MCP schema endpoint - no auth required as it's just the schema
-router.get('/mcp', (_req, res) => {
+router.get("/mcp", (_req, res) => {
   res.json(MCP_SCHEMA);
 });
 
 // MCP execute endpoint - requires authentication
-router.post('/mcp/execute', middleware.authenticate, async (req, res) => {
+router.post("/mcp/execute", middleware.authenticate, async (req, res) => {
   try {
     const { tool: toolName, parameters } = req.body;
 
@@ -24,7 +24,7 @@ router.post('/mcp/execute', middleware.authenticate, async (req, res) => {
     if (!tool) {
       return res.status(404).json({
         success: false,
-                message: `Tool '${toolName}' not found`
+        message: `Tool '${toolName}' not found`,
       });
     }
 
@@ -34,67 +34,72 @@ router.post('/mcp/execute', middleware.authenticate, async (req, res) => {
   } catch (error) {
     res.status(500).json({
       success: false,
-            message: error instanceof Error ? error.message : 'Unknown error occurred'
+      message:
+        error instanceof Error ? error.message : "Unknown error occurred",
     });
   }
 });
 
 // Health check endpoint
-router.get('/health', (_req, res) => {
+router.get("/health", (_req, res) => {
   res.json({
-        status: 'ok',
+    status: "ok",
     timestamp: new Date().toISOString(),
-        version: '0.1.0'
+    version: "0.1.0",
   });
 });
 
 // List devices endpoint
-router.get('/list_devices', middleware.authenticate, async (req, res) => {
+router.get("/list_devices", middleware.authenticate, async (req, res) => {
   try {
-        const tool = tools.find((t: Tool) => t.name === 'list_devices');
+    const tool = tools.find((t: Tool) => t.name === "list_devices");
     if (!tool) {
       return res.status(404).json({
         success: false,
-                message: 'Tool not found'
+        message: "Tool not found",
       });
     }
 
-        const result = await tool.execute({ token: req.headers.authorization?.replace('Bearer ', '') });
+    const result = await tool.execute({
+      token: req.headers.authorization?.replace("Bearer ", ""),
+    });
     res.json(result);
   } catch (error) {
     res.status(500).json({
       success: false,
-            message: error instanceof Error ? error.message : 'Unknown error occurred'
+      message:
+        error instanceof Error ? error.message : "Unknown error occurred",
     });
   }
 });
 
 // Device control endpoint
-router.post('/control', middleware.authenticate, async (req, res) => {
+router.post("/control", middleware.authenticate, async (req, res) => {
   try {
-        const tool = tools.find((t: Tool) => t.name === 'control');
+    const tool = tools.find((t: Tool) => t.name === "control");
     if (!tool) {
       return res.status(404).json({
         success: false,
-                message: 'Tool not found'
+        message: "Tool not found",
       });
     }
 
     const result = await tool.execute({
       ...req.body,
-            token: req.headers.authorization?.replace('Bearer ', '')
+      token: req.headers.authorization?.replace("Bearer ", ""),
     });
     res.json(result);
   } catch (error) {
     res.status(500).json({
       success: false,
-            message: error instanceof Error ? error.message : 'Unknown error occurred'
+      message:
+        error instanceof Error ? error.message : "Unknown error occurred",
     });
   }
 });
 
 // SSE endpoints
-router.get('/subscribe_events', middleware.wsRateLimiter, (req, res) => {
+router.get("/subscribe_events", middleware.wsRateLimiter, (req, res) => {
   try {
     // Get token from query parameter
     const token = req.query.token?.toString();
@@ -102,48 +107,54 @@ router.get('/subscribe_events', middleware.wsRateLimiter, (req, res) => {
     if (!token || !TokenManager.validateToken(token)) {
       return res.status(401).json({
         success: false,
-                message: 'Unauthorized - Invalid token'
+        message: "Unauthorized - Invalid token",
       });
     }
 
     // Set SSE headers
     res.writeHead(200, {
-            'Content-Type': 'text/event-stream',
+      "Content-Type": "text/event-stream",
-            'Cache-Control': 'no-cache',
+      "Cache-Control": "no-cache",
-            'Connection': 'keep-alive',
+      Connection: "keep-alive",
-            'Access-Control-Allow-Origin': '*'
+      "Access-Control-Allow-Origin": "*",
     });
 
     // Send initial connection message
-        res.write(`data: ${JSON.stringify({
+    res.write(
-            type: 'connection',
+      `data: ${JSON.stringify({
-            status: 'connected',
+        type: "connection",
-            timestamp: new Date().toISOString()
+        status: "connected",
-        })}\n\n`);
+        timestamp: new Date().toISOString(),
+      })}\n\n`,
+    );
 
     const clientId = uuidv4();
     const client = {
       id: clientId,
       send: (data: string) => {
         res.write(`data: ${data}\n\n`);
-            }
+      },
     };
 
     // Add client to SSE manager
     const sseClient = sseManager.addClient(client, token);
     if (!sseClient || !sseClient.authenticated) {
-            res.write(`data: ${JSON.stringify({
+      res.write(
-                type: 'error',
+        `data: ${JSON.stringify({
-                message: sseClient ? 'Authentication failed' : 'Maximum client limit reached',
+          type: "error",
-                timestamp: new Date().toISOString()
+          message: sseClient
-            })}\n\n`);
+            ? "Authentication failed"
+            : "Maximum client limit reached",
+          timestamp: new Date().toISOString(),
+        })}\n\n`,
+      );
       return res.end();
     }
 
     // Subscribe to events if specified
-        const events = req.query.events?.toString().split(',').filter(Boolean);
+    const events = req.query.events?.toString().split(",").filter(Boolean);
     if (events?.length) {
-            events.forEach(event => sseManager.subscribeToEvent(clientId, event));
+      events.forEach((event) => sseManager.subscribeToEvent(clientId, event));
     }
 
     // Subscribe to entity if specified
@@ -159,14 +170,14 @@ router.get('/subscribe_events', middleware.wsRateLimiter, (req, res) => {
     }
 
     // Handle client disconnect
-        req.on('close', () => {
+    req.on("close", () => {
       sseManager.removeClient(clientId);
     });
-
   } catch (error) {
     res.status(500).json({
       success: false,
-            message: error instanceof Error ? error.message : 'Unknown error occurred'
+      message:
+        error instanceof Error ? error.message : "Unknown error occurred",
     });
   }
 });
@@ -185,19 +196,20 @@ router.get('/subscribe_events', middleware.wsRateLimiter, (req, res) => {
  *   - total_entities_tracked: Number of entities being tracked
  *   - subscriptions: Lists of entity, event, and domain subscriptions
  */
-router.get('/get_sse_stats', middleware.authenticate, (_req, res) => {
+router.get("/get_sse_stats", middleware.authenticate, (_req, res) => {
   try {
     const stats = sseManager.getStatistics();
     res.json({
       success: true,
       timestamp: new Date().toISOString(),
-            data: stats
+      data: stats,
     });
   } catch (error) {
     res.status(500).json({
       success: false,
-            message: error instanceof Error ? error.message : 'Unknown error occurred',
+      message:
-            timestamp: new Date().toISOString()
+        error instanceof Error ? error.message : "Unknown error occurred",
+      timestamp: new Date().toISOString(),
     });
   }
 });

src/commands.ts

@@ -0,0 +1,27 @@
+// Common commands that work with most entities
+export const commonCommands = ["turn_on", "turn_off", "toggle"] as const;
+
+// Commands specific to cover entities
+export const coverCommands = [
+  ...commonCommands,
+  "open",
+  "close",
+  "stop",
+  "set_position",
+  "set_tilt_position",
+] as const;
+
+// Commands specific to climate entities
+export const climateCommands = [
+  ...commonCommands,
+  "set_temperature",
+  "set_hvac_mode",
+  "set_fan_mode",
+  "set_humidity",
+] as const;
+
+// Types for command validation
+export type CommonCommand = (typeof commonCommands)[number];
+export type CoverCommand = (typeof coverCommands)[number];
+export type ClimateCommand = (typeof climateCommands)[number];
+export type Command = CommonCommand | CoverCommand | ClimateCommand;

src/config/__tests__/test.config.ts

@@ -0,0 +1,162 @@
+import { z } from "zod";
+
+// Test configuration schema
+const testConfigSchema = z.object({
+  // Test Environment
+  TEST_PORT: z.number().default(3001),
+  TEST_HOST: z.string().default("http://localhost"),
+  TEST_WEBSOCKET_PORT: z.number().default(3002),
+
+  // Mock Authentication
+  TEST_JWT_SECRET: z
+    .string()
+    .default("test_jwt_secret_key_that_is_at_least_32_chars"),
+  TEST_TOKEN: z.string().default("test_token_that_is_at_least_32_chars_long"),
+  TEST_INVALID_TOKEN: z.string().default("invalid_token"),
+
+  // Mock Client Settings
+  TEST_CLIENT_IP: z.string().default("127.0.0.1"),
+  TEST_MAX_CLIENTS: z.number().default(10),
+  TEST_PING_INTERVAL: z.number().default(100),
+  TEST_CLEANUP_INTERVAL: z.number().default(200),
+  TEST_MAX_CONNECTION_AGE: z.number().default(1000),
+
+  // Mock Rate Limiting
+  TEST_RATE_LIMIT_WINDOW: z.number().default(60000), // 1 minute
+  TEST_RATE_LIMIT_MAX_REQUESTS: z.number().default(100),
+  TEST_RATE_LIMIT_WEBSOCKET: z.number().default(1000),
+
+  // Mock Events
+  TEST_EVENT_TYPES: z
+    .array(z.string())
+    .default([
+      "state_changed",
+      "automation_triggered",
+      "script_executed",
+      "service_called",
+    ]),
+
+  // Mock Entities
+  TEST_ENTITIES: z
+    .array(
+      z.object({
+        entity_id: z.string(),
+        state: z.string(),
+        attributes: z.record(z.any()),
+        last_changed: z.string(),
+        last_updated: z.string(),
+      }),
+    )
+    .default([
+      {
+        entity_id: "light.test_light",
+        state: "on",
+        attributes: {
+          brightness: 255,
+          color_temp: 400,
+        },
+        last_changed: new Date().toISOString(),
+        last_updated: new Date().toISOString(),
+      },
+      {
+        entity_id: "switch.test_switch",
+        state: "off",
+        attributes: {},
+        last_changed: new Date().toISOString(),
+        last_updated: new Date().toISOString(),
+      },
+    ]),
+
+  // Mock Services
+  TEST_SERVICES: z
+    .array(
+      z.object({
+        domain: z.string(),
+        service: z.string(),
+        data: z.record(z.any()),
+      }),
+    )
+    .default([
+      {
+        domain: "light",
+        service: "turn_on",
+        data: {
+          entity_id: "light.test_light",
+          brightness: 255,
+        },
+      },
+      {
+        domain: "switch",
+        service: "turn_off",
+        data: {
+          entity_id: "switch.test_switch",
+        },
+      },
+    ]),
+
+  // Mock Error Scenarios
+  TEST_ERROR_SCENARIOS: z
+    .array(
+      z.object({
+        type: z.string(),
+        message: z.string(),
+        code: z.number(),
+      }),
+    )
+    .default([
+      {
+        type: "authentication_error",
+        message: "Invalid token",
+        code: 401,
+      },
+      {
+        type: "rate_limit_error",
+        message: "Too many requests",
+        code: 429,
+      },
+      {
+        type: "validation_error",
+        message: "Invalid request body",
+        code: 400,
+      },
+    ]),
+});
+
+// Parse environment variables or use defaults
+const parseTestConfig = () => {
+  const config = {
+    TEST_PORT: parseInt(process.env.TEST_PORT || "3001"),
+    TEST_HOST: process.env.TEST_HOST || "http://localhost",
+    TEST_WEBSOCKET_PORT: parseInt(process.env.TEST_WEBSOCKET_PORT || "3002"),
+    TEST_JWT_SECRET:
+      process.env.TEST_JWT_SECRET ||
+      "test_jwt_secret_key_that_is_at_least_32_chars",
+    TEST_TOKEN:
+      process.env.TEST_TOKEN || "test_token_that_is_at_least_32_chars_long",
+    TEST_INVALID_TOKEN: process.env.TEST_INVALID_TOKEN || "invalid_token",
+    TEST_CLIENT_IP: process.env.TEST_CLIENT_IP || "127.0.0.1",
+    TEST_MAX_CLIENTS: parseInt(process.env.TEST_MAX_CLIENTS || "10"),
+    TEST_PING_INTERVAL: parseInt(process.env.TEST_PING_INTERVAL || "100"),
+    TEST_CLEANUP_INTERVAL: parseInt(process.env.TEST_CLEANUP_INTERVAL || "200"),
+    TEST_MAX_CONNECTION_AGE: parseInt(
+      process.env.TEST_MAX_CONNECTION_AGE || "1000",
+    ),
+    TEST_RATE_LIMIT_WINDOW: parseInt(
+      process.env.TEST_RATE_LIMIT_WINDOW || "60000",
+    ),
+    TEST_RATE_LIMIT_MAX_REQUESTS: parseInt(
+      process.env.TEST_RATE_LIMIT_MAX_REQUESTS || "100",
+    ),
+    TEST_RATE_LIMIT_WEBSOCKET: parseInt(
+      process.env.TEST_RATE_LIMIT_WEBSOCKET || "1000",
+    ),
+  };
+
+  return testConfigSchema.parse(config);
+};
+
+// Export the validated test configuration
+export const TEST_CONFIG = parseTestConfig();
+
+// Export types
+export type TestConfig = z.infer<typeof testConfigSchema>;

src/config/app.config.ts

@@ -1,5 +1,6 @@
-import { config } from 'dotenv';
+import { config } from "dotenv";
-import { resolve } from 'path';
+import { resolve } from "path";
+import { z } from "zod";
 
 /**
  * Load environment variables based on NODE_ENV
@@ -7,11 +8,12 @@ import { resolve } from 'path';
  * Test: .env.test
  * Production: .env
  */
-const envFile = process.env.NODE_ENV === 'production'
+const envFile =
-    ? '.env'
+  process.env.NODE_ENV === "production"
-    : process.env.NODE_ENV === 'test'
+    ? ".env"
-        ? '.env.test'
+    : process.env.NODE_ENV === "test"
-        : '.env.development';
+      ? ".env.test"
+      : ".env.development";
 
 console.log(`Loading environment from ${envFile}`);
 config({ path: resolve(process.cwd(), envFile) });
@@ -20,59 +22,76 @@ config({ path: resolve(process.cwd(), envFile) });
  * Application configuration object
  * Contains all configuration settings for the application
  */
-export const APP_CONFIG = {
+export const AppConfigSchema = z.object({
   /** Server Configuration */
-    PORT: process.env.PORT || 3000,
+  PORT: z.coerce.number().default(4000),
-    NODE_ENV: process.env.NODE_ENV || 'development',
+  NODE_ENV: z
+    .enum(["development", "production", "test"])
+    .default("development"),
 
   /** Home Assistant Configuration */
-    HASS_HOST: process.env.HASS_HOST || 'http://192.168.178.63:8123',
+  HASS_HOST: z.string().default("http://192.168.178.63:8123"),
-    HASS_TOKEN: process.env.HASS_TOKEN,
+  HASS_TOKEN: z.string().optional(),
+
+  /** Speech Features Configuration */
+  SPEECH: z.object({
+    ENABLED: z.boolean().default(false),
+    WAKE_WORD_ENABLED: z.boolean().default(false),
+    SPEECH_TO_TEXT_ENABLED: z.boolean().default(false),
+    WHISPER_MODEL_PATH: z.string().default("/models"),
+    WHISPER_MODEL_TYPE: z.string().default("base"),
+  }).default({
+    ENABLED: false,
+    WAKE_WORD_ENABLED: false,
+    SPEECH_TO_TEXT_ENABLED: false,
+    WHISPER_MODEL_PATH: "/models",
+    WHISPER_MODEL_TYPE: "base",
+  }),
 
   /** Security Configuration */
-    JWT_SECRET: process.env.JWT_SECRET || 'your-secret-key',
+  JWT_SECRET: z.string().default("your-secret-key"),
-    RATE_LIMIT: {
+  RATE_LIMIT: z.object({
     /** Time window for rate limiting in milliseconds */
-        windowMs: 15 * 60 * 1000, // 15 minutes
+    windowMs: z.number().default(15 * 60 * 1000), // 15 minutes
     /** Maximum number of requests per window */
-        max: 100 // limit each IP to 100 requests per windowMs
+    max: z.number().default(100), // limit each IP to 100 requests per windowMs
-    },
+  }),
 
   /** Server-Sent Events Configuration */
-    SSE: {
+  SSE: z.object({
     /** Maximum number of concurrent SSE clients */
-        MAX_CLIENTS: 1000,
+    MAX_CLIENTS: z.number().default(1000),
     /** Ping interval in milliseconds to keep connections alive */
-        PING_INTERVAL: 30000 // 30 seconds
+    PING_INTERVAL: z.number().default(30000), // 30 seconds
-    },
+  }),
 
   /** Logging Configuration */
-    LOGGING: {
+  LOGGING: z.object({
     /** Log level (error, warn, info, http, debug) */
-        LEVEL: process.env.LOG_LEVEL || 'info',
+    LEVEL: z.enum(["error", "warn", "info", "debug", "trace"]).default("info"),
     /** Directory for log files */
-        DIR: process.env.LOG_DIR || 'logs',
+    DIR: z.string().default("logs"),
     /** Maximum log file size before rotation */
-        MAX_SIZE: process.env.LOG_MAX_SIZE || '20m',
+    MAX_SIZE: z.string().default("20m"),
     /** Maximum number of days to keep log files */
-        MAX_DAYS: process.env.LOG_MAX_DAYS || '14d',
+    MAX_DAYS: z.string().default("14d"),
     /** Whether to compress rotated logs */
-        COMPRESS: process.env.LOG_COMPRESS === 'true',
+    COMPRESS: z.boolean().default(false),
     /** Format for timestamps in logs */
-        TIMESTAMP_FORMAT: 'YYYY-MM-DD HH:mm:ss:ms',
+    TIMESTAMP_FORMAT: z.string().default("YYYY-MM-DD HH:mm:ss:ms"),
     /** Whether to include request logging */
-        LOG_REQUESTS: process.env.LOG_REQUESTS === 'true',
+    LOG_REQUESTS: z.boolean().default(false),
-    },
+  }),
 
   /** Application Version */
-    VERSION: '0.1.0'
+  VERSION: z.string().default("0.1.0"),
-} as const;
+});
 
 /** Type definition for the configuration object */
-export type AppConfig = typeof APP_CONFIG;
+export type AppConfig = z.infer<typeof AppConfigSchema>;
 
 /** Required environment variables that must be set */
-const requiredEnvVars = ['HASS_TOKEN'] as const;
+const requiredEnvVars = ["HASS_TOKEN"] as const;
 
 /**
  * Validate that all required environment variables are set
@@ -83,3 +102,37 @@ for (const envVar of requiredEnvVars) {
     throw new Error(`Missing required environment variable: ${envVar}`);
   }
 }
+
+// Load and validate configuration
+export const APP_CONFIG = AppConfigSchema.parse({
+  PORT: process.env.PORT || 4000,
+  NODE_ENV: process.env.NODE_ENV || "development",
+  HASS_HOST: process.env.HASS_HOST || "http://192.168.178.63:8123",
+  HASS_TOKEN: process.env.HASS_TOKEN,
+  JWT_SECRET: process.env.JWT_SECRET || "your-secret-key",
+  RATE_LIMIT: {
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    max: 100, // limit each IP to 100 requests per windowMs
+  },
+  SSE: {
+    MAX_CLIENTS: 1000,
+    PING_INTERVAL: 30000, // 30 seconds
+  },
+  LOGGING: {
+    LEVEL: process.env.LOG_LEVEL || "info",
+    DIR: process.env.LOG_DIR || "logs",
+    MAX_SIZE: process.env.LOG_MAX_SIZE || "20m",
+    MAX_DAYS: process.env.LOG_MAX_DAYS || "14d",
+    COMPRESS: process.env.LOG_COMPRESS === "true",
+    TIMESTAMP_FORMAT: "YYYY-MM-DD HH:mm:ss:ms",
+    LOG_REQUESTS: process.env.LOG_REQUESTS === "true",
+  },
+  VERSION: "0.1.0",
+  SPEECH: {
+    ENABLED: process.env.ENABLE_SPEECH_FEATURES === "true",
+    WAKE_WORD_ENABLED: process.env.ENABLE_WAKE_WORD === "true",
+    SPEECH_TO_TEXT_ENABLED: process.env.ENABLE_SPEECH_TO_TEXT === "true",
+    WHISPER_MODEL_PATH: process.env.WHISPER_MODEL_PATH || "/models",
+    WHISPER_MODEL_TYPE: process.env.WHISPER_MODEL_TYPE || "base",
+  },
+});

src/config/boilerplate.config.ts

@@ -0,0 +1,35 @@
+export const BOILERPLATE_CONFIG = {
+  configuration: {
+    LOG_LEVEL: {
+      type: "string" as const,
+      default: "debug",
+      description: "Logging level",
+      enum: ["error", "warn", "info", "debug", "trace"],
+    },
+    CACHE_DIRECTORY: {
+      type: "string" as const,
+      default: ".cache",
+      description: "Directory for cache files",
+    },
+    CONFIG_DIRECTORY: {
+      type: "string" as const,
+      default: ".config",
+      description: "Directory for configuration files",
+    },
+    DATA_DIRECTORY: {
+      type: "string" as const,
+      default: ".data",
+      description: "Directory for data files",
+    },
+  },
+  internal: {
+    boilerplate: {
+      configuration: {
+        LOG_LEVEL: "debug",
+        CACHE_DIRECTORY: ".cache",
+        CONFIG_DIRECTORY: ".config",
+        DATA_DIRECTORY: ".data",
+      },
+    },
+  },
+};

src/config/hass.config.ts

@@ -1,11 +1,50 @@
-import dotenv from 'dotenv';
+import { config } from "dotenv";
+import { resolve } from "path";
 
-// Load environment variables
+// Load environment variables based on NODE_ENV
-dotenv.config();
+const envFile =
+  process.env.NODE_ENV === "production"
+    ? ".env"
+    : process.env.NODE_ENV === "test"
+      ? ".env.test"
+      : ".env.development";
+
+config({ path: resolve(process.cwd(), envFile) });
 
 export const HASS_CONFIG = {
-    BASE_URL: process.env.HASS_HOST || 'http://homeassistant.local:8123',
+  // Base configuration
-    TOKEN: process.env.HASS_TOKEN || '',
+  BASE_URL: process.env.HASS_HOST || "http://localhost:8123",
-    SOCKET_URL: process.env.HASS_SOCKET_URL || '',
+  TOKEN: process.env.HASS_TOKEN || "",
-    SOCKET_TOKEN: process.env.HASS_TOKEN || '',
+  SOCKET_URL: process.env.HASS_WS_URL || "ws://localhost:8123/api/websocket",
+  SOCKET_TOKEN: process.env.HASS_TOKEN || "",
+
+  // Boilerplate configuration
+  BOILERPLATE: {
+    CACHE_DIRECTORY: ".cache",
+    CONFIG_DIRECTORY: ".config",
+    DATA_DIRECTORY: ".data",
+    LOG_LEVEL: "debug",
+    ENVIRONMENT: process.env.NODE_ENV || "development",
+  },
+
+  // Application configuration
+  APP_NAME: "homeassistant-mcp",
+  APP_VERSION: "1.0.0",
+
+  // API configuration
+  API_VERSION: "1.0.0",
+  API_PREFIX: "/api",
+
+  // Security configuration
+  RATE_LIMIT: {
+    WINDOW_MS: 15 * 60 * 1000, // 15 minutes
+    MAX_REQUESTS: 100,
+  },
+
+  // WebSocket configuration
+  WS_CONFIG: {
+    AUTO_RECONNECT: true,
+    MAX_RECONNECT_ATTEMPTS: 3,
+    RECONNECT_DELAY: 1000,
+  },
 };