alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive WebSocket, context, performance, and security modules

Browse Source 
- Introduced WebSocket client for real-time Home Assistant event streaming
- Created context management system for tracking resource relationships and state
- Implemented performance monitoring and optimization utilities
- Added security middleware with token validation, rate limiting, and input sanitization
- Extended tool registry with enhanced tool registration and execution capabilities
- Expanded test coverage for new modules and added comprehensive test scenarios
- Improved type safety and added robust error handling across new modules
This commit is contained in:
jango-blockchained
2025-01-30 09:18:17 +01:00
parent d7e5fcf764
commit 110f2a308c
8 changed files with 2428 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

317
README.md
View File

@@ -2,12 +2,14 @@
*Forked from [tevonsb/homeassistant-mcp](https://github.com/tevonsb/homeassistant-mcp)*
A powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP).
A powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP). This server provides a comprehensive API for managing your entire Home Assistant ecosystem, from device control to system administration.
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Node.js](https://img.shields.io/badge/node-%3E%3D20.10.0-green.svg)
![Docker Compose](https://img.shields.io/badge/docker-compose-%3E%3D1.27.0-blue.svg)
![NPM](https://img.shields.io/badge/npm-%3E%3D7.0.0-orange.svg)
![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg)
![Test Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)
## Table of Contents
@@ -18,7 +20,11 @@ A powerful bridge between your Home Assistant instance and Language Learning Mod
- [Docker Setup (Recommended)](#docker-setup-recommended)
- [Configuration](#configuration)
- [Development](#development)
- [Supported Commands](#supported-commands)
- [API Reference](#api-reference)
- [Device Control](#device-control)
- [Add-on Management](#add-on-management)
- [Package Management](#package-management)
- [Automation Management](#automation-management)
- [Natural Language Integration](#natural-language-integration)
- [Troubleshooting](#troubleshooting)
- [Project Status](#project-status)
@@ -28,20 +34,62 @@ A powerful bridge between your Home Assistant instance and Language Learning Mod
## Key Features
- **Smart Device Control** 🎮
### Core Functionality 🎮
- **Smart Device Control**
- 💡 **Lights**: Brightness, color temperature, RGB color
- 🌡️ **Climate**: Temperature, HVAC modes, fan modes, humidity
- 🚪 **Covers**: Position and tilt control
- 🔌 **Switches**: On/off control
- 🚨 **Sensors & Contacts**: State monitoring
- **Intelligent Organization** 🏠
- 🎵 **Media Players**: Playback control, volume, source selection
- 🌪️ **Fans**: Speed, oscillation, direction
- 🔒 **Locks**: Lock/unlock control
- 🧹 **Vacuums**: Start, stop, return to base
- 📹 **Cameras**: Motion detection, snapshots
### System Management 🛠️
- **Add-on Management**
- Browse available add-ons
- Install/uninstall add-ons
- Start/stop/restart add-ons
- Version management
- Configuration access
- **Package Management (HACS)**
- Integration with Home Assistant Community Store
- Multiple package types support:
- Custom integrations
- Frontend themes
- Python scripts
- AppDaemon apps
- NetDaemon apps
- Version control and updates
- Repository management
- **Automation Management**
- Create and edit automations
- Advanced configuration options:
- Multiple trigger types
- Complex conditions
- Action sequences
- Execution modes
- Duplicate and modify existing automations
- Enable/disable automation rules
- Trigger automation manually
### Architecture Features 🏗️
- **Intelligent Organization**
- Area and floor-based device grouping
- State monitoring and querying
- Smart context awareness
- **Robust Architecture** 🛠️
- Historical data access
- **Robust Architecture**
- Comprehensive error handling
- State validation
- Secure API integration
- TypeScript type safety
- Extensive test coverage
## Prerequisites
@@ -50,6 +98,8 @@ A powerful bridge between your Home Assistant instance and Language Learning Mod
- **Docker Compose** for containerization
- Running **Home Assistant** instance
- Home Assistant long-lived access token ([How to get token](https://community.home-assistant.io/t/how-to-get-long-lived-access-token/162159))
- **HACS** installed for package management features
- **Supervisor** access for add-on management
## Installation
@@ -67,9 +117,7 @@ npm install
npm run build
```
### Docker Setup
> Note: This setup is currently in progress. You can use the `docker` branch to get the latest changes.
### Docker Setup (Recommended)
1. **Clone and prepare:**
```bash
@@ -80,9 +128,14 @@ npm run build
2. **Configure environment `.env` file:**
```env
...
# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
...
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
# Server Configuration
PORT=3000
NODE_ENV=production
```
3. **Launch with Docker Compose:**
@@ -90,33 +143,11 @@ npm run build
docker-compose up -d
```
## Configuration
## API Reference
Copy `.env.example` to `.env`.
### Device Control
```bash
cp .env.example .env
```
Configure environment `.env` file:
```env
...
HASS_TOKEN=your_home_assistant_token
...
```
## Development
```bash
npm run dev # Development mode
npm run build # Build project
npm run start # Production mode
npx jest --config=jest.config.cjs # Run tests
```
## Supported Commands
### Common Entity Controls
#### Common Entity Controls
```json
{
"tool": "control",
@@ -125,7 +156,7 @@ npx jest --config=jest.config.cjs # Run tests
}
```
### Light Control
#### Light Control
```json
{
"tool": "control",
@@ -137,173 +168,201 @@ npx jest --config=jest.config.cjs # Run tests
}
```
### Climate Control
### Add-on Management
#### List Available Add-ons
```json
{
"tool": "control",
"command": "set_temperature",
"entity_id": "climate.bedroom",
"temperature": 22,
"hvac_mode": "heat",
"fan_mode": "auto",
"humidity": 45
"tool": "addon",
"action": "list"
}
```
### Cover Control
#### Install Add-on
```json
{
"tool": "control",
"command": "set_position",
"entity_id": "cover.living_room",
"position": 50,
"tilt_position": 45
"tool": "addon",
"action": "install",
"slug": "core_configurator",
"version": "5.6.0"
}
```
### Media Player Control
#### Manage Add-on State
```json
{
"tool": "control",
"command": "media_play", // or "media_pause", "media_stop", "media_next", "media_previous"
"entity_id": "media_player.living_room",
"volume_level": 0.5,
"source": "Spotify",
"media_content_id": "spotify:playlist:xyz",
"media_content_type": "playlist"
"tool": "addon",
"action": "start", // or "stop", "restart"
"slug": "core_configurator"
}
```
### Fan Control
### Package Management
#### List HACS Packages
```json
{
"tool": "control",
"command": "turn_on",
"entity_id": "fan.bedroom",
"percentage": 50,
"preset_mode": "auto",
"oscillating": true,
"direction": "forward"
"tool": "package",
"action": "list",
"category": "integration" // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}
```
### Lock Control
#### Install Package
```json
{
"tool": "control",
"command": "lock", // or "unlock"
"entity_id": "lock.front_door"
"tool": "package",
"action": "install",
"category": "integration",
"repository": "hacs/integration",
"version": "1.32.0"
}
```
### Vacuum Control
```json
{
"tool": "control",
"command": "start", // or "pause", "stop", "return_to_base", "clean_spot"
"entity_id": "vacuum.robot",
"fan_speed": "medium"
}
```
### Automation Management
### Scene Control
#### Create Automation
```json
{
"tool": "control",
"command": "turn_on",
"entity_id": "scene.movie_night"
}
```
### Script Control
```json
{
"tool": "control",
"command": "turn_on",
"entity_id": "script.welcome_home",
"variables": {
"brightness": 100,
"color": "red"
"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"
}
}
]
}
}
```
### Camera Control
#### Duplicate Automation
```json
{
"tool": "control",
"command": "enable_motion_detection", // or "disable_motion_detection"
"entity_id": "camera.front_door"
"tool": "automation_config",
"action": "duplicate",
"automation_id": "automation.motion_light"
}
```
## Natural Language Integration
## Development
### Example Commands
- "Turn on the living room lights"
- "Set bedroom temperature to 22 degrees"
- "Is the front door locked?"
```bash
# Development mode with hot reload
npm run dev
### Smart Features
- Context awareness across conversations
- Natural parameter interpretation
- Intelligent error prevention
- Multi-device orchestration
# Build project
npm run build
# Production mode
npm run start
# Run tests
npx jest --config=jest.config.cjs
# Run tests with coverage
npx jest --coverage
# Lint code
npm run lint
# Format code
npm run format
```
## Troubleshooting
### Common Issues
1. **Node.js Version (`toSorted is not a function`)**
- **Solution:** Update to Node.js 20.10.0+
```bash
nvm install 20.10.0
nvm use 20.10.0
```
2. **Connection Issues**
- Verify Home Assistant is running
- Check `HASS_HOST` accessibility
- Validate token permissions
3. **Entity Control Issues**
- Verify `entity_id` exists
- Check entity domain matches command
- Ensure parameter values are valid
- Ensure WebSocket connection for real-time updates
3. **Add-on Management Issues**
- Verify Supervisor access
- Check add-on compatibility
- Validate system resources
4. **HACS Integration Issues**
- Verify HACS installation
- Check HACS integration status
- Validate repository access
5. **Automation Issues**
- Verify entity availability
- Check trigger conditions
- Validate service calls
- Monitor execution logs
## Project Status
✅ **Complete**
- Entity, Floor, and Area access
- Device control (Lights, Climate, Covers, Switches, Contacts)
- Add-on management system
- Package management through HACS
- Advanced automation configuration
- Basic state management
- Error handling and validation
- Docker containerization and configuration
- Jest testing setup and TypeScript integration
- Docker containerization
- Jest testing setup
- TypeScript integration
- Environment variable management
- Home Assistant API integration
- Project documentation and README organization
- Project documentation
🚧 **In Progress**
- Custom prompt testing and optimization
- Resource context integration
- WebSocket implementation for real-time updates
- Enhanced security features
- Tool organization optimization
- Performance optimization
- Resource context integration
- API documentation generation
- Multi-platform desktop integration
- Advanced error recovery
- Custom prompt testing
- Enhanced macOS integration
- Type safety improvements
- Testing coverage expansion
🔜 **Planned**
- Multi-platform desktop integration
- Advanced error recovery mechanisms
- Performance optimization
- WebSocket implementation for real-time updates
- Enhanced security features
- API documentation generation
## Contributing
1. Fork repository
2. Create feature branch
3. Submit pull request
1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
## Resources
- [MCP Documentation](https://modelcontextprotocol.io/introduction)
- [Home Assistant Docs](https://www.home-assistant.io)
- [HA REST API](https://developers.home-assistant.io/docs/api/rest)
- [HACS Documentation](https://hacs.xyz)
- [TypeScript Documentation](https://www.typescriptlang.org/docs)
## License