KVM/libvirt VMs and backups (Fedora)

fedora-agents MCP Server

[CI] [npm] [License: MIT] [TypeScript]

English summary. MCP server that gives an AI agent hands on KVM/libvirt virtual machines and Borg/Timeshift backups on Fedora. Each tool declares whether it needs sudo and whether it is destructive; the client must confirm destructive calls. Arguments are validated with Zod before any script runs. Install with npx fedora-agents-mcp (--help lists the settings) or npm ci && npm run build. Security policy and tool table: SECURITY.md.

Serveur MCP (Model Context Protocol) qui expose les agents VM-Controller et Backup-Manager via le protocole MCP. Permet a Claude Code de gerer les VMs KVM et les backups directement.

Pourquoi c'est conçu pour des agents LLM

Un script virsh suffit à un humain qui lit la sortie et réagit. Un agent LLM (grand modèle de langage) qui pilote des machines a besoin d'autres garanties, et c'est ce que ce serveur ajoute autour des scripts :

• Chaque appel est traçable. Un identifiant de corrélation est créé par appel d'outil et suit toutes les lignes du journal ; le journal d'audit JSON est écrit de façon synchrone, sur disque avant la réponse à l'agent (src/logger.ts).
• Le réessai dépend de la nature de l'outil. Seules les lectures idempotentes (vm_status, backup_status, backup_list, backup_verify) sont retentées, trois fois avec un délai croissant de 1, 2 puis 5 s ; une action qui modifie (démarrer, arrêter, restaurer, nettoyer) ne l'est jamais. Une erreur de validation ou de permission arrête tout de suite (src/utils/executor.ts).
• Le code de sortie devient une erreur typée. Les scripts renvoient un code (délai dépassé, verrou déjà pris, espace insuffisant...) que le serveur traduit en ErrorCode lisible par l'agent, au lieu d'un texte à interpréter (EXIT_CODE_MAP, src/config.ts).
• Les droits root sont donnés script par script. Aucune règle sudoers sur virsh, virt-clone ou qemu-img ; seuls les scripts système qui en ont besoin sont autorisés, un par un (voir Emplacement des scripts et sudoers).
• La progression des tâches longues est publiée. Clone, export ou sauvegarde reportent leurs étapes à mcp-tracking (scripts/utils/tracking.sh) : l'agent vérifie l'avancement plus tard au lieu de bloquer.
• Le client sait ce qui est dangereux sans liste à maintenir. Chaque outil publie ses annotations MCP (readOnlyHint, destructiveHint, idempotentHint) ; Lyra y lit la dangerosité et fait confirmer l'humain avant une action destructrice.

Local-first et self-hosted : tout tourne sur la machine (on-prem), sans service tiers, avec un modèle local via Ollama dans Lyra ou n'importe quel client MCP.

Demo

[Client MCP : liste des 19 outils, aide, puis etat des VMs KVM]

Enregistree sur la machine reelle avec docs/demo/record.sh : un client MCP minimal (docs/demo/mcp_demo.py) demarre le serveur en stdio, liste les outils, appelle help puis vm_status (lecture seule). Les adresses IP sont remplacees par des adresses d'exemple.

Architecture

fedora-agents/  scripts/                -- scripts bash embarques (autonomes, plus de dependance a fedora-setup)    agents/vm-controller/   vm-start, vm-stop, vm-status, vm-exec, vm-copy, vm-snapshot,                            vm-destroy, vm-export, vm-import (+ common.sh)    agents/backup-manager/  backup-create, backup-list, backup-restore, backup-verify,                            backup-clean, backup-status (+ common.sh)    kvm/                    kvm-clone, kvm-clone-system, kvm-snapshot, verify-vm-clone                            (+ helpers fix-nm-connection-vm, _fix-grub-vm)    backup/                 borg-backup, test-restore, get-borg-passphrase    utils/tracking.sh       reporting optionnel vers MCP Tracking (127.0.0.1:8765)    config.env.example      surcharges locales (KVM_IMAGES_DIR, VM_SSH_USER...)  src/    index.ts          -- point d'entree, enregistrement des outils MCP    config.ts         -- timeouts, permissions, codes d'erreur    logger.ts         -- logging JSON structure    tools/      vm-controller.ts    -- outils vm_start, vm_stop, vm_status, vm_exec, vm_copy,                             vm_snapshot, vm_verify, vm_clone, vm_clone_system, vm_destroy      backup-manager.ts   -- outils backup_create, backup_list, backup_restore,                             backup_verify, backup_clean, backup_status      vm-portability.ts   -- outils vm_export, vm_import    utils/      executor.ts     -- execution des scripts bash avec retry, timeout, gestion erreurs      validation.ts   -- schemas Zod pour tous les parametres d'outils

Outils MCP exposes

help

Liste tous les outils disponibles avec leurs descriptions.

• Script sous-jacent: aucun (genere directement dans index.ts)

VM Controller

Backup Manager

VM Portabilite

Scripts helpers non exposes

Ces scripts sont utilises en interne mais pas directement accessibles via MCP:

Emplacement des scripts et sudoers

src/config.ts resout la racine des scripts dans cet ordre :

1. LYRA_SCRIPTS_DIR (variable d'environnement)
2. /usr/local/lib/lyra/scripts : copie root:root 0755 installee par l'installeur Lyra
3. scripts/ du depot (mode developpement)

Les outils sans sudo (vm_status, vm_start, vm_stop, vm_exec, vm_copy, vm_snapshot, vm_export, vm_verify) pilotent libvirt directement : l'utilisateur doit etre membre du groupe libvirt, que polkit autorise sur qemu:///system :

sudo usermod -aG libvirt "$USER"   # puis se reconnectervirsh -c qemu:///system list --all # doit repondre sans sudo

Aucune regle sudoers ne vise virsh, virt-clone ou qemu-img : un NOPASSWD sur ces binaires equivaut a root (un domaine peut monter le disque de l'hote). Les outils qui demandent root (vm_destroy, vm_clone, vm_clone_system, vm_import et les backup_*) lancent leur script entier via sudo. Ces regles visent uniquement la copie systeme, script par script, jamais un glob sur un dossier inscriptible par l'utilisateur (sinon n'importe quel processus de son uid obtient root en y deposant un .sh) :

user ALL=(ALL) NOPASSWD: /usr/local/lib/lyra/scripts/kvm/kvm-clone.shuser ALL=(ALL) NOPASSWD: /usr/local/lib/lyra/scripts/kvm/kvm-clone-system.sh...

L'installeur Lyra genere ce fichier (/etc/sudoers.d/lyra) et le valide avec visudo -cf avant de l'activer. Installation manuelle :

sudo install -d -o root -g root -m 0755 /usr/local/lib/lyra/scriptssudo cp -r scripts/. /usr/local/lib/lyra/scripts/sudo chown -R root:root /usr/local/lib/lyra/scriptssudo find /usr/local/lib/lyra/scripts -type f -name '*.sh' -exec chmod 0755 {} +

Configuration

Le serveur est un composant de Lyra mais fonctionne seul : SCRIPTS_DIR=./scripts node dist/index.js démarre sans sudoers (les outils marqués requiresSudo échoueront alors proprement).

• Timeouts: src/config.ts (TIMEOUTS)
• Permissions sudo: src/config.ts (TOOL_PERMISSIONS)
• Retry: src/config.ts (RETRY_CONFIG)
• Config locale: scripts/config.env (copier depuis scripts/config.env.example)

Logs

Les logs JSON structures sont ecrits dans:

1. /var/log/mcp-agents/ (si accessible en ecriture)
2. ~/.local/state/mcp-agents/ (fallback utilisateur)
3. /tmp/mcp-agents-logs/ (fallback final)

Installation en une ligne

npx fedora-agents-mcp            # depuis npm ; `npx fedora-agents-mcp --help` pour les reglages                                 # depuis un clone : npm ci && npm run build && node dist/index.js

Configuration Claude Desktop / Claude Code (mcpServers) :

{ "fedora-agents": { "command": "npx", "args": ["-y", "fedora-agents-mcp"] } }

Politique de securite et tableau des outils : SECURITY.md.

Installation et demarrage

Paquets a installer sur l'hote (noms Fedora ; Debian/Ubuntu entre parentheses quand ils different) :

Les cles d'hote SSH des VMs sont conservees dans $XDG_STATE_HOME/fedora-agents/known_hosts (a defaut ~/.local/state/fedora-agents/known_hosts) : premier contact accepte, cle modifiee refusee.

npm installnpm run build
# Test local (scripts/ du depot, sans sudoers)node dist/index.js

La configuration MCP pour Claude Code ou Claude Desktop est decrite dans la section Installation en une ligne.

Part of the Lyra ecosystem