Servidor MCP ArgoCD

Un servidor MCP (Model Context Protocol) que se integra con la API de ArgoCD y permite a los asistentes de inteligencia artificial y a los grandes modelos lingüísticos gestionar las aplicaciones y los recursos de ArgoCD mediante interacciones de lenguaje natural.

Características

• Autenticación y gestión de sesiones
  • Recuperación de información de usuario de la API ArgoCD
  • Autenticación basada en token con ArgoCD
  • Acceso a los ajustes y la configuración del servidor
  • Recuperación de información sobre plugins
  • Recuperación de información sobre versiones
• Gestión de aplicaciones
  • Listar y filtrar aplicaciones por proyecto, nombre, espacio de nombres
  • Obtener información detallada de las aplicaciones
  • Crear, actualizar y eliminar aplicaciones
  • Sincronizar aplicaciones con opciones configurables
• Cliente API robusto
  • Normalización de URL y gestión inteligente de endpoints
  • Gestión exhaustiva de errores y mensajes de error detallados
  • Tiempos de espera configurables y verificación SSL
  • Protección y enmascaramiento de seguridad de tokens
• Experiencia del desarrollador
  • Comprobación completa de tipos estáticos con mypy
  • Documentación detallada y ejemplos
  • Configuración basada en el entorno

Inicio rápido

Configuración

# Clonar el repositorio git clone https://github.com/severity1/argocd-mcp.git cd argocd-mcp # Crear entorno virtual y activarlo uv venv source .venv/bin/activate # Instalar dependencias uv pip install -e

Arrancar el servidor

El servidor se configura mediante variables de entorno. Estas son las opciones de configuración disponibles:

Puede iniciar el servidor de varias maneras:

# Usando las herramientas MCP dev (proporciona herramientas de depuración) export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN mcp dev server.py # Usando el comando MCP run export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN mcp run server.py # Método estándar export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN uv run server.py # Configuración de múltiples variables de entorno export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN export ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1 export ARGOCD_VERIFY_SSL=false # Desactivar la verificación SSL para certificados autofirmados uv run server.py # Utilizar un archivo .env echo "ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1 ARGOCD_VERIFY_SSL=false" > .env uv run server.py # Ejecutar en segundo plano export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN uv run server.py > server.log 2>&1 & echo $! > server.pid

Cuando el token se proporciona mediante una variable de entorno, Claude puede utilizarlo sin que tengas que especificarlo en cada comando.

Conexión con Claude

Usando Claude Code CLI

# Añade el servidor MCP claude mcp add argocd-mcp "uv run $(pwd)/server.py" # Con el token claude mcp add argocd-mcp -e ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN -- "uv run $(pwd)/server.py" # Verifica que se ha añadido claude mcp list # Para depurar, puedes usar MCP Inspector con el comando 'mcp dev'

Uso de Claude Desktop

Crear un archivo de configuración claude_desktop_config.json:

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

Sustituya las rutas y los valores de configuración por sus valores reales:

• Utilice la ruta completa al ejecutable uv (encuéntrelo con which uv en macOS/Linux o where uv en Windows)
• Establece la ruta de directorio correcta a tu instalación de argocd-mcp
• Añade tu token de la API ArgoCD
• Configura otras variables de entorno según sea necesario

Esta configuración indica a Claude Desktop cómo iniciar automáticamente el servidor MCP con su configuración de entorno específica.

Herramientas disponibles

Herramientas de sesión

• get_user_info: Obtiene la información del usuario actual a través de api/v1/session/userinfo

Herramientas de configuración

• get_settings: Obtiene la configuración del servidor ArgoCD incluyendo UI, OIDC y otras configuraciones
• get_plugins: Obtiene información sobre los plugins ArgoCD configurados

Herramientas de versión

• get_version: Obtiene información sobre la versión del servidor API

Herramientas de gestión de aplicaciones

• list_applications: Obtener todas las aplicaciones con opciones de filtrado
• get_application_details: Obtener información detallada sobre una aplicación específica
• create_application: Crear una nueva aplicación
• update_application: Actualizar una aplicación existente
• delete_application: Eliminar una aplicación
• sync_application: Activar una operación de sincronización en una aplicación

Ejemplos de conversaciones

Comprobación de la información de usuario

Usuario: ¿Cuál es mi información de usuario en ArgoCD? Claude: Déjame recuperar tu información de usuario. ⏺ argocd-mcp:get_user_info (MCP) ⎿ {"loggedIn": true, "username": "devops-user", "iss": "argocd"} Has iniciado sesión como "devops-user"

Obtener la versión de ArgoCD

Usuario: ¿Qué versión de ArgoCD se está ejecutando en el servidor? Claude: Déjame comprobar la información de la versión de 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" } Está ejecutando ArgoCD v2.9.3, construido el 15 de septiembre de 2023. Se ejecuta en Linux (amd64) con Go 1.20.7, e incluye Kustomize v5.1.1 y Helm v3.12.3

Obteniendo la configuración de ArgoCD

Usuario: Muéstrame la configuración del servidor ArgoCD Claude: Déjame recuperar la configuración del servidor ArgoCD por ti. ⏺ argocd-mcp:get_settings (MCP) ⎿ { "clusterSettings": { "appLabelKey": "argocd.argoproj.io/instance", "controllerNamespace": "argocd", "execEnabled": true, "statusBadgeEnabled": true, "uiBannerContent": "Esta es una instancia de desarrollo de ArgoCD", "url": "https://argocd.example.com" } } Estos son los parámetros clave de su servidor ArgoCD: - URL: https://argocd.example.com - Espacio de nombres del controlador: argocd - Ejecución habilitada: Sí - Insignia de estado habilitada: Sí - Banner UI: "Esta es una instancia de desarrollo de ArgoCD"

Gestión de aplicaciones

Usuario: ¿Qué aplicaciones tengo en el proyecto de "producción"? Claude: Déjame listar tus aplicaciones en el proyecto de producción. ⏺ 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"}, } } } } Tienes 3 aplicaciones en el proyecto de producción: - frontend-app (Synced, Healthy) - api-service (OutOfSync, Healthy) - database (Synced, Degraded)

Usuario: Sincroniza la aplicación api-service Claude: Sincronizaré la aplicación api-service por ti. ⏺ argocd-mcp:sync_application (MCP) ⎿ { "resourcesResult": {"updated": ["Deployment/api-service"], "hooks": [] }, "status": "Syncing" } Sincronización de la aplicación iniciada con éxito. La operación de sincronización está en curso

Desarrollo

Requisitos

• Python 3.12+
• MCP (incluye FastMCP y herramientas de desarrollo)
• gestor de paquetes uv (recomendado) o pip
• Token API ArgoCD

Comprobación de tipos

Este proyecto utiliza mypy para la comprobación estática de tipos con el fin de mejorar la calidad del código y detectar errores relacionados con los tipos de forma temprana:

# Instalar mypy uv pip install mypy # Ejecutar la comprobación de tipos uv run -m mypy

La configuración de la comprobación de tipos está disponible tanto en pyproject.toml como en mypy.ini. La configuración impone estrictas reglas de tipado incluyendo:

• No permitir definiciones no tipadas
• Advertencia sobre la devolución de tipos Any
• Comprobación de la integridad de las definiciones de función
• Soporte de paquetes de espacios de nombres
• Configuraciones específicas de módulo

Estructura del proyecto

El código está organizado en una estructura modular:

argocd-mcp/ ├── api/ # Cliente API y comunicación │ ├── __init__.py │ └── client.py # Cliente HTTP para API ArgoCD ├── modelos/ # Modelos de datos │ ├── __init__.py │ └── applications.py # Application data structures ├── tools/ # MCP tools implementation │ ├── __init__.py │ ├── session.py # Session tools (user info) │ ├── applications.py # Herramientas de gestión de aplicaciones │ ├── settings.py # Herramientas de configuración del servidor │ └── version.py # Herramientas de información sobre la versión ├── utils/ # Funciones de utilidad │ ├── __init__.py ├── server.py # Punto de entrada principal del servidor ├── pyproject.toml # Configuración y dependencias del proyecto └── mypy.ini # Configuración de comprobación de tipos de Mypy

Ampliación del servidor

Para añadir nuevas funcionalidades:

1. Añade nuevas herramientas al módulo correspondiente en el directorio tools
2. Registra las nuevas herramientas en server.py
3. Sigue los patrones existentes para la validación de parámetros y el manejo de errores
4. Actualizar la documentación en README.md
5. Añadir pruebas para la nueva funcionalidad

Solución de problemas

Si encuentra problemas:

1. Compruebe los registros del servidor (el registro de información está activado por defecto)
2. Tenga en cuenta que el procesamiento de solicitudes de tipo CallToolRequest es informativo, no un error
3. Si utiliza mcp dev server.py, el Inspector MCP se abrirá automáticamente en http://localhost:5173 para la depuración
4. Utilice los registros del servidor para depurar las llamadas a la API y las respuestas
5. Para problemas de certificados SSL con certificados autofirmados:

# Desactivar la verificación SSL export ARGOCD_VERIFY_SSL=false uv run server.py

6. Compruebe si todas las variables de entorno necesarias están configuradas correctamente:

# Mostrar todas las variables de entorno actuales de ArgoCD env | grep ARGOCD

Contribución

Las contribuciones son bienvenidas Por favor, abre un issue o pull request si quieres contribuir a este proyecto.

Cuando contribuyas, por favor sigue estas directrices:

• Asegúrate de que todo el código incluye las indicaciones de tipo adecuadas
• Ejecuta la comprobación de tipos de mypy antes de enviar PRs
• Añade pruebas para las nuevas funcionalidades
• Actualiza la documentación para cualquier nueva característica o cambio