lancontrol

lancontrol

lancontrol は、単一のアクションルーターツールを通じて UniFi Network コントローラーの状態を取得します。接続中のクライアント、ネットワークデバイス、WLAN 設定、サイトのヘルス状態、アクティブなアラーム、最近のイベント、コントローラーのシステム情報、認証済みの ID が対象です。1 つのバイナリで、コマンドラインインターフェースと stdio MCP サーバーを提供します。

これはラベル付きのコアサブセットです。アップストリームの機能全体では、合計 267 個のアクションが定義されています。lancontrol が実装するのは、保持されている 8 個の便利なアクションと help のみです（アクション値は 9 個）。生成されたアクション群は、意図的に名前を挙げて省略しています。official_*（78 アクション）、unifi_*（175 アクション）、および 5 個のハイブリッドエイリアス（list_clients、list_devices、list_networks、list_wifi、get_system_info）です。

設定

help 以外のすべてのアクションでは、両方の変数が必須です。値が不足している場合、リクエストを行う前にエラーになります。

変数	必須	用途
UNIFI_URL	はい	コントローラーのベース URL。例：https://unifi.local。
UNIFI_API_KEY	はい	API キー。X-API-KEY ヘッダーで送信されます。
UNIFI_SITE	いいえ	UniFi のサイト名。既定値は default です。

API キーをツールの引数として渡さないでください。環境変数からのみ読み取られます。

インストール

npx @reneturcios/lancontrol help

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/lancontrol

コンテナーは既定で MCP サーバーとして起動します（下記を参照）。CLI として使用するには、CLI 引数を渡してください。

CLI

lancontrol clients
lancontrol devices
lancontrol wlans
lancontrol health
lancontrol alarms
lancontrol events --limit 25
lancontrol sysinfo
lancontrol me
lancontrol help

lancontrol --version

アクションコマンドは、アップストリームの JSON ペイロードを出力します。help はローカルのアクションドキュメントを出力し、設定もネットワーク接続も必要ありません。終了コード：成功時は 0、呼び出し失敗時（設定不足やアップストリーム API エラーを含む）は 1、使用法エラー時は 2 です。

MCP サーバー

1 つのバイナリで両方のインターフェースを提供します。mcp サブコマンドは stdio MCP サーバーを起動します。

npx -y @reneturcios/lancontrol mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "lancontrol": {
      "command": "npx",
      "args": ["-y", "@reneturcios/lancontrol", "mcp"],
      "env": {
        "UNIFI_URL": "https://unifi.local",
        "UNIFI_API_KEY": "...",
        "UNIFI_SITE": "default"
      }
    }
  }
}

ツール

公開されているツールは 1 つです。

ツール	入力	戻り値
unifi	action（必須、9 個のサブセット値のいずれか）、limit（省略可能な整数、events のみ）	選択したアクションのアップストリームペイロード、または help のローカルドキュメント。

アクション	説明
clients	接続中の無線および有線クライアント。
devices	ネットワークデバイス：AP、スイッチ、ゲートウェイ。
wlans	WiFi ネットワークの設定。
health	サイトのヘルス状態の概要。
alarms	アクティブなアラームと警告。
events	最近のコントローラーイベント。
sysinfo	コントローラーのシステム情報。
me	認証済みの UniFi ID。
help	組み込みのアクションドキュメント。

アップストリームのマッピング（ドキュメントに基づく再構成）

公開仕様ではアクション名が示されていますが、便利なアクションの表には、それぞれに対応するコントローラーパスが正確には記載されていません。そのため、各アクションは UNIFI_URL の下にある、妥当と考えられる文書化済みの UniFi 内部エンドポイントに対する GET として実装されています。X-API-KEY ヘッダーを使用します。

アクション	エンドポイント
clients	GET /proxy/network/api/s/{site}/stat/sta
devices	GET /proxy/network/api/s/{site}/stat/device
wlans	GET /proxy/network/api/s/{site}/rest/wlanconf
health	GET /proxy/network/api/s/{site}/stat/health
alarms	GET /proxy/network/api/s/{site}/stat/alarm
events	GET /proxy/network/api/s/{site}/stat/event（limit が指定された場合は ?_limit={limit} を追加）
sysinfo	GET /proxy/network/api/s/{site}/stat/sysinfo
me	GET /proxy/network/api/self
help	リクエストなし — ローカルで応答

HTTP エラーが発生すると、ステータスと、存在する場合はアップストリームのメッセージ（meta.msg、message、または error）が表示されます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。