unraid-management-agent

Unraid 管理 Agent

Unraid Management Agent 是一个运行在 Unraid 服务上的插件，通过三个接口公开其完整状态和控制功能：

接口	端点	用途
MCP（Model Context Protocol）	http://<unraid-ip>:8043/mcp	AI Agent — 126 个工具、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 GPTs）时，才退而使用 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	完整的 126 个 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）。