Coreflux MQTT MCP Server

Um servidor MCP que se conecta a um broker Coreflux MQTT, fornecendo ações Coreflux e MQTT como ferramentas para assistentes de IA.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Coreflux MQTT MCP Server

License Python Docker Tests Code Quality

Um servidor Model Context Protocol (MCP) de nível empresarial que fornece acesso seguro e escalável aos brokers MQTT da Coreflux e recursos abrangentes de automação para o Claude e outros assistentes de IA compatíveis com MCP.

🚀 Recursos

Funcionalidade Principal

  • 🔌 Integração MQTT: Conexão perfeita com brokers MQTT da Coreflux com suporte completo a TLS
  • 🛠️ API Coreflux Completa: Acesso total a modelos, ações, regras e rotas
  • 🤖 Geração de Código com IA: Geração de código LOT (Language-of-Things) via API Coreflux Copilot
  • 🔍 Descoberta Dinâmica: Descoberta e listagem automática de ações disponíveis
  • 🏥 Monitoramento de Saúde: Verificações abrangentes de saúde do sistema e monitoramento

Recursos Empresariais

  • 🔒 Segurança de Produção: Sanitização abrangente de logs, validação de entrada e recursos de segurança
  • ⚡ Processamento Assíncrono: Processamento de mensagens não bloqueante com limite de taxa e gerenciamento de fila
  • 📝 Registro Aprimorado: Registro estruturado com rotação, filtragem e sanitização de segurança
  • ✅ Validação de Configuração: Sistema abrangente de validação de ambiente e arquivos
  • 🧪 Estrutura de Testes: Suíte completa de testes unitários com simulação e relatórios de cobertura

DevOps e Implantação

  • 🐳 Pronto para Contêineres: Suporte completo de implantação Docker e Kubernetes com verificações de saúde
  • 🔄 Pipeline CI/CD: GitHub Actions com testes automatizados, varredura de segurança e verificações de qualidade
  • 📦 Ferramentas de Desenvolvimento: Hooks de pré-commit, formatação de código, linting e geração de documentação
  • ⚙️ Configuração Fácil: Assistente de configuração interativo com validação e testes
  • 📚 Documentação Rica: Documentação de API, guias de segurança e instruções de implantação

Início Rápido

Implantação com Docker (Recomendado)

  1. Clone e configure:

    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. Implante com Docker:

    docker-compose up -d

🚀 Início Rápido

Pré-requisitos

  • Python 3.11 ou superior
  • Docker (opcional, para implantação em contêiner)
  • Acesso a um broker MQTT da Coreflux
  • Chave da API Coreflux Copilot (opcional, para assistência de IA)

Opção 1: Implantação com Docker (Recomendado)

  1. Clone e configure:

    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. Implante com Docker:

    docker-compose up -d

  3. Verifique a implantação:

    docker-compose logs -f coreflux-mcp-server

Opção 2: Instalação para Desenvolvimento

  1. Clone e configure:

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

  2. Instale as dependências:

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

  3. Configure o ambiente:

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

  4. Valide e teste:

    make validate  # Validate configuration
make test      # Run tests

  5. Inicie o servidor:

    python server.py
# OR
make run

Para instruções detalhadas de implantação, consulte DEPLOYMENT.md.

⚙️ Configuração

Assistente de Configuração Interativo

O servidor inclui um assistente de configuração abrangente que orienta você pela configuração:

python setup_assistant.py

O assistente ajuda com:

  • 🔧 Configurações de conexão do broker MQTT
  • 🔐 Configuração de certificados TLS
  • 🤖 Integração com a API Coreflux Copilot
  • 📝 Configuração de registro e monitoramento
  • ✅ Validação e teste de configuração

Use o assistente de configuração quando:

  • Criando a configuração inicial
  • Atualizando configurações existentes
  • Solucionando problemas de conexão
  • Configurando certificados TLS
  • Migrando entre ambientes

Configuração de Ambiente

Copie .env.example para .env e 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 opções de configuração detalhadas, consulte o Guia de Configuração.

🔌 Conectando o Claude ao Servidor MCP

Usando o Claude Desktop

  1. Localize o arquivo de configuração do Claude Desktop:

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

  2. Adicione a configuração do 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 o Claude Desktop

Nota de Segurança: Para implantações em produção, armazene segredos em variáveis de ambiente seguras ou sistemas de gerenciamento de segredos em vez do arquivo de configuração do Claude.

Usando Variáveis de Ambiente

Para melhor segurança, use variáveis de ambiente em vez de codificar credenciais:

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

Testando a Conexão

Uma vez configurado, teste a conexão perguntando ao Claude:

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

O Claude deve responder com o status do sistema e detalhes do broker se a conexão for bem-sucedida.

🛠️ Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas ao Claude:

Ferramentas MQTT Principais

  • publish_to_coreflux - Publica mensagens em tópicos MQTT com opções de QoS e retenção
  • get_broker_info - Obtém informações detalhadas sobre a conexão com o broker MQTT

Ferramentas de Assistência com IA

  • copilot_assist - Consulta o Coreflux Copilot AI para assistência em automação e geração de código

Ferramentas de Gerenciamento do Sistema

  • comprehensive_health_check - Realiza verificações detalhadas de saúde de todos os componentes do sistema

Para documentação detalhada da API, consulte API_DOCUMENTATION.md.

🧪 Desenvolvimento e Testes

Configuração de Desenvolvimento

  1. Instale as dependências de desenvolvimento:

    pip install -r requirements-dev.txt

  2. Instale os hooks de pré-commit:

    pre-commit install

  3. Execute a configuração completa de desenvolvimento:

    make dev-setup  # Complete development environment setup

Testes

Execute a suíte de testes abrangente:

# 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

Qualidade de Código

Mantenha a qualidade do código com ferramentas 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 desenvolvimento disponíveis:

# 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

🔧 Arquitetura do Sistema

Componentes Principais

  • server.py - Servidor MCP principal com implementações de ferramentas
  • config_validator.py - Validação de configuração e verificação de ambiente
  • message_processor.py - Processamento assíncrono de mensagens MQTT com limite de taxa
  • enhanced_logging.py - Registro estruturado com rotação e filtragem de segurança
  • config_schema.py - Esquemas Pydantic para configuração com segurança de tipos
  • parser.py - Utilitários de sanitização e análise

Recursos de Segurança

  • Sanitização de Entrada - Todas as entradas são sanitizadas para prevenir ataques de injeção
  • Segurança de Logs - Sanitização automática de dados sensíveis em logs
  • Suporte TLS - Criptografia TLS completa para conexões MQTT
  • Validação de Configuração - Validação abrangente de todos os parâmetros de configuração
  • Gerenciamento de Segredos - Tratamento seguro de credenciais e chaves de API

Recursos de Desempenho

  • Processamento Assíncrono - Processamento de mensagens não bloqueante
  • Pooling de Conexões - Gerenciamento eficiente de conexões MQTT
  • Limite de Taxa - Limites de taxa configuráveis para prevenir abuso
  • Monitoramento de Saúde - Verificações de saúde em tempo real e monitoramento do sistema

📚 Documentação

🐳 Implantação Docker

Início Rápido com 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')
"

Implantação Docker em Produção

Consulte DEPLOYMENT.md para instruções abrangentes de implantação em produção, incluindo:

  • Builds Docker em múltiplas etapas
  • Implantações Kubernetes
  • Verificações de saúde e monitoramento
  • Balanceamento de carga e escalabilidade
  • Configurações de segurança

🔑 Integração Coreflux Copilot

O servidor inclui assistência poderosa de IA através da API Coreflux Copilot:

Configuração

  1. Obtenha a Chave da API no painel do Coreflux Copilot
  2. Configure a chave: 
    # 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

Recursos

  • Geração de Código LOT - Gere código Language-of-Things a partir de linguagem natural
  • Assistência em Automação - Obtenha ajuda com tarefas de automação da Coreflux
  • Melhores Práticas - Receba orientação sobre implementações ideais
  • Solução de Problemas - Obtenha assistência com depuração e otimização

Exemplos de Uso

Peça ao Claude para ajudar com automação da 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

🚀 Recursos Avançados

Processamento Assíncrono de Mensagens

O servidor inclui um processador de mensagens assíncrono robusto que:

  • Previne Bloqueio - Processa mensagens sem bloquear o thread principal
  • Limite de Taxa - Limites configuráveis para prevenir sobrecarga do sistema
  • Gerenciamento de Fila - Tratamento inteligente de fila com contrapressão
  • Estatísticas - Métricas de processamento em tempo real e monitoramento

Sistema de Registro Aprimorado

Registro abrangente com recursos empresariais:

  • Registro Estruturado - Logs formatados em JSON para fácil análise
  • Rotação de Logs - Rotação automática de arquivos de log para gerenciar espaço em disco
  • Filtragem de Segurança - Sanitização automática de informações sensíveis
  • Múltiplas Saídas - Suporte a console, arquivo e syslog

Validação de Configuração

Sistema de validação robusto que verifica:

  • Variáveis de Ambiente - Valida toda a configuração necessária
  • Permissões de Arquivo - Garante que os arquivos de certificado estejam acessíveis
  • Conectividade de Rede - Testa a conectividade com o broker MQTT
  • Disponibilidade da API - Valida o acesso à API Copilot

🛡️ Segurança e Conformidade

Recursos de Segurança

  • Sanitização de Entrada - Todas as entradas validadas e sanitizadas
  • Criptografia TLS - Suporte completo a TLS para conexões MQTT
  • Gerenciamento de Segredos - Tratamento seguro de credenciais
  • Registro de Auditoria - Registro abrangente de eventos de segurança
  • Execução sem Root - Executa com privilégios mínimos

Suporte à Conformidade

O servidor suporta vários requisitos de conformidade:

  • SOC 2 - Controles de segurança e monitoramento
  • GDPR - Proteção de dados e privacidade
  • HIPAA - Proteção de dados de saúde (quando configurado adequadamente)

Para informações detalhadas de segurança, consulte SECRET_MANAGEMENT.md.

📊 Monitoramento e Verificações de Saúde

Ferramenta de Verificação de Saúde

Monitoramento abrangente de saúde com a ferramenta 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 Monitoramento

O servidor fornece métricas detalhadas:

  • Status da Conexão - Conectividade com o broker MQTT
  • Processamento de Mensagens - Tamanho da fila e taxas de processamento
  • Recursos do Sistema - Uso de memória e CPU
  • Taxas de Erro - Operações falhas e estatísticas de erro
  • Status da API - Disponibilidade da API Copilot e tempos de resposta

Alertas

Configure alertas para:

  • Falhas de conexão
  • Altas taxas de erro
  • Esgotamento de recursos
  • Eventos de segurança

🤝 Contribuindo

Aceitamos contribuições! Consulte nossas diretrizes de contribuição:

Processo de Desenvolvimento

  1. Faça um fork do repositório
  2. Crie um branch de recurso: git checkout -b feature/amazing-feature
  3. Instale as dependências de desenvolvimento: pip install -r requirements-dev.txt
  4. Configure os hooks de pré-commit: pre-commit install
  5. Faça suas alterações com testes
  6. Execute verificações de qualidade: make quality-check
  7. Faça commit das suas alterações: git commit -am 'Add amazing feature'
  8. Envie para o branch: git push origin feature/amazing-feature
  9. Crie um Pull Request

Padrões de Código

  • Compatibilidade com Python 3.11+
  • Type hints para todas as funções
  • Testes abrangentes com cobertura >90%
  • Varredura de segurança com bandit
  • Formatação de código com black e isort
  • Documentação para todas as APIs públicas

📄 Licença

Este projeto é licenciado sob a Apache License 2.0 - consulte o arquivo LICENSE para detalhes.

🆘 Suporte e Solução de Problemas

Problemas Comuns

Conexão Recusada

Error: MQTT connection failed
  • Verifique o hostname e a porta do broker
  • Verifique a conectividade de rede
  • Confirme a configuração TLS

Falha na Autenticação

Error: Authentication failed
  • Verifique o nome de usuário/senha
  • Verifique a validade da chave da API
  • Confirme as permissões do broker

Falha no Handshake TLS

Error: TLS handshake failed
  • Verifique os caminhos dos certificados
  • Verifique a validade do certificado
  • Confirme a compatibilidade da versão TLS

Modo de Depuração

Ative o registro detalhado para solução de problemas:

export LOG_LEVEL=DEBUG
python server.py

Obtendo Ajuda

🗺️ Roteiro

Status Atual: v1.0.0 ✅

  • ✅ Funcionalidade principal do MQTT
  • ✅ Integração com a API do Copilot
  • ✅ Recursos de segurança empresarial
  • ✅ Testes abrangentes
  • ✅ Suporte a implantação em produção

Próximos Recursos

  • v1.1.0 - Monitoramento e métricas aprimorados
  • v1.2.0 - Endpoints adicionais da API Coreflux
  • v1.3.0 - Suporte a WebSocket para dados em tempo real
  • v2.0.0 - Suporte a múltiplos brokers e federação

📋 Referência Rápida

Comandos Essenciais

# 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

Arquivos Principais

  • server.py - Servidor MCP principal
  • .env - Arquivo de configuração
  • requirements.txt - Dependências Python
  • docker-compose.yml - Implantação Docker
  • Makefile - Comandos de desenvolvimento

Feito com ❤️ pela Comunidade Coreflux

  • remove_action: Remover um evento/função de ação
  • run_action: Executar um evento/função de ação
  • remove_all_models: Remover todos os modelos
  • remove_all_actions: Remover todas as ações
  • remove_all_routes: Remover todas as rotas
  • list_discovered_actions: Listar todas as ações Coreflux descobertas
  • request_lot_code: Gerar código LOT usando a API Coreflux Copilot com base em prompts em linguagem natural

Depuração e Solução de Problemas

O servidor MCP agora inicia mesmo se o broker MQTT não estiver disponível, permitindo que você solucione problemas e configure conexões por meio das ferramentas MCP.

Status da Conexão e Recuperação

  • O servidor iniciará com sucesso mesmo se o broker MQTT estiver inacessível
  • Use a ferramenta get_connection_status para verificar a saúde da conexão e obter orientações de solução de problemas
  • Use a ferramenta setup_mqtt_connection para configurar uma nova conexão de broker sem reiniciar
  • Use as ferramentas check_broker_health ou reconnect_mqtt para testar e tentar novamente as conexões

Ferramentas Disponíveis para Gerenciamento de Conexão

  • get_connection_status: Obter status detalhado da conexão com orientações de solução de problemas
  • setup_mqtt_connection: Configurar dinamicamente uma nova conexão de broker MQTT
  • mqtt_connect: Conectar a um broker MQTT específico com parâmetros personalizados
  • check_broker_health: Testar a conectividade do broker e tentar reconexão
  • reconnect_mqtt: Forçar reconexão ao broker configurado

Etapas Tradicionais de Solução de Problemas

Se você encontrar problemas:

  1. Verifique suas credenciais do broker MQTT na sua configuração do Claude
  2. Garanta que o broker esteja acessível
  3. Execute o assistente de configuração para verificar ou atualizar sua configuração: 
    python setup_assistant.py
  4. Verifique os logs do 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. Execute o servidor com registro de depuração: 
    # Direct execution with debug logging
python server.py --mqtt-host localhost --mqtt-port 1883 --log-level DEBUG

Referências e Documentação

Contribuindo

Contribuições são bem-vindas! Por favor, leia nossas diretrizes de contribuição e envie pull requests para o branch development.

Licença

Este projeto é licenciado sob a Apache License 2.0 - consulte o arquivo LICENSE para obter detalhes.

Suporte

  • 📖 Documentação: Consulte os arquivos README, DEPLOYMENT.md e SECURITY.md
  • 🐛 Problemas: Reporte bugs e solicitações de recursos no GitHub
  • 💬 Comunidade: Junte-se à comunidade Coreflux para discussões