mcp-servidor-uyuni

Servidor de protocolo de contexto de modelo para la API del servidor Uyuni.

Descargo de responsabilidad

Este es un proyecto de código abierto proporcionado "TAL CUAL" sin ninguna garantía, expresa o implícita. Utilícelo bajo su propia responsabilidad. Para más detalles, consulte la sección Licencia.

Herramientas

• get_list_of_active_systems
• get_cpu_de_un_sistema
• get_all_systems_cpu_info
• comprobar_actualizaciones_del_sistema
• comprobar actualizaciones de todos los sistemas
• programar_aplicar_actualizaciones_pendientes_al_sistema
• programar_aplicar_actualización_específica
• añadir_sistema
• eliminar_sistema
• get_systems_needing_security_update_for_cve
• get_systems_needing_reboot
• programar reinicio del sistema
• cancelar acción
• listar_todas_las_acciones_programadas
• listar_claves_activación

Utilización

Hay dos formas principales de ejecutar el mcp-server-uyuni: usando el contenedor Docker pre-construido o ejecutándolo localmente con uv. Ambos métodos requieren un archivo de configuración.

Archivo de configuración

Antes de ejecutar el servidor, es necesario crear un archivo de configuración. Puede colocarlo en cualquier lugar, pero debe proporcionar la ruta correcta al ejecutar el servidor.

UYUNI_SERVER=192.168.1.124:8443 UYUNI_USER=admin UYUNI_PASS=admin # Opcional: Establezca 'false' para desactivar la verificación de certificados SSL. UYUNI_SSL_VERIFY=false # Opcional: Definir como "true" para habilitar las herramientas que realizan acciones de escritura (por ejemplo, solicitudes POST). UYUNI_MCP_WRITE_TOOLS_ENABLED=false Opcional: Establece el protocolo de transporte. Puede ser 'stdio' (por defecto) o 'http' # UYUNI_MCP_TRANSPORT=stdio > [!WARNING] > **Nota de seguridad en el transporte HTTP:** Cuando `UYUNI_MCP_TRANSPORT` se establece en `http`, el servidor se ejecuta sin autenticación. Esto significa que cualquier cliente con acceso a la red puede ejecutar comandos. Utilice este modo sólo en un entorno de red aislado y de confianza. Para más detalles, consulte la Política de Seguridad. > [!WARNING] > **Nota de seguridad sobre las herramientas de escritura:** Activar `UYUNI_MCP_WRITE_TOOLS_ENABLED` permite la ejecución de acciones que cambian el estado y son potencialmente destructivas (por ejemplo, eliminar sistemas, aplicar actualizaciones). Cuando se combina con `UYUNI_MCP_TRANSPORT=http`, este riesgo se amplifica, ya que cualquier cliente con acceso a la red puede realizar estas acciones. Habilite las herramientas de escritura sólo en un entorno de confianza # Opcional: Establezca la ruta para el archivo de registro del servidor. 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=""

Reemplace los valores con los detalles de su servidor Uyuni. Este archivo contiene información sensible y no debe ser enviado al control de versiones.

[NOTA]Formateo de la clave privada SSH

La variable UYUNI_SSH_PRIV_KEY, utilizada por la herramienta add_system, requiere la clave privada completa como una cadena de una sola línea. Las nuevas líneas del archivo de clave original deben sustituirse por la secuencia literal \n.

Puede generar el formato correcto a partir de su archivo de claves (por ejemplo, ~/.ssh/id_rsa) utilizando el siguiente comando. A continuación, puede copiar la salida en su archivo de configuración o variable de entorno.

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

Para establecerla como variable de entorno directamente en tu shell, ejecuta

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

Alternativamente, también puede establecer variables de entorno en lugar de utilizar un archivo.

Depurar con mcp inspect

Puede ejecutar (opción docker)

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

o puede ejecutar (opción uv)

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

Uso con Open WebUI

Open WebUI es una plataforma de IA autoalojada, extensible, rica en funciones y fácil de usar, diseñada para funcionar completamente sin conexión. Admite varios ejecutores LLM como Ollama y API compatibles con OpenAI, con motor de inferencia integrado para RAG, lo que la convierte en una potente solución de despliegue de IA. Más información en https://docs.openwebui.com/

[NOTA] Las siguientes instrucciones describen cómo configurar Open WebUI y el proxy MCP para desarrollo local y pruebas. Para despliegues de producción, por favor consulte la documentación oficial de Open WebUI para los procedimientos de configuración recomendados.

Configurar Open WebUI

Necesita tener instalado uv. Ver https://docs.astral.sh/uv

Start v0.6.10 (para soporte MCP necesitamos una versión >= 0.6.7)

 uv tool run open-webui@0.6.10 serve

Configura la URL de la API de OpenAI siguiendo estas instrucciones:

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

Para gemini, utiliza la URL https://generativelanguage.googleapis.com/v1beta/openai y obtén el token API de Google AI Studio https://aistudio.google.com/

Configurar el soporte MCP de Open WebUI

En primer lugar, asegúrese de que tiene su archivo de configuración listo como se describe en la sección Uso.

A continuación, necesitas un config.json para el servidor proxy MCP a OpenAPI.

Opción 1: Ejecutar con Docker (Recomendado)

Este es el método más sencillo para el despliegue. En el registro de contenedores de GitHub hay disponibles imágenes de contenedores preconstruidas.

Sustituye /ruta/a/tu/config por la ruta absoluta a tu archivo de configuración. Sustituya VERSION por la etiqueta de versión deseada (por ejemplo, v0.2.1) o utilice latest para la versión más reciente de la rama principal.

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

Alternativamente, puede utilizar variables de entorno en lugar de un archivo.

{ "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" ] } }

Opción 2: Ejecutar localmente con uv

Este método es ideal para el desarrollo.

1. Instalar uv: Ver https://docs.astral.sh/uv
2. Instalar dependencias:

   uv sync

3. Sustituya /path/to/your/config por la ruta absoluta a su archivo de configuración.

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

Iniciar el servidor proxy de MCP a OpenAPI

A continuación, puede iniciar el servidor proxy Model Context Protocol to Open API:

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

Añadir la herramienta

A continuación, puede añadir la herramienta a Open Web UI. Consulte https://docs.openwebui.com/openapi-servers/open-webui#step-2-connect-tool-server-in-open-webui.

Tenga en cuenta que la url debe ser http://localhost/mcp-server-uyuni como se explica en https://docs.openwebui.com/openapi-servers/open-webui#-optional-using-a-config-file-with-mcpo

Pruebas de capacidades avanzadas (elicitación)

[NOTA] El Protocolo de Contexto de Modelo (MCP) incluye funciones avanzadas como la Elicitación, que permite a las herramientas solicitar de forma interactiva al usuario la información que falta o la confirmación.

En el momento de escribir esto, no todos los clientes MCP soportan esta capacidad. Por ejemplo, Open WebUI no implementa actualmente la solicitud.

Para probar herramientas que aprovechan la solicitud (como la herramienta add_system cuando falta una clave de activación), necesita un cliente compatible. La extensión oficial de MCP para Visual Studio Code es un cliente de referencia totalmente compatible con la obtención y se recomienda para desarrollar y probar estas funciones.

Compilación de desarrollo local

Para construir la imagen Docker localmente para fines de desarrollo o pruebas:

docker build -t mcp-server-uyuni

A continuación, puede utilizar docker run -i --rm --env-file .venv/config mcp-server-uyuni en cualquiera de las configuraciones mcp-client explicadas anteriormente.

Proceso de lanzamiento

Para crear una nueva versión de mcp-server-uyuni, siga estos pasos.

1. ** Crear una rama de publicación:** git fetch upstream && git checkout upstream/main -b release-x.y.z. Asumiendo que upstream es el alias remoto del git upstream
2. Actualizar la documentación (README.md)
   • Asegúrese de que la lista de herramientas disponibles en la sección "## Herramientas" está actualizada y refleja todas las herramientas implementadas en srv/mcp-server-uyuni/server.py.
   • Revise y actualice las capturas de pantalla en el directorio docs/ y sus referencias en este README.md para reflejar la última interfaz de usuario o funcionalidad, si es necesario.
   • Compruebe que todas las instrucciones de uso y los ejemplos siguen siendo correctos.
3. Actualice los casos de prueba manuales (TEST_CASES.md)
   • Consulte la sección "Cómo actualizar para una nueva etiqueta/versión" dentro de TEST_CASES.md.
   • Añada una nueva columna de estado para la próxima versión (por ejemplo, Estado (vX.Y.Z)).
   • Ejecute todos los casos de prueba manuales relevantes contra el código que se va a liberar.
   • Registre el estado Pasa, Falla, Bloqueado o N/A para cada caso de prueba en la nueva columna de versión.
4. Confirme los cambios: Confirme todas las actualizaciones de README.md, TEST_CASES.md, y cualquier otro archivo modificado.
5. Actualice la versión en pyproject.toml: Utiliza el versionado semántico para establecer la nueva versión.
6. Actualizar uv.lock: Ejecute uv lock para actualizar el archivo uv.lock con la versión establecida en pyproject.toml
7. Actualizar CHANGELOG.md
   • Genera el registro de cambios usando conventional-changelog-cli. Si no lo tienes instalado globalmente, puedes usar npx.
   • El comando para generar el registro de cambios usando el preajuste conventionalcommits y enviarlo a CHANGELOG.md (añadiendo los nuevos cambios) es:

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

   • Revise el CHANGELOG.m d generado para comprobar su exactitud y formato.
   • Confirme el CHANGELOG.md actualizado.
8. Empuja la rama y crea una nueva Pull Request: git push origin release-x.y.z. Asumiendo que origin es el alias remoto de tu git fork.
9. Crear etiqueta Git: Crea una nueva etiqueta Git para la versión (por ejemplo, git tag vX.Y.Z). Sigue las reglas semánticas de versionado.
10. Enviar cambios y etiquetas: Envía tus cambios (incluyendo la actualización del registro de cambios) y la nueva etiqueta al repositorio (por ejemplo, git push && git push --tags).
11. Creación y envío automáticos: Al enviar la etiqueta a GitHub se activará automáticamente la acción "Docker Publish" de GitHub. Esta acción construye la imagen Docker y la empuja al Registro de Contenedores de GitHub(ghcr.io) con etiquetas para la versión específica (por ejemplo, v0.3.0) y major.minor (por ejemplo, v0.3). Al enviar a main se actualizará la última etiqueta.
12. Prueba el contenedor: Extrae la imagen recién publicada deghcr.io y ejecuta las pruebas en TEST_CASES.md contra ella.docker run -i --rm --env-file .venv/config ghcr.io/uyuni-project/mcp-server-uyuni:VERSION (sustituye VERSION por la nueva etiqueta).

Comentarios

¡Nos encantaría saber de ti! Cualquier idea que quieras discutir o compartir, por favor hazlo en https://github.com/uyuni-project/uyuni/discussions/10562

Si encuentra algún error, sea tan amable de abrir un nuevo informe de error en https://github.com/uyuni-project/mcp-server-uyuni/issues/new?type=bug

¡Gracias de antemano de parte del equipo uyuni!

Licencia

Este proyecto está licenciado bajo la Licencia Apache, Versión 2.0. Vea el archivo LICENSE para más detalles.