KVM/libvirt VMs and backups (Fedora)

fedora-agents MCP 服务

英文摘要。 MCP 服务让 AI Agent 能够直接操作 Fedora 上的 KVM/libvirt 虚拟机以及 Borg/Timeshift 备份。每个工具都会声明是否需要 sudo，以及是否具有破坏性；客户端必须确认具有破坏性的调用。任何脚本运行前，都会使用 Zod 验证参数。使用 npx fedora-agents-mcp 安装（--help 会列出设置），或运行 npm ci && npm run build。安全策略和工具表：SECURITY.md。

通过 MCP（Model Context Protocol，模型上下文协议）公开 VM-Controller 和 Backup-Manager Agent 的 MCP 服务。让 Claude Code 能够直接管理 KVM 虚拟机和备份。

为什么它是为 LLM Agent 设计的

对于能读取输出并做出响应的人来说，virsh 脚本就足够了。而操作机器的大模型 Agent 需要其他保障，这正是此服务围绕脚本提供的功能：

• 每次调用都可追踪。 每次工具调用都会生成一个关联 ID，并贯穿所有日志行；JSON 审计日志会同步写入磁盘，确保在向 Agent 响应前完成写入（src/logger.ts）。
• 重试取决于工具的性质。 只有幂等的读取操作（vm_status、backup_status、backup_list、backup_verify）会重试，最多三次，间隔依次为 1、2 和 5 秒；会修改状态的操作（启动、停止、恢复、清理）绝不会重试。验证或权限错误会立即终止（src/utils/executor.ts）。
• 退出代码会转换为类型化错误。 脚本会返回代码（超时、锁已被占用、空间不足……），服务会将其转换为 Agent 可读的 ErrorCode，而不是需要自行解读的文本（EXIT_CODE_MAP、src/config.ts）。
• root 权限按脚本授予。 不会为 virsh、virt-clone 或 qemu-img 配置 sudoers 规则；仅逐一授权确实需要权限的系统脚本（参见脚本和 sudoers 的位置）。
• 长时间运行任务会发布进度。 克隆、导出或备份会通过 mcp-tracking 报告进度（scripts/utils/tracking.sh）：Agent 可以稍后查看进度，无需一直等待。
• 客户端无需维护列表，就能识别危险操作。 每个工具都会发布其 MCP 注解（readOnlyHint、destructiveHint、idempotentHint）；Lyra 会据此判断危险性，并在执行破坏性操作前让用户确认。

本地优先且可自托管：所有内容都在本机（本地部署）运行，不依赖第三方服务；可在 Lyra 中通过 Ollama 使用本地模型，也可使用任何 MCP 客户端。

演示

使用 docs/demo/record.sh 在实际机器上录制：一个最小 MCP 客户端（docs/demo/mcp_demo.py）通过 stdio 启动服务、列出工具、调用 help，然后调用 vm_status（只读）。IP 地址已替换为示例地址。

架构

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

已公开的 MCP 工具

help

列出所有可用工具及其说明。

• 底层脚本：无（直接在 index.ts 中生成）

VM 控制器

工具	底层脚本	描述
vm_start	vm-controller/vm-start.sh	启动 VM，可选择等待 SSH 就绪
vm_stop	vm-controller/vm-stop.sh	停止 VM（正常停止或强制停止）
vm_destroy	vm-controller/vm-destroy.sh	删除 VM 定义和存储
vm_status	vm-controller/vm-status.sh	显示 VM 状态（或列出所有 VM）
vm_exec	vm-controller/vm-exec.sh	通过 SSH 在 VM 中执行命令
vm_copy	vm-controller/vm-copy.sh	通过 SCP 在主机与 VM 之间复制文件
vm_snapshot	vm-controller/vm-snapshot.sh	管理快照（create/list/restore/delete）
vm_verify	kvm/verify-vm-clone.sh	验证克隆是否忠实于主机系统
vm_clone	kvm/kvm-clone.sh	克隆现有 VM（完整克隆或链接克隆）
vm_clone_system	kvm/kvm-clone-system.sh	将整个主机系统克隆到 VM

备份管理器

工具	底层脚本	描述
backup_status	backup-manager/backup-status.sh	备份总览仪表板
backup_list	backup-manager/backup-list.sh	列出可用备份
backup_create	backup-manager/backup-create.sh	创建备份（timeshift/borg/vm-snapshot/manual）
backup_verify	backup-manager/backup-verify.sh	验证备份完整性
backup_restore	backup-manager/backup-restore.sh	恢复备份（有破坏性）
backup_clean	backup-manager/backup-clean.sh	应用保留策略

VM 可移植性

工具	底层脚本	描述
vm_export	vm-controller/vm-export.sh	将 VM 导出为经过清理的 .tar.gz 存档
vm_import	vm-controller/vm-import.sh	从 vm_export 存档导入 VM

未公开的辅助脚本

这些脚本在内部使用，但无法通过 MCP 直接访问：

脚本	作用
agents/vm-controller/common.sh	通用函数（virsh、SSH、日志记录）
agents/backup-manager/common.sh	通用函数（borg、锁、通知）
kvm/kvm-snapshot.sh	由 vm-snapshot.sh 调用的快照引擎
kvm/fix-nm-connection-vm.sh, kvm/_fix-grub-vm.sh	克隆后的修复（NetworkManager、grub BLS）
backup/borg-backup.sh, backup/get-borg-passphrase.sh	Borg 备份；通过 systemd-creds 或 Bitwarden 获取密码短语，绝不以明文存储
backup/test-restore.sh	由 backup-verify --deep 使用的恢复测试

脚本位置和 sudoers

src/config.ts 按以下顺序解析脚本根目录：

1. LYRA_SCRIPTS_DIR（环境变量）
2. /usr/local/lib/lyra/scripts：由 Lyra 安装程序安装的 root:root 0755 副本
3. 仓库中的 scripts/（开发模式）

不使用 sudo 的工具（vm_status、vm_start、vm_stop、vm_exec、vm_copy、vm_snapshot、 vm_export、vm_verify）直接控制 libvirt：用户必须属于 libvirt 组，且 polkit 必须允许该组访问 qemu:///system：

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

没有任何 sudoers 规则针对 virsh、virt-clone 或 qemu-img：对这些二进制文件设置 NOPASSWD 等同于授予 root 权限（一个域可以挂载主机磁盘）。需要 root 权限的工具 （vm_destroy、vm_clone、vm_clone_system、vm_import 和 backup_*）会通过 sudo 运行 整个脚本。这些规则仅针对系统副本中的单个脚本，绝不使用通配符匹配用户可写目录（否则，用户 UID 下的任意进程都可以在其中放入 .sh 文件以获取 root 权限）：

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

Lyra 安装程序会生成此文件（/etc/sudoers.d/lyra），并在启用之前使用 visudo -cf 对其进行验证。手动安装：

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

配置

变量	作用	默认值
SCRIPTS_DIR	脚本目录（agents/、kvm/）：生产环境使用根目录副本，测试使用仓库中的 scripts/	Lyra 安装的根目录副本，否则为 scripts/
MCP_AGENTS_LOG_DIR	JSON 日志（服务、错误、sudo 下或破坏性调用的审计）	如果 /var/log/mcp-agents 可写则使用该目录，否则使用 $XDG_STATE_HOME/mcp-agents（~/.local/state/mcp-agents）；文件权限为 0600，绝不写入 /tmp
scripts/config.env	KVM、Borg、Timeshift 路径（参见 config.env.example）	示例值
VM_SSH_USER、VM_SSH_USERS	VM 的 SSH 账户：默认账户，然后是按 VM 指定的账户（"fedora-base=fedora ubuntu-base=ubuntu"），配置于 config.env 或 ~/.config/vm-controller/config	当前用户

该服务是 Lyra 的一个组件，但也能独立运行：SCRIPTS_DIR=./scripts node dist/index.js 无需 sudoers 即可启动（标记为 requiresSudo 的工具会正常报错）。

• 超时：src/config.ts（TIMEOUTS）
• sudo 权限：src/config.ts（TOOL_PERMISSIONS）
• 重试：src/config.ts（RETRY_CONFIG）
• 本地配置：scripts/config.env（从 scripts/config.env.example 复制）

日志

结构化 JSON 日志写入位置：

1. /var/log/mcp-agents/（如果可写）
2. ~/.local/state/mcp-agents/（用户级回退目录）
3. /tmp/mcp-agents-logs/（最终回退目录）

一行安装

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

Claude Desktop / Claude Code 配置（mcpServers）：

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

安全策略和工具表：SECURITY.md。

安装与启动

需要在主机上安装的软件包（Fedora 软件包名称；名称不同时括号内为 Debian/Ubuntu 对应名称）：

命令	软件包	相关工具
virsh	libvirt-client（libvirt-clients）	所有 vm_*
virt-clone	virt-install（virtinst）	vm_clone
virt-install	virt-install（virtinst）	vm_clone_system
qemu-img	qemu-img（qemu-utils）	vm_status、vm_clone、vm_clone_system、vm_import、vm_export、vm_destroy
guestfish	guestfs-tools（libguestfs-tools）	vm_clone（克隆的网络和 GRUB）
ssh、scp	openssh-clients（openssh-client）	vm_exec、vm_copy、vm_clone（克隆的主机名）
borg	borgbackup	backup_*、vm_export
timeshift	timeshift	backup_*、vm_clone_system
rsync	rsync	backup_create、backup_list、backup_restore、vm_clone_system
nmap（可选）	nmap	vm_verify、vm_clone（在没有来宾 Agent 时搜索 IP）
Node.js >= 18	nodejs	MCP 服务

VM 的 SSH 主机密钥保存在 $XDG_STATE_HOME/fedora-agents/known_hosts（默认路径为 ~/.local/state/fedora-agents/known_hosts）：首次连接时接受密钥，拒绝已更改的密钥。

npm install
npm run build

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

Claude Code 或 Claude Desktop 的 MCP 配置说明见 一行安装一节。

Lyra 生态系统的一部分

仓库	作用
lyra	法语优先的语音助手：语音 DevOps 助手，默认本地运行（AGPL-3.0）；它会先通过规则理解口语法语，再调用模型，因此使用 0.5B 模型就足够
fedora-agents	MCP：KVM 虚拟机和备份
mcp-tracking	MCP + API + 长时任务仪表板
neutroncore	homelab 的 PWA 中枢
hue-mcp	Philips Hue MCP（由 ThomasRohde/hue-mcp 分叉而来）
pylips-mcp	Philips TV MCP
denon-mcp	Denon 功放 MCP
catt-mcp	Chromecast 和 DLNA MCP