unraid-management-agent

Unraid Management Agent

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

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

基本原則： AI エージェントとして操作する場合は、MCP ツールを優先してください。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 を実行します。
• このエージェントには、デフォルトで認証はありません。信頼できる 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（停止）	アレイ上のすべてのデータにアクセスできなくなります
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（削除）と vm_action（リセット）は、破壊的な操作に限ってサーバー側で 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	読み取り／書き込み（破壊的操作）フラグと引数を含む、カテゴリ別にまとめられた全 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／コンテナー）、 修復ランブック、オプションの自律型エージェント、ファン制御（プロファイル／カーブ）、 CPU ガバナー、システムのチューニング（ターボブースト、ディスクキャッシュ、inotify）。