Coreflux MQTT MCP Server

Un servidor MCP que se conecta a un broker Coreflux MQTT, proporcionando acciones de Coreflux y MQTT como herramientas para asistentes de IA.

GitHub
5
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Coreflux MQTT

License Python Docker Tests Code Quality

Un servidor de Protocolo de Contexto de Modelo (MCP) de nivel empresarial que proporciona acceso seguro y escalable a los brokers MQTT de Coreflux y capacidades integrales de automatización para Claude y otros asistentes de IA compatibles con MCP.

🚀 Características

Funcionalidad Principal

  • 🔌 Integración MQTT: Conexión fluida a los brokers MQTT de Coreflux con soporte completo de TLS
  • 🛠️ API Completa de Coreflux: Acceso total a modelos, acciones, reglas y rutas
  • 🤖 Generación de Código con IA: Generación de código LOT (Lenguaje de las Cosas) a través de la API de Coreflux Copilot
  • 🔍 Descubrimiento Dinámico: Descubrimiento y listado automático de acciones disponibles
  • 🏥 Monitoreo de Salud: Verificaciones integrales de salud del sistema y monitoreo

Características Empresariales

  • 🔒 Seguridad de Producción: Saneamiento integral de registros, validación de entradas y características de seguridad
  • ⚡ Procesamiento Asíncrono: Procesamiento de mensajes sin bloqueo con limitación de velocidad y gestión de colas
  • 📝 Registro Mejorado: Registro estructurado con rotación, filtrado y saneamiento de seguridad
  • ✅ Validación de Configuración: Sistema integral de validación de entorno y archivos
  • 🧪 Marco de Pruebas: Suite completa de pruebas unitarias con simulación y reporte de cobertura

DevOps y Despliegue

  • 🐳 Listo para Contenedores: Soporte completo de despliegue con Docker y Kubernetes con verificaciones de salud
  • 🔄 Canal de CI/CD: GitHub Actions con pruebas automatizadas, escaneo de seguridad y verificaciones de calidad
  • 📦 Herramientas de Desarrollo: Hooks de pre-commit, formato de código, linting y generación de documentación
  • ⚙️ Configuración Fácil: Asistente de configuración interactivo con validación y pruebas
  • 📚 Documentación Rica: Documentación de API, guías de seguridad e instrucciones de despliegue

Inicio Rápido

Despliegue con Docker (Recomendado)

  1. Clonar y configurar:

    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

  2. Desplegar con Docker:

    docker-compose up -d

🚀 Inicio Rápido

Requisitos Previos

  • Python 3.11 o superior
  • Docker (opcional, para despliegue en contenedores)
  • Acceso a un broker MQTT de Coreflux
  • Clave API de Coreflux Copilot (opcional, para asistencia de IA)

Opción 1: Despliegue con Docker (Recomendado)

  1. Clonar y configurar:

    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

  2. Desplegar con Docker:

    docker-compose up -d

  3. Verificar el despliegue:

    docker-compose logs -f coreflux-mcp-server

Opción 2: Instalación de Desarrollo

  1. Clonar y configurar:

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

  2. Instalar dependencias:

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

  3. Configurar el entorno:

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

  4. Validar y probar:

    make validate  # Validate configuration
make test      # Run tests

  5. Iniciar el servidor:

    python server.py
# OR
make run

Para instrucciones detalladas de despliegue, consulte DEPLOYMENT.md.

⚙️ Configuración

Asistente de Configuración Interactivo

El servidor incluye un asistente de configuración integral que lo guía a través de la configuración:

python setup_assistant.py

El asistente ayuda con:

  • 🔧 Configuración de conexión al broker MQTT
  • 🔐 Configuración de certificados TLS
  • 🤖 Integración con la API de Coreflux Copilot
  • 📝 Configuración de registro y monitoreo
  • ✅ Validación y prueba de configuración

Use el asistente de configuración cuando:

  • Cree la configuración inicial
  • Actualice configuraciones existentes
  • Solucione problemas de conexión
  • Configure certificados TLS
  • Migre entre entornos

Configuración del Entorno

Copie .env.example a .env y configure:

# 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

Para opciones de configuración detalladas, consulte la Guía de Configuración.

🔌 Conexión de Claude al Servidor MCP

Usando Claude Desktop

  1. Localice el archivo de configuración de Claude Desktop:

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

  2. Agregue la configuración del servidor:

    {
  "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. Reinicie Claude Desktop

Nota de Seguridad: Para despliegues de producción, almacene los secretos en variables de entorno seguras o sistemas de gestión de secretos en lugar del archivo de configuración de Claude.

Usando Variables de Entorno

Para mayor seguridad, use variables de entorno en lugar de codificar credenciales:

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

Probando la Conexión

Una vez configurado, pruebe la conexión preguntando a Claude:

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

Claude debería responder con el estado del sistema y detalles del broker si la conexión es exitosa.

🛠️ Herramientas Disponibles

El servidor proporciona las siguientes herramientas a Claude:

Herramientas MQTT Principales

  • publish_to_coreflux - Publicar mensajes en temas MQTT con opciones de QoS y retención
  • get_broker_info - Obtener información detallada sobre la conexión al broker MQTT

Herramientas de Asistencia de IA

  • copilot_assist - Consultar la IA de Coreflux Copilot para asistencia de automatización y generación de código

Herramientas de Gestión del Sistema

  • comprehensive_health_check - Realizar verificaciones de salud detalladas de todos los componentes del sistema

Para documentación detallada de la API, consulte API_DOCUMENTATION.md.

🧪 Desarrollo y Pruebas

Configuración de Desarrollo

  1. Instalar dependencias de desarrollo:

    pip install -r requirements-dev.txt

  2. Instalar hooks de pre-commit:

    pre-commit install

  3. Ejecutar la configuración completa de desarrollo:

    make dev-setup  # Complete development environment setup

Pruebas

Ejecute la suite de pruebas integral:

# 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

Calidad del Código

Mantenga la calidad del código con herramientas automatizadas:

# 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

Comandos de desarrollo disponibles:

# 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

🔧 Arquitectura del Sistema

Componentes Principales

  • server.py - Servidor MCP principal con implementaciones de herramientas
  • config_validator.py - Validación de configuración y verificación del entorno
  • message_processor.py - Procesamiento asíncrono de mensajes MQTT con limitación de velocidad
  • enhanced_logging.py - Registro estructurado con rotación y filtrado de seguridad
  • config_schema.py - Esquemas Pydantic para configuración segura de tipos
  • parser.py - Utilidades de saneamiento y análisis

Características de Seguridad

  • Saneamiento de Entradas - Todas las entradas se sanean para prevenir ataques de inyección
  • Seguridad de Registros - Saneamiento automático de datos sensibles en registros
  • Soporte TLS - Cifrado TLS completo para conexiones MQTT
  • Validación de Configuración - Validación integral de todos los parámetros de configuración
  • Gestión de Secretos - Manejo seguro de credenciales y claves API

Características de Rendimiento

  • Procesamiento Asíncrono - Procesamiento de mensajes sin bloqueo
  • Agrupación de Conexiones - Gestión eficiente de conexiones MQTT
  • Limitación de Velocidad - Límites de velocidad configurables para prevenir abusos
  • Monitoreo de Salud - Verificaciones de salud en tiempo real y monitoreo del sistema

📚 Documentación

🐳 Despliegue con Docker

Inicio Rápido con 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')
"

Despliegue de Producción con Docker

Consulte DEPLOYMENT.md para instrucciones integrales de despliegue en producción, incluyendo:

  • Construcciones Docker de múltiples etapas
  • Despliegues en Kubernetes
  • Verificaciones de salud y monitoreo
  • Balanceo de carga y escalado
  • Configuraciones de seguridad

🔑 Integración con Coreflux Copilot

El servidor incluye potente asistencia de IA a través de la API de Coreflux Copilot:

Configuración

  1. Obtenga la Clave API del panel de Coreflux Copilot
  2. Configure la clave: 
    # 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

Características

  • Generación de Código LOT - Generar código de Lenguaje de las Cosas a partir de lenguaje natural
  • Asistencia de Automatización - Obtener ayuda con tareas de automatización de Coreflux
  • Mejores Prácticas - Recibir orientación sobre implementaciones óptimas
  • Solución de Problemas - Obtener asistencia con depuración y optimización

Ejemplos de Uso

Pida a Claude que ayude con la automatización de 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

🚀 Características Avanzadas

Procesamiento Asíncrono de Mensajes

El servidor incluye un procesador de mensajes asíncrono robusto que:

  • Previene Bloqueos - Maneja mensajes sin bloquear el hilo principal
  • Limitación de Velocidad - Límites configurables para prevenir sobrecarga del sistema
  • Gestión de Colas - Manejo inteligente de colas con contrapresión
  • Estadísticas - Métricas de procesamiento y monitoreo en tiempo real

Sistema de Registro Mejorado

Registro integral con características empresariales:

  • Registro Estructurado - Registros en formato JSON para fácil análisis
  • Rotación de Registros - Rotación automática de archivos de registro para gestionar espacio en disco
  • Filtrado de Seguridad - Saneamiento automático de información sensible
  • Múltiples Salidas - Soporte para consola, archivo y syslog

Validación de Configuración

Sistema de validación robusto que verifica:

  • Variables de Entorno - Valida toda la configuración requerida
  • Permisos de Archivos - Asegura que los archivos de certificados sean accesibles
  • Conectividad de Red - Prueba la conectividad del broker MQTT
  • Disponibilidad de API - Valida el acceso a la API de Copilot

🛡️ Seguridad y Cumplimiento

Características de Seguridad

  • Saneamiento de Entradas - Todas las entradas validadas y saneadas
  • Cifrado TLS - Soporte completo de TLS para conexiones MQTT
  • Gestión de Secretos - Manejo seguro de credenciales
  • Registro de Auditoría - Registro integral de eventos de seguridad
  • Ejecución sin Root - Se ejecuta con privilegios mínimos

Soporte de Cumplimiento

El servidor soporta varios requisitos de cumplimiento:

  • SOC 2 - Controles de seguridad y monitoreo
  • GDPR - Protección de datos y privacidad
  • HIPAA - Protección de datos de salud (cuando se configura adecuadamente)

Para información detallada de seguridad, consulte SECRET_MANAGEMENT.md.

📊 Monitoreo y Verificaciones de Salud

Herramienta de Verificación de Salud

Monitoreo integral de salud con la herramienta 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"

Métricas de Monitoreo

El servidor proporciona métricas detalladas:

  • Estado de Conexión - Conectividad del broker MQTT
  • Procesamiento de Mensajes - Tamaño de cola y tasas de procesamiento
  • Recursos del Sistema - Uso de memoria y CPU
  • Tasas de Error - Operaciones fallidas y estadísticas de errores
  • Estado de API - Disponibilidad de la API de Copilot y tiempos de respuesta

Alertas

Configure alertas para:

  • Fallos de conexión
  • Altas tasas de error
  • Agotamiento de recursos
  • Eventos de seguridad

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulte nuestras pautas de contribución:

Proceso de Desarrollo

  1. Haga un fork del repositorio
  2. Cree una rama de características: git checkout -b feature/amazing-feature
  3. Instale las dependencias de desarrollo: pip install -r requirements-dev.txt
  4. Configure los hooks de pre-commit: pre-commit install
  5. Haga sus cambios con pruebas
  6. Ejecute las verificaciones de calidad: make quality-check
  7. Confirme sus cambios: git commit -am 'Add amazing feature'
  8. Empuje a la rama: git push origin feature/amazing-feature
  9. Cree una Solicitud de Extracción

Estándares de Código

  • Compatibilidad con Python 3.11+
  • Anotaciones de tipo para todas las funciones
  • Pruebas integrales con cobertura >90%
  • Escaneo de seguridad con bandit
  • Formato de código con black e isort
  • Documentación para todas las APIs públicas

📄 Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0 - consulte el archivo LICENSE para más detalles.

🆘 Soporte y Solución de Problemas

Problemas Comunes

Conexión Rechazada

Error: MQTT connection failed
  • Verifique el hostname y puerto del broker
  • Verifique la conectividad de red
  • Confirme la configuración de TLS

Autenticación Fallida

Error: Authentication failed
  • Verifique el nombre de usuario/contraseña
  • Verifique la validez de la clave API
  • Confirme los permisos del broker

Fallo de Handshake TLS

Error: TLS handshake failed
  • Verifique las rutas de los certificados
  • Verifique la validez de los certificados
  • Confirme la compatibilidad de la versión TLS

Modo de Depuración

Habilite el registro detallado para solución de problemas:

export LOG_LEVEL=DEBUG
python server.py

Obtener Ayuda

🗺️ Hoja de ruta

Estado actual: v1.0.0 ✅

  • ✅ Funcionalidad principal de MQTT
  • ✅ Integración con la API de Copilot
  • ✅ Funciones de seguridad empresarial
  • ✅ Pruebas exhaustivas
  • ✅ Soporte de despliegue en producción

Próximas funciones

  • v1.1.0 - Monitoreo y métricas mejorados
  • v1.2.0 - Puntos finales adicionales de la API de Coreflux
  • v1.3.0 - Soporte de WebSocket para datos en tiempo real
  • v2.0.0 - Soporte multi-broker y federación

📋 Referencia rápida

Comandos esenciales

# 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

Archivos clave

  • server.py - Servidor MCP principal
  • .env - Archivo de configuración
  • requirements.txt - Dependencias de Python
  • docker-compose.yml - Despliegue con Docker
  • Makefile - Comandos de desarrollo

Construido con ❤️ por la Comunidad Coreflux

  • remove_action: Eliminar un evento/función de acción
  • run_action: Ejecutar un evento/función de acción
  • remove_all_models: Eliminar todos los modelos
  • remove_all_actions: Eliminar todas las acciones
  • remove_all_routes: Eliminar todas las rutas
  • list_discovered_actions: Listar todas las acciones de Coreflux descubiertas
  • request_lot_code: Generar código LOT usando la API de Coreflux Copilot basada en indicaciones de lenguaje natural

Depuración y resolución de problemas

El servidor MCP ahora se inicia incluso si el broker MQTT no está disponible, lo que le permite solucionar problemas y configurar conexiones a través de las herramientas MCP.

Estado de conexión y recuperación

  • El servidor se iniciará correctamente incluso si el broker MQTT es inaccesible
  • Use la herramienta get_connection_status para verificar el estado de la conexión y obtener orientación para la resolución de problemas
  • Use la herramienta setup_mqtt_connection para configurar una nueva conexión de broker sin reiniciar
  • Use las herramientas check_broker_health o reconnect_mqtt para probar y reintentar conexiones

Herramientas disponibles para la gestión de conexiones

  • get_connection_status: Obtener estado detallado de la conexión con orientación para la resolución de problemas
  • setup_mqtt_connection: Configurar una nueva conexión de broker MQTT dinámicamente
  • mqtt_connect: Conectarse a un broker MQTT específico con parámetros personalizados
  • check_broker_health: Probar la conectividad del broker e intentar reconexión
  • reconnect_mqtt: Forzar la reconexión al broker configurado

Pasos tradicionales de resolución de problemas

Si encuentra problemas:

  1. Verifique sus credenciales del broker MQTT en su configuración de Claude
  2. Asegúrese de que el broker sea accesible
  3. Ejecute el asistente de configuración para verificar o actualizar su configuración: 
    python setup_assistant.py
  4. Revise los registros de Claude Desktop: 
    # 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
  5. Ejecute el servidor con registro de depuración: 
    # Direct execution with debug logging
python server.py --mqtt-host localhost --mqtt-port 1883 --log-level DEBUG

Referencias y documentación

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lea nuestras pautas de contribución y envíe solicitudes de extracción a la rama development.

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0 - consulte el archivo LICENSE para más detalles.

Soporte

  • 📖 Documentación: Consulte los archivos README, DEPLOYMENT.md y SECURITY.md
  • 🐛 Problemas: Reporte errores y solicitudes de funciones en GitHub
  • 💬 Comunidad: Únase a la comunidad de Coreflux para discusiones