PBIFORGE

Aplicativo MCP do Claude Desktop local para gerar relatórios .pbit do Power BI a partir de conjuntos de dados CSV, instruções em linguagem natural e estilo de imagem de referência.

GitHubExperimente este MCPPatrocinado

Documentação

ReportForge PBI

Gere dashboards do Power BI (.pbit) a partir de arquivos CSV ou bancos de dados SQL ao vivo — localmente, na sua própria máquina, em segundos.

O ReportForge analisa seus dados, projeta um layout de dashboard sensato (cartões de KPI + gráficos + filtros), compila em um template do Power BI e grava o resultado em disco. Abra o .pbit no Power BI Desktop e você terá um relatório funcional.

Destaques

Upload de CSV — envie um único .csv e receba um .pbit. Não é necessário Power BI para gerá-lo.
Fontes SQL ao vivo — SQL Server, PostgreSQL, Oracle. O .pbit gerado consulta o banco de dados ao abrir; as credenciais nunca são incorporadas.
Comandos em linguagem natural — descreva o que você quer ("gráfico de barras de empresa por receita, linha de crescimento por ano"). Alimentado por Claude ou GPT — use sua própria chave de API. Sem chave, o ReportForge ainda produz um dashboard padrão sensato a partir do perfil do CSV; o comando é ignorado.
Layout a partir de uma imagem de referência — envie uma captura de tela de um dashboard que você gosta. O ReportForge lê a estrutura (quantidade de cartões, tipos de gráfico, painel de filtros) e a aplica ao layout gerado, adotando também a paleta de cores como tema do relatório.
Múltiplos tipos de gráfico — barras, colunas, linhas, área, pizza, rosca, dispersão, tabela. Cartões de KPI. Segmentações.
Interface no navegador — roda em http://127.0.0.1:8000/. Somente local por padrão.
Servidor MCP — expõe as mesmas ferramentas ao Claude Desktop via stdio para comandos "/" dentro do Claude.

Início rápido

# 1. Clone
git clone https://github.com/twilize5/reportforge.git
cd reportforge-pbi

# 2. Install Python deps (creates .venv)
.\setup_local.ps1

# 3. Install pbi-tools.core somewhere on PATH or at C:\pbi-tools\
#    Download: https://github.com/pbi-tools/pbi-tools/releases

# 4. Start the local server
.\run_api.ps1

Abra http://127.0.0.1:8000/ no seu navegador.

Se preferir usar o ReportForge dentro do Claude Desktop, consulte LOCAL_SETUP.md para a configuração do MCP via stdio.

A interface do navegador

Campo	O que faz
Fonte de dados	Escolha `CSV file` ou um dos conectores SQL.
Arquivo CSV	Um único CSV com linha de cabeçalho. As colunas são analisadas automaticamente (medidas, dimensões, datas, campos geográficos).
Campos SQL	`Server`, `Database`, `Schema`, `Table` (ou uma consulta `SELECT` de forma livre). O nome de usuário/senha é usado apenas para análise — nunca incorporado no `.pbit`.
Comando	Descrição em linguagem natural do que você quer ver. Requer uma chave de LLM (veja "Assistência de IA" abaixo). Sem chave, o comando é ignorado e você recebe o dashboard padrão determinístico.
Imagem de referência de estilo	PNG/JPG opcional. O ReportForge lê a estrutura do dashboard (número de cartões de KPI, tipos de gráfico, presença de painel de filtros) usando Claude Vision e espelha esse layout no relatório gerado. As cores também são extraídas e aplicadas como tema do relatório.
Assistência de IA	Necessária para que os comandos tenham efeito. Escolha Anthropic/OpenAI e cole uma chave de API, ou escolha Qwen local via Ollama. Apenas os nomes das colunas (não as linhas de dados) são enviados ao modelo.

O .pbit baixado abre no Power BI Desktop, solicita as credenciais da fonte de dados e renderiza o dashboard.

Como os comandos funcionam

O ReportForge sempre executa o construtor de dashboard determinístico (cartões de KPI, gráfico principal de barras/linhas, rosca para dimensões de baixa cardinalidade, segunda página "Detalhamentos" quando o conjunto de dados é rico). Além disso, se você fornecer uma chave de LLM, seu comando é interpretado e visuais adicionais são anexados.

O que o LLM vê:

Seu comando
Nomes das colunas + papéis (measure / dimension)
Tipos semânticos das colunas (temporal, geographic, categorical, etc.)
Visuais que o construtor determinístico já produziu (para não duplicá-los)

O que ele NÃO vê: nenhuma das suas linhas de dados.

O modelo retorna uma lista JSON de especificações de gráfico (tipo, coluna do eixo X, coluna do eixo Y, título); o ReportForge valida cada especificação contra o perfil das colunas e adiciona as que passam.

O cabeçalho de resposta X-ReportForge-Parser informa qual caminho foi executado para cada geração (llm:anthropic, llm:openai, llm:qwen, llm:<provider>-empty, no-key ou deterministic-only). A interface mostra isso sob cada mensagem "Relatório pronto".

Fontes de dados SQL

O ReportForge vem com importações de drivers preguiçosas — a instalação base funciona apenas para uso com CSV. Instale os drivers apenas para os bancos de dados que você precisa:

# SQL Server (also needs the Microsoft ODBC Driver 17 or 18, installed system-wide)
.\.venv\Scripts\python.exe -m pip install pyodbc

# PostgreSQL
.\.venv\Scripts\python.exe -m pip install psycopg2-binary

# Oracle (thin mode - no Oracle client install required)
.\.venv\Scripts\python.exe -m pip install oracledb

Na interface, escolha o tipo de fonte no menu suspenso Fonte de dados. O ReportForge:

Conecta-se com as credenciais fornecidas.
Busca SELECT TOP 1000 (ou LIMIT 1000) para analisar tipos de coluna, cardinalidade e papéis.
Gera uma expressão M do Power Query que o Power BI Desktop usará para buscar o conjunto de dados completo ao vivo.
Compila tudo em um .pbit.

As credenciais nunca entram no arquivo .pbit — o Power BI Desktop solicitará o login na primeira abertura. Este é o comportamento padrão do Template do Power BI.

Exemplo: SQL Server

Campo	Exemplo
Servidor	`db-prod.corp.com,1433` ou `localhost\SQLEXPRESS`
Banco de dados	`AdventureWorks2022`
Esquema	`Sales` (padrão: `dbo`)
Tabela	`Customer`
Nome de usuário/Senha	Deixe em branco para autenticação do Windows, preencha para autenticação SQL.

Exemplo: consulta de forma livre

Cole um SELECT (com joins, filtros, qualquer coisa) na caixa Ou: consulta SELECT. O ReportForge analisará as primeiras 1000 linhas do resultado e usará a mesma consulta no M gerado.

Assistência de IA

Provedor	Modelo usado	Onde obter uma chave
Anthropic	Claude Sonnet com fallbacks	https://console.anthropic.com/
OpenAI	`gpt-4o-mini`	https://platform.openai.com/api-keys
Qwen local	Modelo Qwen do Ollama auto-detectado, ou `QWEN_MODEL` / `OLLAMA_MODEL`	Nenhuma chave de API necessária

O que é enviado ao modelo:

Seu comando
A lista de nomes de colunas + seus papéis inferidos
A lista de visuais já gerados pelo construtor determinístico
Nada mais. Suas linhas de dados nunca saem da sua máquina.

A chave é armazenada em cache no sessionStorage da aba do navegador para que você não precise colá-la novamente a cada geração. Ela é apagada quando a aba é fechada.

Para Qwen local, escolha Qwen 2.5 Local (Ollama) no menu suspenso de provedor. O instalador do Windows inclui um runtime Ollama apenas para CPU e o iniciará quando o ReportForge for aberto; qwen2.5:3b é baixado no primeiro uso se estiver ausente, então a primeira geração com Qwen pode levar alguns minutos e precisa de acesso à internet. O ReportForge chama http://127.0.0.1:11434 por padrão; substitua por QWEN_OLLAMA_URL ou OLLAMA_HOST se o seu servidor Ollama estiver em outro lugar.

Se você pular a chave, o ReportForge usa apenas o construtor de dashboard determinístico. Seu comando não tem efeito nesse caso — o dashboard é construído puramente a partir do perfil das colunas.

Imagem de referência de estilo

Envie qualquer PNG/JPG (uma captura de tela de um dashboard que você gosta, um mockup de marca, uma página do Tableau). O ReportForge executa duas extrações em paralelo:

Extração de layout (Claude Vision, requer chave Anthropic) Lê o layout estrutural do dashboard de referência:

Quantos cartões de KPI/métrica estão visíveis → usado como a quantidade de cartões de KPI no relatório gerado
Quais tipos de gráfico estão presentes (barras, colunas, linhas, área, rosca, etc.) → influencia a seleção do tipo de gráfico
Se existe um painel de filtro/segmentação à direita → adiciona ou omite um painel de segmentação
Se os cartões de KPI estão em uma coluna à esquerda ou em uma grade na linha superior → escolhe o template de layout correspondente

Extração de paleta (Claude Vision, ou fallback local com Pillow) Extrai o esquema de cores:

Cores primária, secundária e de destaque
Fundo do canvas da página
Paleta de séries de gráficos (rotação de 8 cores)

A extração de layout requer um ANTHROPIC_API_KEY. Se nenhuma chave estiver disponível, o ReportForge ainda amostra as cores localmente com Pillow e o layout usa o padrão orientado por dados.

Endpoints da API

Todos os endpoints são somente locais (127.0.0.1:8000).

Método + caminho	Finalidade
`GET /health`	Sonda de disponibilidade.
`GET /`	A interface do navegador.
`POST /generate-from-csv`	Multipart: `csv_file`, `prompt`, `image_file?`, `llm_provider?`, `llm_api_key?`. Retorna o arquivo `.pbit`.
`POST /generate-from-source`	Multipart: `kind`, `server`, `database`, `schema`, `table` ou `query`, `username`, `password`, `prompt`, `image_file?`, `llm_provider?`, `llm_api_key?`. Retorna o `.pbit`.
`POST /generate`	Caminho somente LLM (requer a variável de ambiente `ANTHROPIC_API_KEY`). Para Claude Desktop.
`/mcp/*`	O servidor MCP, exposto via HTTP. Usado pelo Claude Desktop e outros clientes compatíveis com MCP.

Para integração com Claude Desktop via stdio, aponte o lançador para run_mcp_stdio.ps1 — veja LOCAL_SETUP.md.

Instalador do Windows (um único .exe para usuários finais)

Um instalador com duplo clique está disponível para usuários que não querem executar setup_local.ps1. Ele inclui Python, todas as dependências, o aplicativo FastAPI e pbi-tools.core em um único .exe. Veja installer/README.md para o processo de build. Fluxo de instalação para o usuário final:

Baixe ReportForge-PBI-Setup-1.0.3.exe (ou a versão mais recente).
Execute-o (requer administrador — instala em Program Files).
Menu Iniciar → ReportForge PBI. O servidor inicia e seu navegador abre automaticamente.
Os dados do usuário (relatórios gerados, fontes, sessões) ficam em %LOCALAPPDATA%\ReportForge\ e sobrevivem à reinstalação/desinstalação.

Botão de Ferramenta Externa do Power BI Desktop

Opcional. Adiciona um botão ReportForge PBI à faixa de Ferramentas Externas no Power BI Desktop. Veja EXTERNAL_TOOL_SETUP.md.

Alguns locatários bloqueiam o registro de Ferramentas Externas via política de locatário do Fabric. Se o botão da faixa não aparecer após o registro, a interface do navegador ainda funciona — basta abrir http://127.0.0.1:8000/ diretamente.

Arquitetura (em uma tela)

                ┌──────────────┐
   CSV / SQL → ┤ data_profiler / data_sources ┤ → DatasetProfile
                └──────────────┘
                        │
                        ▼
                  build_intent_from_profile      (deterministic)
                        │
                        │  + prompt parser (regex OR LLM)
                        │  + image layout hint extractor  (Claude Vision)
                        │  + image palette extractor      (Claude Vision / Pillow)
                        ▼
                  ReportIntent (Pydantic)
                        │
                        ▼
                  build_bim_from_profile  →  semantic model (BIM JSON)
                  build_m_for_source      →  Power Query M
                  build_layout_from_intent →  report layout (visuals + theme)
                        │
                        ▼
                  pbi-tools.core compile  →  .pbit
                  inject_data_mashup       (DataMashup binary)
                  inject_report_layout     (Report/Layout)
                        │
                        ▼
                      .pbit file

Arquivos principais:

main.py — aplicativo FastAPI, endpoints, montagem da interface estática.
orchestrator.py — pipelines (pipeline_from_csv, pipeline_from_source).
data_profiler.py — analisador de CSV.
data_sources.py — analisadores de banco de dados + geradores M para MSSQL / Postgres / Oracle.
auto_intent.py — construtor determinístico de intenção + layout, analisador de comandos por regex.
llm_intent.py — analisador de comandos orientado por LLM (Anthropic + OpenAI).
image_analyzer.py — extração de paleta e dicas de layout a partir de imagens de referência.
file_writer.py — grava a árvore do projeto, injeta DataMashup + Report/Layout.
mcp_server.py — ferramentas MCP para Claude Desktop.
static/index.html — interface do navegador.

Solução de problemas

.pbit não abre / "Ocorreu um erro ao abrir o arquivo". Geralmente é uma geração desatualizada em generated_reports/. Exclua e gere novamente. Se persistir, verifique os logs do servidor — erros de pbi-tools.core geralmente aparecem lá.

O botão de Ferramentas Externas não aparece no Power BI Desktop. Na maioria das vezes é uma política de locatário do Fabric. Veja a seção de solução de problemas em EXTERNAL_TOOL_SETUP.md.

A chamada de LLM falha silenciosamente. Quando a chamada de LLM erra ou retorna uma lista vazia de visuais, o ReportForge usa o construtor determinístico e exibe llm:<provider>-empty no cabeçalho de resposta X-ReportForge-Parser (visível na mensagem de status da interface). Verifique o valor da chave, o menu suspenso de provedor e se openai está instalado (pip install openai) se você escolheu OpenAI.

A análise SQL falha com "pyodbc/psycopg2/oracledb é necessário". Instale o driver relevante no venv (veja Fontes de dados SQL).

A geração é bem-sucedida, mas o dashboard parece azul simples, não como minha imagem de referência. O extrator de paleta local com Pillow é mais conservador que o caminho de visão da Anthropic. Se você tiver um ANTHROPIC_API_KEY definido, o caminho de visão dá melhores resultados de cor. Ou abra o .pbit resultante e ajuste o tema manualmente. Imagem de referência fornecida, mas o layout não corresponde a ela. A extração de layout requer um ANTHROPIC_API_KEY — sem um, apenas as cores são amostradas e o layout recai para o padrão orientado por dados. Verifique se a chave está definida e se a imagem de referência mostra claramente a estrutura do dashboard (tiles de cartões, painéis de gráficos, barra lateral de filtros).

Estado do projeto

Esta é a encarnação local-first do ReportForge. A implantação no Railway não é o caminho suportado no momento — tudo é projetado para rodar na sua máquina, conversar com CSVs e bancos de dados locais, e escrever arquivos .pbit em generated_reports/.

O roadmap (veja .claude/plans/) cobre:

Fase 1: conectores SQL (✅ nesta versão).
Fase 2: modelos de múltiplas tabelas unidas com inferência automática de relacionamentos.
Fase 3: ler o modelo de uma sessão aberta do Power BI Desktop via um auxiliar .NET.