mcp-server-uyuni

Serveur de protocole de contexte de modèle pour l'API du serveur Uyuni.

Avis de non-responsabilité

Il s'agit d'un projet open-source fourni "TEL QUEL" sans aucune garantie, expresse ou implicite. Vous l'utilisez à vos risques et périls. Pour plus de détails, veuillez vous référer à la section Licence.

Outils

• get_list_of_active_systems
• get_cpu__d'un_système
• get_all_systems_cpu_info
• vérifier_les_mises_à_jour_du_système
• vérifier_tous_les_systèmes_pour_les_mises_à_jour
• schedule_apply_pending_updates_to_system
• schedule_apply_specific_update
• ajouter_un_système
• supprimer_système
• get_systems_needing_security_update_for_cve
• obtenir_les_systèmes_nécessitant_un_redémarrage
• programmer le redémarrage du système
• annuler l'action
• list_all_scheduled_actions
• liste des clés d'activation

Utilisation

Il y a deux façons principales d'exécuter le mcp-server-uyuni: en utilisant le conteneur Docker préconstruit ou en l'exécutant localement avec uv. Les deux méthodes nécessitent un fichier de configuration.

Fichier de configuration

Avant de lancer le serveur, vous devez créer un fichier de configuration. Vous pouvez le placer n'importe où, mais vous devez lui fournir le chemin correct lors de l'exécution du serveur.

UYUNI_SERVER=192.168.1.124:8443 UYUNI_USER=admin UYUNI_PASS=admin # Optionnel : Mettez 'false' pour désactiver la vérification du certificat SSL. La valeur par défaut est 'true' # UYUNI_SSL_VERIFY=false # Facultatif : La valeur "true" permet d'activer les outils qui effectuent des actions d'écriture (par exemple, les requêtes POST). La valeur par défaut est 'false' # UYUNI_MCP_WRITE_TOOLS_ENABLED=false # Facultatif : Définit le protocole de transport. Peut être 'stdio' (par défaut) ou 'http'. # UYUNI_MCP_TRANSPORT=stdio > [!WARNING] > **Note de sécurité sur le transport HTTP:** Lorsque `UYUNI_MCP_TRANSPORT` est défini sur `http`, le serveur s'exécute sans authentification. Cela signifie que n'importe quel client ayant accès au réseau peut exécuter des commandes. N'utilisez ce mode que dans un environnement réseau isolé et de confiance. Pour plus de détails, voir la Politique de Sécurité > [!WARNING] > **Note de sécurité sur les outils d'écriture:** L'activation de `UYUNI_MCP_WRITE_TOOLS_ENABLED` permet l'exécution d'actions de changement d'état et d'actions potentiellement destructrices (par exemple, supprimer des systèmes, appliquer des mises à jour). Lorsqu'il est combiné avec `UYUNI_MCP_TRANSPORT=http`, ce risque est amplifié, car n'importe quel client ayant accès au réseau peut effectuer ces actions. N'activez les outils d'écriture que dans un environnement de confiance. # Facultatif : Définir le chemin d'accès au fichier journal du serveur. Par défaut, il est journalisé sur la console. # UYUNI_MCP_LOG_FILE_PATH=/var/log/mcp-server-uyuni.log UYUNI_SSH_PRIV_KEY="-----BEGIN OPENSSH PRIVATE KEY-----\n..." UYUNI_SSH_PRIV_KEY_PASS=""

Remplacez les valeurs par les détails de votre serveur Uyuni. Ce fichier contient des informations sensibles et ne doit pas être soumis au contrôle de version.

[Formatage de la clé privée SSH

La variable UYUNI_SSH_PRIV_KEY, utilisée par l'outil add_system, requiert l'intégralité de la clé privée sous la forme d'une chaîne d'une seule ligne. Les nouvelles lignes du fichier de clé original doivent être remplacées par la séquence littérale \n.

Vous pouvez générer le format correct à partir de votre fichier de clés (par exemple, ~/.ssh/id_rsa) à l'aide de la commande suivante. Vous pouvez ensuite copier la sortie dans votre fichier de configuration ou votre variable d'environnement.

awk 'NF {printf "%s\n", $0}' ~/.ssh/id_rsa

Pour la définir en tant que variable d'environnement directement dans votre shell, exécutez :

export UYUNI_SSH_PRIV_KEY=$(awk 'NF {printf "%s\n", $0}' ~/.ssh/id_rsa)

Vous pouvez également définir des variables d'environnement au lieu d'utiliser un fichier.

Débogage avec mcp inspect

Vous pouvez exécuter (option docker)

npx @modelcontextprotocol/inspector docker run -i --rm --env-file /path/to/your/config ghcr.io/uyuni-project/mcp-server-uyuni:latest

ou vous pouvez exécuter (option uv)

npx @modelcontextprotocol/inspector uv run --env-file=.venv/config --directory . mcp-server-uyuni

Utilisation avec Open WebUI

Open WebUI est une plateforme d'IA auto-hébergée extensible, riche en fonctionnalités et conviviale, conçue pour fonctionner entièrement hors ligne. Elle supporte différents runners LLM comme Ollama et des API compatibles avec OpenAI, avec un moteur d'inférence intégré pour RAG, ce qui en fait une solution puissante de déploiement de l'IA. Pour en savoir plus, consultez le site https://docs.openwebui.com/

[NOTE] Les instructions suivantes décrivent comment configurer Open WebUI et le proxy MCP à des fins de développement local et de test. Pour les déploiements de production, veuillez vous référer à la documentation officielle d'Open WebUI pour les procédures d'installation recommandées.

Configuration d'Open WebUI

Vous devez installer uv. Voir https://docs.astral.sh/uv

Démarrer v0.6.10 (pour le support MCP, nous avons besoin d'une version >= 0.6.7)

 uv tool run open-webui@0.6.10 serve

Configurez l'URL de l'API OpenAI en suivant ces instructions :

https://docs.openwebui.com/getting-started/quick-start/starting-with-openai

Pour gemini, utilisez l'URL https://generativelanguage.googleapis.com/v1beta/openai et obtenez l'API token depuis Google AI Studio https://aistudio.google.com/

Configuration du support Open WebUI MCP

Tout d'abord, assurez-vous que votre fichier de configuration est prêt comme décrit dans la section Utilisation.

Ensuite, vous avez besoin d'un config.json pour le serveur proxy MCP vers OpenAPI.

Option 1 : Exécution avec Docker (Recommandé)

Il s'agit de la méthode de déploiement la plus simple. Des images de conteneurs préconstruites sont disponibles sur le GitHub Container Registry.

Remplacez /path/to/your/config par le chemin absolu vers votre fichier de configuration. Remplacez VERSION par la balise de version souhaitée (par exemple, v0.2.1) ou utilisez latest pour la version la plus récente de la branche principale.

{ "mcpServers" : { "mcp-server-uyuni" : { "command" : "docker", "args" : [ "run", "-i", "--rm", "--env-file", "/path/to/your/config", "ghcr.io/uyuni-project/mcp-server-uyuni:VERSION" ] } } }

Vous pouvez également utiliser des variables d'environnement au lieu d'un fichier.

{ "mcpServers" : { "mcp-server-uyuni" : { "command" : "docker", "args" : [ "run", "-i", "--rm", "-e", "UYUNI_SERVER=192.168.1.124:8443", "-e", "UYUNI_USER=admin", "-e", "UYUNI_PASS=admin", "ghcr.io/uyuni-project/mcp-server-uyuni:VERSION" ] } } }

Option 2 : Exécution locale avec uv

Cette méthode est idéale pour le développement.

1. Installer uv: Voir https://docs.astral.sh/uv
2. Installer les dépendances :

   uv sync

3. Remplacez /path/to/your/config par le chemin absolu de votre fichier de configuration.

{ "mcpServers" : { "mcp-server-uyuni" : { "command" : "uv", "args" : [ "run", "--env-file", "/path/to/your/config", "--directory", ".", "mcp-server-uyuni" ] } } }

Démarrer le serveur proxy MCP vers OpenAPI

Vous pouvez ensuite démarrer le serveur mandataire Model Context Protocol to Open API :

uvx mcpo --port 9000 --config ./config.json

Ajouter l'outil

Vous pouvez ensuite ajouter l'outil à l'Open Web UI. Voir https://docs.openwebui.com/openapi-servers/open-webui#step-2-connect-tool-server-in-open-webui.

Notez que l'url doit être http://localhost/mcp-server-uyuni comme expliqué dans https://docs.openwebui.com/openapi-servers/open-webui#-optional-using-a-config-file-with-mcpo

Test des capacités avancées (Elicitation)

[Le protocole de contexte de modèle (MCP) comprend des fonctionnalités avancées telles que l'élicitation, qui permet aux outils de demander de manière interactive à l'utilisateur des informations manquantes ou une confirmation.

À l'heure où nous écrivons ces lignes, tous les clients MCP ne prennent pas en charge cette fonctionnalité. Par exemple, Open WebUI n'implémente pas actuellement l'élicitation.

Pour tester les outils qui exploitent l'élicitation (comme l'outil add_system lorsqu'une clé d'activation est manquante), vous avez besoin d'un client compatible. L'extension MCP officielle pour Visual Studio Code est un client de référence qui prend entièrement en charge l'élicitation et qui est recommandé pour développer et tester ces fonctionnalités.

Développement local

Pour construire l'image Docker localement à des fins de développement ou de test :

docker build -t mcp-server-uyuni

Ensuite, vous pouvez utiliser docker run -i --rm --env-file .venv/config mcp-server-uyuni à n'importe quelle configuration du client mcp expliquée ci-dessus.

Processus de publication

Pour créer une nouvelle version de mcp-server-uyuni, suivez les étapes suivantes.

1. ** Créer une branche de version:** git fetch upstream && git checkout upstream/main -b release-x.y.z. En supposant que upstream est l'alias distant pour le git upstream
2. Mettre à jour la documentation (README.md)
   • S'assurer que la liste des outils disponibles dans la section "## Tools" est à jour et reflète tous les outils implémentés dans srv/mcp-server-uyuni/server.py.
   • Passez en revue et mettez à jour toutes les captures d'écran dans le répertoire docs/ et leurs références dans ce README.md pour refléter la dernière interface utilisateur ou fonctionnalité, si nécessaire.
   • Vérifiez que toutes les instructions d'utilisation et les exemples sont toujours exacts.
3. Mettre à jour les cas de test manuels (TEST_CASES.md)
   • Se référer à la section "How to Update for a New Tag/Release" dans TEST_CASES.md.
   • Ajouter une nouvelle colonne de statut pour la version à venir (par exemple, Status (vX.Y.Z)).
   • Exécuter tous les cas de test manuels pertinents par rapport au code à publier.
   • Enregistrez l'état Pass, Fail, Blocked ou N/A pour chaque cas de test dans la nouvelle colonne de la version.
4. Valider les modifications : Valider toutes les mises à jour de README.md, TEST_CASES.md, et tout autre fichier modifié.
5. Mettre à jour la version dans pyproject.toml : Utiliser le versionnement sémantique pour définir la nouvelle version.
6. Mettre à jour uv.lock : Exécuter uv lock pour mettre à jour le fichier uv.lock avec la version définie dans pyproject.toml
7. Mise à jour de CHANGELOG.md
   • Générer le changelog en utilisant conventional-changelog-cli. Si vous ne l'avez pas installé globalement, vous pouvez utiliser npx.
   • La commande pour générer le journal des modifications en utilisant le preset conventionalcommits et l'afficher dans CHANGELOG.md (en ajoutant les nouveaux changements) est :

     npx conventional-changelog-cli -p conventionalcommits -i CHANGELOG.md -s

   • Examinez le fichier CHANGELOG.md généré pour en vérifier l'exactitude et le formatage.
   • Livrer le fichier CHANGELOG.md mis à jour.
8. Pousser la branche et créer une nouvelle Pull Request : git push origin release-x.y.z. En supposant que origin est l'alias distant de votre fourche git.
9. Créer une balise Git : Créez une nouvelle balise Git pour la version (par exemple, git tag vX.Y.Z). Suivez les règles de versionnement sémantique.
10. Transférer les modifications et les balises : Pousser vos modifications (y compris la mise à jour du journal des modifications) et la nouvelle balise vers le dépôt (par exemple, git push && git push --tags).
11. Automatisation de la construction et du transfert : Pousser l'étiquette vers GitHub déclenchera automatiquement l'action GitHub "Docker Publish". Cette action construit l'image Docker et la pousse vers le GitHub Container Registry(ghcr.io) avec des tags pour la version spécifique (par exemple, v0.3.0) et major.minor (par exemple, v0.3). Pousser vers main mettra à jour la dernière balise.
12. Tester le conteneur : Tirer l'image nouvellement publiée de ghcr.io et exécuter les tests dans TEST_CASES.md contre elle.docker run -i --rm --env-file .venv/config ghcr.io/uyuni-project/mcp-server-uyuni:VERSION (remplacer VERSION par la nouvelle balise).

Commentaires

Nous aimerions que vous nous fassiez part de vos commentaires ! Si vous souhaitez discuter ou partager une idée, n'hésitez pas à le faire à l'adresse https://github.com/uyuni-project/uyuni/discussions/10562

Si vous rencontrez un bogue, ayez la gentillesse d'ouvrir un nouveau rapport de bogue à l'adresse https://github.com/uyuni-project/mcp-server-uyuni/issues/new?type=bug

Merci d'avance de la part de l'équipe uyuni !

Licence

Ce projet est soumis à la licence Apache, version 2.0. Voir le fichier LICENSE pour plus de détails.