PBIFORGE

Aplicación local de Claude Desktop MCP para generar informes .pbit de Power BI a partir de conjuntos de datos CSV, instrucciones en lenguaje natural y estilo de imagen de referencia.

GitHubPrueba este MCPPatrocinado

Documentación

ReportForge PBI

Genere paneles de Power BI (.pbit) a partir de archivos CSV o bases de datos SQL en vivo — localmente, en su propia máquina, en segundos.

ReportForge perfila sus datos, diseña un diseño de panel sensato (tarjetas KPI + gráficos + filtros), lo compila en una plantilla de Power BI y escribe el resultado en el disco. Abra el .pbit en Power BI Desktop y tendrá un informe funcional.

Destacados

Carga de CSV — suelte un solo .csv, obtenga un .pbit. No se requiere Power BI para generarlo.
Fuentes SQL en vivo — SQL Server, PostgreSQL, Oracle. El .pbit generado consulta la base de datos al abrir; las credenciales nunca se incrustan.
Indicaciones en lenguaje natural — describa lo que desea ("gráfico de barras de empresa por ingresos, línea de crecimiento a lo largo del año"). Impulsado por Claude o GPT — traiga su propia clave API. Sin una clave, ReportForge aún produce un panel predeterminado sensato a partir de un perfil CSV; la indicación se ignora.
Diseño a partir de una imagen de referencia — suelte una captura de pantalla de un panel que le guste. ReportForge lee la estructura (cantidad de tarjetas, tipos de gráficos, panel de filtros) y la aplica al diseño generado, luego adopta la paleta de colores como tema del informe.
Múltiples tipos de gráficos — barras, columnas, líneas, áreas, circular, dona, dispersión, tabla. Tarjetas KPI. Segmentadores.
Interfaz de navegador — se ejecuta en http://127.0.0.1:8000/. Solo local por defecto.
Servidor MCP — expone las mismas herramientas a Claude Desktop a través de stdio para indicaciones "/" dentro de Claude.

Inicio 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/ en su navegador.

Si prefiere usar ReportForge dentro de Claude Desktop, consulte LOCAL_SETUP.md para la configuración de MCP stdio.

La interfaz del navegador

Campo	Qué hace
Fuente de datos	Elija `CSV file` o uno de los conectores SQL.
Archivo CSV	Un solo CSV con fila de encabezado. Las columnas se perfilan automáticamente (medidas, dimensiones, fechas, campos geográficos).
Campos SQL	`Server`, `Database`, `Schema`, `Table` (o una consulta `SELECT` de forma libre). El nombre de usuario/contraseña se usa solo para el perfilado — nunca se incrusta en el `.pbit`.
Indicación	Descripción en lenguaje natural de lo que desea ver. Requiere una clave de LLM (consulte "Asistencia de IA" más abajo). Sin una clave, la indicación se ignora y obtiene el panel predeterminado determinista.
Imagen de referencia de estilo	PNG/JPG opcional. ReportForge lee la estructura del panel (número de tarjetas KPI, tipos de gráficos, presencia del panel de filtros) usando Claude Vision y refleja ese diseño en el informe generado. También se extraen los colores y se aplican como tema del informe.
Asistencia de IA	Requerida para que las indicaciones tengan efecto. Elija Anthropic/OpenAI y pegue una clave API, o elija Qwen local a través de Ollama. Solo los nombres de columnas (no las filas de datos) se envían al modelo.

El .pbit descargado se abre en Power BI Desktop, solicita las credenciales de la fuente de datos y renderiza el panel.

Cómo funcionan las indicaciones

ReportForge siempre ejecuta el constructor de paneles determinista (tarjetas KPI, gráfico de barras/líneas principal, dona para dimensiones de baja cardinalidad, segunda página "Desgloses" cuando el conjunto de datos es rico). Además, si proporciona una clave de LLM, su indicación se interpreta y se agregan visuales adicionales.

Lo que ve el LLM:

Su indicación
Nombres de columnas + roles (measure / dimension)
Tipos semánticos de columnas (temporal, geographic, categorical, etc.)
Visuales que el constructor determinista ya produjo (para no duplicarlos)

Lo que NO ve: ninguna de sus filas de datos.

El modelo devuelve una lista JSON de especificaciones de gráficos (tipo, columna del eje x, columna del eje y, título); ReportForge valida cada especificación contra el perfil de columnas y agrega las que pasan.

El encabezado de respuesta X-ReportForge-Parser le indica qué ruta se ejecutó para cada generación (llm:anthropic, llm:openai, llm:qwen, llm:<provider>-empty, no-key o deterministic-only). La interfaz muestra esto debajo de cada mensaje "Informe listo".

Fuentes de datos SQL

ReportForge incluye importaciones de controladores perezosas — la instalación base funciona solo para uso CSV. Instale controladores solo para las bases de datos que necesite:

# 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

En la interfaz, elija el tipo de fuente en el menú desplegable Fuente de datos. ReportForge:

Se conecta con las credenciales que proporcione.
Extrae SELECT TOP 1000 (o LIMIT 1000) para perfilar tipos de columnas, cardinalidad y roles.
Genera una expresión M de Power Query que Power BI Desktop usará para obtener el conjunto de datos completo en vivo.
Compila todo en un .pbit.

Las credenciales nunca llegan al archivo .pbit — Power BI Desktop solicitará iniciar sesión al abrir por primera vez. Este es el comportamiento estándar de la plantilla de Power BI.

Ejemplo: SQL Server

Campo	Ejemplo
Servidor	`db-prod.corp.com,1433` o `localhost\SQLEXPRESS`
Base de datos	`AdventureWorks2022`
Esquema	`Sales` (por defecto `dbo`)
Tabla	`Customer`
Nombre de usuario/Contraseña	Déjelo en blanco para autenticación de Windows, llénelo para autenticación SQL.

Ejemplo: consulta de forma libre

Pegue un SELECT (con uniones, filtros, lo que sea) en el cuadro O: consulta SELECT. ReportForge perfilará las primeras 1000 filas del resultado y apuntará a la misma consulta en la M generada.

Asistencia de IA

Proveedor	Modelo utilizado	Dónde obtener una clave
Anthropic	Claude Sonnet con respaldos	https://console.anthropic.com/
OpenAI	`gpt-4o-mini`	https://platform.openai.com/api-keys
Qwen local	Modelo Qwen de Ollama auto-detectado, o `QWEN_MODEL` / `OLLAMA_MODEL`	No se requiere clave API

Lo que se envía al modelo:

Su indicación
La lista de nombres de columnas + sus roles inferidos
La lista de visuales ya generados por el constructor determinista
Nada más. Sus filas de datos nunca salen de su máquina.

La clave se almacena en caché en el sessionStorage de la pestaña del navegador para que no tenga que volver a pegarla en cada generación. Se borra cuando se cierra la pestaña.

Para Qwen local, elija Local Qwen 2.5 (Ollama) en el menú desplegable de proveedor. El instalador de Windows incluye un runtime de Ollama solo CPU y lo iniciará cuando ReportForge se lance; qwen2.5:3b se descarga en el primer uso si falta, por lo que la primera generación de Qwen puede tardar unos minutos y necesita acceso a internet. ReportForge llama a http://127.0.0.1:11434 por defecto; anule con QWEN_OLLAMA_URL o OLLAMA_HOST si su servidor Ollama se ejecuta en otro lugar.

Si omite la clave, ReportForge recurre solo al constructor de paneles determinista. Su indicación no tiene efecto en ese caso — el panel se construye puramente a partir del perfil de columnas.

Imagen de referencia de estilo

Suelte cualquier PNG/JPG (una captura de pantalla de un panel que le guste, una maqueta de marca, una página de Tableau). ReportForge ejecuta dos extracciones en paralelo:

Extracción de diseño (Claude Vision, requiere clave de Anthropic) Lee el diseño estructural del panel de referencia:

Cuántas tarjetas KPI/métricas son visibles → se usa como cantidad de tarjetas KPI en el informe generado
Qué tipos de gráficos están presentes (barras, columnas, líneas, áreas, dona, etc.) → influye en la selección del tipo de gráfico
Si existe un panel de filtros/segmentadores en el lado derecho → agrega u omite un panel de segmentadores
Si las tarjetas KPI están en una columna izquierda o en una cuadrícula superior → elige la plantilla de diseño correspondiente

Extracción de paleta (Claude Vision, o respaldo local de Pillow) Extrae el esquema de colores:

Colores primarios, secundarios y de acento
Fondo del lienzo de la página
Paleta de series de gráficos (rotación de 8 colores)

La extracción de diseño requiere un ANTHROPIC_API_KEY. Si no hay clave disponible, ReportForge aún muestrea colores localmente con Pillow y el diseño recurre al predeterminado basado en datos.

Endpoints de API

Todos los endpoints son solo locales (127.0.0.1:8000).

Método + ruta	Propósito
`GET /health`	Sonda de actividad.
`GET /`	La interfaz del navegador.
`POST /generate-from-csv`	Multipart: `csv_file`, `prompt`, `image_file?`, `llm_provider?`, `llm_api_key?`. Devuelve el archivo `.pbit`.
`POST /generate-from-source`	Multipart: `kind`, `server`, `database`, `schema`, `table` o `query`, `username`, `password`, `prompt`, `image_file?`, `llm_provider?`, `llm_api_key?`. Devuelve el `.pbit`.
`POST /generate`	Ruta solo LLM (requiere la variable de entorno `ANTHROPIC_API_KEY`). Para Claude Desktop.
`/mcp/*`	El servidor MCP, expuesto sobre HTTP. Usado por Claude Desktop y otros clientes compatibles con MCP.

Para la integración de Claude Desktop a través de stdio, apunte el lanzador a run_mcp_stdio.ps1 — consulte LOCAL_SETUP.md.

Instalador de Windows (un solo .exe para usuarios finales)

Hay un instalador de doble clic disponible para usuarios que no quieren ejecutar setup_local.ps1. Incluye Python, todas las dependencias, la aplicación FastAPI y pbi-tools.core en un solo .exe. Consulte installer/README.md para el proceso de compilación. Flujo de instalación para el usuario final:

Descargue ReportForge-PBI-Setup-1.0.3.exe (o la última versión).
Ejecútelo (se requiere administrador — se instala en Program Files).
Menú Inicio → ReportForge PBI. El servidor se inicia y su navegador se abre automáticamente.
Los datos del usuario (informes generados, fuentes, sesiones) se encuentran en %LOCALAPPDATA%\ReportForge\ y sobreviven a la reinstalación/desinstalación.

Botón de herramienta externa de Power BI Desktop

Opcional. Agrega un botón ReportForge PBI a la cinta de Herramientas externas en Power BI Desktop. Consulte EXTERNAL_TOOL_SETUP.md.

Algunos inquilinos bloquean el registro de Herramientas externas mediante la política de inquilino de Fabric. Si el botón de la cinta no aparece después de registrarse, la interfaz del navegador aún funciona — simplemente abra http://127.0.0.1:8000/ directamente.

Arquitectura (una pantalla)

                ┌──────────────┐
   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

Archivos clave:

main.py — Aplicación FastAPI, endpoints, montaje de interfaz estática.
orchestrator.py — pipelines (pipeline_from_csv, pipeline_from_source).
data_profiler.py — Perfilador CSV.
data_sources.py — Perfiladores de BD + generadores M para MSSQL / Postgres / Oracle.
auto_intent.py — Constructor de intención + diseño determinista, analizador de indicaciones con regex.
llm_intent.py — Analizador de indicaciones impulsado por LLM (Anthropic + OpenAI).
image_analyzer.py — Extracción de paleta y extracción de sugerencias de diseño a partir de imágenes de referencia.
file_writer.py — Escribe el árbol del proyecto, inyecta DataMashup + Report/Layout.
mcp_server.py — Herramientas MCP para Claude Desktop.
static/index.html — Interfaz del navegador.

Solución de problemas

.pbit no se abre / "Ocurrió un error al abrir el archivo". Generalmente es una generación obsoleta en generated_reports/. Elimine y regenere. Si persiste, revise los registros del servidor — los errores de pbi-tools.core suelen aparecer allí.

El botón de Herramientas externas no aparece en Power BI Desktop. Generalmente es una política de inquilino de Fabric. Consulte la sección de solución de problemas en EXTERNAL_TOOL_SETUP.md.

La llamada al LLM falla silenciosamente. Cuando la llamada al LLM falla o devuelve una lista de visuales vacía, ReportForge recurre al constructor determinista y muestra llm:<provider>-empty en el encabezado de respuesta X-ReportForge-Parser (visible en el mensaje de estado de la interfaz). Verifique el valor de la clave, el menú desplegable de proveedor y que openai esté instalado (pip install openai) si eligió OpenAI.

El perfilado SQL falla con "se requiere pyodbc/psycopg2/oracledb". Instale el controlador correspondiente en el venv (consulte Fuentes de datos SQL).

La generación tiene éxito pero el panel se ve azul simple, no como mi imagen de referencia. El extractor de paleta local de Pillow es más conservador que la ruta de visión de Anthropic. Si tiene un ANTHROPIC_API_KEY configurado, la ruta de visión da mejores resultados de color. O abra el .pbit resultante y ajuste el tema manualmente. Imagen de referencia proporcionada, pero el diseño no coincide con ella. La extracción del diseño requiere un ANTHROPIC_API_KEY — sin uno, solo se muestrean los colores y el diseño vuelve al predeterminado basado en datos. Verifica que la clave esté configurada y que la imagen de referencia muestre claramente la estructura del panel (tarjetas, paneles de gráficos, barra lateral de filtros).

Estado del proyecto

Esta es la versión local-first de ReportForge. El despliegue en Railway no es la vía soportada en este momento — todo está diseñado para ejecutarse en tu máquina, comunicarse con archivos CSV y bases de datos locales, y escribir archivos .pbit en generated_reports/.

La hoja de ruta (ver .claude/plans/) cubre:

Fase 1: conectores SQL (✅ esta versión).
Fase 2: modelos unidos de múltiples tablas con inferencia automática de relaciones.
Fase 3: leer el modelo de una sesión abierta de Power BI Desktop mediante un helper de .NET.