mcp-server-uyuni

Servidor Model Context Protocol per a l'API del Servidor Uyuni.

Disclaimer

Aquest és un projecte de codi obert proporcionat "COM S'ENTI" sense cap garantia, expressa o implícita. Utilitzeu-lo sota el vostre propi risc. Per a més detalls, consulteu la secció Llicència.

Eines

• get_list_of_active_systems
• get_cpu_of_a_system
• get_all_systems_cpu_info
• check_system_updates
• check_all_systems_for_updates
• schedule_apply_pending_updates_to_system
• schedule_apply_specific_update
• add_system
• remove_system
• get_systems_needing_security_update_for_cve
• get_systems_needing_reboot
• schedule_system_reboot
• cancel_action
• list_all_scheduled_actions
• list_activation_keys

Ús

Hi ha dues maneres principals d'executar el mcp-server-uyuni: utilitzant el contenidor Docker preconstruït o executant-lo localment amb uv. Ambdós mètodes requereixen un fitxer config.

Fitxer de configuració

Abans d'executar el servidor, cal crear un fitxer config. Podeu col·locar-lo a qualsevol lloc, però heu de proporcionar la ruta correcta quan executeu el servidor.

UYUNI_SERVER=192.168.1.124:8443
UYUNI_USER=admin
UYUNI_PASS=admin
# Opcional: estableix a 'false' per desactivar la verificació del certificat SSL. Per defecte és 'true'.
# UYUNI_SSL_VERIFY=false
# Opcional: estableix a 'true' per habilitar les eines que realitzen accions d'escriptura (p. ex., sol·licituds POST). Per defecte és 'false'.
# UYUNI_MCP_WRITE_TOOLS_ENABLED=false
# Opcional: estableix el protocol de transport. Pot ser 'stdio' (per defecte) o 'http'.
# UYUNI_MCP_TRANSPORT=stdio

> [!WARNING]
> **Nota de seguretat sobre el transport HTTP:** Quan `UYUNI_MCP_TRANSPORT` es estableix a `http`, el servidor s'executa sense autenticació. Això significa que qualsevol client amb accés a la xarxa pot executar comandes. Utilitzeu aquest mode només en un entorn de xarxa de confiança i aïllat. Per a més detalls, consulteu la Política de seguretat.

> [!WARNING]
> **Nota de seguretat sobre les eines d'escriptura:** Habilitar `UYUNI_MCP_WRITE_TOOLS_ENABLED` permet l'execució d'accions que canvien l'estat i que poden ser destructives (p. ex., eliminar sistemes, aplicar actualitzacions). Quan es combina amb `UYUNI_MCP_TRANSPORT=http`, aquest risc s'amplifica, ja que qualsevol client amb accés a la xarxa pot realitzar aquestes accions. Habiliteu les eines d'escriptura només en un entorn de confiança.

# Opcional: estableix el camí del fitxer de registre del servidor. Per defecte, es registra a la consola.
# 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=""

Substituïu els valors amb els detalls del vostre servidor Uyuni. Este fitxer conté informació sensible i no ha de ser commitejat al control de versions.

[!NOTE] Format del clau privada SSH

La variable UYUNI_SSH_PRIV_KEY, utilitzada per l'eina add_system, requereix tota la clau privada com una única cadena de línia. Les línies noves del fitxer de clau original s'han de substituir per la seqüència literal \n.

Podeu generar el format correcte a partir del vostre fitxer de clau (p. ex., ~/.ssh/id_rsa) utilitzant la següent comanda. Després podeu copiar la sortida al vostre fitxer config o variable d'entorn.

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

Per establir-la directament com a variable d'entorn a la vostra shell, executeu:

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

Alternativament, també podeu establir variables d'entorn en lloc d'utilitzar un fitxer.

Depuració amb mcp inspect

Podeu executar (opció Docker)

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

o podeu executar (opció uv)

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

Ús amb Open WebUI

Open WebUI és una plataforma d'IA autoalbergada, extensible, rica en funcionalitats i fàcil d'usar, dissenyada per funcionar completament offline. Suporta diversos runners LLM com Ollama i API compatibles amb OpenAI, amb un motor d'inferència integrat per RAG, fent-la una solució potent d'implementació d'IA. Més informació a https://docs.openwebui.com/

[!NOTE] Les instruccions següents descriuen com configurar Open WebUI i el proxy MCP per a desenvolupament i proves locals. Per a implementacions en producció, consulteu la documentació oficial d'Open WebUI per a les procediments recomanats.

Instal·lació d'Open WebUI

Cal tenir uv instal·lat. Vegeu https://docs.astral.sh/uv

Inicieu la versió v0.6.10 (per a suport MCP necessitem una versió >= 0.6.7)

 uv tool run open-webui@0.6.10 serve

Configureu l'URL de l'API OpenAI seguint aquestes instruccions:

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

Per a Gemini, utilitzeu l'URL https://generativelanguage.googleapis.com/v1beta/openai i obteniu el token API del Google AI Studio https://aistudio.google.com/

Configuració del suport MCP d'Open WebUI

Primer, assegureu-vos que teniu el fitxer config preparat com s'explica a la secció Ús.

A continuació, necessiteu un config.json per al servidor proxy MCP a OpenAPI.

Opció 1: Execució amb Docker (Recomanada)

Aquesta és la manera més senzilla de desplegar. Les imatges de contenidor preconstruïdes estan disponibles al GitHub Container Registry.

Substituïu /path/to/your/config pel camí absolut al vostre fitxer config. Substituïu VERSION pel tag de llançament desitjat (p. ex., v0.2.1) o useu latest per a la construcció més recent del branch main.

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

Alternativament, podeu utilitzar variables d'entorn en lloc d'un fitxer.

{
  "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ó 2: Execució local amb uv

Aquest mètode és ideal per al desenvolupament.

1. Instal·leu uv: Vegeu https://docs.astral.sh/uv
2. Instal·leu les dependències:

   uv sync
   

3. Substituïu /path/to/your/config pel camí absolut al vostre fitxer config.

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

Inici del servidor proxy MCP a OpenAPI

Després, podeu iniciar el servidor proxy Model Context Protocol a Open API:

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

Afegeix l'eina

Després podeu afegir l'eina a l'Open Web UI. Vegeu https://docs.openwebui.com/openapi-servers/open-webui#step-2-connect-tool-server-in-open-webui.

Recordeu que l'URL ha de ser http://localhost/mcp-server-uyuni com s'exposa a https://docs.openwebui.com/openapi-servers/open-webui#-optional-using-a-config-file-with-mcpo

Prova de capacitats avançades (Elicitation)

[!NOTE] El Model Context Protocol (MCP) inclou característiques avançades com Elicitation, que permet a les eines demanar interactivament informació que falta o confirmació a l'usuari.

Fins a la data d'escriptura, no tots els clients MCP admeten aquesta capacitat. Per exemple, OpenJanuaryUI no admet Elicitation.

Per provar aquesta funcionalitat, podeu utilitzar el mcp-server-uyuni amb un client que suporti Elicitation, com el mcp-cli.

Prova de configuració del servidor

Després d'executar el servidor, podeu provar la configuració utilitzant la comanda següent per obtenir la llista de sistemes actius:

mcp-cli get_list_of_active_systems

Desenvolupament de la versió 2.0

Per a una versió 2.0, consulteu el repositori GitHub i seguiu les instruccions de desenvolupament.

Licència

Aquest projecte està llicenciat sota la Licència Apache, Versió 2.0. Vegeu el fitxer LICENSE per a més detalls.