Compare commits
7 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
345a5888d9 | ||
|
|
d6a5771e01 | ||
|
|
5f4ddfbd88 | ||
|
|
c11b40da9e | ||
|
|
3a54766b61 | ||
|
|
8b1948ce30 | ||
|
|
38ee5368d1 |
64
.github/workflows/deploy-docs.yml
vendored
Normal file
64
.github/workflows/deploy-docs.yml
vendored
Normal file
@@ -0,0 +1,64 @@
|
||||
name: Deploy Documentation to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- '.github/workflows/deploy-docs.yml'
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# Allow only one concurrent deployment
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Ruby
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: '3.2'
|
||||
bundler-cache: true
|
||||
cache-version: 0
|
||||
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v4
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
cd docs
|
||||
bundle install
|
||||
|
||||
- name: Build site
|
||||
run: |
|
||||
cd docs
|
||||
bundle exec jekyll build
|
||||
env:
|
||||
JEKYLL_ENV: production
|
||||
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: docs/_site
|
||||
|
||||
deploy:
|
||||
needs: build
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
215
README.md
215
README.md
@@ -1,11 +1,153 @@
|
||||
# Model Context Protocol (MCP) Server for Home Assistant
|
||||
# 🚀 Model Context Protocol (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.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[](https://jango-blockchained.github.io/homeassistant-mcp/)
|
||||
|
||||
|
||||
## 🌟 Key Benefits
|
||||
|
||||
### 🎮 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 🎭
|
||||
|
||||
### 🤖 AI-Powered Features
|
||||
- Natural language processing for commands
|
||||
- Predictive automation suggestions
|
||||
- Anomaly detection in device behavior
|
||||
|
||||
## 🏗 Architecture Overview
|
||||
|
||||
```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]
|
||||
```
|
||||
|
||||
## 🛠 Installation
|
||||
|
||||
### 🐳 Docker Setup (Recommended)
|
||||
|
||||
```bash
|
||||
# 1. Clone repo with caching
|
||||
git clone --depth 1 https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
|
||||
# 2. Configure environment
|
||||
cp .env.example .env # Edit with your HA details 🔧
|
||||
|
||||
# 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
|
||||
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
|
||||
|
||||
```bash
|
||||
# Check service health 🩺
|
||||
docker compose ps
|
||||
|
||||
# Test API endpoints 🔌
|
||||
curl -I http://localhost:3000/healthcheck # Should return 200 ✅
|
||||
|
||||
# Inspect cache status 💾
|
||||
docker exec mcp_redis redis-cli info memory
|
||||
```
|
||||
|
||||
## 🔮 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
|
||||
|
||||
@@ -48,58 +190,7 @@ The MCP Server is built with scalability, resilience, and security in mind:
|
||||
- **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) (if available)._
|
||||
|
||||
## Installation
|
||||
|
||||
### Basic Setup
|
||||
|
||||
1. **Install Bun:** If Bun is not installed:
|
||||
```bash
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
```
|
||||
|
||||
2. **Clone the Repository:**
|
||||
```bash
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
3. **Install Dependencies:**
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
4. **Build the Project:**
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
|
||||
### Docker Setup (Recommended)
|
||||
|
||||
1. **Clone the Repository:**
|
||||
```bash
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
2. **Configure Environment:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
Customize the `.env` file with your Home Assistant configuration.
|
||||
|
||||
3. **Deploy with Docker Compose:**
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
- View logs: `docker compose logs -f`
|
||||
- Stop the server: `docker compose down`
|
||||
|
||||
4. **Update the Application:**
|
||||
```bash
|
||||
git pull && docker compose up -d --build
|
||||
```
|
||||
For a deeper dive into the system architecture, please refer to our [Architecture Documentation](docs/architecture.md).
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -118,10 +209,10 @@ eventSource.onmessage = (event) => {
|
||||
|
||||
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.md](docs/TROUBLESHOOTING.md)
|
||||
- **Architecture Details:** [Architecture Documentation](docs/ARCHITECTURE.md) _(if available)_
|
||||
- **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
|
||||
|
||||
@@ -160,7 +251,7 @@ The MCP Server is under active development and improvement. Planned enhancements
|
||||
- **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) (if available)._
|
||||
For additional details, check out our [Roadmap](docs/roadmap.md).
|
||||
|
||||
## Community & Support
|
||||
|
||||
@@ -189,7 +280,7 @@ We welcome your contributions! To get started:
|
||||
```
|
||||
5. Commit and push your changes, then open a Pull Request.
|
||||
|
||||
_For detailed guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)._
|
||||
For detailed guidelines, see [Contributing Guide](docs/contributing.md).
|
||||
|
||||
## Troubleshooting & FAQ
|
||||
|
||||
@@ -199,7 +290,7 @@ _For detailed guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)._
|
||||
- **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.
|
||||
|
||||
_For more troubleshooting details, refer to [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)._
|
||||
For more troubleshooting details, refer to [Troubleshooting Guide](docs/troubleshooting.md).
|
||||
|
||||
### Frequently Asked Questions
|
||||
|
||||
@@ -221,7 +312,7 @@ This project is licensed under the MIT License. See [LICENSE](LICENSE) for the f
|
||||
|
||||
## Documentation
|
||||
|
||||
Full documentation is available at: https://yourusername.github.io/your-repo-name/
|
||||
Full documentation is available at: [https://jango-blockchained.github.io/homeassistant-mcp/](https://jango-blockchained.github.io/homeassistant-mcp/)
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
||||
@@ -11,3 +11,7 @@ platforms :mingw, :x64_mingw, :mswin, :jruby do
|
||||
gem "tzinfo", ">= 1"
|
||||
gem "tzinfo-data"
|
||||
end
|
||||
|
||||
# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
|
||||
# do not have a Java counterpart.
|
||||
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
|
||||
@@ -1,60 +0,0 @@
|
||||
# Home Assistant MCP Documentation
|
||||
|
||||
Welcome to the Home Assistant MCP (Master Control Program) documentation. This documentation provides comprehensive information about setting up, configuring, and using the Home Assistant MCP.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Getting Started](./getting-started.md)
|
||||
- Installation
|
||||
- Configuration
|
||||
- First Steps
|
||||
|
||||
2. [API Reference](./API.md)
|
||||
- REST API Endpoints
|
||||
- Authentication
|
||||
- Error Handling
|
||||
|
||||
3. [SSE (Server-Sent Events)](./SSE_API.md)
|
||||
- Event Subscriptions
|
||||
- Real-time Updates
|
||||
- Connection Management
|
||||
|
||||
4. [Tools](./tools/README.md)
|
||||
- Device Control
|
||||
- Automation Management
|
||||
- Add-on Management
|
||||
- Package Management
|
||||
|
||||
5. [Configuration](./configuration/README.md)
|
||||
- Environment Variables
|
||||
- Security Settings
|
||||
- Performance Tuning
|
||||
|
||||
6. [Development](./development/README.md)
|
||||
- Project Structure
|
||||
- Contributing Guidelines
|
||||
- Testing
|
||||
|
||||
7. [Troubleshooting](./troubleshooting.md)
|
||||
- Common Issues
|
||||
- Debugging
|
||||
- FAQ
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [GitHub Repository](https://github.com/yourusername/homeassistant-mcp)
|
||||
- [Issue Tracker](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||
- [Change Log](./CHANGELOG.md)
|
||||
- [Security Policy](./SECURITY.md)
|
||||
|
||||
## Support
|
||||
|
||||
If you need help or have questions:
|
||||
|
||||
1. Check the [Troubleshooting Guide](./troubleshooting.md)
|
||||
2. Search existing [Issues](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||
3. Create a new issue if your problem isn't already reported
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.
|
||||
@@ -1,51 +0,0 @@
|
||||
# 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 artifact and will be updated regularly as new features are planned and developed.
|
||||
|
||||
## Near-Term Goals
|
||||
|
||||
- **Advanced Automation Capabilities:**
|
||||
- Integrate more sophisticated automation rules with conditional logic and multi-step execution.
|
||||
- Introduce a visual automation builder to simplify rule creation.
|
||||
|
||||
- **Enhanced Security Features:**
|
||||
- Implement multi-factor authentication for critical actions.
|
||||
- Strengthen encryption methods and data handling practices.
|
||||
- Expand monitoring and alerting for potential security breaches.
|
||||
|
||||
- **Performance Optimizations:**
|
||||
- Refine the server's resource utilization to reduce latency.
|
||||
- Optimize real-time data streaming via SSE for higher throughput.
|
||||
- Introduce advanced caching mechanisms for frequently requested data.
|
||||
|
||||
## Mid-Term Goals
|
||||
|
||||
- **User Interface Improvements:**
|
||||
- Develop an intuitive, web-based dashboard for easier device management and monitoring.
|
||||
- Provide real-time analytics and performance metrics in the dashboard.
|
||||
|
||||
- **Expanded Integrations:**
|
||||
- Support a broader range of smart home devices and brands.
|
||||
- Integrate with additional home automation platforms and third-party services.
|
||||
|
||||
- **Developer Experience Enhancements:**
|
||||
- Improve documentation and developer tooling.
|
||||
- Streamline contribution guidelines and testing setups.
|
||||
|
||||
## Long-Term Vision
|
||||
|
||||
- **Ecosystem Expansion:**
|
||||
- Build a modular plugin system that allows community-driven extensions and integrations.
|
||||
- Enable seamless integration with future technologies in the smart home and AI domains.
|
||||
|
||||
- **Scalability and Resilience:**
|
||||
- Architect the system to support large-scale deployments across multiple instances.
|
||||
- Incorporate advanced load balancing and failover mechanisms.
|
||||
|
||||
## How to Follow the Roadmap
|
||||
|
||||
- **Community Involvement:** We encourage community feedback and contributions to help refine and prioritize our roadmap.
|
||||
- **Regular Updates:** This document is regularly updated with new goals, milestones, and completed tasks.
|
||||
- **Transparency:** Check the project's GitHub repository and issues for ongoing discussions and updates related to roadmap items.
|
||||
|
||||
*This roadmap is intended to serve as a guide and may evolve based on community needs, technological advancements, and strategic priorities.*
|
||||
@@ -16,7 +16,39 @@ header_pages:
|
||||
- index.md
|
||||
- getting-started.md
|
||||
- api.md
|
||||
- usage.md
|
||||
- tools/tools.md
|
||||
- development/development.md
|
||||
- troubleshooting.md
|
||||
- contributing.md
|
||||
- roadmap.md
|
||||
|
||||
# Collections
|
||||
collections:
|
||||
tools:
|
||||
output: true
|
||||
permalink: /:collection/:name
|
||||
development:
|
||||
output: true
|
||||
permalink: /:collection/:name
|
||||
|
||||
# Default layouts
|
||||
defaults:
|
||||
- scope:
|
||||
path: ""
|
||||
type: "pages"
|
||||
values:
|
||||
layout: "default"
|
||||
- scope:
|
||||
path: "tools"
|
||||
type: "tools"
|
||||
values:
|
||||
layout: "default"
|
||||
- scope:
|
||||
path: "development"
|
||||
type: "development"
|
||||
values:
|
||||
layout: "default"
|
||||
|
||||
# Exclude files from processing
|
||||
exclude:
|
||||
|
||||
401
docs/api.md
401
docs/api.md
@@ -1,4 +1,290 @@
|
||||
# API Reference
|
||||
# 🚀 Home Assistant MCP API Documentation
|
||||
|
||||
 
|
||||
|
||||
## 🌟 Quick Start
|
||||
|
||||
```bash
|
||||
# Get API schema with caching
|
||||
curl -X GET http://localhost:3000/mcp \
|
||||
-H "Cache-Control: max-age=3600" # Cache for 1 hour
|
||||
```
|
||||
|
||||
## 🔌 Core Functions ⚙️
|
||||
|
||||
### State Management (`/api/state`)
|
||||
```http
|
||||
GET /api/state?cache=true # Enable client-side caching
|
||||
POST /api/state
|
||||
```
|
||||
|
||||
**Example Request:**
|
||||
```json
|
||||
{
|
||||
"context": "living_room",
|
||||
"state": {
|
||||
"lights": "on",
|
||||
"temperature": 22
|
||||
},
|
||||
"_cache": { // Optional caching config
|
||||
"ttl": 300, // 5 minutes
|
||||
"tags": ["lights", "climate"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## ⚡ Action Endpoints
|
||||
|
||||
### Execute Action with Cache Validation
|
||||
```http
|
||||
POST /api/action
|
||||
If-None-Match: "etag_value" // Prevent duplicate actions
|
||||
```
|
||||
|
||||
**Batch Processing:**
|
||||
```json
|
||||
{
|
||||
"actions": [
|
||||
{ "action": "🌞 Morning Routine", "params": { "brightness": 80 } },
|
||||
{ "action": "❄️ AC Control", "params": { "temp": 21 } }
|
||||
],
|
||||
"_parallel": true // Execute actions concurrently
|
||||
}
|
||||
```
|
||||
|
||||
## 🔍 Query Functions
|
||||
|
||||
### Available Actions with ETag
|
||||
```http
|
||||
GET /api/actions
|
||||
ETag: "a1b2c3d4" // Client-side cache validation
|
||||
```
|
||||
|
||||
**Response Headers:**
|
||||
```
|
||||
Cache-Control: public, max-age=86400 // 24-hour cache
|
||||
ETag: "a1b2c3d4"
|
||||
```
|
||||
|
||||
## 🌐 WebSocket Events
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('wss://ha-mcp/ws');
|
||||
ws.onmessage = ({ data }) => {
|
||||
const event = JSON.parse(data);
|
||||
if(event.type === 'STATE_UPDATE') {
|
||||
updateUI(event.payload); // 🎨 Real-time UI sync
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 🗃️ Caching Strategies
|
||||
|
||||
### Client-Side Caching
|
||||
```http
|
||||
GET /api/devices
|
||||
Cache-Control: max-age=300, stale-while-revalidate=60
|
||||
```
|
||||
|
||||
### Server-Side Cache-Control
|
||||
```typescript
|
||||
// Example middleware configuration
|
||||
app.use(
|
||||
cacheMiddleware({
|
||||
ttl: 60 * 5, // 5 minutes
|
||||
paths: ['/api/devices', '/mcp'],
|
||||
vary: ['Authorization'] // User-specific caching
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
## ❌ Error Handling
|
||||
|
||||
**429 Too Many Requests:**
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "RATE_LIMITED",
|
||||
"message": "Slow down! 🐢",
|
||||
"retry_after": 30,
|
||||
"docs": "https://ha-mcp/docs/rate-limits"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🚦 Rate Limiting Tiers
|
||||
|
||||
| Tier | Requests/min | Features |
|
||||
|---------------|--------------|------------------------|
|
||||
| Guest | 10 | Basic read-only |
|
||||
| User | 100 | Full access |
|
||||
| Power User | 500 | Priority queue |
|
||||
| Integration | 1000 | Bulk operations |
|
||||
|
||||
## 🛠️ Example Usage
|
||||
|
||||
### Smart Cache Refresh
|
||||
```javascript
|
||||
async function getDevices() {
|
||||
const response = await fetch('/api/devices', {
|
||||
headers: {
|
||||
'If-None-Match': localStorage.getItem('devicesETag')
|
||||
}
|
||||
});
|
||||
|
||||
if(response.status === 304) { // Not Modified
|
||||
return JSON.parse(localStorage.devicesCache);
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
localStorage.setItem('devicesETag', response.headers.get('ETag'));
|
||||
localStorage.setItem('devicesCache', JSON.stringify(data));
|
||||
return data;
|
||||
}
|
||||
```
|
||||
|
||||
## 🔒 Security Middleware (Enhanced)
|
||||
|
||||
### Cache-Aware Rate Limiting
|
||||
```typescript
|
||||
app.use(
|
||||
rateLimit({
|
||||
windowMs: 15 * 60 * 1000, // 15 minutes
|
||||
max: 100, // Limit each IP to 100 requests per window
|
||||
cache: new RedisStore(), // Distributed cache
|
||||
keyGenerator: (req) => {
|
||||
return `${req.ip}-${req.headers.authorization}`;
|
||||
}
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
### Security Headers
|
||||
```http
|
||||
Content-Security-Policy: default-src 'self';
|
||||
Strict-Transport-Security: max-age=31536000;
|
||||
X-Content-Type-Options: nosniff;
|
||||
Cache-Control: public, max-age=600;
|
||||
ETag: "abc123"
|
||||
```
|
||||
|
||||
## 📘 Best Practices
|
||||
|
||||
1. **Cache Wisely:** Use `ETag` and `Cache-Control` headers for state data
|
||||
2. **Batch Operations:** Combine requests using `/api/actions/batch`
|
||||
3. **WebSocket First:** Prefer real-time updates over polling
|
||||
4. **Error Recovery:** Implement exponential backoff with jitter
|
||||
5. **Cache Invalidation:** Use tags for bulk invalidation
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Client] -->|Cached Request| B{CDN}
|
||||
B -->|Cache Hit| C[Return 304]
|
||||
B -->|Cache Miss| D[Origin Server]
|
||||
D -->|Response| B
|
||||
B -->|Response| A
|
||||
```
|
||||
|
||||
> Pro Tip: Use `curl -I` to inspect cache headers! 🔍
|
||||
|
||||
## Device Control
|
||||
|
||||
### Common Entity Controls
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "control",
|
||||
"command": "turn_on", // Options: "turn_on", "turn_off", "toggle"
|
||||
"entity_id": "light.living_room"
|
||||
}
|
||||
```
|
||||
|
||||
### Light Control
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "control",
|
||||
"command": "turn_on",
|
||||
"entity_id": "light.living_room",
|
||||
"brightness": 128,
|
||||
"color_temp": 4000,
|
||||
"rgb_color": [255, 0, 0]
|
||||
}
|
||||
```
|
||||
|
||||
## Add-on Management
|
||||
|
||||
### List Available Add-ons
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "addon",
|
||||
"action": "list"
|
||||
}
|
||||
```
|
||||
|
||||
### Install Add-on
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "addon",
|
||||
"action": "install",
|
||||
"slug": "core_configurator",
|
||||
"version": "5.6.0"
|
||||
}
|
||||
```
|
||||
|
||||
### Manage Add-on State
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "addon",
|
||||
"action": "start", // Options: "start", "stop", "restart"
|
||||
"slug": "core_configurator"
|
||||
}
|
||||
```
|
||||
|
||||
## Package Management
|
||||
|
||||
### List HACS Packages
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "package",
|
||||
"action": "list",
|
||||
"category": "integration" // Options: "integration", "plugin", "theme", "python_script", "appdaemon", "netdaemon"
|
||||
}
|
||||
```
|
||||
|
||||
### Install Package
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "package",
|
||||
"action": "install",
|
||||
"category": "integration",
|
||||
"repository": "hacs/integration",
|
||||
"version": "1.32.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Automation Management
|
||||
|
||||
For automation management details and endpoints, please refer to the [Tools Documentation](tools/tools.md).
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Validate and sanitize all user inputs.
|
||||
- Enforce rate limiting to prevent abuse.
|
||||
- Apply proper security headers.
|
||||
- Gracefully handle errors based on the environment.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you experience issues with the API:
|
||||
- Verify the endpoint and request payload.
|
||||
- Check authentication tokens and required headers.
|
||||
- Consult the [Troubleshooting Guide](troubleshooting.md) for further guidance.
|
||||
|
||||
## MCP Schema Endpoint
|
||||
|
||||
@@ -43,119 +329,6 @@ Example response:
|
||||
|
||||
Note: The `/mcp` endpoint is publicly accessible and does not require authentication, as it only provides schema information.
|
||||
|
||||
## Device Control
|
||||
|
||||
### Common Entity Controls
|
||||
```json
|
||||
{
|
||||
"tool": "control",
|
||||
"command": "turn_on", // or "turn_off", "toggle"
|
||||
"entity_id": "light.living_room"
|
||||
}
|
||||
```
|
||||
|
||||
### Light Control
|
||||
```json
|
||||
{
|
||||
"tool": "control",
|
||||
"command": "turn_on",
|
||||
"entity_id": "light.living_room",
|
||||
"brightness": 128,
|
||||
"color_temp": 4000,
|
||||
"rgb_color": [255, 0, 0]
|
||||
}
|
||||
```
|
||||
|
||||
## Add-on Management
|
||||
|
||||
### List Available Add-ons
|
||||
```json
|
||||
{
|
||||
"tool": "addon",
|
||||
"action": "list"
|
||||
}
|
||||
```
|
||||
|
||||
### Install Add-on
|
||||
```json
|
||||
{
|
||||
"tool": "addon",
|
||||
"action": "install",
|
||||
"slug": "core_configurator",
|
||||
"version": "5.6.0"
|
||||
}
|
||||
```
|
||||
|
||||
### Manage Add-on State
|
||||
```json
|
||||
{
|
||||
"tool": "addon",
|
||||
"action": "start", // or "stop", "restart"
|
||||
"slug": "core_configurator"
|
||||
}
|
||||
```
|
||||
|
||||
## Package Management
|
||||
|
||||
### List HACS Packages
|
||||
```json
|
||||
{
|
||||
"tool": "package",
|
||||
"action": "list",
|
||||
"category": "integration" // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
|
||||
}
|
||||
```
|
||||
|
||||
### Install Package
|
||||
```json
|
||||
{
|
||||
"tool": "package",
|
||||
"action": "install",
|
||||
"category": "integration",
|
||||
"repository": "hacs/integration",
|
||||
"version": "1.32.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Automation Management
|
||||
|
||||
### Create Automation
|
||||
```json
|
||||
{
|
||||
"tool": "automation_config",
|
||||
"action": "create",
|
||||
"config": {
|
||||
"alias": "Motion Light",
|
||||
"description": "Turn on light when motion detected",
|
||||
"mode": "single",
|
||||
"trigger": [
|
||||
{
|
||||
"platform": "state",
|
||||
"entity_id": "binary_sensor.motion",
|
||||
"to": "on"
|
||||
}
|
||||
],
|
||||
"action": [
|
||||
{
|
||||
"service": "light.turn_on",
|
||||
"target": {
|
||||
"entity_id": "light.living_room"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Duplicate Automation
|
||||
```json
|
||||
{
|
||||
"tool": "automation_config",
|
||||
"action": "duplicate",
|
||||
"automation_id": "automation.motion_light"
|
||||
}
|
||||
```
|
||||
|
||||
## Core Functions
|
||||
|
||||
### State Management
|
||||
|
||||
@@ -43,3 +43,26 @@ The MCP Server is designed as a high-performance, secure, and scalable bridge be
|
||||
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.
|
||||
|
||||
*This document is a living document and will be updated as the system evolves.*
|
||||
|
||||
## Key Components
|
||||
|
||||
- **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.
|
||||
|
||||
## Data Flow
|
||||
|
||||
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.
|
||||
|
||||
## 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.*
|
||||
@@ -1,27 +1,27 @@
|
||||
# Contributing to Home Assistant MCP
|
||||
|
||||
We welcome contributions from the community! Your help and feedback are essential to improving the MCP Server. Please review the following guidelines before contributing.
|
||||
We welcome community contributions to improve the MCP Server. Please review the following guidelines before contributing.
|
||||
|
||||
## How to Contribute
|
||||
|
||||
1. **Fork the Repository**: Create your personal fork of the project on GitHub.
|
||||
2. **Create a Feature Branch**: Use clear branch names, e.g., `feature/your-feature` or `bugfix/short-description`.
|
||||
3. **Make Changes**: Develop your feature or fix bugs. Ensure your code follows the project's coding conventions.
|
||||
4. **Write Tests**: Include tests for new features or bug fixes. We aim for high code coverage.
|
||||
5. **Submit a Pull Request (PR)**: Once your changes are complete, submit a PR. Our team will review your request and provide feedback.
|
||||
6. **Address Feedback**: Make any necessary revisions based on code review feedback.
|
||||
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.
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
- Follow the project's established coding style.
|
||||
- Use Bun tooling for linting and formatting:
|
||||
- `bun run lint` for linting
|
||||
- `bun run format` for formatting
|
||||
- `bun run lint`
|
||||
- `bun run format`
|
||||
|
||||
## Documentation
|
||||
|
||||
- Update relevant documentation alongside your code changes.
|
||||
- Ensure that tests pass and coverage remains high.
|
||||
- Update documentation alongside your code changes.
|
||||
- Ensure tests pass and coverage remains high.
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
|
||||
@@ -1,122 +1,30 @@
|
||||
# Getting Started with Home Assistant MCP
|
||||
# Getting Started
|
||||
|
||||
This guide will help you get started with the Home Assistant MCP (Master Control Program).
|
||||
Begin your journey with the Home Assistant MCP Server by following these steps:
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have:
|
||||
|
||||
1. Node.js (v16 or higher)
|
||||
2. A running Home Assistant instance
|
||||
3. A Home Assistant Long-Lived Access Token
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
3. Copy the example environment file:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
4. Edit the `.env` file with your configuration:
|
||||
```env
|
||||
# Server Configuration
|
||||
PORT=3000
|
||||
BUN_ENV=development
|
||||
|
||||
# Home Assistant Configuration
|
||||
HASS_HOST=http://your-hass-instance:8123
|
||||
HASS_TOKEN=your-long-lived-access-token
|
||||
|
||||
# Security Configuration
|
||||
JWT_SECRET=your-secret-key
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
- `PORT`: The port number for the MCP server (default: 3000)
|
||||
- `BUN_ENV`: The environment mode (development, production, test)
|
||||
- `HASS_HOST`: Your Home Assistant instance URL
|
||||
- `HASS_TOKEN`: Your Home Assistant Long-Lived Access Token
|
||||
- `JWT_SECRET`: Secret key for JWT token generation
|
||||
|
||||
### Development Mode
|
||||
|
||||
For development, you can use:
|
||||
|
||||
```bash
|
||||
bun run dev
|
||||
```
|
||||
|
||||
This will start the server in development mode with hot reloading.
|
||||
|
||||
### Production Mode
|
||||
|
||||
For production, build and start the server:
|
||||
|
||||
```bash
|
||||
bun run build
|
||||
bun start
|
||||
```
|
||||
|
||||
## First Steps
|
||||
|
||||
1. Check the server is running:
|
||||
```bash
|
||||
curl http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
2. List available devices:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer your-token" http://localhost:3000/api/tools/devices
|
||||
```
|
||||
|
||||
3. Subscribe to events:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer your-token" http://localhost:3000/api/sse/subscribe?events=state_changed
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read the [API Documentation](./API.md) for available endpoints
|
||||
- Learn about [Server-Sent Events](./SSE_API.md) for real-time updates
|
||||
- Explore available [Tools](./tools/README.md) for device control
|
||||
- Check the [Configuration Guide](./configuration/README.md) for advanced settings
|
||||
- **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 issues:
|
||||
|
||||
1. Verify your Home Assistant instance is accessible
|
||||
2. Check your environment variables are correctly set
|
||||
3. Look for errors in the server logs
|
||||
4. Consult the [Troubleshooting Guide](./troubleshooting.md)
|
||||
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 development and contributing:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Follow the [Development Guide](./development/README.md)
|
||||
4. Submit a pull request
|
||||
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? Check out:
|
||||
|
||||
- [GitHub Issues](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||
- [Troubleshooting Guide](./troubleshooting.md)
|
||||
- [FAQ](./troubleshooting.md#faq)
|
||||
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.
|
||||
@@ -4,11 +4,34 @@ title: Home
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# 📚 Home Assistant MCP Documentation
|
||||
|
||||
Welcome to the documentation for the Home Assistant MCP (Model Context Protocol) Server.
|
||||
|
||||
## 📑 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.
|
||||
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
|
||||
|
||||
@@ -29,18 +52,59 @@ The Model Context Protocol (MCP) Server is a cutting-edge bridge between Home As
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Getting Started](getting-started.md) - Installation and basic setup
|
||||
- [API Reference](api.md) - Complete API documentation
|
||||
- [SSE API](sse-api.md) - Server-Sent Events API documentation
|
||||
- [Architecture](architecture.md) - System architecture and design
|
||||
- [Contributing](contributing.md) - How to contribute to the project
|
||||
- [Troubleshooting](troubleshooting.md) - Common issues and solutions
|
||||
### 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
|
||||
|
||||
## 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)
|
||||
|
||||
## Community and Support
|
||||
|
||||
- [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues) - Report bugs and request features
|
||||
- [GitHub Discussions](https://github.com/jango-blockchained/homeassistant-mcp/discussions) - Ask questions and share ideas
|
||||
If you need help or have questions:
|
||||
|
||||
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
|
||||
|
||||
## License
|
||||
|
||||
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 [LICENSE](https://github.com/jango-blockchained/homeassistant-mcp/blob/main/LICENSE) for details.
|
||||
51
docs/roadmap.md
Normal file
51
docs/roadmap.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Roadmap for MCP Server
|
||||
|
||||
The following roadmap outlines our planned enhancements and future directions for the Home Assistant MCP Server. This document is a living guide that will be updated as new features are planned and developed.
|
||||
|
||||
## Near-Term Goals
|
||||
|
||||
- **Advanced Automation Capabilities:**
|
||||
- Integrate sophisticated automation rules with conditional logic and multi-step execution.
|
||||
- Introduce a visual automation builder for simplified rule creation.
|
||||
|
||||
- **Enhanced Security Features:**
|
||||
- Implement multi-factor authentication for critical actions.
|
||||
- Strengthen encryption methods and data handling practices.
|
||||
- Expand monitoring and alerting for potential security breaches.
|
||||
|
||||
- **Performance Optimizations:**
|
||||
- Refine resource utilization to reduce latency.
|
||||
- Optimize real-time data streaming via SSE.
|
||||
- Introduce advanced caching mechanisms for frequently requested data.
|
||||
|
||||
## Mid-Term Goals
|
||||
|
||||
- **User Interface Improvements:**
|
||||
- Develop an intuitive web-based dashboard for device management and monitoring.
|
||||
- Provide real-time analytics and performance metrics.
|
||||
|
||||
- **Expanded Integrations:**
|
||||
- Support a broader range of smart home devices and brands.
|
||||
- Integrate with additional home automation platforms and third-party services.
|
||||
|
||||
- **Developer Experience Enhancements:**
|
||||
- Improve documentation and developer tooling.
|
||||
- Streamline contribution guidelines and testing setups.
|
||||
|
||||
## Long-Term Vision
|
||||
|
||||
- **Ecosystem Expansion:**
|
||||
- Build a modular plugin system for community-driven extensions and integrations.
|
||||
- Enable seamless integration with future technologies in smart home and AI domains.
|
||||
|
||||
- **Scalability and Resilience:**
|
||||
- Architect the system to support large-scale deployments.
|
||||
- Incorporate advanced load balancing and failover mechanisms.
|
||||
|
||||
## How to Follow the Roadmap
|
||||
|
||||
- **Community Involvement:** We welcome and encourage feedback.
|
||||
- **Regular Updates:** This document is updated regularly with new goals and milestones.
|
||||
- **Transparency:** Check our GitHub repository and issue tracker for ongoing discussions.
|
||||
|
||||
*This roadmap is intended as a guide and may evolve based on community needs, technological advancements, and strategic priorities.*
|
||||
@@ -7,23 +7,24 @@
|
||||
bun test # Run all tests
|
||||
bun test --watch # Run tests in watch mode
|
||||
bun test --coverage # Run tests with coverage
|
||||
bun test path/to/test.ts # Run specific test file
|
||||
bun test path/to/test.ts # Run a specific test file
|
||||
|
||||
# Additional Options
|
||||
DEBUG=true bun test # Run with debug output
|
||||
bun test --pattern "auth" # Run tests matching pattern
|
||||
bun test --timeout 60000 # Run with custom timeout
|
||||
bun test --pattern "auth" # Run tests matching a pattern
|
||||
bun test --timeout 60000 # Run with a custom timeout
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the testing setup and practices used in the Home Assistant MCP project. The project uses Bun's test runner for unit and integration testing, with a comprehensive test suite covering security, SSE (Server-Sent Events), middleware, and other core functionalities.
|
||||
This document describes the testing setup and practices used in the Home Assistant MCP project. We use Bun's test runner for both unit and integration testing, ensuring comprehensive coverage across modules.
|
||||
|
||||
## Test Structure
|
||||
|
||||
Tests are organized in two main locations:
|
||||
|
||||
1. **Root Level Integration Tests** (`/__tests__/`):
|
||||
|
||||
```
|
||||
__tests__/
|
||||
├── ai/ # AI/ML component tests
|
||||
@@ -40,6 +41,7 @@ Tests are organized in two main locations:
|
||||
```
|
||||
|
||||
2. **Component Level Unit Tests** (`src/**/`):
|
||||
|
||||
```
|
||||
src/
|
||||
├── __tests__/ # Global test setup and utilities
|
||||
@@ -49,8 +51,6 @@ Tests are organized in two main locations:
|
||||
│ └── component.ts
|
||||
```
|
||||
|
||||
The root level `__tests__` directory contains integration and end-to-end tests that verify the interaction between different components of the system, while the component-level tests focus on unit testing individual modules.
|
||||
|
||||
## Test Configuration
|
||||
|
||||
### Bun Test Configuration (`bunfig.toml`)
|
||||
@@ -88,26 +88,21 @@ bun run format
|
||||
|
||||
### Global Configuration
|
||||
|
||||
The project uses a global test setup file (`src/__tests__/setup.ts`) that provides:
|
||||
|
||||
A global test setup file (`src/__tests__/setup.ts`) provides:
|
||||
- Environment configuration
|
||||
- Mock utilities
|
||||
- Test helper functions
|
||||
- Global test lifecycle hooks
|
||||
- Global lifecycle hooks
|
||||
|
||||
### Test Environment
|
||||
|
||||
Tests run with the following configuration:
|
||||
|
||||
- Environment variables are loaded from `.env.test`
|
||||
- Console output is suppressed during tests (unless DEBUG=true)
|
||||
- JWT secrets and tokens are automatically configured for testing
|
||||
- Rate limiting and other security features are properly initialized
|
||||
- Environment variables are loaded from `.env.test`.
|
||||
- Console output is minimized unless `DEBUG=true`.
|
||||
- JWT secrets and tokens are preconfigured for testing.
|
||||
- Rate limiting and security features are initialized appropriately.
|
||||
|
||||
## Running Tests
|
||||
|
||||
To run the test suite:
|
||||
|
||||
```bash
|
||||
# Basic test run
|
||||
bun test
|
||||
@@ -115,7 +110,7 @@ bun test
|
||||
# Run tests with coverage
|
||||
bun test --coverage
|
||||
|
||||
# Run specific test file
|
||||
# Run a specific test file
|
||||
bun test path/to/test.test.ts
|
||||
|
||||
# Run tests in watch mode
|
||||
@@ -131,82 +126,61 @@ bun test --timeout 60000
|
||||
bun test --pattern "auth"
|
||||
```
|
||||
|
||||
### Test Environment Setup
|
||||
## Advanced Debugging
|
||||
|
||||
1. **Prerequisites**:
|
||||
- Bun >= 1.0.0
|
||||
- Node.js dependencies (see package.json)
|
||||
### Using Node Inspector
|
||||
|
||||
2. **Environment Files**:
|
||||
- `.env.test` - Test environment variables
|
||||
- `.env.development` - Development environment variables
|
||||
```bash
|
||||
# Start tests with inspector
|
||||
bun test --inspect
|
||||
|
||||
3. **Test Data**:
|
||||
- Mock responses in `__tests__/mock-responses/`
|
||||
- Test fixtures in `__tests__/fixtures/`
|
||||
# Start tests with inspector and break on first line
|
||||
bun test --inspect-brk
|
||||
```
|
||||
|
||||
### Continuous Integration
|
||||
### Using VS Code
|
||||
|
||||
The project uses GitHub Actions for CI/CD. Tests are automatically run on:
|
||||
- Pull requests
|
||||
- Pushes to main branch
|
||||
- Release tags
|
||||
Create a launch configuration in `.vscode/launch.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"type": "bun",
|
||||
"request": "launch",
|
||||
"name": "Debug Tests",
|
||||
"program": "${workspaceFolder}/node_modules/bun/bin/bun",
|
||||
"args": ["test", "${file}"],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"env": { "DEBUG": "true" }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Test Isolation
|
||||
|
||||
To run a single test in isolation:
|
||||
|
||||
```typescript
|
||||
describe.only("specific test suite", () => {
|
||||
it.only("specific test case", () => {
|
||||
// Only this test will run
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Writing Tests
|
||||
|
||||
### Test File Naming
|
||||
|
||||
- Test files should be placed in a `__tests__` directory adjacent to the code being tested
|
||||
- Test files should be named `*.test.ts`
|
||||
- Test files should mirror the structure of the source code
|
||||
- Place test files in a `__tests__` directory adjacent to the code being tested.
|
||||
- Name files with the pattern `*.test.ts`.
|
||||
- Mirror the structure of the source code in your test organization.
|
||||
|
||||
### Test Structure
|
||||
### Example Test Structure
|
||||
|
||||
```typescript
|
||||
import { describe, expect, it, beforeEach } from "bun:test";
|
||||
|
||||
describe("Module Name", () => {
|
||||
beforeEach(() => {
|
||||
// Setup for each test
|
||||
});
|
||||
|
||||
describe("Feature/Function Name", () => {
|
||||
it("should do something specific", () => {
|
||||
// Test implementation
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Test Utilities
|
||||
|
||||
The project provides several test utilities:
|
||||
|
||||
```typescript
|
||||
import { testUtils } from "../__tests__/setup";
|
||||
|
||||
// Available utilities:
|
||||
- mockWebSocket() // Mock WebSocket for SSE tests
|
||||
- mockResponse() // Mock HTTP response for API tests
|
||||
- mockRequest() // Mock HTTP request for API tests
|
||||
- createTestClient() // Create test SSE client
|
||||
- createTestEvent() // Create test event
|
||||
- createTestEntity() // Create test Home Assistant entity
|
||||
- wait() // Helper to wait for async operations
|
||||
```
|
||||
|
||||
## Testing Patterns
|
||||
|
||||
### Security Testing
|
||||
|
||||
Security tests cover:
|
||||
- Token validation and encryption
|
||||
- Rate limiting
|
||||
- Request validation
|
||||
- Input sanitization
|
||||
- Error handling
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
describe("Security Features", () => {
|
||||
it("should validate tokens correctly", () => {
|
||||
@@ -218,83 +192,17 @@ describe("Security Features", () => {
|
||||
});
|
||||
```
|
||||
|
||||
### SSE Testing
|
||||
## Coverage
|
||||
|
||||
SSE tests cover:
|
||||
- Client authentication
|
||||
- Message broadcasting
|
||||
- Rate limiting
|
||||
- Subscription management
|
||||
- Client cleanup
|
||||
The project maintains strict coverage:
|
||||
- Overall coverage: at least 80%
|
||||
- Critical paths: 90%+
|
||||
- New features: ≥85% coverage
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
describe("SSE Features", () => {
|
||||
it("should authenticate valid clients", () => {
|
||||
const client = createTestClient("test-client");
|
||||
const result = sseManager.addClient(client, validToken);
|
||||
expect(result?.authenticated).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
Generate a coverage report with:
|
||||
|
||||
### Middleware Testing
|
||||
|
||||
Middleware tests cover:
|
||||
- Request validation
|
||||
- Input sanitization
|
||||
- Error handling
|
||||
- Response formatting
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
describe("Middleware", () => {
|
||||
it("should sanitize HTML in request body", () => {
|
||||
const req = mockRequest({
|
||||
body: { text: '<script>alert("xss")</script>' }
|
||||
});
|
||||
sanitizeInput(req, res, next);
|
||||
expect(req.body.text).toBe("");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
Integration tests in the root `__tests__` directory cover:
|
||||
|
||||
- **AI/ML Components**: Testing machine learning model integrations and predictions
|
||||
- **API Integration**: End-to-end API route testing
|
||||
- **Context Management**: Testing context persistence and state management
|
||||
- **Home Assistant Integration**: Testing communication with Home Assistant
|
||||
- **Schema Validation**: Testing data validation across the application
|
||||
- **Security Integration**: Testing security features in a full system context
|
||||
- **WebSocket Communication**: Testing real-time communication
|
||||
- **Server Integration**: Testing the complete server setup and configuration
|
||||
|
||||
Example integration test:
|
||||
```typescript
|
||||
describe("API Integration", () => {
|
||||
it("should handle a complete authentication flow", async () => {
|
||||
// Setup test client
|
||||
const client = await createTestClient();
|
||||
|
||||
// Test registration
|
||||
const regResponse = await client.register(testUser);
|
||||
expect(regResponse.status).toBe(201);
|
||||
|
||||
// Test authentication
|
||||
const authResponse = await client.authenticate(testCredentials);
|
||||
expect(authResponse.status).toBe(200);
|
||||
expect(authResponse.body.token).toBeDefined();
|
||||
|
||||
// Test protected endpoint access
|
||||
const protectedResponse = await client.get("/api/protected", {
|
||||
headers: { Authorization: `Bearer ${authResponse.body.token}` }
|
||||
});
|
||||
expect(protectedResponse.status).toBe(200);
|
||||
});
|
||||
});
|
||||
```bash
|
||||
bun test --coverage
|
||||
```
|
||||
|
||||
## Security Middleware Testing
|
||||
@@ -1,144 +1,135 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
This guide helps you diagnose and fix common issues with the Home Assistant MCP.
|
||||
This guide provides solutions to common issues encountered with the Home Assistant MCP Server.
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Connection 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.
|
||||
|
||||
#### Cannot Connect to Home Assistant
|
||||
- **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
|
||||
|
||||
**Symptoms:**
|
||||
- Connection timeout errors
|
||||
- "Failed to connect to Home Assistant" messages
|
||||
- 401 Unauthorized errors
|
||||
- "Tool not found" errors or 404 responses.
|
||||
|
||||
**Solutions:**
|
||||
1. Verify Home Assistant is running
|
||||
2. Check HASS_HOST environment variable
|
||||
3. Validate HASS_TOKEN is correct
|
||||
4. Ensure network connectivity
|
||||
5. Check firewall settings
|
||||
- Double-check the tool name spelling.
|
||||
- Verify that the tool is correctly registered.
|
||||
- Review tool imports and documentation.
|
||||
|
||||
#### SSE Connection Drops
|
||||
### Tool Execution Failures
|
||||
|
||||
**Symptoms:**
|
||||
- Frequent disconnections
|
||||
- Missing events
|
||||
- Connection reset errors
|
||||
- Execution errors or timeouts.
|
||||
|
||||
**Solutions:**
|
||||
1. Check network stability
|
||||
2. Increase connection timeout
|
||||
3. Implement reconnection logic
|
||||
4. Monitor server resources
|
||||
- Validate input parameters.
|
||||
- Check and review error logs.
|
||||
- Debug the tool implementation.
|
||||
- Ensure proper permissions in Home Assistant.
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
#### Invalid Token
|
||||
|
||||
**Symptoms:**
|
||||
- 401 Unauthorized responses
|
||||
- "Invalid token" messages
|
||||
- Authentication failures
|
||||
|
||||
**Solutions:**
|
||||
1. Generate new Long-Lived Access Token
|
||||
2. Check token expiration
|
||||
3. Verify token format
|
||||
4. Update environment variables
|
||||
|
||||
#### Rate Limiting
|
||||
|
||||
**Symptoms:**
|
||||
- 429 Too Many Requests
|
||||
- "Rate limit exceeded" messages
|
||||
|
||||
**Solutions:**
|
||||
1. Implement request throttling
|
||||
2. Adjust rate limit settings
|
||||
3. Cache responses
|
||||
4. Optimize request patterns
|
||||
|
||||
### Tool Issues
|
||||
|
||||
#### Tool Not Found
|
||||
|
||||
**Symptoms:**
|
||||
- "Tool not found" errors
|
||||
- 404 Not Found responses
|
||||
|
||||
**Solutions:**
|
||||
1. Check tool name spelling
|
||||
2. Verify tool registration
|
||||
3. Update tool imports
|
||||
4. Check tool availability
|
||||
|
||||
#### Tool Execution Fails
|
||||
|
||||
**Symptoms:**
|
||||
- Tool execution errors
|
||||
- Unexpected responses
|
||||
- Timeout issues
|
||||
|
||||
**Solutions:**
|
||||
1. Validate input parameters
|
||||
2. Check error logs
|
||||
3. Debug tool implementation
|
||||
4. Verify Home Assistant permissions
|
||||
|
||||
## Debugging
|
||||
## Debugging Steps
|
||||
|
||||
### Server Logs
|
||||
|
||||
1. Enable debug logging:
|
||||
1. Enable debug logging by setting:
|
||||
```env
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
2. Check logs:
|
||||
```bash
|
||||
npm run logs
|
||||
```
|
||||
|
||||
3. Filter logs:
|
||||
3. Filter errors:
|
||||
```bash
|
||||
npm run logs | grep "error"
|
||||
```
|
||||
|
||||
### Network Debugging
|
||||
|
||||
1. Check API endpoints:
|
||||
1. Test API endpoints:
|
||||
```bash
|
||||
curl -v http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
2. Monitor SSE connections:
|
||||
```bash
|
||||
curl -N http://localhost:3000/api/sse/stats
|
||||
```
|
||||
|
||||
3. Test WebSocket:
|
||||
3. Test WebSocket connectivity:
|
||||
```bash
|
||||
wscat -c ws://localhost:3000
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
1. Monitor memory usage:
|
||||
- Monitor memory usage with:
|
||||
```bash
|
||||
npm run stats
|
||||
```
|
||||
|
||||
2. Check response times:
|
||||
```bash
|
||||
curl -w "%{time_total}\n" -o /dev/null -s http://localhost:3000/api/health
|
||||
```
|
||||
## Security Middleware Troubleshooting
|
||||
|
||||
3. Profile code:
|
||||
```bash
|
||||
npm run profile
|
||||
```
|
||||
### 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.
|
||||
|
||||
## FAQ
|
||||
|
||||
@@ -167,7 +158,7 @@ A: Adjust SSE_MAX_CLIENTS in configuration or clean up stale connections.
|
||||
1. Documentation
|
||||
- [API Reference](./API.md)
|
||||
- [Configuration Guide](./configuration/README.md)
|
||||
- [Development Guide](./development/README.md)
|
||||
- [Development Guide](./development/development.md)
|
||||
|
||||
2. Community
|
||||
- GitHub Issues
|
||||
|
||||
@@ -1,5 +1,34 @@
|
||||
# Usage Guide
|
||||
|
||||
This guide explains how to use the Home Assistant MCP Server for smart home device management and integration with language learning systems.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
1. **Starting the Server:**
|
||||
- For development: run `npm run dev`.
|
||||
- For production: run `npm run build` followed by `npm start`.
|
||||
|
||||
2. **Accessing the Web Interface:**
|
||||
- Open [http://localhost:3000](http://localhost:3000) in your browser.
|
||||
|
||||
3. **Real-Time Updates:**
|
||||
- Connect to the SSE endpoint at `/subscribe_events?token=YOUR_TOKEN&domain=light` to receive live updates.
|
||||
|
||||
## Advanced Features
|
||||
|
||||
1. **API Interactions:**
|
||||
- Use the REST API for operations such as device control, automation, and add-on management.
|
||||
- See [API Documentation](api.md) for details.
|
||||
|
||||
2. **Tool Integrations:**
|
||||
- Multiple tools are available (see [Tools Documentation](tools/tools.md)), for tasks like automation management and notifications.
|
||||
|
||||
3. **Security Settings:**
|
||||
- Configure token-based authentication and environment variables as per the [Configuration Guide](getting-started/configuration.md).
|
||||
|
||||
4. **Customization and Extensions:**
|
||||
- Extend server functionality by developing new tools as outlined in the [Development Guide](development/development.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you experience issues, review the [Troubleshooting Guide](troubleshooting.md).
|
||||
@@ -1,4 +1,4 @@
|
||||
site_name: Project Documentation
|
||||
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
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "homeassistant-mcp",
|
||||
"version": "1.0.0",
|
||||
"description": "Home Assistant Master Control Program",
|
||||
"description": "Home Assistant Model Context Protocol",
|
||||
"main": "dist/index.js",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
|
||||
Reference in New Issue
Block a user