halo-light

Serveur MCP pour les lumières Philips Hue, écrit à neuf sur l'API locale CLIP v2 du pont (https, en-tête hue-application-key). Un assistant (Claude, Lyra, etc.) peut lire l'état des lumières, des pièces et des scènes, puis les commander par identifiant ou par nom.

Fonctionnalités

• Lumières, pièces, zones et scènes de l'API v2 (light, grouped_light, room, zone, scene).
• Adressage par identifiant (UUID v2, ou ancien identifiant numérique v1 comme 12) ou par nom.
• Noms insensibles à la casse et aux accents : correspondance exacte d'abord, partielle seulement si elle est unique, sinon une erreur liste les candidats.
• Une scène est activée dans sa propre pièce : aucun groupe n'est codé en dur.
• Couleur par nom (rouge, bleu, orange...), hexadécimal (#ff8800), RGB ou xy ; température de blanc en Kelvin.
• Erreurs remontées comme erreurs MCP (isError) avec un message exploitable par le modèle.
• Annotations MCP sur chaque outil (readOnlyHint, destructiveHint, idempotentHint).
• Extension optionnelle hue_beat (synchronisation lumière / musique) via un script externe.

Installation

Prérequis : Python 3.10 ou plus récent et un pont Hue sur le réseau local.

git clone https://github.com/amineutron/halo-light.git
cd halo-light
uv sync

Configuration

L'application a besoin de l'adresse du pont (facultative : elle est découverte automatiquement s'il n'y a qu'un pont) et d'une clé d'application.

Appairage

uv run halo-light pair            # adresse découverte automatiquement
uv run halo-light pair --host <adresse-du-pont>

Appuyez sur le bouton du pont quand la commande le demande. La clé est enregistrée dans ~/.config/halo-light/config.json, créé en mode 0600 (dossier en 0700). La clé n'est jamais affichée.

uv run halo-light discover liste les ponts connus du service de découverte de Philips.

Variables d'environnement (prioritaires sur le fichier)

Le pont présente un certificat signé par une autorité privée de Signify : par défaut il n'est pas vérifié (réseau local). Pour l'épingler, fournissez l'autorité avec HUE_BRIDGE_CA_CERT.

Brancher le serveur à un client MCP

{
  "mcpServers": {
    "hue": {
      "command": "uv",
      "args": ["--directory", "/chemin/vers/halo-light", "run", "halo-light"],
      "env": { "HUE_APP_KEY": "<cle>" }
    }
  }
}

Évitez d'écrire la clé en clair : préférez le fichier en 0600 ou un gestionnaire de secrets.

Outils exposés

Tous les outils d'action acceptent light_id ou light_name (lumières), group_id ou group_name (pièces et zones). Si les deux sont fournis, l'identifiant l'emporte.

Aucun outil n'est destructif : les changements d'état sont réversibles et rien n'est supprimé sur le pont.

Exemples de résolution de noms

• light_name="cafe" trouve « Lampe Café » (accents et casse ignorés).
• light_name="salon" avec « Salon Plafond » et « Salon Lampadaire » renvoie une erreur qui liste les deux.
• scene_name="relax" existant dans deux pièces renvoie Relax (Salon), Relax (Chambre) : ajoutez group_name="chambre".

Extension optionnelle hue_beat

Les outils hue_beat_* pilotent un script externe de synchronisation lumière / musique (par exemple via l'Entertainment API). Ce script n'est pas fourni ici. Indiquez son chemin :

export HUE_BEAT_PATH=/chemin/vers/hue_beat.py

Contrat attendu du script :

• lancé en arrière-plan avec python <script> --palette=P [--mode=M] [--bass-only] ;
• écrit son PID dans HUE_BEAT_PID_FILE et un état JSON (mode, palette, bpm...) dans HUE_BEAT_STATE_FILE ;
• lit des commandes JSON (palette, mode, brightness, floor, sensitivity) dans HUE_BEAT_CTRL_FILE ;
• s'arrête proprement sur SIGTERM.

Les trois fichiers sont par défaut dans le dossier temporaire du système (hue_beat.pid, hue_beat.state.json, hue_beat.ctrl) ; adaptez les variables aux chemins réels du script. Sans HUE_BEAT_PATH, ces outils répondent par une erreur claire et le reste du serveur fonctionne normalement. HUE_BEAT_PYTHON (facultatif) désigne l'interpréteur qui lance le script, utile quand celui-ci a besoin de paquets (numpy, audio) absents de l'environnement du serveur ; sinon c'est l'interpréteur du serveur. Pendant la synchronisation, le pont peut ignorer les commandes sur les lumières de la zone de divertissement.

Brancher Lyra

Le script ironman-hue (hue_beat.py) de Lyra utilise des chemins fixes, définis par les constantes PID_FILE, STATE_FILE et CTRL_FILE en tête du script. Pour que les outils hue_beat_* les retrouvent, posez ces variables dans l'environnement du serveur avec les mêmes valeurs :

export HUE_BEAT_PATH=<chemin du script hue_beat.py>
export HUE_BEAT_PID_FILE=<valeur de PID_FILE>
export HUE_BEAT_STATE_FILE=<valeur de STATE_FILE>
export HUE_BEAT_CTRL_FILE=<valeur de CTRL_FILE>

Les valeurs par défaut du serveur (hue_beat.pid, etc.) ne correspondent pas à celles du script : sans ces variables, le statut et les réglages ne l'atteignent pas.

La synchronisation en streaming (DTLS) demande en plus un utilisateur « entertainment », sa clé client et la zone de divertissement. Plutôt que de les écrire dans la configuration du client MCP, ajoutez une section beat au fichier ~/.config/halo-light/config.json (mode 0600) ; le serveur les transmet au script sous les noms HUE_USER, HUE_CLIENTKEY et HUE_AREA_ID, sans jamais les afficher :

{
  "bridge_ip": "<adresse-du-pont>",
  "app_key": "<cle>",
  "beat": { "username": "<utilisateur>", "clientkey": "<cle-client>", "area_id": "<zone>" }
}

Sans section beat, HUE_USER reprend la clé d'application. Une variable d'environnement déjà définie l'emporte toujours.

Développement

uv sync
uv run ruff check . && uv run ruff format --check .
uv run pytest

Les tests s'exécutent contre un faux pont en mémoire (httpx.MockTransport, voir tests/fake_bridge.py) et ne touchent jamais un vrai pont. Voir CONTRIBUTING.md.

Inspiration et remerciements

Ce projet est une réécriture indépendante, inspirée par l'interface du serveur ThomasRohde/hue-mcp (licence MIT, © Thomas Rohde), lui-même construit sur la bibliothèque phue de Nathanael Lecaude. Les noms de la plupart des outils sont conservés pour rester compatibles avec les assistants qui les appellent déjà.

Aucune ligne de code d'implémentation n'est reprise de ces projets : tout est écrit à partir de la documentation officielle de l'API Hue (CLIP v2). Merci à Thomas Rohde pour le point de départ. Contrairement à ces projets, qui reposent sur l'API v1, celui-ci utilise l'API v2 (identifiants UUID, scènes rattachées à leur pièce).

Différences avec hue-mcp

• API v2 au lieu de v1 (phue n'est plus nécessaire) ; httpx asynchrone.
• Pas de groupe par défaut codé en dur (l'ancien groupe 81) : un groupe ou une pièce doit être désigné, sauf pour les scènes qui portent leur propre pièce.
• Pas de cache à rafraîchir : l'état est lu en direct (refresh_lights n'existe plus).
• Non repris pour l'instant : create_group, quick_scene, les préréglages de couleur et les effets (set_light_effect). set_color remplace les préréglages.
• Nouveautés : set_color, set_color_xy, groupes par nom, appairage et découverte en ligne de commande.

Licence

MIT. Les projets dont ce serveur s'inspire sont cités dans NOTICE.