Lumenore-MCP

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA acceso a las capacidades de análisis y consulta en lenguaje natural de Lumenore. Construido con FastMCP y Python 3.13 para una integración escalable de análisis de datos.

GitHub

Documentación

Servidor MCP de Analítica Lumenore

License Python MCP Contributor Covenant

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA acceso a las capacidades de analítica y consultas en lenguaje natural de Lumenore. Construido con FastMCP y Python 3.13 para una integración escalable de analítica de datos.

Inicio Rápido

1. Instalar y Ejecutar

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. Conecta Tu Asistente de IA

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

3. Comienza a Analizar

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

📖 Documentación Completa | 🐛 Reportar Problemas | 🔒 Política de Privacidad

Tabla de Contenidos

Descripción General

Este servidor MCP proporciona a los asistentes de IA acceso a las potentes capacidades de analítica de Lumenore:

  • Consultas en Lenguaje Natural: Convierte preguntas en información de datos
  • Analítica Avanzada: Tendencias, predicciones, correlaciones, valores atípicos, cambios, análisis de Pareto
  • Procesamiento en Tiempo Real: Transmite respuestas para grandes conjuntos de datos
  • Cero Almacenamiento de Datos: Procesamiento en memoria sin registro persistente. Cuando el Servidor MCP reenvía solicitudes al backend de Lumenore, se aplican las políticas de privacidad de Lumenore

Instalación

Requisitos Previos

  • Python 3.13+
  • Credenciales de cliente de Lumenore (ID de cliente y secreto)
  • Acceso a la instancia del servidor de Lumenore

Configuración

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

Configuración

Crea un archivo .env en la raíz del proyecto con tus credenciales. Puedes usar .env.example como plantilla:

cp .env.example .env

Luego edita .env con tu configuración:

Usando Credenciales de Cliente

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

Parámetros de Configuración

ParámetroRequeridoDescripciónPredeterminado
LUMENORE_CLIENT_IDSíID de cliente para autenticación de credenciales de clienteNinguno
LUMENORE_SECRETSíSecreto de cliente para autenticación de credenciales de clienteNinguno
SERVER_URLNoURL del servidor de Lumenorehttps://preview.lumenore.com

Ejecutando el Servidor

Inicia el servidor MCP:

python main.py

El servidor se ejecuta en http://0.0.0.0:8080 con transporte SSE para transmisión en tiempo real.

Conectando Tu Asistente de IA

Claude para Escritorio

  1. Configuración → Servidores MCP
  2. Agregar Servidor con: 
    Name: Lumenore Analytics
URL: http://localhost:8080/mcp
Transport: Streamable HTTP

Acceso 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
})

Detalles de Conexión:

  • Protocolo: MCP 2024-11-05+
  • Transporte: HTTP Transmisible (SSE)
  • Puerto: 8080 (predeterminado)
  • Autenticación: No se requiere autenticación a nivel MCP

Probar Conexión:

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

Autenticación

Obteniendo Tus Credenciales

Credenciales de Cliente

  1. Contacta al soporte de Lumenore para obtener credenciales de cliente
  2. Recibe tu LUMENORE_CLIENT_ID y LUMENORE_SECRET
  3. Almacena de forma segura en tu archivo .env

Consulta la sección de Configuración para instrucciones detalladas de configuración.

Mejores Prácticas de Seguridad

Solución de Problemas de Autenticación

"Token de autorización faltante o inválido":

  • Verifica que las credenciales estén configuradas en el archivo .env:
    • Para credenciales de cliente: Verifica que tanto LUMENORE_CLIENT_ID como LUMENORE_SECRET estén configurados
  • Asegúrate de que los créditos de IA de Lumenore estén disponibles
  • Verifica que SERVER_URL apunte a la instancia correcta de Lumenore

Herramientas Disponibles

El servidor proporciona 8 potentes herramientas para análisis de datos:

Gestión de Conjuntos de Datos

get_dataset_metadata - Lista los conjuntos de datos disponibles y los IDs de esquema

Consultas en Lenguaje Natural

nlq_to_data - Convierte preguntas en datos estructurados

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

Analítica Avanzada

get_trend_data - Identifica patrones y tendencias temporales get_prediction_data - Genera pronósticos y predicciones get_outlier_data - Detecta anomalías y patrones inusuales get_correlation_data - Analiza relaciones entre variables get_change_data - Detecta cambios y transiciones de patrones get_pareto_data - Realiza análisis de impacto 80/20

Manejo de Errores

Todas las herramientas devuelven respuestas estandarizadas:

  • Éxito: {"data": {...}, "status": "success"}
  • Error de Validación: {"error": "...", "status": "validation_error"}
  • Error de Servicio: {"error": "...", "status": "error"}

Rendimiento

  • Tiempo de Respuesta: 1-7 segundos
  • Tiempo de Espera: 60 segundos
  • Concurrencia: Se admiten múltiples solicitudes simultáneas

Mejores Prácticas

  1. Comienza con get_dataset_metadata para encontrar IDs de esquema
  2. Sé específico en las consultas en lenguaje natural
  3. Siempre verifica el campo status en las respuestas
  4. Almacena en caché consultas frecuentes para mejor rendimiento

Ejemplos de Uso

Aquí hay tres ejemplos realistas que muestran cómo los asistentes de IA pueden interactuar con el Servidor MCP de Analítica Lumenore:

Ejemplo 1: Análisis de Rendimiento de Ventas

Escenario: Un analista de negocios quiere entender el rendimiento de ventas del último trimestre.

Interacción del Asistente 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
})

Información Esperada:

  • Desglose de ventas regional con totales
  • Visualización de tendencia mensual que muestra crecimiento/disminución
  • Análisis de contribución de productos destacando los principales impulsores de ingresos

Ejemplo 2: Análisis de Comportamiento del Cliente

Escenario: Un equipo de marketing quiere entender los patrones de compra de los clientes y detectar anomalías.

Interacción del Asistente 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
})

Información Esperada:

  • Segmentación de clientes por demografía y gasto
  • Identificación de posibles fraudes o clientes VIP
  • Principales impulsores del valor del cliente para marketing dirigido

Ejemplo 3: Optimización de Inventario

Escenario: Un gerente de operaciones necesita optimizar los niveles de inventario basándose en patrones de demanda y pronósticos.

Interacción del Asistente 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
})

Información Esperada:

  • Patrones históricos de demanda por categoría
  • Pronósticos de demanda futura con intervalos de confianza
  • Advertencia temprana de cambios en patrones de demanda
  • Recomendaciones de optimización de inventario basadas en datos

Beneficios:

  • Actualización automática de datos sin intervención manual
  • Información en tiempo real para la toma de decisiones operativas
  • Carga reducida en sistemas backend mediante almacenamiento en caché eficiente

Mejores Prácticas de los Ejemplos

  1. Comienza con Metadatos: Siempre usa get_dataset_metadata para entender los conjuntos de datos disponibles
  2. Combina Herramientas: Usa múltiples herramientas juntas para un análisis integral
  3. Consultas Específicas: Sé claro y específico en las consultas en lenguaje natural
  4. Manejo de Errores: Siempre verifica el estado de la respuesta antes de procesar resultados
  5. Rendimiento: Almacena en caché los datos de acceso frecuente para mejorar los tiempos de respuesta

Prompts de Claude

Aquí hay ejemplos de prompts que puedes usar con Claude cuando esté conectado a este servidor MCP:

Para Análisis de Ventas:

"Usa las herramientas de Analítica Lumenore para analizar nuestro rendimiento de ventas del cuarto trimestre. Necesito ver desgloses regionales, identificar los productos de mejor rendimiento y entender las tendencias de ventas."

Para Información del Cliente:

"Analiza la demografía de los clientes, encuentra cualquier patrón de compra inusual e identifica qué factores impulsan el valor del cliente. Usa las herramientas de analítica disponibles para proporcionar información integral."

Para Gestión de Inventario:

"Genera pronósticos para el próximo trimestre e identifica cualquier cambio reciente en el comportamiento de la demanda usando las herramientas de análisis predictivo y de tendencias."

Manejo de Errores

Todas las herramientas implementan un manejo integral de errores con tipos de error 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>
}

Probando el Servidor

Puedes probar el servidor MCP usando cualquier cliente compatible con MCP o haciendo solicitudes HTTP al endpoint SSE:

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

Seguridad y Privacidad

Descripción General de Seguridad

El Servidor MCP de Analítica Lumenore implementa múltiples capas de seguridad para proteger tus datos y credenciales de API:

Protección de Datos

  • Procesamiento en Memoria: Todos los datos se procesan en memoria y se descartan inmediatamente después de generar la respuesta
  • Sin Almacenamiento de Datos: El servidor MCP no almacena ni registra consultas de usuarios, IDs de esquema o datos de respuesta
  • Comunicación Segura: Todas las solicitudes de API backend usan cifrado HTTPS
  • Seguridad de Credenciales: Las credenciales de cliente nunca se registran, almacenan o exponen en las respuestas

Seguridad de Autenticación

  • Flujo de Credenciales de Cliente: Autenticación estándar de la industria usando ID de cliente y secreto
  • Gestión de Sesiones: Manejo seguro de sesiones basado en cookies con renovación automática de tokens
  • Sin Autenticación a Nivel MCP: La conexión MCP no requiere autenticación (la autenticación del backend se maneja del lado del servidor)
  • Monitoreo de Seguridad: Los intentos de autenticación fallidos se registran para análisis de seguridad

Mejores Prácticas de Credenciales

  • Variables de Entorno: Almacena credenciales en variables de entorno o archivos .env (nunca en código)
  • Rotación Regular: Rota las credenciales cada 90 días o según sea necesario
  • Limitación de Alcance: Usa credenciales con los permisos mínimos requeridos
  • Entornos Separados: Usa diferentes credenciales para desarrollo, pruebas y producción

Política de Privacidad

Para información detallada sobre cómo Lumenore maneja tus datos, consulta nuestra Política de Privacidad.

Principios Clave de Privacidad

  • Procesamiento Mínimo de Datos: Solo procesa consultas e IDs de esquema proporcionados por los usuarios
  • Sin Historial de Conversaciones: No almacena ni registra el historial de conversaciones
  • Control del Usuario: Los usuarios controlan qué datos se consultan y analizan
  • Cumplimiento: Diseñado para cumplir con las regulaciones de protección de datos (GDPR, CCPA)

Privacidad del Flujo de Datos

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

Consideraciones de Privacidad

  • El servidor MCP actúa como un proxy seguro entre los asistentes de IA y el backend de Lumenore
  • Todas las políticas de privacidad y manejo de datos de la API backend de Lumenore se aplican a tus datos
  • El servidor en sí no retiene ningún dato de usuario más allá del procesamiento inmediato de la solicitud
  • Los usuarios son responsables de asegurar que sus consultas cumplan con las leyes de protección de datos aplicables

Cumplimiento

Cumplimiento Regulatorio

  • GDPR: Cumple con el Reglamento General de Protección de Datos
  • CCPA: Cumple con la Ley de Privacidad del Consumidor de California
  • SOC 2: Los servicios backend siguen los estándares de seguridad SOC 2
  • ISO 27001: Mejores prácticas de gestión de seguridad de la información

Residencia de Datos

  • El procesamiento de datos ocurre en la infraestructura en la nube de Lumenore
  • Los requisitos de residencia de datos deben discutirse con el equipo de ventas de Lumenore
  • Los despliegues empresariales pueden admitir opciones de nube privada o local

Configuración de Seguridad

Seguridad del Entorno

# 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

Seguridad de Producción

  • Usa credenciales de cliente dedicadas para entornos de producción
  • Implementa automatización de rotación de credenciales
  • Monitorea el uso de API y configura alertas para actividad inusual
  • Considera implementar listas blancas de IP para acceso a API
  • Usa VPN o redes privadas para la comunicación del servidor

Gestión de Vulnerabilidades

Reportando Problemas de Seguridad

Nos tomamos la seguridad en serio. Si encuentras una vulnerabilidad:

  1. Correo electrónico: askme@lumenore.com
  2. Incluye detalles de la vulnerabilidad y pasos de reproducción
  3. Te responderemos dentro de las 24 horas
  4. Trabaja con nosotros para resolver el problema antes de la divulgación pública

Actualizaciones de Seguridad

  • Los parches de seguridad se priorizan y despliegan rápidamente
  • Suscríbete a notificaciones de seguridad a través de nuestros canales de soporte
  • Se realizan evaluaciones de seguridad regulares en la infraestructura

Cifrado de Datos

En Tránsito

  • Todas las comunicaciones de API usan cifrado TLS 1.2+
  • HTTPS se aplica para todas las conexiones backend
  • Se puede implementar fijación de certificados para mayor seguridad

En Reposo

  • El almacenamiento de datos backend usa cifrado en reposo
  • El cifrado de la base de datos protege los datos analíticos almacenados
  • La gestión de claves sigue las mejores prácticas de la industria

Control de Acceso

Principio de Mínimo Privilegio

  • Las credenciales del cliente deben tener los permisos mínimos requeridos
  • Credenciales separadas para diferentes aplicaciones y entornos
  • Revisión periódica de los permisos y el uso de las credenciales

Seguridad de Red

  • Las reglas del firewall restringen el acceso solo a los puertos necesarios
  • Considere implementar acceso VPN para la gestión del servidor
  • Use segmentación de red para implementaciones de producción

Solución de Problemas

Pasos Rápidos de Diagnóstico

  1. Verifique que el servidor esté en ejecución: curl -I http://localhost:8080
  2. Verifique que el token esté cargado: Revise los registros de inicio del servidor para ver la advertencia "No authorization token"
  3. Pruebe la conectividad del backend: curl -I https://preview.lumenore.com
  4. Verifique el protocolo MCP: Asegúrese de que el cliente use transporte Streamable HTTP

Ejemplo de configuración del cliente:

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

Pruebas manuales con 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())

Obtención de Ayuda

Si ha probado los pasos anteriores y aún tiene problemas:

  1. Revise los registros del servidor para ver mensajes de error detallados
  2. Verifique la validez del token y sus permisos
  3. Pruebe la API del backend directamente para aislar problemas de MCP frente a problemas del backend
  4. Revise la configuración del cliente MCP para verificar la configuración de transporte y URL
  5. Contacte al soporte con los registros y mensajes de error (consulte la sección Soporte)

Contribuciones

¡Damos la bienvenida a contribuciones al Servidor MCP de Lumenore Analytics! Siga estas pautas:

Código de Conducta

Tenga en cuenta que este proyecto se publica con un Contributor Covenant. Al participar, se espera que cumpla con este código.

Cómo Contribuir

  1. Haga un fork del repositorio
  2. Cree una rama de funcionalidad (git checkout -b feature/amazing-feature)
  3. Confirme sus cambios (git commit -m 'Add amazing feature')
  4. Empuje a la rama (git push origin feature/amazing-feature)
  5. Abra una Solicitud de Extracción (Pull Request)

Configuración de Desarrollo

# 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

Reporte de Errores

Use el rastreador de problemas para reportar errores. Incluya:

  • Pasos para reproducir
  • Comportamiento esperado frente al real
  • Detalles del entorno (versión de Python, sistema operativo)

Solicitudes de Funcionalidades

Damos la bienvenida a solicitudes de funcionalidades a través de GitHub Issues. Por favor:

  • Busque problemas existentes primero
  • Proporcione casos de uso claros
  • Explique la funcionalidad deseada

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENSE para más detalles.

Soporte

Información de Contacto

Para soporte técnico y consultas:

Versión: 1.0.0
Última actualización: enero de 2026
Python: 3.13+
Protocolo MCP: Compatible con la especificación MCP 2024-11-05