星战科技xingzhan.cloud
返回市场
核心流MCP服务器

核心流MCP服务器

作者：CorefluxCommunity3 星标更新：2025-08-01
安装使用来源：spider==github.com

项目介绍

技术文档摘要

Coreflux MQTT MCP 服务器

License Python Docker Tests Code Quality

一款企业级模型上下文协议（MCP）服务器，提供安全、可扩展的访问到Coreflux MQTT代理，并为Claude和其他兼容MCP的人工智能助手提供了全面的自动化能力。

🚀 功能特性

核心功能

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

企业功能

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

DevOps与部署

  • 🐳 容器就绪：完整的Docker和Kubernetes部署支持，带健康检查
  • 🔄 CI/CD流水线：GitHub Actions，带自动测试、安全扫描和质量检查
  • 📦 开发工具：预提交钩子、代码格式化、linting和文档生成
  • ⚙️ 简易设置：交互式设置助手，带验证和测试
  • 📚 丰富的文档：API文档、安全指南和部署说明

快速开始

Docker部署（推荐）

  1. 克隆并配置：

    git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
cd Coreflux-MQTT-MCP-Server
cp .env.example .env
# 编辑.env以进行您的配置

  2. 使用Docker部署：

    docker-compose up -d

🚀 快速开始

先决条件

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

方案1：Docker部署（推荐）

  1. 克隆并配置：

    git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
cd Coreflux-MQTT-MCP-Server
cp .env.example .env
# 编辑.env以进行您的配置

  2. 使用Docker部署：

    docker-compose up -d

  3. 验证部署：

    docker-compose logs -f coreflux-mcp-server

方案2：开发安装

  1. 克隆并设置：

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

  2. 安装依赖项：

    pip install -r requirements.txt
# 对于开发
pip install -r requirements-dev.txt

  3. 配置环境：

    python setup_assistant.py  # 交互式配置
# 或者
cp .env.example .env && nano .env  # 手动配置

  4. 验证和测试：

    make validate  # 验证配置
make test      # 运行测试

  5. 启动服务器：

    python server.py
# 或者
make run

详细的部署说明，请参阅DEPLOYMENT.md。

⚙️ 配置

交互式设置助手

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

python setup_assistant.py

助手帮助您：

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

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

  • 创建初始配置
  • 更新现有设置
  • 排查连接问题
  • 设置TLS证书
  • 在不同环境中迁移

环境配置

复制.env.example到.env并进行配置：

# MQTT代理配置
MQTT_BROKER=your-broker-host.com
MQTT_PORT=8883
MQTT_USER=your-username
MQTT_PASSWORD=your-password
MQTT_USE_TLS=true

# TLS配置（当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

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=/var/log/coreflux-mcp.log

详细的配置选项，请参阅配置指南。

🔌 将Claude连接到MCP服务器

使用Claude桌面

  1. 定位Claude桌面配置文件：

    • macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json

  2. 添加服务器配置：

    {
  "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"
      }
    }
  }
}

  3. 重启Claude桌面

安全提示：对于生产部署，将秘密存储在安全的环境变量或秘密管理系统中，而不是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来测试连接：

你能检查Coreflux MCP服务器的健康状况并向我展示代理信息吗？

如果连接成功，Claude应该会回复系统状态和代理详情。

🛠️ 可用工具

服务器向Claude提供了以下工具：

核心MQTT工具

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

AI辅助工具

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

系统管理工具

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

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

🧪 开发与测试

开发设置

  1. 安装开发依赖项：

    pip install -r requirements-dev.txt

  2. 安装预提交钩子：

    pre-commit install

  3. 运行完整的开发设置：

    make dev-setup  # 完整的开发环境设置

测试

运行全面的测试套件：

# 运行所有测试
make test

# 运行带有覆盖率的测试
make test-coverage

# 运行特定测试类别
make test-unit        # 仅单元测试
make test-integration # 仅集成测试

代码质量

使用自动化工具维护代码质量：

# 格式化代码
make format

# 运行linters
make lint

# 安全扫描
make security-check

# 类型检查
make type-check

# 运行所有质量检查
make quality-check

可用的开发命令：

# 开发工作流
make dev-setup     # 设置完整的开发环境
make validate      # 验证配置和环境
make run           # 带验证启动服务器
make run-debug     # 在调试模式下启动服务器

# 测试和验证
make test          # 运行所有测试
make test-coverage # 运行带有覆盖率报告的测试
make test-unit     # 仅运行单元测试
make validate-config # 验证配置文件

# 代码质量
make format        # 使用black和isort格式化代码
make lint          # 运行所有linters（flake8，bandit，mypy）
make security-check # 运行安全扫描
make type-check    # 使用mypy进行类型检查

# Docker操作
make docker-build  # 构建Docker镜像
make docker-run    # 在Docker容器中运行
make docker-test   # 在Docker中运行测试

# 文档
make docs          # 生成文档
make docs-serve    # 本地服务文档

🔧 系统架构

核心组件

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

安全特性

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

性能特性

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

📚 文档

🐳 Docker部署

使用Docker快速开始

# 克隆并配置
git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
cd Coreflux-MQTT-MCP-Server

# 复制并编辑环境文件
cp .env.example .env
nano .env  # 配置您的设置

# 使用Docker Compose启动
docker-compose up -d

# 查看日志
docker-compose logs -f coreflux-mcp-server

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

生产Docker部署

请参阅DEPLOYMENT.md，了解包括以下内容在内的全面生产部署说明：

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

🔑 Coreflux Copilot集成

服务器通过Coreflux Copilot API提供了强大的AI辅助：

设置

  1. 从Coreflux Copilot仪表板获取API密钥
  2. 配置密钥： 
    # 方案1：环境文件
echo "DO_AGENT_API_KEY=your_api_key_here" >> .env

# 方案2：环境变量
export DO_AGENT_API_KEY=your_api_key_here

特性

  • LOT代码生成 - 从自然语言生成LOT（事物语言）代码
  • 自动化辅助 - 获取Coreflux自动化任务的帮助
  • 最佳实践 - 收到关于最优实施的指导
  • 故障排除 - 获取调试和优化的帮助

使用示例

请求Claude帮助进行Coreflux自动化：

生成一个温度监测系统的LOT代码，当温度超过75°F时触发警报

帮我创建一个处理传感器数据并将其存储在数据库中的规则

🚀 高级功能

异步消息处理

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

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

增强日志系统

全面的日志记录，具有企业特性：

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

配置验证

强大的验证系统，检查：

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

🛡️ 安全与合规

安全特性

  • 输入消毒 - 所有输入被验证和消毒
  • TLS加密 - MQTT连接的完整TLS支持
  • 秘密管理 - 安全的凭证处理
  • 审计日志 - 全面的安全事件日志
  • 非root执行 - 使用最小权限运行

合规支持

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

  • SOC 2 - 安全控制和监控
  • GDPR - 数据保护和隐私
  • HIPAA - 医疗数据保护（正确配置时）

详细的安全部分，请参阅SECRET_MANAGEMENT.md。

📊 监控与健康检查

健康检查工具

使用comprehensive_health_check工具进行全面健康监控：

# 手动健康检查
python server.py --health-check

# 或者询问Claude：
# "请对Coreflux MCP服务器运行全面健康检查"

监控指标

服务器提供详细的指标：

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

警报

配置警报：

  • 连接失败
  • 错误率高
  • 资源耗尽
  • 安全事件

🤝 贡献

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

开发流程

  1. 分叉仓库
  2. 创建功能分支：git checkout -b feature/amazing-feature
  3. 安装开发依赖项：pip install -r requirements-dev.txt
  4. 设置预提交钩子：pre-commit install
  5. 制作您的更改并编写测试
  6. 运行质量检查：make quality-check
  7. 提交您的更改：git commit -am 'Add amazing feature'
  8. 推送到分支：git push origin feature/amazing-feature
  9. 创建拉取请求

代码标准

  • Python 3.11+ 兼容性
  • 类型提示 对所有函数
  • 全面测试 覆盖率>90%
  • 安全扫描 使用bandit
  • 代码格式化 使用black和isort
  • 文档 对所有公共API

📄 许可

本项目根据Apache许可证2.0发布 - 详见LICENSE文件。

🆘 支持与故障排除

常见问题

连接拒绝

错误：MQTT连接失败