ccu-mcp

ccu-mcp est un serveur Model Context Protocol (MCP) qui fait le pont entre les assistants IA (comme Claude, Cursor ou tout client MCP) et les systèmes domotiques HomeMatic. Il se connecte directement à l'API JSON-RPC intégrée de la CCU (via `/api/homematic.cgi`), éliminant le besoin d'addons, d'XML-API ou de services cloud. Il fonctionne avec toute CCU HomeMatic, y compris debmatic, CCU3 et OpenCCU (anciennement RaspberryMatic). Le serveur gère la découverte des appareils, la résolution des types, la gestion des sessions et la conversion des valeurs, exposant des outils qui permettent aux utilisateurs de poser des questions en langage naturel comme « Quelle est la température dans la salle de bain ? », « Y a-t-il des fenêtres ouvertes ? », « Réglez le chauffage du salon à 21 degrés » ou « Montrez-moi tous les appareils avec une batterie faible ». Il prend également en charge des opérations avancées comme le renommage des appareils pour suivre des conventions de nommage, la recherche de noms de canaux incohérents et la vérification de la santé des appareils. **Caractéristiques clés :** - **Connexion CCU directe** : Pas d'addons ni de cloud ; utilise le point de terminaison JSON-RPC standard. - **Transports multiples** : Fonctionne comme sous-processus (stdio) ou comme serveur HTTP autonome (Docker). - **Support Docker** : Images publiées pour linux/amd64 et linux/arm64, avec attestation pour la sécurité de la chaîne d'approvisionnement. - **Profils CCU multiples** : Configurez et basculez entre plusieurs CCU (par exemple, prod et dev) depuis un seul serveur. - **Sécurité** : Authentification par jeton Bearer (auto-généré ou explicite), protection contre le rebinding DNS, liste blanche CORS, support TLS (y compris l'épinglage de certificats auto-signés) et intégration optionnelle de fail2ban. - **Assistant de configuration** : La commande interactive `init` sonde la CCU, épingle les certificats TLS, teste la connexion et écrit un fichier `.env` prêt à l'emploi. Un mode de configuration conversationnel permet à un LLM de guider le processus via le chat. - **Diagnostics** : La commande `doctor` valide la configuration de bout en bout. - **Limitation de débit** : Limites de débit intégrées en rafale et soutenues pour protéger la CCU. - **Interrogation des ressources** : Interrogation optionnelle pour les notifications de changement de ressources MCP. **Installation et utilisation :** - **Démarrage rapide (stdio)** : Définissez les variables d'environnement `CCU_HOST` et `CCU_PASSWORD`, puis exécutez `npx ccu-mcp --stdio`. Configurez votre client MCP (par exemple, Claude Code) avec un fichier `.mcp.json`. - **Docker (HTTP)** : Tirez l'image, exécutez-la avec des variables d'environnement et obtenez le jeton d'authentification depuis le volume de données du conteneur. Configurez le client avec l'URL du serveur et le jeton Bearer. - **Configuration** : Tous les paramètres via des variables d'environnement (voir le tableau dans le README). Prend en charge les env inline, les fichiers `.env` ou les exports shell. - **Options CLI** : `init`, `doctor`, `secret`, `--stdio`, `--http`, `--env`, `--version`, `--help`. **Considérations de sécurité :** - Le serveur utilise par défaut HTTP simple mais avertit lors de l'envoi de jetons sur des interfaces non-bouclées ; définissez `MCP_ALLOW_PLAINTEXT=true` pour reconnaître. - Pour un accès à distance, utilisez TLS (proxy inverse ou HTTPS natif) et définissez `MCP_ALLOWED_HOSTS` pour éviter les erreurs 403. - La rotation des jetons est prise en charge avec des périodes de grâce pour éviter les perturbations côté client. - CORS est refusé par défaut ; autorisez les origines pour les clients basés sur navigateur. **Prérequis :** Node.js 24+ (pour source/stdio) ou Docker. Une CCU HomeMatic en fonctionnement avec des identifiants administrateur. **Exemple de configuration client (stdio) :** ```json { "mcpServers": { "ccu-mcp": { "command": "npx", "args": ["ccu-mcp", "--stdio"], "env": { "CCU_HOST": "votre-nom-dhote-ou-ip-ccu", "CCU_PASSWORD": "votre-mot-de-passe-admin-ccu" } } } } ``` **Exemple de configuration client (HTTP) :** ```json { "mcpServers": { "ccu-mcp": { "url": "http://votre-ip-serveur:3000", "headers": { "Authorization": "Bearer COLLEZ-VOTRE-JETON-ICI" } } } } ``` Le projet est open-source et accueille les contributions. Il inclut des badges pour OpenSSF Best Practices et Scorecard, indiquant un accent sur la sécurité et la qualité.