diff --git a/README.md b/README.md index a02c074..577358b 100644 --- a/README.md +++ b/README.md @@ -1,305 +1,128 @@ -# ๐Ÿš€ MCP Server for Home Assistant - Bringing AI-Powered Smart Homes to Life! +# MCP Server for Home Assistant ๐Ÿ ๐Ÿค– [![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) - ---- +[![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg)](https://www.typescriptlang.org) ## Overview ๐ŸŒ -Welcome to the **Model Context Protocol (MCP) Server for Home Assistant**! This robust platform bridges Home Assistant with cutting-edge Language Learning Models (LLMs), enabling natural language interactions and real-time automation of your smart devices. Imagine entering your home, saying: +MCP (Model Context Protocol) Server is a lightweight integration tool for Home Assistant, providing a flexible interface for device management and automation. -> "Hey MCP, dim the lights and start my evening playlist," +## Core Features โœจ -and watching your home transform instantlyโ€”that's the magic that MCP Server delivers! +- ๐Ÿ”Œ Basic device control via REST API +- ๐Ÿ“ก WebSocket/Server-Sent Events (SSE) for state updates +- ๐Ÿค– Simple automation rule management +- ๐Ÿ” JWT-based authentication ---- +## Prerequisites ๐Ÿ“‹ -## Key Benefits โœจ +- ๐Ÿš€ Bun runtime (v1.0.26+) +- ๐Ÿก Home Assistant instance +- ๐Ÿณ Docker (optional, recommended for deployment) -### ๐ŸŽฎ 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. +## Installation ๐Ÿ› ๏ธ -- **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): +### Docker Deployment (Recommended) ```bash -npx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude -``` +# Clone the repository +git clone https://github.com/jango-blockchained/homeassistant-mcp.git +cd homeassistant-mcp -### ๐Ÿณ Docker Setup (Recommended) +# Copy and edit environment configuration +cp .env.example .env +# Edit .env with your Home Assistant credentials -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 +# Build and start 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: +### Bare Metal Installation ```bash -# 1. Install Bun (if not already installed) +# Install Bun curl -fsSL https://bun.sh/install | bash -# 2. Install project dependencies with caching support -bun install --frozen-lockfile +# Clone the repository +git clone https://github.com/jango-blockchained/homeassistant-mcp.git +cd homeassistant-mcp -# 3. Launch the server in development mode with hot-reload enabled -bun run dev --watch +# Install dependencies +bun install + +# Start the server +bun run dev ``` ---- +## Basic Usage ๐Ÿ–ฅ๏ธ -## Real-World Usage Examples ๐Ÿ” +### Device Control Example -### ๐Ÿ“ฑ Smart Home Dashboard Integration -Integrate MCP's real-time updates into your custom dashboard for a dynamic smart home experience: +```typescript +// Turn on a light +const response = await fetch('http://localhost:3000/api/devices/light.living_room', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${token}` + }, + body: JSON.stringify({ state: 'on' }) +}); +``` -```javascript -const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'); +### WebSocket State Updates -eventSource.onmessage = (event) => { - const data = JSON.parse(event.data); - console.log('Real-time update:', data); - // Update your UI dashboard, e.g., refresh a light intensity indicator. +```typescript +const ws = new WebSocket('ws://localhost:3000/devices'); +ws.onmessage = (event) => { + const deviceState = JSON.parse(event.data); + console.log('Device state updated:', deviceState); }; ``` -### ๐Ÿ  Voice-Activated Control -Utilize voice commands to trigger actions with minimal effort: +## Current Limitations โš ๏ธ -```javascript -// Establish a WebSocket connection for real-time command processing -const ws = new WebSocket('wss://mcp.yourha.com/ws'); - -ws.onmessage = ({ data }) => { - const update = JSON.parse(data); - if (update.entity_id === 'light.living_room') { - console.log('Adjusting living room lighting based on voice command...'); - // Additional logic to update your UI or trigger further actions can go here. - } -}; - -// Simulate processing a voice command -function simulateVoiceCommand(command) { - console.log("Processing voice command:", command); - // Integrate with your actual voice-to-text system as needed. -} - -simulateVoiceCommand("Turn off all the lights for bedtime"); -``` - -๐Ÿ‘‰ Learn more in our [Usage Guide](docs/usage.md). - ---- - -## Update Strategy ๐Ÿ”„ - -Maintain a seamless operation with zero downtime updates: - -```bash -# 1. Pull the latest Docker images -docker compose pull - -# 2. Rebuild and restart containers smoothly -docker compose up -d --build - -# 3. Clean up unused Docker images to free up space -docker system prune -f -``` - -For more details, review our [Troubleshooting & Updates](docs/troubleshooting.md). - ---- - -## Security Features ๐Ÿ” - -We prioritize the security of your smart home with multiple layers of defense: -- **JWT Authentication ๐Ÿ”‘:** Secure, token-based API access to prevent unauthorized usage. -- **Request Sanitization ๐Ÿงผ:** Automatic filtering and validation of API requests to combat injection attacks. -- **Rate Limiting & Fail2Ban ๐Ÿšซ:** Monitors requests to prevent brute force and DDoS attacks. -- **End-to-End Encryption ๐Ÿ”’:** Ensures that your commands and data remain private during transmission. - ---- +- ๐ŸŽ™๏ธ Basic voice command support (work in progress) +- ๐Ÿง  Limited advanced NLP capabilities +- ๐Ÿ”— Minimal third-party device integration +- ๐Ÿ› Early-stage error handling ## Contributing ๐Ÿค -We value community contributions! Here's how you can help improve MCP Server: -1. **Fork the Repository ๐Ÿด** - Create your own copy of the project. -2. **Create a Feature Branch ๐ŸŒฟ** - ```bash - git checkout -b feature/your-feature-name - ``` -3. **Install Dependencies & Run Tests ๐Ÿงช** - ```bash - bun install - bun test --coverage - ``` -4. **Make Your Changes & Commit ๐Ÿ“** - Follow the [Conventional Commits](https://www.conventionalcommits.org) guidelines. -5. **Open a Pull Request ๐Ÿ”€** - Submit your changes for review. +1. Fork the repository +2. Create a feature branch: + ```bash + git checkout -b feature/your-feature + ``` +3. Make your changes +4. Run tests: + ```bash + bun test + ``` +5. Submit a pull request -Read more in our [Contribution Guidelines](docs/contributing.md). +## Roadmap ๐Ÿ—บ๏ธ ---- +- ๐ŸŽค Enhance voice command processing +- ๐Ÿ”Œ Improve device compatibility +- ๐Ÿค– Expand automation capabilities +- ๐Ÿ›ก๏ธ Implement more robust error handling -## Roadmap & Future Enhancements ๐Ÿ”ฎ +## License ๐Ÿ“„ -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. +MIT License. See [LICENSE](LICENSE) for details. -For more details, see our [Roadmap](docs/roadmap.md). +## Support ๐Ÿ†˜ ---- +- ๐Ÿž [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues) +- ๐Ÿ“– Documentation: [Project Docs](https://jango-blockchained.github.io/homeassistant-mcp/) -## 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 +## MCP Client Integration ๐Ÿ”— This MCP server can be integrated with various clients that support the Model Context Protocol. Below are instructions for different client integrations: -### Cursor Integration +### Cursor Integration ๐Ÿ–ฑ๏ธ The server can be integrated with Cursor by adding the configuration to `.cursor/config/config.json`: @@ -318,7 +141,7 @@ The server can be integrated with Cursor by adding the configuration to `.cursor } ``` -### Claude Desktop Integration +### Claude Desktop Integration ๐Ÿ’ฌ For Claude Desktop, add the following to your Claude configuration file: @@ -336,7 +159,7 @@ For Claude Desktop, add the following to your Claude configuration file: } ``` -### Cline Integration +### Cline Integration ๐Ÿ“Ÿ For Cline-based clients, add the following configuration: @@ -361,7 +184,7 @@ For Cline-based clients, add the following configuration: } ``` -### Command Line Usage +### Command Line Usage ๐Ÿ’ป #### Windows A CMD script is provided in the `scripts` directory. To use it: diff --git a/docker/speech/Dockerfile b/docker/speech/Dockerfile index 80e50bc..e0d8185 100644 --- a/docker/speech/Dockerfile +++ b/docker/speech/Dockerfile @@ -1,22 +1,29 @@ # Use Python slim image as builder -FROM python:3.10-slim 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/* + curl \ + wget # 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 +RUN pip install --no-cache-dir \ + "numpy>=1.24.3,<2.0" \ + "sounddevice" \ + "openwakeword" \ + "faster-whisper" \ + "transformers" \ + "torch" \ + "torchaudio" \ + "huggingface_hub" \ + "requests" \ + "soundfile" \ + "tflite-runtime" # Create final image FROM python:3.10-slim @@ -28,31 +35,48 @@ 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 + alsa-utils \ + curl \ + wget -# 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 +# Create necessary directories with explicit permissions +RUN mkdir -p /models/wake_word /audio /app /models/cache /models/models--Systran--faster-whisper-base /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models \ + && chmod -R 777 /models /audio /app /models/cache /models/models--Systran--faster-whisper-base /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models + +# Download wake word models +RUN wget -O /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models/alexa_v0.1.tflite \ + https://github.com/dscripka/openWakeWord/raw/main/openwakeword/resources/models/alexa_v0.1.tflite \ + && wget -O /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models/hey_jarvis_v0.1.tflite \ + https://github.com/dscripka/openWakeWord/raw/main/openwakeword/resources/models/hey_jarvis_v0.1.tflite \ + && chmod 644 /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models/*.tflite + +# Set environment variables for model caching +ENV HF_HOME=/models/cache +ENV TRANSFORMERS_CACHE=/models/cache +ENV HUGGINGFACE_HUB_CACHE=/models/cache + +# Copy scripts and set permissions explicitly +COPY wake_word_detector.py /app/wake_word_detector.py +COPY setup-audio.sh /setup-audio.sh + +# Ensure scripts are executable by any user +RUN chmod 755 /setup-audio.sh /app/wake_word_detector.py + +# Create a non-root user with explicit UID and GID +RUN addgroup --gid 1000 user && \ + adduser --uid 1000 --gid 1000 --disabled-password --gecos '' user + +# Change ownership of directories +RUN chown -R 1000:1000 /models /audio /app /models/cache /models/models--Systran--faster-whisper-base \ + /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models + +# Switch to non-root user +USER 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 \ @@ -60,8 +84,5 @@ ENV WHISPER_MODEL_PATH=/models \ 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"] \ No newline at end of file diff --git a/docker/speech/setup-audio.sh b/docker/speech/setup-audio.sh index dc5c033..1ff5242 100755 --- a/docker/speech/setup-audio.sh +++ b/docker/speech/setup-audio.sh @@ -1,25 +1,58 @@ #!/bin/bash +set -e # Exit immediately if a command exits with a non-zero status +set -x # Print commands and their arguments as they are executed + +echo "Starting audio setup script at $(date)" +echo "Current user: $(whoami)" +echo "Current directory: $(pwd)" + +# Print environment variables related to audio and speech +echo "ENABLE_WAKE_WORD: ${ENABLE_WAKE_WORD}" +echo "PULSE_SERVER: ${PULSE_SERVER}" +echo "WHISPER_MODEL_PATH: ${WHISPER_MODEL_PATH}" # Wait for PulseAudio socket to be available +max_wait=30 +wait_count=0 while [ ! -e /run/user/1000/pulse/native ]; do - echo "Waiting for PulseAudio socket..." + echo "Waiting for PulseAudio socket... (${wait_count}/${max_wait})" sleep 1 + wait_count=$((wait_count + 1)) + if [ $wait_count -ge $max_wait ]; then + echo "ERROR: PulseAudio socket not available after ${max_wait} seconds" + exit 1 + fi done -# Test PulseAudio connection -pactl info || { - echo "Failed to connect to PulseAudio server" +# Verify PulseAudio connection with detailed error handling +if ! pactl info; then + echo "ERROR: Failed to connect to PulseAudio server" + pactl list short modules + pactl list short clients exit 1 -} +fi -# List audio devices -pactl list sources || { - echo "Failed to list audio devices" +# List audio devices with error handling +if ! pactl list sources; then + echo "ERROR: Failed to list audio devices" exit 1 -} +fi -# Start the wake word detector -python /app/wake_word_detector.py +# Ensure wake word detector script is executable +chmod +x /app/wake_word_detector.py + +# Start the wake word detector with logging +echo "Starting wake word detector at $(date)" +python /app/wake_word_detector.py 2>&1 | tee /audio/wake_word_detector.log & +wake_word_pid=$! + +# Wait and check if the process is still running +sleep 5 +if ! kill -0 $wake_word_pid 2>/dev/null; then + echo "ERROR: Wake word detector process died immediately" + cat /audio/wake_word_detector.log + exit 1 +fi # Mute the monitor to prevent feedback pactl set-source-mute alsa_output.pci-0000_00_1b.0.analog-stereo.monitor 1 @@ -30,5 +63,6 @@ pactl set-source-volume alsa_input.pci-0000_00_1b.0.analog-stereo 65% # Set speaker volume to 40% pactl set-sink-volume alsa_output.pci-0000_00_1b.0.analog-stereo 40% -# Make the script executable -chmod +x /setup-audio.sh \ No newline at end of file +# Keep the script running to prevent container exit +echo "Audio setup complete. Keeping container alive." +tail -f /dev/null \ No newline at end of file diff --git a/docker/speech/wake_word_detector.py b/docker/speech/wake_word_detector.py index c5d2340..c3e55a5 100644 --- a/docker/speech/wake_word_detector.py +++ b/docker/speech/wake_word_detector.py @@ -53,8 +53,8 @@ HASS_TOKEN = os.environ.get('HASS_TOKEN') def initialize_asr_model(): """Initialize the ASR model with retries and timeout""" - model_path = os.environ.get('ASR_MODEL_PATH', '/models') - model_name = os.environ.get('ASR_MODEL', 'large-v3') + model_path = os.environ.get('WHISPER_MODEL_PATH', '/models') + model_name = os.environ.get('WHISPER_MODEL_TYPE', 'base') start_time = time.time() for attempt in range(MAX_MODEL_LOAD_RETRIES): diff --git a/docs/api.md b/docs/api.md index c1e1da8..1ac5617 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,728 +1,170 @@ -# ๐Ÿš€ Home Assistant MCP API Documentation +# Home Assistant MCP Server API Documentation -![API Version](https://img.shields.io/badge/API-v2.1-blueviolet) ![Rate Limit](https://img.shields.io/badge/Rate%20Limit-100%2Fmin-brightgreen) +## Overview -## ๐ŸŒŸ Quick Start +This document provides a reference for the MCP Server API, which offers basic device control and state management for Home Assistant. -```bash -# Get API schema with caching -curl -X GET http://localhost:3000/mcp \ - -H "Cache-Control: max-age=3600" # Cache for 1 hour -``` +## Authentication -## ๐Ÿ”Œ Core Functions โš™๏ธ +All API requests require a valid JWT token in the Authorization header: -### State Management (`/api/state`) ```http -GET /api/state?cache=true # Enable client-side caching -POST /api/state +Authorization: Bearer YOUR_TOKEN ``` -**Example Request:** +## Core Endpoints + +### Device State Management + +#### Get Device State +```http +GET /api/state/{entity_id} +``` + +**Response:** ```json { - "context": "living_room", - "state": { - "lights": "on", - "temperature": 22 - }, - "_cache": { // Optional caching config - "ttl": 300, // 5 minutes - "tags": ["lights", "climate"] - } -} -``` - -## โšก Action Endpoints - -### Execute Action with Cache Validation -```http -POST /api/action -If-None-Match: "etag_value" // Prevent duplicate actions -``` - -**Batch Processing:** -```json -{ - "actions": [ - { "action": "๐ŸŒž Morning Routine", "params": { "brightness": 80 } }, - { "action": "โ„๏ธ AC Control", "params": { "temp": 21 } } - ], - "_parallel": true // Execute actions concurrently -} -``` - -## ๐Ÿ” Query Functions - -### Available Actions with ETag -```http -GET /api/actions -ETag: "a1b2c3d4" // Client-side cache validation -``` - -**Response Headers:** -``` -Cache-Control: public, max-age=86400 // 24-hour cache -ETag: "a1b2c3d4" -``` - -## ๐ŸŒ WebSocket Events - -```javascript -const ws = new WebSocket('wss://ha-mcp/ws'); -ws.onmessage = ({ data }) => { - const event = JSON.parse(data); - if(event.type === 'STATE_UPDATE') { - updateUI(event.payload); // ๐ŸŽจ Real-time UI sync - } -}; -``` - -## ๐Ÿ—ƒ๏ธ Caching Strategies - -### Client-Side Caching -```http -GET /api/devices -Cache-Control: max-age=300, stale-while-revalidate=60 -``` - -### Server-Side Cache-Control -```typescript -// Example middleware configuration -app.use( - cacheMiddleware({ - ttl: 60 * 5, // 5 minutes - paths: ['/api/devices', '/mcp'], - vary: ['Authorization'] // User-specific caching - }) -); -``` - -## โŒ Error Handling - -**429 Too Many Requests:** -```json -{ - "error": { - "code": "RATE_LIMITED", - "message": "Slow down! ๐Ÿข", - "retry_after": 30, - "docs": "https://ha-mcp/docs/rate-limits" - } -} -``` - -## ๐Ÿšฆ Rate Limiting Tiers - -| Tier | Requests/min | Features | -|---------------|--------------|------------------------| -| Guest | 10 | Basic read-only | -| User | 100 | Full access | -| Power User | 500 | Priority queue | -| Integration | 1000 | Bulk operations | - -## ๐Ÿ› ๏ธ Example Usage - -### Smart Cache Refresh -```javascript -async function getDevices() { - const response = await fetch('/api/devices', { - headers: { - 'If-None-Match': localStorage.getItem('devicesETag') - } - }); - - if(response.status === 304) { // Not Modified - return JSON.parse(localStorage.devicesCache); - } - - const data = await response.json(); - localStorage.setItem('devicesETag', response.headers.get('ETag')); - localStorage.setItem('devicesCache', JSON.stringify(data)); - return data; -} -``` - -## ๐Ÿ”’ Security Middleware (Enhanced) - -### Cache-Aware Rate Limiting -```typescript -app.use( - rateLimit({ - windowMs: 15 * 60 * 1000, // 15 minutes - max: 100, // Limit each IP to 100 requests per window - cache: new RedisStore(), // Distributed cache - keyGenerator: (req) => { - return `${req.ip}-${req.headers.authorization}`; - } - }) -); -``` - -### Security Headers -```http -Content-Security-Policy: default-src 'self'; -Strict-Transport-Security: max-age=31536000; -X-Content-Type-Options: nosniff; -Cache-Control: public, max-age=600; -ETag: "abc123" -``` - -## ๐Ÿ“˜ Best Practices - -1. **Cache Wisely:** Use `ETag` and `Cache-Control` headers for state data -2. **Batch Operations:** Combine requests using `/api/actions/batch` -3. **WebSocket First:** Prefer real-time updates over polling -4. **Error Recovery:** Implement exponential backoff with jitter -5. **Cache Invalidation:** Use tags for bulk invalidation - -```mermaid -graph LR -A[Client] -->|Cached Request| B{CDN} -B -->|Cache Hit| C[Return 304] -B -->|Cache Miss| D[Origin Server] -D -->|Response| B -B -->|Response| A -``` - -> Pro Tip: Use `curl -I` to inspect cache headers! ๐Ÿ” - -## Device Control - -### Common Entity Controls - -```json -{ - "tool": "control", - "command": "turn_on", // Options: "turn_on", "turn_off", "toggle" - "entity_id": "light.living_room" -} -``` - -### Light Control - -```json -{ - "tool": "control", - "command": "turn_on", "entity_id": "light.living_room", - "brightness": 128, - "color_temp": 4000, - "rgb_color": [255, 0, 0] -} -``` - -## Add-on Management - -### List Available Add-ons - -```json -{ - "tool": "addon", - "action": "list" -} -``` - -### Install Add-on - -```json -{ - "tool": "addon", - "action": "install", - "slug": "core_configurator", - "version": "5.6.0" -} -``` - -### Manage Add-on State - -```json -{ - "tool": "addon", - "action": "start", // Options: "start", "stop", "restart" - "slug": "core_configurator" -} -``` - -## Package Management - -### List HACS Packages - -```json -{ - "tool": "package", - "action": "list", - "category": "integration" // Options: "integration", "plugin", "theme", "python_script", "appdaemon", "netdaemon" -} -``` - -### Install Package - -```json -{ - "tool": "package", - "action": "install", - "category": "integration", - "repository": "hacs/integration", - "version": "1.32.0" -} -``` - -## Automation Management - -For automation management details and endpoints, please refer to the [Tools Documentation](tools/tools.md). - -## Security Considerations - -- Validate and sanitize all user inputs. -- Enforce rate limiting to prevent abuse. -- Apply proper security headers. -- Gracefully handle errors based on the environment. - -## Troubleshooting - -If you experience issues with the API: -- Verify the endpoint and request payload. -- Check authentication tokens and required headers. -- Consult the [Troubleshooting Guide](troubleshooting.md) for further guidance. - -## MCP Schema Endpoint - -The server exposes an MCP (Model Context Protocol) schema endpoint that describes all available tools and their parameters: - -```http -GET /mcp -``` - -This endpoint returns a JSON schema describing all available tools, their parameters, and documentation resources. The schema follows the MCP specification and can be used by LLM clients to understand the server's capabilities. - -Example response: -```json -{ - "tools": [ - { - "name": "list_devices", - "description": "List all devices connected to Home Assistant", - "parameters": { - "type": "object", - "properties": { - "domain": { - "type": "string", - "enum": ["light", "climate", "alarm_control_panel", ...] - }, - "area": { "type": "string" }, - "floor": { "type": "string" } - } - } - }, - // ... other tools - ], - "prompts": [], - "resources": [ - { - "name": "Home Assistant API", - "url": "https://developers.home-assistant.io/docs/api/rest/" - } - ] -} -``` - -Note: The `/mcp` endpoint is publicly accessible and does not require authentication, as it only provides schema information. - -## Core Functions - -### State Management -```http -GET /api/state -POST /api/state -``` - -Manages the current state of the system. - -**Example Request:** -```json -POST /api/state -{ - "context": "living_room", - "state": { - "lights": "on", - "temperature": 22 + "state": "on", + "attributes": { + "brightness": 128 } } ``` -### Context Updates +#### Update Device State ```http -POST /api/context -``` +POST /api/state +Content-Type: application/json -Updates the current context with new information. - -**Example Request:** -```json -POST /api/context { - "user": "john", - "location": "kitchen", - "time": "morning", - "activity": "cooking" + "entity_id": "light.living_room", + "state": "on", + "attributes": { + "brightness": 128 + } } ``` -## Action Endpoints +### Device Control -### Execute Action +#### Execute Device Command ```http -POST /api/action -``` +POST /api/control +Content-Type: application/json -Executes a specified action with given parameters. - -**Example Request:** -```json -POST /api/action { - "action": "turn_on_lights", + "entity_id": "light.living_room", + "command": "turn_on", "parameters": { - "room": "living_room", - "brightness": 80 + "brightness": 50 } } ``` -### Batch Actions -```http -POST /api/actions/batch -``` +## Real-Time Updates -Executes multiple actions in sequence. - -**Example Request:** -```json -POST /api/actions/batch -{ - "actions": [ - { - "action": "turn_on_lights", - "parameters": { - "room": "living_room" - } - }, - { - "action": "set_temperature", - "parameters": { - "temperature": 22 - } - } - ] -} -``` - -## Query Functions - -### Get Available Actions -```http -GET /api/actions -``` - -Returns a list of all available actions. - -**Example Response:** -```json -{ - "actions": [ - { - "name": "turn_on_lights", - "parameters": ["room", "brightness"], - "description": "Turns on lights in specified room" - }, - { - "name": "set_temperature", - "parameters": ["temperature"], - "description": "Sets temperature in current context" - } - ] -} -``` - -### Context Query -```http -GET /api/context?type=current -``` - -Retrieves context information. - -**Example Response:** -```json -{ - "current_context": { - "user": "john", - "location": "kitchen", - "time": "morning", - "activity": "cooking" - } -} -``` - -## WebSocket Events - -The server supports real-time updates via WebSocket connections. +### WebSocket Connection +Connect to real-time updates: ```javascript -// Client-side connection example -const ws = new WebSocket('ws://localhost:3000/ws'); - +const ws = new WebSocket('ws://localhost:3000/events'); ws.onmessage = (event) => { - const data = JSON.parse(event.data); - console.log('Received update:', data); + const deviceUpdate = JSON.parse(event.data); + console.log('Device state changed:', deviceUpdate); }; ``` -### Supported Events - -- `state_change`: Emitted when system state changes -- `context_update`: Emitted when context is updated -- `action_executed`: Emitted when an action is completed -- `error`: Emitted when an error occurs - -**Example Event Data:** -```json -{ - "event": "state_change", - "data": { - "previous_state": { - "lights": "off" - }, - "current_state": { - "lights": "on" - }, - "timestamp": "2024-03-20T10:30:00Z" - } -} -``` - ## Error Handling -All endpoints return standard HTTP status codes: +### Common Error Responses -- 200: Success -- 400: Bad Request -- 401: Unauthorized -- 403: Forbidden -- 404: Not Found -- 500: Internal Server Error - -**Error Response Format:** ```json { "error": { - "code": "INVALID_PARAMETERS", - "message": "Missing required parameter: room", - "details": { - "missing_fields": ["room"] - } + "code": "INVALID_REQUEST", + "message": "Invalid request parameters", + "details": "Entity ID not found or invalid command" } } ``` ## Rate Limiting -The API implements rate limiting to prevent abuse: +Basic rate limiting is implemented: +- Maximum of 100 requests per minute +- Excess requests will receive a 429 Too Many Requests response -- 100 requests per minute per IP for regular endpoints -- 1000 requests per minute per IP for WebSocket connections +## Supported Operations -When rate limit is exceeded, the server returns: +### Supported Commands +- `turn_on` +- `turn_off` +- `toggle` +- `set_brightness` +- `set_color` -```json -{ - "error": { - "code": "RATE_LIMIT_EXCEEDED", - "message": "Too many requests", - "reset_time": "2024-03-20T10:31:00Z" +### Supported Entities +- Lights +- Switches +- Climate controls +- Media players + +## Limitations + +- Limited to basic device control +- No advanced automation +- Minimal error handling +- Basic authentication + +## Best Practices + +1. Always include a valid JWT token +2. Handle potential errors in your client code +3. Use WebSocket for real-time updates when possible +4. Validate entity IDs before sending commands + +## Example Client Usage + +```typescript +async function controlDevice(entityId: string, command: string, params?: Record) { + try { + const response = await fetch('/api/control', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${token}` + }, + body: JSON.stringify({ + entity_id: entityId, + command, + parameters: params + }) + }); + + if (!response.ok) { + const error = await response.json(); + throw new Error(error.message); + } + + return await response.json(); + } catch (error) { + console.error('Device control failed:', error); + throw error; } } + +// Usage example +controlDevice('light.living_room', 'turn_on', { brightness: 50 }) + .then(result => console.log('Device controlled successfully')) + .catch(error => console.error('Control failed', error)); ``` -## Example Usage +## Future Development -### Using curl -```bash -# Get current state -curl -X GET \ - http://localhost:3000/api/state \ - -H 'Authorization: ApiKey your_api_key_here' +Planned improvements: +- Enhanced error handling +- More comprehensive device support +- Improved authentication mechanisms -# Execute action -curl -X POST \ - http://localhost:3000/api/action \ - -H 'Authorization: ApiKey your_api_key_here' \ - -H 'Content-Type: application/json' \ - -d '{ - "action": "turn_on_lights", - "parameters": { - "room": "living_room", - "brightness": 80 - } - }' -``` - -### Using JavaScript -```javascript -// Execute action -async function executeAction() { - const response = await fetch('http://localhost:3000/api/action', { - method: 'POST', - headers: { - 'Authorization': 'ApiKey your_api_key_here', - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - action: 'turn_on_lights', - parameters: { - room: 'living_room', - brightness: 80 - } - }) - }); - - const data = await response.json(); - console.log('Action result:', data); -} -``` - -## Security Middleware - -### Overview - -The security middleware provides a comprehensive set of utility functions to enhance the security of the Home Assistant MCP application. These functions cover various aspects of web security, including: - -- Rate limiting -- Request validation -- Input sanitization -- Security headers -- Error handling - -### Utility Functions - -#### `checkRateLimit(ip: string, maxRequests?: number, windowMs?: number)` - -Manages rate limiting for IP addresses to prevent abuse. - -**Parameters**: -- `ip`: IP address to track -- `maxRequests`: Maximum number of requests allowed (default: 100) -- `windowMs`: Time window for rate limiting (default: 15 minutes) - -**Returns**: `boolean` or throws an error if limit is exceeded - -**Example**: -```typescript -try { - checkRateLimit('127.0.0.1'); // Checks rate limit with default settings -} catch (error) { - // Handle rate limit exceeded -} -``` - -#### `validateRequestHeaders(request: Request, requiredContentType?: string)` - -Validates incoming HTTP request headers for security and compliance. - -**Parameters**: -- `request`: The incoming HTTP request -- `requiredContentType`: Expected content type (default: 'application/json') - -**Checks**: -- Content type -- Request body size -- Authorization header (optional) - -**Example**: -```typescript -try { - validateRequestHeaders(request); -} catch (error) { - // Handle validation errors -} -``` - -#### `sanitizeValue(value: unknown)` - -Sanitizes input values to prevent XSS attacks. - -**Features**: -- Escapes HTML tags -- Handles nested objects and arrays -- Preserves non-string values - -**Example**: -```typescript -const sanitized = sanitizeValue(''); -// Returns: '<script>alert("xss")</script>' -``` - -#### `applySecurityHeaders(request: Request, helmetConfig?: HelmetOptions)` - -Applies security headers to HTTP requests using Helmet. - -**Security Headers**: -- Content Security Policy -- X-Frame-Options -- X-Content-Type-Options -- Referrer Policy -- HSTS (in production) - -**Example**: -```typescript -const headers = applySecurityHeaders(request); -``` - -#### `handleError(error: Error, env?: string)` - -Handles error responses with environment-specific details. - -**Modes**: -- Production: Generic error message -- Development: Detailed error with stack trace - -**Example**: -```typescript -const errorResponse = handleError(error, process.env.NODE_ENV); -``` - -### Middleware Usage - -These utility functions are integrated into Elysia middleware: - -```typescript -const app = new Elysia() - .use(rateLimiter) // Rate limiting - .use(validateRequest) // Request validation - .use(sanitizeInput) // Input sanitization - .use(securityHeaders) // Security headers - .use(errorHandler) // Error handling -``` - -### Best Practices - -1. Always validate and sanitize user inputs -2. Use rate limiting to prevent abuse -3. Apply security headers -4. Handle errors gracefully -5. Keep environment-specific error handling - -### Security Considerations - -- Configurable rate limits -- XSS protection -- Content security policies -- Token validation -- Error information exposure control - -### Troubleshooting - -- Ensure `JWT_SECRET` is set in environment -- Check content type in requests -- Monitor rate limit errors -- Review error handling in different environments \ No newline at end of file +*API is subject to change. Always refer to the latest documentation.* diff --git a/docs/architecture.md b/docs/architecture.md index 1ceba1c..3a0e5a5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,7 +6,7 @@ nav_order: 4 # Architecture Overview ๐Ÿ—๏ธ -This document describes the architecture of the MCP Server, explaining how different components work together to provide a bridge between Home Assistant and Language Learning Models. +This document describes the architecture of the MCP Server, explaining how different components work together to provide a bridge between Home Assistant and custom automation tools. ## System Architecture @@ -15,17 +15,13 @@ graph TD subgraph "Client Layer" WC[Web Clients] MC[Mobile Clients] - VC[Voice Assistants] end subgraph "MCP Server" API[API Gateway] - NLP[NLP Engine] SSE[SSE Manager] WS[WebSocket Server] CM[Command Manager] - SC[Scene Controller] - Cache[Redis Cache] end subgraph "Home Assistant" @@ -33,251 +29,60 @@ graph TD Dev[Devices & Services] end - subgraph "AI Layer" - LLM[Language Models] - IC[Intent Classifier] - NER[Named Entity Recognition] - end - WC --> |HTTP/WS| API MC --> |HTTP/WS| API - VC --> |HTTP| API API --> |Events| SSE API --> |Real-time| WS - API --> |Process| NLP - NLP --> |Query| LLM - NLP --> |Extract| IC - NLP --> |Identify| NER - - CM --> |Execute| HA - HA --> |Control| Dev - - SSE --> |State Updates| WC - SSE --> |State Updates| MC - WS --> |Bi-directional| WC - - Cache --> |Fast Access| API - HA --> |Events| Cache + API --> HA + HA --> API ``` -## Component Details +## Core Components -### 1. Client Layer +### API Gateway +- Handles incoming HTTP and WebSocket requests +- Provides endpoints for device management +- Implements basic authentication and request validation -The client layer consists of various interfaces that interact with the MCP Server: +### SSE Manager +- Manages Server-Sent Events for real-time updates +- Broadcasts device state changes to connected clients -- **Web Clients**: Browser-based dashboards and control panels -- **Mobile Clients**: Native mobile applications -- **Voice Assistants**: Voice-enabled devices and interfaces +### WebSocket Server +- Provides real-time, bidirectional communication +- Supports basic device control and state monitoring -### 2. MCP Server Core +### Command Manager +- Processes device control requests +- Translates API commands to Home Assistant compatible formats -#### API Gateway -- Handles all incoming HTTP requests -- Manages authentication and rate limiting -- Routes requests to appropriate handlers +## Communication Flow -```typescript -interface APIGateway { - authenticate(): Promise; - rateLimit(): Promise; - route(request: Request): Promise; -} -``` +1. Client sends a request to the MCP Server API +2. API Gateway authenticates the request +3. Command Manager processes the request +4. Request is forwarded to Home Assistant +5. Response is sent back to the client via API or WebSocket -#### NLP Engine -- Processes natural language commands -- Integrates with Language Models -- Extracts intents and entities +## Key Design Principles -```typescript -interface NLPEngine { - processCommand(text: string): Promise; - extractEntities(text: string): Promise; - validateIntent(intent: CommandIntent): boolean; -} -``` +- **Simplicity:** Lightweight, focused design +- **Flexibility:** Easily extendable architecture +- **Performance:** Efficient request handling +- **Security:** Basic authentication and validation -#### Event Management -- **SSE Manager**: Handles Server-Sent Events -- **WebSocket Server**: Manages bi-directional communication -- **Command Manager**: Processes and executes commands +## Limitations -### 3. Home Assistant Integration +- Basic device control capabilities +- Limited advanced automation features +- Minimal third-party integrations -The server maintains a robust connection to Home Assistant through: +## Future Improvements -- REST API calls -- WebSocket connections -- Event subscriptions +- Enhanced error handling +- More robust authentication +- Expanded device type support -```typescript -interface HomeAssistantClient { - connect(): Promise; - getState(entityId: string): Promise; - executeCommand(command: Command): Promise; - 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) \ No newline at end of file +*Architecture is subject to change as the project evolves.* \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md index 37dcac3..0783fe5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,249 +6,119 @@ nav_order: 5 # Contributing Guide ๐Ÿค -Thank you for your interest in contributing to the MCP Server project! This guide will help you get started with contributing to the project. +Thank you for your interest in contributing to the MCP Server project! ## Getting Started ### Prerequisites -Before you begin, ensure you have: - - [Bun](https://bun.sh) >= 1.0.26 -- [Node.js](https://nodejs.org) >= 18 -- [Docker](https://www.docker.com) (optional, for containerized development) -- A running Home Assistant instance for testing +- Home Assistant instance +- Basic understanding of TypeScript ### Development Setup -1. Fork and clone the repository: +1. Fork the repository +2. Clone your fork: ```bash - git clone https://github.com/YOUR_USERNAME/advanced-homeassistant-mcp.git - cd advanced-homeassistant-mcp + git clone https://github.com/YOUR_USERNAME/homeassistant-mcp.git + cd homeassistant-mcp ``` -2. Install dependencies: +3. Install dependencies: ```bash bun install ``` -3. Set up your development environment: +4. Configure environment: ```bash cp .env.example .env # Edit .env with your Home Assistant details ``` -4. Start the development server: - ```bash - bun run dev - ``` - ## Development Workflow -### Branch Naming Convention +### Branch Naming - `feature/` - New features - `fix/` - Bug fixes - `docs/` - Documentation updates -- `refactor/` - Code refactoring -- `test/` - Test improvements Example: ```bash -git checkout -b feature/voice-commands +git checkout -b feature/device-control-improvements ``` ### Commit Messages -We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: +Follow simple, clear commit messages: ``` -type(scope): description +type: brief description -[optional body] - -[optional footer] +[optional detailed explanation] ``` Types: -- `feat:` - New features -- `fix:` - Bug fixes -- `docs:` - Documentation changes -- `style:` - Code style changes (formatting, etc.) -- `refactor:` - Code refactoring -- `test:` - Test updates -- `chore:` - Maintenance tasks +- `feat:` - New feature +- `fix:` - Bug fix +- `docs:` - Documentation +- `chore:` - Maintenance -Examples: -```bash -feat(api): add voice command endpoint -fix(sse): resolve connection timeout issue -docs(readme): update installation instructions -``` +### Code Style -### Testing +- Use TypeScript +- Follow existing code structure +- Keep changes focused and minimal -Run tests before submitting your changes: +## Testing + +Run tests before submitting: ```bash # Run all tests bun test -# Run specific test file -bun test test/api/command.test.ts - -# Run tests with coverage -bun test --coverage -``` - -### Code Style - -We use ESLint and Prettier for code formatting: - -```bash -# Check code style -bun run lint - -# Fix code style issues -bun run lint:fix +# Run specific test +bun test test/api/control.test.ts ``` ## Pull Request Process -1. **Update Documentation** - - Add/update relevant documentation - - Include inline code comments where necessary - - Update API documentation if endpoints change - -2. **Write Tests** - - Add tests for new features - - Update existing tests if needed - - Ensure all tests pass - -3. **Create Pull Request** - - Fill out the PR template - - Link related issues - - Provide clear description of changes - -4. **Code Review** - - Address review comments - - Keep discussions focused - - Be patient and respectful +1. Ensure tests pass +2. Update documentation if needed +3. Provide clear description of changes ### PR Template ```markdown ## Description -Brief description of the changes +Brief explanation of the changes ## Type of Change - [ ] Bug fix - [ ] New feature -- [ ] Breaking change - [ ] Documentation update -## How Has This Been Tested? -Describe your test process - -## Checklist -- [ ] Tests added/updated -- [ ] Documentation updated -- [ ] Code follows style guidelines -- [ ] All tests passing +## Testing +Describe how you tested these changes ``` -## Development Guidelines +## Reporting Issues -### Code Organization +- Use GitHub Issues +- Provide clear, reproducible steps +- Include environment details -``` -src/ -โ”œโ”€โ”€ api/ # API endpoints -โ”œโ”€โ”€ core/ # Core functionality -โ”œโ”€โ”€ models/ # Data models -โ”œโ”€โ”€ services/ # Business logic -โ”œโ”€โ”€ utils/ # Utility functions -โ””โ”€โ”€ types/ # TypeScript types -``` +## Code of Conduct -### Best Practices - -1. **Type Safety** - ```typescript - // Use explicit types - interface CommandRequest { - command: string; - parameters?: Record; - } - - function processCommand(request: CommandRequest): Promise { - // 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 - * @throws {ValidationError} If command is invalid - */ -async function processVoiceCommand(command: string): Promise { - // Implementation -} -``` - -### README Updates - -Keep the README up to date with: -- New features -- Changed requirements -- Updated examples -- Modified configuration - -## Getting Help - -- Check [Discussions](https://github.com/jango-blockchained/advanced-homeassistant-mcp/discussions) -- Review existing [Issues](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues) - -## Community Guidelines - -We expect all contributors to: - -- Be respectful and inclusive +- Be respectful - Focus on constructive feedback - Help maintain a positive environment -- Follow our code style guidelines -- Write clear documentation -- Test their code thoroughly -## License +## Resources -By contributing, you agree that your contributions will be licensed under the MIT License. \ No newline at end of file +- [API Documentation](api.md) +- [Troubleshooting Guide](troubleshooting.md) + +*Thank you for contributing!* \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 88a31d7..f0e4f5a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,31 +4,25 @@ title: Home nav_order: 1 --- -# ๐Ÿš€ MCP Server for Home Assistant +# ๐Ÿ  MCP Server for Home Assistant -Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating AI-powered natural language processing into your Home Assistant setup. +Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating a lightweight automation tool with your Home Assistant setup. ## What is MCP Server? -MCP Server is a bridge between Home Assistant and Language Learning Models (LLMs), enabling natural language interactions and real-time automation of your smart devices. It allows you to control your home automation setup using natural language commands while maintaining high performance and security. +MCP Server is a bridge between Home Assistant and custom automation tools, enabling basic device control and real-time monitoring of your smart home environment. It provides a flexible interface for managing and interacting with your home automation setup. ## Key Features -### ๐ŸŽฎ Device Control & Monitoring -- Voice-controlled automation -- Real-time updates via SSE/WebSocket -- Scene-based automation rules - -### ๐Ÿค– AI-Powered Features -- Natural Language Processing (NLP) -- Predictive automation -- Anomaly detection +### ๐ŸŽฎ Device Control +- Basic REST API for device management +- WebSocket and Server-Sent Events (SSE) for real-time updates +- Simple automation rule support ### ๐Ÿ›ก๏ธ Security & Performance - JWT authentication -- Request sanitization -- Sub-100ms latency -- Rate limiting +- Basic request validation +- Lightweight server design ## Documentation Structure @@ -37,19 +31,18 @@ MCP Server is a bridge between Home Assistant and Language Learning Models (LLMs - [Quick Start Tutorial](getting-started/quickstart.md) - Basic usage examples ### Core Documentation -- [API Documentation](api/index.md) - Complete API reference -- [Architecture Overview](architecture.md) - System design and components +- [API Documentation](api/index.md) - API reference +- [Architecture Overview](architecture.md) - System design - [Contributing Guidelines](contributing.md) - How to contribute -- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions +- [Troubleshooting Guide](troubleshooting.md) - Common issues ## Support -If you need help or want to report issues: +Need help or want to report issues? -- [GitHub Issues](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues) -- [GitHub Discussions](https://github.com/jango-blockchained/advanced-homeassistant-mcp/discussions) -- [Contributing Guidelines](contributing.md) +- [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues) +- [GitHub Discussions](https://github.com/jango-blockchained/homeassistant-mcp/discussions) ## License -This project is licensed under the MIT License. See the [LICENSE](https://github.com/jango-blockchained/advanced-homeassistant-mcp/blob/main/LICENSE) file for details. \ No newline at end of file +This project is licensed under the MIT License. See the [LICENSE](https://github.com/jango-blockchained/homeassistant-mcp/blob/main/LICENSE) file for details. \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md index 77d9d64..7d8fda3 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,51 +1,52 @@ # Roadmap for MCP Server -The following roadmap outlines our planned enhancements and future directions for the Home Assistant MCP Server. This document is a living guide that will be updated as new features are planned and developed. +The following roadmap outlines our planned enhancements and future directions for the Home Assistant MCP Server. This document is a living guide that will be updated as new features are developed. ## Near-Term Goals -- **Advanced Automation Capabilities:** - - Integrate sophisticated automation rules with conditional logic and multi-step execution. - - Introduce a visual automation builder for simplified rule creation. +- **Core Functionality Improvements:** + - Enhance REST API capabilities + - Improve WebSocket and SSE reliability + - Develop more robust error handling -- **Enhanced Security Features:** - - Implement multi-factor authentication for critical actions. - - Strengthen encryption methods and data handling practices. - - Expand monitoring and alerting for potential security breaches. +- **Security Enhancements:** + - Strengthen JWT authentication + - Improve input validation + - Add basic logging for security events - **Performance Optimizations:** - - Refine resource utilization to reduce latency. - - Optimize real-time data streaming via SSE. - - Introduce advanced caching mechanisms for frequently requested data. + - Optimize server response times + - Improve resource utilization + - Implement basic caching mechanisms ## Mid-Term Goals -- **User Interface Improvements:** - - Develop an intuitive web-based dashboard for device management and monitoring. - - Provide real-time analytics and performance metrics. +- **Device Integration:** + - Expand support for additional Home Assistant device types + - Improve device state synchronization + - Develop more flexible automation rule support -- **Expanded Integrations:** - - Support a broader range of smart home devices and brands. - - Integrate with additional home automation platforms and third-party services. - -- **Developer Experience Enhancements:** - - Improve documentation and developer tooling. - - Streamline contribution guidelines and testing setups. +- **Developer Experience:** + - Improve documentation + - Create more comprehensive examples + - Develop basic CLI tools for configuration ## Long-Term Vision -- **Ecosystem Expansion:** - - Build a modular plugin system for community-driven extensions and integrations. - - Enable seamless integration with future technologies in smart home and AI domains. +- **Extensibility:** + - Design a simple plugin system + - Create guidelines for community contributions + - Establish a clear extension mechanism -- **Scalability and Resilience:** - - Architect the system to support large-scale deployments. - - Incorporate advanced load balancing and failover mechanisms. +- **Reliability:** + - Implement comprehensive testing + - Develop monitoring and basic health check features + - Improve overall system stability ## How to Follow the Roadmap -- **Community Involvement:** We welcome and encourage feedback. -- **Regular Updates:** This document is updated regularly with new goals and milestones. -- **Transparency:** Check our GitHub repository and issue tracker for ongoing discussions. +- **Community Involvement:** We welcome feedback and contributions. +- **Transparency:** Check our GitHub repository for ongoing discussions. +- **Iterative Development:** Goals may change based on community needs and technical feasibility. *This roadmap is intended as a guide and may evolve based on community needs, technological advancements, and strategic priorities.* \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md index 0e293d7..e2314de 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,34 +1,96 @@ # Usage Guide -This guide explains how to use the Home Assistant MCP Server for smart home device management and integration with language learning systems. +This guide explains how to use the Home Assistant MCP Server for basic device management and integration. -## Basic Usage +## Basic Setup 1. **Starting the Server:** - - For development: run `npm run dev`. - - For production: run `npm run build` followed by `npm start`. + - Development mode: `bun run dev` + - Production mode: `bun run start` -2. **Accessing the Web Interface:** - - Open [http://localhost:3000](http://localhost:3000) in your browser. +2. **Accessing the Server:** + - Default URL: `http://localhost:3000` + - Ensure Home Assistant credentials are configured in `.env` -3. **Real-Time Updates:** - - Connect to the SSE endpoint at `/subscribe_events?token=YOUR_TOKEN&domain=light` to receive live updates. +## Device Control -## Advanced Features +### REST API Interactions -1. **API Interactions:** - - Use the REST API for operations such as device control, automation, and add-on management. - - See [API Documentation](api.md) for details. +Basic device control can be performed via the REST API: -2. **Tool Integrations:** - - Multiple tools are available (see [Tools Documentation](tools/tools.md)), for tasks like automation management and notifications. +```typescript +// Turn on a light +fetch('http://localhost:3000/api/control', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${token}` + }, + body: JSON.stringify({ + entity_id: 'light.living_room', + command: 'turn_on', + parameters: { brightness: 50 } + }) +}); +``` -3. **Security Settings:** - - Configure token-based authentication and environment variables as per the [Configuration Guide](getting-started/configuration.md). +### Supported Commands -4. **Customization and Extensions:** - - Extend server functionality by developing new tools as outlined in the [Development Guide](development/development.md). +- `turn_on` +- `turn_off` +- `toggle` +- `set_brightness` + +### Supported Entities + +- Lights +- Switches +- Climate controls +- Media players + +## Real-Time Updates + +### WebSocket Connection + +Subscribe to real-time device state changes: + +```typescript +const ws = new WebSocket('ws://localhost:3000/events'); +ws.onmessage = (event) => { + const deviceUpdate = JSON.parse(event.data); + console.log('Device state changed:', deviceUpdate); +}; +``` + +## Authentication + +All API requests require a valid JWT token in the Authorization header. + +## Limitations + +- Basic device control only +- Limited error handling +- Minimal third-party integrations ## Troubleshooting -If you experience issues, review the [Troubleshooting Guide](troubleshooting.md). \ No newline at end of file +1. Verify Home Assistant connection +2. Check JWT token validity +3. Ensure correct entity IDs +4. Review server logs for detailed errors + +## Configuration + +Configure the server using environment variables in `.env`: + +``` +HA_URL=http://homeassistant:8123 +HA_TOKEN=your_home_assistant_token +JWT_SECRET=your_jwt_secret +``` + +## Next Steps + +- Explore the [API Documentation](api.md) +- Check [Troubleshooting Guide](troubleshooting.md) +- Review [Contributing Guidelines](contributing.md) \ No newline at end of file