Serveur MCP ArgoCD

Un serveur MCP (Model Context Protocol) qui s'intègre à l'API ArgoCD, permettant aux assistants IA et aux grands modèles de langage de gérer les applications et les ressources ArgoCD par le biais d'interactions en langage naturel.

Caractéristiques

• Authentification et gestion de session
  • Récupération d'informations sur l'utilisateur à partir de l'API ArgoCD
  • Authentification par jeton avec ArgoCD
  • Accès aux paramètres et à la configuration du serveur
  • Récupération d'informations sur les plugins
  • Récupération d'informations sur les versions
• Gestion des applications
  • Liste et filtre des applications par projet, nom, espace de noms
  • Obtenir des informations détaillées sur les applications
  • Créer, mettre à jour et supprimer des applications
  • Synchroniser les applications avec des options configurables
• Client API robuste
  • Normalisation des URL et gestion intelligente des points d'extrémité
  • Gestion complète des erreurs et messages d'erreur détaillés
  • Délais configurables et vérification SSL
  • Protection et masquage de la sécurité des jetons
• Expérience du développeur
  • Vérification statique complète des types avec mypy
  • Documentation détaillée et exemples
  • Configuration basée sur l'environnement

Démarrage rapide

Mise en place

# Cloner le dépôt git clone https://github.com/severity1/argocd-mcp.git cd argocd-mcp # Créer l'environnement virtuel et l'activer uv venv source .venv/bin/activate # Installer les dépendances uv pip install -e

Démarrer le serveur

Le serveur est configuré via des variables d'environnement. Voici les options de configuration disponibles :

Vous pouvez démarrer le serveur de plusieurs façons :

# En utilisant les outils MCP dev (fournit des outils de débogage) export ARGOCD_TOKEN=Votre_ARGOCD_TOKEN mcp dev server.py # En utilisant la commande MCP run export ARGOCD_TOKEN=Votre_ARGOCD_TOKEN mcp run server.py # Méthode standard export ARGOCD_TOKEN=Votre_ARGOCD_TOKEN uv run server.py # Définition de plusieurs variables d'environnement export ARGOCD_TOKEN=Votre_ARGOCD_TOKEN export ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1 export ARGOCD_VERIFY_SSL=false # Désactiver la vérification SSL pour les certificats auto-signés uv run server.py # Utiliser un fichier .env echo "ARGOCD_TOKEN=Votre_ARGOCD_TOKEN ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1 ARGOCD_VERIFY_SSL=false" > .env uv run server.py # Exécution en arrière-plan export ARGOCD_TOKEN=Votre_ARGOCD_TOKEN uv run server.py > server.log 2>&1 & echo $ ! > server.pid

Lorsque le jeton est fourni via une variable d'environnement, Claude peut l'utiliser sans que vous ayez à le spécifier dans chaque commande.

Se connecter avec Claude

Utilisation de Claude Code CLI

# Ajouter le serveur MCP claude mcp add argocd-mcp "uv run $(pwd)/server.py" # Avec le jeton claude mcp add argocd-mcp -e ARGOCD_TOKEN=Votre_ARGOCD_TOKEN -- "uv run $(pwd)/server.py" # Vérifier qu'il a été ajouté claude mcp list # Pour le débogage, vous pouvez utiliser l'inspecteur MCP avec la commande 'mcp dev'

Utilisation de Claude Desktop

Créez un fichier de configuration claude_desktop_config.json:

{ "mcpServers" : {"argocd-mcp" : { "command" : "/path/to/uv", "args" : [ "--directory", "/path/to/argocd-mcp", "run", "server.py" ], "env" : { "ARGOCD_TOKEN" : "your_argocd_token", "ARGOCD_API_URL" : "https://your-argocd-server.com/api/v1", "ARGOCD_VERIFY_SSL" : "true" } } }

Remplacez les chemins et les valeurs de configuration par vos valeurs réelles :

• Utilisez le chemin complet de l'exécutable uv (trouvez-le avec which uv sur macOS/Linux ou where uv sur Windows)
• Définissez le chemin d'accès correct à votre installation d'argocd-mcp
• Ajoutez votre jeton API ArgoCD
• Configurer d'autres variables d'environnement si nécessaire

Cette configuration indique à Claude Desktop comment démarrer automatiquement le serveur MCP avec vos paramètres d'environnement spécifiques.

Outils disponibles

Outils de session

• get_user_info: Obtenir les informations sur l'utilisateur actuel via api/v1/session/userinfo

Outils de paramétrage

• get_settings: Obtenir les paramètres du serveur ArgoCD, y compris l'interface utilisateur, l'OIDC et d'autres configurations
• get_plugins: Obtenir des informations sur les plugins ArgoCD configurés

Outils de version

• get_version: Obtenir des informations sur la version du serveur API

Outils de gestion des applications

• list_applications: Permet d'obtenir toutes les applications avec des options de filtrage
• get_application_details: Obtenir des informations détaillées sur une application spécifique
• create_application: Créer une nouvelle application
• update_application: Mettre à jour une application existante
• delete_application: Supprimer une application
• sync_application: Déclencher une opération de synchronisation sur une application

Exemples de conversations

Vérification de l'information sur l'utilisateur

Utilisateur : Quelles sont mes informations d'utilisateur dans ArgoCD ? Claude : Laissez-moi récupérer vos informations d'utilisateur. ⏺ argocd-mcp:get_user_info (MCP) ⎿ {"loggedIn" : true, "username" : "devops-user", "iss" : "argocd"} Vous êtes connecté en tant que "devops-user"

Obtenir la version d'ArgoCD

Utilisateur : Quelle est la version d'ArgoCD qui tourne sur le serveur ? Claude : Laissez-moi vérifier les informations sur la version d'ArgoCD. ⏺ argocd-mcp:get_version (MCP) ⎿ { "Version" : "v2.9.3+5eaf684", "BuildDate" : "2023-09-15T14:25:11Z", "GitCommit" : "5eaf68452", "GitTreeState" : "clean", "GoVersion" : "go1.20.7", "Compiler" : "gc", "Platform" : "linux/amd64", "KustomizeVersion" : "v5.1.1", "HelmVersion" : "v3.12.3", "KubectlVersion" : "v1.27.4", "JsonnetVersion" : "v0.20.0" } Vous utilisez ArgoCD v2.9.3, construit le 15 septembre 2023. Il fonctionne sous Linux (amd64) avec Go 1.20.7, et inclut Kustomize v5.1.1 et Helm v3.12.3

Obtenir les paramètres d'ArgoCD

User : Show me the ArgoCD server settings Claude : Let me retrieve the ArgoCD server settings for you. ⏺ argocd-mcp:get_settings (MCP) ⎿ { "clusterSettings" : {"appLabelKey" : "argocd.argoproj.io/instance", "controllerNamespace" : "argocd", "execEnabled" : true, "statusBadgeEnabled" : true, "uiBannerContent" : "Ceci est une instance de développement d'ArgoCD", "url" : "https://argocd.example.com" } } Voici les principaux paramètres de votre serveur ArgoCD : - URL : https://argocd.example.com - Espace de noms du contrôleur : argocd - Exécution activée : Oui - Badge d'état activé : Oui - Bannière d'interface utilisateur : "Ceci est une instance de développement d'ArgoCD"

Gestion des applications

Utilisateur : Quelles sont les applications que j'ai dans le projet " production " ? Claude : Laissez-moi lister vos applications dans le projet de production. ⏺ argocd-mcp:list_applications (MCP) ⎿ { "items" : [ { "metadata" : { "name" : "frontend-app", }, "status" : { "sync" : {"status" : "Synced"}, "health" : {"status" : "Healthy"}, } }, { "metadata" : { "name" : "api-service", }, "status" : {"sync" : {"status" : "OutOfSync"}, "health" : {"status" : "Healthy"}, } }, { "metadata" : {"name" : "database", }, "status" : {"sync" : {"status" : "Synced"}, "health" : {"status" : "Degraded"}, } } ] } Vous avez 3 applications dans le projet de production : - frontend-app (Synced, Healthy) - api-service (OutOfSync, Healthy) - database (Synced, Degraded)

User : Sync the api-service application Claude : I'll sync the api-service application for you. ⏺ argocd-mcp:sync_application (MCP) ⎿ { "resourcesResult" : {"updated" : ["Deployment/api-service"], "hooks" : [] }, "status" : "Syncing" } Application sync initiated successfully. L'opération de synchronisation est maintenant en cours

Développement

Exigences

• Python 3.12+
• MCP (inclut FastMCP et les outils de développement)
• gestionnaire de paquets uv (recommandé) ou pip
• Jeton API ArgoCD

Vérification des types

Ce projet utilise mypy pour la vérification statique des types afin d'améliorer la qualité du code et de détecter rapidement les bogues liés aux types :

# Installer mypy uv pip install mypy # Lancer la vérification de type uv run -m mypy

La configuration de la vérification de type est disponible dans pyproject.toml et mypy.ini. La configuration applique des règles de typage strictes, y compris :

• Interdiction des définitions non typées
• Avertissement en cas de retour d'un type quelconque
• Vérification de la complétude des définitions de fonctions
• Prise en charge des paquets d'espace de noms
• Configurations spécifiques aux modules

Structure du projet

Le code est organisé selon une structure modulaire :

argocd-mcp/ ├── api/ # Client API et communication │ ├── __init__.py │ └── client.py # Client HTTP pour l'API ArgoCD ├── models/ # Modèles de données │ ├── __init__.py │ └── applications.py # Structures de données d'application ├── tools/ # Implémentation des outils MCP │ ├── __init__.py │ ├── session.py # Outils de session (info utilisateur) │ ├── applications.py # Outils de gestion des applications │ ├── settings.py # Outils de paramétrage du serveur │ └── version.py # Outils d'information sur les versions ├── utils/ # Fonctions utilitaires │ ├── __init__.py ├── server.py # Point d'entrée principal du serveur ├── pyproject.toml # Configuration du projet et dépendances └── mypy.ini # Configuration de la vérification des types de Mypy

Extension du serveur

Pour ajouter de nouvelles fonctionnalités :

1. Ajouter de nouveaux outils au module approprié dans le répertoire tools
2. Enregistrer les nouveaux outils dans server.py
3. Suivre les modèles existants pour la validation des paramètres et la gestion des erreurs
4. Mettre à jour la documentation dans README.md
5. Ajouter des tests pour les nouvelles fonctionnalités

Résolution des problèmes

Si vous rencontrez des problèmes :

1. Vérifiez les journaux du serveur (la journalisation des informations est activée par défaut)
2. Notez que le traitement d'une requête de type CallToolRequest est une information et non une erreur
3. Si vous utilisez mcp dev server.py, l'inspecteur MCP s'ouvrira automatiquement à l'adresse http://localhost:5173 pour le débogage
4. Utilisez les journaux du serveur pour déboguer les appels et les réponses de l'API
5. Pour les problèmes de certificats SSL avec des certificats auto-signés :

# Désactiver la vérification SSL export ARGOCD_VERIFY_SSL=false uv run server.py

6. Vérifier si toutes les variables d'environnement requises sont correctement définies :

# Afficher toutes les variables d'environnement actuelles d'ArgoCD env | grep ARGOCD

Contribuer

Les contributions sont les bienvenues ! Veuillez ouvrir un problème ou une demande d'extraction si vous souhaitez contribuer à ce projet.

Lorsque vous contribuez, veuillez suivre les directives suivantes :

• Assurez-vous que tout le code inclut des indications de type correctes
• Exécuter la vérification de type mypy avant de soumettre des PRs
• Ajouter des tests pour les nouvelles fonctionnalités
• Mettre à jour la documentation pour toute nouvelle fonctionnalité ou changement