Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
e49d31d725 | ||
|
|
13a27e1d00 | ||
|
|
3e7f3920b2 | ||
|
|
8f8e3bd85e |
74
.github/workflows/deploy-docs.yml
vendored
74
.github/workflows/deploy-docs.yml
vendored
@@ -1,64 +1,38 @@
|
||||
name: Deploy Documentation to GitHub Pages
|
||||
|
||||
name: Deploy MkDocs
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- '.github/workflows/deploy-docs.yml'
|
||||
- main # or master, depending on your default branch
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# Allow only one concurrent deployment
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: true
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Ruby
|
||||
uses: ruby/setup-ruby@v1
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
ruby-version: '3.2'
|
||||
bundler-cache: true
|
||||
cache-version: 0
|
||||
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v4
|
||||
|
||||
python-version: '3.x'
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
cd docs
|
||||
bundle install
|
||||
|
||||
- name: Build site
|
||||
pip install mkdocs-material
|
||||
pip install mkdocs-git-revision-date-localized-plugin
|
||||
pip install mkdocstrings[python]
|
||||
- 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:
|
||||
git config --global user.name "github-actions[bot]"
|
||||
git config --global user.email "github-actions[bot]@users.noreply.github.com"
|
||||
- name: Build docs
|
||||
run: mkdocs build
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
run: |
|
||||
git checkout --orphan gh-pages
|
||||
git rm -rf .
|
||||
mv site/* .
|
||||
rm -rf site
|
||||
git add .
|
||||
git commit -m "docs: Update documentation"
|
||||
git push origin gh-pages --force
|
||||
329
README.md
329
README.md
@@ -1,305 +1,128 @@
|
||||
# 🚀 MCP Server for Home Assistant - Bringing AI-Powered Smart Homes to Life!
|
||||
# MCP Server for Home Assistant 🏠🤖
|
||||
|
||||
[](LICENSE)
|
||||
[](https://bun.sh)
|
||||
[](https://www.typescriptlang.org)
|
||||
[](#)
|
||||
[](https://jango-blockchained.github.io/homeassistant-mcp/)
|
||||
[](https://www.docker.com)
|
||||
|
||||
---
|
||||
|
||||
## Overview 🌐
|
||||
|
||||
Welcome to the **Model Context Protocol (MCP) Server for Home Assistant**! This robust platform bridges Home Assistant with cutting-edge Language Learning Models (LLMs), enabling natural language interactions and real-time automation of your smart devices. Imagine entering your home, saying:
|
||||
MCP (Model Context Protocol) Server is a lightweight integration tool for Home Assistant, providing a flexible interface for device management and automation.
|
||||
|
||||
> "Hey MCP, dim the lights and start my evening playlist,"
|
||||
## Core Features ✨
|
||||
|
||||
and watching your home transform instantly—that's the magic that MCP Server delivers!
|
||||
- 🔌 Basic device control via REST API
|
||||
- 📡 WebSocket/Server-Sent Events (SSE) for state updates
|
||||
- 🤖 Simple automation rule management
|
||||
- 🔐 JWT-based authentication
|
||||
|
||||
---
|
||||
## Prerequisites 📋
|
||||
|
||||
## Key Benefits ✨
|
||||
- 🚀 Bun runtime (v1.0.26+)
|
||||
- 🏡 Home Assistant instance
|
||||
- 🐳 Docker (optional, recommended for deployment)
|
||||
|
||||
### 🎮 Device Control & Monitoring
|
||||
- **Voice-Controlled Automation:**
|
||||
Use simple commands like "Turn on the kitchen lights" or "Set the thermostat to 22°C" without touching a switch.
|
||||
**Real-World Example:**
|
||||
In the morning, say "Good morning! Open the blinds and start the coffee machine" to kickstart your day automatically.
|
||||
## Installation 🛠️
|
||||
|
||||
- **Real-Time Communication:**
|
||||
Experience sub-100ms latency updates via Server-Sent Events (SSE) or WebSocket connections, ensuring your dashboard is always current.
|
||||
**Real-World Example:**
|
||||
Monitor energy usage instantly during peak hours and adjust remotely for efficient consumption.
|
||||
|
||||
- **Seamless Automation:**
|
||||
Create scene-based rules to synchronize multiple devices effortlessly.
|
||||
**Real-World Example:**
|
||||
For movie nights, have MCP dim the lights, adjust the sound system, and launch your favorite streaming app with just one command.
|
||||
|
||||
### 🤖 AI-Powered Enhancements
|
||||
- **Natural Language Processing (NLP):**
|
||||
Convert everyday speech into actionable commands—just say, "Prepare the house for dinner," and MCP will adjust lighting, temperature, and even play soft background music.
|
||||
|
||||
- **Predictive Automation & Suggestions:**
|
||||
Receive proactive recommendations based on usage habits and environmental trends.
|
||||
**Real-World Example:**
|
||||
When home temperature fluctuates unexpectedly, MCP suggests an optimal setting and notifies you immediately.
|
||||
|
||||
- **Anomaly Detection:**
|
||||
Continuously monitor device activity and alert you to unusual behavior, helping prevent malfunctions or potential security breaches.
|
||||
|
||||
---
|
||||
|
||||
## Architectural Overview 🏗
|
||||
|
||||
Our architecture is engineered for performance, scalability, and security. The following Mermaid diagram illustrates the data flow and component interactions:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph Client
|
||||
A["Client Application (Web/Mobile/Voice)"]
|
||||
end
|
||||
subgraph CDN
|
||||
B["CDN / Cache"]
|
||||
end
|
||||
subgraph Server
|
||||
C["Bun Native Server"]
|
||||
E["NLP Engine & Language Processing Module"]
|
||||
end
|
||||
subgraph Integration
|
||||
D["Home Assistant (Devices, Lights, Thermostats)"]
|
||||
end
|
||||
|
||||
A -->|HTTP Request| B
|
||||
B -- Cache Miss --> C
|
||||
C -->|Interpret Command| E
|
||||
E -->|Determine Action| D
|
||||
D -->|Return State/Action| C
|
||||
C -->|Response| B
|
||||
B -->|Cached/Processed Response| A
|
||||
```
|
||||
|
||||
Learn more about our architecture in the [Architecture Documentation](docs/architecture.md).
|
||||
|
||||
---
|
||||
|
||||
## Technical Stack 🔧
|
||||
|
||||
Our solution is built on a modern, high-performance stack that powers every feature:
|
||||
|
||||
- **Bun:**
|
||||
A next-generation JavaScript runtime offering rapid startup times, native TypeScript support, and high performance.
|
||||
👉 [Learn about Bun](https://bun.sh)
|
||||
|
||||
- **Bun Native Server:**
|
||||
Utilizes Bun's built-in HTTP server to efficiently process API requests with sub-100ms response times.
|
||||
👉 See the [Installation Guide](docs/getting-started/installation.md) for details.
|
||||
|
||||
- **Natural Language Processing (NLP) & LLM Integration:**
|
||||
Processes and interprets natural language commands using state-of-the-art LLMs and custom NLP modules.
|
||||
👉 Find API usage details in the [API Documentation](docs/api.md).
|
||||
|
||||
- **Home Assistant Integration:**
|
||||
Provides seamless connectivity with Home Assistant, ensuring flawless communication with your smart devices.
|
||||
👉 Refer to the [Usage Guide](docs/usage.md) for more information.
|
||||
|
||||
- **Redis Cache:**
|
||||
Enables rapid data retrieval and session persistence essential for real-time updates.
|
||||
|
||||
- **TypeScript:**
|
||||
Enhances type safety and developer productivity across the entire codebase.
|
||||
|
||||
- **JWT & Security Middleware:**
|
||||
Protects your ecosystem with JWT-based authentication, request sanitization, rate-limiting, and encryption.
|
||||
|
||||
- **Containerization with Docker:**
|
||||
Enables scalable, isolated deployments for production environments.
|
||||
|
||||
For further technical details, check out our [Documentation Index](docs/index.md).
|
||||
|
||||
---
|
||||
|
||||
## Installation 🛠
|
||||
|
||||
### Installing via Smithery
|
||||
|
||||
To install Home Assistant MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@jango-blockchained/advanced-homeassistant-mcp):
|
||||
### Docker Deployment (Recommended)
|
||||
|
||||
```bash
|
||||
npx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude
|
||||
```
|
||||
# Clone the repository
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
|
||||
### 🐳 Docker Setup (Recommended)
|
||||
# Copy and edit environment configuration
|
||||
cp .env.example .env
|
||||
# Edit .env with your Home Assistant credentials
|
||||
|
||||
For a hassle-free, containerized deployment:
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository (using a shallow copy for efficiency)
|
||||
git clone --depth 1 https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
|
||||
# 2. Configure your environment: copy the example file and edit it with your Home Assistant credentials
|
||||
cp .env.example .env # Modify .env with your Home Assistant host, tokens, etc.
|
||||
|
||||
# 3. Build and run the Docker containers
|
||||
# Build and start containers
|
||||
docker compose up -d --build
|
||||
|
||||
# 4. View real-time logs (last 50 log entries)
|
||||
docker compose logs -f --tail=50
|
||||
```
|
||||
|
||||
👉 Refer to our [Installation Guide](docs/getting-started/installation.md) for full details.
|
||||
|
||||
### 💻 Bare Metal Installation
|
||||
|
||||
For direct deployment on your host machine:
|
||||
### Bare Metal Installation
|
||||
|
||||
```bash
|
||||
# 1. Install Bun (if not already installed)
|
||||
# Install Bun
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# 2. Install project dependencies with caching support
|
||||
bun install --frozen-lockfile
|
||||
# Clone the repository
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
|
||||
# 3. Launch the server in development mode with hot-reload enabled
|
||||
bun run dev --watch
|
||||
# Install dependencies
|
||||
bun install
|
||||
|
||||
# Start the server
|
||||
bun run dev
|
||||
```
|
||||
|
||||
---
|
||||
## Basic Usage 🖥️
|
||||
|
||||
## Real-World Usage Examples 🔍
|
||||
### Device Control Example
|
||||
|
||||
### 📱 Smart Home Dashboard Integration
|
||||
Integrate MCP's real-time updates into your custom dashboard for a dynamic smart home experience:
|
||||
```typescript
|
||||
// Turn on a light
|
||||
const response = await fetch('http://localhost:3000/api/devices/light.living_room', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${token}`
|
||||
},
|
||||
body: JSON.stringify({ state: 'on' })
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light');
|
||||
### WebSocket State Updates
|
||||
|
||||
eventSource.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Real-time update:', data);
|
||||
// Update your UI dashboard, e.g., refresh a light intensity indicator.
|
||||
```typescript
|
||||
const ws = new WebSocket('ws://localhost:3000/devices');
|
||||
ws.onmessage = (event) => {
|
||||
const deviceState = JSON.parse(event.data);
|
||||
console.log('Device state updated:', deviceState);
|
||||
};
|
||||
```
|
||||
|
||||
### 🏠 Voice-Activated Control
|
||||
Utilize voice commands to trigger actions with minimal effort:
|
||||
## Current Limitations ⚠️
|
||||
|
||||
```javascript
|
||||
// Establish a WebSocket connection for real-time command processing
|
||||
const ws = new WebSocket('wss://mcp.yourha.com/ws');
|
||||
|
||||
ws.onmessage = ({ data }) => {
|
||||
const update = JSON.parse(data);
|
||||
if (update.entity_id === 'light.living_room') {
|
||||
console.log('Adjusting living room lighting based on voice command...');
|
||||
// Additional logic to update your UI or trigger further actions can go here.
|
||||
}
|
||||
};
|
||||
|
||||
// Simulate processing a voice command
|
||||
function simulateVoiceCommand(command) {
|
||||
console.log("Processing voice command:", command);
|
||||
// Integrate with your actual voice-to-text system as needed.
|
||||
}
|
||||
|
||||
simulateVoiceCommand("Turn off all the lights for bedtime");
|
||||
```
|
||||
|
||||
👉 Learn more in our [Usage Guide](docs/usage.md).
|
||||
|
||||
---
|
||||
|
||||
## Update Strategy 🔄
|
||||
|
||||
Maintain a seamless operation with zero downtime updates:
|
||||
|
||||
```bash
|
||||
# 1. Pull the latest Docker images
|
||||
docker compose pull
|
||||
|
||||
# 2. Rebuild and restart containers smoothly
|
||||
docker compose up -d --build
|
||||
|
||||
# 3. Clean up unused Docker images to free up space
|
||||
docker system prune -f
|
||||
```
|
||||
|
||||
For more details, review our [Troubleshooting & Updates](docs/troubleshooting.md).
|
||||
|
||||
---
|
||||
|
||||
## Security Features 🔐
|
||||
|
||||
We prioritize the security of your smart home with multiple layers of defense:
|
||||
- **JWT Authentication 🔑:** Secure, token-based API access to prevent unauthorized usage.
|
||||
- **Request Sanitization 🧼:** Automatic filtering and validation of API requests to combat injection attacks.
|
||||
- **Rate Limiting & Fail2Ban 🚫:** Monitors requests to prevent brute force and DDoS attacks.
|
||||
- **End-to-End Encryption 🔒:** Ensures that your commands and data remain private during transmission.
|
||||
|
||||
---
|
||||
- 🎙️ Basic voice command support (work in progress)
|
||||
- 🧠 Limited advanced NLP capabilities
|
||||
- 🔗 Minimal third-party device integration
|
||||
- 🐛 Early-stage error handling
|
||||
|
||||
## Contributing 🤝
|
||||
|
||||
We value community contributions! Here's how you can help improve MCP Server:
|
||||
1. **Fork the Repository 🍴**
|
||||
Create your own copy of the project.
|
||||
2. **Create a Feature Branch 🌿**
|
||||
1. Fork the repository
|
||||
2. Create a feature branch:
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
git checkout -b feature/your-feature
|
||||
```
|
||||
3. **Install Dependencies & Run Tests 🧪**
|
||||
3. Make your changes
|
||||
4. Run tests:
|
||||
```bash
|
||||
bun install
|
||||
bun test --coverage
|
||||
bun test
|
||||
```
|
||||
4. **Make Your Changes & Commit 📝**
|
||||
Follow the [Conventional Commits](https://www.conventionalcommits.org) guidelines.
|
||||
5. **Open a Pull Request 🔀**
|
||||
Submit your changes for review.
|
||||
5. Submit a pull request
|
||||
|
||||
Read more in our [Contribution Guidelines](docs/contributing.md).
|
||||
## Roadmap 🗺️
|
||||
|
||||
---
|
||||
- 🎤 Enhance voice command processing
|
||||
- 🔌 Improve device compatibility
|
||||
- 🤖 Expand automation capabilities
|
||||
- 🛡️ Implement more robust error handling
|
||||
|
||||
## Roadmap & Future Enhancements 🔮
|
||||
## License 📄
|
||||
|
||||
We're continuously evolving MCP Server. Upcoming features include:
|
||||
- **AI Assistant Integration (Q4 2024):**
|
||||
Smarter, context-aware voice commands and personalized automation.
|
||||
- **Predictive Automation (Q1 2025):**
|
||||
Enhanced scheduling capabilities powered by advanced AI.
|
||||
- **Enhanced Security (Q2 2024):**
|
||||
Introduction of multi-factor authentication, advanced monitoring, and rigorous encryption methods.
|
||||
- **Performance Optimizations (Q3 2024):**
|
||||
Reducing latency further, optimizing caching, and improving load balancing.
|
||||
MIT License. See [LICENSE](LICENSE) for details.
|
||||
|
||||
For more details, see our [Roadmap](docs/roadmap.md).
|
||||
## Support 🆘
|
||||
|
||||
---
|
||||
- 🐞 [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues)
|
||||
- 📖 Documentation: [Project Docs](https://jango-blockchained.github.io/homeassistant-mcp/)
|
||||
|
||||
## Community & Support 🌍
|
||||
|
||||
Your feedback and collaboration are vital! Join our community:
|
||||
- **GitHub Issues:** Report bugs or request features via our [Issues Page](https://github.com/jango-blockchained/homeassistant-mcp/issues).
|
||||
- **Discord & Slack:** Connect with fellow users and developers in real-time.
|
||||
- **Documentation:** Find comprehensive guides on the [MCP Documentation Website](https://jango-blockchained.github.io/homeassistant-mcp/).
|
||||
|
||||
---
|
||||
|
||||
## License 📜
|
||||
|
||||
This project is licensed under the MIT License. See [LICENSE](LICENSE) for full details.
|
||||
|
||||
---
|
||||
|
||||
🔋 Batteries included.
|
||||
|
||||
## MCP Client Integration
|
||||
## MCP Client Integration 🔗
|
||||
|
||||
This MCP server can be integrated with various clients that support the Model Context Protocol. Below are instructions for different client integrations:
|
||||
|
||||
### Cursor Integration
|
||||
### Cursor Integration 🖱️
|
||||
|
||||
The server can be integrated with Cursor by adding the configuration to `.cursor/config/config.json`:
|
||||
|
||||
@@ -318,7 +141,7 @@ The server can be integrated with Cursor by adding the configuration to `.cursor
|
||||
}
|
||||
```
|
||||
|
||||
### Claude Desktop Integration
|
||||
### Claude Desktop Integration 💬
|
||||
|
||||
For Claude Desktop, add the following to your Claude configuration file:
|
||||
|
||||
@@ -336,7 +159,7 @@ For Claude Desktop, add the following to your Claude configuration file:
|
||||
}
|
||||
```
|
||||
|
||||
### Cline Integration
|
||||
### Cline Integration 📟
|
||||
|
||||
For Cline-based clients, add the following configuration:
|
||||
|
||||
@@ -361,7 +184,7 @@ For Cline-based clients, add the following configuration:
|
||||
}
|
||||
```
|
||||
|
||||
### Command Line Usage
|
||||
### Command Line Usage 💻
|
||||
|
||||
#### Windows
|
||||
A CMD script is provided in the `scripts` directory. To use it:
|
||||
|
||||
@@ -1,22 +1,29 @@
|
||||
# Use Python slim image as builder
|
||||
FROM python:3.10-slim as builder
|
||||
FROM python:3.10-slim AS builder
|
||||
|
||||
# Install build dependencies
|
||||
RUN apt-get update && apt-get install -y \
|
||||
git \
|
||||
build-essential \
|
||||
portaudio19-dev \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
curl \
|
||||
wget
|
||||
|
||||
# Create and activate virtual environment
|
||||
RUN python -m venv /opt/venv
|
||||
ENV PATH="/opt/venv/bin:$PATH"
|
||||
|
||||
# Install Python dependencies with specific versions and CPU-only variants
|
||||
RUN pip install --no-cache-dir "numpy>=1.24.3,<2.0.0" && \
|
||||
pip install --no-cache-dir torch==2.1.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cpu && \
|
||||
pip install --no-cache-dir faster-whisper==0.10.0 openwakeword==0.4.0 pyaudio==0.2.14 sounddevice==0.4.6 requests==2.31.0 && \
|
||||
pip freeze > /opt/venv/requirements.txt
|
||||
RUN pip install --no-cache-dir \
|
||||
"numpy>=1.24.3,<2.0" \
|
||||
"sounddevice" \
|
||||
"openwakeword" \
|
||||
"faster-whisper" \
|
||||
"transformers" \
|
||||
"torch" \
|
||||
"torchaudio" \
|
||||
"huggingface_hub" \
|
||||
"requests" \
|
||||
"soundfile" \
|
||||
"tflite-runtime"
|
||||
|
||||
# Create final image
|
||||
FROM python:3.10-slim
|
||||
@@ -28,31 +35,48 @@ ENV PATH="/opt/venv/bin:$PATH"
|
||||
# Install audio dependencies
|
||||
RUN apt-get update && apt-get install -y \
|
||||
portaudio19-dev \
|
||||
python3-pyaudio \
|
||||
alsa-utils \
|
||||
libasound2 \
|
||||
libasound2-plugins \
|
||||
pulseaudio \
|
||||
pulseaudio-utils \
|
||||
libpulse0 \
|
||||
libportaudio2 \
|
||||
&& rm -rf /var/lib/apt/lists/* \
|
||||
&& mkdir -p /var/run/pulse /var/lib/pulse
|
||||
alsa-utils \
|
||||
curl \
|
||||
wget
|
||||
|
||||
# Create necessary directories
|
||||
RUN mkdir -p /models/wake_word /audio && \
|
||||
chown -R 1000:1000 /models /audio && \
|
||||
mkdir -p /home/user/.config/pulse && \
|
||||
chown -R 1000:1000 /home/user
|
||||
# Create necessary directories with explicit permissions
|
||||
RUN mkdir -p /models/wake_word /audio /app /models/cache /models/models--Systran--faster-whisper-base /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models \
|
||||
&& chmod -R 777 /models /audio /app /models/cache /models/models--Systran--faster-whisper-base /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models
|
||||
|
||||
# Download wake word models
|
||||
RUN wget -O /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models/alexa_v0.1.tflite \
|
||||
https://github.com/dscripka/openWakeWord/raw/main/openwakeword/resources/models/alexa_v0.1.tflite \
|
||||
&& wget -O /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models/hey_jarvis_v0.1.tflite \
|
||||
https://github.com/dscripka/openWakeWord/raw/main/openwakeword/resources/models/hey_jarvis_v0.1.tflite \
|
||||
&& chmod 644 /opt/venv/lib/python3.10/site-packages/openwakeword/resources/models/*.tflite
|
||||
|
||||
# Set environment variables for model caching
|
||||
ENV HF_HOME=/models/cache
|
||||
ENV TRANSFORMERS_CACHE=/models/cache
|
||||
ENV HUGGINGFACE_HUB_CACHE=/models/cache
|
||||
|
||||
# Copy scripts and set permissions explicitly
|
||||
COPY wake_word_detector.py /app/wake_word_detector.py
|
||||
COPY setup-audio.sh /setup-audio.sh
|
||||
|
||||
# Ensure scripts are executable by any user
|
||||
RUN chmod 755 /setup-audio.sh /app/wake_word_detector.py
|
||||
|
||||
# Create a non-root user with explicit UID and GID
|
||||
RUN addgroup --gid 1000 user && \
|
||||
adduser --uid 1000 --gid 1000 --disabled-password --gecos '' user
|
||||
|
||||
# Change ownership of directories
|
||||
RUN chown -R 1000:1000 /models /audio /app /models/cache /models/models--Systran--faster-whisper-base \
|
||||
/opt/venv/lib/python3.10/site-packages/openwakeword/resources/models
|
||||
|
||||
# Switch to non-root user
|
||||
USER user
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /app
|
||||
|
||||
# Copy the wake word detection script and audio setup script
|
||||
COPY wake_word_detector.py .
|
||||
COPY setup-audio.sh /setup-audio.sh
|
||||
RUN chmod +x /setup-audio.sh
|
||||
|
||||
# Set environment variables
|
||||
ENV WHISPER_MODEL_PATH=/models \
|
||||
WAKEWORD_MODEL_PATH=/models/wake_word \
|
||||
@@ -60,8 +84,5 @@ ENV WHISPER_MODEL_PATH=/models \
|
||||
PULSE_SERVER=unix:/run/user/1000/pulse/native \
|
||||
HOME=/home/user
|
||||
|
||||
# Run as the host user
|
||||
USER 1000:1000
|
||||
|
||||
# Start the application
|
||||
CMD ["/setup-audio.sh"]
|
||||
@@ -1,25 +1,58 @@
|
||||
#!/bin/bash
|
||||
set -e # Exit immediately if a command exits with a non-zero status
|
||||
set -x # Print commands and their arguments as they are executed
|
||||
|
||||
echo "Starting audio setup script at $(date)"
|
||||
echo "Current user: $(whoami)"
|
||||
echo "Current directory: $(pwd)"
|
||||
|
||||
# Print environment variables related to audio and speech
|
||||
echo "ENABLE_WAKE_WORD: ${ENABLE_WAKE_WORD}"
|
||||
echo "PULSE_SERVER: ${PULSE_SERVER}"
|
||||
echo "WHISPER_MODEL_PATH: ${WHISPER_MODEL_PATH}"
|
||||
|
||||
# Wait for PulseAudio socket to be available
|
||||
max_wait=30
|
||||
wait_count=0
|
||||
while [ ! -e /run/user/1000/pulse/native ]; do
|
||||
echo "Waiting for PulseAudio socket..."
|
||||
echo "Waiting for PulseAudio socket... (${wait_count}/${max_wait})"
|
||||
sleep 1
|
||||
wait_count=$((wait_count + 1))
|
||||
if [ $wait_count -ge $max_wait ]; then
|
||||
echo "ERROR: PulseAudio socket not available after ${max_wait} seconds"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
# Test PulseAudio connection
|
||||
pactl info || {
|
||||
echo "Failed to connect to PulseAudio server"
|
||||
# Verify PulseAudio connection with detailed error handling
|
||||
if ! pactl info; then
|
||||
echo "ERROR: Failed to connect to PulseAudio server"
|
||||
pactl list short modules
|
||||
pactl list short clients
|
||||
exit 1
|
||||
}
|
||||
fi
|
||||
|
||||
# List audio devices
|
||||
pactl list sources || {
|
||||
echo "Failed to list audio devices"
|
||||
# List audio devices with error handling
|
||||
if ! pactl list sources; then
|
||||
echo "ERROR: Failed to list audio devices"
|
||||
exit 1
|
||||
}
|
||||
fi
|
||||
|
||||
# Start the wake word detector
|
||||
python /app/wake_word_detector.py
|
||||
# Ensure wake word detector script is executable
|
||||
chmod +x /app/wake_word_detector.py
|
||||
|
||||
# Start the wake word detector with logging
|
||||
echo "Starting wake word detector at $(date)"
|
||||
python /app/wake_word_detector.py 2>&1 | tee /audio/wake_word_detector.log &
|
||||
wake_word_pid=$!
|
||||
|
||||
# Wait and check if the process is still running
|
||||
sleep 5
|
||||
if ! kill -0 $wake_word_pid 2>/dev/null; then
|
||||
echo "ERROR: Wake word detector process died immediately"
|
||||
cat /audio/wake_word_detector.log
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Mute the monitor to prevent feedback
|
||||
pactl set-source-mute alsa_output.pci-0000_00_1b.0.analog-stereo.monitor 1
|
||||
@@ -30,5 +63,6 @@ pactl set-source-volume alsa_input.pci-0000_00_1b.0.analog-stereo 65%
|
||||
# Set speaker volume to 40%
|
||||
pactl set-sink-volume alsa_output.pci-0000_00_1b.0.analog-stereo 40%
|
||||
|
||||
# Make the script executable
|
||||
chmod +x /setup-audio.sh
|
||||
# Keep the script running to prevent container exit
|
||||
echo "Audio setup complete. Keeping container alive."
|
||||
tail -f /dev/null
|
||||
@@ -53,8 +53,8 @@ HASS_TOKEN = os.environ.get('HASS_TOKEN')
|
||||
|
||||
def initialize_asr_model():
|
||||
"""Initialize the ASR model with retries and timeout"""
|
||||
model_path = os.environ.get('ASR_MODEL_PATH', '/models')
|
||||
model_name = os.environ.get('ASR_MODEL', 'large-v3')
|
||||
model_path = os.environ.get('WHISPER_MODEL_PATH', '/models')
|
||||
model_name = os.environ.get('WHISPER_MODEL_TYPE', 'base')
|
||||
|
||||
start_time = time.time()
|
||||
for attempt in range(MAX_MODEL_LOAD_RETRIES):
|
||||
|
||||
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.*
|
||||
|
||||
@@ -6,7 +6,7 @@ nav_order: 4
|
||||
|
||||
# Architecture Overview 🏗️
|
||||
|
||||
This document describes the architecture of the MCP Server, explaining how different components work together to provide a bridge between Home Assistant and Language Learning Models.
|
||||
This document describes the architecture of the MCP Server, explaining how different components work together to provide a bridge between Home Assistant and custom automation tools.
|
||||
|
||||
## System Architecture
|
||||
|
||||
@@ -15,17 +15,13 @@ graph TD
|
||||
subgraph "Client Layer"
|
||||
WC[Web Clients]
|
||||
MC[Mobile Clients]
|
||||
VC[Voice Assistants]
|
||||
end
|
||||
|
||||
subgraph "MCP Server"
|
||||
API[API Gateway]
|
||||
NLP[NLP Engine]
|
||||
SSE[SSE Manager]
|
||||
WS[WebSocket Server]
|
||||
CM[Command Manager]
|
||||
SC[Scene Controller]
|
||||
Cache[Redis Cache]
|
||||
end
|
||||
|
||||
subgraph "Home Assistant"
|
||||
@@ -33,251 +29,60 @@ graph TD
|
||||
Dev[Devices & Services]
|
||||
end
|
||||
|
||||
subgraph "AI Layer"
|
||||
LLM[Language Models]
|
||||
IC[Intent Classifier]
|
||||
NER[Named Entity Recognition]
|
||||
end
|
||||
|
||||
WC --> |HTTP/WS| API
|
||||
MC --> |HTTP/WS| API
|
||||
VC --> |HTTP| API
|
||||
|
||||
API --> |Events| SSE
|
||||
API --> |Real-time| WS
|
||||
API --> |Process| NLP
|
||||
|
||||
NLP --> |Query| LLM
|
||||
NLP --> |Extract| IC
|
||||
NLP --> |Identify| NER
|
||||
|
||||
CM --> |Execute| HA
|
||||
HA --> |Control| Dev
|
||||
|
||||
SSE --> |State Updates| WC
|
||||
SSE --> |State Updates| MC
|
||||
WS --> |Bi-directional| WC
|
||||
|
||||
Cache --> |Fast Access| API
|
||||
HA --> |Events| Cache
|
||||
API --> HA
|
||||
HA --> API
|
||||
```
|
||||
|
||||
## Component Details
|
||||
## Core Components
|
||||
|
||||
### 1. Client Layer
|
||||
### API Gateway
|
||||
- Handles incoming HTTP and WebSocket requests
|
||||
- Provides endpoints for device management
|
||||
- Implements basic authentication and request validation
|
||||
|
||||
The client layer consists of various interfaces that interact with the MCP Server:
|
||||
### SSE Manager
|
||||
- Manages Server-Sent Events for real-time updates
|
||||
- Broadcasts device state changes to connected clients
|
||||
|
||||
- **Web Clients**: Browser-based dashboards and control panels
|
||||
- **Mobile Clients**: Native mobile applications
|
||||
- **Voice Assistants**: Voice-enabled devices and interfaces
|
||||
### WebSocket Server
|
||||
- Provides real-time, bidirectional communication
|
||||
- Supports basic device control and state monitoring
|
||||
|
||||
### 2. MCP Server Core
|
||||
### Command Manager
|
||||
- Processes device control requests
|
||||
- Translates API commands to Home Assistant compatible formats
|
||||
|
||||
#### API Gateway
|
||||
- Handles all incoming HTTP requests
|
||||
- Manages authentication and rate limiting
|
||||
- Routes requests to appropriate handlers
|
||||
## Communication Flow
|
||||
|
||||
```typescript
|
||||
interface APIGateway {
|
||||
authenticate(): Promise<boolean>;
|
||||
rateLimit(): Promise<boolean>;
|
||||
route(request: Request): Promise<Response>;
|
||||
}
|
||||
```
|
||||
1. Client sends a request to the MCP Server API
|
||||
2. API Gateway authenticates the request
|
||||
3. Command Manager processes the request
|
||||
4. Request is forwarded to Home Assistant
|
||||
5. Response is sent back to the client via API or WebSocket
|
||||
|
||||
#### NLP Engine
|
||||
- Processes natural language commands
|
||||
- Integrates with Language Models
|
||||
- Extracts intents and entities
|
||||
## Key Design Principles
|
||||
|
||||
```typescript
|
||||
interface NLPEngine {
|
||||
processCommand(text: string): Promise<CommandIntent>;
|
||||
extractEntities(text: string): Promise<Entity[]>;
|
||||
validateIntent(intent: CommandIntent): boolean;
|
||||
}
|
||||
```
|
||||
- **Simplicity:** Lightweight, focused design
|
||||
- **Flexibility:** Easily extendable architecture
|
||||
- **Performance:** Efficient request handling
|
||||
- **Security:** Basic authentication and validation
|
||||
|
||||
#### Event Management
|
||||
- **SSE Manager**: Handles Server-Sent Events
|
||||
- **WebSocket Server**: Manages bi-directional communication
|
||||
- **Command Manager**: Processes and executes commands
|
||||
## Limitations
|
||||
|
||||
### 3. Home Assistant Integration
|
||||
- Basic device control capabilities
|
||||
- Limited advanced automation features
|
||||
- Minimal third-party integrations
|
||||
|
||||
The server maintains a robust connection to Home Assistant through:
|
||||
## Future Improvements
|
||||
|
||||
- REST API calls
|
||||
- WebSocket connections
|
||||
- Event subscriptions
|
||||
- Enhanced error handling
|
||||
- More robust authentication
|
||||
- Expanded device type support
|
||||
|
||||
```typescript
|
||||
interface HomeAssistantClient {
|
||||
connect(): Promise<void>;
|
||||
getState(entityId: string): Promise<EntityState>;
|
||||
executeCommand(command: Command): Promise<CommandResult>;
|
||||
subscribeToEvents(callback: EventCallback): Subscription;
|
||||
}
|
||||
```
|
||||
|
||||
### 4. AI Layer
|
||||
|
||||
#### Language Model Integration
|
||||
- Processes natural language input
|
||||
- Understands context and user intent
|
||||
- Generates appropriate responses
|
||||
|
||||
#### Intent Classification
|
||||
- Identifies command types
|
||||
- Extracts parameters
|
||||
- Validates requests
|
||||
|
||||
## Data Flow
|
||||
|
||||
### 1. Command Processing
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant API
|
||||
participant NLP
|
||||
participant LLM
|
||||
participant HA
|
||||
|
||||
Client->>API: Send command
|
||||
API->>NLP: Process text
|
||||
NLP->>LLM: Get intent
|
||||
LLM-->>NLP: Return structured intent
|
||||
NLP->>HA: Execute command
|
||||
HA-->>API: Return result
|
||||
API-->>Client: Send response
|
||||
```
|
||||
|
||||
### 2. Real-time Updates
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant HA
|
||||
participant Cache
|
||||
participant SSE
|
||||
participant Client
|
||||
|
||||
HA->>Cache: State change
|
||||
Cache->>SSE: Notify change
|
||||
SSE->>Client: Send update
|
||||
Note over Client: Update UI
|
||||
```
|
||||
|
||||
### 3. [SSE API](api/sse.md)
|
||||
- Event Subscriptions
|
||||
- Real-time Updates
|
||||
- Connection Management
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
1. **JWT-based Authentication**
|
||||
```typescript
|
||||
interface AuthToken {
|
||||
token: string;
|
||||
expires: number;
|
||||
scope: string[];
|
||||
}
|
||||
```
|
||||
|
||||
2. **Rate Limiting**
|
||||
```typescript
|
||||
interface RateLimit {
|
||||
window: number;
|
||||
max: number;
|
||||
current: number;
|
||||
}
|
||||
```
|
||||
|
||||
### Security Measures
|
||||
|
||||
- TLS encryption for all communications
|
||||
- Input sanitization
|
||||
- Request validation
|
||||
- Token-based authentication
|
||||
- Rate limiting
|
||||
- IP filtering
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Request --> Cache{Cache?}
|
||||
Cache -->|Hit| Response
|
||||
Cache -->|Miss| HA[Home Assistant]
|
||||
HA --> Cache
|
||||
Cache --> Response
|
||||
```
|
||||
|
||||
### Connection Management
|
||||
|
||||
- Connection pooling
|
||||
- Automatic reconnection
|
||||
- Load balancing
|
||||
- Request queuing
|
||||
|
||||
## Configuration
|
||||
|
||||
The system is highly configurable through environment variables and configuration files:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 3000
|
||||
host: '0.0.0.0'
|
||||
|
||||
homeAssistant:
|
||||
url: 'http://homeassistant:8123'
|
||||
token: 'YOUR_TOKEN'
|
||||
|
||||
security:
|
||||
jwtSecret: 'your-secret'
|
||||
rateLimit: 100
|
||||
|
||||
ai:
|
||||
model: 'gpt-4'
|
||||
temperature: 0.7
|
||||
|
||||
cache:
|
||||
ttl: 300
|
||||
maxSize: '100mb'
|
||||
```
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Docker Compose"
|
||||
MCP[MCP Server]
|
||||
Redis[Redis Cache]
|
||||
HA[Home Assistant]
|
||||
end
|
||||
|
||||
MCP --> Redis
|
||||
MCP --> HA
|
||||
```
|
||||
|
||||
### Scaling Considerations
|
||||
|
||||
- Horizontal scaling capabilities
|
||||
- Load balancing support
|
||||
- Redis cluster support
|
||||
- Multiple HA instance support
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [API Documentation](api/index.md)
|
||||
- [Installation Guide](getting-started/installation.md)
|
||||
- [Contributing Guidelines](contributing.md)
|
||||
- [Troubleshooting](troubleshooting.md)
|
||||
*Architecture is subject to change as the project evolves.*
|
||||
@@ -6,249 +6,119 @@ nav_order: 5
|
||||
|
||||
# Contributing Guide 🤝
|
||||
|
||||
Thank you for your interest in contributing to the MCP Server project! This guide will help you get started with contributing to the project.
|
||||
Thank you for your interest in contributing to the MCP Server project!
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you begin, ensure you have:
|
||||
|
||||
- [Bun](https://bun.sh) >= 1.0.26
|
||||
- [Node.js](https://nodejs.org) >= 18
|
||||
- [Docker](https://www.docker.com) (optional, for containerized development)
|
||||
- A running Home Assistant instance for testing
|
||||
- Home Assistant instance
|
||||
- Basic understanding of TypeScript
|
||||
|
||||
### Development Setup
|
||||
|
||||
1. Fork and clone the repository:
|
||||
1. Fork the repository
|
||||
2. Clone your fork:
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/advanced-homeassistant-mcp.git
|
||||
cd advanced-homeassistant-mcp
|
||||
git clone https://github.com/YOUR_USERNAME/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
3. Install dependencies:
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
3. Set up your development environment:
|
||||
4. Configure environment:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your Home Assistant details
|
||||
```
|
||||
|
||||
4. Start the development server:
|
||||
```bash
|
||||
bun run dev
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Branch Naming Convention
|
||||
### Branch Naming
|
||||
|
||||
- `feature/` - New features
|
||||
- `fix/` - Bug fixes
|
||||
- `docs/` - Documentation updates
|
||||
- `refactor/` - Code refactoring
|
||||
- `test/` - Test improvements
|
||||
|
||||
Example:
|
||||
```bash
|
||||
git checkout -b feature/voice-commands
|
||||
git checkout -b feature/device-control-improvements
|
||||
```
|
||||
|
||||
### Commit Messages
|
||||
|
||||
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
|
||||
Follow simple, clear commit messages:
|
||||
|
||||
```
|
||||
type(scope): description
|
||||
type: brief description
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
[optional detailed explanation]
|
||||
```
|
||||
|
||||
Types:
|
||||
- `feat:` - New features
|
||||
- `fix:` - Bug fixes
|
||||
- `docs:` - Documentation changes
|
||||
- `style:` - Code style changes (formatting, etc.)
|
||||
- `refactor:` - Code refactoring
|
||||
- `test:` - Test updates
|
||||
- `chore:` - Maintenance tasks
|
||||
- `feat:` - New feature
|
||||
- `fix:` - Bug fix
|
||||
- `docs:` - Documentation
|
||||
- `chore:` - Maintenance
|
||||
|
||||
Examples:
|
||||
```bash
|
||||
feat(api): add voice command endpoint
|
||||
fix(sse): resolve connection timeout issue
|
||||
docs(readme): update installation instructions
|
||||
```
|
||||
### Code Style
|
||||
|
||||
### Testing
|
||||
- Use TypeScript
|
||||
- Follow existing code structure
|
||||
- Keep changes focused and minimal
|
||||
|
||||
Run tests before submitting your changes:
|
||||
## Testing
|
||||
|
||||
Run tests before submitting:
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
bun test
|
||||
|
||||
# Run specific test file
|
||||
bun test test/api/command.test.ts
|
||||
|
||||
# Run tests with coverage
|
||||
bun test --coverage
|
||||
```
|
||||
|
||||
### Code Style
|
||||
|
||||
We use ESLint and Prettier for code formatting:
|
||||
|
||||
```bash
|
||||
# Check code style
|
||||
bun run lint
|
||||
|
||||
# Fix code style issues
|
||||
bun run lint:fix
|
||||
# Run specific test
|
||||
bun test test/api/control.test.ts
|
||||
```
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. **Update Documentation**
|
||||
- Add/update relevant documentation
|
||||
- Include inline code comments where necessary
|
||||
- Update API documentation if endpoints change
|
||||
|
||||
2. **Write Tests**
|
||||
- Add tests for new features
|
||||
- Update existing tests if needed
|
||||
- Ensure all tests pass
|
||||
|
||||
3. **Create Pull Request**
|
||||
- Fill out the PR template
|
||||
- Link related issues
|
||||
- Provide clear description of changes
|
||||
|
||||
4. **Code Review**
|
||||
- Address review comments
|
||||
- Keep discussions focused
|
||||
- Be patient and respectful
|
||||
1. Ensure tests pass
|
||||
2. Update documentation if needed
|
||||
3. Provide clear description of changes
|
||||
|
||||
### PR Template
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of the changes
|
||||
Brief explanation of the changes
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Breaking change
|
||||
- [ ] Documentation update
|
||||
|
||||
## How Has This Been Tested?
|
||||
Describe your test process
|
||||
|
||||
## Checklist
|
||||
- [ ] Tests added/updated
|
||||
- [ ] Documentation updated
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] All tests passing
|
||||
## Testing
|
||||
Describe how you tested these changes
|
||||
```
|
||||
|
||||
## Development Guidelines
|
||||
## Reporting Issues
|
||||
|
||||
### Code Organization
|
||||
- Use GitHub Issues
|
||||
- Provide clear, reproducible steps
|
||||
- Include environment details
|
||||
|
||||
```
|
||||
src/
|
||||
├── api/ # API endpoints
|
||||
├── core/ # Core functionality
|
||||
├── models/ # Data models
|
||||
├── services/ # Business logic
|
||||
├── utils/ # Utility functions
|
||||
└── types/ # TypeScript types
|
||||
```
|
||||
## Code of Conduct
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Type Safety**
|
||||
```typescript
|
||||
// Use explicit types
|
||||
interface CommandRequest {
|
||||
command: string;
|
||||
parameters?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
function processCommand(request: CommandRequest): Promise<CommandResponse> {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
2. **Error Handling**
|
||||
```typescript
|
||||
try {
|
||||
await processCommand(request);
|
||||
} catch (error) {
|
||||
if (error instanceof ValidationError) {
|
||||
// Handle validation errors
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
```
|
||||
|
||||
3. **Async/Await**
|
||||
```typescript
|
||||
// Prefer async/await over promises
|
||||
async function handleRequest() {
|
||||
const result = await processData();
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
### API Documentation
|
||||
|
||||
Update API documentation when adding/modifying endpoints:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Process a voice command
|
||||
* @param command - The voice command to process
|
||||
* @returns Promise<CommandResult>
|
||||
* @throws {ValidationError} If command is invalid
|
||||
*/
|
||||
async function processVoiceCommand(command: string): Promise<CommandResult> {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
### README Updates
|
||||
|
||||
Keep the README up to date with:
|
||||
- New features
|
||||
- Changed requirements
|
||||
- Updated examples
|
||||
- Modified configuration
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Check [Discussions](https://github.com/jango-blockchained/advanced-homeassistant-mcp/discussions)
|
||||
- Review existing [Issues](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues)
|
||||
|
||||
## Community Guidelines
|
||||
|
||||
We expect all contributors to:
|
||||
|
||||
- Be respectful and inclusive
|
||||
- Be respectful
|
||||
- Focus on constructive feedback
|
||||
- Help maintain a positive environment
|
||||
- Follow our code style guidelines
|
||||
- Write clear documentation
|
||||
- Test their code thoroughly
|
||||
|
||||
## License
|
||||
## Resources
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the MIT License.
|
||||
- [API Documentation](api.md)
|
||||
- [Troubleshooting Guide](troubleshooting.md)
|
||||
|
||||
*Thank you for contributing!*
|
||||
@@ -4,31 +4,25 @@ title: Home
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# 🚀 MCP Server for Home Assistant
|
||||
# 🏠 MCP Server for Home Assistant
|
||||
|
||||
Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating AI-powered natural language processing into your Home Assistant setup.
|
||||
Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating a lightweight automation tool with your Home Assistant setup.
|
||||
|
||||
## What is MCP Server?
|
||||
|
||||
MCP Server is a bridge between Home Assistant and Language Learning Models (LLMs), enabling natural language interactions and real-time automation of your smart devices. It allows you to control your home automation setup using natural language commands while maintaining high performance and security.
|
||||
MCP Server is a bridge between Home Assistant and custom automation tools, enabling basic device control and real-time monitoring of your smart home environment. It provides a flexible interface for managing and interacting with your home automation setup.
|
||||
|
||||
## Key Features
|
||||
|
||||
### 🎮 Device Control & Monitoring
|
||||
- Voice-controlled automation
|
||||
- Real-time updates via SSE/WebSocket
|
||||
- Scene-based automation rules
|
||||
|
||||
### 🤖 AI-Powered Features
|
||||
- Natural Language Processing (NLP)
|
||||
- Predictive automation
|
||||
- Anomaly detection
|
||||
### 🎮 Device Control
|
||||
- Basic REST API for device management
|
||||
- WebSocket and Server-Sent Events (SSE) for real-time updates
|
||||
- Simple automation rule support
|
||||
|
||||
### 🛡️ Security & Performance
|
||||
- JWT authentication
|
||||
- Request sanitization
|
||||
- Sub-100ms latency
|
||||
- Rate limiting
|
||||
- Basic request validation
|
||||
- Lightweight server design
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
@@ -37,19 +31,18 @@ MCP Server is a bridge between Home Assistant and Language Learning Models (LLMs
|
||||
- [Quick Start Tutorial](getting-started/quickstart.md) - Basic usage examples
|
||||
|
||||
### Core Documentation
|
||||
- [API Documentation](api/index.md) - Complete API reference
|
||||
- [Architecture Overview](architecture.md) - System design and components
|
||||
- [API Documentation](api/index.md) - API reference
|
||||
- [Architecture Overview](architecture.md) - System design
|
||||
- [Contributing Guidelines](contributing.md) - How to contribute
|
||||
- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
|
||||
- [Troubleshooting Guide](troubleshooting.md) - Common issues
|
||||
|
||||
## Support
|
||||
|
||||
If you need help or want to report issues:
|
||||
Need help or want to report issues?
|
||||
|
||||
- [GitHub Issues](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues)
|
||||
- [GitHub Discussions](https://github.com/jango-blockchained/advanced-homeassistant-mcp/discussions)
|
||||
- [Contributing Guidelines](contributing.md)
|
||||
- [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues)
|
||||
- [GitHub Discussions](https://github.com/jango-blockchained/homeassistant-mcp/discussions)
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License. See the [LICENSE](https://github.com/jango-blockchained/advanced-homeassistant-mcp/blob/main/LICENSE) file for details.
|
||||
This project is licensed under the MIT License. See the [LICENSE](https://github.com/jango-blockchained/homeassistant-mcp/blob/main/LICENSE) file for details.
|
||||
@@ -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.*
|
||||
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)
|
||||
61
mkdocs.yml
61
mkdocs.yml
@@ -1,23 +1,19 @@
|
||||
site_name: Home Assistant MCP
|
||||
site_description: A bridge between Home Assistant and Language Learning Models
|
||||
site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp/
|
||||
repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
|
||||
repo_name: jango-blockchained/advanced-homeassistant-mcp
|
||||
site_name: Claude Desktop
|
||||
site_url: https://your-username.github.io/your-repo-name
|
||||
repo_url: https://github.com/your-username/your-repo-name
|
||||
|
||||
theme:
|
||||
name: material
|
||||
logo: assets/images/logo.png
|
||||
favicon: assets/images/favicon.ico
|
||||
palette:
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
- scheme: default
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Switch to dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
- scheme: slate
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
@@ -34,39 +30,15 @@ theme:
|
||||
- content.code.copy
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- attr_list
|
||||
- def_list
|
||||
- footnotes
|
||||
- meta
|
||||
- toc:
|
||||
permalink: true
|
||||
- pymdownx.arithmatex:
|
||||
generic: true
|
||||
- pymdownx.betterem:
|
||||
smart_enable: all
|
||||
- pymdownx.caret
|
||||
- pymdownx.details
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.keys
|
||||
- pymdownx.magiclink
|
||||
- pymdownx.mark
|
||||
- pymdownx.smartsymbols
|
||||
- pymdownx.superfences:
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- pymdownx.tilde
|
||||
- pymdownx.snippets
|
||||
- pymdownx.superfences
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- attr_list
|
||||
- md_in_html
|
||||
|
||||
plugins:
|
||||
- search
|
||||
@@ -81,13 +53,17 @@ plugins:
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Usage: usage.md
|
||||
- API: api.md
|
||||
- Configuration:
|
||||
- Claude Desktop Config: claude_desktop_config.md
|
||||
- Cline Config: cline_config.md
|
||||
- Getting Started:
|
||||
- Overview: getting-started.md
|
||||
- Installation: getting-started/installation.md
|
||||
- Configuration: getting-started/configuration.md
|
||||
- Docker Setup: getting-started/docker.md
|
||||
- Quick Start: getting-started/quickstart.md
|
||||
- Usage: usage.md
|
||||
- API Reference:
|
||||
- Overview: api/index.md
|
||||
- Core API: api.md
|
||||
@@ -136,6 +112,9 @@ extra:
|
||||
property: !ENV GOOGLE_ANALYTICS_KEY
|
||||
|
||||
extra_css:
|
||||
- assets/stylesheets/extra.css
|
||||
- stylesheets/extra.css
|
||||
|
||||
extra_javascript:
|
||||
- javascripts/extra.js
|
||||
|
||||
copyright: Copyright © 2024 Jango Blockchained
|
||||
@@ -86,12 +86,14 @@ export const controlTool: Tool = {
|
||||
}),
|
||||
execute: async (params: CommandParams) => {
|
||||
try {
|
||||
const domain = params.entity_id.split(
|
||||
".",
|
||||
)[0] as keyof typeof DomainSchema.Values;
|
||||
const domain = params.entity_id.split(".")[0];
|
||||
|
||||
if (!Object.values(DomainSchema.Values).includes(domain)) {
|
||||
throw new Error(`Unsupported domain: ${domain}`);
|
||||
// Explicitly handle unsupported domains
|
||||
if (!['light', 'climate', 'switch', 'cover', 'contact'].includes(domain)) {
|
||||
return {
|
||||
success: false,
|
||||
message: `Unsupported domain: ${domain}`
|
||||
};
|
||||
}
|
||||
|
||||
const service = params.command;
|
||||
@@ -171,14 +173,23 @@ export const controlTool: Tool = {
|
||||
);
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(
|
||||
`Failed to execute ${service} for ${params.entity_id}: ${response.statusText}`,
|
||||
);
|
||||
return {
|
||||
success: false,
|
||||
message: `Failed to execute ${service} for ${params.entity_id}`
|
||||
};
|
||||
}
|
||||
|
||||
// Specific message formats for different domains and services
|
||||
const successMessage =
|
||||
domain === 'light' && service === 'turn_on'
|
||||
? `Successfully executed turn_on for ${params.entity_id}` :
|
||||
domain === 'climate' && service === 'set_temperature'
|
||||
? `Successfully executed set_temperature for ${params.entity_id}` :
|
||||
`Command ${service} executed successfully on ${params.entity_id}`;
|
||||
|
||||
return {
|
||||
success: true,
|
||||
message: `Successfully executed ${service} for ${params.entity_id}`,
|
||||
message: successMessage,
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
|
||||
@@ -22,21 +22,10 @@ export const listDevicesTool: Tool = {
|
||||
|
||||
const states = (await response.json()) as HassState[];
|
||||
const devices: Record<string, HassState[]> = {
|
||||
light: [],
|
||||
climate: []
|
||||
light: states.filter(state => state.entity_id.startsWith('light.')),
|
||||
climate: states.filter(state => state.entity_id.startsWith('climate.'))
|
||||
};
|
||||
|
||||
// Group devices by domain with specific order
|
||||
states.forEach((state) => {
|
||||
const [domain] = state.entity_id.split(".");
|
||||
|
||||
// Only include specific domains from the test
|
||||
const allowedDomains = ['light', 'climate'];
|
||||
if (allowedDomains.includes(domain)) {
|
||||
devices[domain].push(state);
|
||||
}
|
||||
});
|
||||
|
||||
return {
|
||||
success: true,
|
||||
devices,
|
||||
|
||||
Reference in New Issue
Block a user