Lumenore-MCP

Um servidor Model Context Protocol (MCP) que fornece acesso a assistentes de IA às capacidades de análise e consulta em linguagem natural da Lumenore. Construído com FastMCP e Python 3.13 para integração escalável de análise de dados.

GitHub

Documentação

Servidor MCP de Analytics Lumenore

License Python MCP Contributor Covenant

Um servidor Model Context Protocol (MCP) que fornece a assistentes de IA acesso aos recursos de analytics e consultas em linguagem natural da Lumenore. Construído com FastMCP e Python 3.13 para integração escalável de análise de dados.

Início Rápido

1. Instalar e Executar

git clone https://github.com/Lumenore-Platform/lumenore-mcp.git
cd lumenore-mcp
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your client credentials (LUMENORE_CLIENT_ID and LUMENORE_SECRET)
python main.py

2. Conectar Seu Assistente de IA

  • URL: http://localhost:8080/mcp
  • Transporte: HTTP Streamable

3. Começar a Analisar

# Example: Get sales insights
result = await client.call_tool("nlq_to_data", {
    "userQuery": "Top 5 sales regions last month",
    "schemaId": 123
})

📖 Documentação Completa | 🐛 Reportar Problemas | 🔒 Política de Privacidade

Sumário

Visão Geral

Este servidor MCP fornece a assistentes de IA acesso aos poderosos recursos de analytics da Lumenore:

  • Consultas em Linguagem Natural: Converta perguntas em insights de dados
  • Analytics Avançados: Tendências, previsões, correlações, outliers, mudanças, análise de Pareto
  • Processamento em Tempo Real: Transmita respostas para grandes conjuntos de dados
  • Zero Armazenamento de Dados: Processamento em memória sem registro persistente. Quando o Servidor MCP encaminha solicitações para o backend da Lumenore, as políticas de privacidade da Lumenore se aplicam

Instalação

Pré-requisitos

  • Python 3.13+
  • Credenciais de cliente Lumenore (ID do cliente e segredo)
  • Acesso à instância do servidor Lumenore

Configuração

git clone https://github.com/Lumenore-Platform/lumenore-mcp.git
cd lumenore-mcp
pip install -r requirements.txt

Configuração

Crie um arquivo .env na raiz do projeto com suas credenciais. Você pode usar .env.example como modelo:

cp .env.example .env

Em seguida, edite .env com sua configuração:

Usando Credenciais de Cliente

LUMENORE_CLIENT_ID="your_client_id_here"
LUMENORE_SECRET="your_secret_here"
SERVER_URL="https://preview.lumenore.com"

Parâmetros de Configuração

ParâmetroObrigatórioDescriçãoPadrão
LUMENORE_CLIENT_IDSimID do cliente para autenticação de credenciais de clienteNenhum
LUMENORE_SECRETSimSegredo do cliente para autenticação de credenciais de clienteNenhum
SERVER_URLNãoURL do servidor Lumenorehttps://preview.lumenore.com

Executando o Servidor

Inicie o servidor MCP:

python main.py

O servidor executa em http://0.0.0.0:8080 com transporte SSE para streaming em tempo real.

Conectando Seu Assistente de IA

Claude para Desktop

  1. Configurações → Servidores MCP
  2. Adicionar Servidor com: 
    Name: Lumenore Analytics
URL: http://localhost:8080/mcp
Transport: Streamable HTTP

Acesso Programático (Python)

from mcp.client import MCPClient

client = MCPClient("http://localhost:8080/mcp", transport="streamable_http")
tools = await client.list_tools()
result = await client.call_tool("nlq_to_data", {
    "userQuery": "Top 5 sales regions last month",
    "schemaId": 123
})

Detalhes da Conexão:

  • Protocolo: MCP 2024-11-05+
  • Transporte: HTTP Streamable (SSE)
  • Porta: 8080 (padrão)
  • Autenticação: Nenhuma autenticação em nível MCP necessária

Testar Conexão:

curl -I http://localhost:8080  # Should return HTTP/1.1 200 OK

Autenticação

Obtendo Suas Credenciais

Credenciais de Cliente

  1. Entre em contato com o suporte da Lumenore para obter credenciais de cliente
  2. Receba seu LUMENORE_CLIENT_ID e LUMENORE_SECRET
  3. Armazene com segurança no seu arquivo .env

Consulte a seção Configuração para instruções detalhadas de configuração.

Melhores Práticas de Segurança

Solução de Problemas de Autenticação

"Token de autorização ausente ou inválido":

  • Verifique se as credenciais estão definidas no arquivo .env:
    • Para credenciais de cliente: Verifique se ambos LUMENORE_CLIENT_ID e LUMENORE_SECRET estão definidos
  • Garanta que os créditos de IA da Lumenore estejam disponíveis
  • Verifique se SERVER_URL aponta para a instância correta da Lumenore

Ferramentas Disponíveis

O servidor fornece 8 ferramentas poderosas para análise de dados:

Gerenciamento de Conjuntos de Dados

get_dataset_metadata - Lista conjuntos de dados disponíveis e IDs de esquema

Consultas em Linguagem Natural

nlq_to_data - Converte perguntas em dados estruturados

{
  "userQuery": "Top 5 sales regions last month",
  "schemaId": 123
}

Analytics Avançados

get_trend_data - Identifica padrões e tendências temporais get_prediction_data - Gera previsões e predições get_outlier_data - Detecta anomalias e padrões incomuns get_correlation_data - Analisa relações entre variáveis get_change_data - Detecta mudanças e transições de padrões get_pareto_data - Realiza análise de impacto 80/20

Tratamento de Erros

Todas as ferramentas retornam respostas padronizadas:

  • Sucesso: {"data": {...}, "status": "success"}
  • Erro de Validação: {"error": "...", "status": "validation_error"}
  • Erro de Serviço: {"error": "...", "status": "error"}

Desempenho

  • Tempo de Resposta: 1-7 segundos
  • Tempo Limite: 60 segundos
  • Concorrência: Suporta múltiplas solicitações simultâneas

Melhores Práticas

  1. Comece com get_dataset_metadata para encontrar IDs de esquema
  2. Seja específico em consultas em linguagem natural
  3. Sempre verifique o campo status nas respostas
  4. Armazene em cache consultas frequentes para melhor desempenho

Exemplos de Uso

Aqui estão três exemplos realistas mostrando como assistentes de IA podem interagir com o Servidor MCP de Analytics Lumenore:

Exemplo 1: Análise de Desempenho de Vendas

Cenário: Um analista de negócios deseja entender o desempenho de vendas do último trimestre.

Interação do Assistente de IA:

# Step 1: Get available datasets
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Query sales data
sales_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show me total sales by region for Q4 2024, sorted by highest sales",
    "schemaId": 35403
})

# Step 3: Analyze trends
trend_analysis = await client.call_tool("get_trend_data", {
    "userQuery": "What are the monthly sales trends for Q4 2024?",
    "schemaId": 35403
})

# Step 4: Identify top performers
pareto_analysis = await client.call_tool("get_pareto_data", {
    "userQuery": "Which products contribute to 80% of our sales?",
    "schemaId": 35403
})

Insights Esperados:

  • Detalhamento de vendas por região com totais
  • Visualização de tendência mensal mostrando crescimento/declínio
  • Análise de contribuição por produto destacando os principais geradores de receita

Exemplo 2: Análise de Comportamento do Cliente

Cenário: Uma equipe de marketing deseja entender padrões de compra dos clientes e detectar anomalias.

Interação do Assistente de IA:

# Step 1: Get customer dataset information
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Analyze customer segments
customer_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show customer demographics and average order value by age group",
    "schemaId": 35404
})

# Step 3: Detect unusual patterns
anomaly_detection = await client.call_tool("get_outlier_data", {
    "userQuery": "Find customers with unusually high order values or frequency",
    "schemaId": 35404
})

# Step 4: Understand correlations
correlation_analysis = await client.call_tool("get_correlation_data", {
    "userQuery": "What factors correlate with customer lifetime value?",
    "schemaId": 35404
})

Insights Esperados:

  • Segmentação de clientes por dados demográficos e gastos
  • Identificação de possíveis fraudes ou clientes VIP
  • Principais impulsionadores de valor do cliente para marketing direcionado

Exemplo 3: Otimização de Estoque

Cenário: Um gerente de operações precisa otimizar os níveis de estoque com base em padrões de demanda e previsões.

Interação do Assistente de IA:

# Step 1: Get inventory dataset
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Analyze historical demand
demand_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show monthly demand for each product category over the past year",
    "schemaId": 35405
})

# Step 3: Identify trends
trend_analysis = await client.call_tool("get_trend_data", {
    "userQuery": "What are the demand trends for each product category?",
    "schemaId": 35405
})

# Step 4: Generate forecasts
forecast = await client.call_tool("get_prediction_data", {
    "userQuery": "Predict demand for next 3 months by product category",
    "schemaId": 35405
})

# Step 5: Detect demand changes
change_detection = await client.call_tool("get_change_data", {
    "userQuery": "Have there been any significant changes in demand patterns recently?",
    "schemaId": 35405
})

Insights Esperados:

  • Padrões históricos de demanda por categoria
  • Previsões futuras de demanda com intervalos de confiança
  • Alerta antecipado de mudanças nos padrões de demanda
  • Recomendações de otimização de estoque baseadas em dados

Benefícios:

  • Atualização automática de dados sem intervenção manual
  • Insights em tempo real para tomada de decisão operacional
  • Redução de carga nos sistemas backend através de cache eficiente

Melhores Práticas dos Exemplos

  1. Comece com Metadados: Sempre use get_dataset_metadata para entender os conjuntos de dados disponíveis
  2. Combine Ferramentas: Use múltiplas ferramentas juntas para análise abrangente
  3. Consultas Específicas: Seja claro e específico em consultas em linguagem natural
  4. Tratamento de Erros: Sempre verifique o status da resposta antes de processar resultados
  5. Desempenho: Armazene em cache dados acessados com frequência para melhorar os tempos de resposta

Prompts para Claude

Aqui estão exemplos de prompts que você pode usar com Claude quando conectado a este servidor MCP:

Para Análise de Vendas:

"Use as ferramentas de Analytics Lumenore para analisar nosso desempenho de vendas no Q4. Preciso ver detalhamentos regionais, identificar produtos de melhor desempenho e entender as tendências de vendas."

Para Insights de Clientes:

"Analise os dados demográficos dos clientes, encontre quaisquer padrões de compra incomuns e identifique quais fatores impulsionam o valor do cliente. Use as ferramentas de analytics disponíveis para fornecer insights abrangentes."

Para Gerenciamento de Estoque:

"Gere previsões para o próximo trimestre e identifique quaisquer mudanças recentes no comportamento da demanda usando as ferramentas de análise preditiva e de tendências."

Tratamento de Erros

Todas as ferramentas implementam tratamento abrangente de erros com tipos de erro específicos:

# Validation errors
{
    "error": "Invalid request parameters: <details>",
    "status": "validation_error",
    "query": "<user_query>",
    "schema_id": <schema_id>
}

# Service errors
{
    "error": "<Operation> failed: <details>",
    "status": "error",
    "query": "<user_query>",
    "schema_id": <schema_id>
}

Testando o Servidor

Você pode testar o servidor MCP usando qualquer cliente compatível com MCP ou fazendo solicitações HTTP ao endpoint SSE:

# Example: Testing with curl (adjust based on MCP protocol)
curl -N http://localhost:8080

Segurança e Privacidade

Visão Geral de Segurança

O Servidor MCP de Analytics Lumenore implementa múltiplas camadas de segurança para proteger seus dados e credenciais de API:

Proteção de Dados

  • Processamento em Memória: Todos os dados são processados em memória e imediatamente descartados após a geração da resposta
  • Sem Armazenamento de Dados: O servidor MCP não armazena ou registra consultas de usuários, IDs de esquema ou dados de resposta
  • Comunicação Segura: Todas as solicitações de API backend usam criptografia HTTPS
  • Segurança de Credenciais: Credenciais de cliente nunca são registradas, armazenadas ou expostas em respostas

Segurança de Autenticação

  • Fluxo de Credenciais de Cliente: Autenticação padrão da indústria usando ID e segredo do cliente
  • Gerenciamento de Sessão: Tratamento seguro de sessão baseado em cookies com renovação automática de token
  • Sem Autenticação em Nível MCP: A conexão MCP não requer autenticação (a autenticação do backend é tratada no lado do servidor)
  • Monitoramento de Segurança: Tentativas de autenticação falhas são registradas para análise de segurança

Melhores Práticas de Credenciais

  • Variáveis de Ambiente: Armazene credenciais em variáveis de ambiente ou arquivos .env (nunca em código)
  • Rotação Regular: Rode as credenciais a cada 90 dias ou conforme necessário
  • Limitação de Escopo: Use credenciais com permissões mínimas necessárias
  • Ambientes Separados: Use credenciais diferentes para desenvolvimento, homologação e produção

Política de Privacidade

Para informações detalhadas sobre como a Lumenore trata seus dados, consulte nossa Política de Privacidade.

Princípios Chave de Privacidade

  • Processamento Mínimo de Dados: Apenas processa consultas e IDs de esquema fornecidos pelos usuários
  • Sem Histórico de Conversas: Não armazena ou registra histórico de conversas
  • Controle do Usuário: Os usuários controlam quais dados são consultados e analisados
  • Conformidade: Projetado para cumprir regulamentações de proteção de dados (GDPR, CCPA)

Privacidade do Fluxo de Dados

User Query → MCP Server → Lumenore Backend → Results → User
             (No storage)   (Lumenore's privacy policy applies)

Considerações de Privacidade

  • O servidor MCP atua como um proxy seguro entre assistentes de IA e o backend da Lumenore
  • Todas as políticas de privacidade e tratamento de dados da API backend da Lumenore se aplicam aos seus dados
  • O servidor em si não retém nenhum dado do usuário além do processamento imediato da solicitação
  • Os usuários são responsáveis por garantir que suas consultas estejam em conformidade com as leis de proteção de dados aplicáveis

Conformidade

Conformidade Regulatória

  • GDPR: Em conformidade com o Regulamento Geral de Proteção de Dados
  • CCPA: Em conformidade com a Lei de Privacidade do Consumidor da Califórnia
  • SOC 2: Os serviços backend seguem os padrões de segurança SOC 2
  • ISO 27001: Melhores práticas de gestão de segurança da informação

Residência de Dados

  • O processamento de dados ocorre na infraestrutura de nuvem da Lumenore
  • Requisitos de residência de dados devem ser discutidos com a equipe de vendas da Lumenore
  • Implantações empresariais podem suportar opções de nuvem privada ou on-premise

Configuração de Segurança

Segurança do Ambiente

# Secure credentials management
export LUMENORE_CLIENT_ID="your_client_id"
export LUMENORE_SECRET="your_secret"

# Restrict file permissions
chmod 600 .env
chmod 700 /path/to/server/directory

# Use secure network connections only
# Avoid using public Wi-Fi for sensitive operations

Segurança de Produção

  • Use credenciais de cliente dedicadas para ambientes de produção
  • Implemente automação de rotação de credenciais
  • Monitore o uso da API e configure alertas para atividades incomuns
  • Considere implementar lista de permissões de IP para acesso à API
  • Use VPN ou redes privadas para comunicação do servidor

Gerenciamento de Vulnerabilidades

Reportando Problemas de Segurança

Levamos a segurança a sério. Se você encontrar uma vulnerabilidade:

  1. E-mail: askme@lumenore.com
  2. Inclua detalhes da vulnerabilidade e etapas de reprodução
  3. Reconheceremos dentro de 24 horas
  4. Trabalhe conosco para resolver o problema antes da divulgação pública

Atualizações de Segurança

  • Correções de segurança são priorizadas e implantadas rapidamente
  • Assine notificações de segurança através de nossos canais de suporte
  • Avaliações regulares de segurança são realizadas na infraestrutura

Criptografia de Dados

Em Trânsito

  • Todas as comunicações de API usam criptografia TLS 1.2+
  • HTTPS é aplicado para todas as conexões backend
  • Fixação de certificado pode ser implementada para segurança aprimorada

Em Repouso

  • O armazenamento de dados backend usa criptografia em repouso
  • A criptografia do banco de dados protege os dados analíticos armazenados
  • O gerenciamento de chaves segue as melhores práticas do setor

Controle de Acesso

Princípio do Menor Privilégio

  • As credenciais do cliente devem ter as permissões mínimas necessárias
  • Credenciais separadas para diferentes aplicações e ambientes
  • Revisão regular das permissões e do uso das credenciais

Segurança de Rede

  • As regras de firewall restringem o acesso apenas às portas necessárias
  • Considere implementar acesso via VPN para gerenciamento do servidor
  • Use segmentação de rede para implantações em produção

Solução de Problemas

Etapas Rápidas de Diagnóstico

  1. Verifique se o servidor está em execução: curl -I http://localhost:8080
  2. Confirme se o token está carregado: Verifique os logs de inicialização do servidor para o aviso "No authorization token"
  3. Teste a conectividade do backend: curl -I https://preview.lumenore.com
  4. Verifique o protocolo MCP: Garanta que o cliente esteja usando transporte Streamable HTTP

Exemplo de configuração do cliente:

{
    "server": {
        "lumenore-server": {
            "type": "streamable-http",
            "url": "http://localhost:8080/mcp",
        }
    }
}

Teste manual com Python:

from config import config
from core.lumenore_analytics import LumenoreAnalytics
import asyncio

async def test():
    client = LumenoreAnalytics()
    result = await client.make_request('get-domain', method='GET')
    print(result)

asyncio.run(test())

Obtendo Ajuda

Se você tentou as etapas acima e ainda tem problemas:

  1. Verifique os logs do servidor para mensagens de erro detalhadas
  2. Confirme a validade do token e as permissões
  3. Teste a API do backend diretamente para isolar problemas entre MCP e backend
  4. Revise a configuração do cliente MCP para transporte e configurações de URL
  5. Entre em contato com o suporte com logs e mensagens de erro (veja a seção Suporte)

Contribuindo

Aceitamos contribuições para o Lumenore Analytics MCP Server! Siga estas diretrizes:

Código de Conduta

Observe que este projeto é lançado com um Contributor Covenant. Ao participar, você concorda em cumprir este código.

Como Contribuir

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  4. Envie para o branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Configuração de Desenvolvimento

# Clone your fork
git clone <your-fork-url>
cd lumenore-mcp

# Install development dependencies
pip install -r requirements.txt

# Run tests (if available)
python -m pytest

Relatando Bugs

Use o rastreador de problemas para relatar bugs. Inclua:

  • Etapas para reproduzir
  • Comportamento esperado versus comportamento real
  • Detalhes do ambiente (versão do Python, SO)

Solicitações de Funcionalidades

Aceitamos solicitações de funcionalidades por meio do GitHub Issues. Por favor:

  • Pesquise problemas existentes primeiro
  • Forneça casos de uso claros
  • Explique a funcionalidade desejada

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Suporte

Informações de Contato

Para suporte técnico e consultas:

Versão: 1.0.0
Última Atualização: Janeiro de 2026
Python: 3.13+
Protocolo MCP: Compatível com a especificação MCP 2024-11-05