Mcpmqtt

🚀 MCP MQTT Server

MCP（モデルコンテキストプロトコル）サーバーです。このサーバーは、発見可能なインターフェースを通じて、LLMエージェントパイプラインにMQTT操作を提供します。サーバーはワイルドカードマッチングによる細粒度のトピック権限をサポートし、MCPクライアントに包括的なMQTT機能を提供します。

✨ 主な機能

• MCPサーバーインターフェース：MQTT操作のためのMCPサーバー実装
• トピック権限：MQTTワイルドカード（+ と #）をサポートする細粒度の読み取り/書き込み権限
• 認証：MQTTブローカーの認証サポート
• 発見可能：トピックの発見とサンプルのためのMCPリソース
• 設定可能：スキーマ検証付きのJSONベースの設定
• 非同期サポート：非ブロッキング操作のための完全な非同期/待機サポート

🏗️ アーキテクチャ

┌─────────────────┐    ┌──────────────────────────────────┐
│   MCP Client    │    │         mcpMQTT Application      │
│                 │    │                                  │
│  ┌───────────┐  │    │  ┌─────────────┐                 │
│  │   Agent   │  │◄──►│  │ MCP Server  │                 │
│  └───────────┘  │    │  └─────────────┘                 │
└─────────────────┘    │         │                        │
                       │  ┌─────────────────────────────┐ │
┌─────────────────┐    │  │   Topic Permission Manager  │ │
│  MQTT Broker    │◄──►│  └─────────────────────────────┘ │
└─────────────────┘    │         │                        │
                       │  ┌─────────────┐                 │
                       │  │ MQTT Client │                 │
                       │  │  Manager    │                 │
                       │  └─────────────┘                 │
                       └──────────────────────────────────┘

📦 インストール

pip install mcpMQTT

⚙️ 設定

設定ファイルの構造

設定ファイルを ~/.config/mcpmqtt/config.json に作成するか、コマンドラインでユーティリティを起動する際に --config パラメータを使用してカスタムパスを指定します。

{
  "mqtt": {
    "host": "localhost",
    "port": 1883,
    "username": null,
    "password": null,
    "keepalive": 60
  },
  "topics": [
    {
      "pattern": "sensors/+/temperature",
      "permissions": ["read"],
      "description": "Temperature sensor data from any location (+ matches single level like 'room1', 'room2'. Known rooms are 'exampleroom1' and 'exampleroom2'). Use subscribe, not read on this topic. Never publish."
    },
    {
      "pattern": "sensors/+/humidity",
      "permissions": ["read"],
      "description": "Humidity sensor data from any location. (+ matches single level like 'room1', 'room2'. Known rooms are 'exampleroom1' and 'exampleroom2'). Use subscribe, not read on this topic. Never publish. Data returned as %RH"
    },
    {
      "pattern": "actuators/#",
      "permissions": ["write"],
      "description": "All actuator control topics (# matches multiple levels like 'lights/room1'. To enable a light you write any payload to 'lights/room1/on', to disable you write to 'lights/room1/off')"
    },
    {
      "pattern": "status/system",
      "permissions": ["read"],
      "description": "System status information - exact topic match"
    },
    {
      "pattern": "commands/+/request",
      "permissions": ["write"],
      "description": "Command request topics for request/response patterns"
    },
    {
      "pattern": "commands/+/response",
      "permissions": ["read"],
      "description": "Command response topics for request/response patterns"
    }
  ],
  "logging": {
    "level": "INFO",
    "logfile": null
  }
}

設定セクション

• mqtt：MQTTブローカーの接続設定
• topics：権限と説明付きのトピックパターン
• logging：アプリケーションのログレベル

トピックパターンと権限

ワイルドカードサポート:

• +：単一レベルのワイルドカード（1つのトピックレベルに一致）
• #：複数レベルのワイルドカード（複数のレベルに一致、最後に置く必要があります）

権限:

• read：トピックを購読し、メッセージを受信できます
• write：トピックにメッセージを公開できます
• 両方の権限を組み合わせることができます：["read", "write"]

例:

• sensors/+/temperature は sensors/room1/temperature、sensors/kitchen/temperature に一致します
• actuators/# は actuators/lights、actuators/lights/room1/brightness に一致します
• status/system は status/system と正確に一致します

💻 使用例

MCPサーバーの実行

インストールされたスクリプトを使用する場合:

mcpMQTT

または、モジュールを直接使用する場合:

python -m mcpMQTT.app.mcp_server

カスタム設定を使用する場合:

mcpMQTT --config /path/to/config.json --log-level DEBUG
# または
python -m mcpMQTT.app.mcp_server --config /path/to/config.json --log-level DEBUG

MCPツール

MCPサーバーは、MQTT操作のための3つのツールを提供します。

mqtt_publish

MQTTトピックにメッセージを公開します。

{
  "topic": "sensors/room1/temperature",
  "payload": "22.5",
  "qos": 0
}

mqtt_subscribe

トピックを購読し、メッセージを収集します。

{
  "topic": "sensors/+/temperature",
  "timeout": 30,
  "max_messages": 5
}

mqtt_read

トピックを購読し、1つのメッセージを待ちます。

{
  "topic" : "sensors/+/temperature",
  "timeout" : 5
}

mqtt_query

MQTT通信のためのリクエスト/レスポンスパターン。

{
  "request_topic": "commands/room1/request",
  "response_topic": "commands/room1/response",
  "payload": "get_status",
  "timeout": 5
}

MCPリソース

mcpmqtt://topics/allowed

権限と説明付きの許可されたトピックパターンを取得します。

mcpmqtt://topics/examples

ワイルドカードを使用したトピックパターンの使用例を取得します。

🛠️ 開発

プロジェクト構造

mcpMQTT/
├── app/
│   ├── __init__.py
│   ├── mcp_server.py        # MCPサーバーの実装とエントリーポイント
│   └── mqtt_client.py       # 拡張されたMQTTクライアントマネージャー
├── config/
│   ├── config_manager.py    # 設定の読み込みと検証
│   ├── schema.py           # Pydanticモデルと検証
│   ├── example_config.json # サンプル設定ファイル
│   └── example_with_logging.json # ログ設定付きのサンプル
├── examples/
│   ├── example_config.json        # 基本的な設定例
│   └── example_with_logging.json  # ファイルログを有効にした設定
├── pyproject.toml
├── LOGGING_USAGE.md        # 詳細なログドキュメント
└── README.md

設定例

詳細な設定例については、 フォルダを参照してください。

• - 複数のトピックパターンを持つ基本的な設定
• - ファイルログを有効にした設定

🌟 サンプル

MCPクライアントの統合

このMCPサーバーは stdio プロトコルを使用します。これは、LLMオーケストレーターによって起動される必要があることを意味します。

典型的な設定（mcp.json）は次のようになります。

{
  "mcpServers": {
    "mqtt": {
      "command": "mcpMQTT",
      "args": [
        "--config /usr/local/etc/mcpMQTT.conf"
      ],
      "env": {
        "PYTHONPATH": "/just/an/example/path/"
      },
      "timeout": 300,
      "alwaysAllow": [
        "mqtt_read"
      ]
    }
  }
}

🔒 セキュリティに関する考慮事項

このMCPは、エージェントがMQTTブローカー上で関連付けられたユーザーに公開されているすべてのトピックを購読および公開できることに注意してください。MCPが実際にアクセスまたは操作できる機能を制限するために、MQTTブローカーで細粒度の設定を行う必要があります。

📄 ライセンス

詳細は LICENSE.md を参照してください。