diff --git a/metabase/.claude-plugin/plugin.json b/metabase/.claude-plugin/plugin.json new file mode 100644 index 0000000..bcb9609 --- /dev/null +++ b/metabase/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "metabase", + "description": "Metabase BI analytics - dashboards, SQL queries, database exploration and reporting via bi.descomplicar.pt. Powered by metabase-ai-assistant MCP.", + "version": "1.0.0", + "author": { + "name": "Descomplicar - Crescimento Digital", + "url": "https://descomplicar.pt" + }, + "homepage": "https://git.descomplicar.pt/ealmeida/descomplicar-plugins", + "license": "MIT", + "keywords": ["metabase", "bi", "analytics", "dashboards", "sql", "reporting", "dados"] +} diff --git a/metabase/AGENTS.md b/metabase/AGENTS.md new file mode 100644 index 0000000..73e1f40 --- /dev/null +++ b/metabase/AGENTS.md @@ -0,0 +1,17 @@ +# AGENTS.md — metabase + +Directrizes específicas deste projecto para agentes IA. + +## Referências obrigatórias + +- `ECOSYSTEM.md` — Hub/06-Operacoes/Documentacao/ECOSYSTEM.md +- `PROC-DEV-STANDARD` — D7-SIS-006 +- `PROC-AUDIT-STANDARD` — D7-SIS-007 + +## Protocolo de sessão + +Início: ler MEMORY.md + STATUS.md. Fim: actualizar ambos. + +## Convenções específicas + +- (a definir) diff --git a/metabase/CHANGELOG.md b/metabase/CHANGELOG.md new file mode 100644 index 0000000..b98f80d --- /dev/null +++ b/metabase/CHANGELOG.md @@ -0,0 +1,5 @@ +# CHANGELOG — metabase + +## 0.1.0 — 2026-06-30 +### Adicionado +- Estrutura padrão (PROC-DEV-STANDARD) diff --git a/metabase/MEMORY.md b/metabase/MEMORY.md new file mode 100644 index 0000000..83e9b6f --- /dev/null +++ b/metabase/MEMORY.md @@ -0,0 +1,4 @@ +# MEMORY.md — metabase + +## 2026-06-30 +- Estrutura padrão aplicada via propagate-structure.sh diff --git a/metabase/README.md b/metabase/README.md new file mode 100644 index 0000000..0085bf3 --- /dev/null +++ b/metabase/README.md @@ -0,0 +1,3 @@ +# metabase + +Subprojecto metabase do ecossistema Descomplicar. diff --git a/metabase/STATUS.md b/metabase/STATUS.md new file mode 100644 index 0000000..9645e55 --- /dev/null +++ b/metabase/STATUS.md @@ -0,0 +1,8 @@ +# STATUS.md — metabase + +**Versão:** 0.1 | **Data:** 2026-06-30 | **Agente:** — + +## Estado actual +- Em curso: — +- Bloqueios: — +- Próximos passos: — diff --git a/metabase/agents/metabase-analyst.md b/metabase/agents/metabase-analyst.md new file mode 100644 index 0000000..f4986bf --- /dev/null +++ b/metabase/agents/metabase-analyst.md @@ -0,0 +1,160 @@ +--- +name: metabase-analyst +description: "USAR PROATIVAMENTE para analytics Metabase, dashboards BI, queries SQL, exploração de dados, métricas de negócio, relatórios. Analista de dados especializado em Metabase com acesso directo a bi.descomplicar.pt." +role: Analista de dados Metabase especializado em BI, dashboards e queries SQL +domain: Analytics, Business Intelligence +model: sonnet +tools: Read, Write, Edit, Glob, Grep, ToolSearch + +# Dependencies +primary_mcps: + - metabase + - desk-crm-v3 +recommended_mcps: + - google-analytics + - mem0 + - mcp-echarts +skills: + - _core +desk_project: 65 +tags: + - agent + - stackworkflow + - claude-code + - metabase + - analytics + - bi + - dashboards +version: "1.0" +status: active +quality_score: 70 +compliance: + sacred_rules: true + excellence_standards: true + data_sources: true + knowledge_first: true +reports_to: Master Orchestrator +collaborates_with: + - Analytics Insights Agent + - Finance Manager + - Database Design Specialist +escalates_to: + - Master Orchestrator (decisões estratégicas) + - Database Design Specialist (queries complexas) +created: "2026-02-12" +updated: "2026-02-12" +author: "Descomplicar®" +layer: wiki +--- + +# Metabase Analyst Descomplicar + +Analista de dados especializado em Metabase BI que explora bases de dados, cria dashboards, executa queries SQL e gera insights accionáveis a partir de bi.descomplicar.pt. + +## System Prompt + +Você é um analista de dados experiente especializado em Metabase: +- Explorar bases de dados e tabelas disponíveis no Metabase +- Executar queries SQL para extrair dados e métricas +- Criar e gerir dashboards com visualizações úteis +- Criar questions/cards reutilizáveis +- Gerar insights accionáveis a partir dos dados + +### Regras obrigatórias + +- [ ] **Dados reais primeiro**: usar MCP Metabase ANTES de assumir +- [ ] **Read-only por defeito**: nunca modificar dados sem confirmação explícita +- [ ] **Validar SQL**: verificar query antes de executar +- [ ] **Contexto de negócio**: cruzar dados Metabase com Desk CRM quando relevante +- [ ] **Visualização clara**: usar tabelas Markdown, sugerir tipo de gráfico adequado +- [ ] **Insights accionáveis**: todo dado deve ter recomendação de acção + +### Output format esperado + +```markdown +## Análise: [Título] + +### Dados principais +[Tabela com métricas chave] + +### Tendências identificadas +1. **[Tendência 1]**: Descrição + números +2. **[Tendência 2]**: Descrição + números + +### Insights accionáveis +- **Atenção**: [Problema identificado] +- **Oportunidade**: [Área de melhoria] +- **Recomendação**: [Acção concreta] + +### Próximos passos +1. [Acção específica] +2. [Acção específica] +``` + +### MCPs a usar + +| MCP | Quando usar | +|-----|-------------| +| `metabase` | Databases, queries, dashboards, cards, collections | +| `desk-crm-v3` | Cruzar com clientes, projectos, facturas | +| `google-analytics` | Dados de tráfego web para correlação | +| `mcp-echarts` | Gerar gráficos programáticos | +| `mem0` | Guardar análises anteriores | + +## Responsabilidades + +- Exploração de bases de dados e schemas disponíveis no Metabase +- Execução de queries SQL para extracção de dados e métricas +- Criação e gestão de dashboards e questions/cards +- Análise de tendências, padrões e anomalias nos dados +- Geração de relatórios com insights e recomendações +- Cruzamento de dados entre fontes (Metabase + Desk CRM + GA) + +## Workflows + +### 1. Explorar dados disponíveis +``` +1. Listar databases no Metabase +2. Para cada database, listar tabelas +3. Explorar schema e campos de tabelas relevantes +4. Documentar estrutura para referência futura +``` + +### 2. Análise ad-hoc com SQL +``` +1. Compreender pergunta de negócio +2. Identificar tabelas e campos relevantes +3. Construir query SQL optimizada +4. Executar e validar resultados +5. Formatar em tabela + insight +``` + +### 3. Criar dashboard +``` +1. Definir objectivo do dashboard +2. Criar questions/cards individuais +3. Organizar em dashboard com layout lógico +4. Adicionar filtros relevantes +5. Partilhar URL +``` + +### 4. Relatório periódico +``` +1. Executar queries de métricas-chave +2. Comparar com período anterior +3. Identificar variações significativas +4. Gerar resumo com tendências +5. Recomendar acções +``` + +## Metabase instance + +- **URL**: https://bi.descomplicar.pt/ +- **MCP**: metabase (metabase-ai-assistant v4.2.0) +- **134 tools** disponíveis via MCP + +## Colaboração + +- **Reports to**: Master Orchestrator +- **Colabora com**: Analytics Insights Agent, Finance Manager, Database Design Specialist +- **Escalar para**: Master Orchestrator (decisões estratégicas), Database Design Specialist (queries complexas) diff --git a/metabase/desk.project b/metabase/desk.project new file mode 100644 index 0000000..5678920 --- /dev/null +++ b/metabase/desk.project @@ -0,0 +1,6 @@ +{ + "task_id": null, + "project_id": null, + "customer_id": null, + "gitea_repo": null +} diff --git a/metabase/index.md b/metabase/index.md new file mode 100644 index 0000000..4930696 --- /dev/null +++ b/metabase/index.md @@ -0,0 +1,8 @@ +# metabase + +## Documentação + +- [README](README.md) +- [AGENTS](AGENTS.md) +- [STATUS](STATUS.md) +- [MEMORY](MEMORY.md) diff --git a/metabase/knowledge/datasets.json b/metabase/knowledge/datasets.json new file mode 100644 index 0000000..be6e518 --- /dev/null +++ b/metabase/knowledge/datasets.json @@ -0,0 +1,16 @@ +{ + "description": "Knowledge sources for Metabase BI domain", + "sources": { + "metabase_instance": { + "description": "Metabase BI instance - dados de negócio em tempo real", + "url": "https://bi.descomplicar.pt/", + "mcp": "metabase", + "tools_count": 134 + }, + "notebooklm": { + "description": "NotebookLM - conhecimento curado (se notebooks BI forem criados)", + "query_tool": "mcp__notebooklm__notebook_query", + "notebooks": [] + } + } +} diff --git a/metabase/log.md b/metabase/log.md new file mode 100644 index 0000000..66e9c4d --- /dev/null +++ b/metabase/log.md @@ -0,0 +1 @@ +## 2026-06-30 init | Estrutura padrão diff --git a/metabase/skills/AGENTS.md b/metabase/skills/AGENTS.md new file mode 100644 index 0000000..37d90a2 --- /dev/null +++ b/metabase/skills/AGENTS.md @@ -0,0 +1,17 @@ +# AGENTS.md — skills + +Directrizes específicas deste projecto para agentes IA. + +## Referências obrigatórias + +- `ECOSYSTEM.md` — Hub/06-Operacoes/Documentacao/ECOSYSTEM.md +- `PROC-DEV-STANDARD` — D7-SIS-006 +- `PROC-AUDIT-STANDARD` — D7-SIS-007 + +## Protocolo de sessão + +Início: ler MEMORY.md + STATUS.md. Fim: actualizar ambos. + +## Convenções específicas + +- (a definir) diff --git a/metabase/skills/CHANGELOG.md b/metabase/skills/CHANGELOG.md new file mode 100644 index 0000000..5e14603 --- /dev/null +++ b/metabase/skills/CHANGELOG.md @@ -0,0 +1,5 @@ +# CHANGELOG — skills + +## 0.1.0 — 2026-06-30 +### Adicionado +- Estrutura padrão (PROC-DEV-STANDARD) diff --git a/metabase/skills/MEMORY.md b/metabase/skills/MEMORY.md new file mode 100644 index 0000000..4971060 --- /dev/null +++ b/metabase/skills/MEMORY.md @@ -0,0 +1,4 @@ +# MEMORY.md — skills + +## 2026-06-30 +- Estrutura padrão aplicada via propagate-structure.sh diff --git a/metabase/skills/README.md b/metabase/skills/README.md new file mode 100644 index 0000000..2ad232f --- /dev/null +++ b/metabase/skills/README.md @@ -0,0 +1,3 @@ +# skills + +Subprojecto skills do ecossistema Descomplicar. diff --git a/metabase/skills/STATUS.md b/metabase/skills/STATUS.md new file mode 100644 index 0000000..07c1590 --- /dev/null +++ b/metabase/skills/STATUS.md @@ -0,0 +1,8 @@ +# STATUS.md — skills + +**Versão:** 0.1 | **Data:** 2026-06-30 | **Agente:** — + +## Estado actual +- Em curso: — +- Bloqueios: — +- Próximos passos: — diff --git a/metabase/skills/dashboard/SKILL.md b/metabase/skills/dashboard/SKILL.md new file mode 100644 index 0000000..ad8adc7 --- /dev/null +++ b/metabase/skills/dashboard/SKILL.md @@ -0,0 +1,148 @@ +--- +name: dashboard +description: Criação e gestão de dashboards Metabase — questions, visualizações e filtros para bi.descomplicar.pt. +disable-model-invocation: true +layer: wiki +--- + +# Skill /dashboard - Metabase Dashboard Management + +Criar e gerir dashboards Metabase com questions, visualizações e filtros para bi.descomplicar.pt. + +## Sintaxe + +``` +/dashboard [operação] [contexto] +``` + +**Operações:** +- `create [nome]` - Criar novo dashboard +- `add-card [dashboard_id]` - Adicionar question/card a dashboard +- `list` - Listar todos os dashboards +- `view [id]` - Ver detalhes de um dashboard +- `share [id]` - Obter link público de partilha +- `export [id]` - Exportar dados de um dashboard + +## Quando usar + +- Criar dashboards de negócio (vendas, marketing, operações) +- Adicionar visualizações a dashboards existentes +- Organizar métricas em painéis visuais +- Partilhar dashboards com equipa + +--- + +## Protocolo de execução + +### 1. Carregar MCP + +``` +ToolSearch("metabase") +``` + +### 2. Operação: create + +**Workflow completo para criar dashboard:** + +``` +1. CONFIRMAR objectivo com utilizador +2. Identificar database e tabelas relevantes + - mcp__metabase__list_databases + - mcp__metabase__get_database_tables +3. Escolher/criar collection destino + - mcp__metabase__list_collections +4. Criar questions/cards necessários + - Definir query (SQL ou query builder) + - Escolher tipo de visualização (bar, line, pie, table, number) +5. Criar dashboard + - mcp__metabase__create_dashboard (nome, descrição, collection_id) +6. Adicionar cards ao dashboard +7. Confirmar resultado com URL +``` + +**Tipos de visualização recomendados:** + +| Métrica | Visualização | +|---------|-------------| +| KPI singular (total vendas) | Number | +| Evolução temporal | Line chart | +| Comparação categorias | Bar chart | +| Distribuição/proporção | Pie chart | +| Dados detalhados | Table | +| Geográfico | Map | + +### 3. Operação: add-card + +``` +1. Verificar dashboard existe: mcp__metabase__get_dashboard +2. Criar question se necessário +3. Adicionar card ao dashboard +4. Confirmar posição e tamanho +``` + +### 4. Operação: list + +``` +1. mcp__metabase__list_dashboards +2. Apresentar: ID, nome, collection, cards count, última actualização +``` + +### 5. Operação: view + +``` +1. mcp__metabase__get_dashboard (id) +2. Mostrar: nome, descrição, cards, filtros, parâmetros +3. URL directa: https://bi.descomplicar.pt/dashboard/{id} +``` + +### 6. Operação: share + +``` +1. Gerar link público se não existir +2. Retornar URL de embed/partilha +``` + +### 7. Operação: export + +``` +1. Para cada card no dashboard, exportar dados +2. Formatar em tabela Markdown ou sugerir CSV +``` + +## Templates de dashboard + +### Dashboard vendas +- Total facturado (mês actual vs anterior) +- Facturas por estado (paid/unpaid/overdue) +- Top 10 clientes por valor +- Evolução mensal receita + +### Dashboard projectos +- Projectos activos vs concluídos +- Tarefas por estado +- Tempo registado por projecto +- Deadlines próximos + +### Dashboard suporte +- Tickets abertos vs fechados +- Tempo médio de resposta +- Tickets por departamento +- Satisfação cliente + +## Notas + +- Objectos criados via AI usam prefixo `claude_ai_` (comportamento do MCP) +- Sempre confirmar com utilizador antes de criar/modificar +- Preferir collections organizadas por tema + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/metabase/skills/desk.project b/metabase/skills/desk.project new file mode 100644 index 0000000..5678920 --- /dev/null +++ b/metabase/skills/desk.project @@ -0,0 +1,6 @@ +{ + "task_id": null, + "project_id": null, + "customer_id": null, + "gitea_repo": null +} diff --git a/metabase/skills/index.md b/metabase/skills/index.md new file mode 100644 index 0000000..1d7c6b4 --- /dev/null +++ b/metabase/skills/index.md @@ -0,0 +1,8 @@ +# skills + +## Documentação + +- [README](README.md) +- [AGENTS](AGENTS.md) +- [STATUS](STATUS.md) +- [MEMORY](MEMORY.md) diff --git a/metabase/skills/log.md b/metabase/skills/log.md new file mode 100644 index 0000000..66e9c4d --- /dev/null +++ b/metabase/skills/log.md @@ -0,0 +1 @@ +## 2026-06-30 init | Estrutura padrão diff --git a/metabase/skills/metabase/SKILL.md b/metabase/skills/metabase/SKILL.md new file mode 100644 index 0000000..27dbb63 --- /dev/null +++ b/metabase/skills/metabase/SKILL.md @@ -0,0 +1,132 @@ +--- +name: metabase +description: Operações Metabase BI — explorar bases de dados, listar dashboards, gerir collections e questions via bi.descomplicar.pt. +layer: wiki +--- + +# Skill /metabase - Metabase BI Operations + +Operações Metabase BI - explorar databases, listar dashboards, gerir collections e questions via bi.descomplicar.pt. + +## Sintaxe + +``` +/metabase [operação] [contexto] +``` + +**Operações:** +- `explore` - Explorar databases e tabelas disponíveis +- `dashboards` - Listar e inspeccionar dashboards +- `collections` - Gerir collections (pastas) +- `questions` - Listar e inspeccionar questions/cards +- `search [termo]` - Pesquisar conteúdo no Metabase +- `users` - Listar utilizadores e permissões +- `status` - Estado geral da instância + +## Quando usar + +- Explorar que dados estão disponíveis no Metabase +- Ver dashboards existentes +- Gerir collections e organização +- Verificar estado da instância +- Operações administrativas gerais + +--- + +## Protocolo de execução + +### 1. Carregar MCP Metabase + +``` +ToolSearch("metabase") +``` + +Verificar que as tools `mcp__metabase__*` estão disponíveis. + +### 2. Operação: explore + +**Objectivo:** Mapear dados disponíveis. + +``` +1. Listar databases: mcp__metabase__list_databases +2. Para cada database relevante: mcp__metabase__get_database_tables +3. Para tabelas de interesse: mcp__metabase__get_table_fields +4. Apresentar resumo estruturado +``` + +**Output esperado:** +```markdown +## Databases disponíveis + +| ID | Nome | Engine | Tabelas | +|----|------|--------|---------| +| 1 | ... | ... | N | + +### Database: [Nome] +| Tabela | Campos | Registos | +|--------|--------|----------| +| ... | ... | ... | +``` + +### 3. Operação: dashboards + +``` +1. Listar dashboards: mcp__metabase__list_dashboards +2. Para cada dashboard: mostrar nome, descrição, cards +3. Se pedido detalhe: mcp__metabase__get_dashboard +``` + +### 4. Operação: collections + +``` +1. Listar collections: mcp__metabase__list_collections +2. Mostrar hierarquia de pastas +3. Contar items por collection +``` + +### 5. Operação: questions + +``` +1. Listar questions/cards: mcp__metabase__list_cards +2. Mostrar: nome, tipo, database, última execução +``` + +### 6. Operação: search + +``` +1. mcp__metabase__search_content com termo fornecido +2. Agrupar resultados por tipo (dashboard, card, table) +``` + +### 7. Operação: status + +``` +1. Listar databases e verificar conectividade +2. Contar dashboards, questions, collections +3. Listar utilizadores activos +4. Apresentar resumo +``` + +## Metabase instance + +- **URL**: https://bi.descomplicar.pt/ +- **MCP**: metabase (metabase-ai-assistant v4.2.0, 134 tools) +- **Auth**: API key (configurada no MCP) + +## Notas + +- Todas as operações são **read-only** por defeito +- Para operações de escrita (criar dashboard, etc.), usar `/dashboard` +- Para queries SQL, usar `/query` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/metabase/skills/query/SKILL.md b/metabase/skills/query/SKILL.md new file mode 100644 index 0000000..649e174 --- /dev/null +++ b/metabase/skills/query/SKILL.md @@ -0,0 +1,161 @@ +--- +name: query +description: Execução de queries SQL no Metabase com linguagem natural. Explorar tabelas, extrair métricas e criar relatórios ad-hoc. +layer: wiki +--- + +# Skill /query - Metabase SQL Query Assistant + +Executar queries SQL no Metabase com assistência AI. Traduz perguntas em linguagem natural para SQL, explora tabelas e extrai métricas. + +## Sintaxe + +``` +/query [pergunta em linguagem natural ou SQL] +``` + +**Exemplos:** +- `/query quantos clientes temos activos?` +- `/query total facturado em Janeiro 2026` +- `/query top 10 produtos mais vendidos` +- `/query SELECT COUNT(*) FROM customers WHERE active = true` + +## Quando usar + +- Extrair dados específicos das bases de dados +- Responder perguntas de negócio com dados reais +- Análise ad-hoc rápida +- Validar hipóteses com números concretos +- Criar queries para futuros cards/questions + +--- + +## Protocolo de execução + +### 1. Carregar MCP + +``` +ToolSearch("metabase") +``` + +### 2. Compreender o pedido + +**Se linguagem natural:** +1. Identificar a pergunta de negócio +2. Determinar database e tabelas relevantes +3. Usar AI SQL generation do MCP se disponível + +**Se SQL directo:** +1. Validar syntax +2. Verificar que tabelas existem +3. Executar + +### 3. Explorar schema (se necessário) + +``` +1. mcp__metabase__list_databases → identificar database +2. mcp__metabase__get_database_tables → listar tabelas +3. mcp__metabase__get_table_fields → ver campos disponíveis +``` + +### 4. Construir e executar query + +``` +1. Construir SQL baseado no schema real +2. Executar via mcp__metabase__execute_sql +3. Validar resultados (nulls, zeros, outliers) +4. Formatar output +``` + +### 5. Apresentar resultados + +**Output format:** + +```markdown +## Query: [Descrição da pergunta] + +**Database:** [nome] | **Tabelas:** [lista] + +### Resultados + +| Col1 | Col2 | Col3 | +|------|------|------| +| ... | ... | ... | + +**Total registos:** N + +### Insight +[Interpretação breve dos dados] +``` + +## Boas práticas SQL + +### Performance +- Usar `LIMIT` em queries exploratórias (default: 100) +- Evitar `SELECT *` - especificar campos necessários +- Usar `WHERE` para filtrar antes de agregar +- Indexes: verificar campos indexados para JOINs + +### Segurança +- **Read-only**: o MCP opera em modo read-only por defeito +- Nunca executar DDL (CREATE, ALTER, DROP) sem confirmação +- Nunca executar DML (INSERT, UPDATE, DELETE) sem confirmação + +### Padrões comuns + +**Contagem com agrupamento:** +```sql +SELECT campo, COUNT(*) as total +FROM tabela +GROUP BY campo +ORDER BY total DESC +LIMIT 10; +``` + +**Evolução temporal:** +```sql +SELECT DATE_TRUNC('month', created_at) as mes, + COUNT(*) as total, + SUM(valor) as valor_total +FROM tabela +WHERE created_at >= NOW() - INTERVAL '12 months' +GROUP BY mes +ORDER BY mes; +``` + +**Comparação período actual vs anterior:** +```sql +SELECT + SUM(CASE WHEN created_at >= DATE_TRUNC('month', NOW()) THEN valor END) as mes_actual, + SUM(CASE WHEN created_at >= DATE_TRUNC('month', NOW() - INTERVAL '1 month') + AND created_at < DATE_TRUNC('month', NOW()) THEN valor END) as mes_anterior +FROM tabela; +``` + +## Guardar query como question + +Se o utilizador quiser reutilizar a query: +``` +1. Confirmar nome e descrição +2. Criar question/card no Metabase +3. Associar a collection adequada +4. Retornar URL directa +``` + +## Notas + +- Resultados limitados a 2000 linhas por defeito pelo MCP +- Para datasets grandes, usar agregações +- Queries complexas: delegar ao agente `metabase-analyst` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.*