Mcpmqtt

🚀 MCP MQTT服務器

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：應用程序日誌級別

主題模式和權限

通配符支持：

• +：單級通配符（匹配一個主題級別）
• #：多級通配符（匹配多個級別，必須位於最後）

權限：

• 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操作工具：

mqtt_publish

向MQTT主題發佈消息。

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

mqtt_subscribe

訂閱主題並收集消息。

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

mqtt_read

訂閱一個主題並等待單條消息。

{
  "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代理上與其關聯的用戶所暴露的所有主題。你必須在MQTT代理上進行細粒度配置，以限制MCP實際可以訪問或操作的功能。

📄 許可證

請參閱 LICENSE.md 文件。