金大哥 - mcpMQTT MCP 详情

article

README

🚀 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

配置示例

有关详细的配置示例，请参阅 examples/ 文件夹：

example_config.json - 包含多个主题模式的基本配置
example_with_logging.json - 启用文件日志的配置

📚 详细示例

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 文件。

mcpMQTT