Home Assistant MCP Server

# 🛣️ ROADMAP - SERVEUR HTTP-MCP BRIDGE AVEC AUTHENTIFICATION ## 📋 **VUE D'ENSEMBLE** Ce projet implémente un bridge HTTP sécurisé pour exposer le protocole MCP (Model Context Protocol) avec authentification utilisateur, gestion des permissions par outil, et configuration personnalisée de Home Assistant. ## 🎯 **OBJECTIFS PRINCIPAUX** - ✅ Bridge HTTP-MCP fonctionnel avec file d'attente - ✅ Base de données SQLite intégrée avec logs et nettoyage automatique - 🔐 Système d'authentification sécurisé (inscription/login) - ⚙️ Configuration Home Assistant par utilisateur - 🎛️ Gestion granulaire des permissions par outil MCP - 📊 Dashboard web intégré avec monitoring temps réel --- ## 🗓️ **PLANNING DÉTAILLÉ** ### **PHASE 0 : PRÉPARATION** ✅ **TERMINÉ** **État : ✅ Complété** #### ✅ **Milestone 0.1 : Documentation & Git** - [x] Roadmap complète (ROADMAP.md) - [x] Documentation architecture (BRIDGE_ARCHITECTURE.md) - [x] Documentation API (API_DOCUMENTATION.md) - [x] Push vers GitHub (commit fa943d4) - [x] Repository McpHomeAssistant configuré --- ### **PHASE 1 : BRIDGE CORE** ✅ **TERMINÉ** **État : ✅ Complété** #### ✅ **Milestone 1.1 : Infrastructure HTTP-MCP** - [x] **FastAPI Server** : Serveur HTTP sur port 3003 - [x] **AsyncRequestQueue** : File d'attente thread-safe FIFO - [x] **MCPSessionPool** : Pool de connexions MCP réutilisables - [x] **MockMCPServer** : Serveur MCP de test intégré #### ✅ **Milestone 1.2 : Endpoints Core Fonctionnels** ```http POST /mcp/initialize # ✅ Initialisation session MCP POST /mcp/tools/list # ✅ Liste des outils disponibles POST /mcp/tools/call # ✅ Exécution d'outils avec session GET /health # ✅ Health check serveur GET /mcp/status # ✅ Statut bridge et sessions ``` #### ✅ **Milestone 1.3 : File d'attente & Sécurité** - [x] **Queue Priority System** : Gestion priorités et timeouts - [x] **Session Management** : Isolation des sessions utilisateur - [x] **Error Handling** : Gestion robuste erreurs et connexions - [x] **Health Monitoring** : Surveillance sessions MCP --- ### **PHASE 2.1-2.3 : BASE DE DONNÉES** ✅ **TERMINÉ** **État : ✅ Complété** #### ✅ **Milestone 2.1 : SQLite Database System** - [x] **Database Module** : database.py avec SQLAlchemy - [x] **Tables Structure** : logs, requests, errors, stats - [x] **DatabaseManager** : Classe de gestion complète - [x] **Migration System** : Création automatique des tables #### ✅ **Milestone 2.2 : Logging System** - [x] **Daily Log Rotation** : Logs journaliers bridge_YYYY-MM-DD.log - [x] **Database Integration** : Logs automatiques en BDD - [x] **Structured Logging** : Format JSON structuré - [x] **Log Levels** : INFO, WARNING, ERROR, DEBUG #### ✅ **Milestone 2.3 : Cleanup & Maintenance** - [x] **Auto Cleanup Task** : Nettoyage automatique à 2h00 - [x] **30-Day Retention** : Suppression logs > 30 jours - [x] **Database VACUUM** : Optimisation base de données - [x] **Admin Endpoints** : /admin/stats, /admin/cleanup, /admin/logs/rotate --- ### **PHASE 2.4 : CACHE & CIRCUIT BREAKER** ✅ **TERMINÉ** **État : ✅ Complété** #### ✅ **Milestone 2.4 : Cache L1 Mémoire & Circuit Breaker** - [x] **LRU Cache** : Cache mémoire avec TTL (outils 10min, réponses 1min) - [x] **Circuit Breaker** : Protection avec états CLOSED/OPEN/HALF_OPEN - [x] **Retry Logic** : Retry automatique avec backoff exponentiel - [x] **Metrics Endpoint** : /admin/metrics avec métriques complètes - [x] **Performance Monitoring** : Surveillance temps réponse et erreurs - [x] **Auto Cleanup** : Nettoyage cache automatique toutes les 5 minutes **📦 Livré** : Module cache_manager.py complet (commit 8ae08bc) --- ### **PHASE 3.1 : AUTHENTIFICATION** ✅ **TERMINÉ** **État : ✅ Complété** #### ✅ **Milestone 3.1 : Système d'authentification sécurisé** - [x] **User Database** : Tables users et user_sessions avec tous les champs - [x] **Sessions Database** : Gestion JWT avec refresh tokens - [x] **Password Hashing** : Hachage PBKDF2-HMAC-SHA256 sécurisé (100k itérations) - [x] **JWT Management** : Tokens access (24h) et refresh (30 jours) - [x] **Middleware Auth** : Protection endpoints avec dependencies FastAPI - [x] **Security Features** : Protection brute force, verrouillage compte - [x] **Admin Default** : Utilisateur admin/Admin123! créé automatiquement #### ✅ **Endpoints d'authentification** ```http POST /auth/register # ✅ Inscription nouveau utilisateur POST /auth/login # ✅ Connexion utilisateur avec validation POST /auth/logout # ✅ Déconnexion (révocation session) POST /auth/refresh # ✅ Rafraîchissement token GET /auth/me # ✅ Informations utilisateur connecté GET /auth/sessions # ✅ Sessions actives utilisateur ``` **📦 Livré** : Module auth_manager.py complet avec sécurité avancée --- ### **PHASE 3.2 : CONFIGURATION HOME ASSISTANT** ✅ **TERMINÉ** **État : ✅ Complété** #### ✅ **Milestone 3.2 : Gestion configuration HA par utilisateur** - [x] **Config Database** : Table ha_configs (user_id, url, token_encrypted, last_test, last_status) - [x] **System Config** : Table system_config pour clés de chiffrement système - [x] **Token Encryption** : Chiffrement AES-256 Fernet + PBKDF2-HMAC-SHA256 (100k itérations) - [x] **Connection Testing** : Test connexion HA temps réel avec métriques détaillées - [x] **URL Validation** : Validation URLs HA avec recommandations HTTPS - [x] **Multi-Instance Support** : Support plusieurs configurations HA par utilisateur - [x] **Security Features** : Gestion erreurs, timeouts, validation stricte tokens #### ✅ **Endpoints de configuration complets** ```http POST /config/homeassistant # ✅ Configuration HA utilisateur GET /config/homeassistant # ✅ Lister configurations utilisateur GET /config/homeassistant/{id} # ✅ Récupérer configuration spécifique PUT /config/homeassistant/{id} # ✅ Mise à jour configuration HA DELETE /config/homeassistant/{id} # ✅ Suppression configuration HA POST /config/homeassistant/{id}/test # ✅ Test connexion configuration sauvée POST /config/homeassistant/test # ✅ Test direct sans sauvegarde ``` #### ✅ **Fonctionnalités avancées** - [x] **Chiffrement sécurisé** : AES-256 avec clés uniques par installation - [x] **Validation complète** : URLs, tokens, timeouts, gestion erreurs HTTP - [x] **Tests en temps réel** : Mesure latence, version HA, nombre entités - [x] **Gestion multi-config** : Plusieurs instances HA par utilisateur avec statuts - [x] **Session management** : Nettoyage automatique sessions HTTP - [x] **Tests unitaires** : Suite complète de tests pour toutes les fonctionnalités **📦 Livré** : Module ha_config_manager.py complet avec chiffrement (commit 3ed986d) --- ### **PHASE 3.3 : GESTION PERMISSIONS OUTILS** ✅ **TERMINÉ** **État : ✅ Complété (commit d061e69)** #### ✅ **Milestone 3.3 : Permissions granulaires par outil MCP** - [x] **Permissions Database** : Tables user_tool_permissions et default_permissions avec index optimisés - [x] **Default Permissions** : Système d'héritage des permissions par défaut - [x] **Permission Validation** : Middleware validation automatique avant appels MCP - [x] **Admin Management** : Endpoints admin complets gestion permissions - [x] **User Preferences** : Interface utilisateur consultation permissions #### ✅ **Endpoints de permissions** ```http POST /permissions/validate # Validation permission individuelle POST /permissions/validate/bulk # Validation permissions en lot GET /permissions/me # Résumé permissions utilisateur GET /permissions/user/{id} # [ADMIN] Permissions utilisateur spécifique PUT /permissions/user/{id} # [ADMIN] Mise à jour permissions utilisateur PUT /permissions/user/{id}/bulk # [ADMIN] Mise à jour permissions en masse DELETE /permissions/user/{id}/tool/{name} # [ADMIN] Suppression permission GET /permissions/defaults # [ADMIN] Permissions par défaut PUT /permissions/defaults # [ADMIN] Mise à jour permissions par défaut ``` #### ✅ **Système de permissions complet** - [x] **Validation granulaire** : Permissions READ/WRITE/EXECUTE par outil MCP - [x] **Cache intelligent** : Système cache avec TTL 5min pour performances - [x] **Héritage permissions** : Permissions par défaut pour nouveaux utilisateurs - [x] **Permissions built-in** : Outils Home Assistant pré-configurés - [x] **Middleware sécurisé** : Validation automatique avec logs d'audit **📦 Livré** : Module permissions_manager.py + permissions_middleware.py complets (commit d061e69) --- ### **PHASE 3.4 : DASHBOARD WEB INTÉGRÉ** ✅ **TERMINÉ** **État : ✅ Complété** #### ✅ **Milestone 3.4 : Interface web complète sécurisée** - [x] **Dashboard HTML/JS** : Interface responsive moderne avec CSS framework custom (14.2KB) - [x] **Authentication UI** : Pages login/register sécurisées avec formulaires interactifs - [x] **Configuration Pages** : Interface config HA et permissions avec validation temps réel - [x] **Monitoring Real-time** : Charts métriques en temps réel avec WebSocket support - [x] **Logs Viewer** : Visualisation logs avec filtres, pagination et export CSV/JSON - [x] **Admin Panel** : Interface administration complète avec gestion utilisateurs #### ✅ **Pages Dashboard implémentées** ``` / # ✅ Page d'accueil avec redirection dashboard /login # ✅ Page de connexion sécurisée /dashboard # ✅ Dashboard principal avec navigation SPA /permissions # ✅ Gestion permissions outils MCP /config # ✅ Configuration Home Assistant multi-instance /tools # ✅ Gestion et test des outils MCP /logs # ✅ Visualisation logs avec filtrage avancé /admin # ✅ Panel administration [ADMIN ONLY] ``` #### ✅ **Fonctionnalités Dashboard réalisées** - [x] **Interface responsive** : Design moderne compatible mobile/desktop (CSS Grid/Flexbox) - [x] **Single Page App** : Navigation dynamique sans rechargement (JavaScript ES6+) - [x] **Charts Temps Réel** : Graphiques activité 24h, métriques connexions - [x] **Status Widgets** : État HA, sessions actives, outils MCP, métriques système - [x] **API Complète** : 15+ endpoints pour métriques, config, logs, administration - [x] **Tools Testing** : Interface test direct outils MCP avec résultats détaillés - [x] **User Management** : [ADMIN] Gestion utilisateurs, rôles et permissions granulaires - [x] **Export de données** : Export logs CSV/JSON, configuration backup - [x] **WebSocket Ready** : Infrastructure pour mises à jour temps réel #### ✅ **Composants techniques livrés** - [x] **web/static/css/main.css** : Framework CSS complet (700+ lignes, design system) - [x] **web/static/js/dashboard.js** : Application JavaScript SPA (700+ lignes) - [x] **web/templates/** : 9 templates HTML complets (index, login, dashboard, overview, etc.) - [x] **bridge_server.py** : 25+ nouveaux endpoints API pour l'interface web - [x] **Scripts de test** : test_simple.py et test_complete.py pour validation automatique #### ✅ **Tests et validation** - [x] **Tests automatiques** : 100% des composants testés (pages, API, templates, CSS/JS) - [x] **Interface fonctionnelle** : Navigation, formulaires, tableaux, modals opérationnels - [x] **Performance validée** : Chargement rapide, responsive design, optimisations CSS/JS - [x] **Sécurité intégrée** : Authentification, sessions, protection CSRF, validation entrées **📦 Livré** : Interface web complète et fonctionnelle avec dashboard moderne sécurisé --- ### **PHASE 3.5 : SÉCURITÉ & PRODUCTION** 🔒 **À FAIRE** **État : ⏳ Planifié** #### 🎯 **Milestone 3.5 : Sécurisation production** - [ ] **Rate Limiting** : Limitation requêtes par utilisateur (100/min par défaut) - [ ] **HTTPS Support** : Configuration SSL/TLS recommandée - [ ] **Input Validation** : Validation stricte toutes les entrées - [ ] **Admin Endpoints Security** : Protection renforcée endpoints admin - [ ] **Audit Logs** : Logs d'audit pour actions sensibles - [ ] **Backup System** : Sauvegarde configuration et base de données #### 🎯 **Endpoints de sécurité** ```http GET /admin/security/audit # [ADMIN] Logs d'audit POST /admin/security/backup # [ADMIN] Création backup GET /admin/security/stats # [ADMIN] Statistiques sécurité PUT /admin/security/limits # [ADMIN] Configuration rate limiting ``` #### 🎯 **Tests de sécurité** - [ ] **Penetration Testing** : Tests basiques de sécurité - [ ] **Load Testing** : Tests de charge avec authentification - [ ] **Security Scanning** : Scan vulnérabilités connues - [ ] **Backup Recovery** : Tests restauration backups --- ## 🏗️ **ARCHITECTURE TECHNIQUE MISE À JOUR** ### **Composants Principaux avec Authentification** ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ LM Studio │ │ n8n / Clients │ │ Autres Apps │ │ │ │ │ │ │ └─────────┬───────┘ └─────────┬────────┘ └─────────┬───────┘ │ │ │ └──────────────────────┼───────────────────────┘ │ (avec JWT token) ┌─────────────▼──────────────┐ │ HTTP-MCP BRIDGE │ │ ┌─────────────────────┐ │ │ │ Auth Middleware │ │ <- Validation JWT │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ Queue Manager │ │ │ │ ┌───┬───┬───┬───┐ │ │ │ │ │ R │ R │ R │ R │ │ │ <- File d'attente FIFO │ │ └───┴───┴───┴───┘ │ │ │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ Permission Check │ │ <- Validation outils │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ Session Pool │ │ │ │ ┌───┬───┬───┬───┐ │ │ │ │ │ S │ S │ S │ S │ │ │ <- Pool sessions MCP │ │ └───┴───┴───┴───┘ │ │ │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ SQLite Database │ │ <- Users, Permissions, Logs │ └─────────────────────┘ │ └─────────────┬──────────────┘ │ ┌─────────────▼──────────────┐ │ MCP SERVER │ │ (Home Assistant) │ │ │ └─────────────┬──────────────┘ │ ┌─────────────▼──────────────┐ │ HOME ASSISTANT │ │ (192.168.1.22:8123) │ └────────────────────────────┘ ``` ### **Base de Données Schema** ```sql -- Table utilisateurs CREATE TABLE users ( id INTEGER PRIMARY KEY, username VARCHAR(50) UNIQUE NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, is_admin BOOLEAN DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- Table configurations Home Assistant CREATE TABLE user_configs ( user_id INTEGER, ha_url VARCHAR(255), ha_token_encrypted TEXT, domains_allowed JSON, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY(user_id) REFERENCES users(id) ); -- Table permissions outils CREATE TABLE user_tool_permissions ( user_id INTEGER, tool_name VARCHAR(100), can_read BOOLEAN DEFAULT TRUE, can_write BOOLEAN DEFAULT FALSE, is_enabled BOOLEAN DEFAULT TRUE, FOREIGN KEY(user_id) REFERENCES users(id) ); -- Table permissions par défaut (pour nouveaux utilisateurs) CREATE TABLE default_permissions ( tool_name VARCHAR(100), can_read BOOLEAN DEFAULT TRUE, can_write BOOLEAN DEFAULT FALSE, is_enabled BOOLEAN DEFAULT TRUE ); ``` --- ## 📊 **MÉTRIQUES DE SUCCÈS MISES À JOUR** ### **Performance Targets** - **Latence** : < 200ms pour requêtes avec authentification - **Throughput** : > 50 req/sec par utilisateur simultané - **Uptime** : > 99.9% - **Memory** : < 512MB avec base utilisateurs (100 users) ### **Sécurité Targets** - **Authentication** : JWT avec expiration 24h - **Rate Limiting** : 100 req/min par utilisateur par défaut - **Audit Logs** : 100% des actions sensibles loggées - **Data Protection** : Tokens HA chiffrés AES-256 ### **Fonctionnalités Clés Étendues** - ✅ **Multi-User Support** : Support utilisateurs multiples - ✅ **Granular Permissions** : Permissions par outil et par utilisateur - ✅ **HA Config Management** : Configuration HA personnalisée - ✅ **Integrated Dashboard** : Interface web complète - ✅ **Audit Trail** : Traçabilité complète des actions --- ## 🚀 **DÉPLOIEMENT & LIVRAISON MISE À JOUR** ### **Stratégie de Release Étendue** - **Alpha** : ✅ Bridge basique + BDD (Phases 0-2.3) - **TERMINÉ** - **Beta** : Cache + Auth + Config HA (Phases 2.4-3.2) - **En cours** - **RC** : Permissions + Dashboard (Phases 3.3-3.4) - **Planifié** - **Stable** : Sécurité + Production (Phase 3.5) - **Planifié** ### **Documentation Requise Étendue** - [x] API Reference complète ✅ **TERMINÉ** - [x] Architecture détaillée ✅ **TERMINÉ** - [ ] Guide d'installation avec authentification - [ ] Guide configuration multi-utilisateurs - [ ] Guide gestion permissions - [ ] Guide dashboard administration - [ ] Security best practices --- ## ⚡ **POINTS D'ATTENTION MISE À JOUR** ### **Nouveaux Risques Identifiés** 1. **Sécurité Authentification** : Gestion tokens JWT et sessions 2. **Performance Multi-User** : Scalabilité avec plusieurs utilisateurs 3. **Configuration HA** : Gestion tokens HA multiples et chiffrement 4. **UI/UX Dashboard** : Complexité interface utilisateur 5. **Database Growth** : Croissance base de données avec utilisateurs ### **Nouvelles Stratégies de Mitigation** 1. **Security Testing** : Tests sécurité automatisés 2. **Load Testing Multi-User** : Tests charge avec authentification 3. **Database Optimization** : Indexes et optimisations requêtes 4. **UI/UX Testing** : Tests interface utilisateur 5. **Monitoring Enhanced** : Métriques sécurité et performance --- ## 📅 **TIMELINE MISE À JOUR** **Estimation totale : 20-25 jours de développement** - ✅ **Phases 0-2.3** : Terminées (Bridge + BDD) - **8 jours** - ✅ **Phase 2.4** : Cache & Circuit Breaker - **TERMINÉ** - ✅ **Phase 3.1** : Authentification - **TERMINÉ** - ✅ **Phase 3.2** : Config Home Assistant - **TERMINÉ** - ✅ **Phase 3.3** : Permissions outils - **TERMINÉ** - ✅ **Phase 3.4** : Dashboard web - **TERMINÉ** ✨ - ⏳ **Phase 3.5** : Sécurité production - **2-3 jours** **✅ Livraison Beta (avec auth)** : TERMINÉ **✅ Livraison RC (avec dashboard)** : TERMINÉ ✨ **⏳ Livraison Stable** : Phase 3.5 restante