@maestro-ai/mcp-server 1.2.0 → 2.0.0

package/dist/content/skills/specialist-dados-analytics-ia/mcp_functions/generate_insights_dashboard.py

@@ -0,0 +1,669 @@
+#!/usr/bin/env python3
+"""
+Função MCP de Referência: generate_insights_dashboard
+
+Esta função serve como referência para implementação no MCP.
+NÃO EXECUTÁVEL LOCALMENTE - Apenas documentação da estrutura esperada.
+
+Propósito: Gerar dashboard completo de insights
+"""
+
+async def generate_insights_dashboard(params: dict) -> dict:
+    """
+    Gera dashboard completo de insights
+    
+    Args:
+        params: {
+            "dashboard_tool": str,                  # Ferramenta de dashboard
+            "kpi_definitions": list[dict],           # Definições de KPIs
+            "data_model": dict,                      # Modelo de dados
+            "visualization_config": dict,             # Configuração de visualização
+            "access_control": dict,                   # Controle de acesso
+            "alert_config": dict,                     # Configuração de alertas
+            "project_context": dict                  # Contexto do projeto
+        }
+    
+    Returns:
+        dict: {
+            "success": bool,                          # Status da geração
+            "dashboard_url": str,                     # URL do dashboard
+            "dashboard_config": dict,                 # Configuração do dashboard
+            "queries": list[str],                      # Queries SQL geradas
+            "visualizations": list[dict],             # Visualizações criadas
+            "setup_instructions": list[str],          # Instruções de setup
+            "validation_score": int,                  # Score de validação
+            "errors": list[dict]                      # Erros encontrados
+        }
+    """
+    
+    # IMPLEMENTAÇÃO ESPERADA NO MCP:
+    
+    dashboard_tool = params["dashboard_tool"]
+    kpi_definitions = params["kpi_definitions"]
+    data_model = params["data_model"]
+    
+    # 1. Gerar configuração base do dashboard
+    dashboard_config = await generate_dashboard_config(params)
+    
+    # 2. Gerar queries SQL para KPIs
+    queries = await generate_kpi_queries(kpi_definitions, data_model)
+    
+    # 3. Criar visualizações baseadas nos KPIs
+    visualizations = await create_visualizations(kpi_definitions, dashboard_tool)
+    
+    # 4. Configurar filtros e interatividade
+    filters_config = await configure_filters(params.get("visualization_config", {}))
+    
+    # 5. Configurar controle de acesso
+    access_config = await configure_access_control(params.get("access_control", {}))
+    
+    # 6. Configurar alertas
+    alert_config = await configure_alerts(params.get("alert_config", {}))
+    
+    # 7. Gerar instruções de setup
+    setup_instructions = await generate_setup_instructions(dashboard_tool, dashboard_config)
+    
+    # 8. Calcular score de validação
+    validation_score = calculate_dashboard_score(dashboard_config, queries, visualizations)
+    
+    # 9. Gerar URL do dashboard
+    dashboard_url = generate_dashboard_url(dashboard_tool, dashboard_config)
+    
+    return {
+        "success": True,
+        "dashboard_url": dashboard_url,
+        "dashboard_config": dashboard_config,
+        "queries": queries,
+        "visualizations": visualizations,
+        "setup_instructions": setup_instructions,
+        "validation_score": validation_score,
+        "errors": []
+    }
+
+
+# FUNÇÕES AUXILIARES (Referência)
+
+async def generate_dashboard_config(params: dict) -> dict:
+    """
+    Gera configuração base do dashboard
+    
+    Args:
+        params: Parâmetros do dashboard
+        
+    Returns:
+        dict: Configuração do dashboard
+    """
+    dashboard_tool = params["dashboard_tool"]
+    kpi_definitions = params["kpi_definitions"]
+    
+    config = {
+        "name": f"Analytics Dashboard - {params.get('project_name', 'Default')}",
+        "description": "Dashboard completo de insights e KPIs",
+        "tool": dashboard_tool,
+        "refresh_interval": params.get("refresh_interval", "5m"),
+        "theme": params.get("theme", "light"),
+        "layout": {
+            "type": "grid",
+            "columns": 12,
+            "rows": 8
+        },
+        "kpis": kpi_definitions,
+        "created_at": datetime.now().isoformat()
+    }
+    
+    # Configuração específica por ferramenta
+    if dashboard_tool == "metabase":
+        config["metabase_config"] = {
+            "database": params.get("database", "analytics"),
+            "schema": params.get("schema", "public"),
+            "collection": "analytics_collection"
+        }
+    elif dashboard_tool == "looker":
+        config["looker_config"] = {
+            "model": "analytics",
+            "view": "analytics_view",
+            "explore": "analytics_explore"
+        }
+    elif dashboard_tool == "tableau":
+        config["tableau_config"] = {
+            "datasource": "analytics_ds",
+            "workbook": "analytics_workbook"
+        }
+    
+    return config
+
+
+async def generate_kpi_queries(kpi_definitions: list[dict], data_model: dict) -> list[str]:
+    """
+    Gera queries SQL para KPIs
+    
+    Args:
+        kpi_definitions: Lista de definições de KPIs
+        data_model: Modelo de dados
+        
+    Returns:
+        list[str]: Queries SQL geradas
+    """
+    queries = []
+    
+    for kpi in kpi_definitions:
+        kpi_name = kpi["name"]
+        formula = kpi["formula"]
+        
+        # Gerar query baseada no KPI
+        if "conversao" in kpi_name.lower():
+            query = generate_conversion_query(formula, data_model)
+        elif "receita" in kpi_name.lower():
+            query = generate_revenue_query(formula, data_model)
+        elif "churn" in kpi_name.lower():
+            query = generate_churn_query(formula, data_model)
+        elif "usuarios" in kpi_name.lower():
+            query = generate_users_query(formula, data_model)
+        else:
+            query = generate_generic_kpi_query(formula, data_model)
+        
+        queries.append({
+            "kpi_name": kpi_name,
+            "query": query,
+            "description": f"Query para KPI: {kpi_name}"
+        })
+    
+    return queries
+
+
+def generate_conversion_query(formula: str, data_model: dict) -> str:
+    """Gera query para KPI de conversão"""
+    return f"""
+    -- Taxa de Conversão
+    SELECT 
+        DATE_TRUNC('month', order_date) as mes,
+        COUNT(DISTINCT c.customer_id) as visitantes_unicos,
+        COUNT(DISTINCT o.order_id) as pedidos,
+        (COUNT(DISTINCT o.order_id) * 100.0 / COUNT(DISTINCT c.customer_id)) as taxa_conversao,
+        SUM(o.total_amount) as receita_total
+    FROM {data_model.get('fact_table', 'fact_orders')} o
+    JOIN {data_model.get('dim_customer', 'dim_customer')} c ON o.customer_id = c.customer_id
+    WHERE o.order_date >= DATE_SUB(CURRENT_DATE(), INTERVAL '12 months')
+    GROUP BY DATE_TRUNC('month', o.order_date)
+    ORDER BY mes DESC
+    """
+
+
+def generate_revenue_query(formula: str, data_model: dict) -> str:
+    """Gera query para KPI de receita"""
+    return f"""
+    -- Receita Total
+    SELECT 
+        DATE_TRUNC('month', order_date) as mes,
+        COUNT(*) as total_pedidos,
+        SUM(total_amount) as receita_total,
+        AVG(total_amount) as valor_medio_pedido,
+        COUNT(DISTINCT customer_id) as clientes_unicos
+    FROM {data_model.get('fact_table', 'fact_orders')}
+    WHERE order_date >= DATE_SUB(CURRENT_DATE(), INTERVAL '12 months')
+    GROUP BY DATE_TRUNC('month', order_date)
+    ORDER BY mes DESC
+    """
+
+
+def generate_churn_query(formula: str, data_model: dict) -> str:
+    """Gera query para KPI de churn"""
+    return f"""
+    -- Taxa de Churn
+    WITH monthly_customers AS (
+        SELECT 
+            DATE_TRUNC('month', first_purchase_date) as mes,
+            COUNT(DISTINCT customer_id) as new_customers
+        FROM {data_model.get('dim_customer', 'dim_customer')}
+        WHERE first_purchase_date >= DATE_SUB(CURRENT_DATE(), INTERVAL '12 months')
+        GROUP BY DATE_TRUNC('month', first_purchase_date)
+    ),
+    customer_activity AS (
+        SELECT 
+            DATE_TRUNC('month', order_date) as mes,
+            COUNT(DISTINCT customer_id) as active_customers
+        FROM {data_model.get('fact_table', 'fact_orders')}
+        WHERE order_date >= DATE_SUB(CURRENT_DATE(), INTERVAL '12 months')
+        GROUP BY DATE_TRUNC('month', order_date)
+    )
+    SELECT 
+        m.mes,
+        m.new_customers,
+        COALESCE(a.active_customers, 0) as active_customers,
+        CASE 
+            WHEN LAG(a.active_customers) OVER (ORDER BY m.mes) IS NULL THEN 0
+            ELSE (1 - (COALESCE(a.active_customers, 0) * 1.0 / LAG(a.active_customers) OVER (ORDER BY m.mes))) * 100
+        END as churn_rate
+    FROM monthly_customers m
+    LEFT JOIN customer_activity a ON m.mes = a.mes
+    ORDER BY m.mes DESC
+    """
+
+
+def generate_users_query(formula: str, data_model: dict) -> str:
+    """Gera query para KPI de usuários"""
+    return f"""
+    -- Usuários Ativos
+    SELECT 
+        DATE_TRUNC('day', event_timestamp) as dia,
+        COUNT(DISTINCT user_id) as usuarios_unicos,
+        COUNT(*) as total_eventos,
+        COUNT(DISTINCT session_id) as sessoes_unicas
+    FROM {data_model.get('fact_table', 'fact_events')}
+    WHERE event_timestamp >= DATE_SUB(CURRENT_DATE(), INTERVAL '30 days')
+    GROUP BY DATE_TRUNC('day', event_timestamp)
+    ORDER BY dia DESC
+    """
+
+
+def generate_generic_kpi_query(formula: str, data_model: dict) -> str:
+    """Gera query genérica para KPI"""
+    return f"""
+    -- Query Genérica para KPI
+    SELECT 
+        DATE_TRUNC('month', created_at) as mes,
+        COUNT(*) as total_registros,
+        COUNT(DISTINCT id) as registros_unicos
+    FROM {data_model.get('fact_table', 'fact_analytics')}
+    WHERE created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL '12 months')
+    GROUP BY DATE_TRUNC('month', created_at)
+    ORDER BY mes DESC
+    """
+
+
+async def create_visualizations(kpi_definitions: list[dict], dashboard_tool: str) -> list[dict]:
+    """
+    Cria visualizações baseadas nos KPIs
+    
+    Args:
+        kpi_definitions: Lista de definições de KPIs
+        dashboard_tool: Ferramenta de dashboard
+        
+    Returns:
+        list[dict]: Visualizações criadas
+    """
+    visualizations = []
+    
+    for i, kpi in enumerate(kpi_definitions):
+        kpi_name = kpi["name"]
+        
+        # Determinar tipo de visualização baseado no KPI
+        if "tendência" in kpi_name.lower() or "growth" in kpi_name.lower():
+            viz_type = "line_chart"
+        elif "comparação" in kpi_name.lower() or "comparison" in kpi_name.lower():
+            viz_type = "bar_chart"
+        elif "distribuição" in kpi_name.lower() or "distribution" in kpi_name.lower():
+            viz_type = "pie_chart"
+        elif "mapa" in kpi_name.lower() or "geográfico" in kpi_name.lower():
+            viz_type = "map"
+        else:
+            viz_type = "kpi_card"
+        
+        visualization = {
+            "id": f"viz_{i+1}",
+            "name": f"{kpi_name} Visualization",
+            "type": viz_type,
+            "kpi_name": kpi_name,
+            "position": {
+                "x": (i % 3) * 4,
+                "y": (i // 3) * 2,
+                "width": 4,
+                "height": 2
+            },
+            "config": generate_viz_config(viz_type, kpi, dashboard_tool)
+        }
+        
+        visualizations.append(visualization)
+    
+    return visualizations
+
+
+def generate_viz_config(viz_type: str, kpi: dict, dashboard_tool: str) -> dict:
+    """Gera configuração específica da visualização"""
+    
+    base_config = {
+        "title": kpi["name"],
+        "subtitle": kpi.get("description", ""),
+        "target": kpi.get("target", ""),
+        "frequency": kpi.get("frequency", "Diário")
+    }
+    
+    if viz_type == "line_chart":
+        base_config.update({
+            "x_axis": "time",
+            "y_axis": "value",
+            "trend_line": True,
+            "comparison": True
+        })
+    elif viz_type == "bar_chart":
+        base_config.update({
+            "x_axis": "category",
+            "y_axis": "value",
+            "sort": "desc",
+            "limit": 10
+        })
+    elif viz_type == "pie_chart":
+        base_config.update({
+            "value_field": "value",
+            "label_field": "category",
+            "show_percentage": True,
+            "legend": True
+        })
+    elif viz_type == "kpi_card":
+        base_config.update({
+            "value_format": "number",
+            "show_trend": True,
+            "show_comparison": True,
+            "color_scheme": "default"
+        })
+    
+    return base_config
+
+
+async def configure_filters(visualization_config: dict) -> dict:
+    """
+    Configura filtros e interatividade
+    
+    Args:
+        visualization_config: Configuração de visualização
+        
+    Returns:
+        dict: Configuração de filtros
+    """
+    return {
+        "date_range": {
+            "type": "date_range",
+            "default": "last_30_days",
+            "options": ["last_7_days", "last_30_days", "last_90_days", "custom_range"]
+        },
+        "category_filter": {
+            "type": "multi_select",
+            "field": "category",
+            "default": "all",
+            "options": visualization_config.get("categories", [])
+        },
+        "segment_filter": {
+            "type": "single_select",
+            "field": "segment",
+            "default": "all",
+            "options": visualization_config.get("segments", [])
+        },
+        "region_filter": {
+            "type": "multi_select",
+            "field": "region",
+            "default": "all",
+            "options": visualization_config.get("regions", [])
+        }
+    }
+
+
+async def configure_access_control(access_control: dict) -> dict:
+    """
+    Configura controle de acesso
+    
+    Args:
+        access_control: Configuração de acesso
+        
+    Returns:
+        dict: Configuração de acesso
+    """
+    return {
+        "authentication": {
+            "enabled": access_control.get("authentication", True),
+            "method": access_control.get("auth_method", "oauth"),
+            "providers": access_control.get("auth_providers", ["google", "microsoft"])
+        },
+        "authorization": {
+            "enabled": access_control.get("authorization", True),
+            "rbac": access_control.get("rbac", True),
+            "roles": {
+                "admin": {
+                    "permissions": ["read", "write", "delete", "admin"],
+                    "access_level": "all"
+                },
+                "analyst": {
+                    "permissions": ["read", "write"],
+                    "access_level": "all"
+                },
+                "viewer": {
+                    "permissions": ["read"],
+                    "access_level": "restricted"
+                }
+            }
+        },
+        "data_security": {
+            "row_level_security": access_control.get("row_level_security", True),
+            "column_level_security": access_control.get("column_level_security", True),
+            "data_masking": access_control.get("data_masking", True)
+        }
+    }
+
+
+async def configure_alerts(alert_config: dict) -> dict:
+    """
+    Configura alertas
+    
+    Args:
+        alert_config: Configuração de alertas
+        
+    Returns:
+        dict: Configuração de alertas
+    """
+    return {
+        "enabled": alert_config.get("enabled", True),
+        "channels": {
+            "email": {
+                "enabled": alert_config.get("email_enabled", True),
+                "recipients": alert_config.get("email_recipients", []),
+                "template": "default"
+            },
+            "slack": {
+                "enabled": alert_config.get("slack_enabled", False),
+                "webhook": alert_config.get("slack_webhook", ""),
+                "channel": alert_config.get("slack_channel", "#analytics-alerts")
+            },
+            "webhook": {
+                "enabled": alert_config.get("webhook_enabled", False),
+                "url": alert_config.get("webhook_url", ""),
+                "headers": alert_config.get("webhook_headers", {})
+            }
+        },
+        "rules": [
+            {
+                "name": "KPI Threshold Breach",
+                "condition": "kpi_value > threshold OR kpi_value < threshold",
+                "severity": "warning",
+                "cooldown": "5m"
+            },
+            {
+                "name": "Data Quality Issue",
+                "condition": "data_quality_score < 90",
+                "severity": "critical",
+                "cooldown": "1m"
+            },
+            {
+                "name": "Dashboard Performance",
+                "condition": "load_time > 10s",
+                "severity": "warning",
+                "cooldown": "10m"
+            }
+        ]
+    }
+
+
+async def generate_setup_instructions(dashboard_tool: str, dashboard_config: dict) -> list[str]:
+    """
+    Gera instruções de setup
+    
+    Args:
+        dashboard_tool: Ferramenta de dashboard
+        dashboard_config: Configuração do dashboard
+        
+    Returns:
+        list[str]: Instruções de setup
+    """
+    instructions = []
+    
+    if dashboard_tool == "metabase":
+        instructions.extend([
+            "1. Acesse o Metabase em http://localhost:3000",
+            "2. Faça login com suas credenciais",
+            "3. Configure a conexão com o banco de dados",
+            "4. Importe as queries SQL geradas",
+            "5. Crie as visualizações usando o editor visual",
+            "6. Configure os filtros e parâmetros",
+            "7. Configure o agendamento de atualização",
+            "8. Compartilhe o dashboard com os usuários"
+        ])
+    elif dashboard_tool == "looker":
+        instructions.extend([
+            "1. Acesse o Looker em https://looker.empresa.com",
+            "2. Configure o projeto e modelo de dados",
+            "3. Importe as views e explores",
+            "4. Crie os dashboards usando o LookML",
+            "5. Configure os filtros e parâmetros",
+            "6. Configure os schedules de atualização",
+            "7. Configure as permissões de acesso",
+            "8. Teste o dashboard com usuários"
+        ])
+    elif dashboard_tool == "tableau":
+        instructions.extend([
+            "1. Abra o Tableau Desktop",
+            "2. Conecte-se à fonte de dados",
+            "3. Importe as queries SQL",
+            "4. Crie as visualizações arrastando campos",
+            "5. Configure os filtros e parâmetros",
+            "6. Crie o dashboard com múltiplas visualizações",
+            "7. Configure as ações e interatividade",
+            "8. Publique no Tableau Server"
+        ])
+    
+    instructions.extend([
+        "9. Configure os alertas e notificações",
+        "10. Teste todas as funcionalidades",
+        "11. Documente o dashboard",
+        "12. Treine os usuários finais"
+    ])
+    
+    return instructions
+
+
+def calculate_dashboard_score(dashboard_config: dict, queries: list, visualizations: list) -> int:
+    """
+    Calcula score de validação do dashboard
+    
+    Args:
+        dashboard_config: Configuração do dashboard
+        queries: Queries geradas
+        visualizations: Visualizações criadas
+        
+    Returns:
+        int: Score de validação
+    """
+    score = 0
+    max_score = 100
+    
+    # Configuração completa (20 pontos)
+    if dashboard_config.get("name") and dashboard_config.get("tool"):
+        score += 20
+    
+    # Queries válidas (25 pontos)
+    if queries and len(queries) > 0:
+        score += 25
+    
+    # Visualizações criadas (25 pontos)
+    if visualizations and len(visualizations) > 0:
+        score += 25
+    
+    # Filtros configurados (15 pontos)
+    if dashboard_config.get("filters_config"):
+        score += 15
+    
+    # Acesso configurado (15 pontos)
+    if dashboard_config.get("access_config"):
+        score += 15
+    
+    return score
+
+
+def generate_dashboard_url(dashboard_tool: str, dashboard_config: dict) -> str:
+    """
+    Gera URL do dashboard
+    
+    Args:
+        dashboard_tool: Ferramenta de dashboard
+        dashboard_config: Configuração do dashboard
+        
+    Returns:
+        str: URL do dashboard
+    """
+    base_urls = {
+        "metabase": "http://localhost:3000/dashboard/",
+        "looker": "https://looker.empresa.com/dashboards/",
+        "tableau": "https://tableau.empresa.com/views/"
+    }
+    
+    dashboard_id = dashboard_config.get("id", "1")
+    base_url = base_urls.get(dashboard_tool, "http://localhost:3000/dashboard/")
+    
+    return f"{base_url}{dashboard_id}"
+
+
+# EXEMPLO DE USO
+
+if __name__ == "__main__":
+    """
+    Exemplo de como a função seria chamada no MCP:
+    
+    result = await generate_insights_dashboard({
+        "dashboard_tool": "metabase",
+        "kpi_definitions": [
+            {
+                "name": "Taxa de Conversão",
+                "formula": "(pedidos ÷ visitas) × 100",
+                "target": "3.5%",
+                "frequency": "Diário"
+            },
+            {
+                "name": "Receita Total",
+                "formula": "SUM(total_amount)",
+                "target": "R$ 50.000",
+                "frequency": "Diário"
+            }
+        ],
+        "data_model": {
+            "fact_table": "fact_orders",
+            "dim_customer": "dim_customer",
+            "dim_product": "dim_product"
+        },
+        "visualization_config": {
+            "categories": ["Eletrônicos", "Roupas", "Alimentos"],
+            "segments": ["Premium", "Standard", "Basic"],
+            "regions": ["São Paulo", "Rio", "Brasília"]
+        },
+        "access_control": {
+            "authentication": True,
+            "authorization": True,
+            "rbac": True
+        },
+        "alert_config": {
+            "enabled": True,
+            "email_enabled": True,
+            "slack_enabled": False
+        },
+        "project_context": {
+            "project_name": "E-commerce Analytics",
+            "industry": "e-commerce"
+        }
+    })
+    
+    print(f"Dashboard Generated: {result['success']}")
+    print(f"Dashboard URL: {result['dashboard_url']}")
+    print(f"Queries Generated: {len(result['queries'])}")
+    print(f"Visualizations: {len(result['visualizations'])}")
+    print(f"Validation Score: {result['validation_score']}")
+    """
+    
+    print("Esta é uma função de referência para implementação no MCP.")
+    print("NÃO EXECUTÁVEL LOCALMENTE.")
+    print("Consulte MCP_INTEGRATION.md para detalhes de implementação.")