unraid-management-agent

Unraid 管理 Agent

Unraid 管理 Agent 是一个运行于 Unraid 服务器上的插件，通过以下三个接口公开服务器的完整状态和控制功能：

接口	端点	用途
MCP（Model Context Protocol）	http://<unraid-ip>:8043/mcp	AI Agent — 125 个工具、5 个资源、6 个提示词
REST API	http://<unraid-ip>:8043/api/v1	脚本、Custom GPT Actions、集成
WebSocket	ws://<unraid-ip>:8043/api/v1/ws	实时事件流（近乎实时）

核心原则： 作为 AI Agent 执行操作时，优先使用 MCP 工具——这些工具专门构建、经过验证，并采用便于发现的名称。仅当客户端无法使用 MCP（例如 ChatGPT Custom GPT）时，才退而使用 REST API。切勿臆造工具名称或路径；实际目录见下方的参考文件。

决策工作流

1. 连接

如果客户端尚未连接，请阅读 references/connection.md。简而言之：

• Streamable HTTP（远程／LAN）： 将客户端指向 http://<unraid-ip>:8043/mcp。
• STDIO（服务器本地）： 运行 unraid-management-agent mcp-stdio。
• Agent 默认不启用身份验证——它面向受信任的 LAN，或 VPN／反向代理后方的环境。除非用户说明，否则不要假设存在 API 密钥。

2. 先读再写

执行操作前，始终先使用只读工具确认当前状态：

• 系统快照 → get_system_info，或使用 get_diagnostic_summary 获取概览
• 阵列 → get_array_status；磁盘 → list_disks / get_disk_info
• 容器 → list_containers / search_containers / get_container_info
• VM → list_vms / search_vms / get_vm_info

只读工具标记为 ReadOnlyHint: true。完整目录见 references/mcp-tools.md。

3. 选择最精简的工具

• 要在多个容器／VM 中查找某一个？使用 search_containers / search_vms，不要倾倒完整的 list_ 列表。
• 需要查看特定子系统？使用专用 getter（get_ups_status、get_gpu_metrics、get_zfs_pools，……），而不是从 get_diagnostic_summary 中抓取信息。
• 需要历史记录／时间序列指标？使用 query_metric_history、get_parity_history、get_alert_history、get_health_check_history。

4. 确认破坏性操作

控制工具（ReadOnlyHint: false）会更改系统。其中的高风险操作要求 confirm=true，且必须先向用户确认：

工具	影响
array_action（stop）	使所有阵列数据无法访问
system_reboot / system_shutdown	重启／关闭整个服务器
execute_user_script / run_runbook	执行任意用户定义的操作
delete_vm_snapshot / restore_vm_snapshot	不可逆的 VM 状态更改
delete_alert_rule / delete_health_check	移除配置
set_fan_speed / set_fan_mode	更改风扇转速／控制模式
set_fan_profile / create_fan_profile	更改温度曲线
restore_fan_defaults	将所有风扇控制重置为 BIOS 默认值
remote_share_action	挂载／卸载网络存储

注意： container_action（remove）和 vm_action（reset）仅在执行破坏性操作时由服务器端强制要求 confirm=true，因此只读取架构的客户端无法看到这一要求。

发送 confirm=true 前，始终说明将要发生的情况，并等待用户明确批准。完整的读／写分类见 references/mcp-tools.md。

5. 正确使用实时数据

对于持续变化的值（CPU、容器状态），不要紧密循环轮询 REST API。请使用 MCP 资源（references/diagnostics.md）或 WebSocket 数据流。一次 MCP 工具调用即可返回最新的缓存值。

6. 使用提示词诊断，而不是临时拼凑调用链

该 Agent 内置了 6 个诊断提示词，可为常见调查（磁盘健康、性能、维护、阵列状态、概览、故障排查）编排合适的工具。优先使用它们，而不是重新设计分析流程。请参阅 references/diagnostics.md。

---

关键反模式

反模式	改用	原因
臆造工具名称（docker_restart、getArray）	使用 references/mcp-tools.md 中的准确名称	名称错误只会导致调用失败
未经确认就停止阵列或重启	读取状态、说明影响，然后设置 confirm=true	可能导致数据丢失／停机
循环轮询 GET /api/v1/system	使用 MCP 资源或 WebSocket ws://…/api/v1/ws	Agent 已会缓存；轮询会浪费 CPU
调用 list_containers 后在上下文中筛选	使用 search_containers／get_container_info	占用更少上下文，速度更快，也更准确
手动编写磁盘健康分析	使用 diagnose_disk_health 提示词	内置提示词涵盖 SMART、温度、损耗和错误
假设需要 API 密钥／认证标头	除非另有说明，否则按未经身份验证的 LAN／VPN 处理	默认部署不启用身份验证
在支持 MCP 的客户端中使用 REST	使用 MCP 工具	参数经过验证，结果更丰富，往返次数更少
直接编辑 Unraid 配置文件	使用 Agent 的控制工具／设置端点	工具与 WebUI 自身的逻辑和验证相匹配

---

参考文件

需要详细信息时，请阅读以下文件。让 SKILL.md 保持在上下文中；按需加载参考文件。

文件	阅读时机
references/connection.md	通过 MCP HTTP／STDIO 连接任何客户端（Claude Code/Desktop、claude.ai、Cursor、Copilot、Gemini CLI、ChatGPT）；排查连接问题
references/mcp-tools.md	按类别分组的全部 125 个 MCP 工具目录，包含读／写（破坏性）标记和参数
references/diagnostics.md	6 个诊断提示词和 5 个实时资源——各自的分析内容及适用场景
references/rest-api.md	面向非 MCP 客户端（Custom GPT Actions、脚本）的 REST API 接口：基础路径、关键端点、路径／请求体约定
references/workflows.md	自然语言请求 → 工具／端点映射和端到端示例（监控、容器／VM／阵列控制、维护）

功能一览

• 监控（只读）： 系统、阵列、磁盘 + SMART、共享、Docker （容器、网络、统计数据、日志、更新检查）、VM + 快照、GPU、UPS、 NUT、ZFS（池／数据集／快照／ARC）、网络 + 访问 URL、硬件、 通知、校验历史、日志、采集器、设置、未分配设备、 远程 SMB/NFS 共享。
• 控制： 容器和 VM 生命周期、阵列启动／停止、校验启动／停止／暂停／恢复、 磁盘启动／停转、容器和插件更新、VM 快照创建／删除／恢复、VM 克隆、服务启动／停止／重启、用户脚本、采集器启用／禁用 + 间隔设置、重启／关机。
• 可观测性与自动化： 告警规则（expr-lang）+ 模板、健康检查（HTTP/TCP/容器）、 修复运行手册、可选的自主 Agent、风扇控制（配置文件／曲线）、CPU 调速器，以及系统调优（Turbo Boost、磁盘缓存、inotify）。