Coreflux MQTT MCP服务器

![License](https://opensource.org/licenses/Apache-2.0) ![Python](https://www.python.org/downloads/) ](https://www.docker.com/) ![Tests](https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server/actions) ![Code Quality](https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server)

一个企业级模型上下文协议（MCP）服务器，为Claude和其他兼容MCP的AI助手提供对Coreflux MQTT代理的安全、可扩展的访问以及全面的自动化功能。

🚀 特性

核心功能

🔌 MQTT集成：与Coreflux MQTT代理无缝连接，并提供完整的TLS支持
🛠️ 完整的Coreflux API：完全访问模型、操作、规则和路线
🤖 AI代码生成：通过Coreflux Copilot API生成LOT（物的语言）代码
🔍 动态发现：自动发现和列出可用操作
🏥 健康监测：全面的系统健康检查和监测

企业功能

🔒 生产安全：全面的日志清理、输入验证和安全功能
⚡ 异步处理：具有速率限制和队列管理的非阻塞消息处理
� 增强日志记录：具有轮换、过滤和安全净化功能的结构化日志记录
✅ 配置验证：全面的环境和文件验证系统
🧪 测试框架：完整的单元测试套件，包括模拟和覆盖率报告

DevOps与部署

🐳 集装箱准备就绪：全面支持Docker和Kubernetes部署，并进行健康检查
🔄 CI/CD管道：GitHub Actions提供自动化测试、安全扫描和质量检查
📦 开发工具：预提交挂钩、代码格式化、linting和文档生成
⚙️ 轻松设置：具有验证和测试功能的交互式设置助手
📚 丰富的文档：API文档、安全指南和部署说明

快速开始

Docker部署（推荐）

克隆和配置:

   git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
   cd Coreflux-MQTT-MCP-Server
   cp .env.example .env
   # Edit .env with your configuration

使用Docker进行部署:

   docker-compose up -d

🚀 快速开始

先决条件

Python 3.11或更高版本
Docker（可选，用于容器化部署）
访问Coreflux MQTT代理
Coreflux Copilot API密钥（可选，用于人工智能辅助）

选项1:Docker部署（推荐）

克隆和配置:

   git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
   cd Coreflux-MQTT-MCP-Server
   cp .env.example .env
   # Edit .env with your configuration

使用Docker进行部署:

   docker-compose up -d

验证部署:

   docker-compose logs -f coreflux-mcp-server

选项2：开发安装

克隆和设置:

   git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
   cd Coreflux-MQTT-MCP-Server

安装依赖项:

   pip install -r requirements.txt
   # For development
   pip install -r requirements-dev.txt

配置环境:

   python setup_assistant.py  # Interactive configuration
   # OR
   cp .env.example .env && nano .env  # Manual configuration

验证和测试:

   make validate  # Validate configuration
   make test      # Run tests

启动服务器:

   python server.py
   # OR
   make run

有关详细的部署说明，请参阅部署.md.

⚙️ 配置

交互式设置助手

服务器包括一个全面的设置助手，可指导您完成配置：

python setup_assistant.py

助理协助：

🔧 MQTT代理连接设置
🔐 TLS证书配置
🤖 Coreflux Copilot API集成
📝 日志记录和监控设置
✅ 配置验证和测试

在以下情况下使用设置助手：

创建初始配置
更新现有设置
解决连接问题
设置TLS证书
在环境之间迁移

环境配置

复制 .env.example 向 .env 并配置：

# MQTT Broker Configuration
MQTT_BROKER=your-broker-host.com
MQTT_PORT=8883
MQTT_USER=your-username
MQTT_PASSWORD=your-password
MQTT_USE_TLS=true

# TLS Configuration (when MQTT_USE_TLS=true)
MQTT_CA_CERT=/path/to/ca.crt
MQTT_CERT_FILE=/path/to/client.crt  
MQTT_KEY_FILE=/path/to/client.key

# Coreflux Copilot API
DO_AGENT_API_KEY=your-api-key-here

# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=/var/log/coreflux-mcp.log

有关详细的配置选项，请参阅配置指南.

🔌 将Claude连接到MCP服务器

使用克劳德桌面

找到Claude Desktop配置文件:

- macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json

添加服务器配置:

   {
     "mcpServers": {
       "coreflux": {
         "command": "python",
         "args": ["/path/to/your/server.py"],
         "env": {
           "MQTT_BROKER": "your-broker-host.com",
           "MQTT_PORT": "8883",
           "MQTT_USER": "your-username", 
           "MQTT_PASSWORD": "your-password",
           "MQTT_USE_TLS": "true",
           "DO_AGENT_API_KEY": "your-copilot-api-key"
         }
       }
     }
   }

重新启动克劳德桌面

安全说明：对于生产部署，将机密存储在安全的环境变量或机密管理系统中，而不是Claude配置文件中。

使用环境变量

为了更好的安全性，使用环境变量而不是硬编码凭据：

{
  "mcpServers": {
    "coreflux": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "MQTT_BROKER": "${COREFLUX_MQTT_BROKER}",
        "MQTT_PORT": "${COREFLUX_MQTT_PORT}",
        "MQTT_USER": "${COREFLUX_MQTT_USER}",
        "MQTT_PASSWORD": "${COREFLUX_MQTT_PASSWORD}",
        "DO_AGENT_API_KEY": "${COREFLUX_API_KEY}"
      }
    }
  }
}

测试连接

配置后，通过询问Claude来测试连接：

Can you check the health of the Coreflux MCP server and show me the broker information?

如果连接成功，Claude应返回系统状态和代理详细信息。

🛠️ 可用工具

服务器为Claude提供以下工具：

核心MQTT工具

publish_to_coreflux -使用QoS和保留选项将消息发布到MQTT主题
get_broker_info -获取有关MQTT代理连接的详细信息

AI辅助工具

copilot_assist -查询Coreflux Copilot AI以获得自动化辅助和代码生成

系统管理工具

comprehensive_health_check -对所有系统组件进行详细的健康检查

有关API的详细文档，请参阅 API_DOCUMENTATION.md.

🧪 开发与测试

开发设置

安装开发依赖项:

   pip install -r requirements-dev.txt

安装预提交挂钩:

   pre-commit install

运行完整的开发设置:

   make dev-setup  # Complete development environment setup

测试

运行综合测试套件：

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run specific test categories
make test-unit        # Unit tests only
make test-integration # Integration tests only

代码质量

使用自动化工具保持代码质量：

# Format code
make format

# Run linters
make lint

# Security scanning
make security-check

# Type checking
make type-check

# Run all quality checks
make quality-check

可用的开发命令：

# Development workflow
make dev-setup     # Set up complete development environment
make validate      # Validate configuration and environment  
make run           # Start the server with validation
make run-debug     # Start server in debug mode

# Testing and validation
make test          # Run all tests
make test-coverage # Run tests with coverage report
make test-unit     # Run unit tests only
make validate-config # Validate configuration files

# Code quality
make format        # Format code with black and isort
make lint          # Run all linters (flake8, bandit, mypy)
make security-check # Run security scanning
make type-check    # Run type checking with mypy

# Docker operations  
make docker-build  # Build Docker image
make docker-run    # Run in Docker container
make docker-test   # Run tests in Docker

# Documentation
make docs          # Generate documentation
make docs-serve    # Serve documentation locally

🔧 系统架构

核心组件

server.py -主MCP服务器及其工具实现
config_validator.py -配置验证和环境检查
message_processor.py -具有速率限制的异步MQTT消息处理
enhanced_logging.py -带轮换和安全过滤的结构化日志记录
config_schema.py -用于类型安全配置的Pydantic模式
parser.py -净化和解析实用程序

安全功能

输入消毒 -所有输入都经过消毒，以防止注射攻击
日志安全 -日志中敏感数据的自动清理
TLS支持 -MQTT连接的完全TLS加密
配置验证 -全面验证所有配置参数
秘密管理 -凭证和API密钥的安全处理

性能特点

异步处理 -无阻塞消息处理
连接池 -高效的MQTT连接管理
速率限制 -可配置的速率限制，以防止滥用
健康监测 -实时健康检查和系统监控

📚 文档

API文档 -完整的API参考
部署指导 -生产部署说明
秘密管理 -安全和秘密管理指南
配置参考 -完整的配置选项

🐳 Docker部署

Docker快速入门

# Clone and configure
git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
cd Coreflux-MQTT-MCP-Server

# Copy and edit environment file
cp .env.example .env
nano .env  # Configure your settings

# Start with Docker Compose
docker-compose up -d

# Check logs
docker-compose logs -f coreflux-mcp-server

# Health check
docker-compose exec coreflux-mcp-server python -c "
import os
os.system('python server.py --health-check')
"

生产Docker部署

看部署.md 了解全面的生产部署说明，包括：

多阶段Docker构建
Kubernetes部署
健康检查和监测
负载平衡和扩展
安全配置

🔑 Coreflux副驾驶集成

服务器通过Coreflux Copilot API提供强大的人工智能帮助：

设置

获取API密钥 从Coreflux Copilot仪表板
配置密钥:

   # Option 1: Environment file
   echo "DO_AGENT_API_KEY=your_api_key_here" >> .env

   # Option 2: Environment variable
   export DO_AGENT_API_KEY=your_api_key_here

特性

LOT代码生成 -从自然语言生成事物语言代码
自动化辅助 -获取Coreflux自动化任务的帮助
最佳实践 -获得最佳实施的指导
故障排除 -获得调试和优化方面的帮助

使用示例

请Claude帮助Coreflux自动化：

Generate LOT code for a temperature monitoring system that triggers an alert when the temperature exceeds 75°F

Help me create a rule that processes sensor data and stores it in a database

🚀 高级功能

异步消息处理

服务器包括一个强大的异步消息处理器，它：

防止堵塞 -在不阻塞主线程的情况下处理消息
速率限制 -可配置的限制，防止系统过载
队列管理 -带背压的智能队列处理
统计 -实时处理指标和监控

增强型测井系统

具有企业功能的全面日志记录：

结构化日志记录 -JSON格式的日志，便于解析
日志轮转 -自动轮换日志文件以管理磁盘空间
安全过滤 -敏感信息的自动净化
多个输出 -控制台、文件和syslog支持

配置验证

强大的验证系统，检查：

环境变量 -验证所有必需的配置
文件权限 -确保证书文件可访问
网络连接 -测试MQTT代理连接
API可用性 -验证Copilot API访问

🛡️ 安全与合规

安全功能

输入消毒 -所有输入都经过验证和消毒
TLS加密 -MQTT连接的完全TLS支持
秘密管理 -安全的凭证处理
审计日志 -全面的安全事件记录
非根执行 -以最低权限运行

合规支持

服务器支持各种合规要求：

SOC 2 -安全控制和监控
GDPR 数据保护 -数据保护和隐私
健康保险流通与责任法案 -医疗保健数据保护（正确配置时）

有关详细的安全信息，请参阅机密_管理.md.

📊 监测和健康检查

健康检查工具

全面的健康监测 comprehensive_health_check 工具：

# Manual health check
python server.py --health-check

# Or ask Claude:
# "Please run a comprehensive health check on the Coreflux MCP server"

监控指标

服务器提供详细的指标：

连接状态 -MQTT代理连接
消息处理 -队列大小和处理速率
系统资源 -内存和CPU使用率
错误率 -失败的操作和错误统计
API状态 -Copilot API可用性和响应时间

告警

为以下对象配置警报：

连接失败
错误率高
资源枯竭
安全事件

🤝 贡献

我们欢迎捐款！请参阅我们的贡献指南：

开发过程

分叉存储库
创建特征分支： git checkout -b feature/amazing-feature
安装开发依赖关系： pip install -r requirements-dev.txt
设置预提交挂钩： pre-commit install
制造您通过测试所做的更改
跑质量检查： make quality-check
提交您的更改： git commit -am 'Add amazing feature'
推到分行： git push origin feature/amazing-feature
创建拉取请求

代码规范

Python 3.11+ 兼容性
键入提示 适用于所有功能
综合测试 覆盖率>90%
安全扫描 与土匪
代码格式化 黑色和isort
文档适用于所有公共API

📄 许可证

此项目根据Apache许可证2.0获得许可-请参阅许可证文件以获取详细信息。

🆘 支持和故障排除

常见问题

连接被拒绝

Error: MQTT connection failed

检查代理主机名和端口
验证网络连接
确认TLS配置

认证失败

Error: Authentication failed

验证用户名/密码
检查API密钥的有效性
确认经纪人权限

TLS握手失败

Error: TLS handshake failed

验证证书路径
检查证书有效性
确认TLS版本兼容性

调试模式

启用详细日志以进行故障排除：

export LOG_LEVEL=DEBUG
python server.py

获取帮助

GitHub问题: 报告错误和请求功能
讨论: 社区支持和问题
文档: 完整的文件
安全问题：报告给security@coreflux.org

🗺️ 路线图

当前状态：v1.0.0✅

✅ 核心MQTT功能
✅ Copilot API集成
✅ 企业安全功能
✅ 综合测试
✅ 生产部署支持

即将推出的功能

v1.1.0版本 -增强的监控和指标
v1.2.0版本 -其他Coreflux API终点
v1.3.0版本 -WebSocket支持实时数据
v2.0.0版本 -多代理支持和联盟

______________________________________________________________________

📋 快速参考

基本命令

# Setup and configuration
python setup_assistant.py    # Interactive setup
make validate                 # Validate configuration

# Development
make dev-setup               # Complete dev environment
make test                    # Run all tests
make quality-check           # Run all quality checks

# Deployment
docker-compose up -d         # Docker deployment
make docker-build           # Build Docker image

# Monitoring
make health-check           # System health check
docker-compose logs -f      # View logs

关键文件

server.py -主MCP服务器
.env -配置文件
requirements.txt -Python依赖关系
docker-compose.yml -Docker部署
Makefile -开发命令

______________________________________________________________________

内置于❤️ Coreflux社区

remove_action：删除动作事件/函数
run_action：运行操作事件/函数
remove_all_models：删除所有模型
remove_all_actions：删除所有操作
remove_all_routes：删除所有路线
list_discovered_actions：列出所有发现的Coreflux操作
request_lot_code：基于自然语言提示，使用Coreflux Copilot API生成LOT代码

调试和故障排除

现在，即使MQTT代理不可用，MCP服务器也会启动，允许您通过MCP工具对连接进行故障排除和配置。

连接状态和恢复

即使无法访问MQTT代理，服务器也会成功启动
使用 get_connection_status 用于检查连接健康状况并获取故障排除指导的工具
使用 setup_mqtt_connection 无需重新启动即可配置新代理连接的工具
使用 check_broker_health 或 reconnect_mqtt 用于测试和重试连接的工具

可用的连接管理工具

get_connection_status：通过故障排除指南获取详细的连接状态
setup_mqtt_connection：动态配置新的MQTT代理连接
mqtt_connect：使用自定义参数连接到特定的MQTT代理
check_broker_health：测试代理连接并尝试重新连接
reconnect_mqtt：强制重新连接到配置的代理

传统故障排除步骤

如果您遇到问题：

在Claude配置中验证MQTT代理凭据
确保代理可访问
运行安装助手以验证或更新您的配置：

   python setup_assistant.py

检查克劳德桌面日志：

   # Check Claude's logs for errors (macOS/Linux)
   tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
   # Windows PowerShell
   Get-Content -Path "$env:USERPROFILE\AppData\Roaming\Claude\Logs\mcp*.log" -Tail 20 -Wait

使用调试日志运行服务器：

   # Direct execution with debug logging
   python server.py --mqtt-host localhost --mqtt-port 1883 --log-level DEBUG

参考文献和文件

部署.md -生产部署指南
安全.md -安全准则和最佳做法
MCP文件 -MCP官方文件
Coreflux平台 -Coreflux自动化平台

贡献

欢迎投稿！请阅读我们的投稿指南，并向 development 支。

许可证

此项目根据Apache许可证2.0获得许可-请参阅许可证文件以获取详细信息。

支持

📖 文档：检查README、DEPLOYMENT.md和SECURITY.md文件
🐛 问题：在GitHub上报告错误和功能请求
💬 社区：加入Coreflux社区进行讨论

Coreflux MQTT MCP Server

快速接入

详细介绍

Coreflux MQTT MCP服务器

🚀 特性

核心功能

企业功能

DevOps与部署

快速开始

Docker部署（推荐）

🚀 快速开始

先决条件

选项1:Docker部署（推荐）

选项2：开发安装

⚙️ 配置

交互式设置助手

环境配置

🔌 将Claude连接到MCP服务器

使用克劳德桌面

使用环境变量

测试连接

🛠️ 可用工具

核心MQTT工具

AI辅助工具

系统管理工具

🧪 开发与测试

开发设置

测试

代码质量

🔧 系统架构

核心组件

安全功能

性能特点

📚 文档

🐳 Docker部署

Docker快速入门

生产Docker部署

🔑 Coreflux副驾驶集成

设置

特性

使用示例

🚀 高级功能

异步消息处理

增强型测井系统

配置验证

🛡️ 安全与合规

安全功能

合规支持

📊 监测和健康检查

健康检查工具

监控指标

告警

🤝 贡献

开发过程

代码规范

📄 许可证

🆘 支持和故障排除

常见问题

调试模式

获取帮助

🗺️ 路线图

当前状态：v1.0.0✅

即将推出的功能

📋 快速参考

基本命令

关键文件

调试和故障排除

连接状态和恢复

可用的连接管理工具

传统故障排除步骤

参考文献和文件

贡献

许可证

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP