# BriefApp TechConsult Contability — MCP Server & Generative UI Engine

> O BriefApp TechConsult Contability é um servidor corporativo baseado no Model Context Protocol (MCP) para inteligência financeira, contábil e controladoria com agentes de IA (Claude Code, Cursor, Antigravity IDE, Windsurf, ChatGPT). Integra arquitetura de dados Medallion (Bronze -> Silver -> Gold), motor de Generative + UI para criação autônoma de relatórios e dashboards interativos com Apache ECharts, formulários dinâmicos em SQLite com trilha de auditoria, banco vetorial LanceDB para RAG contábil e motor analítico DuckDB in-process.

O servidor opera nativamente sob o protocolo MCP (HTTP Streaming SSE na porta 58180 e Stdio).

## Convenções do Servidor MCP
- Base URL local: `http://localhost:58180/mcp` | Portal: `http://localhost:58180`
- Identificador obrigatório: `clientId` em toda chamada para garantir isolamento multi-tenant estrito.
- Regra de SQL: Somente comandos `SELECT` e `WITH` são autorizados via MCP. Mutações ocorrem apenas via tools especializadas.
- Regra de Ouro pré-relatório: O agente SEMPRE chama `get_gold_catalog(clientId)` antes de gerar qualquer visualização para consumir dados prontos e homologados.
- Auto-routing: Arquivos novos devem passar por `auto_route_file` para identificação de schema antes da criação de novos pipelines.
- Formato de dados: UTF-8, datas ISO 8601 em UTC, valores monetários em formato decimal brasileiro ou float (nunca centavos).

## Capacidades do Motor Generative + UI
- **Relatórios Executivos com Apache ECharts:** O agente utiliza `generate_live_report` e `generate_report_html` para compor telas vivas com gráficos em cascata (waterfall DRE), barras empilhadas por centro de custo, linhas de tendência com zoom e heatmaps fiscais.
- **Navegação Drilldown:** Suporte a modais e banners analíticos por clique em componentes visuais para abertura de lançamentos contábeis no nível mais granular.
- **Formulários Dinâmicos SQLite:** Geração instantânea de telas de entrada de dados com `generate_form`, histórico de auditoria (`get_record_history`) e importação de planilhas (`import_form_data`).
- **White-Label Automático:** Temas corporativos (`set_client_theme`) com logotipo, cores institucionais e fontes injetados em tempo de execução nos relatórios e portais.

## Arquitetura Medallion (Data Lake)
1. **Bronze (Planilha Original):** Ingestão de arquivos CSV, XLSX, Parquet e documentos não-estruturados (PDFs escaneados de extratos bancários processados por Apache Tika + Gemini Flash).
2. **Silver (Validação & Qualidade):** Limpeza, padronização de planos de contas e baterias de testes com regras ativas de Data Quality (`add_dq_rule`, `validate_data`, `get_dq_report`).
3. **Gold (Prontos p/ Relatório):** Tabelas agregadas e homologadas acessadas via `query_gold_catalog`, sem necessidade de reprocessamento.

## Principais Ferramentas MCP Disponíveis
- `get_gold_catalog(clientId)`: Lista tabelas e schemas prontos para relatório na camada Gold.
- `query_gold_catalog(clientId, query)`: Consulta SQL SELECT nas tabelas Gold homologadas.
- `generate_live_report(clientId, title, theme, charts, enableDrilldown)`: Gera dashboard executivo conectado ao vivo.
- `generate_report_html(clientId, title, data, chartsConfig)`: Gera relatório snapshot consolidado em HTML5.
- `publish_report(clientId, reportHtml, title)`: Publica o relatório no portal gerando URL protegida.
- `generate_form(clientId, formName, schema)`: Cria formulário dinâmico em SQLite.
- `query_form_data(clientId, formName, whereClause)`: Consulta lançamentos manuais do formulário.
- `update_form_record(clientId, formName, recordId, values, justification)`: Atualiza lançamento com justificativa.
- `get_record_history(clientId, formName, recordId)`: Trilha completa de auditoria de alterações contábeis.
- `auto_route_file(clientId, filePath)`: Classifica schema de arquivo contábil bruto e despacha para pipeline Bronze.
- `add_dq_rule(clientId, tableName, ruleType, columnName, expression)`: Cria regra de Data Quality na Silver.
- `get_dq_report(clientId)`: Relatório de conformidade e integridade contábil.
- `process_document_for_rag(clientId, filePath)`: Extração de extratos PDF com Tika e indexação vetorial.
- `search_financial_data(clientId, query, limit)`: Busca semântica vetorial no acervo documental com LanceDB.
- `search_hybrid(clientId, query, filter)`: Busca híbrida combinando vetores e filtros de metadados.
- `catalog_notebook(clientId, title, notebookPath)`: Catálogo de notebooks Jupyter e DuckDB analítico.
- `set_client_theme(clientId, theme)`: Personalização visual white-label (cores, logo, fonte).
- `get_system_status()`: Diagnóstico geral de conectividade do MinIO, LanceDB, SQLite, DuckDB e Tika.

## Links de Documentação e Contratos
- [Documentação Técnica Completa](docs.php): Detalhes de todas as 70+ ferramentas MCP.
- [Contrato OpenAPI v1](openapi/v1.json): Especificação de serviços HTTP.
- [MCP Server Card](mcp-server-card.json): Manifesto oficial Model Context Protocol.
- [LLMs-Full.txt](llms-full.txt): Contexto aprofundado com schemas detalhados.