unifi-network

UniFi Network MCP サーバー

依存関係

必須：network 任意：なし

データを収集する前に、MCP のディスカバリーを通じて必須ツールを確認してください。ディスカバリーだけでは、コントローラーへの接続や認可が確認されたことにはなりません。必須サーバーまたは必須ツールが見つからない場合、あるいは必須の読み取りに失敗した場合は、処理を中止して利用できないことを報告してください。任意のソースを省略できるのは、レポートに不足しているソースと、それによって生じるカバレッジの制限を明記する場合に限ります。接続に関するサポートには製品セットアップスキルを使用してください。秘密情報は要求しないでください。

カバレッジと制限事項

すべてのレポートに カバレッジと制限事項 セクションを含めてください。要求された各ソースとそのステータス（利用可能、利用不可、一部利用可能、または上限到達）、要求された時間範囲とタイムゾーン、または現在の状態を収集した時刻、実際に適用したフィルター、取得件数、制限、ページネーション、失敗した呼び出しや不明なフィールドを明記してください。件数は取得したレコード数を示し、完全性が確認されていない限り、総数を示すものではありません。正常に完了した空のクエリは観測結果です。失敗したソースや欠落したソースは利用不可であり、結果が空だったことを意味するものではありません。上限に達した場合、追加の範囲指定付き読み取りでカバレッジが確認されない限り、そのソースに上限到達のラベルを付けてください。完全性を確認できない場合は、一部利用可能のラベルを付けてください。利用不可、一部利用可能、または上限到達のデータに基づいて、カバレッジが完全であること、問題がないこと、または全体的な健全性を主張しないでください。適切な場合は、「取得したレコード内に懸念されるアクティビティは見つかりませんでした」と記載してください。

観測結果（利用可能な場合は、ソース／ツール、レコード ID、タイムスタンプを引用）、仮説（相関関係と別の説明）、ID 情報（ソースに明示的に裏付けられた認証情報／アカウントの帰属と、その制限のみ）を分けてください。タイミング、似た名前、近接性、または一致するイベントがないことだけでは、ID 情報も原因も証明できません。認証情報のイベントで特定できるのは記録されたアカウントであり、実際に操作した人物ではありません。マッピングの欠落や時刻の不確かさによって、相関関係には制限が生じます。

UniFi Network Controller の照会と管理を可能にする UniFi Network MCP サーバーを利用できます。このサーバーには、デバイス、クライアント、ファイアウォール、VPN、ルーティング、WLAN、Traffic Flows、統計などを扱う 210 個のツールが用意されています。

ツールの検出

このサーバーでは、デフォルトで 遅延読み込み が使用され、最初はメタツールのみが登録されます。これらを使って、任意のツールを検索して呼び出してください。

メタツール	目的
unifi_tool_index	名前または説明でツールを検索します。category、search、include_schemas を使って絞り込めます
unifi_execute	名前を指定して任意のツールを呼び出します（遅延読み込みモードでは必須）
unifi_batch	複数のツールを並列で実行します
unifi_batch_status	非同期バッチジョブのステータスを確認します

ワークフロー： unifi_tool_index を呼び出して適切なツールを見つけ、その後 unifi_execute で呼び出します。独立したクエリを複数実行する場合は、unifi_batch を使用してください。逐次呼び出しより大幅に高速です。

安全モデル

このサーバーは実際のネットワークインフラストラクチャを制御するため、「デフォルトで安全」です。

読み取り操作 — 常に利用できます。すべての list_*、get_*、クエリツールは、特別な権限がなくても動作します。

変更操作 — 権限によって制御され、デフォルト設定は操作によって異なります。

• デフォルトで有効： ファイアウォールポリシー、ポートフォワード、トラフィックルート、QoS ルール、VPN クライアント、ACL ルール、バウチャー、ユーザーグループ
• デフォルトで無効（高リスク）： ネットワーク、WLAN、デバイス、クライアント、ルート、VPN サーバー
• 削除操作 — 常にデフォルトで無効です

変更操作が権限エラーで失敗した場合、設定すべき環境変数をユーザーに伝えてください：UNIFI_POLICY_NETWORK_<CATEGORY>_<ACTION>=true。エラーに記載された変数をそのまま使用してください。<CATEGORY> はサーバーの設定キー（CLIENT_GROUPS、FIREWALL_POLICIES、OON_POLICIES）であり、tools_manifest.json の permission_category の省略表記（client_group、firewall、oon_policy）ではありません。省略表記から組み立てた変数は読み取られません。

確認フロー — すべての変更操作は、プレビューしてから確定します。

1. デフォルトの呼び出し → 変更内容のプレビューを返します
2. confirm=true を指定して呼び出す → 変更を実行します

必ず最初にプレビューし、確定する前にユーザーに提示してください。

応答形式

すべてのツールは、{"success": true, "data": ...}、{"success": false, "error": "..."}、または {"success": true, "requires_confirmation": true, "preview": ...} を返します。必ず最初に success を確認してください。ネットワーク／WLAN と VPN 状態への書き込みは、実行後に読み戻しが行われ、mutation_applied、partial_success、persisted_fields、unchanged_fields、dropped_fields、coerced_fields および書き込み後の実際の詳細も報告されます。すでに満たされているため変更されなかったフィールドは unchanged_fields に表示され、書き込みの部分的な失敗とは見なされません。確認後に実行した書き込みが失敗しても、必ずしもロールバックされたとは限りません。再試行または補償処理を行う前に、これらのフィールドを確認してください。

秘匿されたシークレット： シークレットフィールド（WLAN パスフレーズ（x_passphrase）、VPN 秘密鍵／事前共有鍵、VPN 設定全体を格納したファイル（インポートされた WireGuard／OpenVPN 設定ファイル）、SNMP コミュニティ文字列、SNMPv3 パスワード、デバイスの SSH 認証情報）は、デフォルトで ***REDACTED*** として返されます。生の値はプロセスのポリシー（UNIFI_NETWORK_REDACT_SENSITIVE_FIELDS=false またはグローバル設定の UNIFI_REDACT_SENSITIVE_FIELDS=false）によって制御され、ツールの引数では制御されません。更新時は、変更するフィールドのみを送信してください。シークレットを変更せずに維持するには、そのフィールドを省略してください。***REDACTED*** をそのまま送り返してはいけません。プレースホルダーが実際のシークレットを上書きしないよう、拒否されます。