McpMQTT

管理 Python

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

0 条评论
分类：管理