openwrt-mcp-server

openwrt-mcp-server

openwrt-mcp-server は、OpenWrt と Linux エッジデバイス向けの Rust ベースの MCP スタイルのブリッジです。現在は、HTTP と MQTT を介して単一デバイスの JSON-RPC 制御インターフェースを提供しています。長期的には、Rust サーバーを OpenWrt の外部でも単独のフリート MCP サービスとして実行し、EdgePulse やその他のデバイスアダプターを通じて多数の OpenWrt デバイスを管理できるようにする予定です。

現在のデプロイモード：

• 1 台のデバイス向けの、OpenWrt または Linux 上で動作するコンパニオンプロセス。
• AI エージェントやオーケストレーションシステム向けのリモートブリッジエンドポイント。
• 将来的には、デバイスレジストリ、ルールベースのアクセス制御、マルチテナント分離を備えたスタンドアロンのフリートサーバー。

現在の機能

• warp を使用した HTTP API。
• rumqttc を使用した MQTT トランスポート。
• JSON-RPC 2.0 のリクエストおよびレスポンスエンベロープ。
• x-api-token ヘッダーによるトークン保護付き HTTP エンドポイント。
• 起動時検証を備えた TOML 設定。
• OpenWrt の ubus からの実際のコンテキスト収集と、/proc、/sys、ip -j からの Linux フォールバックデータ。
• サポート対象のデバイス操作に対する、許可リスト方式のコマンド実行。
• トランスポート、コマンド、コマンドのリスクメタデータ、コンテキストコレクターを確認する device.describe 機能イントロスペクション。
• 将来のモジュール向け拡張ポイントとなる、軽量なコマンドおよびコンテキストレジストリ。
• サービス、設定、HTTP、MQTT のイベントに対する構造化 JSON ログ。
• schema/ 配下にある、コマンドとコンテキストのペイロード用 JSON Schema ドキュメント。

プロジェクト構成

• src/context/collector.rs：デバイスのコンテキストを収集します。
• src/context/registry.rs：組み込みのコンテキストコレクターと拡張メタデータを宣言します。
• src/executor/command.rs：許可リストにあるコマンドをディスパッチします。
• src/executor/registry.rs：コマンド名、必須引数、リスクレベルを宣言します。
• src/http/routes.rs：認証付き HTTP JSON-RPC エンドポイントを公開します。
• src/mqtt/handler.rs：MQTT のサブスクリプション、ディスパッチ、レスポンスのパブリッシュを処理します。
• src/config/mod.rs：config.toml を読み込み、検証します。
• src/logging.rs：簡潔な JSON ログレコードを出力します。
• src/model/types.rs：共通のリクエスト／結果／コンテキスト型を定義します。
• schema/：ドキュメント化されたペイロード形式の JSON Schema ファイルを格納します。
• docs/edgepulse-integration-roadmap.md：EdgePulse、フリート、RBAC、マルチテナントの計画について説明します。

ビルドとテスト

cargo build --release
cargo test

OpenWrt にデプロイする場合は、OpenWrt SDK またはデバイスに適した musl ターゲットを使ってクロスコンパイルしてください。

設定

config.toml の例：

[mqtt]
broker = "mqtt://localhost:1883"
client_id = "openwrt-one"
username = "mcp-user"
password = "mcp-pass"
topic_prefix = "mcp/device/openwrt-one"

[http]
enable = true
listen_addr = "0.0.0.0"
port = 8080
token = "your-api-token"

現在、次の場合は検証により拒否されます：

• mqtt.broker、mqtt.client_id、または mqtt.topic_prefix が空の場合。
• MQTT トピックプレフィックスに + または # が含まれている場合。
• http.listen_addr が無効な場合。
• http.port = 0 の場合。
• HTTP が有効で、http.token が空の場合。

HTTP API

すべての HTTP エンドポイントには、次の指定が必要です：

x-api-token: <configured token>

現在のコンテキストを取得します：

curl -H 'x-api-token: change-me' \
  http://127.0.0.1:8080/api/context

サーバーの機能を確認します：

curl -H 'x-api-token: change-me' \
  http://127.0.0.1:8080/api/describe

許可リストにあるコマンドを実行します：

curl -H 'x-api-token: change-me' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"device.executeCommand","params":{"command":"get_context"},"id":"cmd-1"}' \
  http://127.0.0.1:8080/api/cmd

サポート対象の組み込みコマンドは src/executor/registry.rs で宣言されています。

MQTT API

コマンドトピック：

{topic_prefix}/cmd

レスポンストピック：

{topic_prefix}/resp

機能リクエストの例：

{
  "jsonrpc": "2.0",
  "method": "device.describe",
  "params": {},
  "id": "describe-1"
}

コマンドリクエストの例：

{
  "jsonrpc": "2.0",
  "method": "device.executeCommand",
  "params": {
    "command": "restart_interface",
    "args": {
      "interface": "wan"
    }
  },
  "id": "cmd-1"
}

スキーマ

スキーマファイルでは、想定されるペイロードを記述しています：

• schema/command.schema.json
• schema/context.schema.json

現在、実行時検証は型付きパース、コマンドの許可リスト、引数チェック、設定検証を通じて実装されています。完全な JSON Schema 検証は、将来のセキュリティ強化として計画されています。

EdgePulse との統合

openwrt-mcp-server は、リモート MCP ブリッジとして ../edgepulse と統合することを想定しています。EdgePulse は、テレメトリー、ポリシー、名前付きアクション、監査ログ、AI エージェントの会話状態について、引き続き OpenWrt ローカルの権威あるシステムである必要があります。この Rust サーバーは、リモートの HTTP／MQTT／MCP 向けリクエストを、利用可能な場合は EdgePulse のローカル API に変換します。

詳細な計画については、docs/edgepulse-integration-roadmap.md を参照してください。

ロードマップ

現在のベースライン：

• 単一デバイス向け HTTP/MQTT JSON-RPC ブリッジ。
• OpenWrt/Linux のコンテキスト収集。
• コマンドおよびコンテキストのレジストリ。
• device.describe によるイントロスペクション。
• 構造化 JSON ログ。
• 設定の検証。
• スキーマのドキュメント。

短期的な強化：

• 実行時の JSON Schema 検証。
• HTTP/MQTT リクエストおよびコマンド結果の永続的な監査ログ。
• edgepulse-ctl 用 EdgePulse クライアントアダプター、その後 ubus または Unix ソケットに対応。
• 利用可能な場合、直接実行する変更コマンドを、EdgePulse のポリシーで制御された名前付きアクションに置き換え。
• 初期の許可リストを超えるコマンドのサンドボックス化。
• リクエストのテストとデバッグ用 CLI ユーティリティ。

フリートの方向性：

• OpenWrt 外部でのスタンドアロン MCP サーバーモード。
• デバイスレジストリと明示的なターゲット選択。
• ユーザー、サービスアカウント、デバイス、メソッド、権限に対するルールベースのアクセス制御。
• テナントを考慮した設定、トークン、MQTT ルーティング、コンテキストキャッシュ、ポリシー、監査記録。
• マルチテナントのフリートサービス運用。

長期的な拡張：

• ダッシュボードとライブ運用向けの WebSocket トランスポート。
• テレメトリーメトリクスのストリーミングエンドポイント。
• 低帯域幅 MQTT 向けのコンテキスト差分圧縮。
• セキュアブートとシステム整合性のレポート。
• 定期的なコマンド実行に対応するスケジューラー。