unraid-management-agent

Unraid Management Agent

Unraid Management Agent は、Unraid サーバー上で動作し、次の3つのインターフェースを通じて、サーバーの状態と制御機能全体を公開するプラグインです。

インターフェース	エンドポイント	用途
MCP（Model Context Protocol）	http://<unraid-ip>:8043/mcp	AI エージェント — 126個のツール、5個のリソース、6個のプロンプト
REST API	http://<unraid-ip>:8043/api/v1	スクリプト、Custom GPT Actions、インテグレーション
WebSocket	ws://<unraid-ip>:8043/api/v1/ws	ライブイベントのストリーミング（ほぼリアルタイム）

基本原則： AI エージェントとして操作する場合は、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 を実行します。
• エージェントにはデフォルトで認証がありません。信頼できる 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を探す場合は、一覧をすべて取得する list_ ではなく、search_containers／search_vms を使用してください。
• 特定のサブシステムを確認する場合は、get_diagnostic_summary の情報を抽出するのではなく、専用の取得ツール（get_ups_status、get_gpu_metrics、get_zfs_pools、…）を使用してください。
• 時系列の履歴／メトリクスが必要な場合は、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 ツールを1回呼び出すだけで、すでに最新のキャッシュ値が返されます。

6. アドホックなチェーンではなく、プロンプトで診断する

エージェントには、よくある調査（ディスクの健全性、パフォーマンス、メンテナンス、アレイの状態、概要、トラブルシューティング）に適したツールを組み合わせる、6 つの組み込み診断プロンプトが用意されています。分析を一から作り直すのではなく、これらを優先してください。詳しくは references/diagnostics.md をご覧ください。

---

避けるべき重大なアンチパターン

アンチパターン	代わりに使うもの	理由
ツール名を独自に考案する（docker_restart、getArray）	references/mcp-tools.md に記載された正確な名前	名前が間違っていると失敗します
確認せずにアレイを停止したり、再起動したりする	状態を読み取り、影響を説明してから confirm=true を指定する	データ損失／ダウンタイムにつながります
GET /api/v1/system をループでポーリングする	MCP リソースまたは WebSocket ws://…/api/v1/ws	エージェントはすでにキャッシュしているため、ポーリングは CPU を無駄に消費します
list_containers を実行してからコンテキスト内でフィルタリングする	search_containers／get_container_info	コンテキストの消費が減り、高速かつ高精度です
ディスクの健全性分析を手作業で組み立てる	diagnose_disk_health プロンプト	組み込みプロンプトで SMART、温度、消耗度、エラーを確認できます
API キー／認証ヘッダーがあると決めつける	指示がない限り、認証のない LAN／VPN として扱う	デフォルトのデプロイでは認証がありません
MCP 対応クライアントから REST を使う	MCP ツール	引数が検証され、結果がより豊富で、往復回数も少なくなります
Unraid の設定ファイルを直接編集する	エージェントの制御ツール／設定エンドポイント	ツールは 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/コンテナー）、修復ランブック、オプションの自律型エージェント、ファン制御（プロファイル／カーブ）、 CPU ガバナー、システムのチューニング（ターボブースト、ディスクキャッシュ、inotify）。