Compare commits
49 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
cc9eede856 | ||
|
|
f0ff3d5e5a | ||
|
|
81d6dea7da | ||
|
|
1328bd1306 | ||
|
|
6fa88be433 | ||
|
|
2892f24030 | ||
|
|
1e3442db14 | ||
|
|
f74154d96f | ||
|
|
36d83e0a0e | ||
|
|
33defac76c | ||
|
|
4306a6866f | ||
|
|
039f6890a7 | ||
|
|
4fff318ea9 | ||
|
|
ea6efd553d | ||
|
|
d45ef5c622 | ||
|
|
9358f83229 | ||
|
|
e49d31d725 | ||
|
|
13a27e1d00 | ||
|
|
3e7f3920b2 | ||
|
|
8f8e3bd85e | ||
|
|
7e7f83e985 | ||
|
|
c42f981f55 | ||
|
|
00cd0a5b5a | ||
|
|
4e9ebbbc2c | ||
|
|
eefbf790c3 | ||
|
|
942c175b90 | ||
|
|
10e895bb94 | ||
|
|
a1cc54f01f | ||
|
|
e3256682ba | ||
|
|
7635cce15a | ||
|
|
53a041921b | ||
|
|
af3399515a | ||
|
|
01991c0060 | ||
|
|
3f8d67b145 | ||
|
|
ab8b597843 | ||
|
|
ddf9070a64 | ||
|
|
b9727981cc | ||
|
|
e1db799b1d | ||
|
f5c01ad83a | ||
|
|
190915214d | ||
|
|
905339fb67 | ||
|
|
849b080aba | ||
|
|
f8bbe4af6f | ||
|
|
3a6f79c9a8 | ||
|
|
60f18f8e71 | ||
|
|
47f11b3d95 | ||
|
|
f24be8ff53 | ||
|
|
dfff432321 | ||
|
|
d59bf02d08 |
@@ -73,7 +73,6 @@ temp/
|
||||
.cloud/
|
||||
*.db
|
||||
*.db-*
|
||||
bun.lockb
|
||||
.cursor/
|
||||
.cursor*
|
||||
.cursorconfig
|
||||
@@ -102,3 +102,10 @@ 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
|
||||
70
.github/workflows/deploy-docs.yml
vendored
70
.github/workflows/deploy-docs.yml
vendored
@@ -1,64 +1,34 @@
|
||||
name: Deploy Documentation to GitHub Pages
|
||||
|
||||
name: Deploy Documentation
|
||||
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
|
||||
- 'mkdocs.yml'
|
||||
|
||||
jobs:
|
||||
build:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: write
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Ruby
|
||||
uses: ruby/setup-ruby@v1
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
ruby-version: '3.2'
|
||||
bundler-cache: true
|
||||
cache-version: 0
|
||||
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v4
|
||||
|
||||
fetch-depth: 0
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.x'
|
||||
cache: 'pip'
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
cd docs
|
||||
bundle install
|
||||
|
||||
- name: Build site
|
||||
python -m pip install --upgrade pip
|
||||
pip install -r docs/requirements.txt
|
||||
- name: Configure Git
|
||||
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
|
||||
git config --global user.name "github-actions[bot]"
|
||||
git config --global user.email "github-actions[bot]@users.noreply.github.com"
|
||||
- name: Build and Deploy
|
||||
run: |
|
||||
mkdocs build --strict
|
||||
mkdocs gh-deploy --force --clean
|
||||
32
.github/workflows/docs-deploy.yml
vendored
32
.github/workflows/docs-deploy.yml
vendored
@@ -1,32 +0,0 @@
|
||||
name: Deploy Documentation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- 'mkdocs.yml'
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
deploy-docs:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: 3.x
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install mkdocs-material
|
||||
pip install mkdocs
|
||||
|
||||
- name: Deploy documentation
|
||||
run: mkdocs gh-deploy --force
|
||||
13
.gitignore
vendored
13
.gitignore
vendored
@@ -31,7 +31,7 @@ wheels/
|
||||
venv/
|
||||
ENV/
|
||||
env/
|
||||
|
||||
.venv/
|
||||
# Logs
|
||||
logs
|
||||
*.log
|
||||
@@ -88,3 +88,14 @@ site/
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
|
||||
models/
|
||||
|
||||
*.code-workspace
|
||||
*.ttf
|
||||
*.otf
|
||||
*.woff
|
||||
*.woff2
|
||||
*.eot
|
||||
*.svg
|
||||
*.png
|
||||
69
Dockerfile
69
Dockerfile
@@ -1,23 +1,70 @@
|
||||
# Use Bun as the base image
|
||||
FROM oven/bun:1.0.25
|
||||
# Use Node.js as base for building
|
||||
FROM node:20-slim as builder
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /app
|
||||
|
||||
# Copy package files
|
||||
# Install bun
|
||||
RUN npm install -g bun@1.0.25
|
||||
|
||||
# Install only the minimal dependencies needed and clean up in the same layer
|
||||
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/*
|
||||
|
||||
# Set build-time environment variables
|
||||
ENV NODE_ENV=production \
|
||||
NODE_OPTIONS="--max-old-space-size=2048" \
|
||||
BUN_INSTALL_CACHE=0
|
||||
|
||||
# Copy only package files first
|
||||
COPY package.json ./
|
||||
|
||||
# Install dependencies
|
||||
RUN bun install
|
||||
# Install dependencies with a clean slate
|
||||
RUN rm -rf node_modules .bun bun.lockb && \
|
||||
bun install --no-save
|
||||
|
||||
# Copy source code
|
||||
COPY . .
|
||||
# Copy source files and build
|
||||
COPY src ./src
|
||||
COPY tsconfig*.json ./
|
||||
RUN bun build ./src/index.ts --target=bun --minify --outdir=./dist
|
||||
|
||||
# Build TypeScript
|
||||
RUN bun run build
|
||||
# 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
|
||||
CMD ["bun", "run", "start"]
|
||||
# Start the application with optimized flags
|
||||
CMD ["bun", "--smol", "run", "start"]
|
||||
466
README.md
466
README.md
@@ -1,321 +1,239 @@
|
||||
# 🚀 Model Context Protocol (MCP) Server for Home Assistant
|
||||
# MCP Server for Home Assistant 🏠🤖
|
||||
|
||||
The **Model Context Protocol (MCP) Server** is a robust, secure, and high-performance bridge that integrates Home Assistant with Language Learning Models (LLMs), enabling natural language control and real-time monitoring of your smart home devices. Unlock advanced automation, control, and analytics for your Home Assistant ecosystem.
|
||||
[](LICENSE) [](https://bun.sh) [](https://www.typescriptlang.org) [](https://smithery.ai/server/@jango-blockchained/advanced-homeassistant-mcp)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[](https://jango-blockchained.github.io/homeassistant-mcp/)
|
||||
|
||||
## Overview 🌐
|
||||
|
||||
## 🌟 Key Benefits
|
||||
MCP (Model Context Protocol) Server is a lightweight integration tool for Home Assistant, providing a flexible interface for device management and automation.
|
||||
|
||||
### 🎮 Device Control & Monitoring
|
||||
- **Voice-like Control:** "Dim living room lights to 50%" 🌇
|
||||
- **Real-time Updates:** WebSocket/SSE with <100ms latency ⚡
|
||||
- **Cross-Device Automation:** Create scene-based rules 🎭
|
||||
## Core Features ✨
|
||||
|
||||
### 🤖 AI-Powered Features
|
||||
- Natural language processing for commands
|
||||
- Predictive automation suggestions
|
||||
- Anomaly detection in device behavior
|
||||
- 🔌 Basic device control via REST API
|
||||
- 📡 WebSocket/Server-Sent Events (SSE) for state updates
|
||||
- 🤖 Simple automation rule management
|
||||
- 🔐 JWT-based authentication
|
||||
- 🎤 Real-time device control and monitoring
|
||||
- 🎤 Server-Sent Events (SSE) for live updates
|
||||
- 🎤 Comprehensive logging
|
||||
- 🎤 Optional speech features:
|
||||
- 🎤 Wake word detection ("hey jarvis", "ok google", "alexa")
|
||||
- 🎤 Speech-to-text using fast-whisper
|
||||
- 🎤 Multiple language support
|
||||
- 🎤 GPU acceleration support
|
||||
|
||||
## 🏗 Architecture Overview
|
||||
## Prerequisites 📋
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[User Interface] --> B{MCP Server}
|
||||
B --> C[Home Assistant]
|
||||
B --> D[LLM Integration]
|
||||
B --> E[Cache Layer]
|
||||
E --> F[Redis]
|
||||
B --> G[Security Middleware]
|
||||
C --> H[Smart Devices]
|
||||
```
|
||||
- 🚀 Bun runtime (v1.0.26+)
|
||||
- 🏡 Home Assistant instance
|
||||
- 🐳 Docker (optional, recommended for deployment and speech features)
|
||||
- 🖥️ Node.js 18+ (optional, for speech features)
|
||||
- 🖥️ NVIDIA GPU with CUDA support (optional, for faster speech processing)
|
||||
|
||||
## 🛠 Installation
|
||||
## Installation 🛠️
|
||||
|
||||
### 🐳 Docker Setup (Recommended)
|
||||
### Docker Deployment (Recommended)
|
||||
|
||||
```bash
|
||||
# 1. Clone repo with caching
|
||||
git clone --depth 1 https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
# Clone the repository
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
|
||||
# 2. Configure environment
|
||||
cp .env.example .env # Edit with your HA details 🔧
|
||||
# Copy and edit environment configuration
|
||||
cp .env.example .env
|
||||
# Edit .env with your Home Assistant credentials and speech features settings
|
||||
|
||||
# 3. Start with compose
|
||||
docker compose up -d --build # Auto-scaling enabled 📈
|
||||
|
||||
# View real-time logs 📜
|
||||
docker compose logs -f --tail=50
|
||||
```
|
||||
|
||||
### 📦 Bare Metal Installation
|
||||
|
||||
```bash
|
||||
# Install Bun (if missing)
|
||||
curl -fsSL https://bun.sh/install | bash # 🐇 Fast runtime
|
||||
|
||||
# Install dependencies with cache
|
||||
bun install --frozen-lockfile # ♻️ Reliable dep tree
|
||||
|
||||
# Start in dev mode with hot-reload 🔥
|
||||
bun run dev --watch
|
||||
```
|
||||
|
||||
## 🚦 Rate Limiting Tiers
|
||||
|
||||
| Plan | Requests/min | Features | Cache TTL |
|
||||
|---------------|--------------|------------------------|-------------|
|
||||
| Free | 100 | Basic controls | 5min |
|
||||
| Pro | 1,000 | Priority queue | 1hr |
|
||||
| Enterprise | 10,000 | Dedicated cache | Custom |
|
||||
|
||||
## 💡 Example Usage
|
||||
|
||||
```javascript
|
||||
// Real-time device monitoring 🌐
|
||||
const ws = new WebSocket('wss://mcp.yourha.com/ws');
|
||||
|
||||
ws.onmessage = ({ data }) => {
|
||||
const update = JSON.parse(data);
|
||||
if(update.entity_id === 'light.kitchen') {
|
||||
smartBulb(update.state); // 🎛️ Update UI
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 🔄 Update Strategy
|
||||
|
||||
```bash
|
||||
# Zero-downtime updates 🕒
|
||||
docker compose pull
|
||||
# Build and start containers
|
||||
docker compose up -d --build
|
||||
docker system prune # Clean old images 🧹
|
||||
```
|
||||
|
||||
## 🛡 Security Features
|
||||
|
||||
- JWT authentication with refresh tokens 🔑
|
||||
- Automatic request sanitization 🧼
|
||||
- IP-based rate limiting with fail2ban integration 🚫
|
||||
- End-to-end encryption support 🔒
|
||||
|
||||
## 🌍 Community & Support
|
||||
|
||||
| Platform | Link | Response Time |
|
||||
|----------------|-------------------------------|---------------|
|
||||
| 📚 Docs | [API Reference](docs/api.md) | Instant |
|
||||
| 💬 Discord | [Join Chat](#) | <1hr |
|
||||
| 🐛 GitHub | [Issues](#) | <24hr |
|
||||
| 🐦 Twitter | [@HomeMCP](#) | <2hr |
|
||||
|
||||
## 🚧 Troubleshooting Guide
|
||||
### Bare Metal Installation
|
||||
|
||||
```bash
|
||||
# Check service health 🩺
|
||||
docker compose ps
|
||||
# Install Bun
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# Test API endpoints 🔌
|
||||
curl -I http://localhost:3000/healthcheck # Should return 200 ✅
|
||||
# Clone the repository
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
|
||||
# Inspect cache status 💾
|
||||
docker exec mcp_redis redis-cli info memory
|
||||
```
|
||||
# Install dependencies
|
||||
bun install
|
||||
|
||||
## 🔮 Roadmap Highlights
|
||||
|
||||
- [ ] **AI Assistant Integration** (Q4 2024) 🤖
|
||||
- [ ] **Predictive Automation** (Q1 2025) 🔮
|
||||
- [x] **Real-time Analytics** (Shipped! 🚀)
|
||||
- [ ] **Energy Optimization** (Q3 2024) 🌱
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
We love community input! Here's how to help:
|
||||
|
||||
1. 🍴 Fork the repository
|
||||
2. 🌿 Create a feature branch
|
||||
3. 💻 Make your changes
|
||||
4. 🧪 Run tests: `bun test --coverage`
|
||||
5. 📦 Commit using [Conventional Commits](https://www.conventionalcommits.org)
|
||||
6. 🔀 Open a Pull Request
|
||||
|
||||
**Pro Tip:** Check our [Good First Issues](https://github.com/jango-blockchained/homeassistant-mcp/contribute) for starter tasks! 🎯
|
||||
|
||||
---
|
||||
|
||||
**📢 Note:** This project adheres to [Semantic Versioning](https://semver.org). Always check breaking changes in release notes before upgrading! ⚠️
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Key Features](#key-features)
|
||||
- [Architecture & Design](#architecture--design)
|
||||
- [Installation](#installation)
|
||||
- [Basic Setup](#basic-setup)
|
||||
- [Docker Setup (Recommended)](#docker-setup-recommended)
|
||||
- [Usage](#usage)
|
||||
- [API & Documentation](#api--documentation)
|
||||
- [Development](#development)
|
||||
- [Roadmap & Future Plans](#roadmap--future-plans)
|
||||
- [Community & Support](#community--support)
|
||||
- [Contributing](#contributing)
|
||||
- [Troubleshooting & FAQ](#troubleshooting--faq)
|
||||
- [License](#license)
|
||||
|
||||
## Overview
|
||||
|
||||
The MCP Server bridges Home Assistant with advanced LLM integrations to deliver intuitive control, automation, and state monitoring. Leveraging a high-performance runtime and real-time communication protocols, MCP offers a seamless experience for managing your smart home.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Device Control & Monitoring
|
||||
- **Smart Device Control:** Manage lights, climate, covers, switches, sensors, media players, fans, locks, vacuums, and cameras using natural language commands.
|
||||
- **Real-time Updates:** Receive instant notifications and updates via Server-Sent Events (SSE).
|
||||
|
||||
### System & Automation Management
|
||||
- **Automation Engine:** Create, modify, and trigger custom automation rules with ease.
|
||||
- **Add-on & Package Management:** Integrates with HACS for deploying custom integrations, themes, scripts, and applications.
|
||||
- **Robust System Management:** Features advanced state monitoring, error handling, and security safeguards.
|
||||
|
||||
## Architecture & Design
|
||||
|
||||
The MCP Server is built with scalability, resilience, and security in mind:
|
||||
|
||||
- **High-Performance Runtime:** Powered by Bun for fast startup, efficient memory utilization, and native TypeScript support.
|
||||
- **Real-time Communication:** Employs Server-Sent Events (SSE) for continuous, real-time data updates.
|
||||
- **Modular & Extensible:** Designed to support plugins, add-ons, and custom automation scripts, allowing for easy expansion.
|
||||
- **Secure API Integration:** Implements token-based authentication, rate limiting, and adherence to best security practices.
|
||||
|
||||
For a deeper dive into the system architecture, please refer to our [Architecture Documentation](docs/architecture.md).
|
||||
|
||||
## Usage
|
||||
|
||||
Once the server is running, open your browser at [http://localhost:3000](http://localhost:3000). For real-time device updates, integrate the SSE endpoint in your application:
|
||||
|
||||
```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('Update received:', data);
|
||||
};
|
||||
```
|
||||
|
||||
## API & Documentation
|
||||
|
||||
Access comprehensive API details and guides in the docs directory:
|
||||
|
||||
- **API Reference:** [API Documentation](docs/api.md)
|
||||
- **SSE Documentation:** [SSE API](docs/sse-api.md)
|
||||
- **Troubleshooting Guide:** [Troubleshooting](docs/troubleshooting.md)
|
||||
- **Architecture Details:** [Architecture Documentation](docs/architecture.md)
|
||||
|
||||
## Development
|
||||
|
||||
### Running in Development Mode
|
||||
|
||||
```bash
|
||||
# Start the server
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
## Basic Usage 🖥️
|
||||
|
||||
- Execute all tests:
|
||||
```bash
|
||||
bun test
|
||||
### Device Control Example
|
||||
|
||||
```typescript
|
||||
// Turn on a light
|
||||
const response = await fetch('http://localhost:3000/api/devices/light.living_room', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${token}`
|
||||
},
|
||||
body: JSON.stringify({ state: 'on' })
|
||||
});
|
||||
```
|
||||
|
||||
- Run tests with coverage:
|
||||
```bash
|
||||
bun test --coverage
|
||||
### WebSocket State Updates
|
||||
|
||||
```typescript
|
||||
const ws = new WebSocket('ws://localhost:3000/devices');
|
||||
ws.onmessage = (event) => {
|
||||
const deviceState = JSON.parse(event.data);
|
||||
console.log('Device state updated:', deviceState);
|
||||
};
|
||||
```
|
||||
|
||||
### Production Build & Start
|
||||
## Speech Features (Optional)
|
||||
|
||||
The MCP Server includes optional speech processing capabilities:
|
||||
|
||||
### Prerequisites
|
||||
1. Docker installed and running
|
||||
2. NVIDIA GPU with CUDA support (optional)
|
||||
3. At least 4GB RAM (8GB+ recommended for larger models)
|
||||
|
||||
### Setup
|
||||
|
||||
1. Enable speech features in your .env:
|
||||
```bash
|
||||
bun run build
|
||||
bun start
|
||||
ENABLE_SPEECH_FEATURES=true
|
||||
ENABLE_WAKE_WORD=true
|
||||
ENABLE_SPEECH_TO_TEXT=true
|
||||
WHISPER_MODEL_PATH=/models
|
||||
WHISPER_MODEL_TYPE=base
|
||||
```
|
||||
|
||||
## Roadmap & Future Plans
|
||||
|
||||
The MCP Server is under active development and improvement. Planned enhancements include:
|
||||
|
||||
- **Advanced Automation Capabilities:** Introducing more complex automation rules and conditional logic.
|
||||
- **Enhanced Security Features:** Additional authentication layers, encryption enhancements, and security monitoring tools.
|
||||
- **User Interface Improvements:** Development of a more intuitive web dashboard for easier device management.
|
||||
- **Expanded Integrations:** Support for a wider array of smart home devices and third-party services.
|
||||
- **Performance Optimizations:** Continued efforts to reduce latency and improve resource efficiency.
|
||||
|
||||
For additional details, check out our [Roadmap](docs/roadmap.md).
|
||||
|
||||
## Community & Support
|
||||
|
||||
Join our community to stay updated, share ideas, and get help:
|
||||
|
||||
- **GitHub Issues:** Report bugs or suggest features on our [GitHub Issues Page](https://github.com/jango-blockchained/homeassistant-mcp/issues).
|
||||
- **Discussion Forums:** Connect with other users and contributors in our community forums.
|
||||
- **Chat Platforms:** Join our real-time discussions on [Discord](#) or [Slack](#).
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome your contributions! To get started:
|
||||
|
||||
1. Fork the repository.
|
||||
2. Create your feature branch:
|
||||
2. Start the speech services:
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
docker-compose up -d
|
||||
```
|
||||
3. Install dependencies:
|
||||
```bash
|
||||
bun install
|
||||
|
||||
### Available Models
|
||||
|
||||
Choose a model based on your needs:
|
||||
- `tiny.en`: Fastest, basic accuracy
|
||||
- `base.en`: Good balance (recommended)
|
||||
- `small.en`: Better accuracy, slower
|
||||
- `medium.en`: High accuracy, resource intensive
|
||||
- `large-v2`: Best accuracy, very resource intensive
|
||||
|
||||
### Usage
|
||||
|
||||
1. Wake word detection listens for:
|
||||
- "hey jarvis"
|
||||
- "ok google"
|
||||
- "alexa"
|
||||
|
||||
2. After wake word detection:
|
||||
- Audio is automatically captured
|
||||
- Speech is transcribed
|
||||
- Commands are processed
|
||||
|
||||
3. Manual transcription is also available:
|
||||
```typescript
|
||||
const speech = speechService.getSpeechToText();
|
||||
const text = await speech.transcribe(audioBuffer);
|
||||
```
|
||||
4. Make your changes and run tests:
|
||||
```bash
|
||||
bun test
|
||||
|
||||
## Configuration
|
||||
|
||||
See [Configuration Guide](docs/configuration.md) for detailed settings.
|
||||
|
||||
## API Documentation
|
||||
|
||||
See [API Documentation](docs/api/index.md) for available endpoints.
|
||||
|
||||
## Development
|
||||
|
||||
See [Development Guide](docs/development/index.md) for contribution guidelines.
|
||||
|
||||
## License 📄
|
||||
|
||||
MIT License. See [LICENSE](LICENSE) for details.
|
||||
|
||||
## Support 🆘
|
||||
|
||||
- 🐞 [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues)
|
||||
- 📖 Documentation: [Project Docs](https://jango-blockchained.github.io/homeassistant-mcp/)
|
||||
|
||||
## MCP Client Integration 🔗
|
||||
|
||||
This MCP server can be integrated with various clients that support the Model Context Protocol. Below are instructions for different client integrations:
|
||||
|
||||
### 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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
5. Commit and push your changes, then open a Pull Request.
|
||||
|
||||
For detailed guidelines, see [Contributing Guide](docs/contributing.md).
|
||||
### Claude Desktop Integration 💬
|
||||
|
||||
## Troubleshooting & FAQ
|
||||
For Claude Desktop, add the following to your Claude configuration file:
|
||||
|
||||
### Common Issues
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "bun",
|
||||
"args": ["run", "start", "--port", "8080"],
|
||||
"env": {
|
||||
"NODE_ENV": "production"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **Connection Problems:** Ensure that your `HASS_HOST`, authentication token, and WebSocket URL are correctly configured.
|
||||
- **Docker Deployment:** Confirm that Docker is running and that your `.env` file contains the correct settings.
|
||||
- **Automation Errors:** Verify entity availability and review your automation configurations for potential issues.
|
||||
### Cline Integration 📟
|
||||
|
||||
For more troubleshooting details, refer to [Troubleshooting Guide](docs/troubleshooting.md).
|
||||
For Cline-based clients, add the following configuration:
|
||||
|
||||
### Frequently Asked Questions
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "bun",
|
||||
"args": [
|
||||
"run",
|
||||
"start",
|
||||
"--enable-cline",
|
||||
"--config",
|
||||
"${configDir}/.env"
|
||||
],
|
||||
"env": {
|
||||
"NODE_ENV": "production",
|
||||
"CLINE_MODE": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Q: What platforms does MCP Server support?**
|
||||
### Command Line Usage 💻
|
||||
|
||||
A: MCP Server runs on Linux, macOS, and Windows (Docker is recommended for Windows environments).
|
||||
#### Windows
|
||||
A CMD script is provided in the `scripts` directory. To use it:
|
||||
|
||||
**Q: How do I report a bug or request a feature?**
|
||||
1. Navigate to the `scripts` directory
|
||||
2. Run `start_mcp.cmd`
|
||||
|
||||
A: Please use our [GitHub Issues Page](https://github.com/jango-blockchained/homeassistant-mcp/issues) to report bugs or request new features.
|
||||
|
||||
**Q: Can I contribute to the project?**
|
||||
|
||||
A: Absolutely! We welcome contributions from the community. See the [Contributing](#contributing) section for more details.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License. See [LICENSE](LICENSE) for the full license text.
|
||||
|
||||
## Documentation
|
||||
|
||||
Full documentation is available at: [https://jango-blockchained.github.io/homeassistant-mcp/](https://jango-blockchained.github.io/homeassistant-mcp/)
|
||||
|
||||
## Quick Start
|
||||
|
||||
## Installation
|
||||
|
||||
## Usage
|
||||
The script will start the MCP server with default configuration.
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
|
||||
import express from 'express';
|
||||
import request from 'supertest';
|
||||
@@ -5,10 +6,10 @@ import router from '../../../src/ai/endpoints/ai-router.js';
|
||||
import type { AIResponse, AIError } from '../../../src/ai/types/index.js';
|
||||
|
||||
// Mock NLPProcessor
|
||||
jest.mock('../../../src/ai/nlp/processor.js', () => {
|
||||
// // jest.mock('../../../src/ai/nlp/processor.js', () => {
|
||||
return {
|
||||
NLPProcessor: jest.fn().mockImplementation(() => ({
|
||||
processCommand: jest.fn().mockImplementation(async () => ({
|
||||
NLPProcessor: mock().mockImplementation(() => ({
|
||||
processCommand: mock().mockImplementation(async () => ({
|
||||
intent: {
|
||||
action: 'turn_on',
|
||||
target: 'light.living_room',
|
||||
@@ -21,8 +22,8 @@ jest.mock('../../../src/ai/nlp/processor.js', () => {
|
||||
context: 0.9
|
||||
}
|
||||
})),
|
||||
validateIntent: jest.fn().mockImplementation(async () => true),
|
||||
suggestCorrections: jest.fn().mockImplementation(async () => [
|
||||
validateIntent: mock().mockImplementation(async () => true),
|
||||
suggestCorrections: mock().mockImplementation(async () => [
|
||||
'Try using simpler commands',
|
||||
'Specify the device name clearly'
|
||||
])
|
||||
@@ -57,7 +58,7 @@ describe('AI Router', () => {
|
||||
model: 'claude' as const
|
||||
};
|
||||
|
||||
it('should successfully interpret a valid command', async () => {
|
||||
test('should successfully interpret a valid command', async () => {
|
||||
const response = await request(app)
|
||||
.post('/ai/interpret')
|
||||
.send(validRequest);
|
||||
@@ -81,7 +82,7 @@ describe('AI Router', () => {
|
||||
expect(body.context).toBeDefined();
|
||||
});
|
||||
|
||||
it('should handle invalid input format', async () => {
|
||||
test('should handle invalid input format', async () => {
|
||||
const response = await request(app)
|
||||
.post('/ai/interpret')
|
||||
.send({
|
||||
@@ -97,7 +98,7 @@ describe('AI Router', () => {
|
||||
expect(Array.isArray(error.recovery_options)).toBe(true);
|
||||
});
|
||||
|
||||
it('should handle missing required fields', async () => {
|
||||
test('should handle missing required fields', async () => {
|
||||
const response = await request(app)
|
||||
.post('/ai/interpret')
|
||||
.send({
|
||||
@@ -111,7 +112,7 @@ describe('AI Router', () => {
|
||||
expect(typeof error.message).toBe('string');
|
||||
});
|
||||
|
||||
it('should handle rate limiting', async () => {
|
||||
test('should handle rate limiting', async () => {
|
||||
// Make multiple requests to trigger rate limiting
|
||||
const requests = Array(101).fill(validRequest);
|
||||
const responses = await Promise.all(
|
||||
@@ -145,7 +146,7 @@ describe('AI Router', () => {
|
||||
model: 'claude' as const
|
||||
};
|
||||
|
||||
it('should successfully execute a valid intent', async () => {
|
||||
test('should successfully execute a valid intent', async () => {
|
||||
const response = await request(app)
|
||||
.post('/ai/execute')
|
||||
.send(validRequest);
|
||||
@@ -169,7 +170,7 @@ describe('AI Router', () => {
|
||||
expect(body.context).toBeDefined();
|
||||
});
|
||||
|
||||
it('should handle invalid intent format', async () => {
|
||||
test('should handle invalid intent format', async () => {
|
||||
const response = await request(app)
|
||||
.post('/ai/execute')
|
||||
.send({
|
||||
@@ -199,7 +200,7 @@ describe('AI Router', () => {
|
||||
model: 'claude' as const
|
||||
};
|
||||
|
||||
it('should return a list of suggestions', async () => {
|
||||
test('should return a list of suggestions', async () => {
|
||||
const response = await request(app)
|
||||
.get('/ai/suggestions')
|
||||
.send(validRequest);
|
||||
@@ -209,7 +210,7 @@ describe('AI Router', () => {
|
||||
expect(response.body.suggestions.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('should handle missing context', async () => {
|
||||
test('should handle missing context', async () => {
|
||||
const response = await request(app)
|
||||
.get('/ai/suggestions')
|
||||
.send({});
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { IntentClassifier } from '../../../src/ai/nlp/intent-classifier.js';
|
||||
|
||||
describe('IntentClassifier', () => {
|
||||
@@ -8,7 +9,7 @@ describe('IntentClassifier', () => {
|
||||
});
|
||||
|
||||
describe('Basic Intent Classification', () => {
|
||||
it('should classify turn_on commands', async () => {
|
||||
test('should classify turn_on commands', async () => {
|
||||
const testCases = [
|
||||
{
|
||||
input: 'turn on the living room light',
|
||||
@@ -35,7 +36,7 @@ describe('IntentClassifier', () => {
|
||||
}
|
||||
});
|
||||
|
||||
it('should classify turn_off commands', async () => {
|
||||
test('should classify turn_off commands', async () => {
|
||||
const testCases = [
|
||||
{
|
||||
input: 'turn off the living room light',
|
||||
@@ -62,7 +63,7 @@ describe('IntentClassifier', () => {
|
||||
}
|
||||
});
|
||||
|
||||
it('should classify set commands with parameters', async () => {
|
||||
test('should classify set commands with parameters', async () => {
|
||||
const testCases = [
|
||||
{
|
||||
input: 'set the living room light brightness to 50',
|
||||
@@ -99,7 +100,7 @@ describe('IntentClassifier', () => {
|
||||
}
|
||||
});
|
||||
|
||||
it('should classify query commands', async () => {
|
||||
test('should classify query commands', async () => {
|
||||
const testCases = [
|
||||
{
|
||||
input: 'what is the living room temperature',
|
||||
@@ -128,13 +129,13 @@ describe('IntentClassifier', () => {
|
||||
});
|
||||
|
||||
describe('Edge Cases and Error Handling', () => {
|
||||
it('should handle empty input gracefully', async () => {
|
||||
test('should handle empty input gracefully', async () => {
|
||||
const result = await classifier.classify('', { parameters: {}, primary_target: '' });
|
||||
expect(result.action).toBe('unknown');
|
||||
expect(result.confidence).toBeLessThan(0.5);
|
||||
});
|
||||
|
||||
it('should handle unknown commands with low confidence', async () => {
|
||||
test('should handle unknown commands with low confidence', async () => {
|
||||
const result = await classifier.classify(
|
||||
'do something random',
|
||||
{ parameters: {}, primary_target: 'light.living_room' }
|
||||
@@ -143,7 +144,7 @@ describe('IntentClassifier', () => {
|
||||
expect(result.confidence).toBeLessThan(0.5);
|
||||
});
|
||||
|
||||
it('should handle missing entities gracefully', async () => {
|
||||
test('should handle missing entities gracefully', async () => {
|
||||
const result = await classifier.classify(
|
||||
'turn on the lights',
|
||||
{ parameters: {}, primary_target: '' }
|
||||
@@ -154,7 +155,7 @@ describe('IntentClassifier', () => {
|
||||
});
|
||||
|
||||
describe('Confidence Calculation', () => {
|
||||
it('should assign higher confidence to exact matches', async () => {
|
||||
test('should assign higher confidence to exact matches', async () => {
|
||||
const exactMatch = await classifier.classify(
|
||||
'turn on',
|
||||
{ parameters: {}, primary_target: 'light.living_room' }
|
||||
@@ -166,7 +167,7 @@ describe('IntentClassifier', () => {
|
||||
expect(exactMatch.confidence).toBeGreaterThan(partialMatch.confidence);
|
||||
});
|
||||
|
||||
it('should boost confidence for polite phrases', async () => {
|
||||
test('should boost confidence for polite phrases', async () => {
|
||||
const politeRequest = await classifier.classify(
|
||||
'please turn on the lights',
|
||||
{ parameters: {}, primary_target: 'light.living_room' }
|
||||
@@ -180,7 +181,7 @@ describe('IntentClassifier', () => {
|
||||
});
|
||||
|
||||
describe('Context Inference', () => {
|
||||
it('should infer set action when parameters are present', async () => {
|
||||
test('should infer set action when parameters are present', async () => {
|
||||
const result = await classifier.classify(
|
||||
'lights at 50%',
|
||||
{
|
||||
@@ -192,7 +193,7 @@ describe('IntentClassifier', () => {
|
||||
expect(result.parameters).toHaveProperty('brightness', 50);
|
||||
});
|
||||
|
||||
it('should infer query action for question-like inputs', async () => {
|
||||
test('should infer query action for question-like inputs', async () => {
|
||||
const result = await classifier.classify(
|
||||
'how warm is it',
|
||||
{ parameters: {}, primary_target: 'sensor.temperature' }
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
|
||||
import express from 'express';
|
||||
import request from 'supertest';
|
||||
@@ -11,9 +12,9 @@ import { MCP_SCHEMA } from '../../src/mcp/schema.js';
|
||||
config({ path: resolve(process.cwd(), '.env.test') });
|
||||
|
||||
// Mock dependencies
|
||||
jest.mock('../../src/security/index.js', () => ({
|
||||
// // jest.mock('../../src/security/index.js', () => ({
|
||||
TokenManager: {
|
||||
validateToken: jest.fn().mockImplementation((token) => token === 'valid-test-token'),
|
||||
validateToken: mock().mockImplementation((token) => token === 'valid-test-token'),
|
||||
},
|
||||
rateLimiter: (req: any, res: any, next: any) => next(),
|
||||
securityHeaders: (req: any, res: any, next: any) => next(),
|
||||
@@ -39,11 +40,11 @@ const mockEntity: Entity = {
|
||||
};
|
||||
|
||||
// Mock Home Assistant module
|
||||
jest.mock('../../src/hass/index.js');
|
||||
// // jest.mock('../../src/hass/index.js');
|
||||
|
||||
// Mock LiteMCP
|
||||
jest.mock('litemcp', () => ({
|
||||
LiteMCP: jest.fn().mockImplementation(() => ({
|
||||
// // jest.mock('litemcp', () => ({
|
||||
LiteMCP: mock().mockImplementation(() => ({
|
||||
name: 'home-assistant',
|
||||
version: '0.1.0',
|
||||
tools: []
|
||||
@@ -61,7 +62,7 @@ app.get('/mcp', (_req, res) => {
|
||||
|
||||
app.get('/state', (req, res) => {
|
||||
const authHeader = req.headers.authorization;
|
||||
if (!authHeader || !authHeader.startsWith('Bearer ') || authHeader.split(' ')[1] !== 'valid-test-token') {
|
||||
if (!authHeader || !authHeader.startsWith('Bearer ') || authHeader.spltest(' ')[1] !== 'valid-test-token') {
|
||||
return res.status(401).json({ error: 'Unauthorized' });
|
||||
}
|
||||
res.json([mockEntity]);
|
||||
@@ -69,7 +70,7 @@ app.get('/state', (req, res) => {
|
||||
|
||||
app.post('/command', (req, res) => {
|
||||
const authHeader = req.headers.authorization;
|
||||
if (!authHeader || !authHeader.startsWith('Bearer ') || authHeader.split(' ')[1] !== 'valid-test-token') {
|
||||
if (!authHeader || !authHeader.startsWith('Bearer ') || authHeader.spltest(' ')[1] !== 'valid-test-token') {
|
||||
return res.status(401).json({ error: 'Unauthorized' });
|
||||
}
|
||||
|
||||
@@ -87,7 +88,7 @@ app.post('/command', (req, res) => {
|
||||
|
||||
describe('API Endpoints', () => {
|
||||
describe('GET /mcp', () => {
|
||||
it('should return MCP schema without authentication', async () => {
|
||||
test('should return MCP schema without authentication', async () => {
|
||||
const response = await request(app)
|
||||
.get('/mcp')
|
||||
.expect('Content-Type', /json/)
|
||||
@@ -102,13 +103,13 @@ describe('API Endpoints', () => {
|
||||
|
||||
describe('Protected Endpoints', () => {
|
||||
describe('GET /state', () => {
|
||||
it('should return 401 without authentication', async () => {
|
||||
test('should return 401 without authentication', async () => {
|
||||
await request(app)
|
||||
.get('/state')
|
||||
.expect(401);
|
||||
});
|
||||
|
||||
it('should return state with valid token', async () => {
|
||||
test('should return state with valid token', async () => {
|
||||
const response = await request(app)
|
||||
.get('/state')
|
||||
.set('Authorization', 'Bearer valid-test-token')
|
||||
@@ -123,7 +124,7 @@ describe('API Endpoints', () => {
|
||||
});
|
||||
|
||||
describe('POST /command', () => {
|
||||
it('should return 401 without authentication', async () => {
|
||||
test('should return 401 without authentication', async () => {
|
||||
await request(app)
|
||||
.post('/command')
|
||||
.send({
|
||||
@@ -133,7 +134,7 @@ describe('API Endpoints', () => {
|
||||
.expect(401);
|
||||
});
|
||||
|
||||
it('should process valid command with authentication', async () => {
|
||||
test('should process valid command with authentication', async () => {
|
||||
const response = await request(app)
|
||||
.set('Authorization', 'Bearer valid-test-token')
|
||||
.post('/command')
|
||||
@@ -148,7 +149,7 @@ describe('API Endpoints', () => {
|
||||
expect(response.body).toHaveProperty('success', true);
|
||||
});
|
||||
|
||||
it('should validate command parameters', async () => {
|
||||
test('should validate command parameters', async () => {
|
||||
await request(app)
|
||||
.post('/command')
|
||||
.set('Authorization', 'Bearer valid-test-token')
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { jest, describe, beforeEach, it, expect } from '@jest/globals';
|
||||
import { z } from 'zod';
|
||||
import { DomainSchema } from '../../src/schemas.js';
|
||||
@@ -80,7 +81,7 @@ describe('Context Tests', () => {
|
||||
});
|
||||
|
||||
// Add your test cases here
|
||||
it('should execute tool successfully', async () => {
|
||||
test('should execute tool successfully', async () => {
|
||||
const result = await mockTool.execute({ test: 'value' });
|
||||
expect(result.success).toBe(true);
|
||||
});
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { jest, describe, it, expect } from '@jest/globals';
|
||||
import { ContextManager, ResourceType, RelationType, ResourceState } from '../../src/context/index.js';
|
||||
|
||||
@@ -5,7 +6,7 @@ describe('Context Manager', () => {
|
||||
describe('Resource Management', () => {
|
||||
const contextManager = new ContextManager();
|
||||
|
||||
it('should add resources', () => {
|
||||
test('should add resources', () => {
|
||||
const resource: ResourceState = {
|
||||
id: 'light.living_room',
|
||||
type: ResourceType.DEVICE,
|
||||
@@ -20,7 +21,7 @@ describe('Context Manager', () => {
|
||||
expect(retrievedResource).toEqual(resource);
|
||||
});
|
||||
|
||||
it('should update resources', () => {
|
||||
test('should update resources', () => {
|
||||
const resource: ResourceState = {
|
||||
id: 'light.living_room',
|
||||
type: ResourceType.DEVICE,
|
||||
@@ -35,14 +36,14 @@ describe('Context Manager', () => {
|
||||
expect(retrievedResource?.state).toBe('off');
|
||||
});
|
||||
|
||||
it('should remove resources', () => {
|
||||
test('should remove resources', () => {
|
||||
const resourceId = 'light.living_room';
|
||||
contextManager.removeResource(resourceId);
|
||||
const retrievedResource = contextManager.getResource(resourceId);
|
||||
expect(retrievedResource).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should get resources by type', () => {
|
||||
test('should get resources by type', () => {
|
||||
const light1: ResourceState = {
|
||||
id: 'light.living_room',
|
||||
type: ResourceType.DEVICE,
|
||||
@@ -73,7 +74,7 @@ describe('Context Manager', () => {
|
||||
describe('Relationship Management', () => {
|
||||
const contextManager = new ContextManager();
|
||||
|
||||
it('should add relationships', () => {
|
||||
test('should add relationships', () => {
|
||||
const light: ResourceState = {
|
||||
id: 'light.living_room',
|
||||
type: ResourceType.DEVICE,
|
||||
@@ -106,7 +107,7 @@ describe('Context Manager', () => {
|
||||
expect(related[0]).toEqual(room);
|
||||
});
|
||||
|
||||
it('should remove relationships', () => {
|
||||
test('should remove relationships', () => {
|
||||
const sourceId = 'light.living_room';
|
||||
const targetId = 'room.living_room';
|
||||
contextManager.removeRelationship(sourceId, targetId, RelationType.CONTAINS);
|
||||
@@ -114,7 +115,7 @@ describe('Context Manager', () => {
|
||||
expect(related).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should get related resources with depth', () => {
|
||||
test('should get related resources with depth', () => {
|
||||
const light: ResourceState = {
|
||||
id: 'light.living_room',
|
||||
type: ResourceType.DEVICE,
|
||||
@@ -148,7 +149,7 @@ describe('Context Manager', () => {
|
||||
describe('Resource Analysis', () => {
|
||||
const contextManager = new ContextManager();
|
||||
|
||||
it('should analyze resource usage', () => {
|
||||
test('should analyze resource usage', () => {
|
||||
const light: ResourceState = {
|
||||
id: 'light.living_room',
|
||||
type: ResourceType.DEVICE,
|
||||
@@ -171,8 +172,8 @@ describe('Context Manager', () => {
|
||||
describe('Event Subscriptions', () => {
|
||||
const contextManager = new ContextManager();
|
||||
|
||||
it('should handle resource subscriptions', () => {
|
||||
const callback = jest.fn();
|
||||
test('should handle resource subscriptions', () => {
|
||||
const callback = mock();
|
||||
const resourceId = 'light.living_room';
|
||||
const resource: ResourceState = {
|
||||
id: resourceId,
|
||||
@@ -189,8 +190,8 @@ describe('Context Manager', () => {
|
||||
expect(callback).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle type subscriptions', () => {
|
||||
const callback = jest.fn();
|
||||
test('should handle type subscriptions', () => {
|
||||
const callback = mock();
|
||||
const type = ResourceType.DEVICE;
|
||||
|
||||
const unsubscribe = contextManager.subscribeToType(type, callback);
|
||||
|
||||
75
__tests__/core/server.test.ts
Normal file
75
__tests__/core/server.test.ts
Normal file
@@ -0,0 +1,75 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
|
||||
import {
|
||||
type MockLiteMCPInstance,
|
||||
type Tool,
|
||||
createMockLiteMCPInstance,
|
||||
createMockServices,
|
||||
setupTestEnvironment,
|
||||
cleanupMocks
|
||||
} from '../utils/test-utils';
|
||||
import { resolve } from "path";
|
||||
import { config } from "dotenv";
|
||||
import { Tool as IndexTool, tools as indexTools } from "../../src/index.js";
|
||||
|
||||
// Load test environment variables
|
||||
config({ path: resolve(process.cwd(), '.env.test') });
|
||||
|
||||
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);
|
||||
});
|
||||
|
||||
test('should register all required tools', () => {
|
||||
const toolNames = indexTools.map((tool: IndexTool) => tool.name);
|
||||
|
||||
expect(toolNames).toContain('list_devices');
|
||||
expect(toolNames).toContain('control');
|
||||
});
|
||||
|
||||
test('should configure tools with correct parameters', () => {
|
||||
const listDevicesTool = indexTools.find((tool: IndexTool) => tool.name === 'list_devices');
|
||||
expect(listDevicesTool).toBeDefined();
|
||||
expect(listDevicesTool?.description).toBe('List all available Home Assistant devices');
|
||||
|
||||
const controlTool = indexTools.find((tool: IndexTool) => tool.name === 'control');
|
||||
expect(controlTool).toBeDefined();
|
||||
expect(controlTool?.description).toBe('Control Home Assistant devices and services');
|
||||
});
|
||||
});
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { HassInstanceImpl } from '../../src/hass/index.js';
|
||||
import * as HomeAssistant from '../../src/types/hass.js';
|
||||
import { HassWebSocketClient } from '../../src/websocket/client.js';
|
||||
@@ -54,8 +55,8 @@ interface MockWebSocketConstructor extends jest.Mock<MockWebSocketInstance> {
|
||||
}
|
||||
|
||||
// Mock the entire hass module
|
||||
jest.mock('../../src/hass/index.js', () => ({
|
||||
get_hass: jest.fn()
|
||||
// // jest.mock('../../src/hass/index.js', () => ({
|
||||
get_hass: mock()
|
||||
}));
|
||||
|
||||
describe('Home Assistant API', () => {
|
||||
@@ -66,11 +67,11 @@ describe('Home Assistant API', () => {
|
||||
beforeEach(() => {
|
||||
hass = new HassInstanceImpl('http://localhost:8123', 'test_token');
|
||||
mockWs = {
|
||||
send: jest.fn(),
|
||||
close: jest.fn(),
|
||||
addEventListener: jest.fn(),
|
||||
removeEventListener: jest.fn(),
|
||||
dispatchEvent: jest.fn(),
|
||||
send: mock(),
|
||||
close: mock(),
|
||||
addEventListener: mock(),
|
||||
removeEventListener: mock(),
|
||||
dispatchEvent: mock(),
|
||||
onopen: null,
|
||||
onclose: null,
|
||||
onmessage: null,
|
||||
@@ -84,7 +85,7 @@ describe('Home Assistant API', () => {
|
||||
} as MockWebSocketInstance;
|
||||
|
||||
// Create a mock WebSocket constructor
|
||||
MockWebSocket = jest.fn().mockImplementation(() => mockWs) as MockWebSocketConstructor;
|
||||
MockWebSocket = mock().mockImplementation(() => mockWs) as MockWebSocketConstructor;
|
||||
MockWebSocket.CONNECTING = 0;
|
||||
MockWebSocket.OPEN = 1;
|
||||
MockWebSocket.CLOSING = 2;
|
||||
@@ -96,7 +97,7 @@ describe('Home Assistant API', () => {
|
||||
});
|
||||
|
||||
describe('State Management', () => {
|
||||
it('should fetch all states', async () => {
|
||||
test('should fetch all states', async () => {
|
||||
const mockStates: HomeAssistant.Entity[] = [
|
||||
{
|
||||
entity_id: 'light.living_room',
|
||||
@@ -108,7 +109,7 @@ describe('Home Assistant API', () => {
|
||||
}
|
||||
];
|
||||
|
||||
global.fetch = jest.fn().mockResolvedValueOnce({
|
||||
global.fetch = mock().mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: () => Promise.resolve(mockStates)
|
||||
});
|
||||
@@ -121,7 +122,7 @@ describe('Home Assistant API', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('should fetch single state', async () => {
|
||||
test('should fetch single state', async () => {
|
||||
const mockState: HomeAssistant.Entity = {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'on',
|
||||
@@ -131,7 +132,7 @@ describe('Home Assistant API', () => {
|
||||
context: { id: '123', parent_id: null, user_id: null }
|
||||
};
|
||||
|
||||
global.fetch = jest.fn().mockResolvedValueOnce({
|
||||
global.fetch = mock().mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: () => Promise.resolve(mockState)
|
||||
});
|
||||
@@ -144,16 +145,16 @@ describe('Home Assistant API', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle state fetch errors', async () => {
|
||||
global.fetch = jest.fn().mockRejectedValueOnce(new Error('Failed to fetch states'));
|
||||
test('should handle state fetch errors', async () => {
|
||||
global.fetch = mock().mockRejectedValueOnce(new Error('Failed to fetch states'));
|
||||
|
||||
await expect(hass.fetchStates()).rejects.toThrow('Failed to fetch states');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Service Calls', () => {
|
||||
it('should call service', async () => {
|
||||
global.fetch = jest.fn().mockResolvedValueOnce({
|
||||
test('should call service', async () => {
|
||||
global.fetch = mock().mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({})
|
||||
});
|
||||
@@ -175,8 +176,8 @@ describe('Home Assistant API', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle service call errors', async () => {
|
||||
global.fetch = jest.fn().mockRejectedValueOnce(new Error('Service call failed'));
|
||||
test('should handle service call errors', async () => {
|
||||
global.fetch = mock().mockRejectedValueOnce(new Error('Service call failed'));
|
||||
|
||||
await expect(
|
||||
hass.callService('invalid_domain', 'invalid_service', {})
|
||||
@@ -185,8 +186,8 @@ describe('Home Assistant API', () => {
|
||||
});
|
||||
|
||||
describe('Event Subscription', () => {
|
||||
it('should subscribe to events', async () => {
|
||||
const callback = jest.fn();
|
||||
test('should subscribe to events', async () => {
|
||||
const callback = mock();
|
||||
await hass.subscribeEvents(callback, 'state_changed');
|
||||
|
||||
expect(MockWebSocket).toHaveBeenCalledWith(
|
||||
@@ -194,8 +195,8 @@ describe('Home Assistant API', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle subscription errors', async () => {
|
||||
const callback = jest.fn();
|
||||
test('should handle subscription errors', async () => {
|
||||
const callback = mock();
|
||||
MockWebSocket.mockImplementation(() => {
|
||||
throw new Error('WebSocket connection failed');
|
||||
});
|
||||
@@ -207,14 +208,14 @@ describe('Home Assistant API', () => {
|
||||
});
|
||||
|
||||
describe('WebSocket connection', () => {
|
||||
it('should connect to WebSocket endpoint', async () => {
|
||||
test('should connect to WebSocket endpoint', async () => {
|
||||
await hass.subscribeEvents(() => { });
|
||||
expect(MockWebSocket).toHaveBeenCalledWith(
|
||||
'ws://localhost:8123/api/websocket'
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle connection errors', async () => {
|
||||
test('should handle connection errors', async () => {
|
||||
MockWebSocket.mockImplementation(() => {
|
||||
throw new Error('Connection failed');
|
||||
});
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { jest, describe, beforeEach, afterAll, it, expect } from '@jest/globals';
|
||||
import type { Mock } from 'jest-mock';
|
||||
|
||||
@@ -40,7 +41,7 @@ jest.unstable_mockModule('@digital-alchemy/core', () => ({
|
||||
bootstrap: async () => mockInstance,
|
||||
services: {}
|
||||
})),
|
||||
TServiceParams: jest.fn()
|
||||
TServiceParams: mock()
|
||||
}));
|
||||
|
||||
jest.unstable_mockModule('@digital-alchemy/hass', () => ({
|
||||
@@ -78,7 +79,7 @@ describe('Home Assistant Connection', () => {
|
||||
process.env = originalEnv;
|
||||
});
|
||||
|
||||
it('should return a Home Assistant instance with services', async () => {
|
||||
test('should return a Home Assistant instance with services', async () => {
|
||||
const { get_hass } = await import('../../src/hass/index.js');
|
||||
const hass = await get_hass();
|
||||
|
||||
@@ -89,7 +90,7 @@ describe('Home Assistant Connection', () => {
|
||||
expect(typeof hass.services.climate.set_temperature).toBe('function');
|
||||
});
|
||||
|
||||
it('should reuse the same instance on subsequent calls', async () => {
|
||||
test('should reuse the same instance on subsequent calls', async () => {
|
||||
const { get_hass } = await import('../../src/hass/index.js');
|
||||
const firstInstance = await get_hass();
|
||||
const secondInstance = await get_hass();
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { jest, describe, beforeEach, afterEach, it, expect } from '@jest/globals';
|
||||
import { WebSocket } from 'ws';
|
||||
import { EventEmitter } from 'events';
|
||||
@@ -44,19 +45,19 @@ const mockWebSocket: WebSocketMock = {
|
||||
close: jest.fn<WebSocketCloseHandler>(),
|
||||
readyState: 1,
|
||||
OPEN: 1,
|
||||
removeAllListeners: jest.fn()
|
||||
removeAllListeners: mock()
|
||||
};
|
||||
|
||||
jest.mock('ws', () => ({
|
||||
WebSocket: jest.fn().mockImplementation(() => mockWebSocket)
|
||||
// // jest.mock('ws', () => ({
|
||||
WebSocket: mock().mockImplementation(() => mockWebSocket)
|
||||
}));
|
||||
|
||||
// Mock fetch globally
|
||||
const mockFetch = jest.fn() as jest.MockedFunction<typeof fetch>;
|
||||
const mockFetch = mock() as jest.MockedFunction<typeof fetch>;
|
||||
global.fetch = mockFetch;
|
||||
|
||||
// Mock get_hass
|
||||
jest.mock('../../src/hass/index.js', () => {
|
||||
// // jest.mock('../../src/hass/index.js', () => {
|
||||
let instance: TestHassInstance | null = null;
|
||||
const actual = jest.requireActual<typeof import('../../src/hass/index.js')>('../../src/hass/index.js');
|
||||
return {
|
||||
@@ -85,12 +86,12 @@ describe('Home Assistant Integration', () => {
|
||||
jest.clearAllMocks();
|
||||
});
|
||||
|
||||
it('should create a WebSocket client with the provided URL and token', () => {
|
||||
test('should create a WebSocket client with the provided URL and token', () => {
|
||||
expect(client).toBeInstanceOf(EventEmitter);
|
||||
expect(jest.mocked(WebSocket)).toHaveBeenCalledWith(mockUrl);
|
||||
expect(// // jest.mocked(WebSocket)).toHaveBeenCalledWith(mockUrl);
|
||||
});
|
||||
|
||||
it('should connect and authenticate successfully', async () => {
|
||||
test('should connect and authenticate successfully', async () => {
|
||||
const connectPromise = client.connect();
|
||||
|
||||
// Get and call the open callback
|
||||
@@ -114,7 +115,7 @@ describe('Home Assistant Integration', () => {
|
||||
await connectPromise;
|
||||
});
|
||||
|
||||
it('should handle authentication failure', async () => {
|
||||
test('should handle authentication failure', async () => {
|
||||
const connectPromise = client.connect();
|
||||
|
||||
// Get and call the open callback
|
||||
@@ -130,7 +131,7 @@ describe('Home Assistant Integration', () => {
|
||||
await expect(connectPromise).rejects.toThrow();
|
||||
});
|
||||
|
||||
it('should handle connection errors', async () => {
|
||||
test('should handle connection errors', async () => {
|
||||
const connectPromise = client.connect();
|
||||
|
||||
// Get and call the error callback
|
||||
@@ -141,7 +142,7 @@ describe('Home Assistant Integration', () => {
|
||||
await expect(connectPromise).rejects.toThrow('Connection failed');
|
||||
});
|
||||
|
||||
it('should handle message parsing errors', async () => {
|
||||
test('should handle message parsing errors', async () => {
|
||||
const connectPromise = client.connect();
|
||||
|
||||
// Get and call the open callback
|
||||
@@ -198,12 +199,12 @@ describe('Home Assistant Integration', () => {
|
||||
});
|
||||
});
|
||||
|
||||
it('should create instance with correct properties', () => {
|
||||
test('should create instance with correct properties', () => {
|
||||
expect(instance['baseUrl']).toBe(mockBaseUrl);
|
||||
expect(instance['token']).toBe(mockToken);
|
||||
});
|
||||
|
||||
it('should fetch states', async () => {
|
||||
test('should fetch states', async () => {
|
||||
const states = await instance.fetchStates();
|
||||
expect(states).toEqual([mockState]);
|
||||
expect(mockFetch).toHaveBeenCalledWith(
|
||||
@@ -216,7 +217,7 @@ describe('Home Assistant Integration', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('should fetch single state', async () => {
|
||||
test('should fetch single state', async () => {
|
||||
const state = await instance.fetchState('light.test');
|
||||
expect(state).toEqual(mockState);
|
||||
expect(mockFetch).toHaveBeenCalledWith(
|
||||
@@ -229,7 +230,7 @@ describe('Home Assistant Integration', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('should call service', async () => {
|
||||
test('should call service', async () => {
|
||||
await instance.callService('light', 'turn_on', { entity_id: 'light.test' });
|
||||
expect(mockFetch).toHaveBeenCalledWith(
|
||||
`${mockBaseUrl}/api/services/light/turn_on`,
|
||||
@@ -244,17 +245,17 @@ describe('Home Assistant Integration', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle fetch errors', async () => {
|
||||
test('should handle fetch errors', async () => {
|
||||
mockFetch.mockRejectedValueOnce(new Error('Network error'));
|
||||
await expect(instance.fetchStates()).rejects.toThrow('Network error');
|
||||
});
|
||||
|
||||
it('should handle invalid JSON responses', async () => {
|
||||
test('should handle invalid JSON responses', async () => {
|
||||
mockFetch.mockResolvedValueOnce(new Response('invalid json'));
|
||||
await expect(instance.fetchStates()).rejects.toThrow();
|
||||
});
|
||||
|
||||
it('should handle non-200 responses', async () => {
|
||||
test('should handle non-200 responses', async () => {
|
||||
mockFetch.mockResolvedValueOnce(new Response('Error', { status: 500 }));
|
||||
await expect(instance.fetchStates()).rejects.toThrow();
|
||||
});
|
||||
@@ -263,15 +264,15 @@ describe('Home Assistant Integration', () => {
|
||||
let eventCallback: (event: HassEvent) => void;
|
||||
|
||||
beforeEach(() => {
|
||||
eventCallback = jest.fn();
|
||||
eventCallback = mock();
|
||||
});
|
||||
|
||||
it('should subscribe to events', async () => {
|
||||
test('should subscribe to events', async () => {
|
||||
const subscriptionId = await instance.subscribeEvents(eventCallback);
|
||||
expect(typeof subscriptionId).toBe('number');
|
||||
});
|
||||
|
||||
it('should unsubscribe from events', async () => {
|
||||
test('should unsubscribe from events', async () => {
|
||||
const subscriptionId = await instance.subscribeEvents(eventCallback);
|
||||
await instance.unsubscribeEvents(subscriptionId);
|
||||
});
|
||||
@@ -309,19 +310,19 @@ describe('Home Assistant Integration', () => {
|
||||
process.env = originalEnv;
|
||||
});
|
||||
|
||||
it('should create instance with default configuration', async () => {
|
||||
test('should create instance with default configuration', async () => {
|
||||
const instance = await get_hass() as TestHassInstance;
|
||||
expect(instance._baseUrl).toBe('http://localhost:8123');
|
||||
expect(instance._token).toBe('test_token');
|
||||
});
|
||||
|
||||
it('should reuse existing instance', async () => {
|
||||
test('should reuse existing instance', async () => {
|
||||
const instance1 = await get_hass();
|
||||
const instance2 = await get_hass();
|
||||
expect(instance1).toBe(instance2);
|
||||
});
|
||||
|
||||
it('should use custom configuration', async () => {
|
||||
test('should use custom configuration', async () => {
|
||||
process.env.HASS_HOST = 'https://hass.example.com';
|
||||
process.env.HASS_TOKEN = 'prod_token';
|
||||
const instance = await get_hass() as TestHassInstance;
|
||||
|
||||
@@ -1,15 +1,10 @@
|
||||
import { jest, describe, it, expect } from '@jest/globals';
|
||||
|
||||
// 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 }],
|
||||
};
|
||||
};
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { formatToolCall } from "../src/utils/helpers";
|
||||
|
||||
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 +17,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 +30,7 @@ describe('helpers', () => {
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle empty objects', () => {
|
||||
test('should handle empty objects', () => {
|
||||
const testObj = {};
|
||||
const result = formatToolCall(testObj);
|
||||
|
||||
@@ -47,5 +42,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
|
||||
}]
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import {
|
||||
MediaPlayerSchema,
|
||||
FanSchema,
|
||||
@@ -17,7 +18,7 @@ import {
|
||||
|
||||
describe('Device Schemas', () => {
|
||||
describe('Media Player Schema', () => {
|
||||
it('should validate a valid media player entity', () => {
|
||||
test('should validate a valid media player entity', () => {
|
||||
const mediaPlayer = {
|
||||
entity_id: 'media_player.living_room',
|
||||
state: 'playing',
|
||||
@@ -35,7 +36,7 @@ describe('Device Schemas', () => {
|
||||
expect(() => MediaPlayerSchema.parse(mediaPlayer)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should validate media player list response', () => {
|
||||
test('should validate media player list response', () => {
|
||||
const response = {
|
||||
media_players: [{
|
||||
entity_id: 'media_player.living_room',
|
||||
@@ -48,7 +49,7 @@ describe('Device Schemas', () => {
|
||||
});
|
||||
|
||||
describe('Fan Schema', () => {
|
||||
it('should validate a valid fan entity', () => {
|
||||
test('should validate a valid fan entity', () => {
|
||||
const fan = {
|
||||
entity_id: 'fan.bedroom',
|
||||
state: 'on',
|
||||
@@ -64,7 +65,7 @@ describe('Device Schemas', () => {
|
||||
expect(() => FanSchema.parse(fan)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should validate fan list response', () => {
|
||||
test('should validate fan list response', () => {
|
||||
const response = {
|
||||
fans: [{
|
||||
entity_id: 'fan.bedroom',
|
||||
@@ -77,7 +78,7 @@ describe('Device Schemas', () => {
|
||||
});
|
||||
|
||||
describe('Lock Schema', () => {
|
||||
it('should validate a valid lock entity', () => {
|
||||
test('should validate a valid lock entity', () => {
|
||||
const lock = {
|
||||
entity_id: 'lock.front_door',
|
||||
state: 'locked',
|
||||
@@ -91,7 +92,7 @@ describe('Device Schemas', () => {
|
||||
expect(() => LockSchema.parse(lock)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should validate lock list response', () => {
|
||||
test('should validate lock list response', () => {
|
||||
const response = {
|
||||
locks: [{
|
||||
entity_id: 'lock.front_door',
|
||||
@@ -104,7 +105,7 @@ describe('Device Schemas', () => {
|
||||
});
|
||||
|
||||
describe('Vacuum Schema', () => {
|
||||
it('should validate a valid vacuum entity', () => {
|
||||
test('should validate a valid vacuum entity', () => {
|
||||
const vacuum = {
|
||||
entity_id: 'vacuum.robot',
|
||||
state: 'cleaning',
|
||||
@@ -119,7 +120,7 @@ describe('Device Schemas', () => {
|
||||
expect(() => VacuumSchema.parse(vacuum)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should validate vacuum list response', () => {
|
||||
test('should validate vacuum list response', () => {
|
||||
const response = {
|
||||
vacuums: [{
|
||||
entity_id: 'vacuum.robot',
|
||||
@@ -132,7 +133,7 @@ describe('Device Schemas', () => {
|
||||
});
|
||||
|
||||
describe('Scene Schema', () => {
|
||||
it('should validate a valid scene entity', () => {
|
||||
test('should validate a valid scene entity', () => {
|
||||
const scene = {
|
||||
entity_id: 'scene.movie_night',
|
||||
state: 'on',
|
||||
@@ -144,7 +145,7 @@ describe('Device Schemas', () => {
|
||||
expect(() => SceneSchema.parse(scene)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should validate scene list response', () => {
|
||||
test('should validate scene list response', () => {
|
||||
const response = {
|
||||
scenes: [{
|
||||
entity_id: 'scene.movie_night',
|
||||
@@ -157,7 +158,7 @@ describe('Device Schemas', () => {
|
||||
});
|
||||
|
||||
describe('Script Schema', () => {
|
||||
it('should validate a valid script entity', () => {
|
||||
test('should validate a valid script entity', () => {
|
||||
const script = {
|
||||
entity_id: 'script.welcome_home',
|
||||
state: 'on',
|
||||
@@ -174,7 +175,7 @@ describe('Device Schemas', () => {
|
||||
expect(() => ScriptSchema.parse(script)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should validate script list response', () => {
|
||||
test('should validate script list response', () => {
|
||||
const response = {
|
||||
scripts: [{
|
||||
entity_id: 'script.welcome_home',
|
||||
@@ -187,7 +188,7 @@ describe('Device Schemas', () => {
|
||||
});
|
||||
|
||||
describe('Camera Schema', () => {
|
||||
it('should validate a valid camera entity', () => {
|
||||
test('should validate a valid camera entity', () => {
|
||||
const camera = {
|
||||
entity_id: 'camera.front_door',
|
||||
state: 'recording',
|
||||
@@ -200,7 +201,7 @@ describe('Device Schemas', () => {
|
||||
expect(() => CameraSchema.parse(camera)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should validate camera list response', () => {
|
||||
test('should validate camera list response', () => {
|
||||
const response = {
|
||||
cameras: [{
|
||||
entity_id: 'camera.front_door',
|
||||
|
||||
@@ -1,14 +1,17 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { entitySchema, serviceSchema, stateChangedEventSchema, configSchema, automationSchema, deviceControlSchema } from '../../src/schemas/hass.js';
|
||||
import AjvModule from 'ajv';
|
||||
const Ajv = AjvModule.default || AjvModule;
|
||||
import Ajv from 'ajv';
|
||||
import { describe, expect, test } from "bun:test";
|
||||
|
||||
const ajv = new Ajv();
|
||||
|
||||
// Create validation functions for each schema
|
||||
const validateEntity = ajv.compile(entitySchema);
|
||||
const validateService = ajv.compile(serviceSchema);
|
||||
|
||||
describe('Home Assistant Schemas', () => {
|
||||
const ajv = new Ajv({ allErrors: true });
|
||||
|
||||
describe('Entity Schema', () => {
|
||||
const validate = ajv.compile(entitySchema);
|
||||
|
||||
it('should validate a valid entity', () => {
|
||||
test('should validate a valid entity', () => {
|
||||
const validEntity = {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'on',
|
||||
@@ -24,28 +27,26 @@ describe('Home Assistant Schemas', () => {
|
||||
user_id: null
|
||||
}
|
||||
};
|
||||
expect(validate(validEntity)).toBe(true);
|
||||
expect(validateEntity(validEntity)).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject entity with missing required fields', () => {
|
||||
test('should reject entity with missing required fields', () => {
|
||||
const invalidEntity = {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'on'
|
||||
// missing attributes, last_changed, last_updated, context
|
||||
};
|
||||
expect(validate(invalidEntity)).toBe(false);
|
||||
expect(validate.errors).toBeDefined();
|
||||
expect(validateEntity(invalidEntity)).toBe(false);
|
||||
expect(validateEntity.errors).toBeDefined();
|
||||
});
|
||||
|
||||
it('should validate entity with additional attributes', () => {
|
||||
const entityWithExtraAttrs = {
|
||||
entity_id: 'climate.living_room',
|
||||
state: '22',
|
||||
test('should validate entity with additional attributes', () => {
|
||||
const validEntity = {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'on',
|
||||
attributes: {
|
||||
temperature: 22,
|
||||
humidity: 45,
|
||||
mode: 'auto',
|
||||
custom_attr: 'value'
|
||||
brightness: 100,
|
||||
color_mode: 'brightness'
|
||||
},
|
||||
last_changed: '2024-01-01T00:00:00Z',
|
||||
last_updated: '2024-01-01T00:00:00Z',
|
||||
@@ -55,12 +56,12 @@ describe('Home Assistant Schemas', () => {
|
||||
user_id: null
|
||||
}
|
||||
};
|
||||
expect(validate(entityWithExtraAttrs)).toBe(true);
|
||||
expect(validateEntity(validEntity)).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject invalid entity_id format', () => {
|
||||
const invalidEntityId = {
|
||||
entity_id: 'invalid_format',
|
||||
test('should reject invalid entity_id format', () => {
|
||||
const invalidEntity = {
|
||||
entity_id: 'invalid_entity',
|
||||
state: 'on',
|
||||
attributes: {},
|
||||
last_changed: '2024-01-01T00:00:00Z',
|
||||
@@ -71,25 +72,26 @@ describe('Home Assistant Schemas', () => {
|
||||
user_id: null
|
||||
}
|
||||
};
|
||||
expect(validate(invalidEntityId)).toBe(false);
|
||||
expect(validateEntity(invalidEntity)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('Service Schema', () => {
|
||||
const validate = ajv.compile(serviceSchema);
|
||||
|
||||
it('should validate a basic service call', () => {
|
||||
test('should validate a basic service call', () => {
|
||||
const basicService = {
|
||||
domain: 'light',
|
||||
service: 'turn_on',
|
||||
target: {
|
||||
entity_id: ['light.living_room']
|
||||
},
|
||||
service_data: {
|
||||
brightness_pct: 100
|
||||
}
|
||||
};
|
||||
expect(validate(basicService)).toBe(true);
|
||||
expect(validateService(basicService)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate service call with multiple targets', () => {
|
||||
test('should validate service call with multiple targets', () => {
|
||||
const multiTargetService = {
|
||||
domain: 'light',
|
||||
service: 'turn_on',
|
||||
@@ -102,18 +104,18 @@ describe('Home Assistant Schemas', () => {
|
||||
brightness_pct: 100
|
||||
}
|
||||
};
|
||||
expect(validate(multiTargetService)).toBe(true);
|
||||
expect(validateService(multiTargetService)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate service call without targets', () => {
|
||||
test('should validate service call without targets', () => {
|
||||
const noTargetService = {
|
||||
domain: 'homeassistant',
|
||||
service: 'restart'
|
||||
};
|
||||
expect(validate(noTargetService)).toBe(true);
|
||||
expect(validateService(noTargetService)).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject service call with invalid target type', () => {
|
||||
test('should reject service call with invalid target type', () => {
|
||||
const invalidService = {
|
||||
domain: 'light',
|
||||
service: 'turn_on',
|
||||
@@ -121,15 +123,26 @@ describe('Home Assistant Schemas', () => {
|
||||
entity_id: 'not_an_array' // should be an array
|
||||
}
|
||||
};
|
||||
expect(validate(invalidService)).toBe(false);
|
||||
expect(validate.errors).toBeDefined();
|
||||
expect(validateService(invalidService)).toBe(false);
|
||||
expect(validateService.errors).toBeDefined();
|
||||
});
|
||||
|
||||
test('should reject service call with invalid domain', () => {
|
||||
const invalidService = {
|
||||
domain: 'invalid_domain',
|
||||
service: 'turn_on',
|
||||
target: {
|
||||
entity_id: ['light.living_room']
|
||||
}
|
||||
};
|
||||
expect(validateService(invalidService)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('State Changed Event Schema', () => {
|
||||
const validate = ajv.compile(stateChangedEventSchema);
|
||||
|
||||
it('should validate a valid state changed event', () => {
|
||||
test('should validate a valid state changed event', () => {
|
||||
const validEvent = {
|
||||
event_type: 'state_changed',
|
||||
data: {
|
||||
@@ -172,7 +185,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(validEvent)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate event with null old_state', () => {
|
||||
test('should validate event with null old_state', () => {
|
||||
const newEntityEvent = {
|
||||
event_type: 'state_changed',
|
||||
data: {
|
||||
@@ -202,7 +215,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(newEntityEvent)).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject event with invalid event_type', () => {
|
||||
test('should reject event with invalid event_type', () => {
|
||||
const invalidEvent = {
|
||||
event_type: 'wrong_type',
|
||||
data: {
|
||||
@@ -226,7 +239,7 @@ describe('Home Assistant Schemas', () => {
|
||||
describe('Config Schema', () => {
|
||||
const validate = ajv.compile(configSchema);
|
||||
|
||||
it('should validate a minimal config', () => {
|
||||
test('should validate a minimal config', () => {
|
||||
const minimalConfig = {
|
||||
latitude: 52.3731,
|
||||
longitude: 4.8922,
|
||||
@@ -245,7 +258,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(minimalConfig)).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject config with missing required fields', () => {
|
||||
test('should reject config with missing required fields', () => {
|
||||
const invalidConfig = {
|
||||
latitude: 52.3731,
|
||||
longitude: 4.8922
|
||||
@@ -255,7 +268,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate.errors).toBeDefined();
|
||||
});
|
||||
|
||||
it('should reject config with invalid types', () => {
|
||||
test('should reject config with invalid types', () => {
|
||||
const invalidConfig = {
|
||||
latitude: '52.3731', // should be number
|
||||
longitude: 4.8922,
|
||||
@@ -279,7 +292,7 @@ describe('Home Assistant Schemas', () => {
|
||||
describe('Automation Schema', () => {
|
||||
const validate = ajv.compile(automationSchema);
|
||||
|
||||
it('should validate a basic automation', () => {
|
||||
test('should validate a basic automation', () => {
|
||||
const basicAutomation = {
|
||||
alias: 'Turn on lights at sunset',
|
||||
description: 'Automatically turn on lights when the sun sets',
|
||||
@@ -301,7 +314,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(basicAutomation)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate automation with conditions', () => {
|
||||
test('should validate automation with conditions', () => {
|
||||
const automationWithConditions = {
|
||||
alias: 'Conditional Light Control',
|
||||
mode: 'single',
|
||||
@@ -335,7 +348,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(automationWithConditions)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate automation with multiple triggers and actions', () => {
|
||||
test('should validate automation with multiple triggers and actions', () => {
|
||||
const complexAutomation = {
|
||||
alias: 'Complex Automation',
|
||||
mode: 'parallel',
|
||||
@@ -380,7 +393,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(complexAutomation)).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject automation without required fields', () => {
|
||||
test('should reject automation without required fields', () => {
|
||||
const invalidAutomation = {
|
||||
description: 'Missing required fields'
|
||||
// missing alias, trigger, and action
|
||||
@@ -389,7 +402,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate.errors).toBeDefined();
|
||||
});
|
||||
|
||||
it('should validate all automation modes', () => {
|
||||
test('should validate all automation modes', () => {
|
||||
const modes = ['single', 'parallel', 'queued', 'restart'];
|
||||
modes.forEach(mode => {
|
||||
const automation = {
|
||||
@@ -415,7 +428,7 @@ describe('Home Assistant Schemas', () => {
|
||||
describe('Device Control Schema', () => {
|
||||
const validate = ajv.compile(deviceControlSchema);
|
||||
|
||||
it('should validate light control command', () => {
|
||||
test('should validate light control command', () => {
|
||||
const lightCommand = {
|
||||
domain: 'light',
|
||||
command: 'turn_on',
|
||||
@@ -429,7 +442,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(lightCommand)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate climate control command', () => {
|
||||
test('should validate climate control command', () => {
|
||||
const climateCommand = {
|
||||
domain: 'climate',
|
||||
command: 'set_temperature',
|
||||
@@ -444,7 +457,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(climateCommand)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate cover control command', () => {
|
||||
test('should validate cover control command', () => {
|
||||
const coverCommand = {
|
||||
domain: 'cover',
|
||||
command: 'set_position',
|
||||
@@ -457,7 +470,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(coverCommand)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate fan control command', () => {
|
||||
test('should validate fan control command', () => {
|
||||
const fanCommand = {
|
||||
domain: 'fan',
|
||||
command: 'set_speed',
|
||||
@@ -471,7 +484,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(fanCommand)).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject command with invalid domain', () => {
|
||||
test('should reject command with invalid domain', () => {
|
||||
const invalidCommand = {
|
||||
domain: 'invalid_domain',
|
||||
command: 'turn_on',
|
||||
@@ -481,7 +494,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate.errors).toBeDefined();
|
||||
});
|
||||
|
||||
it('should reject command with mismatched domain and entity_id', () => {
|
||||
test('should reject command with mismatched domain and entity_id', () => {
|
||||
const mismatchedCommand = {
|
||||
domain: 'light',
|
||||
command: 'turn_on',
|
||||
@@ -490,7 +503,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(mismatchedCommand)).toBe(false);
|
||||
});
|
||||
|
||||
it('should validate command with array of entity_ids', () => {
|
||||
test('should validate command with array of entity_ids', () => {
|
||||
const multiEntityCommand = {
|
||||
domain: 'light',
|
||||
command: 'turn_on',
|
||||
@@ -502,7 +515,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(multiEntityCommand)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate scene activation command', () => {
|
||||
test('should validate scene activation command', () => {
|
||||
const sceneCommand = {
|
||||
domain: 'scene',
|
||||
command: 'turn_on',
|
||||
@@ -514,7 +527,7 @@ describe('Home Assistant Schemas', () => {
|
||||
expect(validate(sceneCommand)).toBe(true);
|
||||
});
|
||||
|
||||
it('should validate script execution command', () => {
|
||||
test('should validate script execution command', () => {
|
||||
const scriptCommand = {
|
||||
domain: 'script',
|
||||
command: 'turn_on',
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { TokenManager, validateRequest, sanitizeInput, errorHandler, rateLimiter, securityHeaders } from '../../src/security/index.js';
|
||||
import { mock, describe, it, expect, beforeEach, afterEach } from 'bun:test';
|
||||
import jwt from 'jsonwebtoken';
|
||||
@@ -17,7 +18,7 @@ describe('Security Module', () => {
|
||||
const testToken = 'test-token';
|
||||
const encryptionKey = 'test-encryption-key-that-is-long-enough';
|
||||
|
||||
it('should encrypt and decrypt tokens', () => {
|
||||
test('should encrypt and decrypt tokens', () => {
|
||||
const encrypted = TokenManager.encryptToken(testToken, encryptionKey);
|
||||
expect(encrypted).toContain('aes-256-gcm:');
|
||||
|
||||
@@ -25,20 +26,20 @@ describe('Security Module', () => {
|
||||
expect(decrypted).toBe(testToken);
|
||||
});
|
||||
|
||||
it('should validate tokens correctly', () => {
|
||||
test('should validate tokens correctly', () => {
|
||||
const validToken = jwt.sign({ data: 'test' }, TEST_SECRET, { expiresIn: '1h' });
|
||||
const result = TokenManager.validateToken(validToken);
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.error).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should handle empty tokens', () => {
|
||||
test('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', () => {
|
||||
test('should handle expired tokens', () => {
|
||||
const now = Math.floor(Date.now() / 1000);
|
||||
const payload = {
|
||||
data: 'test',
|
||||
@@ -51,13 +52,13 @@ describe('Security Module', () => {
|
||||
expect(result.error).toBe('Token has expired');
|
||||
});
|
||||
|
||||
it('should handle invalid token format', () => {
|
||||
test('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', () => {
|
||||
test('should handle missing JWT secret', () => {
|
||||
delete process.env.JWT_SECRET;
|
||||
const payload = { data: 'test' };
|
||||
const token = jwt.sign(payload, 'some-secret');
|
||||
@@ -66,7 +67,7 @@ describe('Security Module', () => {
|
||||
expect(result.error).toBe('JWT secret not configured');
|
||||
});
|
||||
|
||||
it('should handle rate limiting for failed attempts', () => {
|
||||
test('should handle rate limiting for failed attempts', () => {
|
||||
const invalidToken = 'x'.repeat(64);
|
||||
const testIp = '127.0.0.1';
|
||||
|
||||
@@ -111,7 +112,7 @@ describe('Security Module', () => {
|
||||
mockNext = mock(() => { });
|
||||
});
|
||||
|
||||
it('should pass valid requests', () => {
|
||||
test('should pass valid requests', () => {
|
||||
if (mockRequest.headers) {
|
||||
mockRequest.headers.authorization = 'Bearer valid-token';
|
||||
}
|
||||
@@ -123,7 +124,7 @@ describe('Security Module', () => {
|
||||
expect(mockNext).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should reject invalid content type', () => {
|
||||
test('should reject invalid content type', () => {
|
||||
if (mockRequest.headers) {
|
||||
mockRequest.headers['content-type'] = 'text/plain';
|
||||
}
|
||||
@@ -139,7 +140,7 @@ describe('Security Module', () => {
|
||||
});
|
||||
});
|
||||
|
||||
it('should reject missing token', () => {
|
||||
test('should reject missing token', () => {
|
||||
if (mockRequest.headers) {
|
||||
delete mockRequest.headers.authorization;
|
||||
}
|
||||
@@ -155,7 +156,7 @@ describe('Security Module', () => {
|
||||
});
|
||||
});
|
||||
|
||||
it('should reject invalid request body', () => {
|
||||
test('should reject invalid request body', () => {
|
||||
mockRequest.body = null;
|
||||
|
||||
validateRequest(mockRequest, mockResponse, mockNext);
|
||||
@@ -197,7 +198,7 @@ describe('Security Module', () => {
|
||||
mockNext = mock(() => { });
|
||||
});
|
||||
|
||||
it('should sanitize HTML tags from request body', () => {
|
||||
test('should sanitize HTML tags from request body', () => {
|
||||
sanitizeInput(mockRequest, mockResponse, mockNext);
|
||||
|
||||
expect(mockRequest.body).toEqual({
|
||||
@@ -209,7 +210,7 @@ describe('Security Module', () => {
|
||||
expect(mockNext).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle non-object body', () => {
|
||||
test('should handle non-object body', () => {
|
||||
mockRequest.body = 'string body';
|
||||
sanitizeInput(mockRequest, mockResponse, mockNext);
|
||||
expect(mockNext).toHaveBeenCalled();
|
||||
@@ -235,7 +236,7 @@ describe('Security Module', () => {
|
||||
mockNext = mock(() => { });
|
||||
});
|
||||
|
||||
it('should handle errors in production mode', () => {
|
||||
test('should handle errors in production mode', () => {
|
||||
process.env.NODE_ENV = 'production';
|
||||
const error = new Error('Test error');
|
||||
errorHandler(error, mockRequest, mockResponse, mockNext);
|
||||
@@ -248,7 +249,7 @@ describe('Security Module', () => {
|
||||
});
|
||||
});
|
||||
|
||||
it('should include error message in development mode', () => {
|
||||
test('should include error message in development mode', () => {
|
||||
process.env.NODE_ENV = 'development';
|
||||
const error = new Error('Test error');
|
||||
errorHandler(error, mockRequest, mockResponse, mockNext);
|
||||
@@ -265,7 +266,7 @@ describe('Security Module', () => {
|
||||
});
|
||||
|
||||
describe('Rate Limiter', () => {
|
||||
it('should limit requests after threshold', async () => {
|
||||
test('should limit requests after threshold', async () => {
|
||||
const mockContext = {
|
||||
request: new Request('http://localhost', {
|
||||
headers: new Headers({
|
||||
@@ -292,7 +293,7 @@ describe('Security Module', () => {
|
||||
});
|
||||
|
||||
describe('Security Headers', () => {
|
||||
it('should set security headers', async () => {
|
||||
test('should set security headers', async () => {
|
||||
const mockHeaders = new Headers();
|
||||
const mockContext = {
|
||||
request: new Request('http://localhost', {
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { describe, it, expect } from 'bun:test';
|
||||
import {
|
||||
checkRateLimit,
|
||||
@@ -9,31 +10,31 @@ import {
|
||||
|
||||
describe('Security Middleware Utilities', () => {
|
||||
describe('Rate Limiter', () => {
|
||||
it('should allow requests under threshold', () => {
|
||||
test('should allow requests under threshold', () => {
|
||||
const ip = '127.0.0.1';
|
||||
expect(() => checkRateLimit(ip, 10)).not.toThrow();
|
||||
expect(() => checkRateLimtest(ip, 10)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should throw when requests exceed threshold', () => {
|
||||
test('should throw when requests exceed threshold', () => {
|
||||
const ip = '127.0.0.2';
|
||||
|
||||
// Simulate multiple requests
|
||||
for (let i = 0; i < 11; i++) {
|
||||
if (i < 10) {
|
||||
expect(() => checkRateLimit(ip, 10)).not.toThrow();
|
||||
expect(() => checkRateLimtest(ip, 10)).not.toThrow();
|
||||
} else {
|
||||
expect(() => checkRateLimit(ip, 10)).toThrow('Too many requests from this IP, please try again later');
|
||||
expect(() => checkRateLimtest(ip, 10)).toThrow('Too many requests from this IP, please try again later');
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('should reset rate limit after window expires', async () => {
|
||||
test('should reset rate limit after window expires', async () => {
|
||||
const ip = '127.0.0.3';
|
||||
|
||||
// Simulate multiple requests
|
||||
for (let i = 0; i < 11; i++) {
|
||||
if (i < 10) {
|
||||
expect(() => checkRateLimit(ip, 10, 50)).not.toThrow();
|
||||
expect(() => checkRateLimtest(ip, 10, 50)).not.toThrow();
|
||||
}
|
||||
}
|
||||
|
||||
@@ -41,12 +42,12 @@ describe('Security Middleware Utilities', () => {
|
||||
await new Promise(resolve => setTimeout(resolve, 100));
|
||||
|
||||
// Should be able to make requests again
|
||||
expect(() => checkRateLimit(ip, 10, 50)).not.toThrow();
|
||||
expect(() => checkRateLimtest(ip, 10, 50)).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Request Validation', () => {
|
||||
it('should validate content type', () => {
|
||||
test('should validate content type', () => {
|
||||
const mockRequest = new Request('http://localhost', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
@@ -57,7 +58,7 @@ describe('Security Middleware Utilities', () => {
|
||||
expect(() => validateRequestHeaders(mockRequest)).not.toThrow();
|
||||
});
|
||||
|
||||
it('should reject invalid content type', () => {
|
||||
test('should reject invalid content type', () => {
|
||||
const mockRequest = new Request('http://localhost', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
@@ -68,7 +69,7 @@ describe('Security Middleware Utilities', () => {
|
||||
expect(() => validateRequestHeaders(mockRequest)).toThrow('Content-Type must be application/json');
|
||||
});
|
||||
|
||||
it('should reject large request bodies', () => {
|
||||
test('should reject large request bodies', () => {
|
||||
const mockRequest = new Request('http://localhost', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
@@ -82,13 +83,13 @@ describe('Security Middleware Utilities', () => {
|
||||
});
|
||||
|
||||
describe('Input Sanitization', () => {
|
||||
it('should sanitize HTML tags', () => {
|
||||
test('should sanitize HTML tags', () => {
|
||||
const input = '<script>alert("xss")</script>Hello';
|
||||
const sanitized = sanitizeValue(input);
|
||||
expect(sanitized).toBe('<script>alert("xss")</script>Hello');
|
||||
});
|
||||
|
||||
it('should sanitize nested objects', () => {
|
||||
test('should sanitize nested objects', () => {
|
||||
const input = {
|
||||
text: '<script>alert("xss")</script>Hello',
|
||||
nested: {
|
||||
@@ -104,7 +105,7 @@ describe('Security Middleware Utilities', () => {
|
||||
});
|
||||
});
|
||||
|
||||
it('should preserve non-string values', () => {
|
||||
test('should preserve non-string values', () => {
|
||||
const input = {
|
||||
number: 123,
|
||||
boolean: true,
|
||||
@@ -116,7 +117,7 @@ describe('Security Middleware Utilities', () => {
|
||||
});
|
||||
|
||||
describe('Security Headers', () => {
|
||||
it('should apply security headers', () => {
|
||||
test('should apply security headers', () => {
|
||||
const mockRequest = new Request('http://localhost');
|
||||
const headers = applySecurityHeaders(mockRequest);
|
||||
|
||||
@@ -129,7 +130,7 @@ describe('Security Middleware Utilities', () => {
|
||||
});
|
||||
|
||||
describe('Error Handling', () => {
|
||||
it('should handle errors in production mode', () => {
|
||||
test('should handle errors in production mode', () => {
|
||||
const error = new Error('Test error');
|
||||
const result = handleError(error, 'production');
|
||||
|
||||
@@ -140,7 +141,7 @@ describe('Security Middleware Utilities', () => {
|
||||
});
|
||||
});
|
||||
|
||||
it('should include error details in development mode', () => {
|
||||
test('should include error details in development mode', () => {
|
||||
const error = new Error('Test error');
|
||||
const result = handleError(error, 'development');
|
||||
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { TokenManager } from '../../src/security/index.js';
|
||||
import jwt from 'jsonwebtoken';
|
||||
|
||||
@@ -16,36 +17,36 @@ describe('TokenManager', () => {
|
||||
const validToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNjE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
|
||||
|
||||
describe('Token Encryption/Decryption', () => {
|
||||
it('should encrypt and decrypt tokens successfully', () => {
|
||||
test('should encrypt and decrypt tokens successfully', () => {
|
||||
const encrypted = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
const decrypted = TokenManager.decryptToken(encrypted, encryptionKey);
|
||||
expect(decrypted).toBe(validToken);
|
||||
});
|
||||
|
||||
it('should generate different encrypted values for same token', () => {
|
||||
test('should generate different encrypted values for same token', () => {
|
||||
const encrypted1 = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
const encrypted2 = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
expect(encrypted1).not.toBe(encrypted2);
|
||||
});
|
||||
|
||||
it('should handle empty tokens', () => {
|
||||
test('should handle empty tokens', () => {
|
||||
expect(() => TokenManager.encryptToken('', encryptionKey)).toThrow('Invalid token');
|
||||
expect(() => TokenManager.decryptToken('', encryptionKey)).toThrow('Invalid encrypted token');
|
||||
});
|
||||
|
||||
it('should handle empty encryption keys', () => {
|
||||
test('should handle empty encryption keys', () => {
|
||||
expect(() => TokenManager.encryptToken(validToken, '')).toThrow('Invalid encryption key');
|
||||
expect(() => TokenManager.decryptToken(validToken, '')).toThrow('Invalid encryption key');
|
||||
});
|
||||
|
||||
it('should fail decryption with wrong key', () => {
|
||||
test('should fail decryption with wrong key', () => {
|
||||
const encrypted = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
expect(() => TokenManager.decryptToken(encrypted, 'wrong-key-32-chars-long!!!!!!!!')).toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Token Validation', () => {
|
||||
it('should validate correct tokens', () => {
|
||||
test('should validate correct tokens', () => {
|
||||
const payload = { sub: '123', name: 'Test User', iat: Math.floor(Date.now() / 1000), exp: Math.floor(Date.now() / 1000) + 3600 };
|
||||
const token = jwt.sign(payload, TEST_SECRET);
|
||||
const result = TokenManager.validateToken(token);
|
||||
@@ -53,7 +54,7 @@ describe('TokenManager', () => {
|
||||
expect(result.error).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should reject expired tokens', () => {
|
||||
test('should reject expired tokens', () => {
|
||||
const payload = { sub: '123', name: 'Test User', iat: Math.floor(Date.now() / 1000) - 7200, exp: Math.floor(Date.now() / 1000) - 3600 };
|
||||
const token = jwt.sign(payload, TEST_SECRET);
|
||||
const result = TokenManager.validateToken(token);
|
||||
@@ -61,13 +62,13 @@ describe('TokenManager', () => {
|
||||
expect(result.error).toBe('Token has expired');
|
||||
});
|
||||
|
||||
it('should reject malformed tokens', () => {
|
||||
test('should reject malformed tokens', () => {
|
||||
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', () => {
|
||||
test('should reject tokens with invalid signature', () => {
|
||||
const payload = { sub: '123', name: 'Test User', iat: Math.floor(Date.now() / 1000), exp: Math.floor(Date.now() / 1000) + 3600 };
|
||||
const token = jwt.sign(payload, 'different-secret');
|
||||
const result = TokenManager.validateToken(token);
|
||||
@@ -75,7 +76,7 @@ describe('TokenManager', () => {
|
||||
expect(result.error).toBe('Invalid token signature');
|
||||
});
|
||||
|
||||
it('should handle tokens with missing expiration', () => {
|
||||
test('should handle tokens with missing expiration', () => {
|
||||
const payload = { sub: '123', name: 'Test User' };
|
||||
const token = jwt.sign(payload, TEST_SECRET);
|
||||
const result = TokenManager.validateToken(token);
|
||||
@@ -83,7 +84,7 @@ describe('TokenManager', () => {
|
||||
expect(result.error).toBe('Token missing required claims');
|
||||
});
|
||||
|
||||
it('should handle undefined and null inputs', () => {
|
||||
test('should handle undefined and null inputs', () => {
|
||||
const undefinedResult = TokenManager.validateToken(undefined);
|
||||
expect(undefinedResult.valid).toBe(false);
|
||||
expect(undefinedResult.error).toBe('Invalid token format');
|
||||
@@ -95,26 +96,26 @@ describe('TokenManager', () => {
|
||||
});
|
||||
|
||||
describe('Security Features', () => {
|
||||
it('should use secure encryption algorithm', () => {
|
||||
test('should use secure encryption algorithm', () => {
|
||||
const encrypted = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
expect(encrypted).toContain('aes-256-gcm');
|
||||
});
|
||||
|
||||
it('should prevent token tampering', () => {
|
||||
test('should prevent token tampering', () => {
|
||||
const encrypted = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
const tampered = encrypted.slice(0, -5) + 'xxxxx';
|
||||
expect(() => TokenManager.decryptToken(tampered, encryptionKey)).toThrow();
|
||||
});
|
||||
|
||||
it('should use unique IVs for each encryption', () => {
|
||||
test('should use unique IVs for each encryption', () => {
|
||||
const encrypted1 = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
const encrypted2 = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
const iv1 = encrypted1.split(':')[1];
|
||||
const iv2 = encrypted2.split(':')[1];
|
||||
const iv1 = encrypted1.spltest(':')[1];
|
||||
const iv2 = encrypted2.spltest(':')[1];
|
||||
expect(iv1).not.toBe(iv2);
|
||||
});
|
||||
|
||||
it('should handle large tokens', () => {
|
||||
test('should handle large tokens', () => {
|
||||
const largeToken = 'x'.repeat(10000);
|
||||
const encrypted = TokenManager.encryptToken(largeToken, encryptionKey);
|
||||
const decrypted = TokenManager.decryptToken(encrypted, encryptionKey);
|
||||
@@ -123,19 +124,19 @@ describe('TokenManager', () => {
|
||||
});
|
||||
|
||||
describe('Error Handling', () => {
|
||||
it('should throw descriptive errors for invalid inputs', () => {
|
||||
test('should throw descriptive errors for invalid inputs', () => {
|
||||
expect(() => TokenManager.encryptToken(null as any, encryptionKey)).toThrow('Invalid token');
|
||||
expect(() => TokenManager.encryptToken(validToken, null as any)).toThrow('Invalid encryption key');
|
||||
expect(() => TokenManager.decryptToken('invalid-base64', encryptionKey)).toThrow('Invalid encrypted token');
|
||||
});
|
||||
|
||||
it('should handle corrupted encrypted data', () => {
|
||||
test('should handle corrupted encrypted data', () => {
|
||||
const encrypted = TokenManager.encryptToken(validToken, encryptionKey);
|
||||
const corrupted = encrypted.replace(/[a-zA-Z]/g, 'x');
|
||||
expect(() => TokenManager.decryptToken(corrupted, encryptionKey)).toThrow();
|
||||
});
|
||||
|
||||
it('should handle invalid base64 input', () => {
|
||||
test('should handle invalid base64 input', () => {
|
||||
expect(() => TokenManager.decryptToken('not-base64!@#$%^', encryptionKey)).toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,61 +1,82 @@
|
||||
import { jest, describe, beforeEach, afterEach, it, expect } from '@jest/globals';
|
||||
import express from 'express';
|
||||
import { LiteMCP } from 'litemcp';
|
||||
import { logger } from '../src/utils/logger.js';
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
|
||||
import type { Mock } from "bun:test";
|
||||
import type { Express, Application } from 'express';
|
||||
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 = {
|
||||
use: jest.fn(),
|
||||
listen: jest.fn((port: number, callback: () => void) => {
|
||||
const mockApp: MockApp = {
|
||||
use: mock(() => undefined),
|
||||
listen: mock((port: number, callback: () => void) => {
|
||||
callback();
|
||||
return { close: jest.fn() };
|
||||
return { close: mock(() => undefined) };
|
||||
})
|
||||
};
|
||||
return jest.fn(() => mockApp);
|
||||
});
|
||||
const mockExpress = mock(() => mockApp);
|
||||
|
||||
// Mock LiteMCP
|
||||
jest.mock('litemcp', () => ({
|
||||
LiteMCP: jest.fn(() => ({
|
||||
addTool: jest.fn(),
|
||||
start: jest.fn().mockImplementation(async () => { })
|
||||
}))
|
||||
}));
|
||||
// Mock LiteMCP instance
|
||||
const mockLiteMCPInstance: MockLiteMCPInstance = {
|
||||
addTool: mock(() => undefined),
|
||||
start: mock(() => Promise.resolve())
|
||||
};
|
||||
const mockLiteMCP = mock((name: string, version: string) => mockLiteMCPInstance);
|
||||
|
||||
// Mock logger
|
||||
jest.mock('../src/utils/logger.js', () => ({
|
||||
logger: {
|
||||
info: jest.fn(),
|
||||
error: jest.fn(),
|
||||
debug: jest.fn()
|
||||
}
|
||||
}));
|
||||
const mockLogger: MockLogger = {
|
||||
info: mock((message: string) => undefined),
|
||||
error: mock((message: string) => undefined),
|
||||
debug: mock((message: string) => undefined)
|
||||
};
|
||||
|
||||
describe('Server Initialization', () => {
|
||||
let originalEnv: NodeJS.ProcessEnv;
|
||||
let mockApp: ReturnType<typeof express>;
|
||||
|
||||
beforeEach(() => {
|
||||
// Store original environment
|
||||
originalEnv = { ...process.env };
|
||||
|
||||
// Reset all mocks
|
||||
jest.clearAllMocks();
|
||||
// Setup mocks
|
||||
(globalThis as any).express = mockExpress;
|
||||
(globalThis as any).LiteMCP = mockLiteMCP;
|
||||
(globalThis as any).logger = mockLogger;
|
||||
|
||||
// Get the mock express app
|
||||
mockApp = express();
|
||||
// Reset all mocks
|
||||
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
|
||||
jest.resetModules();
|
||||
// Clean up mocks
|
||||
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 +84,15 @@ describe('Server Initialization', () => {
|
||||
await import('../src/index.js');
|
||||
|
||||
// Verify Express server was initialized
|
||||
expect(express).toHaveBeenCalled();
|
||||
expect(mockApp.use).toHaveBeenCalled();
|
||||
expect(mockApp.listen).toHaveBeenCalled();
|
||||
expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('Server is running on port'));
|
||||
expect(mockExpress.mock.calls.length).toBeGreaterThan(0);
|
||||
expect(mockApp.use.mock.calls.length).toBeGreaterThan(0);
|
||||
expect(mockApp.listen.mock.calls.length).toBeGreaterThan(0);
|
||||
|
||||
const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
|
||||
expect(infoMessages.some(msg => msg.includes('Server is running on port'))).toBe(true);
|
||||
});
|
||||
|
||||
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 +100,38 @@ describe('Server Initialization', () => {
|
||||
await import('../src/index.js');
|
||||
|
||||
// Verify Express server was not initialized
|
||||
expect(express).not.toHaveBeenCalled();
|
||||
expect(mockApp.use).not.toHaveBeenCalled();
|
||||
expect(mockApp.listen).not.toHaveBeenCalled();
|
||||
expect(logger.info).toHaveBeenCalledWith('Running in Claude mode - Express server disabled');
|
||||
expect(mockExpress.mock.calls.length).toBe(0);
|
||||
expect(mockApp.use.mock.calls.length).toBe(0);
|
||||
expect(mockApp.listen.mock.calls.length).toBe(0);
|
||||
|
||||
const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
|
||||
expect(infoMessages).toContain('Running in Claude mode - Express server disabled');
|
||||
});
|
||||
|
||||
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
|
||||
jest.resetModules();
|
||||
expect(mockLiteMCP.mock.calls.length).toBeGreaterThan(0);
|
||||
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 +139,11 @@ describe('Server Initialization', () => {
|
||||
await import('../src/index.js');
|
||||
|
||||
// Verify Express server was initialized (default behavior)
|
||||
expect(express).toHaveBeenCalled();
|
||||
expect(mockApp.use).toHaveBeenCalled();
|
||||
expect(mockApp.listen).toHaveBeenCalled();
|
||||
expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('Server is running on port'));
|
||||
expect(mockExpress.mock.calls.length).toBeGreaterThan(0);
|
||||
expect(mockApp.use.mock.calls.length).toBeGreaterThan(0);
|
||||
expect(mockApp.listen.mock.calls.length).toBeGreaterThan(0);
|
||||
|
||||
const infoMessages = mockLogger.info.mock.calls.map(([msg]) => msg);
|
||||
expect(infoMessages.some(msg => msg.includes('Server is running on port'))).toBe(true);
|
||||
});
|
||||
});
|
||||
328
__tests__/speech/speechToText.test.ts
Normal file
328
__tests__/speech/speechToText.test.ts
Normal file
@@ -0,0 +1,328 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { SpeechToText, TranscriptionResult, WakeWordEvent, TranscriptionError, TranscriptionOptions } from '../../src/speech/speechToText';
|
||||
import { EventEmitter } from 'events';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import { spawn } from 'child_process';
|
||||
import { describe, expect, beforeEach, afterEach, it, mock, spyOn } from 'bun:test';
|
||||
|
||||
// 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', () => {
|
||||
test('should create instance with default config', () => {
|
||||
const instance = new SpeechToText({ modelPath: '/models/whisper', modelType: 'base.en' });
|
||||
expect(instance instanceof EventEmitter).toBe(true);
|
||||
expect(instance instanceof SpeechToText).toBe(true);
|
||||
});
|
||||
|
||||
test('should initialize successfully', async () => {
|
||||
const initSpy = spyOn(speechToText, 'initialize');
|
||||
await speechToText.initialize();
|
||||
expect(initSpy).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
test('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', () => {
|
||||
test('should return true when Docker container is running', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emtest('data', Buffer.from('Up 2 hours'));
|
||||
}, 0);
|
||||
|
||||
const result = await speechToText.checkHealth();
|
||||
expect(result).toBe(true);
|
||||
});
|
||||
|
||||
test('should return false when Docker container is not running', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(1), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
const result = await speechToText.checkHealth();
|
||||
expect(result).toBe(false);
|
||||
});
|
||||
|
||||
test('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', () => {
|
||||
test('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');
|
||||
});
|
||||
});
|
||||
|
||||
test('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
|
||||
}]
|
||||
};
|
||||
|
||||
test('should transcribe audio successfully', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
const transcriptionPromise = speechToText.transcribeAudio('/test/audio.wav');
|
||||
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emtest('data', Buffer.from(JSON.stringify(mockTranscriptionResult)));
|
||||
}, 0);
|
||||
|
||||
const result = await transcriptionPromise;
|
||||
expect(result).toEqual(mockTranscriptionResult);
|
||||
});
|
||||
|
||||
test('should handle transcription errors', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(1), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
const transcriptionPromise = speechToText.transcribeAudio('/test/audio.wav');
|
||||
|
||||
setTimeout(() => {
|
||||
mockProcess.stderr.emtest('data', Buffer.from('Transcription failed'));
|
||||
}, 0);
|
||||
|
||||
await expect(transcriptionPromise).rejects.toThrow(TranscriptionError);
|
||||
});
|
||||
|
||||
test('should handle invalid JSON output', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
const transcriptionPromise = speechToText.transcribeAudio('/test/audio.wav');
|
||||
|
||||
setTimeout(() => {
|
||||
mockProcess.stdout.emtest('data', Buffer.from('Invalid JSON'));
|
||||
}, 0);
|
||||
|
||||
await expect(transcriptionPromise).rejects.toThrow(TranscriptionError);
|
||||
});
|
||||
|
||||
test('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', () => {
|
||||
test('should emit progress events', async () => {
|
||||
const mockProcess = {
|
||||
stdout: new EventEmitter(),
|
||||
stderr: new EventEmitter(),
|
||||
on: (event: string, cb: (code: number) => void) => {
|
||||
if (event === 'close') setTimeout(() => cb(0), 0);
|
||||
}
|
||||
};
|
||||
spawnMock.mockImplementation(() => mockProcess);
|
||||
|
||||
return new Promise<void>((resolve) => {
|
||||
const progressEvents: any[] = [];
|
||||
speechToText.on('progress', (event) => {
|
||||
progressEvents.push(event);
|
||||
if (progressEvents.length === 2) {
|
||||
expect(progressEvents).toEqual([
|
||||
{ type: 'stdout', data: 'Processing' },
|
||||
{ type: 'stderr', data: 'Loading model' }
|
||||
]);
|
||||
resolve();
|
||||
}
|
||||
});
|
||||
|
||||
void speechToText.transcribeAudio('/test/audio.wav');
|
||||
|
||||
mockProcess.stdout.emtest('data', Buffer.from('Processing'));
|
||||
mockProcess.stderr.emtest('data', Buffer.from('Loading model'));
|
||||
});
|
||||
});
|
||||
|
||||
test('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.emtest('error', new Error('Test error'));
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Cleanup', () => {
|
||||
test('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);
|
||||
});
|
||||
|
||||
test('should clean up resources on shutdown', async () => {
|
||||
await speechToText.initialize();
|
||||
const shutdownSpy = spyOn(speechToText, 'shutdown');
|
||||
await speechToText.shutdown();
|
||||
expect(shutdownSpy).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
});
|
||||
203
__tests__/tools/automation-config.test.ts
Normal file
203
__tests__/tools/automation-config.test.ts
Normal file
@@ -0,0 +1,203 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
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');
|
||||
});
|
||||
});
|
||||
});
|
||||
191
__tests__/tools/automation.test.ts
Normal file
191
__tests__/tools/automation.test.ts
Normal file
@@ -0,0 +1,191 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
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');
|
||||
});
|
||||
});
|
||||
});
|
||||
231
__tests__/tools/device-control.test.ts
Normal file
231
__tests__/tools/device-control.test.ts
Normal file
@@ -0,0 +1,231 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
|
||||
import { tools } from '../../src/index.js';
|
||||
import {
|
||||
TEST_CONFIG,
|
||||
createMockResponse,
|
||||
getMockCallArgs
|
||||
} from '../utils/test-utils';
|
||||
|
||||
describe('Device Control Tools', () => {
|
||||
let mocks: { mockFetch: ReturnType<typeof mock> };
|
||||
|
||||
beforeEach(async () => {
|
||||
// Setup mock fetch
|
||||
mocks = {
|
||||
mockFetch: mock(() => Promise.resolve(createMockResponse({})))
|
||||
};
|
||||
globalThis.fetch = mocks.mockFetch;
|
||||
await Promise.resolve();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Reset mocks
|
||||
globalThis.fetch = undefined;
|
||||
});
|
||||
|
||||
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 = tools.find(tool => tool.name === 'list_devices');
|
||||
expect(listDevicesTool).toBeDefined();
|
||||
|
||||
if (!listDevicesTool) {
|
||||
throw new Error('list_devices tool not found');
|
||||
}
|
||||
|
||||
const result = await listDevicesTool.execute({});
|
||||
|
||||
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 = tools.find(tool => tool.name === 'list_devices');
|
||||
expect(listDevicesTool).toBeDefined();
|
||||
|
||||
if (!listDevicesTool) {
|
||||
throw new Error('list_devices tool not found');
|
||||
}
|
||||
|
||||
const result = await listDevicesTool.execute({});
|
||||
|
||||
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 = tools.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
|
||||
});
|
||||
|
||||
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 = tools.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'
|
||||
});
|
||||
|
||||
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 = tools.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'
|
||||
});
|
||||
|
||||
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 = tools.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
|
||||
});
|
||||
|
||||
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
|
||||
})
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
192
__tests__/tools/entity-state.test.ts
Normal file
192
__tests__/tools/entity-state.test.ts
Normal file
@@ -0,0 +1,192 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
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'
|
||||
}
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
2
__tests__/tools/scene-control.test.ts
Normal file
2
__tests__/tools/scene-control.test.ts
Normal file
@@ -0,0 +1,2 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
|
||||
218
__tests__/tools/script-control.test.ts
Normal file
218
__tests__/tools/script-control.test.ts
Normal file
@@ -0,0 +1,218 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
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');
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { ToolRegistry, ToolCategory, EnhancedTool } from '../../src/tools/index.js';
|
||||
|
||||
describe('ToolRegistry', () => {
|
||||
@@ -18,27 +19,27 @@ describe('ToolRegistry', () => {
|
||||
ttl: 1000
|
||||
}
|
||||
},
|
||||
execute: jest.fn().mockResolvedValue({ success: true }),
|
||||
validate: jest.fn().mockResolvedValue(true),
|
||||
preExecute: jest.fn().mockResolvedValue(undefined),
|
||||
postExecute: jest.fn().mockResolvedValue(undefined)
|
||||
execute: mock().mockResolvedValue({ success: true }),
|
||||
validate: mock().mockResolvedValue(true),
|
||||
preExecute: mock().mockResolvedValue(undefined),
|
||||
postExecute: mock().mockResolvedValue(undefined)
|
||||
};
|
||||
});
|
||||
|
||||
describe('Tool Registration', () => {
|
||||
it('should register a tool successfully', () => {
|
||||
test('should register a tool successfully', () => {
|
||||
registry.registerTool(mockTool);
|
||||
const retrievedTool = registry.getTool('test_tool');
|
||||
expect(retrievedTool).toBe(mockTool);
|
||||
});
|
||||
|
||||
it('should categorize tools correctly', () => {
|
||||
test('should categorize tools correctly', () => {
|
||||
registry.registerTool(mockTool);
|
||||
const deviceTools = registry.getToolsByCategory(ToolCategory.DEVICE);
|
||||
expect(deviceTools).toContain(mockTool);
|
||||
});
|
||||
|
||||
it('should handle multiple tools in the same category', () => {
|
||||
test('should handle multiple tools in the same category', () => {
|
||||
const mockTool2 = {
|
||||
...mockTool,
|
||||
name: 'test_tool_2'
|
||||
@@ -53,7 +54,7 @@ describe('ToolRegistry', () => {
|
||||
});
|
||||
|
||||
describe('Tool Execution', () => {
|
||||
it('should execute a tool with all hooks', async () => {
|
||||
test('should execute a tool with all hooks', async () => {
|
||||
registry.registerTool(mockTool);
|
||||
await registry.executeTool('test_tool', { param: 'value' });
|
||||
|
||||
@@ -63,20 +64,20 @@ describe('ToolRegistry', () => {
|
||||
expect(mockTool.postExecute).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should throw error for non-existent tool', async () => {
|
||||
test('should throw error for non-existent tool', async () => {
|
||||
await expect(registry.executeTool('non_existent', {}))
|
||||
.rejects.toThrow('Tool non_existent not found');
|
||||
});
|
||||
|
||||
it('should handle validation failure', async () => {
|
||||
mockTool.validate = jest.fn().mockResolvedValue(false);
|
||||
test('should handle validation failure', async () => {
|
||||
mockTool.validate = mock().mockResolvedValue(false);
|
||||
registry.registerTool(mockTool);
|
||||
|
||||
await expect(registry.executeTool('test_tool', {}))
|
||||
.rejects.toThrow('Invalid parameters');
|
||||
});
|
||||
|
||||
it('should execute without optional hooks', async () => {
|
||||
test('should execute without optional hooks', async () => {
|
||||
const simpleTool: EnhancedTool = {
|
||||
name: 'simple_tool',
|
||||
description: 'A simple tool',
|
||||
@@ -85,7 +86,7 @@ describe('ToolRegistry', () => {
|
||||
platform: 'test',
|
||||
version: '1.0.0'
|
||||
},
|
||||
execute: jest.fn().mockResolvedValue({ success: true })
|
||||
execute: mock().mockResolvedValue({ success: true })
|
||||
};
|
||||
|
||||
registry.registerTool(simpleTool);
|
||||
@@ -95,7 +96,7 @@ describe('ToolRegistry', () => {
|
||||
});
|
||||
|
||||
describe('Caching', () => {
|
||||
it('should cache tool results when enabled', async () => {
|
||||
test('should cache tool results when enabled', async () => {
|
||||
registry.registerTool(mockTool);
|
||||
const params = { test: 'value' };
|
||||
|
||||
@@ -108,7 +109,7 @@ describe('ToolRegistry', () => {
|
||||
expect(mockTool.execute).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should not cache results when disabled', async () => {
|
||||
test('should not cache results when disabled', async () => {
|
||||
const uncachedTool: EnhancedTool = {
|
||||
...mockTool,
|
||||
metadata: {
|
||||
@@ -130,7 +131,7 @@ describe('ToolRegistry', () => {
|
||||
expect(uncachedTool.execute).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it('should expire cache after TTL', async () => {
|
||||
test('should expire cache after TTL', async () => {
|
||||
mockTool.metadata.caching!.ttl = 100; // Short TTL for testing
|
||||
registry.registerTool(mockTool);
|
||||
const params = { test: 'value' };
|
||||
@@ -147,7 +148,7 @@ describe('ToolRegistry', () => {
|
||||
expect(mockTool.execute).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it('should clean expired cache entries', async () => {
|
||||
test('should clean expired cache entries', async () => {
|
||||
mockTool.metadata.caching!.ttl = 100;
|
||||
registry.registerTool(mockTool);
|
||||
const params = { test: 'value' };
|
||||
@@ -168,12 +169,12 @@ describe('ToolRegistry', () => {
|
||||
});
|
||||
|
||||
describe('Category Management', () => {
|
||||
it('should return empty array for unknown category', () => {
|
||||
test('should return empty array for unknown category', () => {
|
||||
const tools = registry.getToolsByCategory('unknown' as ToolCategory);
|
||||
expect(tools).toEqual([]);
|
||||
});
|
||||
|
||||
it('should handle tools across multiple categories', () => {
|
||||
test('should handle tools across multiple categories', () => {
|
||||
const systemTool: EnhancedTool = {
|
||||
...mockTool,
|
||||
name: 'system_tool',
|
||||
|
||||
19
__tests__/types/litemcp.d.ts
vendored
Normal file
19
__tests__/types/litemcp.d.ts
vendored
Normal file
@@ -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>;
|
||||
}
|
||||
}
|
||||
149
__tests__/utils/test-utils.ts
Normal file
149
__tests__/utils/test-utils.ts
Normal file
@@ -0,0 +1,149 @@
|
||||
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>>;
|
||||
}) => {
|
||||
// Reset mock calls by creating a new mock
|
||||
mocks.liteMcpInstance.addTool = mock((tool: Tool) => undefined);
|
||||
mocks.liteMcpInstance.start = mock(() => Promise.resolve());
|
||||
mocks.mockFetch = mock(() => Promise.resolve(new Response()));
|
||||
globalThis.fetch = mocks.mockFetch;
|
||||
};
|
||||
@@ -1 +1,2 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
|
||||
import { HassWebSocketClient } from '../../src/websocket/client.js';
|
||||
import WebSocket from 'ws';
|
||||
@@ -5,7 +6,7 @@ import { EventEmitter } from 'events';
|
||||
import * as HomeAssistant from '../../src/types/hass.js';
|
||||
|
||||
// Mock WebSocket
|
||||
jest.mock('ws');
|
||||
// // jest.mock('ws');
|
||||
|
||||
describe('WebSocket Event Handling', () => {
|
||||
let client: HassWebSocketClient;
|
||||
@@ -25,10 +26,10 @@ describe('WebSocket Event Handling', () => {
|
||||
eventEmitter.on(event, listener);
|
||||
return mockWebSocket;
|
||||
}),
|
||||
send: jest.fn(),
|
||||
close: jest.fn(),
|
||||
send: mock(),
|
||||
close: mock(),
|
||||
readyState: WebSocket.OPEN,
|
||||
removeAllListeners: jest.fn(),
|
||||
removeAllListeners: mock(),
|
||||
// Add required WebSocket properties
|
||||
binaryType: 'arraybuffer',
|
||||
bufferedAmount: 0,
|
||||
@@ -36,9 +37,9 @@ describe('WebSocket Event Handling', () => {
|
||||
protocol: '',
|
||||
url: 'ws://test.com',
|
||||
isPaused: () => false,
|
||||
ping: jest.fn(),
|
||||
pong: jest.fn(),
|
||||
terminate: jest.fn()
|
||||
ping: mock(),
|
||||
pong: mock(),
|
||||
terminate: mock()
|
||||
} as unknown as jest.Mocked<WebSocket>;
|
||||
|
||||
// Mock WebSocket constructor
|
||||
@@ -53,9 +54,9 @@ describe('WebSocket Event Handling', () => {
|
||||
client.disconnect();
|
||||
});
|
||||
|
||||
it('should handle connection events', () => {
|
||||
test('should handle connection events', () => {
|
||||
// Simulate open event
|
||||
eventEmitter.emit('open');
|
||||
eventEmitter.emtest('open');
|
||||
|
||||
// Verify authentication message was sent
|
||||
expect(mockWebSocket.send).toHaveBeenCalledWith(
|
||||
@@ -63,17 +64,17 @@ describe('WebSocket Event Handling', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle authentication response', () => {
|
||||
test('should handle authentication response', () => {
|
||||
// Simulate auth_ok message
|
||||
eventEmitter.emit('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
|
||||
// Verify client is ready for commands
|
||||
expect(mockWebSocket.readyState).toBe(WebSocket.OPEN);
|
||||
});
|
||||
|
||||
it('should handle auth failure', () => {
|
||||
test('should handle auth failure', () => {
|
||||
// Simulate auth_invalid message
|
||||
eventEmitter.emit('message', JSON.stringify({
|
||||
eventEmitter.emtest('message', JSON.stringify({
|
||||
type: 'auth_invalid',
|
||||
message: 'Invalid token'
|
||||
}));
|
||||
@@ -82,34 +83,34 @@ describe('WebSocket Event Handling', () => {
|
||||
expect(mockWebSocket.close).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle connection errors', () => {
|
||||
test('should handle connection errors', () => {
|
||||
// Create error spy
|
||||
const errorSpy = jest.fn();
|
||||
const errorSpy = mock();
|
||||
client.on('error', errorSpy);
|
||||
|
||||
// Simulate error
|
||||
const testError = new Error('Test error');
|
||||
eventEmitter.emit('error', testError);
|
||||
eventEmitter.emtest('error', testError);
|
||||
|
||||
// Verify error was handled
|
||||
expect(errorSpy).toHaveBeenCalledWith(testError);
|
||||
});
|
||||
|
||||
it('should handle disconnection', () => {
|
||||
test('should handle disconnection', () => {
|
||||
// Create close spy
|
||||
const closeSpy = jest.fn();
|
||||
const closeSpy = mock();
|
||||
client.on('close', closeSpy);
|
||||
|
||||
// Simulate close
|
||||
eventEmitter.emit('close');
|
||||
eventEmitter.emtest('close');
|
||||
|
||||
// Verify close was handled
|
||||
expect(closeSpy).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle event messages', () => {
|
||||
test('should handle event messages', () => {
|
||||
// Create event spy
|
||||
const eventSpy = jest.fn();
|
||||
const eventSpy = mock();
|
||||
client.on('event', eventSpy);
|
||||
|
||||
// Simulate event message
|
||||
@@ -123,44 +124,44 @@ describe('WebSocket Event Handling', () => {
|
||||
}
|
||||
}
|
||||
};
|
||||
eventEmitter.emit('message', JSON.stringify(eventData));
|
||||
eventEmitter.emtest('message', JSON.stringify(eventData));
|
||||
|
||||
// Verify event was handled
|
||||
expect(eventSpy).toHaveBeenCalledWith(eventData.event);
|
||||
});
|
||||
|
||||
describe('Connection Events', () => {
|
||||
it('should handle successful connection', (done) => {
|
||||
test('should handle successful connection', (done) => {
|
||||
client.on('open', () => {
|
||||
expect(mockWebSocket.send).toHaveBeenCalled();
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emit('open');
|
||||
eventEmitter.emtest('open');
|
||||
});
|
||||
|
||||
it('should handle connection errors', (done) => {
|
||||
test('should handle connection errors', (done) => {
|
||||
const error = new Error('Connection failed');
|
||||
client.on('error', (err: Error) => {
|
||||
expect(err).toBe(error);
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emit('error', error);
|
||||
eventEmitter.emtest('error', error);
|
||||
});
|
||||
|
||||
it('should handle connection close', (done) => {
|
||||
test('should handle connection close', (done) => {
|
||||
client.on('disconnected', () => {
|
||||
expect(mockWebSocket.close).toHaveBeenCalled();
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emit('close');
|
||||
eventEmitter.emtest('close');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Authentication', () => {
|
||||
it('should send authentication message on connect', () => {
|
||||
test('should send authentication message on connect', () => {
|
||||
const authMessage: HomeAssistant.AuthMessage = {
|
||||
type: 'auth',
|
||||
access_token: 'test_token'
|
||||
@@ -170,27 +171,27 @@ describe('WebSocket Event Handling', () => {
|
||||
expect(mockWebSocket.send).toHaveBeenCalledWith(JSON.stringify(authMessage));
|
||||
});
|
||||
|
||||
it('should handle successful authentication', (done) => {
|
||||
test('should handle successful authentication', (done) => {
|
||||
client.on('auth_ok', () => {
|
||||
done();
|
||||
});
|
||||
|
||||
client.connect();
|
||||
eventEmitter.emit('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
});
|
||||
|
||||
it('should handle authentication failure', (done) => {
|
||||
test('should handle authentication failure', (done) => {
|
||||
client.on('auth_invalid', () => {
|
||||
done();
|
||||
});
|
||||
|
||||
client.connect();
|
||||
eventEmitter.emit('message', JSON.stringify({ type: 'auth_invalid' }));
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'auth_invalid' }));
|
||||
});
|
||||
});
|
||||
|
||||
describe('Event Subscription', () => {
|
||||
it('should handle state changed events', (done) => {
|
||||
test('should handle state changed events', (done) => {
|
||||
const stateEvent: HomeAssistant.StateChangedEvent = {
|
||||
event_type: 'state_changed',
|
||||
data: {
|
||||
@@ -236,16 +237,16 @@ describe('WebSocket Event Handling', () => {
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emit('message', JSON.stringify({ type: 'event', event: stateEvent }));
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'event', event: stateEvent }));
|
||||
});
|
||||
|
||||
it('should subscribe to specific events', async () => {
|
||||
test('should subscribe to specific events', async () => {
|
||||
const subscriptionId = 1;
|
||||
const callback = jest.fn();
|
||||
const callback = mock();
|
||||
|
||||
// Mock successful subscription
|
||||
const subscribePromise = client.subscribeEvents('state_changed', callback);
|
||||
eventEmitter.emit('message', JSON.stringify({
|
||||
eventEmitter.emtest('message', JSON.stringify({
|
||||
id: 1,
|
||||
type: 'result',
|
||||
success: true
|
||||
@@ -258,7 +259,7 @@ describe('WebSocket Event Handling', () => {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'on'
|
||||
};
|
||||
eventEmitter.emit('message', JSON.stringify({
|
||||
eventEmitter.emtest('message', JSON.stringify({
|
||||
type: 'event',
|
||||
event: {
|
||||
event_type: 'state_changed',
|
||||
@@ -269,13 +270,13 @@ describe('WebSocket Event Handling', () => {
|
||||
expect(callback).toHaveBeenCalledWith(eventData);
|
||||
});
|
||||
|
||||
it('should unsubscribe from events', async () => {
|
||||
test('should unsubscribe from events', async () => {
|
||||
// First subscribe
|
||||
const subscriptionId = await client.subscribeEvents('state_changed', () => { });
|
||||
|
||||
// Then unsubscribe
|
||||
const unsubscribePromise = client.unsubscribeEvents(subscriptionId);
|
||||
eventEmitter.emit('message', JSON.stringify({
|
||||
eventEmitter.emtest('message', JSON.stringify({
|
||||
id: 2,
|
||||
type: 'result',
|
||||
success: true
|
||||
@@ -286,16 +287,16 @@ describe('WebSocket Event Handling', () => {
|
||||
});
|
||||
|
||||
describe('Message Handling', () => {
|
||||
it('should handle malformed messages', (done) => {
|
||||
test('should handle malformed messages', (done) => {
|
||||
client.on('error', (error: Error) => {
|
||||
expect(error.message).toContain('Unexpected token');
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emit('message', 'invalid json');
|
||||
eventEmitter.emtest('message', 'invalid json');
|
||||
});
|
||||
|
||||
it('should handle unknown message types', (done) => {
|
||||
test('should handle unknown message types', (done) => {
|
||||
const unknownMessage = {
|
||||
type: 'unknown_type',
|
||||
data: {}
|
||||
@@ -306,12 +307,12 @@ describe('WebSocket Event Handling', () => {
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emit('message', JSON.stringify(unknownMessage));
|
||||
eventEmitter.emtest('message', JSON.stringify(unknownMessage));
|
||||
});
|
||||
});
|
||||
|
||||
describe('Reconnection', () => {
|
||||
it('should attempt to reconnect on connection loss', (done) => {
|
||||
test('should attempt to reconnect on connection loss', (done) => {
|
||||
let reconnectAttempts = 0;
|
||||
client.on('disconnected', () => {
|
||||
reconnectAttempts++;
|
||||
@@ -321,19 +322,19 @@ describe('WebSocket Event Handling', () => {
|
||||
}
|
||||
});
|
||||
|
||||
eventEmitter.emit('close');
|
||||
eventEmitter.emtest('close');
|
||||
});
|
||||
|
||||
it('should re-authenticate after reconnection', (done) => {
|
||||
test('should re-authenticate after reconnection', (done) => {
|
||||
client.connect();
|
||||
|
||||
client.on('auth_ok', () => {
|
||||
done();
|
||||
});
|
||||
|
||||
eventEmitter.emit('close');
|
||||
eventEmitter.emit('open');
|
||||
eventEmitter.emit('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
eventEmitter.emtest('close');
|
||||
eventEmitter.emtest('open');
|
||||
eventEmitter.emtest('message', JSON.stringify({ type: 'auth_ok' }));
|
||||
});
|
||||
});
|
||||
});
|
||||
604
bun.lock
Normal file
604
bun.lock
Normal file
@@ -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=="],
|
||||
}
|
||||
}
|
||||
64
docker-build.sh
Executable file
64
docker-build.sh
Executable file
@@ -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
|
||||
88
docker/speech/Dockerfile
Normal file
88
docker/speech/Dockerfile
Normal file
@@ -0,0 +1,88 @@
|
||||
# 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 \
|
||||
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" \
|
||||
"sounddevice" \
|
||||
"openwakeword" \
|
||||
"faster-whisper" \
|
||||
"transformers" \
|
||||
"torch" \
|
||||
"torchaudio" \
|
||||
"huggingface_hub" \
|
||||
"requests" \
|
||||
"soundfile" \
|
||||
"tflite-runtime"
|
||||
|
||||
# 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 \
|
||||
pulseaudio \
|
||||
alsa-utils \
|
||||
curl \
|
||||
wget
|
||||
|
||||
# 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
|
||||
|
||||
# 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
|
||||
|
||||
# Start the application
|
||||
CMD ["/setup-audio.sh"]
|
||||
68
docker/speech/setup-audio.sh
Executable file
68
docker/speech/setup-audio.sh
Executable file
@@ -0,0 +1,68 @@
|
||||
#!/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... (${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
|
||||
|
||||
# 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 with error handling
|
||||
if ! pactl list sources; then
|
||||
echo "ERROR: Failed to list audio devices"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 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
|
||||
|
||||
# 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%
|
||||
|
||||
# Keep the script running to prevent container exit
|
||||
echo "Audio setup complete. Keeping container alive."
|
||||
tail -f /dev/null
|
||||
415
docker/speech/wake_word_detector.py
Normal file
415
docker/speech/wake_word_detector.py
Normal file
@@ -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('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):
|
||||
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
|
||||
@@ -4,6 +4,9 @@ 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.
|
||||
@@ -15,3 +18,6 @@ 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"
|
||||
@@ -2,9 +2,24 @@ 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:
|
||||
@@ -56,3 +71,8 @@ exclude:
|
||||
- Gemfile.lock
|
||||
- node_modules
|
||||
- vendor
|
||||
|
||||
# Sass settings
|
||||
sass:
|
||||
style: compressed
|
||||
sass_dir: _sass
|
||||
754
docs/api.md
754
docs/api.md
@@ -1,728 +1,170 @@
|
||||
# 🚀 Home Assistant MCP API Documentation
|
||||
# Home Assistant MCP Server API Documentation
|
||||
|
||||
 
|
||||
## Overview
|
||||
|
||||
## 🌟 Quick Start
|
||||
This document provides a reference for the MCP Server API, which offers basic device control and state management for Home Assistant.
|
||||
|
||||
```bash
|
||||
# Get API schema with caching
|
||||
curl -X GET http://localhost:3000/mcp \
|
||||
-H "Cache-Control: max-age=3600" # Cache for 1 hour
|
||||
```
|
||||
## Authentication
|
||||
|
||||
## 🔌 Core Functions ⚙️
|
||||
All API requests require a valid JWT token in the Authorization header:
|
||||
|
||||
### State Management (`/api/state`)
|
||||
```http
|
||||
GET /api/state?cache=true # Enable client-side caching
|
||||
POST /api/state
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
**Example Request:**
|
||||
## Core Endpoints
|
||||
|
||||
### Device State Management
|
||||
|
||||
#### Get Device State
|
||||
```http
|
||||
GET /api/state/{entity_id}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"context": "living_room",
|
||||
"state": {
|
||||
"lights": "on",
|
||||
"temperature": 22
|
||||
},
|
||||
"_cache": { // Optional caching config
|
||||
"ttl": 300, // 5 minutes
|
||||
"tags": ["lights", "climate"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## ⚡ Action Endpoints
|
||||
|
||||
### Execute Action with Cache Validation
|
||||
```http
|
||||
POST /api/action
|
||||
If-None-Match: "etag_value" // Prevent duplicate actions
|
||||
```
|
||||
|
||||
**Batch Processing:**
|
||||
```json
|
||||
{
|
||||
"actions": [
|
||||
{ "action": "🌞 Morning Routine", "params": { "brightness": 80 } },
|
||||
{ "action": "❄️ AC Control", "params": { "temp": 21 } }
|
||||
],
|
||||
"_parallel": true // Execute actions concurrently
|
||||
}
|
||||
```
|
||||
|
||||
## 🔍 Query Functions
|
||||
|
||||
### Available Actions with ETag
|
||||
```http
|
||||
GET /api/actions
|
||||
ETag: "a1b2c3d4" // Client-side cache validation
|
||||
```
|
||||
|
||||
**Response Headers:**
|
||||
```
|
||||
Cache-Control: public, max-age=86400 // 24-hour cache
|
||||
ETag: "a1b2c3d4"
|
||||
```
|
||||
|
||||
## 🌐 WebSocket Events
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('wss://ha-mcp/ws');
|
||||
ws.onmessage = ({ data }) => {
|
||||
const event = JSON.parse(data);
|
||||
if(event.type === 'STATE_UPDATE') {
|
||||
updateUI(event.payload); // 🎨 Real-time UI sync
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 🗃️ Caching Strategies
|
||||
|
||||
### Client-Side Caching
|
||||
```http
|
||||
GET /api/devices
|
||||
Cache-Control: max-age=300, stale-while-revalidate=60
|
||||
```
|
||||
|
||||
### Server-Side Cache-Control
|
||||
```typescript
|
||||
// Example middleware configuration
|
||||
app.use(
|
||||
cacheMiddleware({
|
||||
ttl: 60 * 5, // 5 minutes
|
||||
paths: ['/api/devices', '/mcp'],
|
||||
vary: ['Authorization'] // User-specific caching
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
## ❌ Error Handling
|
||||
|
||||
**429 Too Many Requests:**
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "RATE_LIMITED",
|
||||
"message": "Slow down! 🐢",
|
||||
"retry_after": 30,
|
||||
"docs": "https://ha-mcp/docs/rate-limits"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🚦 Rate Limiting Tiers
|
||||
|
||||
| Tier | Requests/min | Features |
|
||||
|---------------|--------------|------------------------|
|
||||
| Guest | 10 | Basic read-only |
|
||||
| User | 100 | Full access |
|
||||
| Power User | 500 | Priority queue |
|
||||
| Integration | 1000 | Bulk operations |
|
||||
|
||||
## 🛠️ Example Usage
|
||||
|
||||
### Smart Cache Refresh
|
||||
```javascript
|
||||
async function getDevices() {
|
||||
const response = await fetch('/api/devices', {
|
||||
headers: {
|
||||
'If-None-Match': localStorage.getItem('devicesETag')
|
||||
}
|
||||
});
|
||||
|
||||
if(response.status === 304) { // Not Modified
|
||||
return JSON.parse(localStorage.devicesCache);
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
localStorage.setItem('devicesETag', response.headers.get('ETag'));
|
||||
localStorage.setItem('devicesCache', JSON.stringify(data));
|
||||
return data;
|
||||
}
|
||||
```
|
||||
|
||||
## 🔒 Security Middleware (Enhanced)
|
||||
|
||||
### Cache-Aware Rate Limiting
|
||||
```typescript
|
||||
app.use(
|
||||
rateLimit({
|
||||
windowMs: 15 * 60 * 1000, // 15 minutes
|
||||
max: 100, // Limit each IP to 100 requests per window
|
||||
cache: new RedisStore(), // Distributed cache
|
||||
keyGenerator: (req) => {
|
||||
return `${req.ip}-${req.headers.authorization}`;
|
||||
}
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
### Security Headers
|
||||
```http
|
||||
Content-Security-Policy: default-src 'self';
|
||||
Strict-Transport-Security: max-age=31536000;
|
||||
X-Content-Type-Options: nosniff;
|
||||
Cache-Control: public, max-age=600;
|
||||
ETag: "abc123"
|
||||
```
|
||||
|
||||
## 📘 Best Practices
|
||||
|
||||
1. **Cache Wisely:** Use `ETag` and `Cache-Control` headers for state data
|
||||
2. **Batch Operations:** Combine requests using `/api/actions/batch`
|
||||
3. **WebSocket First:** Prefer real-time updates over polling
|
||||
4. **Error Recovery:** Implement exponential backoff with jitter
|
||||
5. **Cache Invalidation:** Use tags for bulk invalidation
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Client] -->|Cached Request| B{CDN}
|
||||
B -->|Cache Hit| C[Return 304]
|
||||
B -->|Cache Miss| D[Origin Server]
|
||||
D -->|Response| B
|
||||
B -->|Response| A
|
||||
```
|
||||
|
||||
> Pro Tip: Use `curl -I` to inspect cache headers! 🔍
|
||||
|
||||
## Device Control
|
||||
|
||||
### Common Entity Controls
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "control",
|
||||
"command": "turn_on", // Options: "turn_on", "turn_off", "toggle"
|
||||
"entity_id": "light.living_room"
|
||||
}
|
||||
```
|
||||
|
||||
### Light Control
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "control",
|
||||
"command": "turn_on",
|
||||
"entity_id": "light.living_room",
|
||||
"brightness": 128,
|
||||
"color_temp": 4000,
|
||||
"rgb_color": [255, 0, 0]
|
||||
"state": "on",
|
||||
"attributes": {
|
||||
"brightness": 128
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
#### Update Device State
|
||||
```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
|
||||
```
|
||||
Content-Type: application/json
|
||||
|
||||
Manages the current state of the system.
|
||||
|
||||
**Example Request:**
|
||||
```json
|
||||
POST /api/state
|
||||
{
|
||||
"context": "living_room",
|
||||
"state": {
|
||||
"lights": "on",
|
||||
"temperature": 22
|
||||
"entity_id": "light.living_room",
|
||||
"state": "on",
|
||||
"attributes": {
|
||||
"brightness": 128
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Context Updates
|
||||
### Device Control
|
||||
|
||||
#### Execute Device Command
|
||||
```http
|
||||
POST /api/context
|
||||
```
|
||||
POST /api/control
|
||||
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"
|
||||
}
|
||||
```
|
||||
|
||||
## 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",
|
||||
"entity_id": "light.living_room",
|
||||
"command": "turn_on",
|
||||
"parameters": {
|
||||
"room": "living_room",
|
||||
"brightness": 80
|
||||
"brightness": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Batch Actions
|
||||
```http
|
||||
POST /api/actions/batch
|
||||
```
|
||||
## Real-Time Updates
|
||||
|
||||
Executes multiple actions in sequence.
|
||||
|
||||
**Example Request:**
|
||||
```json
|
||||
POST /api/actions/batch
|
||||
{
|
||||
"actions": [
|
||||
{
|
||||
"action": "turn_on_lights",
|
||||
"parameters": {
|
||||
"room": "living_room"
|
||||
}
|
||||
},
|
||||
{
|
||||
"action": "set_temperature",
|
||||
"parameters": {
|
||||
"temperature": 22
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Query Functions
|
||||
|
||||
### Get Available Actions
|
||||
```http
|
||||
GET /api/actions
|
||||
```
|
||||
|
||||
Returns a list of all available actions.
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"actions": [
|
||||
{
|
||||
"name": "turn_on_lights",
|
||||
"parameters": ["room", "brightness"],
|
||||
"description": "Turns on lights in specified room"
|
||||
},
|
||||
{
|
||||
"name": "set_temperature",
|
||||
"parameters": ["temperature"],
|
||||
"description": "Sets temperature in current context"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Context Query
|
||||
```http
|
||||
GET /api/context?type=current
|
||||
```
|
||||
|
||||
Retrieves context information.
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"current_context": {
|
||||
"user": "john",
|
||||
"location": "kitchen",
|
||||
"time": "morning",
|
||||
"activity": "cooking"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## WebSocket Events
|
||||
|
||||
The server supports real-time updates via WebSocket connections.
|
||||
### WebSocket Connection
|
||||
Connect to real-time updates:
|
||||
|
||||
```javascript
|
||||
// Client-side connection example
|
||||
const ws = new WebSocket('ws://localhost:3000/ws');
|
||||
|
||||
const ws = new WebSocket('ws://localhost:3000/events');
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Received update:', data);
|
||||
const deviceUpdate = JSON.parse(event.data);
|
||||
console.log('Device state changed:', deviceUpdate);
|
||||
};
|
||||
```
|
||||
|
||||
### Supported Events
|
||||
|
||||
- `state_change`: Emitted when system state changes
|
||||
- `context_update`: Emitted when context is updated
|
||||
- `action_executed`: Emitted when an action is completed
|
||||
- `error`: Emitted when an error occurs
|
||||
|
||||
**Example Event Data:**
|
||||
```json
|
||||
{
|
||||
"event": "state_change",
|
||||
"data": {
|
||||
"previous_state": {
|
||||
"lights": "off"
|
||||
},
|
||||
"current_state": {
|
||||
"lights": "on"
|
||||
},
|
||||
"timestamp": "2024-03-20T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
All endpoints return standard HTTP status codes:
|
||||
### Common Error Responses
|
||||
|
||||
- 200: Success
|
||||
- 400: Bad Request
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Not Found
|
||||
- 500: Internal Server Error
|
||||
|
||||
**Error Response Format:**
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "INVALID_PARAMETERS",
|
||||
"message": "Missing required parameter: room",
|
||||
"details": {
|
||||
"missing_fields": ["room"]
|
||||
}
|
||||
"code": "INVALID_REQUEST",
|
||||
"message": "Invalid request parameters",
|
||||
"details": "Entity ID not found or invalid command"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
The API implements rate limiting to prevent abuse:
|
||||
Basic rate limiting is implemented:
|
||||
- Maximum of 100 requests per minute
|
||||
- Excess requests will receive a 429 Too Many Requests response
|
||||
|
||||
- 100 requests per minute per IP for regular endpoints
|
||||
- 1000 requests per minute per IP for WebSocket connections
|
||||
## Supported Operations
|
||||
|
||||
When rate limit is exceeded, the server returns:
|
||||
### Supported Commands
|
||||
- `turn_on`
|
||||
- `turn_off`
|
||||
- `toggle`
|
||||
- `set_brightness`
|
||||
- `set_color`
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "RATE_LIMIT_EXCEEDED",
|
||||
"message": "Too many requests",
|
||||
"reset_time": "2024-03-20T10:31:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
### Supported Entities
|
||||
- Lights
|
||||
- Switches
|
||||
- Climate controls
|
||||
- Media players
|
||||
|
||||
## Example Usage
|
||||
## Limitations
|
||||
|
||||
### Using curl
|
||||
```bash
|
||||
# Get current state
|
||||
curl -X GET \
|
||||
http://localhost:3000/api/state \
|
||||
-H 'Authorization: ApiKey your_api_key_here'
|
||||
- Limited to basic device control
|
||||
- No advanced automation
|
||||
- Minimal error handling
|
||||
- Basic authentication
|
||||
|
||||
# Execute action
|
||||
curl -X POST \
|
||||
http://localhost:3000/api/action \
|
||||
-H 'Authorization: ApiKey your_api_key_here' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"action": "turn_on_lights",
|
||||
"parameters": {
|
||||
"room": "living_room",
|
||||
"brightness": 80
|
||||
}
|
||||
}'
|
||||
```
|
||||
## Best Practices
|
||||
|
||||
### Using JavaScript
|
||||
```javascript
|
||||
// Execute action
|
||||
async function executeAction() {
|
||||
const response = await fetch('http://localhost:3000/api/action', {
|
||||
1. Always include a valid JWT token
|
||||
2. Handle potential errors in your client code
|
||||
3. Use WebSocket for real-time updates when possible
|
||||
4. Validate entity IDs before sending commands
|
||||
|
||||
## Example Client Usage
|
||||
|
||||
```typescript
|
||||
async function controlDevice(entityId: string, command: string, params?: Record<string, unknown>) {
|
||||
try {
|
||||
const response = await fetch('/api/control', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'ApiKey your_api_key_here',
|
||||
'Content-Type': 'application/json'
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${token}`
|
||||
},
|
||||
body: JSON.stringify({
|
||||
action: 'turn_on_lights',
|
||||
parameters: {
|
||||
room: 'living_room',
|
||||
brightness: 80
|
||||
}
|
||||
entity_id: entityId,
|
||||
command,
|
||||
parameters: params
|
||||
})
|
||||
});
|
||||
|
||||
const data = await response.json();
|
||||
console.log('Action result:', data);
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(error.message);
|
||||
}
|
||||
```
|
||||
|
||||
## Security Middleware
|
||||
|
||||
### Overview
|
||||
|
||||
The security middleware provides a comprehensive set of utility functions to enhance the security of the Home Assistant MCP application. These functions cover various aspects of web security, including:
|
||||
|
||||
- Rate limiting
|
||||
- Request validation
|
||||
- Input sanitization
|
||||
- Security headers
|
||||
- Error handling
|
||||
|
||||
### Utility Functions
|
||||
|
||||
#### `checkRateLimit(ip: string, maxRequests?: number, windowMs?: number)`
|
||||
|
||||
Manages rate limiting for IP addresses to prevent abuse.
|
||||
|
||||
**Parameters**:
|
||||
- `ip`: IP address to track
|
||||
- `maxRequests`: Maximum number of requests allowed (default: 100)
|
||||
- `windowMs`: Time window for rate limiting (default: 15 minutes)
|
||||
|
||||
**Returns**: `boolean` or throws an error if limit is exceeded
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
try {
|
||||
checkRateLimit('127.0.0.1'); // Checks rate limit with default settings
|
||||
return await response.json();
|
||||
} catch (error) {
|
||||
// Handle rate limit exceeded
|
||||
console.error('Device control failed:', error);
|
||||
throw error;
|
||||
}
|
||||
```
|
||||
|
||||
#### `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
|
||||
}
|
||||
|
||||
// Usage example
|
||||
controlDevice('light.living_room', 'turn_on', { brightness: 50 })
|
||||
.then(result => console.log('Device controlled successfully'))
|
||||
.catch(error => console.error('Control failed', error));
|
||||
```
|
||||
|
||||
#### `sanitizeValue(value: unknown)`
|
||||
## Future Development
|
||||
|
||||
Sanitizes input values to prevent XSS attacks.
|
||||
Planned improvements:
|
||||
- Enhanced error handling
|
||||
- More comprehensive device support
|
||||
- Improved authentication mechanisms
|
||||
|
||||
**Features**:
|
||||
- Escapes HTML tags
|
||||
- Handles nested objects and arrays
|
||||
- Preserves non-string values
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
const sanitized = sanitizeValue('<script>alert("xss")</script>');
|
||||
// Returns: '<script>alert("xss")</script>'
|
||||
```
|
||||
|
||||
#### `applySecurityHeaders(request: Request, helmetConfig?: HelmetOptions)`
|
||||
|
||||
Applies security headers to HTTP requests using Helmet.
|
||||
|
||||
**Security Headers**:
|
||||
- Content Security Policy
|
||||
- X-Frame-Options
|
||||
- X-Content-Type-Options
|
||||
- Referrer Policy
|
||||
- HSTS (in production)
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
const headers = applySecurityHeaders(request);
|
||||
```
|
||||
|
||||
#### `handleError(error: Error, env?: string)`
|
||||
|
||||
Handles error responses with environment-specific details.
|
||||
|
||||
**Modes**:
|
||||
- Production: Generic error message
|
||||
- Development: Detailed error with stack trace
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
const errorResponse = handleError(error, process.env.NODE_ENV);
|
||||
```
|
||||
|
||||
### Middleware Usage
|
||||
|
||||
These utility functions are integrated into Elysia middleware:
|
||||
|
||||
```typescript
|
||||
const app = new Elysia()
|
||||
.use(rateLimiter) // Rate limiting
|
||||
.use(validateRequest) // Request validation
|
||||
.use(sanitizeInput) // Input sanitization
|
||||
.use(securityHeaders) // Security headers
|
||||
.use(errorHandler) // Error handling
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. Always validate and sanitize user inputs
|
||||
2. Use rate limiting to prevent abuse
|
||||
3. Apply security headers
|
||||
4. Handle errors gracefully
|
||||
5. Keep environment-specific error handling
|
||||
|
||||
### Security Considerations
|
||||
|
||||
- Configurable rate limits
|
||||
- XSS protection
|
||||
- Content security policies
|
||||
- Token validation
|
||||
- Error information exposure control
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- Ensure `JWT_SECRET` is set in environment
|
||||
- Check content type in requests
|
||||
- Monitor rate limit errors
|
||||
- Review error handling in different environments
|
||||
*API is subject to change. Always refer to the latest documentation.*
|
||||
|
||||
326
docs/api/core.md
Normal file
326
docs/api/core.md
Normal file
@@ -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)
|
||||
242
docs/api/index.md
Normal file
242
docs/api/index.md
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
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
|
||||
|
||||
# API Reference
|
||||
|
||||
The Advanced Home Assistant MCP provides several APIs for integration and automation:
|
||||
|
||||
- [Core API](core.md) - Primary interface for system control
|
||||
- [SSE API](sse.md) - Server-Sent Events for real-time updates
|
||||
- [Core Functions](core.md) - Essential system functions
|
||||
266
docs/api/sse.md
Normal file
266
docs/api/sse.md
Normal file
@@ -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)
|
||||
@@ -1,68 +1,88 @@
|
||||
# Architecture Documentation for MCP Server
|
||||
---
|
||||
layout: default
|
||||
title: Architecture
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
## Overview
|
||||
# Architecture Overview 🏗️
|
||||
|
||||
The MCP Server is designed as a high-performance, secure, and scalable bridge between Home Assistant and Language Learning Models (LLMs). This document outlines the architectural design principles, core components, and deployment strategies that power the MCP Server.
|
||||
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.
|
||||
|
||||
## Key Architectural Components
|
||||
## System Architecture
|
||||
|
||||
### High-Performance Runtime with Bun
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Client Layer"
|
||||
WC[Web Clients]
|
||||
MC[Mobile Clients]
|
||||
end
|
||||
|
||||
- **Fast Startup & Efficiency:** Powered by Bun, the MCP Server benefits from rapid startup times, efficient memory utilization, and native TypeScript support.
|
||||
- **Optimized Build Process:** Bun's build tools allow for quick iteration and deployment, ensuring minimal downtime and swift performance enhancement.
|
||||
subgraph "MCP Server"
|
||||
API[API Gateway]
|
||||
SSE[SSE Manager]
|
||||
WS[WebSocket Server]
|
||||
CM[Command Manager]
|
||||
end
|
||||
|
||||
### Real-time Communication using Server-Sent Events (SSE)
|
||||
subgraph "Home Assistant"
|
||||
HA[Home Assistant Core]
|
||||
Dev[Devices & Services]
|
||||
end
|
||||
|
||||
- **Continuous Updates:** The server leverages SSE to deliver real-time notifications and updates, ensuring that any changes in Home Assistant are immediately communicated to connected clients.
|
||||
- **Scalable Connection Handling:** SSE provides an event-driven model that efficiently manages multiple simultaneous client connections.
|
||||
WC --> |HTTP/WS| API
|
||||
MC --> |HTTP/WS| API
|
||||
|
||||
### Modular & Extensible Design
|
||||
API --> |Events| SSE
|
||||
API --> |Real-time| WS
|
||||
|
||||
- **Plugin Architecture:** Designed with modularity in mind, the MCP Server supports plugins, add-ons, and custom automation scripts, enabling seamless feature expansion without disrupting core functionality.
|
||||
- **Separation of Concerns:** Different components, such as device management, automation control, and system monitoring, are clearly separated, allowing independent development, testing, and scaling.
|
||||
API --> HA
|
||||
HA --> API
|
||||
```
|
||||
|
||||
### Secure API Integration
|
||||
## Core Components
|
||||
|
||||
- **Token-Based Authentication:** Robust token-based authentication mechanisms restrict access to authorized users and systems.
|
||||
- **Rate Limiting & Error Handling:** Integrated rate limiting combined with comprehensive error handling ensures system stability and prevents misuse.
|
||||
- **Best Practices:** All API endpoints follow industry-standard security guidelines to protect data and maintain system integrity.
|
||||
### API Gateway
|
||||
- Handles incoming HTTP and WebSocket requests
|
||||
- Provides endpoints for device management
|
||||
- Implements basic authentication and request validation
|
||||
|
||||
### Deployment & Scalability
|
||||
### SSE Manager
|
||||
- Manages Server-Sent Events for real-time updates
|
||||
- Broadcasts device state changes to connected clients
|
||||
|
||||
- **Containerized Deployment with Docker:** The use of Docker Compose enables straightforward deployment, management, and scaling of the server and its dependencies.
|
||||
- **Flexible Environment Configuration:** Environment variables and configuration files (.env) facilitate smooth transitions between development, testing, and production setups.
|
||||
### WebSocket Server
|
||||
- Provides real-time, bidirectional communication
|
||||
- Supports basic device control and state monitoring
|
||||
|
||||
## Future Enhancements
|
||||
### Command Manager
|
||||
- Processes device control requests
|
||||
- Translates API commands to Home Assistant compatible formats
|
||||
|
||||
- **Advanced Automation Logic:** Integration of more complex automation rules and conditional decision-making capabilities.
|
||||
- **Enhanced Security Measures:** Additional layers of security, such as multi-factor authentication and improved encryption techniques, are on the roadmap.
|
||||
- **Improved Monitoring & Analytics:** Future updates will introduce advanced performance metrics and real-time analytics to monitor system health and user interactions.
|
||||
## Communication Flow
|
||||
|
||||
## Conclusion
|
||||
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
|
||||
|
||||
The architecture of the MCP Server prioritizes performance, scalability, and security. By leveraging Bun's high-performance runtime, employing real-time communication through SSE, and maintaining a modular, secure design, the MCP Server provides a robust platform for integrating Home Assistant with modern LLM functionalities.
|
||||
## Key Design Principles
|
||||
|
||||
*This document is a living document and will be updated as the system evolves.*
|
||||
- **Simplicity:** Lightweight, focused design
|
||||
- **Flexibility:** Easily extendable architecture
|
||||
- **Performance:** Efficient request handling
|
||||
- **Security:** Basic authentication and validation
|
||||
|
||||
## Key Components
|
||||
## Limitations
|
||||
|
||||
- **API Module:** Handles RESTful endpoints, authentication, and error management.
|
||||
- **SSE Module:** Provides real-time updates through Server-Sent Events.
|
||||
- **Tools Module:** Offers various utilities for device control, automation, and data processing.
|
||||
- **Security Module:** Implements token-based authentication and secure communications.
|
||||
- **Integration Module:** Bridges data between Home Assistant and external systems.
|
||||
- Basic device control capabilities
|
||||
- Limited advanced automation features
|
||||
- Minimal third-party integrations
|
||||
|
||||
## Data Flow
|
||||
## Future Improvements
|
||||
|
||||
1. Requests enter via the API endpoints.
|
||||
2. Security middleware validates and processes requests.
|
||||
3. Core modules process data and execute the necessary business logic.
|
||||
4. Real-time notifications are managed by the SSE module.
|
||||
- Enhanced error handling
|
||||
- More robust authentication
|
||||
- Expanded device type support
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Expand modularity with potential microservices.
|
||||
- Enhance security with multi-factor authentication.
|
||||
- Improve scalability through distributed architectures.
|
||||
|
||||
*Further diagrams and detailed breakdowns will be added in future updates.*
|
||||
*Architecture is subject to change as the project evolves.*
|
||||
28
docs/assets/stylesheets/extra.css
Normal file
28
docs/assets/stylesheets/extra.css
Normal file
@@ -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;
|
||||
}
|
||||
16
docs/config/claude_desktop_config.json
Normal file
16
docs/config/claude_desktop_config.json
Normal file
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "bun",
|
||||
"args": [
|
||||
"run",
|
||||
"start",
|
||||
"--port",
|
||||
"8080"
|
||||
],
|
||||
"env": {
|
||||
"NODE_ENV": "production"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
18
docs/config/cline_config.json
Normal file
18
docs/config/cline_config.json
Normal file
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "bun",
|
||||
"args": [
|
||||
"run",
|
||||
"start",
|
||||
"--enable-cline",
|
||||
"--config",
|
||||
"${configDir}/.env"
|
||||
],
|
||||
"env": {
|
||||
"NODE_ENV": "production",
|
||||
"CLINE_MODE": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
30
docs/config/index.md
Normal file
30
docs/config/index.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Configuration
|
||||
|
||||
This section covers the configuration options available in the Home Assistant MCP Server.
|
||||
|
||||
## Overview
|
||||
|
||||
The MCP Server can be configured through various configuration files and environment variables. This section will guide you through the available options and their usage.
|
||||
|
||||
## Configuration Files
|
||||
|
||||
The main configuration files are:
|
||||
|
||||
1. `.env` - Environment variables
|
||||
2. `config.yaml` - Main configuration file
|
||||
3. `devices.yaml` - Device-specific configurations
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key environment variables that can be set:
|
||||
|
||||
- `MCP_HOST` - Host address (default: 0.0.0.0)
|
||||
- `MCP_PORT` - Port number (default: 8123)
|
||||
- `MCP_LOG_LEVEL` - Logging level (default: INFO)
|
||||
- `MCP_CONFIG_DIR` - Configuration directory path
|
||||
|
||||
## Next Steps
|
||||
|
||||
- See [System Configuration](../configuration.md) for detailed configuration options
|
||||
- Check [Environment Setup](../getting-started/configuration.md) for initial setup
|
||||
- Review [Security](../security.md) for security-related configurations
|
||||
270
docs/configuration.md
Normal file
270
docs/configuration.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# System Configuration
|
||||
|
||||
This document provides detailed information about configuring the Home Assistant MCP Server.
|
||||
|
||||
## Configuration File Structure
|
||||
|
||||
The MCP Server uses environment variables for configuration, with support for different environments (development, test, production):
|
||||
|
||||
```bash
|
||||
# .env, .env.development, or .env.test
|
||||
PORT=4000
|
||||
NODE_ENV=development
|
||||
HASS_HOST=http://192.168.178.63:8123
|
||||
HASS_TOKEN=your_token_here
|
||||
JWT_SECRET=your_secret_key
|
||||
```
|
||||
|
||||
## Server Settings
|
||||
|
||||
### Basic Server Configuration
|
||||
- `PORT`: Server port number (default: 4000)
|
||||
- `NODE_ENV`: Environment mode (development, production, test)
|
||||
- `HASS_HOST`: Home Assistant instance URL
|
||||
- `HASS_TOKEN`: Home Assistant long-lived access token
|
||||
|
||||
### Security Settings
|
||||
- `JWT_SECRET`: Secret key for JWT token generation
|
||||
- `RATE_LIMIT`: Rate limiting configuration
|
||||
- `windowMs`: Time window in milliseconds (default: 15 minutes)
|
||||
- `max`: Maximum requests per window (default: 100)
|
||||
|
||||
### WebSocket Settings
|
||||
- `SSE`: Server-Sent Events configuration
|
||||
- `MAX_CLIENTS`: Maximum concurrent clients (default: 1000)
|
||||
- `PING_INTERVAL`: Keep-alive ping interval in ms (default: 30000)
|
||||
|
||||
### Speech Features (Optional)
|
||||
- `ENABLE_SPEECH_FEATURES`: Enable speech processing features (default: false)
|
||||
- `ENABLE_WAKE_WORD`: Enable wake word detection (default: false)
|
||||
- `ENABLE_SPEECH_TO_TEXT`: Enable speech-to-text conversion (default: false)
|
||||
- `WHISPER_MODEL_PATH`: Path to Whisper models directory (default: /models)
|
||||
- `WHISPER_MODEL_TYPE`: Whisper model type (default: base)
|
||||
- Available models: tiny.en, base.en, small.en, medium.en, large-v2
|
||||
|
||||
## Environment Variables
|
||||
|
||||
All configuration is managed through environment variables:
|
||||
|
||||
```bash
|
||||
# Server
|
||||
PORT=4000
|
||||
NODE_ENV=development
|
||||
|
||||
# Home Assistant
|
||||
HASS_HOST=http://your-hass-instance:8123
|
||||
HASS_TOKEN=your_token_here
|
||||
|
||||
# Security
|
||||
JWT_SECRET=your-secret-key
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=info
|
||||
LOG_DIR=logs
|
||||
LOG_MAX_SIZE=20m
|
||||
LOG_MAX_DAYS=14d
|
||||
LOG_COMPRESS=true
|
||||
LOG_REQUESTS=true
|
||||
|
||||
# Speech Features (Optional)
|
||||
ENABLE_SPEECH_FEATURES=false
|
||||
ENABLE_WAKE_WORD=false
|
||||
ENABLE_SPEECH_TO_TEXT=false
|
||||
WHISPER_MODEL_PATH=/models
|
||||
WHISPER_MODEL_TYPE=base
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Security Rate Limiting
|
||||
Rate limiting is enabled by default to protect against brute force attacks:
|
||||
|
||||
```typescript
|
||||
RATE_LIMIT: {
|
||||
windowMs: 15 * 60 * 1000, // 15 minutes
|
||||
max: 100 // limit each IP to 100 requests per window
|
||||
}
|
||||
```
|
||||
|
||||
### Logging
|
||||
The server uses Bun's built-in logging capabilities with additional configuration:
|
||||
|
||||
```typescript
|
||||
LOGGING: {
|
||||
LEVEL: "info", // debug, info, warn, error
|
||||
DIR: "logs",
|
||||
MAX_SIZE: "20m",
|
||||
MAX_DAYS: "14d",
|
||||
COMPRESS: true,
|
||||
TIMESTAMP_FORMAT: "YYYY-MM-DD HH:mm:ss:ms",
|
||||
LOG_REQUESTS: true
|
||||
}
|
||||
```
|
||||
|
||||
### Speech-to-Text Configuration
|
||||
When speech features are enabled, you can configure the following options:
|
||||
|
||||
```typescript
|
||||
SPEECH: {
|
||||
ENABLED: false, // Master switch for all speech features
|
||||
WAKE_WORD_ENABLED: false, // Enable wake word detection
|
||||
SPEECH_TO_TEXT_ENABLED: false, // Enable speech-to-text
|
||||
WHISPER_MODEL_PATH: "/models", // Path to Whisper models
|
||||
WHISPER_MODEL_TYPE: "base", // Model type to use
|
||||
}
|
||||
```
|
||||
|
||||
Available Whisper models:
|
||||
- `tiny.en`: Fastest, lowest accuracy
|
||||
- `base.en`: Good balance of speed and accuracy
|
||||
- `small.en`: Better accuracy, slower
|
||||
- `medium.en`: High accuracy, much slower
|
||||
- `large-v2`: Best accuracy, very slow
|
||||
|
||||
For production deployments, we recommend using system tools like `logrotate` for log management.
|
||||
|
||||
Example logrotate configuration (`/etc/logrotate.d/mcp-server`):
|
||||
```
|
||||
/var/log/mcp-server.log {
|
||||
daily
|
||||
rotate 7
|
||||
compress
|
||||
delaycompress
|
||||
missingok
|
||||
notifempty
|
||||
create 644 mcp mcp
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Always use environment variables for sensitive information
|
||||
2. Keep .env files secure and never commit them to version control
|
||||
3. Use different environment files for development, test, and production
|
||||
4. Enable SSL/TLS in production (preferably via reverse proxy)
|
||||
5. Monitor log files for issues
|
||||
6. Regularly rotate logs in production
|
||||
7. Start with smaller Whisper models and upgrade if needed
|
||||
8. Consider GPU acceleration for larger Whisper models
|
||||
|
||||
## Validation
|
||||
|
||||
The server validates configuration on startup using Zod schemas:
|
||||
- Required fields are checked (e.g., HASS_TOKEN)
|
||||
- Value types are verified
|
||||
- Enums are validated (e.g., LOG_LEVEL, WHISPER_MODEL_TYPE)
|
||||
- Default values are applied when not specified
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common configuration issues:
|
||||
1. Missing required environment variables
|
||||
2. Invalid environment variable values
|
||||
3. Permission issues with log directories
|
||||
4. Rate limiting too restrictive
|
||||
5. Speech model loading failures
|
||||
6. Docker not available for speech features
|
||||
7. Insufficient system resources for larger models
|
||||
|
||||
See the [Troubleshooting Guide](troubleshooting.md) for solutions.
|
||||
|
||||
# Configuration Guide
|
||||
|
||||
This document describes all available configuration options for the Home Assistant MCP Server.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Required Settings
|
||||
|
||||
```bash
|
||||
# Server Configuration
|
||||
PORT=3000 # Server port
|
||||
HOST=localhost # Server host
|
||||
|
||||
# Home Assistant
|
||||
HASS_URL=http://localhost:8123 # Home Assistant URL
|
||||
HASS_TOKEN=your_token # Long-lived access token
|
||||
|
||||
# Security
|
||||
JWT_SECRET=your_secret # JWT signing secret
|
||||
```
|
||||
|
||||
### Optional Settings
|
||||
|
||||
```bash
|
||||
# Rate Limiting
|
||||
RATE_LIMIT_WINDOW=60000 # Time window in ms (default: 60000)
|
||||
RATE_LIMIT_MAX=100 # Max requests per window (default: 100)
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=info # debug, info, warn, error (default: info)
|
||||
LOG_DIR=logs # Log directory (default: logs)
|
||||
LOG_MAX_SIZE=10m # Max log file size (default: 10m)
|
||||
LOG_MAX_FILES=5 # Max number of log files (default: 5)
|
||||
|
||||
# WebSocket/SSE
|
||||
WS_HEARTBEAT=30000 # WebSocket heartbeat interval in ms (default: 30000)
|
||||
SSE_RETRY=3000 # SSE retry interval in ms (default: 3000)
|
||||
|
||||
# Speech Features
|
||||
ENABLE_SPEECH_FEATURES=false # Enable speech processing (default: false)
|
||||
ENABLE_WAKE_WORD=false # Enable wake word detection (default: false)
|
||||
ENABLE_SPEECH_TO_TEXT=false # Enable speech-to-text (default: false)
|
||||
|
||||
# Speech Model Configuration
|
||||
WHISPER_MODEL_PATH=/models # Path to whisper models (default: /models)
|
||||
WHISPER_MODEL_TYPE=base # Model type: tiny|base|small|medium|large-v2 (default: base)
|
||||
WHISPER_LANGUAGE=en # Primary language (default: en)
|
||||
WHISPER_TASK=transcribe # Task type: transcribe|translate (default: transcribe)
|
||||
WHISPER_DEVICE=cuda # Processing device: cpu|cuda (default: cuda if available, else cpu)
|
||||
|
||||
# Wake Word Configuration
|
||||
WAKE_WORDS=hey jarvis,ok google,alexa # Comma-separated wake words (default: hey jarvis)
|
||||
WAKE_WORD_SENSITIVITY=0.5 # Detection sensitivity 0-1 (default: 0.5)
|
||||
```
|
||||
|
||||
## Speech Features
|
||||
|
||||
### Model Selection
|
||||
|
||||
Choose a model based on your needs:
|
||||
|
||||
| Model | Size | Memory Required | Speed | Accuracy |
|
||||
|------------|-------|-----------------|-------|----------|
|
||||
| tiny.en | 75MB | 1GB | Fast | Basic |
|
||||
| base.en | 150MB | 2GB | Good | Good |
|
||||
| small.en | 500MB | 4GB | Med | Better |
|
||||
| medium.en | 1.5GB | 8GB | Slow | High |
|
||||
| large-v2 | 3GB | 16GB | Slow | Best |
|
||||
|
||||
### GPU Acceleration
|
||||
|
||||
When `WHISPER_DEVICE=cuda`:
|
||||
- NVIDIA GPU with CUDA support required
|
||||
- Significantly faster processing
|
||||
- Higher memory requirements
|
||||
|
||||
### Wake Word Detection
|
||||
|
||||
- Multiple wake words supported via comma-separated list
|
||||
- Adjustable sensitivity (0-1):
|
||||
- Lower values: Fewer false positives, may miss some triggers
|
||||
- Higher values: More responsive, may have false triggers
|
||||
- Default (0.5): Balanced detection
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. Model Selection:
|
||||
- Start with `base.en` model
|
||||
- Upgrade if better accuracy needed
|
||||
- Downgrade if performance issues
|
||||
|
||||
2. Resource Management:
|
||||
- Monitor memory usage
|
||||
- Use GPU acceleration when available
|
||||
- Consider model size vs available resources
|
||||
|
||||
3. Wake Word Configuration:
|
||||
- Use distinct wake words
|
||||
- Adjust sensitivity based on environment
|
||||
- Limit number of wake words for better performance
|
||||
@@ -1,36 +1,124 @@
|
||||
# Contributing to Home Assistant MCP
|
||||
---
|
||||
layout: default
|
||||
title: Contributing
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
We welcome community contributions to improve the MCP Server. Please review the following guidelines before contributing.
|
||||
# Contributing Guide 🤝
|
||||
|
||||
## How to Contribute
|
||||
Thank you for your interest in contributing to the MCP Server project!
|
||||
|
||||
1. **Fork the Repository:** Create your personal fork on GitHub.
|
||||
2. **Create a Feature Branch:** Use a clear name (e.g., `feature/your-feature` or `bugfix/short-description`).
|
||||
3. **Make Changes:** Develop your feature or fix bugs while following our coding standards.
|
||||
4. **Write Tests:** Include tests for new features or bug fixes.
|
||||
5. **Submit a Pull Request:** Once your changes are complete, submit a PR for review.
|
||||
6. **Address Feedback:** Revise your PR based on maintainers' suggestions.
|
||||
## Getting Started
|
||||
|
||||
## Code Style Guidelines
|
||||
### Prerequisites
|
||||
|
||||
- Follow the project's established coding style.
|
||||
- Use Bun tooling for linting and formatting:
|
||||
- `bun run lint`
|
||||
- `bun run format`
|
||||
- [Bun](https://bun.sh) >= 1.0.26
|
||||
- Home Assistant instance
|
||||
- Basic understanding of TypeScript
|
||||
|
||||
## Documentation
|
||||
### Development Setup
|
||||
|
||||
- Update documentation alongside your code changes.
|
||||
- Ensure tests pass and coverage remains high.
|
||||
1. Fork the repository
|
||||
2. Clone your fork:
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
3. Install dependencies:
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
4. Configure environment:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your Home Assistant details
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Branch Naming
|
||||
|
||||
- `feature/` - New features
|
||||
- `fix/` - Bug fixes
|
||||
- `docs/` - Documentation updates
|
||||
|
||||
Example:
|
||||
```bash
|
||||
git checkout -b feature/device-control-improvements
|
||||
```
|
||||
|
||||
### Commit Messages
|
||||
|
||||
Follow simple, clear commit messages:
|
||||
|
||||
```
|
||||
type: brief description
|
||||
|
||||
[optional detailed explanation]
|
||||
```
|
||||
|
||||
Types:
|
||||
- `feat:` - New feature
|
||||
- `fix:` - Bug fix
|
||||
- `docs:` - Documentation
|
||||
- `chore:` - Maintenance
|
||||
|
||||
### Code Style
|
||||
|
||||
- Use TypeScript
|
||||
- Follow existing code structure
|
||||
- Keep changes focused and minimal
|
||||
|
||||
## Testing
|
||||
|
||||
Run tests before submitting:
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
bun test
|
||||
|
||||
# Run specific test
|
||||
bun test test/api/control.test.ts
|
||||
```
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. Ensure tests pass
|
||||
2. Update documentation if needed
|
||||
3. Provide clear description of changes
|
||||
|
||||
### PR Template
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief explanation of the changes
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Documentation update
|
||||
|
||||
## Testing
|
||||
Describe how you tested these changes
|
||||
```
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
- Use the GitHub Issues page to report bugs, request new features, or ask questions.
|
||||
- Provide clear descriptions, replication steps, and any error logs.
|
||||
- Use GitHub Issues
|
||||
- Provide clear, reproducible steps
|
||||
- Include environment details
|
||||
|
||||
## Community
|
||||
## Code of Conduct
|
||||
|
||||
- Join our real-time discussions on our chat platforms (Discord, Slack, etc.).
|
||||
- Engage with other contributors to exchange ideas and solutions.
|
||||
- Be respectful
|
||||
- Focus on constructive feedback
|
||||
- Help maintain a positive environment
|
||||
|
||||
Thank you for helping improve the Home Assistant MCP project!
|
||||
## Resources
|
||||
|
||||
- [API Documentation](api.md)
|
||||
- [Troubleshooting Guide](troubleshooting.md)
|
||||
|
||||
*Thank you for contributing!*
|
||||
141
docs/deployment.md
Normal file
141
docs/deployment.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Deployment Guide
|
||||
|
||||
This documentation is automatically deployed to GitHub Pages using GitHub Actions. Here's how it works and how to manage deployments.
|
||||
|
||||
## Automatic Deployment
|
||||
|
||||
The documentation is automatically deployed when changes are pushed to the `main` or `master` branch. The deployment process:
|
||||
|
||||
1. Triggers on push to main/master
|
||||
2. Sets up Python environment
|
||||
3. Installs required dependencies
|
||||
4. Builds the documentation
|
||||
5. Deploys to the `gh-pages` branch
|
||||
|
||||
### GitHub Actions Workflow
|
||||
|
||||
The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`. This is the single source of truth for documentation deployment:
|
||||
|
||||
```yaml
|
||||
name: Deploy MkDocs
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
- master
|
||||
workflow_dispatch: # Allow manual trigger
|
||||
```
|
||||
|
||||
## Manual Deployment
|
||||
|
||||
If needed, you can deploy manually using:
|
||||
|
||||
```bash
|
||||
# Create a virtual environment
|
||||
python -m venv venv
|
||||
|
||||
# Activate the virtual environment
|
||||
source venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r docs/requirements.txt
|
||||
|
||||
# Build the documentation
|
||||
mkdocs build
|
||||
|
||||
# Deploy to GitHub Pages
|
||||
mkdocs gh-deploy --force
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Documentation Updates
|
||||
- Test locally before pushing: `mkdocs serve`
|
||||
- Verify all links work
|
||||
- Ensure images are optimized
|
||||
- Check mobile responsiveness
|
||||
|
||||
### 2. Version Control
|
||||
- Keep documentation in sync with code versions
|
||||
- Use meaningful commit messages
|
||||
- Tag important documentation versions
|
||||
|
||||
### 3. Content Guidelines
|
||||
- Use consistent formatting
|
||||
- Keep navigation structure logical
|
||||
- Include examples where appropriate
|
||||
- Maintain up-to-date screenshots
|
||||
|
||||
### 4. Maintenance
|
||||
- Regularly review and update content
|
||||
- Check for broken links
|
||||
- Update dependencies
|
||||
- Monitor GitHub Actions logs
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Failed Deployments**
|
||||
- Check GitHub Actions logs
|
||||
- Verify dependencies are up to date
|
||||
- Ensure all required files exist
|
||||
|
||||
2. **Broken Links**
|
||||
- Run `mkdocs build --strict`
|
||||
- Use relative paths in markdown
|
||||
- Check case sensitivity
|
||||
|
||||
3. **Style Issues**
|
||||
- Verify theme configuration
|
||||
- Check CSS customizations
|
||||
- Test on multiple browsers
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### requirements.txt
|
||||
|
||||
Create a requirements file for documentation dependencies:
|
||||
|
||||
```txt
|
||||
mkdocs-material
|
||||
mkdocs-minify-plugin
|
||||
mkdocs-git-revision-date-plugin
|
||||
mkdocs-mkdocstrings
|
||||
mkdocs-social-plugin
|
||||
mkdocs-redirects
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
- Check [GitHub Pages settings](https://github.com/jango-blockchained/advanced-homeassistant-mcp/settings/pages)
|
||||
- Monitor build status in Actions tab
|
||||
- Verify site accessibility
|
||||
|
||||
## Workflow Features
|
||||
|
||||
### Caching
|
||||
The workflow implements caching for Python dependencies to speed up deployments:
|
||||
- Pip cache for Python packages
|
||||
- MkDocs dependencies cache
|
||||
|
||||
### Deployment Checks
|
||||
Several checks are performed during deployment:
|
||||
1. Link validation with `mkdocs build --strict`
|
||||
2. Build verification
|
||||
3. Post-deployment site accessibility check
|
||||
|
||||
### Manual Triggers
|
||||
You can manually trigger deployments using the "workflow_dispatch" event in GitHub Actions.
|
||||
|
||||
## Cleanup
|
||||
|
||||
To clean up duplicate workflow files, run:
|
||||
|
||||
```bash
|
||||
# Make the script executable
|
||||
chmod +x scripts/cleanup-workflows.sh
|
||||
|
||||
# Run the cleanup script
|
||||
./scripts/cleanup-workflows.sh
|
||||
```
|
||||
310
docs/development/best-practices.md
Normal file
310
docs/development/best-practices.md
Normal file
@@ -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)
|
||||
@@ -1,190 +0,0 @@
|
||||
# Development Guide
|
||||
|
||||
This guide provides information for developers who want to contribute to or extend the Home Assistant MCP.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
homeassistant-mcp/
|
||||
├── src/
|
||||
│ ├── __tests__/ # Test files
|
||||
│ ├── __mocks__/ # Mock files
|
||||
│ ├── api/ # API endpoints and route handlers
|
||||
│ ├── config/ # Configuration management
|
||||
│ ├── hass/ # Home Assistant integration
|
||||
│ ├── interfaces/ # TypeScript interfaces
|
||||
│ ├── mcp/ # MCP core functionality
|
||||
│ ├── middleware/ # Express middleware
|
||||
│ ├── routes/ # Route definitions
|
||||
│ ├── security/ # Security utilities
|
||||
│ ├── sse/ # Server-Sent Events handling
|
||||
│ ├── tools/ # Tool implementations
|
||||
│ ├── types/ # TypeScript type definitions
|
||||
│ └── utils/ # Utility functions
|
||||
├── __tests__/ # Test files
|
||||
├── docs/ # Documentation
|
||||
├── dist/ # Compiled JavaScript
|
||||
└── scripts/ # Build and utility scripts
|
||||
```
|
||||
|
||||
## Development Setup
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. Set up development environment:
|
||||
```bash
|
||||
cp .env.example .env.development
|
||||
```
|
||||
|
||||
3. Start development server:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
We follow these coding standards:
|
||||
|
||||
1. TypeScript best practices
|
||||
- Use strict type checking
|
||||
- Avoid `any` types
|
||||
- Document complex types
|
||||
|
||||
2. ESLint rules
|
||||
- Run `npm run lint` to check
|
||||
- Run `npm run lint:fix` to auto-fix
|
||||
|
||||
3. Code formatting
|
||||
- Use Prettier
|
||||
- Run `npm run format` to format code
|
||||
|
||||
## Testing
|
||||
|
||||
1. Unit tests:
|
||||
```bash
|
||||
npm run test
|
||||
```
|
||||
|
||||
2. Integration tests:
|
||||
```bash
|
||||
npm run test:integration
|
||||
```
|
||||
|
||||
3. Coverage report:
|
||||
```bash
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
## Creating New Tools
|
||||
|
||||
1. Create a new file in `src/tools/`:
|
||||
```typescript
|
||||
import { z } from 'zod';
|
||||
import { Tool } from '../types';
|
||||
|
||||
export const myTool: Tool = {
|
||||
name: 'my_tool',
|
||||
description: 'Description of my tool',
|
||||
parameters: z.object({
|
||||
// Define parameters
|
||||
}),
|
||||
execute: async (params) => {
|
||||
// Implement tool logic
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
2. Add to `src/tools/index.ts`
|
||||
3. Create tests in `__tests__/tools/`
|
||||
4. Add documentation in `docs/tools/`
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Write/update tests
|
||||
5. Update documentation
|
||||
6. Submit a pull request
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
1. Ensure all tests pass
|
||||
2. Update documentation
|
||||
3. Update CHANGELOG.md
|
||||
4. Get review from maintainers
|
||||
|
||||
## Building
|
||||
|
||||
1. Development build:
|
||||
```bash
|
||||
npm run build:dev
|
||||
```
|
||||
|
||||
2. Production build:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
1. Update documentation for changes
|
||||
2. Follow documentation structure
|
||||
3. Include examples
|
||||
4. Update type definitions
|
||||
|
||||
## Debugging
|
||||
|
||||
1. Development debugging:
|
||||
```bash
|
||||
npm run dev:debug
|
||||
```
|
||||
|
||||
2. Test debugging:
|
||||
```bash
|
||||
npm run test:debug
|
||||
```
|
||||
|
||||
3. VSCode launch configurations provided
|
||||
|
||||
## Performance
|
||||
|
||||
1. Follow performance best practices
|
||||
2. Use caching where appropriate
|
||||
3. Implement rate limiting
|
||||
4. Monitor memory usage
|
||||
|
||||
## Security
|
||||
|
||||
1. Follow security best practices
|
||||
2. Validate all inputs
|
||||
3. Use proper authentication
|
||||
4. Handle errors securely
|
||||
|
||||
## Deployment
|
||||
|
||||
1. Build for production:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
2. Start production server:
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
3. Docker deployment:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
Need development help?
|
||||
1. Check documentation
|
||||
2. Search issues
|
||||
3. Create new issue
|
||||
4. Join discussions
|
||||
197
docs/development/environment.md
Normal file
197
docs/development/environment.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Development Environment Setup
|
||||
|
||||
This guide will help you set up your development environment for the Home Assistant MCP Server.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Software
|
||||
- Python 3.10 or higher
|
||||
- pip (Python package manager)
|
||||
- git
|
||||
- Docker (optional, for containerized development)
|
||||
- Node.js 18+ (for frontend development)
|
||||
|
||||
### System Requirements
|
||||
- 4GB RAM minimum
|
||||
- 2 CPU cores minimum
|
||||
- 10GB free disk space
|
||||
|
||||
## Initial Setup
|
||||
|
||||
1. Clone the Repository
|
||||
```bash
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
2. Create Virtual Environment
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Linux/macOS
|
||||
# or
|
||||
.venv\Scripts\activate # Windows
|
||||
```
|
||||
|
||||
3. Install Dependencies
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
pip install -r docs/requirements.txt # for documentation
|
||||
```
|
||||
|
||||
## Development Tools
|
||||
|
||||
### Code Editor Setup
|
||||
We recommend using Visual Studio Code with these extensions:
|
||||
- Python
|
||||
- Docker
|
||||
- YAML
|
||||
- ESLint
|
||||
- Prettier
|
||||
|
||||
### VS Code Settings
|
||||
```json
|
||||
{
|
||||
"python.linting.enabled": true,
|
||||
"python.linting.pylintEnabled": true,
|
||||
"python.formatting.provider": "black",
|
||||
"editor.formatOnSave": true
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
1. Create Local Config
|
||||
```bash
|
||||
cp config.example.yaml config.yaml
|
||||
```
|
||||
|
||||
2. Set Environment Variables
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Unit Tests
|
||||
```bash
|
||||
pytest tests/unit
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
```bash
|
||||
pytest tests/integration
|
||||
```
|
||||
|
||||
### Coverage Report
|
||||
```bash
|
||||
pytest --cov=src tests/
|
||||
```
|
||||
|
||||
## Docker Development
|
||||
|
||||
### Build Container
|
||||
```bash
|
||||
docker build -t mcp-server-dev -f Dockerfile.dev .
|
||||
```
|
||||
|
||||
### Run Development Container
|
||||
```bash
|
||||
docker run -it --rm \
|
||||
-v $(pwd):/app \
|
||||
-p 8123:8123 \
|
||||
mcp-server-dev
|
||||
```
|
||||
|
||||
## Database Setup
|
||||
|
||||
### Local Development Database
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 5432:5432 \
|
||||
-e POSTGRES_USER=mcp \
|
||||
-e POSTGRES_PASSWORD=development \
|
||||
-e POSTGRES_DB=mcp_dev \
|
||||
postgres:14
|
||||
```
|
||||
|
||||
### Run Migrations
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
## Frontend Development
|
||||
|
||||
1. Install Node.js Dependencies
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
2. Start Development Server
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
### Build Documentation
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
### View Documentation
|
||||
Open http://localhost:8000 in your browser
|
||||
|
||||
## Debugging
|
||||
|
||||
### VS Code Launch Configuration
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Python: MCP Server",
|
||||
"type": "python",
|
||||
"request": "launch",
|
||||
"program": "src/main.py",
|
||||
"console": "integratedTerminal"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
|
||||
### Install Pre-commit
|
||||
```bash
|
||||
pip install pre-commit
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
### Available Hooks
|
||||
- black (code formatting)
|
||||
- flake8 (linting)
|
||||
- isort (import sorting)
|
||||
- mypy (type checking)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common Issues:
|
||||
1. Port already in use
|
||||
- Check for running processes: `lsof -i :8123`
|
||||
- Kill process if needed: `kill -9 PID`
|
||||
|
||||
2. Database connection issues
|
||||
- Verify PostgreSQL is running
|
||||
- Check connection settings in .env
|
||||
|
||||
3. Virtual environment problems
|
||||
- Delete and recreate: `rm -rf .venv && python -m venv .venv`
|
||||
- Reinstall dependencies
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Review the [Architecture Guide](../architecture.md)
|
||||
2. Check [Contributing Guidelines](../contributing.md)
|
||||
3. Start with [Simple Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
||||
54
docs/development/index.md
Normal file
54
docs/development/index.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Development Guide
|
||||
|
||||
Welcome to the development guide for the Home Assistant MCP Server. This section provides comprehensive information for developers who want to contribute to or extend the project.
|
||||
|
||||
## Development Overview
|
||||
|
||||
The MCP Server is built with modern development practices in mind, focusing on:
|
||||
|
||||
- Clean, maintainable code
|
||||
- Comprehensive testing
|
||||
- Clear documentation
|
||||
- Modular architecture
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Set up your development environment
|
||||
2. Fork the repository
|
||||
3. Install dependencies
|
||||
4. Run tests
|
||||
5. Make your changes
|
||||
6. Submit a pull request
|
||||
|
||||
## Development Topics
|
||||
|
||||
- [Architecture](../architecture.md) - System architecture and design
|
||||
- [Contributing](../contributing.md) - Contribution guidelines
|
||||
- [Testing](../testing.md) - Testing framework and guidelines
|
||||
- [Troubleshooting](../troubleshooting.md) - Common issues and solutions
|
||||
- [Deployment](../deployment.md) - Deployment procedures
|
||||
- [Roadmap](../roadmap.md) - Future development plans
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Follow the coding style guide
|
||||
- Write comprehensive tests
|
||||
- Document your changes
|
||||
- Keep commits atomic
|
||||
- Use meaningful commit messages
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. Create a feature branch
|
||||
2. Make your changes
|
||||
3. Run tests
|
||||
4. Update documentation
|
||||
5. Submit a pull request
|
||||
6. Address review comments
|
||||
7. Merge when approved
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Review the [Architecture](../architecture.md)
|
||||
- Check [Contributing Guidelines](../contributing.md)
|
||||
- Set up your [Development Environment](environment.md)
|
||||
296
docs/development/interfaces.md
Normal file
296
docs/development/interfaces.md
Normal file
@@ -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)
|
||||
323
docs/development/test-migration-guide.md
Normal file
323
docs/development/test-migration-guide.md
Normal file
@@ -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)
|
||||
};
|
||||
```
|
||||
226
docs/development/tools.md
Normal file
226
docs/development/tools.md
Normal file
@@ -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)
|
||||
22
docs/examples/index.md
Normal file
22
docs/examples/index.md
Normal file
@@ -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
|
||||
...
|
||||
212
docs/features/speech.md
Normal file
212
docs/features/speech.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# Speech Features
|
||||
|
||||
The Home Assistant MCP Server includes powerful speech processing capabilities powered by fast-whisper and custom wake word detection. This guide explains how to set up and use these features effectively.
|
||||
|
||||
## Overview
|
||||
|
||||
The speech processing system consists of two main components:
|
||||
1. Wake Word Detection - Listens for specific trigger phrases
|
||||
2. Speech-to-Text - Transcribes spoken commands using fast-whisper
|
||||
|
||||
## Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Docker environment:
|
||||
```bash
|
||||
docker --version # Should be 20.10.0 or higher
|
||||
```
|
||||
|
||||
2. For GPU acceleration:
|
||||
- NVIDIA GPU with CUDA support
|
||||
- NVIDIA Container Toolkit installed
|
||||
- NVIDIA drivers 450.80.02 or higher
|
||||
|
||||
### Installation
|
||||
|
||||
1. Enable speech features in your `.env`:
|
||||
```bash
|
||||
ENABLE_SPEECH_FEATURES=true
|
||||
ENABLE_WAKE_WORD=true
|
||||
ENABLE_SPEECH_TO_TEXT=true
|
||||
```
|
||||
|
||||
2. Configure model settings:
|
||||
```bash
|
||||
WHISPER_MODEL_PATH=/models
|
||||
WHISPER_MODEL_TYPE=base
|
||||
WHISPER_LANGUAGE=en
|
||||
WHISPER_TASK=transcribe
|
||||
WHISPER_DEVICE=cuda # or cpu
|
||||
```
|
||||
|
||||
3. Start the services:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Wake Word Detection
|
||||
|
||||
The wake word detector continuously listens for configured trigger phrases. Default wake words:
|
||||
- "hey jarvis"
|
||||
- "ok google"
|
||||
- "alexa"
|
||||
|
||||
Custom wake words can be configured:
|
||||
```bash
|
||||
WAKE_WORDS=computer,jarvis,assistant
|
||||
```
|
||||
|
||||
When a wake word is detected:
|
||||
1. The system starts recording audio
|
||||
2. Audio is processed through the speech-to-text pipeline
|
||||
3. The resulting command is processed by the server
|
||||
|
||||
### Speech-to-Text
|
||||
|
||||
#### Automatic Transcription
|
||||
|
||||
After wake word detection:
|
||||
1. Audio is automatically captured (default: 5 seconds)
|
||||
2. The audio is transcribed using the configured whisper model
|
||||
3. The transcribed text is processed as a command
|
||||
|
||||
#### Manual Transcription
|
||||
|
||||
You can also manually transcribe audio using the API:
|
||||
|
||||
```typescript
|
||||
// Using the TypeScript client
|
||||
import { SpeechService } from '@ha-mcp/client';
|
||||
|
||||
const speech = new SpeechService();
|
||||
|
||||
// Transcribe from audio buffer
|
||||
const buffer = await getAudioBuffer();
|
||||
const text = await speech.transcribe(buffer);
|
||||
|
||||
// Transcribe from file
|
||||
const text = await speech.transcribeFile('command.wav');
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Using the REST API
|
||||
POST /api/speech/transcribe
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
file: <audio file>
|
||||
```
|
||||
|
||||
### Event Handling
|
||||
|
||||
The system emits various events during speech processing:
|
||||
|
||||
```typescript
|
||||
speech.on('wakeWord', (word: string) => {
|
||||
console.log(`Wake word detected: ${word}`);
|
||||
});
|
||||
|
||||
speech.on('listening', () => {
|
||||
console.log('Listening for command...');
|
||||
});
|
||||
|
||||
speech.on('transcribing', () => {
|
||||
console.log('Processing speech...');
|
||||
});
|
||||
|
||||
speech.on('transcribed', (text: string) => {
|
||||
console.log(`Transcribed text: ${text}`);
|
||||
});
|
||||
|
||||
speech.on('error', (error: Error) => {
|
||||
console.error('Speech processing error:', error);
|
||||
});
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Model Selection
|
||||
|
||||
Choose an appropriate model based on your needs:
|
||||
|
||||
1. Resource-constrained environments:
|
||||
- Use `tiny.en` or `base.en`
|
||||
- Run on CPU if GPU unavailable
|
||||
- Limit concurrent processing
|
||||
|
||||
2. High-accuracy requirements:
|
||||
- Use `small.en` or `medium.en`
|
||||
- Enable GPU acceleration
|
||||
- Increase audio quality
|
||||
|
||||
3. Production environments:
|
||||
- Use `base.en` or `small.en`
|
||||
- Enable GPU acceleration
|
||||
- Configure appropriate timeouts
|
||||
|
||||
### GPU Acceleration
|
||||
|
||||
When using GPU acceleration:
|
||||
|
||||
1. Monitor GPU memory usage:
|
||||
```bash
|
||||
nvidia-smi -l 1
|
||||
```
|
||||
|
||||
2. Adjust model size if needed:
|
||||
```bash
|
||||
WHISPER_MODEL_TYPE=small # Decrease if GPU memory limited
|
||||
```
|
||||
|
||||
3. Configure processing device:
|
||||
```bash
|
||||
WHISPER_DEVICE=cuda # Use GPU
|
||||
WHISPER_DEVICE=cpu # Use CPU if GPU unavailable
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. Wake word detection not working:
|
||||
- Check microphone permissions
|
||||
- Adjust `WAKE_WORD_SENSITIVITY`
|
||||
- Verify wake words configuration
|
||||
|
||||
2. Poor transcription quality:
|
||||
- Check audio input quality
|
||||
- Try a larger model
|
||||
- Verify language settings
|
||||
|
||||
3. Performance issues:
|
||||
- Monitor resource usage
|
||||
- Consider smaller model
|
||||
- Check GPU acceleration status
|
||||
|
||||
### Logging
|
||||
|
||||
Enable debug logging for detailed information:
|
||||
```bash
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
Speech-specific logs will be tagged with `[SPEECH]` prefix.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. Audio Privacy:
|
||||
- Audio is processed locally
|
||||
- No data sent to external services
|
||||
- Temporary files automatically cleaned
|
||||
|
||||
2. Access Control:
|
||||
- Speech endpoints require authentication
|
||||
- Rate limiting applies to transcription
|
||||
- Configurable command restrictions
|
||||
|
||||
3. Resource Protection:
|
||||
- Timeouts prevent hanging
|
||||
- Memory limits enforced
|
||||
- Graceful error handling
|
||||
@@ -1,30 +0,0 @@
|
||||
# Getting Started
|
||||
|
||||
Begin your journey with the Home Assistant MCP Server by following these steps:
|
||||
|
||||
- **API Documentation:** Read the [API Documentation](api.md) for available endpoints.
|
||||
- **Real-Time Updates:** Learn about [Server-Sent Events](sse-api.md) for live communication.
|
||||
- **Tools:** Explore available [Tools](tools/tools.md) for device control and automation.
|
||||
- **Configuration:** Refer to the [Configuration Guide](configuration.md) for setup and advanced settings.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you encounter any issues:
|
||||
1. Verify that your Home Assistant instance is accessible.
|
||||
2. Ensure that all required environment variables are properly set.
|
||||
3. Consult the [Troubleshooting Guide](troubleshooting.md) for additional solutions.
|
||||
|
||||
## Development
|
||||
|
||||
For contributors:
|
||||
1. Fork the repository.
|
||||
2. Create a feature branch.
|
||||
3. Follow the [Development Guide](development/development.md) for contribution guidelines.
|
||||
4. Submit a pull request with your enhancements.
|
||||
|
||||
## Support
|
||||
|
||||
Need help?
|
||||
- Visit our [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues).
|
||||
- Review the [Troubleshooting Guide](troubleshooting.md).
|
||||
- Check the [FAQ](troubleshooting.md#faq) for common questions.
|
||||
10
docs/getting-started/docker.md
Normal file
10
docs/getting-started/docker.md
Normal file
@@ -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...
|
||||
8
docs/getting-started/index.md
Normal file
8
docs/getting-started/index.md
Normal file
@@ -0,0 +1,8 @@
|
||||
# Getting Started
|
||||
|
||||
Welcome to the Advanced Home Assistant MCP getting started guide. Follow these steps to begin:
|
||||
|
||||
1. [Installation](installation.md)
|
||||
2. [Configuration](configuration.md)
|
||||
3. [Docker Setup](docker.md)
|
||||
4. [Quick Start](quickstart.md)
|
||||
@@ -1,124 +1,181 @@
|
||||
# Installation Guide
|
||||
---
|
||||
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
|
||||
|
||||
### System Requirements
|
||||
- **Operating System:** Linux, macOS, or Windows (Docker recommended)
|
||||
- **Runtime:** Bun v1.0.26 or higher
|
||||
- **Home Assistant:** v2023.11 or higher
|
||||
- **Minimum Hardware:**
|
||||
- 2 CPU cores
|
||||
- 2GB RAM
|
||||
- 10GB free disk space
|
||||
Before installing MCP Server, ensure you have:
|
||||
|
||||
### Software Dependencies
|
||||
- Bun runtime
|
||||
- Docker (optional, recommended for deployment)
|
||||
- Git
|
||||
- Node.js (for some development tasks)
|
||||
- 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. Basic Setup
|
||||
### 1. 🔧 Smithery Installation (Recommended)
|
||||
|
||||
#### Install Bun
|
||||
```bash
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
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
|
||||
```
|
||||
|
||||
#### Clone Repository
|
||||
#### Installation Steps
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
npx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude
|
||||
```
|
||||
|
||||
#### Install Dependencies
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
### 2. 🐳 Docker Installation
|
||||
|
||||
For a containerized deployment:
|
||||
|
||||
#### Configure Environment
|
||||
1. Copy environment template
|
||||
```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
|
||||
```
|
||||
2. Edit `.env` file with your Home Assistant configuration
|
||||
- Set `HASS_HOST`
|
||||
- Configure authentication tokens
|
||||
- Adjust other settings as needed
|
||||
# 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
|
||||
```bash
|
||||
bun run build
|
||||
bun start
|
||||
# Build and start containers
|
||||
docker compose up -d --build
|
||||
|
||||
# View logs (optional)
|
||||
docker compose logs -f --tail=50
|
||||
```
|
||||
|
||||
### 2. Docker Setup (Recommended)
|
||||
### 3. 💻 Manual Installation
|
||||
|
||||
#### Prerequisites
|
||||
- Docker
|
||||
- Docker Compose
|
||||
For direct installation on your system:
|
||||
|
||||
#### Deployment Steps
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
# 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 file with your settings
|
||||
# Edit .env with your configuration
|
||||
|
||||
# Deploy with Docker Compose
|
||||
docker compose up -d
|
||||
# Start the server
|
||||
bun run dev --watch
|
||||
```
|
||||
|
||||
### 3. Home Assistant Add-on (Coming Soon)
|
||||
We're working on a direct Home Assistant add-on for even easier installation.
|
||||
## 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
|
||||
|
||||
### Check Installation
|
||||
- Web Interface: [http://localhost:3000](http://localhost:3000)
|
||||
- Logs: `docker compose logs` or check `logs/` directory
|
||||
To verify your installation:
|
||||
|
||||
### Troubleshooting
|
||||
- Ensure all environment variables are correctly set
|
||||
- Check network connectivity to Home Assistant
|
||||
- Verify authentication tokens
|
||||
|
||||
## Updating
|
||||
|
||||
### Basic Setup
|
||||
1. Check server status:
|
||||
```bash
|
||||
git pull
|
||||
bun install
|
||||
bun run build
|
||||
bun start
|
||||
curl http://localhost:3000/health
|
||||
```
|
||||
|
||||
### Docker
|
||||
2. Test Home Assistant connection:
|
||||
```bash
|
||||
git pull
|
||||
docker compose up -d --build
|
||||
curl http://localhost:3000/api/state
|
||||
```
|
||||
|
||||
## Uninstallation
|
||||
## Troubleshooting
|
||||
|
||||
### Basic Setup
|
||||
```bash
|
||||
cd homeassistant-mcp
|
||||
bun stop # Stop the application
|
||||
rm -rf node_modules dist
|
||||
```
|
||||
If you encounter issues:
|
||||
|
||||
### Docker
|
||||
1. Check the [Troubleshooting Guide](../troubleshooting.md)
|
||||
2. Verify your environment variables
|
||||
3. Check server logs:
|
||||
```bash
|
||||
docker compose down
|
||||
docker rmi homeassistant-mcp # Remove image
|
||||
# For Docker installation
|
||||
docker compose logs -f
|
||||
|
||||
# For manual installation
|
||||
bun run dev
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
- [Configuration Guide](configuration.md)
|
||||
- [Usage Instructions](../usage.md)
|
||||
- [Troubleshooting](../troubleshooting.md)
|
||||
|
||||
- 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).
|
||||
219
docs/getting-started/quickstart.md
Normal file
219
docs/getting-started/quickstart.md
Normal file
@@ -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).
|
||||
133
docs/index.md
133
docs/index.md
@@ -4,107 +4,54 @@ title: Home
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# 📚 Home Assistant MCP Documentation
|
||||
# Advanced Home Assistant MCP
|
||||
|
||||
Welcome to the documentation for the Home Assistant MCP (Model Context Protocol) Server.
|
||||
Welcome to the Advanced Home Assistant Master Control Program documentation.
|
||||
|
||||
## 📑 Documentation Index
|
||||
|
||||
- [Getting Started Guide](getting-started.md)
|
||||
- [API Documentation](api.md)
|
||||
- [Troubleshooting](troubleshooting.md)
|
||||
- [Contributing Guide](contributing.md)
|
||||
|
||||
For project overview, installation, and general information, please see our [main README](../README.md).
|
||||
|
||||
## 🔗 Quick Links
|
||||
|
||||
- [GitHub Repository](https://github.com/jango-blockchained/homeassistant-mcp)
|
||||
- [Issue Tracker](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 [LICENSE](../LICENSE) for details.
|
||||
|
||||
# Model Context Protocol (MCP) Server
|
||||
|
||||
## Overview
|
||||
|
||||
The Model Context Protocol (MCP) Server is a cutting-edge bridge between Home Assistant and Language Learning Models (LLMs), designed to revolutionize smart home automation and control. This documentation provides comprehensive information about setting up, configuring, and using the Home Assistant MCP.
|
||||
|
||||
## Key Features
|
||||
|
||||
### 🏠 Smart Home Integration
|
||||
- Natural language control of smart devices
|
||||
- Real-time device state monitoring
|
||||
- Advanced automation capabilities
|
||||
|
||||
### 🤖 LLM Powered Interactions
|
||||
- Intuitive voice and text-based commands
|
||||
- Context-aware device management
|
||||
- Intelligent automation suggestions
|
||||
|
||||
### 🔒 Security & Performance
|
||||
- Token-based authentication
|
||||
- High-performance Bun runtime
|
||||
- Secure, real-time communication protocols
|
||||
|
||||
## Documentation
|
||||
|
||||
### Core Documentation
|
||||
1. [Getting Started](getting-started.md)
|
||||
- Installation and basic setup
|
||||
- Configuration
|
||||
- First Steps
|
||||
|
||||
2. [API Reference](api.md)
|
||||
- REST API Endpoints
|
||||
- Authentication
|
||||
- Error Handling
|
||||
|
||||
3. [SSE API](sse-api.md)
|
||||
- Event Subscriptions
|
||||
- Real-time Updates
|
||||
- Connection Management
|
||||
|
||||
### Advanced Topics
|
||||
4. [Architecture](architecture.md)
|
||||
- System Design
|
||||
- Components
|
||||
- Data Flow
|
||||
|
||||
5. [Configuration](getting-started.md#configuration)
|
||||
- Environment Variables
|
||||
- Security Settings
|
||||
- Performance Tuning
|
||||
|
||||
6. [Development Guide](development/development.md)
|
||||
- Project Structure
|
||||
- Contributing Guidelines
|
||||
- Testing
|
||||
|
||||
7. [Troubleshooting](troubleshooting.md)
|
||||
- Common Issues
|
||||
- Debugging
|
||||
- FAQ
|
||||
This documentation provides comprehensive information about setting up, configuring, and using the Advanced Home Assistant MCP system.
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [GitHub Repository](https://github.com/jango-blockchained/homeassistant-mcp)
|
||||
- [Issue Tracker](https://github.com/jango-blockchained/homeassistant-mcp/issues)
|
||||
- [Contributing Guide](contributing.md)
|
||||
- [Roadmap](roadmap.md)
|
||||
- [Getting Started](getting-started/index.md)
|
||||
- [API Reference](api/index.md)
|
||||
- [Configuration Guide](getting-started/configuration.md)
|
||||
- [Docker Setup](getting-started/docker.md)
|
||||
|
||||
## Community and Support
|
||||
## What is MCP Server?
|
||||
|
||||
If you need help or have questions:
|
||||
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.
|
||||
|
||||
1. Check the [Troubleshooting Guide](troubleshooting.md)
|
||||
2. Search existing [Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues)
|
||||
3. Join our [GitHub Discussions](https://github.com/jango-blockchained/homeassistant-mcp/discussions)
|
||||
4. Create a new issue if your problem isn't already reported
|
||||
## Key Features
|
||||
|
||||
### 🎮 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
|
||||
- Basic request validation
|
||||
- Lightweight server design
|
||||
|
||||
## 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) - API reference
|
||||
- [Architecture Overview](architecture.md) - System design
|
||||
- [Contributing Guidelines](contributing.md) - How to contribute
|
||||
- [Troubleshooting Guide](troubleshooting.md) - Common issues
|
||||
|
||||
## Support
|
||||
|
||||
Need help or want to report issues?
|
||||
|
||||
- [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 [LICENSE](https://github.com/jango-blockchained/homeassistant-mcp/blob/main/LICENSE) for details.
|
||||
This project is licensed under the MIT License. See the [LICENSE](https://github.com/jango-blockchained/homeassistant-mcp/blob/main/LICENSE) file for details.
|
||||
62
docs/javascripts/extra.js
Normal file
62
docs/javascripts/extra.js
Normal file
@@ -0,0 +1,62 @@
|
||||
// Dark mode handling
|
||||
document.addEventListener('DOMContentLoaded', function () {
|
||||
// Check for saved dark mode preference
|
||||
const darkMode = localStorage.getItem('darkMode');
|
||||
if (darkMode === 'true') {
|
||||
document.body.classList.add('dark-mode');
|
||||
}
|
||||
});
|
||||
|
||||
// Smooth scrolling for anchor links
|
||||
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
|
||||
anchor.addEventListener('click', function (e) {
|
||||
e.preventDefault();
|
||||
document.querySelector(this.getAttribute('href')).scrollIntoView({
|
||||
behavior: 'smooth'
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// Add copy button to code blocks
|
||||
document.querySelectorAll('pre code').forEach((block) => {
|
||||
const button = document.createElement('button');
|
||||
button.className = 'copy-button';
|
||||
button.textContent = 'Copy';
|
||||
|
||||
button.addEventListener('click', async () => {
|
||||
await navigator.clipboard.writeText(block.textContent);
|
||||
button.textContent = 'Copied!';
|
||||
setTimeout(() => {
|
||||
button.textContent = 'Copy';
|
||||
}, 2000);
|
||||
});
|
||||
|
||||
const pre = block.parentNode;
|
||||
pre.insertBefore(button, block);
|
||||
});
|
||||
|
||||
// Add version selector handling
|
||||
const versionSelector = document.querySelector('.version-selector');
|
||||
if (versionSelector) {
|
||||
versionSelector.addEventListener('change', (e) => {
|
||||
const version = e.target.value;
|
||||
window.location.href = `/${version}/`;
|
||||
});
|
||||
}
|
||||
|
||||
// Add feedback handling
|
||||
document.querySelectorAll('.feedback-button').forEach(button => {
|
||||
button.addEventListener('click', function () {
|
||||
const feedback = this.getAttribute('data-feedback');
|
||||
// Send feedback to analytics
|
||||
if (typeof gtag !== 'undefined') {
|
||||
gtag('event', 'feedback', {
|
||||
'event_category': 'Documentation',
|
||||
'event_label': feedback
|
||||
});
|
||||
}
|
||||
// Show thank you message
|
||||
this.textContent = 'Thank you!';
|
||||
this.disabled = true;
|
||||
});
|
||||
});
|
||||
12
docs/javascripts/mathjax.js
Normal file
12
docs/javascripts/mathjax.js
Normal file
@@ -0,0 +1,12 @@
|
||||
window.MathJax = {
|
||||
tex: {
|
||||
inlineMath: [["\\(", "\\)"]],
|
||||
displayMath: [["\\[", "\\]"]],
|
||||
processEscapes: true,
|
||||
processEnvironments: true
|
||||
},
|
||||
options: {
|
||||
ignoreHtmlClass: ".*|",
|
||||
processHtmlClass: "arithmatex"
|
||||
}
|
||||
};
|
||||
42
docs/requirements.txt
Normal file
42
docs/requirements.txt
Normal file
@@ -0,0 +1,42 @@
|
||||
# Core
|
||||
mkdocs>=1.5.3
|
||||
mkdocs-material>=9.5.3
|
||||
|
||||
# Enhanced Functionality
|
||||
mkdocs-minify-plugin>=0.7.1
|
||||
mkdocs-git-revision-date-localized-plugin>=1.2.1
|
||||
mkdocs-glightbox>=0.3.4
|
||||
mkdocs-git-authors-plugin>=0.7.2
|
||||
mkdocs-git-committers-plugin>=0.2.3
|
||||
mkdocs-static-i18n>=1.2.0
|
||||
mkdocs-awesome-pages-plugin>=2.9.2
|
||||
mkdocs-redirects>=1.2.1
|
||||
mkdocs-include-markdown-plugin>=6.0.4
|
||||
mkdocs-macros-plugin>=1.0.4
|
||||
mkdocs-meta-descriptions-plugin>=3.0.0
|
||||
mkdocs-print-site-plugin>=2.3.6
|
||||
|
||||
# Code Documentation
|
||||
mkdocstrings>=0.24.0
|
||||
mkdocstrings-python>=1.7.5
|
||||
|
||||
# Markdown Extensions
|
||||
pymdown-extensions>=10.5
|
||||
markdown>=3.5.1
|
||||
mdx_truly_sane_lists>=1.3
|
||||
pygments>=2.17.2
|
||||
|
||||
# Math Support
|
||||
python-markdown-math>=0.8
|
||||
|
||||
# Diagrams
|
||||
plantuml-markdown>=3.9.2
|
||||
mkdocs-mermaid2-plugin>=1.1.1
|
||||
|
||||
# Search Enhancements
|
||||
mkdocs-material[imaging]>=9.5.3
|
||||
pillow>=10.2.0
|
||||
cairosvg>=2.7.1
|
||||
|
||||
# Development Tools
|
||||
mike>=2.0.0 # For version management
|
||||
@@ -1,51 +1,52 @@
|
||||
# Roadmap for MCP Server
|
||||
|
||||
The following roadmap outlines our planned enhancements and future directions for the Home Assistant MCP Server. This document is a living guide that will be updated as new features are planned and developed.
|
||||
The following roadmap outlines our planned enhancements and future directions for the Home Assistant MCP Server. This document is a living guide that will be updated as new features are developed.
|
||||
|
||||
## Near-Term Goals
|
||||
|
||||
- **Advanced Automation Capabilities:**
|
||||
- Integrate sophisticated automation rules with conditional logic and multi-step execution.
|
||||
- Introduce a visual automation builder for simplified rule creation.
|
||||
- **Core Functionality Improvements:**
|
||||
- Enhance REST API capabilities
|
||||
- Improve WebSocket and SSE reliability
|
||||
- Develop more robust error handling
|
||||
|
||||
- **Enhanced Security Features:**
|
||||
- Implement multi-factor authentication for critical actions.
|
||||
- Strengthen encryption methods and data handling practices.
|
||||
- Expand monitoring and alerting for potential security breaches.
|
||||
- **Security Enhancements:**
|
||||
- Strengthen JWT authentication
|
||||
- Improve input validation
|
||||
- Add basic logging for security events
|
||||
|
||||
- **Performance Optimizations:**
|
||||
- Refine resource utilization to reduce latency.
|
||||
- Optimize real-time data streaming via SSE.
|
||||
- Introduce advanced caching mechanisms for frequently requested data.
|
||||
- Optimize server response times
|
||||
- Improve resource utilization
|
||||
- Implement basic caching mechanisms
|
||||
|
||||
## Mid-Term Goals
|
||||
|
||||
- **User Interface Improvements:**
|
||||
- Develop an intuitive web-based dashboard for device management and monitoring.
|
||||
- Provide real-time analytics and performance metrics.
|
||||
- **Device Integration:**
|
||||
- Expand support for additional Home Assistant device types
|
||||
- Improve device state synchronization
|
||||
- Develop more flexible automation rule support
|
||||
|
||||
- **Expanded Integrations:**
|
||||
- Support a broader range of smart home devices and brands.
|
||||
- Integrate with additional home automation platforms and third-party services.
|
||||
|
||||
- **Developer Experience Enhancements:**
|
||||
- Improve documentation and developer tooling.
|
||||
- Streamline contribution guidelines and testing setups.
|
||||
- **Developer Experience:**
|
||||
- Improve documentation
|
||||
- Create more comprehensive examples
|
||||
- Develop basic CLI tools for configuration
|
||||
|
||||
## Long-Term Vision
|
||||
|
||||
- **Ecosystem Expansion:**
|
||||
- Build a modular plugin system for community-driven extensions and integrations.
|
||||
- Enable seamless integration with future technologies in smart home and AI domains.
|
||||
- **Extensibility:**
|
||||
- Design a simple plugin system
|
||||
- Create guidelines for community contributions
|
||||
- Establish a clear extension mechanism
|
||||
|
||||
- **Scalability and Resilience:**
|
||||
- Architect the system to support large-scale deployments.
|
||||
- Incorporate advanced load balancing and failover mechanisms.
|
||||
- **Reliability:**
|
||||
- Implement comprehensive testing
|
||||
- Develop monitoring and basic health check features
|
||||
- Improve overall system stability
|
||||
|
||||
## How to Follow the Roadmap
|
||||
|
||||
- **Community Involvement:** We welcome and encourage feedback.
|
||||
- **Regular Updates:** This document is updated regularly with new goals and milestones.
|
||||
- **Transparency:** Check our GitHub repository and issue tracker for ongoing discussions.
|
||||
- **Community Involvement:** We welcome feedback and contributions.
|
||||
- **Transparency:** Check our GitHub repository for ongoing discussions.
|
||||
- **Iterative Development:** Goals may change based on community needs and technical feasibility.
|
||||
|
||||
*This roadmap is intended as a guide and may evolve based on community needs, technological advancements, and strategic priorities.*
|
||||
146
docs/security.md
Normal file
146
docs/security.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Security Guide
|
||||
|
||||
This document outlines security best practices and configurations for the Home Assistant MCP Server.
|
||||
|
||||
## Authentication
|
||||
|
||||
### JWT Authentication
|
||||
The server uses JWT (JSON Web Tokens) for API authentication:
|
||||
|
||||
```http
|
||||
Authorization: Bearer YOUR_JWT_TOKEN
|
||||
```
|
||||
|
||||
### Token Configuration
|
||||
```yaml
|
||||
security:
|
||||
jwt_secret: YOUR_SECRET_KEY
|
||||
token_expiry: 24h
|
||||
refresh_token_expiry: 7d
|
||||
```
|
||||
|
||||
## Access Control
|
||||
|
||||
### CORS Configuration
|
||||
Configure allowed origins to prevent unauthorized access:
|
||||
|
||||
```yaml
|
||||
security:
|
||||
allowed_origins:
|
||||
- http://localhost:3000
|
||||
- https://your-domain.com
|
||||
```
|
||||
|
||||
### IP Filtering
|
||||
Restrict access by IP address:
|
||||
|
||||
```yaml
|
||||
security:
|
||||
allowed_ips:
|
||||
- 192.168.1.0/24
|
||||
- 10.0.0.0/8
|
||||
```
|
||||
|
||||
## SSL/TLS Configuration
|
||||
|
||||
### Enable HTTPS
|
||||
```yaml
|
||||
ssl:
|
||||
enabled: true
|
||||
cert_file: /path/to/cert.pem
|
||||
key_file: /path/to/key.pem
|
||||
```
|
||||
|
||||
### Certificate Management
|
||||
1. Use Let's Encrypt for free SSL certificates
|
||||
2. Regularly renew certificates
|
||||
3. Monitor certificate expiration
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### Basic Rate Limiting
|
||||
```yaml
|
||||
rate_limit:
|
||||
enabled: true
|
||||
requests_per_minute: 100
|
||||
burst: 20
|
||||
```
|
||||
|
||||
### Advanced Rate Limiting
|
||||
```yaml
|
||||
rate_limit:
|
||||
rules:
|
||||
- endpoint: /api/control
|
||||
requests_per_minute: 50
|
||||
- endpoint: /api/state
|
||||
requests_per_minute: 200
|
||||
```
|
||||
|
||||
## Data Protection
|
||||
|
||||
### Sensitive Data
|
||||
- Use environment variables for secrets
|
||||
- Encrypt sensitive data at rest
|
||||
- Implement secure backup procedures
|
||||
|
||||
### Logging Security
|
||||
- Avoid logging sensitive information
|
||||
- Rotate logs regularly
|
||||
- Protect log file access
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Regular Security Updates
|
||||
- Keep dependencies updated
|
||||
- Monitor security advisories
|
||||
- Apply patches promptly
|
||||
|
||||
2. Password Policies
|
||||
- Enforce strong passwords
|
||||
- Implement password expiration
|
||||
- Use secure password storage
|
||||
|
||||
3. Monitoring
|
||||
- Log security events
|
||||
- Monitor access patterns
|
||||
- Set up alerts for suspicious activity
|
||||
|
||||
4. Network Security
|
||||
- Use VPN for remote access
|
||||
- Implement network segmentation
|
||||
- Configure firewalls properly
|
||||
|
||||
## Security Checklist
|
||||
|
||||
- [ ] Configure SSL/TLS
|
||||
- [ ] Set up JWT authentication
|
||||
- [ ] Configure CORS properly
|
||||
- [ ] Enable rate limiting
|
||||
- [ ] Implement IP filtering
|
||||
- [ ] Secure sensitive data
|
||||
- [ ] Set up monitoring
|
||||
- [ ] Configure backup encryption
|
||||
- [ ] Update security policies
|
||||
|
||||
## Incident Response
|
||||
|
||||
1. Detection
|
||||
- Monitor security logs
|
||||
- Set up intrusion detection
|
||||
- Configure alerts
|
||||
|
||||
2. Response
|
||||
- Document incident details
|
||||
- Isolate affected systems
|
||||
- Investigate root cause
|
||||
|
||||
3. Recovery
|
||||
- Apply security fixes
|
||||
- Restore from backups
|
||||
- Update security measures
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Security Best Practices](https://owasp.org/www-project-top-ten/)
|
||||
- [JWT Security](https://jwt.io/introduction)
|
||||
- [SSL Configuration](https://ssl-config.mozilla.org/)
|
||||
364
docs/sse-api.md
364
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);
|
||||
```
|
||||
164
docs/stylesheets/extra.css
Normal file
164
docs/stylesheets/extra.css
Normal file
@@ -0,0 +1,164 @@
|
||||
/* Modern Dark Theme Enhancements */
|
||||
[data-md-color-scheme="slate"] {
|
||||
--md-default-bg-color: #1a1b26;
|
||||
--md-default-fg-color: #a9b1d6;
|
||||
--md-default-fg-color--light: #a9b1d6;
|
||||
--md-default-fg-color--lighter: #787c99;
|
||||
--md-default-fg-color--lightest: #4e5173;
|
||||
--md-primary-fg-color: #7aa2f7;
|
||||
--md-primary-fg-color--light: #7dcfff;
|
||||
--md-primary-fg-color--dark: #2ac3de;
|
||||
--md-accent-fg-color: #bb9af7;
|
||||
--md-accent-fg-color--transparent: #bb9af722;
|
||||
--md-accent-bg-color: #1a1b26;
|
||||
--md-accent-bg-color--light: #24283b;
|
||||
}
|
||||
|
||||
/* Code Blocks */
|
||||
.highlight pre {
|
||||
background-color: #24283b !important;
|
||||
border-radius: 6px;
|
||||
padding: 1em;
|
||||
margin: 1em 0;
|
||||
overflow: auto;
|
||||
}
|
||||
|
||||
.highlight code {
|
||||
font-family: 'Roboto Mono', monospace;
|
||||
font-size: 0.9em;
|
||||
}
|
||||
|
||||
/* Copy Button */
|
||||
.copy-button {
|
||||
position: absolute;
|
||||
right: 0.5em;
|
||||
top: 0.5em;
|
||||
padding: 0.4em 0.8em;
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border: 1px solid var(--md-accent-fg-color--transparent);
|
||||
border-radius: 4px;
|
||||
color: var(--md-default-fg-color);
|
||||
font-size: 0.8em;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s ease;
|
||||
}
|
||||
|
||||
.copy-button:hover {
|
||||
background-color: var(--md-accent-fg-color--transparent);
|
||||
border-color: var(--md-accent-fg-color);
|
||||
}
|
||||
|
||||
/* Navigation Enhancements */
|
||||
.md-nav {
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
.md-nav__link {
|
||||
padding: 0.4rem 0;
|
||||
transition: color 0.2s ease;
|
||||
}
|
||||
|
||||
.md-nav__link:hover {
|
||||
color: var(--md-primary-fg-color) !important;
|
||||
}
|
||||
|
||||
/* Tabs */
|
||||
.md-tabs__link {
|
||||
opacity: 0.8;
|
||||
transition: opacity 0.2s ease;
|
||||
}
|
||||
|
||||
.md-tabs__link:hover {
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
.md-tabs__link--active {
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
/* Admonitions */
|
||||
.md-typeset .admonition,
|
||||
.md-typeset details {
|
||||
border-width: 0;
|
||||
border-left-width: 4px;
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
/* Tables */
|
||||
.md-typeset table:not([class]) {
|
||||
border-radius: 4px;
|
||||
box-shadow: 0 2px 4px var(--md-accent-fg-color--transparent);
|
||||
}
|
||||
|
||||
.md-typeset table:not([class]) th {
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border-bottom: 2px solid var(--md-accent-fg-color--transparent);
|
||||
}
|
||||
|
||||
/* Search */
|
||||
.md-search__form {
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
/* Feedback Buttons */
|
||||
.feedback-button {
|
||||
padding: 0.5em 1em;
|
||||
margin: 0 0.5em;
|
||||
border-radius: 4px;
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border: 1px solid var(--md-accent-fg-color--transparent);
|
||||
color: var(--md-default-fg-color);
|
||||
cursor: pointer;
|
||||
transition: all 0.2s ease;
|
||||
}
|
||||
|
||||
.feedback-button:hover {
|
||||
background-color: var(--md-accent-fg-color--transparent);
|
||||
border-color: var(--md-accent-fg-color);
|
||||
}
|
||||
|
||||
.feedback-button:disabled {
|
||||
opacity: 0.5;
|
||||
cursor: not-allowed;
|
||||
}
|
||||
|
||||
/* Version Selector */
|
||||
.version-selector {
|
||||
padding: 0.5em;
|
||||
border-radius: 4px;
|
||||
background-color: var(--md-accent-bg-color--light);
|
||||
border: 1px solid var(--md-accent-fg-color--transparent);
|
||||
color: var(--md-default-fg-color);
|
||||
}
|
||||
|
||||
/* Scrollbar */
|
||||
::-webkit-scrollbar {
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-track {
|
||||
background: var(--md-accent-bg-color--light);
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb {
|
||||
background: var(--md-accent-fg-color--transparent);
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb:hover {
|
||||
background: var(--md-accent-fg-color);
|
||||
}
|
||||
|
||||
/* Print Styles */
|
||||
@media print {
|
||||
.md-typeset a {
|
||||
color: var(--md-default-fg-color) !important;
|
||||
}
|
||||
|
||||
.md-content__inner {
|
||||
margin: 0;
|
||||
padding: 1rem;
|
||||
}
|
||||
}
|
||||
240
docs/tools/addons-packages/addon.md
Normal file
240
docs/tools/addons-packages/addon.md
Normal file
@@ -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)
|
||||
236
docs/tools/addons-packages/package.md
Normal file
236
docs/tools/addons-packages/package.md
Normal file
@@ -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)
|
||||
321
docs/tools/automation/automation-config.md
Normal file
321
docs/tools/automation/automation-config.md
Normal file
@@ -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)
|
||||
211
docs/tools/automation/automation.md
Normal file
211
docs/tools/automation/automation.md
Normal file
@@ -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)
|
||||
195
docs/tools/device-management/control.md
Normal file
195
docs/tools/device-management/control.md
Normal file
@@ -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)
|
||||
139
docs/tools/device-management/list-devices.md
Normal file
139
docs/tools/device-management/list-devices.md
Normal file
@@ -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)
|
||||
251
docs/tools/events/sse-stats.md
Normal file
251
docs/tools/events/sse-stats.md
Normal file
@@ -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)
|
||||
253
docs/tools/events/subscribe-events.md
Normal file
253
docs/tools/events/subscribe-events.md
Normal file
@@ -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)
|
||||
167
docs/tools/history-state/history.md
Normal file
167
docs/tools/history-state/history.md
Normal file
@@ -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)
|
||||
215
docs/tools/history-state/scene.md
Normal file
215
docs/tools/history-state/scene.md
Normal file
@@ -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)
|
||||
42
docs/tools/index.md
Normal file
42
docs/tools/index.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Tools Overview
|
||||
|
||||
The Home Assistant MCP Server provides a variety of tools to help you manage and interact with your home automation system.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### Device Management
|
||||
- [List Devices](device-management/list-devices.md) - View and manage connected devices
|
||||
- [Device Control](device-management/control.md) - Control device states and settings
|
||||
|
||||
### History & State
|
||||
- [History](history-state/history.md) - View and analyze historical data
|
||||
- [Scene Management](history-state/scene.md) - Create and manage scenes
|
||||
|
||||
### Automation
|
||||
- [Automation Management](automation/automation.md) - Create and manage automations
|
||||
- [Automation Configuration](automation/automation-config.md) - Configure automation settings
|
||||
|
||||
### Add-ons & Packages
|
||||
- [Add-on Management](addons-packages/addon.md) - Manage server add-ons
|
||||
- [Package Management](addons-packages/package.md) - Handle package installations
|
||||
|
||||
### Notifications
|
||||
- [Notify](notifications/notify.md) - Send and manage notifications
|
||||
|
||||
### Events
|
||||
- [Event Subscription](events/subscribe-events.md) - Subscribe to system events
|
||||
- [SSE Statistics](events/sse-stats.md) - Monitor Server-Sent Events statistics
|
||||
|
||||
## Getting Started
|
||||
|
||||
To get started with these tools:
|
||||
|
||||
1. Ensure you have the MCP Server properly installed and configured
|
||||
2. Check the specific tool documentation for detailed usage instructions
|
||||
3. Use the API endpoints or command-line interface as needed
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Review the [API Documentation](../api/index.md) for programmatic access
|
||||
- Check [Configuration](../config/index.md) for tool-specific settings
|
||||
- See [Examples](../examples/index.md) for practical use cases
|
||||
249
docs/tools/notifications/notify.md
Normal file
249
docs/tools/notifications/notify.md
Normal file
@@ -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)
|
||||
@@ -1,127 +0,0 @@
|
||||
# Home Assistant MCP Tools
|
||||
|
||||
This section documents all available tools in the Home Assistant MCP.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### Device Management
|
||||
|
||||
1. [List Devices](./list-devices.md)
|
||||
- List all available Home Assistant devices
|
||||
- Group devices by domain
|
||||
- Get device states and attributes
|
||||
|
||||
2. [Device Control](./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)
|
||||
- Fetch device state history
|
||||
- Filter by time range
|
||||
- Get significant changes
|
||||
|
||||
2. [Scene Management](./scene.md)
|
||||
- List available scenes
|
||||
- Activate scenes
|
||||
- Scene state information
|
||||
|
||||
### Automation
|
||||
|
||||
1. [Automation Management](./automation.md)
|
||||
- List automations
|
||||
- Toggle automation state
|
||||
- Trigger automations manually
|
||||
|
||||
2. [Automation Configuration](./automation-config.md)
|
||||
- Create new automations
|
||||
- Update existing automations
|
||||
- Delete automations
|
||||
- Duplicate automations
|
||||
|
||||
### Add-ons and Packages
|
||||
|
||||
1. [Add-on Management](./addon.md)
|
||||
- List available add-ons
|
||||
- Install/uninstall add-ons
|
||||
- Start/stop/restart add-ons
|
||||
- Get add-on information
|
||||
|
||||
2. [Package Management](./package.md)
|
||||
- Manage HACS packages
|
||||
- Install/update/remove packages
|
||||
- List available packages by category
|
||||
|
||||
### Notifications
|
||||
|
||||
1. [Notify](./notify.md)
|
||||
- Send notifications
|
||||
- Support for multiple notification services
|
||||
- Custom notification data
|
||||
|
||||
### Real-time Events
|
||||
|
||||
1. [Event Subscription](./subscribe-events.md)
|
||||
- Subscribe to Home Assistant events
|
||||
- Monitor specific entities
|
||||
- Domain-based monitoring
|
||||
|
||||
2. [SSE Statistics](./sse-stats.md)
|
||||
- Get SSE connection statistics
|
||||
- Monitor active subscriptions
|
||||
- Connection management
|
||||
|
||||
## Using Tools
|
||||
|
||||
All tools can be accessed through:
|
||||
|
||||
1. REST API endpoints
|
||||
2. WebSocket connections
|
||||
3. Server-Sent Events (SSE)
|
||||
|
||||
### Authentication
|
||||
|
||||
Tools require authentication using:
|
||||
- Home Assistant Long-Lived Access Token
|
||||
- JWT tokens for specific operations
|
||||
|
||||
### Error Handling
|
||||
|
||||
All tools follow a consistent error handling pattern:
|
||||
```typescript
|
||||
{
|
||||
success: boolean;
|
||||
message?: string;
|
||||
data?: any;
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
Tools are subject to rate limiting:
|
||||
- Default: 100 requests per 15 minutes
|
||||
- Configurable through environment variables
|
||||
|
||||
## Tool Development
|
||||
|
||||
Want to create a new tool? Check out:
|
||||
- [Tool Development Guide](../development/tools.md)
|
||||
- [Tool Interface Documentation](../development/interfaces.md)
|
||||
- [Best Practices](../development/best-practices.md)
|
||||
|
||||
## Examples
|
||||
|
||||
Each tool documentation includes:
|
||||
- Usage examples
|
||||
- Code snippets
|
||||
- Common use cases
|
||||
- Troubleshooting tips
|
||||
|
||||
## Support
|
||||
|
||||
Need help with tools?
|
||||
- Check individual tool documentation
|
||||
- See [Troubleshooting Guide](../troubleshooting.md)
|
||||
- Create an issue on GitHub
|
||||
@@ -1,345 +1,374 @@
|
||||
# Troubleshooting Guide
|
||||
---
|
||||
layout: default
|
||||
title: Troubleshooting
|
||||
nav_order: 6
|
||||
---
|
||||
|
||||
This guide provides solutions to common issues encountered with the Home Assistant MCP Server.
|
||||
# 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
|
||||
|
||||
- **Server Not Starting:**
|
||||
- Verify that all required environment variables are correctly set.
|
||||
- Check for port conflicts or missing dependencies.
|
||||
- Review the server logs for error details.
|
||||
### 1. Connection Issues
|
||||
|
||||
- **Connection Problems:**
|
||||
- Ensure your Home Assistant instance is reachable.
|
||||
- Confirm that the authentication token is valid.
|
||||
- Check network configurations and firewalls.
|
||||
|
||||
## Tool Issues
|
||||
|
||||
### Tool Not Found
|
||||
#### Cannot Connect to MCP Server
|
||||
|
||||
**Symptoms:**
|
||||
- "Tool not found" errors or 404 responses.
|
||||
- Server not responding
|
||||
- Connection refused errors
|
||||
- Timeout errors
|
||||
|
||||
**Solutions:**
|
||||
- Double-check the tool name spelling.
|
||||
- Verify that the tool is correctly registered.
|
||||
- Review tool imports and documentation.
|
||||
|
||||
### Tool Execution Failures
|
||||
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:**
|
||||
- Execution errors or timeouts.
|
||||
- "Connection Error" in health check
|
||||
- Cannot control devices
|
||||
- State updates not working
|
||||
|
||||
**Solutions:**
|
||||
- Validate input parameters.
|
||||
- Check and review error logs.
|
||||
- Debug the tool implementation.
|
||||
- Ensure proper permissions in Home Assistant.
|
||||
|
||||
## Debugging Steps
|
||||
1. Verify Home Assistant URL and token in `.env`:
|
||||
```env
|
||||
HA_URL=http://homeassistant:8123
|
||||
HA_TOKEN=your_long_lived_access_token
|
||||
```
|
||||
|
||||
### Server Logs
|
||||
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" errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Generate a new token:
|
||||
```bash
|
||||
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" errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Check current rate limit status:
|
||||
```bash
|
||||
curl -I http://localhost:3000/api/state
|
||||
```
|
||||
|
||||
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:**
|
||||
- Frequent disconnections
|
||||
- Missing state updates
|
||||
- EventSource errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
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:**
|
||||
- Slow response times
|
||||
- Command execution delays
|
||||
- UI lag
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Enable Redis caching:
|
||||
```env
|
||||
REDIS_ENABLED=true
|
||||
REDIS_URL=redis://localhost:6379
|
||||
```
|
||||
|
||||
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 by setting:
|
||||
```env
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
2. Check logs:
|
||||
```bash
|
||||
npm run logs
|
||||
```
|
||||
3. Filter errors:
|
||||
```bash
|
||||
npm run logs | grep "error"
|
||||
DEBUG=mcp:*
|
||||
```
|
||||
|
||||
### Network Debugging
|
||||
|
||||
1. Test API endpoints:
|
||||
Monitor network traffic:
|
||||
|
||||
```bash
|
||||
curl -v http://localhost:3000/api/health
|
||||
```
|
||||
2. Monitor SSE connections:
|
||||
```bash
|
||||
curl -N http://localhost:3000/api/sse/stats
|
||||
```
|
||||
3. Test WebSocket connectivity:
|
||||
```bash
|
||||
wscat -c ws://localhost:3000
|
||||
# TCP dump for API traffic
|
||||
tcpdump -i any port 3000 -w debug.pcap
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
### Performance Profiling
|
||||
|
||||
- Monitor memory usage with:
|
||||
```bash
|
||||
npm run stats
|
||||
Enable performance monitoring:
|
||||
|
||||
```env
|
||||
ENABLE_METRICS=true
|
||||
METRICS_PORT=9090
|
||||
```
|
||||
|
||||
## Security Middleware Troubleshooting
|
||||
|
||||
### Rate Limiting Problems
|
||||
|
||||
**Symptoms:** Receiving 429 (Too Many Requests) errors.
|
||||
|
||||
**Solutions:**
|
||||
- Adjust and fine-tune rate limit settings.
|
||||
- Consider different limits for critical versus non-critical endpoints.
|
||||
|
||||
### Request Validation Failures
|
||||
|
||||
**Symptoms:** 400 or 415 errors on valid requests.
|
||||
|
||||
**Solutions:**
|
||||
- Verify that the `Content-Type` header is set correctly.
|
||||
- Inspect request payload size and format.
|
||||
|
||||
### Input Sanitization Issues
|
||||
|
||||
**Symptoms:** Unexpected data transformation or loss.
|
||||
|
||||
**Solutions:**
|
||||
- Test sanitization with various input types.
|
||||
- Implement custom sanitization for complex data if needed.
|
||||
|
||||
### Security Header Configuration
|
||||
|
||||
**Symptoms:** Missing or improper security headers.
|
||||
|
||||
**Solutions:**
|
||||
- Review and update security header configurations (e.g., Helmet settings).
|
||||
- Ensure environment-specific header settings are in place.
|
||||
|
||||
### Error Handling and Logging
|
||||
|
||||
**Symptoms:** Inconsistent error responses.
|
||||
|
||||
**Solutions:**
|
||||
- Enhance logging for detailed error tracking.
|
||||
- Adjust error handlers for production and development differences.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [OWASP Security Guidelines](https://owasp.org/www-project-top-ten/)
|
||||
- [Helmet.js Documentation](https://helmetjs.github.io/)
|
||||
- [JWT Security Best Practices](https://jwt.io/introduction)
|
||||
|
||||
## Getting Help
|
||||
|
||||
If issues persist:
|
||||
1. Review detailed logs.
|
||||
2. Verify your configuration and environment.
|
||||
3. Consult the GitHub issue tracker or community forums.
|
||||
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
|
||||
# Create a cron job
|
||||
*/5 * * * * curl -f http://localhost:3000/health || notify-admin
|
||||
```
|
||||
|
||||
### Log Rotation
|
||||
|
||||
Configure log rotation:
|
||||
|
||||
```yaml
|
||||
logging:
|
||||
maxSize: "100m"
|
||||
maxFiles: "7d"
|
||||
compress: true
|
||||
```
|
||||
|
||||
### Backup Configuration
|
||||
|
||||
Regularly backup your configuration:
|
||||
|
||||
```bash
|
||||
# Backup script
|
||||
tar -czf mcp-backup-$(date +%Y%m%d).tar.gz \
|
||||
.env \
|
||||
config/ \
|
||||
data/
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: How do I reset my configuration?
|
||||
A: Delete `.env` and copy `.env.example` to start fresh.
|
||||
### General Questions
|
||||
|
||||
### Q: Why are my events delayed?
|
||||
A: Check network latency and server load. Consider adjusting buffer sizes.
|
||||
#### Q: What is MCP Server?
|
||||
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?
|
||||
A: Generate a new token in Home Assistant and update HASS_TOKEN.
|
||||
#### Q: What are the system requirements?
|
||||
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"?
|
||||
A: Adjust SSE_MAX_CLIENTS in configuration or clean up stale connections.
|
||||
|
||||
## Error Codes
|
||||
|
||||
- `E001`: Connection Error
|
||||
- `E002`: Authentication Error
|
||||
- `E003`: Rate Limit Error
|
||||
- `E004`: Tool Error
|
||||
- `E005`: Configuration Error
|
||||
|
||||
## Support Resources
|
||||
|
||||
1. Documentation
|
||||
- [API Reference](./API.md)
|
||||
- [Configuration Guide](./configuration/README.md)
|
||||
- [Development Guide](./development/development.md)
|
||||
|
||||
2. Community
|
||||
- GitHub Issues
|
||||
- Discussion Forums
|
||||
- Stack Overflow
|
||||
|
||||
3. Tools
|
||||
- Diagnostic Scripts
|
||||
- Testing Tools
|
||||
- Monitoring Tools
|
||||
|
||||
## Still Need Help?
|
||||
|
||||
1. Create a detailed issue:
|
||||
- Error messages
|
||||
- Steps to reproduce
|
||||
- Environment details
|
||||
- Logs
|
||||
|
||||
2. Contact support:
|
||||
- GitHub Issues
|
||||
- Email Support
|
||||
- Community Forums
|
||||
|
||||
## Security Middleware Troubleshooting
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
#### Rate Limiting Problems
|
||||
|
||||
**Symptom**: Unexpected 429 (Too Many Requests) errors
|
||||
|
||||
**Possible Causes**:
|
||||
- Misconfigured rate limit settings
|
||||
- Shared IP addresses (e.g., behind NAT)
|
||||
- Aggressive client-side retry mechanisms
|
||||
|
||||
**Solutions**:
|
||||
1. Adjust rate limit parameters
|
||||
```typescript
|
||||
// Customize rate limit for specific scenarios
|
||||
checkRateLimit(ip, maxRequests = 200, windowMs = 30 * 60 * 1000)
|
||||
#### Q: How do I update MCP Server?
|
||||
A: For Docker installation:
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
For manual installation:
|
||||
```bash
|
||||
git pull
|
||||
bun install
|
||||
bun run build
|
||||
```
|
||||
|
||||
2. Implement more granular rate limiting
|
||||
- Use different limits for different endpoints
|
||||
- Consider user authentication level
|
||||
### Integration Questions
|
||||
|
||||
#### Request Validation Failures
|
||||
#### Q: Can I use MCP Server with any Home Assistant instance?
|
||||
A: Yes, MCP Server works with any Home Assistant instance that has the REST API enabled and a valid long-lived access token.
|
||||
|
||||
**Symptom**: 400 or 415 status codes on valid requests
|
||||
#### 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.
|
||||
|
||||
**Possible Causes**:
|
||||
- Incorrect `Content-Type` header
|
||||
- Large request payloads
|
||||
- Malformed authorization headers
|
||||
### Security Questions
|
||||
|
||||
**Debugging Steps**:
|
||||
1. Verify request headers
|
||||
```typescript
|
||||
// Check content type and size
|
||||
validateRequestHeaders(request, 'application/json')
|
||||
```
|
||||
#### Q: Is my Home Assistant token secure?
|
||||
A: Yes, your Home Assistant token is stored securely and only used for authenticated communication between MCP Server and your Home Assistant instance.
|
||||
|
||||
2. Log detailed validation errors
|
||||
```typescript
|
||||
try {
|
||||
validateRequestHeaders(request);
|
||||
} catch (error) {
|
||||
console.error('Request validation failed:', error.message);
|
||||
}
|
||||
```
|
||||
#### Q: Can I use MCP Server remotely?
|
||||
A: Yes, but we recommend using a secure connection (HTTPS) and proper authentication when exposing MCP Server to the internet.
|
||||
|
||||
#### Input Sanitization Issues
|
||||
### Troubleshooting Questions
|
||||
|
||||
**Symptom**: Unexpected data transformation or loss
|
||||
#### Q: Why are my device states not updating?
|
||||
A: Check:
|
||||
1. Home Assistant connection
|
||||
2. WebSocket connection status
|
||||
3. Device availability in Home Assistant
|
||||
4. Network connectivity
|
||||
|
||||
**Possible Causes**:
|
||||
- Complex nested objects
|
||||
- Non-standard input formats
|
||||
- Overly aggressive sanitization
|
||||
|
||||
**Troubleshooting**:
|
||||
1. Test sanitization with various input types
|
||||
```typescript
|
||||
const input = {
|
||||
text: '<script>alert("xss")</script>',
|
||||
nested: { html: '<img src="x" onerror="alert(1)">World' }
|
||||
};
|
||||
const sanitized = sanitizeValue(input);
|
||||
```
|
||||
|
||||
2. Custom sanitization for specific use cases
|
||||
```typescript
|
||||
function customSanitize(value) {
|
||||
// Add custom sanitization logic
|
||||
return sanitizeValue(value);
|
||||
}
|
||||
```
|
||||
|
||||
#### Security Header Configuration
|
||||
|
||||
**Symptom**: Missing or incorrect security headers
|
||||
|
||||
**Possible Causes**:
|
||||
- Misconfigured Helmet options
|
||||
- Environment-specific header requirements
|
||||
|
||||
**Solutions**:
|
||||
1. Custom security header configuration
|
||||
```typescript
|
||||
const customHelmetConfig = {
|
||||
contentSecurityPolicy: {
|
||||
directives: {
|
||||
defaultSrc: ["'self'"],
|
||||
scriptSrc: ["'self'", 'trusted-cdn.com']
|
||||
}
|
||||
}
|
||||
};
|
||||
applySecurityHeaders(request, customHelmetConfig);
|
||||
```
|
||||
|
||||
#### Error Handling and Logging
|
||||
|
||||
**Symptom**: Inconsistent error responses
|
||||
|
||||
**Possible Causes**:
|
||||
- Incorrect environment configuration
|
||||
- Unhandled error types
|
||||
|
||||
**Debugging Techniques**:
|
||||
1. Verify environment settings
|
||||
```typescript
|
||||
const errorResponse = handleError(error, process.env.NODE_ENV);
|
||||
```
|
||||
|
||||
2. Add custom error handling
|
||||
```typescript
|
||||
function enhancedErrorHandler(error, env) {
|
||||
// Add custom logging or monitoring
|
||||
console.error('Security error:', error);
|
||||
return handleError(error, env);
|
||||
}
|
||||
```
|
||||
|
||||
### Performance and Security Monitoring
|
||||
|
||||
1. **Logging**
|
||||
- Enable debug logging for security events
|
||||
- Monitor rate limit and validation logs
|
||||
|
||||
2. **Metrics**
|
||||
- Track rate limit hit rates
|
||||
- Monitor request validation success/failure ratios
|
||||
|
||||
3. **Continuous Improvement**
|
||||
- Regularly review and update security configurations
|
||||
- Conduct periodic security audits
|
||||
|
||||
### Environment-Specific Considerations
|
||||
|
||||
#### Development
|
||||
- More verbose error messages
|
||||
- Relaxed rate limiting
|
||||
- Detailed security logs
|
||||
|
||||
#### Production
|
||||
- Minimal error details
|
||||
- Strict rate limiting
|
||||
- Comprehensive security headers
|
||||
|
||||
### External Resources
|
||||
|
||||
- [OWASP Security Guidelines](https://owasp.org/www-project-top-ten/)
|
||||
- [Helmet.js Documentation](https://helmetjs.github.io/)
|
||||
- [JWT Security Best Practices](https://jwt.io/introduction)
|
||||
|
||||
### Getting Help
|
||||
|
||||
If you encounter persistent issues:
|
||||
1. Check application logs
|
||||
2. Verify environment configurations
|
||||
3. Consult the project's issue tracker
|
||||
4. Reach out to the development team with detailed error information
|
||||
#### Q: Why are my commands not working?
|
||||
A: Verify:
|
||||
1. Command syntax
|
||||
2. Device availability
|
||||
3. User permissions
|
||||
4. Home Assistant API access
|
||||
100
docs/usage.md
100
docs/usage.md
@@ -1,34 +1,96 @@
|
||||
# Usage Guide
|
||||
|
||||
This guide explains how to use the Home Assistant MCP Server for smart home device management and integration with language learning systems.
|
||||
This guide explains how to use the Home Assistant MCP Server for basic device management and integration.
|
||||
|
||||
## Basic Usage
|
||||
## Basic Setup
|
||||
|
||||
1. **Starting the Server:**
|
||||
- For development: run `npm run dev`.
|
||||
- For production: run `npm run build` followed by `npm start`.
|
||||
- Development mode: `bun run dev`
|
||||
- Production mode: `bun run start`
|
||||
|
||||
2. **Accessing the Web Interface:**
|
||||
- Open [http://localhost:3000](http://localhost:3000) in your browser.
|
||||
2. **Accessing the Server:**
|
||||
- Default URL: `http://localhost:3000`
|
||||
- Ensure Home Assistant credentials are configured in `.env`
|
||||
|
||||
3. **Real-Time Updates:**
|
||||
- Connect to the SSE endpoint at `/subscribe_events?token=YOUR_TOKEN&domain=light` to receive live updates.
|
||||
## Device Control
|
||||
|
||||
## Advanced Features
|
||||
### REST API Interactions
|
||||
|
||||
1. **API Interactions:**
|
||||
- Use the REST API for operations such as device control, automation, and add-on management.
|
||||
- See [API Documentation](api.md) for details.
|
||||
Basic device control can be performed via the REST API:
|
||||
|
||||
2. **Tool Integrations:**
|
||||
- Multiple tools are available (see [Tools Documentation](tools/tools.md)), for tasks like automation management and notifications.
|
||||
```typescript
|
||||
// Turn on a light
|
||||
fetch('http://localhost:3000/api/control', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${token}`
|
||||
},
|
||||
body: JSON.stringify({
|
||||
entity_id: 'light.living_room',
|
||||
command: 'turn_on',
|
||||
parameters: { brightness: 50 }
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
3. **Security Settings:**
|
||||
- Configure token-based authentication and environment variables as per the [Configuration Guide](getting-started/configuration.md).
|
||||
### Supported Commands
|
||||
|
||||
4. **Customization and Extensions:**
|
||||
- Extend server functionality by developing new tools as outlined in the [Development Guide](development/development.md).
|
||||
- `turn_on`
|
||||
- `turn_off`
|
||||
- `toggle`
|
||||
- `set_brightness`
|
||||
|
||||
### Supported Entities
|
||||
|
||||
- Lights
|
||||
- Switches
|
||||
- Climate controls
|
||||
- Media players
|
||||
|
||||
## Real-Time Updates
|
||||
|
||||
### WebSocket Connection
|
||||
|
||||
Subscribe to real-time device state changes:
|
||||
|
||||
```typescript
|
||||
const ws = new WebSocket('ws://localhost:3000/events');
|
||||
ws.onmessage = (event) => {
|
||||
const deviceUpdate = JSON.parse(event.data);
|
||||
console.log('Device state changed:', deviceUpdate);
|
||||
};
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
All API requests require a valid JWT token in the Authorization header.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Basic device control only
|
||||
- Limited error handling
|
||||
- Minimal third-party integrations
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you experience issues, review the [Troubleshooting Guide](troubleshooting.md).
|
||||
1. Verify Home Assistant connection
|
||||
2. Check JWT token validity
|
||||
3. Ensure correct entity IDs
|
||||
4. Review server logs for detailed errors
|
||||
|
||||
## Configuration
|
||||
|
||||
Configure the server using environment variables in `.env`:
|
||||
|
||||
```
|
||||
HA_URL=http://homeassistant:8123
|
||||
HA_TOKEN=your_home_assistant_token
|
||||
JWT_SECRET=your_jwt_secret
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Explore the [API Documentation](api.md)
|
||||
- Check [Troubleshooting Guide](troubleshooting.md)
|
||||
- Review [Contributing Guidelines](contributing.md)
|
||||
91
extra/README.md
Normal file
91
extra/README.md
Normal file
@@ -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
|
||||
@@ -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
|
||||
91
extra/speech-to-text-example.ts
Normal file
91
extra/speech-to-text-example.ts
Normal file
@@ -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);
|
||||
});
|
||||
237
mkdocs.yml
237
mkdocs.yml
@@ -1,26 +1,249 @@
|
||||
site_name: Home Assistant Model Context Protocol (MCP)
|
||||
site_url: https://yourusername.github.io/your-repo-name/
|
||||
repo_url: https://github.com/yourusername/your-repo-name
|
||||
site_name: MCP Server for Home Assistant
|
||||
site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp
|
||||
repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
|
||||
site_description: Home Assistant MCP Server Documentation
|
||||
# Add this to handle GitHub Pages serving from a subdirectory
|
||||
site_dir: site/advanced-homeassistant-mcp
|
||||
|
||||
theme:
|
||||
name: material
|
||||
logo: assets/images/logo.png
|
||||
favicon: assets/images/favicon.ico
|
||||
|
||||
# Modern Features
|
||||
features:
|
||||
# Navigation Enhancements
|
||||
- navigation.tabs
|
||||
- navigation.tabs.sticky
|
||||
- navigation.indexes
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- navigation.path
|
||||
- navigation.footer
|
||||
- navigation.prune
|
||||
- navigation.tracking
|
||||
- navigation.instant
|
||||
|
||||
# UI Elements
|
||||
- header.autohide
|
||||
- toc.integrate
|
||||
- toc.follow
|
||||
- announce.dismiss
|
||||
|
||||
# Search Features
|
||||
- search.suggest
|
||||
- search.highlight
|
||||
- search.share
|
||||
|
||||
# Code Features
|
||||
- content.code.annotate
|
||||
- content.code.copy
|
||||
- content.code.select
|
||||
- content.tabs.link
|
||||
- content.tooltips
|
||||
|
||||
# Theme Configuration
|
||||
palette:
|
||||
# Dark mode as primary
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
primary: deep-purple
|
||||
accent: purple
|
||||
toggle:
|
||||
icon: material/weather-sunny
|
||||
name: Switch to light mode
|
||||
# Light mode as secondary
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
primary: deep-purple
|
||||
accent: purple
|
||||
toggle:
|
||||
icon: material/weather-night
|
||||
name: Switch to dark mode
|
||||
|
||||
font:
|
||||
text: Roboto
|
||||
code: Roboto Mono
|
||||
|
||||
icon:
|
||||
repo: fontawesome/brands/github
|
||||
edit: material/pencil
|
||||
view: material/eye
|
||||
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight
|
||||
- pymdownx.superfences
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
# Modern Code Highlighting
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
|
||||
# Advanced Formatting
|
||||
- pymdownx.critic
|
||||
- pymdownx.caret
|
||||
- pymdownx.keys
|
||||
- pymdownx.mark
|
||||
- pymdownx.tilde
|
||||
|
||||
# Interactive Elements
|
||||
- pymdownx.details
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
|
||||
# Diagrams & Formatting
|
||||
- pymdownx.superfences:
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
- pymdownx.arithmatex:
|
||||
generic: true
|
||||
|
||||
# Additional Extensions
|
||||
- admonition
|
||||
- attr_list
|
||||
- md_in_html
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
- footnotes
|
||||
- tables
|
||||
- def_list
|
||||
- abbr
|
||||
|
||||
plugins:
|
||||
# Core Plugins
|
||||
- search:
|
||||
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
|
||||
- minify:
|
||||
minify_html: true
|
||||
- mkdocstrings
|
||||
|
||||
# Advanced Features
|
||||
- social:
|
||||
cards: false
|
||||
- tags
|
||||
- offline
|
||||
|
||||
# Version Management
|
||||
- git-revision-date-localized:
|
||||
enable_creation_date: true
|
||||
type: date
|
||||
|
||||
extra:
|
||||
# Consent Management
|
||||
consent:
|
||||
title: Cookie consent
|
||||
description: >-
|
||||
We use cookies to recognize your repeated visits and preferences, as well
|
||||
as to measure the effectiveness of our documentation and whether users
|
||||
find what they're searching for. With your consent, you're helping us to
|
||||
make our documentation better.
|
||||
actions:
|
||||
- accept
|
||||
- reject
|
||||
- manage
|
||||
|
||||
# Version Management
|
||||
version:
|
||||
provider: mike
|
||||
default: latest
|
||||
|
||||
# Social Links
|
||||
social:
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/jango-blockchained/homeassistant-mcp
|
||||
- icon: fontawesome/brands/docker
|
||||
link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
|
||||
|
||||
# Status Indicators
|
||||
status:
|
||||
new: Recently added
|
||||
deprecated: Deprecated
|
||||
beta: Beta
|
||||
|
||||
# Analytics
|
||||
analytics:
|
||||
provider: google
|
||||
property: !ENV GOOGLE_ANALYTICS_KEY
|
||||
feedback:
|
||||
title: Was this page helpful?
|
||||
ratings:
|
||||
- icon: material/emoticon-happy-outline
|
||||
name: This page was helpful
|
||||
data: 1
|
||||
note: >-
|
||||
Thanks for your feedback!
|
||||
- icon: material/emoticon-sad-outline
|
||||
name: This page could be improved
|
||||
data: 0
|
||||
note: >-
|
||||
Thanks for your feedback! Please consider creating an issue to help us improve.
|
||||
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
|
||||
extra_javascript:
|
||||
- javascripts/mathjax.js
|
||||
- https://polyfill.io/v3/polyfill.min.js?features=es6
|
||||
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
|
||||
- javascripts/extra.js
|
||||
|
||||
copyright: Copyright © 2025 jango-blockchained
|
||||
|
||||
# Keep existing nav structure
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Getting Started:
|
||||
- Overview: getting-started/index.md
|
||||
- Installation: getting-started/installation.md
|
||||
- Quick Start: getting-started/quickstart.md
|
||||
- Configuration: getting-started/configuration.md
|
||||
- Docker Setup: getting-started/docker.md
|
||||
- API Reference:
|
||||
- Overview: api/index.md
|
||||
- Core API: api/core.md
|
||||
- SSE API: api/sse.md
|
||||
- API Documentation: api.md
|
||||
- Usage: usage.md
|
||||
- Configuration:
|
||||
- Overview: config/index.md
|
||||
- System Configuration: configuration.md
|
||||
- Security: security.md
|
||||
- Tools:
|
||||
- Overview: tools/index.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/index.md
|
||||
- Environment Setup: development/environment.md
|
||||
- Architecture: architecture.md
|
||||
- Contributing: contributing.md
|
||||
- Testing: testing.md
|
||||
- Best Practices: development/best-practices.md
|
||||
- Interfaces: development/interfaces.md
|
||||
- Tool Development: development/tools.md
|
||||
- Test Migration Guide: development/test-migration-guide.md
|
||||
- Troubleshooting: troubleshooting.md
|
||||
- Deployment: deployment.md
|
||||
- Roadmap: roadmap.md
|
||||
- Examples:
|
||||
- Overview: examples/index.md
|
||||
@@ -21,7 +21,7 @@
|
||||
"profile": "bun --inspect src/index.ts",
|
||||
"clean": "rm -rf dist .bun coverage",
|
||||
"typecheck": "bun x tsc --noEmit",
|
||||
"preinstall": "bun install --frozen-lockfile"
|
||||
"example:speech": "bun run examples/speech-to-text-example.ts"
|
||||
},
|
||||
"dependencies": {
|
||||
"@elysiajs/cors": "^1.2.0",
|
||||
@@ -30,13 +30,17 @@
|
||||
"@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"
|
||||
},
|
||||
|
||||
21
search/scripts/start_mcp.cmd
Normal file
21
search/scripts/start_mcp.cmd
Normal file
@@ -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
|
||||
28
smithery.yaml
Normal file
28
smithery.yaml
Normal file
@@ -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()
|
||||
}
|
||||
})
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user