Plugin Mcp IA (Jeedom)

:warning: IMPORTANT

S’il n’y a pas d’information sur la mise à jour, c’est que celle-ci concerne uniquement de la mise à jour de documentation, de traduction ou de texte.

Présentation

Le plugin mcpIA expose l’écosystème Jeedom via le protocole MCP (Model Context Protocol) à des agents IA externes (Claude Desktop, Cursor, n8n, LangChain, etc.).

Grâce à ce plugin, un agent IA peut lire l’état de vos équipements, exécuter des actions, consulter l’historique des capteurs, parcourir vos logs et bien plus — le tout de manière sécurisée via un token Bearer par profil.

Demande d’aide sur Community

Pour toute demande d’aide, utilisez le bouton Post Community (icône bleue) disponible directement sur la page de configuration du plugin — il pré-remplit automatiquement votre message avec les informations essentielles.

Merci par ailleurs de fournir systématiquement les informations suivantes :

Compatibilité

:warning: IMPORTANT

La version minimum du core de Jeedom requise pour le plugin est la version 4.4.8 avec un OS Debian 11 minimum.

Versions OS compatibles :

Plateformes compatibles :

Démarrage rapide

Bienvenue ! Si vous venez d’installer mcpIA et souhaitez être opérationnel en quelques minutes, suivez ce guide.

Étape 1 — Vérifier les dépendances et lancer le démon

Dans Plugins → mcpIA → Configuration, vérifiez que les dépendances sont installées (section Dépendances → statut vert) et que le démon tourne (section Démon → statut “OK”). Si ce n’est pas le cas, cliquez sur “Relancer” pour les dépendances, puis “(Re)Démarrer” pour le démon.

Étape 2 — Créer un profil

Depuis la page principale du plugin, cliquez sur “Ajouter”, donnez un nom au profil (ex : “Claude Desktop”) et sauvegardez. Dans la section “Équipements”, cliquez sur “Configurer”, cochez les équipements à exposer à l’agent, puis sauvegardez.

Étape 3 — Copier l’URL et le token

Dans la section “Serveur MCP” de la fiche d’équipement, notez votre URL (locale ou externe) et copiez le Token Bearer avec le bouton Copier.

Étape 4 — Connecter votre client IA

Je veux… Client recommandé
Utiliser Claude dans un navigateur, sans rien installer Claude.ai web — flux OAuth 2.1 automatique, HTTPS requis
Utiliser l’application Claude Desktop (Windows / macOS) Claude Desktop — configuration JSON
Coder dans VS Code avec GitHub Copilot VS Code + GitHub Copilot
Coder dans Cursor avec un assistant IA Cursor
Automatiser avec n8n, LangChain, Continue.dev… Autres clients MCP

Cliquez sur le client correspondant dans la section “Utilisation avec un client MCP” ci-dessous pour les instructions détaillées.

Installation des dépendances et lancement du Démon

Dépendances

Le plugin installe automatiquement ses dépendances Python (environnement pyenv + venv, Python 3.12.12, librairies mcp et aiohttp) lors de l’installation ou d’une mise à jour si nécessaire. Si l’installation automatique a échoué, rendez-vous sur la page de configuration du plugin, section Dépendances, et cliquez sur Relancer.

:warning: NOTE

L’installation des dépendances inclut la compilation de Python via pyenv. La durée varie selon le matériel : de 2 à 5 minutes sur une VM ou un système récent, jusqu’à 20 à 30 minutes sur des configurations plus modestes (Raspberry Pi, Odroid…). Ne pas interrompre le processus.

Les logs d’installation se trouvent dans le fichier mcpia_update, accessible depuis la page de configuration du plugin ou depuis le menu Analyse / Logs de Jeedom.

:warning: NOTE

Le plugin configure automatiquement les modules Apache nécessaires (proxy, proxy_http, headers) lors de l’installation — aucune action manuelle n’est requise sous une installation Jeedom standard.

Réparation des dépendances

Ces options sont à utiliser uniquement en cas de problème avec l’installation des dépendances. Après activation, il est nécessaire de relancer l’installation des dépendances.

:warning: NOTE

Ces options se désactivent automatiquement après usage — c’est normal. Elles ne s’appliquent qu’une seule fois par activation.

:warning: IMPORTANT

La mise à jour système forcée (option 1) peut corrompre votre installation si elle échoue. Elle est déconseillée sur une Box Jeedom officielle. En cas de doute, demandez conseil sur le Community avant de l’activer.

Il est conseillé de procéder en deux temps : activez d’abord uniquement la mise à jour système (option 1), relancez les dépendances, puis redémarrez Jeedom avant d’appliquer les options 2 et 3.

Lancement du Démon

Une fois les dépendances installées, cliquez sur le bouton “(Re)Démarrer” dans la section Démon de la page de configuration. Le statut doit passer à “OK” (voyant vert).

Si le démon refuse de se lancer, consultez en priorité les logs mcpia_update (problème d’installation des dépendances) et mcpia_daemon (erreur au démarrage du démon). En cas de blocage, postez sur le Community avec les informations listées dans la section Demande d’aide sur Community ci-dessus.

Configuration du Plugin

Configuration globale (niveau plugin)

Dans Plugins → Gestion des plugins → mcpIA, la section “Configuration” expose les paramètres globaux du plugin :

:information_source: NOTE

Le port 6270 n’est pas choisi au hasard : sur un clavier T9, 6 → M, 2 → C, 7 → P — soit MCP ! Le 0 final complète le numéro de port. Si ce port est déjà utilisé sur votre serveur, vous pouvez le changer ici sans impact fonctionnel.

Créer un profil IA

Dans Jeedom, un profil mcpIA est un équipement au sens du plugin — c’est l’objet de base que vous créez, nommez et configurez comme n’importe quel équipement Jeedom. Chaque profil représente une connexion distincte : un token d’authentification, une liste d’équipements autorisés, une liste de scénarios accessibles et des droits configurables indépendamment. Vous pouvez créer plusieurs profils pour des usages ou des agents différents.

Depuis la page de gestion du plugin, cliquez sur “Ajouter”. Donnez un nom au profil (ex : Claude Desktop, Copilot, Profil famille) et sauvegardez.

La page de l’équipement s’organise en cinq sections :

Section “Paramètres généraux”

Section “Serveur MCP”

:warning: ATTENTION

Ne communiquez jamais votre token MCP. Il donne un accès au périmètre d’équipements que vous avez autorisés. En cas de doute, utilisez le bouton Renouveler — l’ancien token est immédiatement invalidé, sans redémarrage du démon.

Section “Équipements”

Le panneau affiche l’arborescence complète de votre installation, organisée par Pièce → Équipement → Commandes :

  1. Cochez la case “Autoriser” à gauche du nom de l’équipement pour l’exposer à l’agent.
  2. Par défaut, toutes les commandes de l’équipement sont exposées. Vous pouvez affiner en cochant/décochant individuellement chaque commande.
  3. Le champ “Description sémantique” (optionnel) permet de donner à l’agent une description en langage naturel de l’équipement (ex : “Ampoule Philips Hue du bureau, variable en intensité et en couleur”). Plus la description est précise, meilleur est le comportement de l’agent.

:information_source: NOTE

Comment rédiger une bonne description sémantique ? Une description efficace répond à trois questions : quoi (nature de l’équipement), où (localisation précise si le nom de pièce est ambigu), comment (capacités ou contraintes particuliers). Exemples :

  • Court et efficace : “Prise connectée de la cafetière, cuisine”
  • Détaillé : “Thermostat du salon Netatmo, contrôle la chaudière principale, plage 7-25°C”
  • À éviter : laisser vide si le nom de l’équipement est déjà clair (ex : “Télévision Salon” n’a pas besoin de description). Ne pas paraphraser le nom — apporter une information supplémentaire.

:information_source: NOTE

Une future version du plugin proposera une option de génération automatique des descriptions sémantiques via IA — plus besoin de les saisir manuellement.

Une fois votre sélection faite, cliquez sur “Sauvegarder”. L’arborescence est envoyée immédiatement au démon — les changements sont pris en compte à chaud, sans redémarrage.

La barre de recherche permet de filtrer l’arborescence par nom de pièce, d’équipement ou de commande.

:information_source: NOTE

Le bouton crayon à droite d’un équipement ouvre directement la page de configuration du plugin propriétaire. Le bouton engrenage ouvre la configuration avancée de l’équipement ou de la commande.

Section “Logs”

Ces deux options d’autorisation sont désactivées par défaut. Les activer uniquement si vous faites confiance à l’agent pour effectuer ces opérations.

Le panneau affiche la liste de tous les fichiers de log disponibles sur votre Jeedom, répartis en Logs système et plugins et Logs scénarios (filtrable via la barre de recherche) :

  1. Cochez la case “Autoriser” à gauche du nom du fichier.
  2. Vérifiez ou modifiez le libellé — c’est le nom lisible que l’agent utilisera pour ce log (ex : “Plugin mcpIA”, “Scénario Réveil”). Un libellé est automatiquement suggéré selon le nom du fichier.

Une fois votre sélection faite, cliquez sur “Sauvegarder”. La liste des logs autorisés est envoyée immédiatement au démon — les changements sont pris en compte à chaud, sans redémarrage.

Section “Scénarios”

Ces options de modification sont désactivées par défaut. Les activer uniquement si vous faites confiance à l’agent pour modifier la logique de vos scénarios.

Le panneau affiche la liste de tous les scénarios disponibles sur votre Jeedom, organisés par groupe (sections rétractables), avec leur nom, objet parent et état actif/inactif (filtrable via la barre de recherche) :

  1. Cochez la case “Autoriser” à gauche du nom du scénario pour le rendre accessible à l’agent.
  2. Utilisez le bouton lien (📎) à droite pour ouvrir directement la page du scénario dans Jeedom.
  3. Utilisez les boutons “Tout ouvrir” / “Tout fermer” pour naviguer dans les groupes.

Une fois votre sélection faite, cliquez sur “Sauvegarder”. La liste des scénarios autorisés est envoyée immédiatement au démon — les changements sont pris en compte à chaud, sans redémarrage.

Section “Centre de messages”

Cette option est désactivée par défaut. Utile pour permettre à l’agent de nettoyer les alertes accumulées.

Section “Variables”

Cette option est désactivée par défaut. Elle couvre à la fois les opérations d’écriture et de suppression — une seule option pour les deux. Pour les variables locales à un scénario, le scénario concerné doit également figurer dans la whitelist des scénarios du profil ; sinon l’opération est refusée même si cette option est activée.

Section “Moteur de tâches”

Cette option est désactivée par défaut. Le contrôle des tâches planifiées peut affecter le fonctionnement des plugins — à activer uniquement si vous faites confiance à l’agent pour ces opérations.

Section “Batteries”

Cette liste est indépendante de la liste des équipements exposés au LLM : un équipement peut avoir sa batterie surveillée sans être exposé aux commandes IA. Par exemple, un interrupteur Hue que vous ne souhaitez pas rendre contrôlable par l’agent peut quand même apparaître dans les rapports de batterie.

Le panneau affiche tous les équipements Jeedom actifs qui ont une batterie déclarée, organisés par pièce (sections rétractables), avec le niveau de charge actuel de chaque équipement (filtrable via la barre de recherche) :

  1. Cochez la case “Autoriser” à gauche du nom pour inclure l’équipement dans les rapports batterie.
  2. Utilisez les boutons “Tout sélectionner” / “Tout désélectionner” pour une sélection rapide, ou “Tout ouvrir” / “Tout fermer” pour naviguer dans l’arborescence.

Une fois votre sélection faite, cliquez sur “Sauvegarder”. La liste est immédiatement prise en compte — les changements ne nécessitent pas de redémarrage du démon.

Section “Sauvegardes”

Cette option est désactivée par défaut. Déclencher une sauvegarde est une opération longue (30 à 120 secondes) et consommatrice de ressources — à activer uniquement si vous faites confiance à l’agent pour initier des sauvegardes.

Section “Mises à jour”

Ces deux options sont désactivées par défaut. Appliquer une mise à jour redémarre le plugin concerné — à activer uniquement si vous faites confiance à l’agent pour ces opérations. La mise à jour du Core Jeedom n’est jamais autorisée via ces outils (protection système obligatoire).

Section “Plugins & Démons”

Cette option est désactivée par défaut. Démarrer ou arrêter un démon de plugin peut interrompre des automations qui en dépendent — à activer uniquement si vous faites confiance à l’agent pour ces opérations. L’agent ne peut pas contrôler le plugin mcpIA lui-même via ces outils.

Section “Accès OAuth”

Cette section gère les connexions des clients MCP modernes qui utilisent le flux OAuth 2.1 (Claude.ai web, MCP Inspector, Continue.dev, n8n…) au lieu du Bearer token statique.

:information_source: NOTE

Le Bearer token statique et les connexions OAuth coexistent indépendamment. Révoquer les tokens OAuth n’affecte pas le Bearer token statique, et renouveler le Bearer token n’affecte pas les connexions OAuth.

Utilisation avec un client MCP

Le plugin mcpIA expose Jeedom comme un serveur MCP accessible par n’importe quel client compatible. L’URL de connexion est l’URL de votre Jeedom (locale ou distante) suivie de /mcp :

https://<url-de-votre-jeedom>/mcp

:information_source: NOTE

L’URL locale et l’URL externe sont disponibles dans la page de l’équipement mcpIA, dans la section “Serveur MCP”. Le Token Bearer associé au profil y est également disponible (bouton Copier).

:information_source: NOTE

Claude.ai (version web) est compatible avec mcpIA via le flux OAuth 2.1. Depuis la v1.0.0, mcpIA implémente le protocole OAuth 2.1 avec PKCE requis par Claude.ai web pour les serveurs MCP distants. Voir la section Avec Claude.ai (version web) ci-dessous.

Avec Claude.ai (version web) — OAuth 2.1

Claude.ai (interface web d’Anthropic) supporte les serveurs MCP distants via un flux OAuth 2.1 automatique — aucun token à configurer manuellement.

Étape 1 — Ouvrir Claude.ai et ajouter un serveur MCP

Dans Claude.ai, ouvrez le menu lateral, puis dans la section Outils (ou Settings → Extensions), cliquez sur “Ajouter un serveur MCP”. Renseignez l’URL de votre Jeedom :

https://<url-de-votre-jeedom>/mcp

:warning: ATTENTION

Claude.ai web exige une connexion HTTPS. Une URL http:// est refusée. Si votre Jeedom n’est accessible qu’en HTTP sur votre réseau local, utilisez Claude Desktop (Option B) à la place.

Étape 2 — Flux d’autorisation OAuth

Claude.ai redirige automatiquement vers la page d’autorisation mcpIA sur votre Jeedom. Connectez-vous à Jeedom si ce n’est pas déjà fait, puis :

  1. Sélectionnez le profil mcpIA à utiliser depuis le menu déroulant
  2. Cliquez sur “Autoriser”

Claude.ai reçoit automatiquement un access token (valide 1h) et un refresh token (valide 30 jours, renouvelé automatiquement). Vous n’avez rien d’autre à faire.

:information_source: NOTE

Pour qu’un utilisateur Jeedom non-administrateur puisse approuver une connexion OAuth, il doit figurer dans la liste Utilisateurs et sessions de la section Accès OAuth du profil mcpIA concerné. Les administrateurs Jeedom ont toujours accès à tous les profils actifs.

Gérer et révoquer les connexions

Depuis la fiche équipement mcpIA dans Jeedom, cliquez sur “Gérer” dans la section Accès OAuth pour voir toutes les sessions actives, leur IP de connexion et les révoquer si nécessaire.

Avec Claude Desktop

Claude Desktop est le client officiel d’Anthropic. Il supporte le protocole MCP.

:information_source: NOTE

Les étapes ci-dessous sont rédigées pour Windows. Sur macOS, le fichier de configuration se trouve dans ~/Library/Application Support/Claude/claude_desktop_config.json. Sur Linux, dans ~/.config/Claude/claude_desktop_config.json. Par ailleurs, le problème de chemin avec npx décrit à l’Étape 3 est spécifique à Windows — sur macOS et Linux, npx fonctionne généralement sans ce problème.

Étape 1 — Installer Node.js

Selon votre version de Claude Desktop, vous aurez peut-être besoin de mcp-remote (voir Étape 3). Par précaution, installez Node.js depuis nodejs.org (version LTS recommandée) si ce n’est pas déjà fait.

Étape 2 — Autoriser l’exécution de scripts PowerShell (Windows uniquement)

Sur Windows, l’exécution de scripts est bloquée par défaut. Sans cette étape, npm install échoue avec un message d’erreur PowerShell mentionnant que “l’exécution de scripts est désactivée sur ce système”.

Option recommandée — Ouvrez Terminal (clic droit sur le menu Démarrer → Terminal) et exécutez :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Cette commande s’applique uniquement à votre compte utilisateur.

Si vous êtes administrateur de la machine — Ouvrez Terminal en tant qu’administrateur (clic droit sur le menu Démarrer → Terminal (administrateur)) et exécutez :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Cette commande s’applique à tous les utilisateurs de la machine.

Étape 3 — Installer mcp-remote

Ouvrez un terminal et installez mcp-remote globalement :

npm install -g mcp-remote

:information_source: NOTE

Pourquoi ne pas utiliser npx mcp-remote ? Sur Windows, npx est installé dans C:\Program Files\nodejs\ (chemin avec espace). Claude Desktop ne gère pas correctement ce chemin et échoue au démarrage. En installant mcp-remote globalement, il s’installe dans %APPDATA%\npm\ (sans espace) et fonctionne correctement.

Étape 4 — Configurer Claude Desktop

Dans Claude Desktop, ouvrez Paramètres → Développeur et cliquez sur le bouton “Modifier la config” — cela ouvre l’explorateur de fichiers dans le répertoire contenant le fichier de configuration. Ouvrez le fichier claude_desktop_config.json avec un éditeur de texte.

:information_source: NOTE

Le bloc JSON à copier est disponible directement depuis la fiche d’équipement mcpIA, via le bouton “Afficher” situé à la ligne “Configuration client MCP”. Il est pré-rempli avec l’URL et le token du profil.

Ajoutez votre serveur mcpIA dans la section mcpServers. Deux formats sont possibles selon votre version de Claude Desktop :

Option A — Transport HTTP natif (non supporté sur Windows à ce jour)

:warning: ATTENTION

Claude Desktop sur Windows ne supporte actuellement que le transport stdio — il exige un champ "command" dans la configuration. Le format "type": "http" (transport HTTP natif) n’est pas encore reconnu et provoque une erreur. En attendant son support officiel, utilisez l’Option B ci-dessous.

{
  "mcpServers": {
    "jeedom": {
      "type": "http",
      "url": "https://<url-de-votre-jeedom>/mcp",
      "headers": {
        "Authorization": "Bearer <votre-token>"
      }
    }
  }
}

Option B — Via mcp-remote (méthode recommandée)

En accès local (http://) :

{
  "mcpServers": {
    "jeedom": {
      "command": "mcp-remote",
      "args": [
        "http://192.168.1.100/mcp",
        "--header",
        "Authorization:Bearer <votre-token>",
        "--allow-http"
      ]
    }
  }
}

En accès distant (https://) :

{
  "mcpServers": {
    "jeedom": {
      "command": "mcp-remote",
      "args": [
        "https://xyz.eu.jeedom.link/mcp",
        "--header",
        "Authorization:Bearer <votre-token>"
      ]
    }
  }
}

:warning: ATTENTION

Dans l’Option B, il ne doit pas y avoir d’espace entre Authorization: et Bearer dans l’argument --header.

Accès local en http:// : mcp-remote bloque les connexions HTTP non chiffrées par mesure de sécurité. L’option --allow-http est obligatoire quand l’URL commence par http://. Sans elle, mcp-remote refuse la connexion. Elle est inutile pour les URLs https://.

Remplacez :

:bulb: ASTUCE

Le bouton “Afficher” (section Serveur MCP de la fiche équipement) génère automatiquement le bon snippet avec ou sans --allow-http selon le protocole de votre URL.

Si vous avez plusieurs profils mcpIA, vous pouvez les déclarer comme serveurs distincts dans mcpServers, chacun avec son propre token.

Étape 5 — Premier lancement

Fermez entièrement Claude Desktop (y compris depuis la barre des tâches / zone de notification), puis relancez-le. Pour vérifier que les outils sont bien disponibles, vous pouvez demander directement à Claude : “Quels outils MCP as-tu à disposition ?” — il listera les outils Jeedom s’il les a bien chargés.

Vous pouvez tester avec des questions comme :

Avec Cursor

Dans Cursor, ouvrez Settings → MCP et ajoutez un serveur MCP de type HTTP, ou éditez directement le fichier .cursor/mcp.json à la racine de votre projet.

:information_source: NOTE

Le bloc JSON à copier est disponible directement depuis la fiche d’équipement mcpIA, via le bouton “Afficher” → onglet Cursor.

{
  "mcpServers": {
    "jeedom": {
      "url": "https://<url-de-votre-jeedom>/mcp",
      "headers": {
        "Authorization": "Bearer <votre-token>"
      }
    }
  }
}

Remplacez "jeedom" par le nom souhaité, <url-de-votre-jeedom> par l’URL de votre Jeedom, et <votre-token> par le token Bearer de votre profil mcpIA.

Pour activer : ouvrez Settings → MCP dans Cursor — le serveur doit apparaître avec un voyant vert. Si ce n’est pas le cas, cliquez sur “Refresh”. Pour utiliser les outils Jeedom, ouvrez le chat (Ctrl+L), basculez en mode Agent, puis demandez par exemple : “Quels outils MCP as-tu à disposition ?”.

Avec VS Code (GitHub Copilot)

VS Code supporte nativement les serveurs MCP depuis la version 1.99. Une fois configuré, GitHub Copilot en mode Agent peut utiliser tous les outils et ressources exposés par mcpIA.

:information_source: NOTE

Le bloc JSON à copier est disponible directement depuis la fiche d’équipement mcpIA, via le bouton “Afficher” → onglet VS Code.

Via la palette de commandes : Ctrl+Shift+P → MCP: Add Server → choisir HTTP → renseigner l’URL → donner un nom (ex : jeedom). VS Code crée automatiquement l’entrée dans .vscode/mcp.json. Ajouter ensuite le header Authorization manuellement.

Via settings.json (configuration utilisateur globale) :

{
  "mcp": {
    "servers": {
      "jeedom": {
        "type": "http",
        "url": "https://<url-de-votre-jeedom>/mcp",
        "headers": {
          "Authorization": "Bearer <votre-token>"
        }
      }
    }
  }
}

Via .vscode/mcp.json (configuration par projet) :

{
  "servers": {
    "jeedom": {
      "type": "http",
      "url": "https://<url-de-votre-jeedom>/mcp",
      "headers": {
        "Authorization": "Bearer ${env:JEEDOM_MCP_TOKEN}"
      }
    }
  }
}

:information_source: NOTE

Utiliser ${env:JEEDOM_MCP_TOKEN} pour éviter de stocker le token en clair dans un fichier commité. Définir la variable dans l’environnement système ou dans un fichier .env ignoré par Git.

Pour activer : ouvrez Copilot Chat → passez en mode Agent → le serveur jeedom apparaît dans la liste des MCP servers disponibles.

Avec d’autres clients MCP

Le protocole MCP est ouvert — tout client compatible Streamable HTTP peut se connecter au plugin mcpIA :

Client Méthode de connexion
n8n Nœud “MCP Client” — URL + header Authorization: Bearer <token>
OpenWebUI Ajouter un outil MCP dans les préférences (Settings > Tools) — URL + header Authorization: Bearer <token>
LangChain / LangGraph streamablehttp_client depuis mcp Python SDK
Continue.dev Config MCP dans ~/.continue/config.json

:information_source: NOTE

Le plugin utilise le transport Streamable HTTP (mode sans état). Certains clients anciens qui n’utilisent que SSE ou stdio ne sont pas compatibles directement — vérifiez que votre client supporte bien HTTP/MCP.

Outils et Ressources disponibles

Le plugin mcpIA donne accès à l’agent IA à des ressources (informations que l’agent peut consulter librement) et à des outils (actions que l’agent peut exécuter sur votre Jeedom).

Tout ce qui est listé ici est limité aux équipements et logs que vous avez explicitement autorisés dans la configuration du profil. L’agent ne peut ni voir ni agir en dehors de ce périmètre.

Ressources

Les ressources sont des données auxquelles l’agent peut accéder à tout moment pour comprendre ce qui est disponible dans votre installation. Il les consulte automatiquement en arrière-plan quand il en a besoin.

Point d’entrée principal : la ressource jeedom://home/devices est lue automatiquement par l’agent — elle contient tous les identifiants (cmdId) dont il a besoin pour appeler executeActions, readValues, readHistory, getStats et getStateDuration. Sur les grandes installations où la ressource est trop volumineuse, l’outil searchDevices permet de filtrer l’arborescence par pièce, équipement, description, nom de commande, type générique ou identifiant logique (logicalId).

Catalogue de vos équipements et commandes

Ressource jeedom://home/devices

Donne accès à l’inventaire complet de tous les équipements et commandes que vous avez autorisés, organisé par pièce. C’est le “plan” de votre installation que l’agent consulte pour savoir ce qu’il peut faire : quels appareils existent, dans quelle pièce, et quelles actions ou informations sont disponibles pour chacun.

Cette ressource est également mise à jour en temps réel : lorsque vous modifiez la liste des équipements autorisés dans Jeedom et sauvegardez, les clients MCP connectés qui supportent les notifications reçoivent automatiquement un signal de mise à jour — sans redémarrage ni reconnexion.

Exemples de prompts :

  • “Quels équipements peux-tu contrôler dans ma maison ?”
  • “Donne-moi la liste de tous les appareils disponibles pièce par pièce.”
  • “Qu’est-ce que tu as accès dans le salon ?”

Liste des fichiers de log disponibles

Ressource jeedom://home/logs

Donne accès à la liste des fichiers de log que vous avez autorisés, avec leur nom et leur libellé. L’agent consulte cette ressource pour savoir quels logs il peut lire ou dans lesquels il peut effectuer des recherches.

Exemples de prompts :

  • “Quels logs peux-tu consulter ?”
  • “As-tu accès aux logs du plugin mcpIA ?”

Outils — Équipements et domotique

Explorer les équipements disponibles

Outil searchDevices

Filtre l’arborescence des équipements autorisés avec six critères combinables : par pièce, par nom d’équipement, par description sémantique, par nom de commande, par type générique Jeedom ou par identifiant logique (logicalId). L’agent l’utilise automatiquement sur les grandes installations quand la ressource jeedom://home/devices est trop volumineuse pour tenir en une seule réponse — vous n’avez généralement pas besoin de le demander explicitement.

Exemples de prompts :

  • “Quels équipements peux-tu contrôler dans le salon ?”
  • “Montre-moi tous les équipements de type lumière disponibles.”
  • “Quelles lumières peux-tu contrôler ?”

Agir sur vos équipements

Outil executeActions

Permet à l’agent d’exécuter une ou plusieurs actions sur vos équipements Jeedom : allumer/éteindre un appareil, régler un niveau (variateur, thermostat), choisir une couleur (ampoule connectée), ou envoyer une notification. Plusieurs actions peuvent être déclenchées en une seule demande.

:information_source: NOTE

Certains plugins proposent des commandes enrichies avec des champs supplémentaires — par exemple le plugin DiscordLink permet d’envoyer des messages formatés (embed) avec titre, description, couleur, footer, pièces jointes, etc. L’agent découvre automatiquement ces champs dans le catalogue des équipements (jeedom://home/devices) et peut les utiliser directement dans ses requêtes, sans configuration supplémentaire de votre part.

Exemples de prompts :

  • “Allume la lumière du salon.”
  • “Éteins toutes les lumières du rez-de-chaussée.”
  • “Mets le chauffage du bureau à 20 degrés.”
  • “Règle la lampe du couloir à 40% et mets-la en orange.”
  • “Lance la scène “Cinéma” dans le salon.”
  • “Envoie une alerte sur mon téléphone pour me dire que la porte du garage est ouverte.”
  • “Poste un message dans Discord avec un bloc coloré en bleu, le titre ‘Météo du jour’ et le résumé des températures.”

Lire l’état actuel de vos équipements

Outil readValues

Lit en temps réel la valeur actuelle d’un ou plusieurs capteurs ou équipements : température, état d’une alarme, consommation électrique, position d’un volet, etc.

Exemples de prompts :

  • “Quelle est la température dans le salon en ce moment ?”
  • “La porte d’entrée est-elle fermée ?”
  • “Donne-moi l’état de tous mes volets.”
  • “Quelle est la consommation électrique actuelle de la maison ?”

Consulter l’historique d’une valeur

Outil readHistory

Récupère les valeurs enregistrées par Jeedom pour un capteur ou un équipement sur une période que vous choisissez. L’agent adapte automatiquement la précision selon la durée demandée : valeurs brutes pour les courtes périodes, moyennes horaires ou journalières pour les longues périodes.

Exemples de prompts :

  • “Comment a évolué la température du salon ces 24 dernières heures ?”
  • “Montre-moi la consommation électrique de la semaine dernière, jour par jour.”
  • “À quelle heure la porte de garage a-t-elle été ouverte hier ?”
  • “Trace l’évolution de l’humidité dans la chambre ce mois-ci.”

Obtenir des statistiques sur une valeur

Outil getStats

Calcule des indicateurs statistiques sur un capteur sur une période donnée : valeur minimale, maximale, moyenne, écart-type, tendance. Idéal pour obtenir un résumé chiffré sans avoir à parcourir tous les points de mesure.

Exemples de prompts :

  • “Quelle était la température moyenne dans le salon la semaine dernière ?”
  • “Quelle est la consommation électrique min et max de la journée ?”
  • “Donne-moi un résumé de la température extérieure ce mois-ci.”
  • “Est-ce que la température de la cave a tendance à monter ou baisser en ce moment ?”

Savoir depuis combien de temps un équipement est dans un état

Outil getStateDuration

Indique depuis combien de temps un équipement se trouve dans son état actuel (ou dans un état précis que vous demandez). Utile pour savoir si quelque chose a été oublié allumé, ouvert ou déclenché.

Exemples de prompts :

  • “Depuis combien de temps la lumière du couloir est allumée ?”
  • “La fenêtre du bureau est ouverte depuis quand ?”
  • “Depuis combien de temps le portail est fermé ?”
  • “Est-ce que l’alarme est armée depuis longtemps ?”

Outils — Logs et diagnostics

Ces outils permettent à l’agent de vous aider à diagnostiquer des problèmes sur votre Jeedom en lisant et analysant les fichiers de log.

Consulter les informations sur les logs disponibles

Outil getLogsInfo

Retourne pour chaque log autorisé : sa taille, la date de sa dernière modification, et les droits disponibles (possibilité ou non de le vider ou de le supprimer). L’agent l’utilise automatiquement pour savoir ce qu’il peut faire avant de lire ou gérer un log.

Exemples de prompts :

  • “Quels logs sont disponibles et quelle est leur taille ?”
  • “Quand a été modifié le log du plugin mcpIA pour la dernière fois ?”

Lire les dernières lignes d’un log

Outil readLogs

Lit rapidement la fin d’un ou plusieurs fichiers de log (les N dernières lignes). Utile pour un diagnostic rapide ou pour voir ce qui vient de se passer.

Exemples de prompts :

  • “Montre-moi les 50 dernières lignes du log mcpIA.”
  • “Y a-t-il des erreurs récentes dans le log du plugin TTSCast ?”
  • “Que s’est-il passé récemment dans les logs de Jeedom ?”

Rechercher dans les logs

Outil searchLogs

Effectue une recherche complète dans un ou plusieurs fichiers de log en une seule requête, avec des filtres : par mot-clé (simple ou liste), par niveau de gravité (erreur, avertissement, info…), par plage de dates, ou via une expression régulière. Toutes les recherches s’exécutent en parallèle. Affiche le contexte autour de chaque résultat et reconnaît les messages d’erreur qui s’étendent sur plusieurs lignes (stack traces).

Exemples de prompts :

  • “Y a-t-il des erreurs dans le log mcpIA aujourd’hui ?”
  • “Cherche les mots ‘timeout’ ou ‘refused’ ou ‘unreachable’ dans le log du démon.”
  • “Cherche les lignes qui contiennent ‘error’ mais pas ‘auth’.”
  • “Montre-moi tous les avertissements du log Jeedom de la semaine dernière.”
  • “Y a-t-il eu des erreurs critiques dans les logs entre hier soir et ce matin ?”
  • “Cherche des erreurs dans les logs mcpIA et ttscast en même temps.”

Vider un fichier de log

Outil clearLog

Efface le contenu d’un fichier de log (le fichier est conservé, mais son contenu est supprimé). Ne fonctionne que si cette permission a été activée dans la configuration du profil.

Exemples de prompts :

  • “Vide le log mcpIA.”
  • “Efface le contenu du log du plugin TTSCast.”

Supprimer un fichier de log

Outil removeLog

Supprime définitivement un fichier de log. Ne fonctionne que si cette permission a été activée dans la configuration du profil. À utiliser avec précaution.

Exemples de prompts :

  • “Supprime le fichier de log mcpIA.”

Outils — Scénarios

Ces outils permettent à l’agent d’observer et d’interagir avec les scénarios Jeedom que vous avez explicitement autorisés.

Lister les scénarios disponibles

Outil listScenarios

Retourne la liste des scénarios autorisés avec leur nom, groupe, état actif/inactif et informations contextuelles. L’agent l’utilise pour découvrir les scénarios accessibles avant d’agir.

Exemples de prompts :

  • “Quels scénarios sont disponibles ?”
  • “Liste tous les scénarios que tu peux gérer.”
  • “Y a-t-il des scénarios liés au chauffage ?”

Consulter le détail d’un scénario

Outil getScenario

Retourne le contenu complet d’un scénario : ses blocs SI/ALORS/SINON, ses déclencheurs, ses conditions et la liste des tags (paramètres) qu’il accepte. Utile avant de déclencher un scénario avec des paramètres.

Exemples de prompts :

  • “Montre-moi le contenu du scénario ‘Réveil’.”
  • “Qu’est-ce que fait exactement le scénario de simulation de présence ?”
  • “Quels paramètres accepte le scénario d’alerte ?”

Déclencher un scénario

Outil runScenario

Lance l’exécution d’un scénario. Si le scénario utilise des tags (paramètres), ils peuvent être passés dans la demande.

Exemples de prompts :

  • “Lance le scénario de réveil.”
  • “Démarre le scénario de départ en vacances.”
  • “Déclenche le scénario d’alerte avec le message ‘Porte ouverte’.”

Arrêter un scénario en cours

Outil stopScenario

Arrête un scénario qui est en cours d’exécution.

Exemples de prompts :

  • “Arrête le scénario de simulation de présence.”

Activer / Désactiver un scénario

Outils enableScenario / disableScenario

Active ou désactive un scénario. Un scénario désactivé ne peut pas être déclenché.

Exemples de prompts :

  • “Désactive le scénario de chauffage pour aujourd’hui.”
  • “Réactive le scénario d’alarme.”
  • “Quels scénarios sont actuellement désactivés ?”

Modifier les propriétés d’un scénario

Outil updateScenario

Permet de modifier le nom, le groupe, la description ou l’état actif d’un scénario existant. Si l’option Autoriser la modification des déclencheurs et planification est activée dans la configuration du profil, l’agent peut également modifier le mode d’exécution (provoqué, planifié, mixte), les déclencheurs (commandes, variables…) et l’expression cron.

Exemples de prompts :

  • “Ajoute une description au scénario de simulation de présence.”
  • “Déplace le scénario ‘Réveil’ dans le groupe ‘Matin’.”
  • “Planifie le scénario ‘Arrosage’ pour s’exécuter tous les jours à 7h.”
  • “Rends ce scénario mixte : déclenché par le capteur et programmé à 22h.”

Créer un scénario

Outil createScenario

Crée un nouveau scénario dans Jeedom. Ne fonctionne que si l’option Autoriser la création est activée dans la configuration du profil. Le scénario créé est automatiquement ajouté à la liste des scénarios autorisés. Le mode d’exécution est déduit automatiquement : « planifié » si une expression cron est fournie, « provoqué » si des déclencheurs sont spécifiés, « mixte » si les deux sont présents.

Exemples de prompts :

  • “Crée un scénario appelé ‘Routine du soir’, planifié tous les jours à 21h.”
  • “Crée un scénario déclenché par le capteur de mouvement du couloir.”

Modifier les blocs d’un scénario

Outil setScenarioBlocks

Réécrit la structure des blocs SI/ALORS/SINON d’un scénario existant. L’agent peut d’abord utiliser getScenario pour récupérer la structure actuelle, puis proposer une version modifiée. Ne fonctionne que si les options Autoriser la création et Autoriser la modification des blocs sont toutes deux activées dans la configuration du profil.

⚠️ L’agent doit vous présenter les blocs à créer ou modifier et obtenir votre confirmation avant d’appliquer les changements.

Exemples de prompts :

  • “Ajoute une action ‘Allumer le salon’ dans le bloc ALORS du scénario ‘Arrivée à la maison’.”
  • “Modifie le scénario de réveil pour envoyer une notification à 7h30 au lieu de 7h00.”
  • “Consulte les blocs du scénario de simulation de présence, puis optimise-les.”

Copier un scénario

Outil copyScenario

Crée une copie exacte d’un scénario existant sous un nouveau nom. La copie est structurellement identique à l’original : blocs SI/ALORS/SINON, déclencheurs, expression cron et métadonnées sont tous dupliqués fidèlement via le mécanisme natif de Jeedom. Le scénario copié est automatiquement ajouté à la liste des scénarios autorisés du profil. Ne fonctionne que si l’option Autoriser la création est activée.

Note : par défaut, la copie est créée inactive (isActive=false), quelle que soit l’état du scénario source. Cela évite qu’elle s’exécute en parallèle de l’original avant d’avoir été examinée et modifiée. L’agent peut explicitement demander une copie active en précisant activateImmediately=true.

Exemples de prompts :

  • “Copie le scénario ‘Routine du matin’ et appelle la copie ‘Routine du week-end’.”
  • “Duplique le scénario de simulation de présence pour en faire une version hiver.”
  • “Copie le scénario de réveil en version active directement.”

Outils — Centre de messages et batteries

Ces outils permettent à l’agent de consulter le centre de messages Jeedom et l’état des batteries de vos équipements.

Lire les messages du centre de messages

Outil getMessages

Retourne la liste des messages présents dans le centre de messages Jeedom (alertes, erreurs plugins, notifications système…), avec leur date, type et contenu.

Exemples de prompts :

  • “Y a-t-il des messages dans le centre de messages ?”
  • “Quelles alertes ou erreurs sont en attente dans Jeedom ?”
  • “Montre-moi les dernières notifications système.”

Acquitter des messages

Outil acknowledgeMessages

Acquitte (supprime) un ou plusieurs messages du centre de messages, identifiés par leurs identifiants. Nécessite que l’option Autoriser l’acquittement soit activée dans la configuration du profil — même pour un seul message.

⚠️ L’agent doit vous demander confirmation avant d’acquitter des messages.

Exemples de prompts :

  • “Acquitte le message numéro 42.”
  • “Supprime cette alerte du centre de messages.”
  • “Vide le centre de messages.”
  • “Efface toutes les notifications en attente.”

Consulter l’état des batteries

Outil getBatteryStatus

Retourne l’état des batteries des équipements présents dans la whitelist batteries du profil (configurée dans la section Batteries de l’équipement). Cette liste est indépendante des équipements exposés au LLM — un équipement peut être surveillé pour sa batterie sans être contrôlable par l’agent. Peut être filtré pour n’afficher que les équipements en alerte batterie, ou limité à une liste d’équipements spécifiques.

Exemples de prompts :

  • “Y a-t-il des équipements avec une batterie faible ?”
  • “Donne-moi le niveau de batterie de tous mes équipements.”
  • “Quels capteurs sont en alerte batterie en ce moment ?”
  • “Quelle est la batterie du capteur de porte du garage ?”

Outils — Santé et infrastructure Jeedom

Diagnostiquer l’état de santé de Jeedom

Outil getHealthStatus

Retourne l’état de santé complet de l’infrastructure Jeedom : état du matériel, de la base de données, du réseau, de l’espace disque, de la mémoire, d’Apache, des crons, des scénarios, des versions OS/PHP/Node, du swap et de la charge système. Les éléments en erreur (ko) apparaissent en premier, suivis des avertissements (warning), puis des éléments sains (ok). Lecture seule — aucune permission supplémentaire requise.

Exemples de prompts :

  • “Mon Jeedom est-il en bonne santé ?”
  • “Y a-t-il des problèmes sur mon serveur Jeedom ?”
  • “Vérifie l’état de la base de données, du réseau et de l’espace disque.”
  • “Qu’est-ce qui ne va pas sur mon Jeedom en ce moment ?”
  • “Fais un bilan complet de l’infrastructure avant que j’intervienne.”

Outils — Moteur de tâches Jeedom

Ces outils donnent à l’agent accès au moteur cron interne de Jeedom : il peut inspecter toutes les tâches planifiées (y compris les démons de plugins), diagnostiquer les tâches bloquées ou à expression invalide, et — si la permission est accordée — les contrôler et les modifier.

Inventorier les tâches planifiées

Outil listCrons

Retourne la liste de toutes les tâches enregistrées dans le moteur cron Jeedom. Quatre filtres disponibles : "all" (toutes), "scheduled" (tâches périodiques uniquement, isCronDaemon=false), "cron-daemon" (démons enregistrés dans le moteur cron — boucle de polling avec intervalle sleepTime), "error" (tâches à expression cron invalide OU bloquées depuis plus longtemps que leur timeout configuré). Retourne également isCronDaemon, sleepTime (intervalle de polling pour les cron-démons, null sinon), once et runtime. Lecture libre — aucune permission requise.

Exemples de prompts :

  • “Liste toutes les tâches planifiées Jeedom.”
  • “Y a-t-il des tâches bloquées ou en erreur dans le moteur cron ?”
  • “Quelles tâches sont enregistrées comme démons dans le moteur cron ?”
  • “Y a-t-il des tâches avec un schedule invalide ?”

Consulter le détail d’une tâche

Outil getCrons

Retourne les informations complètes d’une ou plusieurs tâches identifiées par leur ID. Inclut l’état en temps réel (running — vérification du processus, pas seulement le champ d’état), le PID, le timeout, isCronDaemon, sleepTime, once et runtime (durée de la dernière exécution en secondes). Lecture libre — aucune permission requise.

Exemples de prompts :

  • “Donne-moi le détail de la tâche cron avec l’ID 42.”
  • “Quelle est la durée moyenne d’exécution de la tâche de backup ?”

Contrôler une tâche planifiée

Outil controlCron

Permet de démarrer (start), arrêter (stop), activer (enable), désactiver (disable) ou exécuter immédiatement (run) une tâche planifiée. Nécessite que l’option Contrôle des tâches soit activée dans la configuration du profil.

⚠️ L’action run exécute la tâche immédiatement, indépendamment de son planning.

Exemples de prompts :

  • “Lance le backup Jeedom maintenant.”
  • “Désactive la tâche de nettoyage temporaire des logs.”
  • “Démarre la tâche planifiée de vérification du réseau.”

Modifier une tâche planifiée

Outil updateCron

Permet de modifier l’expression cron (planification) et/ou le timeout d’une tâche. La modification du timeout est autorisée sur tout type de tâche y compris les démons. La modification de l’expression est refusée pour les tâches démons (gérée par le Core Jeedom). Toute expression invalide est rejetée avec un message d’erreur explicite — jamais silencieusement acceptée. Nécessite que l’option Contrôle des tâches soit activée dans la configuration du profil.

⚠️ Une modification de planning prend effet immédiatement au prochain cycle du moteur cron.

Exemples de prompts :

  • “Change la tâche de sauvegarde pour qu’elle s’exécute à 3h du matin au lieu de 2h.”
  • “Augmente le timeout de la tâche ‘refresh météo’ à 120 secondes.”
  • “Reprogramme la vérification DNS toutes les 10 minutes.”

Outils — Variables Jeedom

Ces outils permettent à l’agent de lire, créer, modifier et supprimer les variables Jeedom (dataStore). Les variables globales sont partagées entre tous les scénarios ; les variables locales sont privées à un scénario spécifique.

Lister les variables Jeedom

Outil listVariables

Retourne la liste de toutes les variables accessibles, avec pour chacune son nom, sa valeur, son scope (global ou scenario) et les informations du scénario concerné le cas échéant. Trois filtres sont disponibles et peuvent être combinés : par scope, par liste de scénarios (scenarioIds) et par nom (namePattern, sous-chaîne insensible à la casse). Les résultats sont triés alphabétiquement par nom. Lecture libre — aucune permission requise.

Exemples de prompts :

  • “Liste toutes les variables Jeedom.”
  • “Quelles variables globales sont définies dans Jeedom ?”
  • “Montre-moi toutes les variables locales du scénario ‘Réveil’.”
  • “Y a-t-il des variables qui contiennent ‘temp’ dans leur nom ?”

Lire des variables spécifiques

Outil getVariables

Récupère la valeur de une ou plusieurs variables ciblées par leur nom exact (et scope/scenarioId). Chaque entrée de la réponse indique la valeur actuelle ou une erreur si la variable n’existe pas. À utiliser quand les noms sont connus à l’avance — pour parcourir les variables avec des filtres, préférer listVariables.

Exemples de prompts :

  • “Quelle est la valeur de la variable ‘mode_maison’ ?”
  • “Donne-moi la valeur des variables ‘temp_consigne’ et ‘temp_actuelle’.”
  • “Quelle est la valeur de la variable locale ‘compteur’ du scénario d’arrosage ?”

Créer ou modifier des variables

Outil setVariables

Crée ou met à jour une ou plusieurs variables en un seul appel. Si la variable n’existe pas, elle est créée automatiquement. Supporte les variables globales (scope="global") et les variables locales à un scénario (scope="scenario"). Nécessite que l’option Modifier des variables soit activée dans la configuration du profil. Pour les variables locales, le scénario cible doit également figurer dans la whitelist des scénarios du profil.

Exemples de prompts :

  • “Mets la variable ‘mode_maison’ à ‘vacances’.”
  • “Crée une variable globale ‘heure_coucher’ avec la valeur ‘22:30’.”
  • “Mets à jour les variables ‘temp_min’ et ‘temp_max’.”
  • “Modifie la variable locale ‘compteur’ du scénario d’arrosage à 0.”

Supprimer des variables

Outil deleteVariables

Supprime une ou plusieurs variables. Fonctionne en mode dry-run par défaut : sans confirmation explicite, l’outil retourne la liste des variables qui seraient supprimées sans les modifier. Il faut passer confirm=True pour effectuer la suppression réelle. Mêmes prérequis que setVariables (permission allowModifyVariables + whitelist scénarios pour les variables locales).

⚠️ L’agent doit vous présenter la liste des variables à supprimer et obtenir votre confirmation avant de procéder à la suppression effective.

Exemples de prompts :

  • “Supprime la variable globale ‘test’.”
  • “Supprime toutes les variables locales du scénario ‘Démo’.”
  • “Montre-moi ce qui serait supprimé si je supprime ces variables.”

Outils — Sauvegardes Jeedom

Ces outils permettent à l’agent de consulter l’état complet des sauvegardes Jeedom et de déclencher une sauvegarde.

Consulter l’état des sauvegardes

Outil getBackupStatus

Retourne l’état des trois sources de sauvegarde configurées dans Jeedom :

Les sources Market et Samba ne sont interrogées que si elles sont entièrement activées et configurées. Lecture seule — aucune permission requise.

Exemples de prompts :

  • “Quelles sauvegardes Jeedom sont disponibles ?”
  • “Quelle est la dernière sauvegarde effectuée ?”
  • “Combien d’espace disque occupent mes sauvegardes locales ?”
  • “Mes sauvegardes sont-elles bien envoyées sur le cloud Market ?”
  • “Vérifie que la sauvegarde Samba est bien active et à jour.”

Déclencher une sauvegarde

Outil triggerBackup

Lance une sauvegarde complète de Jeedom en arrière-plan (configurations, plugins, scénarios, données). La commande retourne immédiatement — la sauvegarde s’exécute en tâche de fond et prend 30 à 120 secondes selon la taille de l’installation. Jeedom envoie automatiquement la sauvegarde aux destinations activées (Market, Samba) à la fin de la sauvegarde locale. Nécessite que l’option Déclencher une sauvegarde soit activée dans la configuration du profil.

⚠️ L’agent doit vous demander confirmation avant de déclencher une sauvegarde. Vérifiez le résultat avec getBackupStatus quelques minutes après.

Exemples de prompts :

  • “Lance une sauvegarde Jeedom maintenant.”
  • “Fais une sauvegarde avant que j’intervienne sur la configuration.”
  • “Déclenche une sauvegarde complète et dis-moi quand c’est terminé.”

Outils — Centre de Mises à Jour Jeedom

Ces outils permettent à l’agent de consulter les mises à jour disponibles pour les plugins Jeedom, de déclencher une vérification sur le Market et d’appliquer des mises à jour.

Consulter les mises à jour disponibles

Outil listUpdates

Retourne la liste des mises à jour disponibles pour les plugins Jeedom, avec les informations suivantes pour chaque entrée : identifiant (logicalId), nom, type, statut, source, version installée (localVersion), version disponible (remoteVersion), et si la mise à jour est verrouillée (locked).

Le résultat inclut également la date de dernière vérification (lastCheck) et le nombre total de mises à jour disponibles (nbNeedUpdate).

Les paramètres optionnels permettent de filtrer la liste :

Lecture seule — aucune permission requise.

Exemples de prompts :

  • “Quels plugins ont des mises à jour disponibles ?”
  • “Y a-t-il des mises à jour Jeedom en attente ?”
  • “Liste tous les plugins à jour.”
  • “Quels plugins sont verrouillés ?”
  • “Montre-moi les mises à jour disponibles hors plugins verrouillés.”

Vérifier les mises à jour

Outil checkForUpdates

Déclenche une vérification active des mises à jour sur le Market Jeedom. La commande retourne immédiatement — la vérification s’exécute en tâche de fond (15 à 30 secondes selon la connexion). Consultez ensuite listUpdates pour voir le résultat actualisé. Nécessite que l’option Vérifier les mises à jour soit activée dans la configuration du profil.

Exemples de prompts :

  • “Lance une vérification des mises à jour Jeedom.”
  • “Rafraîchis la liste des mises à jour disponibles.”
  • “Y a-t-il de nouvelles mises à jour ? Lance une vérification.”

Appliquer des mises à jour

Outil doUpdates

Lance la mise à jour d’un ou plusieurs plugins en arrière-plan. Passer une liste vide lance la mise à jour de tous les plugins ayant une mise à jour disponible (à l’exception des plugins verrouillés et du Core Jeedom). La commande retourne immédiatement avec la liste des plugins lancés et ceux ignorés (avec la raison).

⚠️ La mise à jour du Core Jeedom n’est jamais autorisée via cet outil. Appliquer une mise à jour redémarre le plugin concerné. L’agent doit vous demander confirmation avant de procéder.

Nécessite que l’option Appliquer les mises à jour soit activée dans la configuration du profil.

Exemples de prompts :

  • “Mets à jour tous les plugins qui ont une mise à jour disponible.”
  • “Mets à jour uniquement le plugin ‘Alarme’.”
  • “Lance les mises à jour en attente, sauf les plugins verrouillés.”

Outils — Plugins & Démons Jeedom

Ces outils permettent à l’agent d’inventorier les plugins installés sur votre Jeedom, de consulter l’état des démons et — si la permission est accordée — de les contrôler et de gérer les dépendances.

Inventorier les plugins

Outil listPlugins

Retourne la liste de tous les plugins installés sur votre Jeedom avec leurs informations complètes : état (actif/inactif), version installée, auteur, licence, catégorie, compatibilité OS (require, requireOsVersion), présence d’un démon (hasDaemon) et de dépendances gérées (hasDependency), liens vers la documentation, le changelog stable et beta. Lecture libre — aucune permission requise.

Paramètre optionnel :

Exemples de prompts :

  • “Liste tous les plugins installés sur mon Jeedom.”
  • “Quels plugins sont actuellement désactivés ?”
  • “Quels plugins ont un démon externe ?”
  • “Quelle est la version du plugin TTSCast ?”

Consulter l’état des démons

Outil listDaemons

Retourne la liste de tous les plugins ayant leur propre processus démon externe (mcpIA, TTSCast, DiscordLink…) avec leur état en temps réel : state ("ok" / "nok"), launchable (le démon peut-il démarrer — dépendances OK ?), auto (gestion automatique activée ou non) et lastLaunch (date du dernier démarrage). Lecture libre — aucune permission requise.

Note : listDaemons est distinct de listCrons(type="cron-daemon") — les démons modernes (Python, Node.js) ne s’enregistrent pas dans le moteur cron.

Exemples de prompts :

  • “Quels démons de plugins sont en cours d’exécution ?”
  • “Le démon TTSCast est-il démarré ?”
  • “Y a-t-il des démons arrêtés qui devraient être actifs ?”

Contrôler les démons et les dépendances

Outil managePlugins

Gère les démons et les dépendances d’un ou plusieurs plugins en un seul appel. Chaque opération est indépendante — une erreur sur un plugin n’annule pas les autres.

Actions disponibles :

Les actions de contrôle nécessitent l’option Contrôle des plugins & démons dans la configuration du profil. L’agent ne peut pas contrôler le plugin mcpIA lui-même via cet outil — seule l’interface d’administration Jeedom le permet.

⚠️ L’agent doit toujours vous demander confirmation avant d’effectuer une action de contrôle (démarrage, arrêt, redémarrage de démon ou installation de dépendances).

Exemples de prompts :

  • “Redémarre le démon du plugin TTSCast.”
  • “Installe les dépendances du plugin DiscordLink.”
  • “Active la gestion automatique du démon Alarme.”
  • “Quel est l’état des dépendances du plugin SSH-Manager ?”
  • “Y a-t-il des plugins dont les dépendances ne sont pas installées ?”

Outils — Caméras

Ces outils permettent à l’agent de voir ce que voient vos caméras Jeedom et d’analyser visuellement la scène : détecter une anomalie, confirmer un état, répondre à une question sur l’environnement capturé.

:information_source: NOTE

L’agent reçoit l’image et l’analyse visuellement — il peut décrire la scène, détecter un objet, signaler une anomalie ou répondre à vos questions. L’image n’apparaît pas dans le chat — le protocole MCP la transmet directement à l’agent pour analyse, sans la retourner dans l’interface utilisateur.

Prendre et analyser un ou plusieurs snapshots caméra

Outil getCameraSnapshots

Récupère une ou plusieurs images depuis des caméras Jeedom et les transmet à l’agent pour analyse visuelle. L’agent peut décrire la scène, identifier des objets, détecter une anomalie ou répondre à n’importe quelle question sur ce qu’il observe. Plusieurs caméras peuvent être interrogées en une seule requête.

Compatible avec :

Paramètre :

Formats acceptés : JPEG, PNG, WebP. Les flux vidéo continus (RTSP, HLS .m3u8) sont automatiquement détectés et refusés — ils ne peuvent pas être capturés en tant qu’image fixe.

Exemples de prompts :

  • “Montre-moi ce que voit la caméra du jardin.”
  • “Y a-t-il quelqu’un dans l’entrée en ce moment ?”
  • “La voiture est-elle garée dans l’allée ?”
  • “Montre-moi toutes les caméras extérieures.”
  • “Regarde la caméra du salon et décris ce que tu vois.”
  • “Y a-t-il une anomalie visible sur la caméra du garage ?”
  • “La porte du jardin est-elle ouverte ? Vérifie avec la caméra.”
  • “Analyse le dernier snapshot détecté par Frigate sur la caméra de l’entrée.”

Envoyer un snapshot caméra vers un messenger

Outil sendCameraSnapshots

Envoie une ou plusieurs photos prises par des caméras Jeedom vers une commande de messagerie (Discord, Telegram, notification push…). Le plugin caméra est détecté automatiquement — plugin Caméra natif ou Frigate. N caméras = N messages indépendants.

Paramètres :

Exemples de prompts :

  • “Envoie-moi une photo de la caméra du jardin sur Discord.”
  • “Envoie un snapshot de toutes les caméras extérieures sur Telegram.”
  • “Prends 3 photos de la caméra de l’entrée et envoie-les sur Discord avec le message ‘Détection mouvement’.”
  • “Envoie le dernier snapshot Frigate de la caméra garage sur Discord.”

Outils — Designs Jeedom

Ces outils permettent à l’agent d’interagir avec les Designs Jeedom — les tableaux de bord visuels que vous créez dans l’interface Web de Jeedom (menu Design). L’agent peut lister les Designs existants, inspecter leur contenu, créer de nouveaux Designs et y placer des blocs (textes HTML, équipements, commandes, scénarios, graphiques, images, zones…). Il peut également modifier les propriétés d’un Design existant ou supprimer entièrement un Design.

:information_source: NOTE

L’agent calcule lui-même les positions des blocs en se basant sur les dimensions du canvas. Le résultat n’est pas forcément pixel-perfect — vous pouvez toujours ajuster manuellement à la souris dans l’interface Jeedom après génération.

Ces outils nécessitent d’activer les permissions correspondantes dans la configuration du profil :

Lister les Designs disponibles

Outil listDesigns

Retourne la liste de tous les Designs de votre installation : nom, nombre de blocs, dimensions du canvas, présence d’une image de fond. Point d’entrée naturel avant toute autre opération sur les Designs.

Exemples de prompts :

  • “Énumère les Designs disponibles dans mon Jeedom.”
  • “Quels tableaux de bord visuels existent sur mon installation ?”

Consulter le contenu d’un Design

Outil getDesigns

Récupère le contenu complet d’un ou plusieurs Designs en un seul appel : liste de tous les blocs avec leurs identifiants (planId), type, élément lié, position, dimensions, styles CSS et configuration. L’agent appelle systématiquement cet outil avant de modifier ou supprimer des blocs, car il a besoin des planId.

Exemples de prompts :

  • “Montre-moi le contenu du Design ‘Salon’.”
  • “Quels blocs sont présents dans mon Design principal ?”

Récupérer l’image de fond d’un Design

Outil getDesignBackgrounds

Récupère et transmet à l’agent les images de fond d’un ou plusieurs Designs (photo de pièce, plan d’appartement…) sous forme d’image compressée. L’agent peut ainsi analyser visuellement le layout avant de placer des blocs.

Exemples de prompts :

  • “Regarde l’image de fond de mon Design et propose où placer les équipements du salon.”

Créer un nouveau Design

Outil createDesign

Crée un nouveau Design vide avec le nom et les dimensions que vous souhaitez, en choisissant la couleur ou la transparence du canvas. Retourne l’identifiant du Design créé, à utiliser ensuite avec setDesignBlocks.

Nécessite la permission Modification des Designs.

Exemples de prompts :

  • “Crée un Design appelé ‘Tableau de bord principal’, 1200×800px, fond sombre.”
  • “Génère un Design avec toutes les commandes du salon.”

Modifier les propriétés d’un ou plusieurs Designs

Outil updateDesigns

Modifie les propriétés d’un ou plusieurs Designs existants en un seul appel : nom, dimensions du canvas, couleur ou transparence du fond, icône, ordre d’affichage. Seuls les champs fournis sont modifiés — les autres sont conservés.

Nécessite la permission Modification des Designs.

Exemples de prompts :

  • “Renomme le Design ‘Salon’ en ‘Séjour’.”
  • “Élargis le canvas du Design ‘Tableau de bord’ à 1600px de large.”
  • “Mets un fond bleu foncé sur le Design ‘Nuit’.”

Ajouter ou modifier des blocs dans un Design

Outil setDesignBlocks

Ajoute ou met à jour un ou plusieurs blocs dans un Design en un seul appel. Chaque bloc peut être de type texte HTML libre, équipement, commande, scénario, graphique, image, zone cliquable, lien vers une vue ou un autre Design. Plusieurs Designs peuvent être alimentés en une seule requête.

Nécessite la permission Modification des Designs.

Exemples de prompts :

  • “Ajoute un bloc texte avec la température du salon sur le Design ‘Principal’.”
  • “Place les commandes de toutes les lumières du salon sur le Design ‘Tableau de bord’, en 3 colonnes.”
  • “Ajoute un graphique de la consommation électrique sur le Design.”
  • “Génère un Design complet pour le salon avec les lumières, la température et les volets.”

Supprimer des blocs d’un Design

Outil removeDesignBlocks

Supprime un ou plusieurs blocs d’un Design. Nécessite de connaître les planId — appeler getDesigns([designId]) préalablement pour les récupérer.

⚠️ Attention : la suppression d’un bloc de type image supprime également le fichier image sur le serveur.

Nécessite la permission Modification des Designs.

Exemples de prompts :

  • “Supprime le bloc texte en haut à gauche du Design ‘Salon’.”
  • “Vide le Design ‘Test’ de tous ses blocs.”

Supprimer un Design entier

Outil deleteDesigns

Supprime un ou plusieurs Designs avec tous leurs blocs. L’agent effectue toujours un dry-run en premier : il vous présente la liste des Designs ciblés et le nombre de blocs qui seront supprimés, puis attend votre confirmation avant d’exécuter. Les fichiers image physiques associés aux blocs image sont également supprimés.

⚠️ Opération irréversible. Nécessite la permission Suppression des Designs.

Exemples de prompts :

  • “Supprime le Design ‘Test’.”
  • “Supprime tous les Designs dont le nom commence par ‘Draft’.”

Gestion des équipements

Statut temps réel d’un équipement

Outil getDevicesStatus

Retourne l’état temps réel d’un ou plusieurs équipements Jeedom : activé/désactivé, visible sur le dashboard, niveau de batterie, niveau d’alerte actif (warning / danger / timeout), plugin propriétaire, pièce et catégorie. Aucune permission particulière n’est requise.

Exemples de prompts :

  • “Quel est l’état de ma prise connectée du salon ?”
  • “Y a-t-il des équipements désactivés en ce moment ?”
  • “Donne-moi le niveau de batterie de mon détecteur de fumée.”

Résumé agrégé par pièce

Outil getRoomsSummary

Retourne les résumés agrégés calculés par Jeedom pour chaque pièce : nombre de lumières allumées, température moyenne, humidité, motions actives, etc. Les clés disponibles dépendent de la configuration des résumés Jeedom. Sans paramètre, retourne toutes les pièces. Aucune permission particulière n’est requise.

Exemples de prompts :

  • “Quelle est la température dans chaque pièce ?”
  • “Combien de lumières sont allumées dans la maison en ce moment ?”
  • “Résume-moi l’état du salon et de la cuisine.”

Activer ou désactiver des équipements

Outil setDevicesEnabled

Active ou désactive un ou plusieurs équipements Jeedom en lot. Un équipement désactivé ne répond plus à ses automatisations et commandes.

⚠️ Désactiver un équipement l’arrête complètement. L’agent doit toujours vous demander confirmation avant de désactiver un équipement.

Nécessite que l’option Gérer les équipements soit activée dans la configuration du profil.

Exemples de prompts :

  • “Désactive la prise du salon.”
  • “Réactive tous les équipements que tu as désactivés.”

Afficher ou masquer des équipements sur le dashboard

Outil setDevicesVisible

Modifie la visibilité sur le dashboard d’un ou plusieurs équipements en lot. Un équipement masqué continue de fonctionner normalement — seul son affichage sur le dashboard est affecté.

Nécessite que l’option Gérer les équipements soit activée dans la configuration du profil.

Exemples de prompts :

  • “Cache le thermomètre du garage sur le dashboard.”
  • “Affiche tous les équipements du salon que j’ai masqués.”

Déplacer des équipements dans une autre pièce

Outil moveDevicesToRoom

Déplace un ou plusieurs équipements vers une autre pièce en lot. En cas d’erreur sur un équipement (pièce introuvable par exemple), les autres déplacements de l’appel sont tout de même exécutés.

⚠️ L’agent affiche la liste des déplacements prévus et demande votre confirmation avant d’exécuter l’opération.

Nécessite que l’option Gérer les équipements soit activée dans la configuration du profil.

Exemples de prompts :

  • “Déplace le détecteur de mouvement de l’entrée vers le couloir.”
  • “Tous les équipements Philips Hue du salon — déplace-les dans la pièce ‘Séjour’.”

Mettre à jour les descriptions sémantiques

Outil updateDevicesDescription

Met à jour la description sémantique d’un ou plusieurs équipements de la whitelist en lot. Ces descriptions sont utilisées par searchDevices pour les recherches contextuelles et apparaissent dans la ressource jeedom://home/devices.

L’usage typique est de demander à l’agent de générer automatiquement les descriptions de tous les équipements d’une pièce ou d’un groupe, puis de les enregistrer en une seule opération.

Nécessite que l’option Modifier les descriptions soit activée dans la configuration du profil.

Exemples de prompts :

  • “Génère une description courte pour chaque équipement du salon et enregistre-les.”
  • “Mets à jour les descriptions de tous mes équipements Netatmo.”
  • “Décris le détecteur de fumée du couloir à partir de ses commandes.”

Prompts MCP — Tableaux de bord prêts à l’emploi

Les prompts MCP sont des modèles de conversation prédéfinis qui permettent d’obtenir en une seule demande un rapport complet, sans avoir à rédiger un prompt détaillé.

:warning: NOTE — Support client variable

Le support des prompts MCP dans les interfaces graphiques est encore variable selon les clients. Ils sont exposés par le démon et vérifiables dans MCP Inspector (onglet Prompts). Si votre client ne les expose pas, utilisez directement les exemples de prompts textuels ci-dessous — le résultat est identique.

Page Santé

Prompt pageSante

Tableau de bord santé complet de votre installation, équivalent à la page Santé native de Jeedom. Ce prompt collecte toutes les données en parallèle et produit un rapport structuré en quatre sections :

Section Contenu
🖥️ Système État de l’infrastructure Jeedom (matériel, base de données, réseau, espace disque, mémoire, Apache, cron…) + état en temps réel de tous les démons de plugins
🔋 Batteries Bilan des batteries des équipements de votre whitelist, groupés par niveau : 🔴 Critique, 🟡 Attention, ✅ OK
📬 Messages Alertes, erreurs plugins et notifications en attente dans le centre de messages Jeedom
📋 Logs — 24 h Anomalies (WARNING / ERROR) détectées dans vos logs autorisés sur les dernières 24 heures, avec mention du fuseau horaire du serveur

Comment l’utiliser : Si votre client MCP expose un onglet ou menu Prompts, sélectionnez ` pageSante ` directement. Sinon, utilisez l’un des exemples de prompts ci-dessous.

Exemples de prompts équivalents :

  • “Fais une page santé complète de mon Jeedom.”
  • “Donne-moi un bilan complet de l’état de mon installation.”
  • “Y a-t-il des problèmes sur mon système Jeedom ? Vérifie les batteries, les messages et les logs.”

Mises à jour du plugin

Les profils mcpIA (tokens, équipements autorisés, logs autorisés) sont stockés dans la base de données Jeedom — ils sont intégralement conservés après une mise à jour du plugin. Aucune reconfiguration n’est nécessaire.

Lors d’une mise à jour, le démon est automatiquement redémarré par Jeedom. Si ce n’est pas le cas, vous pouvez le relancer manuellement depuis la page de configuration du plugin, section Démon.

FAQ

Aucun outil visible / “Serveur MCP non disponible”

  1. Vérifier que le démon mcpIA est démarré dans Jeedom (page équipement → statut vert)
  2. Vérifier que le fichier de configuration JSON est valide (pas de virgule en trop, guillemets corrects)
  3. Relancer complètement le client (pas seulement la fenêtre — sur Windows, vérifier la barre des tâches également)
  4. Tester l’URL depuis un navigateur : https://<url-de-votre-jeedom>/mcp (ou http:// si accès local par IP) doit retourner 401 Unauthorized — cela confirme qu’Apache et le démon répondent correctement

mcp-remote refuse la connexion sur URL http://

Erreur “401 Unauthorized”

Erreur “503 Service Unavailable”

“Aucune commande autorisée” / arbre vide

Le token ne fonctionne pas après un renouvellement

Mon token a été compromis ou partagé par erreur

Depuis la fiche d’équipement dans Jeedom, cliquez sur le bouton “Renouveler” à côté du token. Un nouveau token est généré immédiatement — l’ancien ne fonctionne plus. Mettez ensuite à jour le token dans le fichier de configuration de votre client et relancez-le.

Message ASGI callable returned without completing response dans les logs

Ce message apparaît dans les logs lorsque le démon mcpIA a été redémarré alors qu’un client (Claude Desktop, Cursor…) était connecté en arrière-plan. La connexion en cours a été interrompue brutalement — c’est un comportement normal, aucune action n’est requise. Le client se reconnecte automatiquement à l’usage suivant.

La page d’autorisation OAuth affiche “redirect_uri non autorisée”

Ce message indique que le client MCP qui tente de se connecter utilise une redirect_uri différente de celle enregistrée lors de l’enregistrement automatique. Causes possibles :

Solution : l’enregistrement se fait automatiquement à la prochaine tentative de connexion du client MCP — aucune action manuelle n’est nécessaire. Si le problème persiste, vérifiez que l’URL configurée dans votre client MCP correspond à celle affichée dans la section Serveur MCP de la fiche équipement.

Le flux OAuth échoue avec “access_denied”

Un client OAuth est toujours connecté après révocation

La révocation invalide le token côté serveur immédiatement. Si le client semble toujours fonctionner, c’est qu’il utilisait un access token encore valide en cache. Les access tokens expirent automatiquement après 1 heure — passé ce délai, le client sera refusé et devra renouveler via son refresh token (qui est lui aussi révoqué). En pratique, la déconnexion effective intervient dans l’heure suivant la révocation.

Je développe un plugin Jeedom — comment exposer des champs supplémentaires à l’agent IA ?

Par défaut, mcpIA reconstruit l’arbre des équipements depuis le Core Jeedom et expose les commandes de type action avec leur nom, type et sous-type. Pour les commandes de type message (ex : envoyer une notification Discord, un email, un SMS…), le sous-type impose les champs title et message — mais un plugin peut avoir des dizaines de champs supplémentaires (description, couleur, pièces jointes, boutons rapides…) qu’un LLM ne peut pas découvrir seul.

Le mécanisme mcpMetadata() permet de déclarer ces champs directement dans votre plugin PHP, sans modifier mcpIA.

Implémentation :

Ajoutez une méthode statique mcpMetadata() dans la classe principale de votre plugin (celle qui étend eqLogic). La clé de chaque entrée est le logicalId de la commande concernée. Chaque entrée déclare :

public static function mcpMetadata(): array {
    return [
        'sendEmbed' => [
            'hint'    => 'Envoie un embed Discord riche avec titre, description, couleur et champs optionnels.',
            'options' => [
                'title'       => ['required' => true,  'type' => 'string',  'hint' => 'Titre principal de l\'embed'],
                'description' => ['required' => false, 'type' => 'string',  'hint' => 'Corps du message (markdown supporté)'],
                'color'       => ['required' => false, 'type' => 'string',  'hint' => 'Couleur de la barre latérale',  'example' => '#3498db'],
                'footer'      => ['required' => false, 'type' => 'string',  'hint' => 'Texte en pied d\'embed'],
                'url'         => ['required' => false, 'type' => 'string',  'hint' => 'URL cliquable sur le titre'],
            ],
        ],
    ];
}

Règles à respecter :

Exemple de lecture côté plugin :

public function execCmd($options = []) {
    $title       = $options['title']       ?? '';
    $description = $options['description'] ?? $options['message'] ?? ''; // fallback sur message
    $color       = $options['color']       ?? '#000000';
    // ...
}

Plugin de référence : plugin-discordlink — la méthode mcpMetadata() dans discordlink.class.php expose les commandes sendEmbed et sendFile avec l’ensemble de leurs champs.

Note : mcpIA détecte automatiquement mcpMetadata() lors de la reconstruction de l’arbre (à la sauvegarde de l’équipement ou au démarrage du démon). Aucune configuration supplémentaire n’est requise dans mcpIA.

Idées de prompts

Vous venez de connecter votre agent à Jeedom et vous ne savez pas par où commencer ? Voici quelques exemples pour explorer ce que vous pouvez faire.

Découverte et état général

Bilan de la nuit / de la journée

Températures et confort

Consommation et énergie

Sécurité et surveillance

Diagnostics et logs

Santé et infrastructure

Actions

Scénarios et automatisations

Messages et batteries

Moteur de tâches

Variables Jeedom

Sauvegardes

Mises à jour Jeedom

Caméras et surveillance visuelle

:information_source: NOTE

L’agent analyse l’image directement — il décrit la scène, détecte des objets ou des anomalies et répond à vos questions. L’image n’apparaît pas dans le chat : elle est transmise à l’agent en coulisses via le protocole MCP.

Gestion des équipements

Prompts intégrés

Ces prompts sont exposés par le démon mcpIA et accessibles dans les clients MCP qui supportent l’onglet Prompts (MCP Inspector, n8n, Continue.dev…).

Prompt Rôle
pageSante Rapport santé complet : état système et démons, batteries, messages en attente, anomalies dans les logs des 24 dernières heures
Nous utilisons des cookies pour vous garantir la meilleure expérience sur notre site web. Si vous continuez à utiliser ce site, nous supposerons que vous en êtes satisfait.