Horizun PBI MCP

Maqueta HTML del spec con las posiciones FINALES. No escribe al .pbip. Lo que muestra el preview es exactamente lo que se escribiria: tipos, titulos, campos, tamanos y posiciones salen del mismo compilado que usa la aplicacion.

Genera una MAQUETA HTML de una hoja propuesta (sin escribir nada al .pbip). `spec`: {page_name, canvas?, layout?, visuals:[{type,title,fields,position?}]}. Devuelve la ruta del HTML (abrelo en el navegador para revisar el diseno).

Perfila los VALORES del modelo abierto y devuelve lo que no cuadra. Complementa a pbi_audit_model, que revisa la estructura: un porcentaje que vale -800 no es un defecto del modelo sino de los datos, y solo se ve consultandolos. Detecta porcentajes fuera de 0-100, columnas vacias, columnas de un solo valor y columnas mayormente vacias. Cada hallazgo trae la consulta que lo demuestra y la consecuencia concreta sobre el tablero. Solo lectura. `tables` acota el trabajo; `max_columns` evita que un modelo grande agote el timeout y devuelva un perfil a medias.

Mira el modelo y PROPONE varios diseños distintos, con su porque. A diferencia de pbi_page_building_blocks, que entrega el inventario y deja el diseño en manos de quien pregunta, esto clasifica lo que hay —que columna es un estado, cual una fecha, cuales forman una familia de metricas comparables— y devuelve paginas completas con un spec listo para aplicar. Devuelve tambien `blockers`: lo que hay que resolver ANTES de construir (p.ej. un modelo sin medidas, donde todo visual caeria en sumas implicitas), y `themes` con las paletas disponibles. Usalo para ofrecer opciones al usuario en vez de decidir por el.

Aplica la politica de retencion a los backups. DESTRUCTIVA. Sin `confirm` devuelve el MANIFIESTO de lo que se eliminaria, sin tocar nada. Solo se borran directorios de journal reconocibles (con su `manifest.json`) dentro de la carpeta de backups del proyecto activo: nunca un archivo suelto, ni un enlace simbolico, ni una raiz amplia. Se conserva siempre el journal mas reciente y TODOS los pendientes: un journal pendiente guarda los unicos originales de una transaccion que no llego a cerrarse.

Restaura los originales guardados en un journal. DESTRUCTIVA. Sin `confirm` devuelve la VISTA PREVIA: que archivos se restaurarian, cual es su estado actual y si alguien los cambio despues. Estados: `recoverable`, `recovered`, `conflict`, `incomplete`, `corrupted`. Si un archivo cambio despues de la transaccion, se rechaza con `recovery_conflict` en vez de pisar ese trabajo; `force_conflict` lo aplica de todas formas. Cada archivo se verifica byte a byte tras restaurarlo, y se recrean los directorios padre que hubieran desaparecido.

Reescala las paginas ya escritas al lienzo de otro sistema. El camino de vuelta que faltaba. Aplicar un sistema cambia el tema del informe, pero NO reescribe lo ya compuesto: las paginas se quedan con el lienzo anterior —visuales fuera de limites, basura invisible que si viaja al render— y con los colores que se cocieron al componerlas: un titulo compuesto en tema oscuro queda BLANCO SOBRE BLANCO al pasar a claro, sin que falle nada. Esto hace las dos cosas: reescala cada visual proporcionalmente al lienzo nuevo (acotandolo si no cabe) y recalcula el color de texto de los elementos decorativos con el tema del sistema destino. **No recompone**: no se puede saber que intencion tenia cada visual, y adivinarla seria peor. Si una pagina necesita otra estructura, recomponla con `pbi_compose_page`. Esto la deja utilizable, no optima. `pages`: subconjunto opcional (id o nombre visible); por defecto todas. `dry_run=true` (por defecto) devuelve el plan visual por visual, con cuales estaban ya fuera de limites, sin escribir nada. Escribe en el informe (PBIR): requiere el proyecto CERRADO en Desktop.

Refresca el modelo LOCAL abierto en Power BI Desktop (no el Service). `type`: full | calculate | clear_values (tambien automatic | data_only). `tables`: lista opcional de tablas a refrescar; si se omite, todo el modelo. Los errores de credenciales/origen se reportan. `timeout_seconds` (600 por defecto, `0` lo desactiva): un refresh lanzado por XMLA **no puede mostrar el dialogo de credenciales** de Desktop, asi que un origen sin credenciales guardadas deja al motor esperando para siempre y no hay ninguna ventana que cerrar. Al agotarse el plazo se pide la cancelacion al motor y se devuelve `refresh_timeout` enumerando los origenes que REQUIEREN credenciales -no si las tienen: eso Desktop no lo expone- y si la cancelacion se confirmo o el comando pudo quedar corriendo. Devuelve estado, duracion y **`rows_by_table`**: cuantas filas quedaron en cada tabla refrescada. Un refresh puede terminar en 'ok' y haber cargado CERO filas -credenciales que devuelven vacio, un filtro de fecha que no alcanza nada, un origen que cambio de esquema-, asi que las tablas vacias salen ademas en `warnings`. Si no se pudo contar, se dice; no se inventa el numero. En un proyecto **.pbip los datos NO se guardan**: viven en la sesion de Desktop y al reabrir hay que refrescar otra vez. Lo que persiste al guardar es la definicion (TMDL + PBIR). **Exige `confirm=true` desde 2.0.0.** Hasta entonces era la unica tool `destructiveHint` sin confirmacion junto con `pbi_open_and_refresh`: un agente que decide por «¿tiene `confirm`?» no veia nada que preguntar.

Renombra una medida actualizando TODO lo que la referencia. Renombrar a mano rompe el informe en silencio: cualquier visual o medida que apuntara al nombre viejo abre y sale VACIO, sin error. Esta tool compila primero y escribe en UNA transaccion: la cabecera TMDL, las expresiones DAX de otras medidas que usan `[old_name]`, y los visual.json del informe. Devuelve la lista de lo tocado. Limite honesto: las referencias DAX CALIFICADAS (`Tabla[old]`) no se reescriben —pueden ser una columna homonima de otra tabla, y adivinar seria corromper—; si quedan, salen en `warnings` con su ubicacion, igual que las de bookmarks y filtros. Solo `pbip` (escribe modelo E informe a la vez: exige Desktop CERRADO). `dry_run=true` (defecto) devuelve el plan sin escribir.

Cambia el nombre visible de una pagina. El id interno no cambia.

Fija el orden de las paginas del informe. Acepta ids o nombres visibles. Las paginas que no menciones quedan al final, conservando su orden relativo.

Detecta referencias rotas en los visuales y las repara. Sin `mapping` solo diagnostica: adivinar a que campo queria apuntar un visual roto no es una decision que deba tomarse sola. Pasa `{"Tabla[Viejo]": "Tabla[Nuevo]"}` para repararlas, y el destino se valida contra el modelo antes de escribir.

Sustituye una referencia de campo dentro de un visual. `old_ref`/`new_ref`: 'Tabla[Campo]' o '[Medida]'. Trabaja sobre las proyecciones existentes; no crea roles nuevos. Falla si el visual no referencia `old_ref`, en vez de no hacer nada en silencio. El destino se valida contra el modelo antes de escribir: si no existe, es ambiguo o es de otro tipo (medida donde va una columna), se rechaza con `field_not_found` en lugar de inventarlo.

Version PBIR observada, tema, custom visuals y tipos clonables. Solo se pueden crear visuales de tipos ya presentes en el informe: se clona una estructura real en vez de inventarla. Esta tool dice cuales hay disponibles antes de intentarlo.

Ejecuta una consulta DAX de SOLO LECTURA contra el modelo activo. Solo se admiten formas reconocidas: EVALUATE, DEFINE...EVALUATE y DMVs de $SYSTEM. Cualquier otra cosa se rechaza (politica fail-closed). `max_rows`: limite de filas. `max_bytes`: tope de tamano del resultado, para no devolver megas al cliente. `timeout_seconds`: timeout del comando. `export=true` vuelca el resultado completo a outputs/ y devuelve la ruta. Devuelve columnas, tipos observados, filas, estadisticas de ejecucion y si se trunco (y por que: filas o tamano). Los errores DAX del motor se devuelven tal cual. `query` es el unico nombre de la consulta: no hay alias `dax`, porque `query` es obligatorio en el contrato congelado y un alias no podria sustituirlo. Ejemplo: `pbi_run_dax(query="EVALUATE TOPN(5, 'Ventas')")`.

Busca objetos del modelo por nombre (y en el DAX de las medidas). `term`: texto a buscar, sin distinguir mayusculas. `kinds`: filtra por tipo — table, column, measure, hierarchy, role. Para las medidas indica si coincidio el nombre o la expresion.

Selecciona el modelo local activo para futuras operaciones. Si hay un solo modelo abierto no hace falta indicar nada. Si hay varios, pasa `port` **o** `connection_string` TAL CUAL lo devuelve `pbi_list_desktop_models` (`"Data Source=localhost:56057"`): lo que sale de esa tool entra en esta sin tener que extraer el puerto a mano.

Detalle de la sesion: modelo activo, proyecto activo y su frescura. Distingue una sesion valida de una obsoleta (`stale`) o de otra que ocupo el mismo puerto (`mismatch`).

Colorea un visual con el color que DEVUELVE una medida. Es el modo "valor de campo" de Power BI: la medida entrega '#D03B3B' o un nombre de color, y el visual lo aplica tal cual. Es el patron tipico de un semaforo calculado en DAX. `field`: '[Medida]' o 'Tabla[Medida]' que devuelve el color. `target`: 'background' o 'font' (tablas y matrices), 'bars' (barras, columnas y puntos). La matriz de que combinacion funciona en que tipo de visual vive en el servidor y se valida antes de escribir. `target_column`: columna proyectada a pintar; sin ella se pinta la columna del propio campo.

Oculta o muestra una columna del modelo (p.ej. ocultar columnas de ID). mode='both' esta temporalmente deshabilitado bajo la politica estricta: 'live' necesita Power BI Desktop abierto y 'pbip' lo necesita cerrado, asi que una sola llamada aplicaria solo uno de los dos destinos. Elige 'live' o 'pbip', o usa 'auto' y se mira el estado para elegir. Si estas construyendo desde cero, 'auto' o 'pbip': el defecto es 'live' y exige Desktop abierto.

Colorea un visual segun el valor de un campo (degradado). Es lo que convierte una matriz de numeros en un mapa de calor, o unas barras planas en una escala de semaforo. `field`: 'Tabla[Campo]' o '[Medida]' de donde sale el VALOR. `target_column`: que columna del visual se pinta con ese valor; sin ella se pinta la columna del propio `field`. Debe estar proyectada en el visual (p.ej. pintar 'Resumen[semaforo]' con '[Puntaje promedio]'). `target`: 'background' o 'font' para tablas y matrices; 'bars' para barras, columnas y puntos. `mid_color`: si lo indicas, el degradado tiene tres paradas en vez de dos, util cuando hay un punto neutro. `min_value`/`mid_value`/`max_value`: anclas numericas de las paradas (sin ellas, Power BI usa el minimo y maximo observados). `null_strategy`: asZero | none | specificColor. Si el visual ya tenia una regla en ese mismo destino, se sustituye: dos degradados sobre la misma propiedad no se suman, se pisan.

Cambia el filtro cruzado de una relacion. `direction`: 'single' (una direccion, recomendado) o 'both' (bidireccional). OJO: cambiar a 'single' puede alterar totales que dependian de la bidireccional; verifica el informe despues. No confundir `direction='both'` (bidireccional, valido) con `mode='both'`, que esta temporalmente deshabilitado bajo la politica estricta: 'live' necesita Power BI Desktop abierto y 'pbip' lo necesita cerrado, asi que una sola llamada aplicaria solo uno de los dos destinos.

Cambia el modo de almacenamiento de una tabla: import | directQuery | dual. Con directQuery el dato se consulta al origen en cada interaccion y desaparece el refresco, pero NO es un interruptor inocuo: la consulta M tiene que ser plegable al origen, las columnas y tablas calculadas dejan de estar disponibles, y cada visual pasa a ser una consulta al servidor. Devuelve el modo anterior y cuantas particiones cambiaron, para poder deshacerlo sabiendo exactamente que se toco. Escribe en TMDL: requiere el proyecto CERRADO en Power BI Desktop.

Filtra un visual EXISTENTE sin escribir `filterConfig` a mano. `filters`: lista de specs. Por COLUMNA, `{field: 'Tabla[Columna]', values?: [...], type?: 'Categorical' | 'Advanced' | 'TopN' | 'Range' | 'RelativeDate' | 'Passthrough', exclude?: bool, raw?: {...}, hidden?: bool, locked?: bool, display_name?: str}`. Con `values` se arma un filtro de lista (Categorical); sin `values` ni `raw` el campo queda declarado pero SIN acotar, como el panel de filtros vacio. `raw` pasa una consulta semantica ya construida, para lo que este constructor no cubre. Por MEDIDA, `{measure: 'Tabla[Medida]', condition: 'GreaterThan', value: 0}` (`condition`: Equal | NotEqual | GreaterThan | GreaterThanOrEqual | LessThan | LessThanOrEqual, o los simbolos `> >= < <= = !=`). Es la forma de ENCADENAR slicers de dimension cuando varias tablas de hechos cuelgan de las mismas dimensiones y una relacion bidireccional crearia ambiguedad. `field`/`measure` van con el NOMBRE real de la tabla. La mitad interna de la consulta usa un ALIAS (`SourceRef.Source`) que esta tool resuelve sola: escribirlo a mano ahi es el error mas comun al construir un filtro de visual, y Power BI lo ignora sin decir por que. Por defecto REEMPLAZA los filtros del visual, y una lista vacia los quita todos. **Cuidado con los slicers**: suelen traer un filtro `Categorical` donde vive la seleccion del usuario, y reemplazarlo la borra. Para anadir sin pisar, `merge=true` (ahi una lista vacia no quita nada). No comprueba el campo contra el modelo: uno que no existe se escribe igual y Power BI lo resuelve en silencio a nada.

Cambia u oculta el titulo de un visual PRESERVANDO su formato. `title`: el texto nuevo. `show=false`: oculta el titulo SIN borrar su texto ni formato (el rodeo de poner texto vacio dejaba la banda del titulo ocupando altura); `show=true` lo vuelve a mostrar. Se puede pasar solo uno de los dos, o ambos.

Fija el orden Z de los visuales de una pagina. `order`: ids de MENOR a MAYOR z; el ultimo queda encima. Los visuales que no menciones se colocan por encima, conservando su orden relativo.

Descarga una carpeta de SharePoint a outputs/ de forma todo-o-nada. Primero inventaria el lote y valida `max_files`, `max_total_mb` y el filtro opcional `extensions` (por ejemplo `['xlsx','csv']`). Luego usa URLs temporales emitidas por Graph, verifica tamano y SHA-256 y publica el directorio completo bajo `outputs/sharepoint/`. Un fallo elimina el staging y no deja una carpeta final parcial. Es una descarga de solo lectura remota: no sube, mueve ni elimina nada en SharePoint.

Conecta con SharePoint Online y lista una carpeta mediante Graph. `site_url` es la URL HTTPS del sitio; `library` es el nombre o id de la biblioteca documental; `folder_path` usa `/`. Sigue la paginacion de Graph y puede recorrer subcarpetas con un limite total explicito. Autenticacion app-only: las credenciales SOLO se leen de las variables `HORIZUN_PBI_MCP_SHAREPOINT_TENANT_ID`, `_CLIENT_ID` y `_CLIENT_SECRET`. Nunca se aceptan secretos como parametros ni se devuelven tokens.

Por donde empezar. Mira el estado real y dice los siguientes pasos. Ciento treinta y dos tools con buen nombre siguen siendo ciento treinta y dos tools. Esta responde «¿y ahora que?» con tres o cuatro pasos concretos, cada uno con el nombre exacto de la tool y **por que** toca ahora: si hay proyecto activo, si tiene modelo o solo informe, si esta vacio, y si Power BI Desktop lo tiene abierto —que impide escribir el TMDL—. Devuelve tambien `common_tasks`: tareas frecuentes y la secuencia de tools que las resuelve. No escribe nada. Empieza por aqui cuando no sepas que sigue.

Valida la conexion al modelo activo con una consulta trivial.

Actualiza una medida existente. Lo no especificado se conserva. mode='both' esta temporalmente deshabilitado bajo la politica estricta: 'live' necesita Power BI Desktop abierto y 'pbip' lo necesita cerrado, asi que una sola llamada aplicaria solo uno de los dos destinos. Elige 'live' o 'pbip', o usa 'auto' y se mira el estado para elegir. Si estas construyendo desde cero, 'auto' o 'pbip': el defecto es 'live' y exige Desktop abierto.

Reemplaza ENTERA la consulta M de una particion o expresion. No hay edicion parcial ni sustitucion por expresion regular: se localiza el bloque por su estructura y se cambia completo. `dry_run` viene ACTIVADO: la primera llamada enseña lo que se escribiria sin tocar el disco, sin backup y sin journal. `expected_sha256` (el que devuelve `pbi_get_power_query`) rechaza la escritura si el texto cambio desde que lo leiste, en vez de pisar el trabajo de otro. Escribe TMDL: exige proyecto .pbip y Power BI Desktop CERRADO. Va con backup, journal, transaccion, relectura y rollback; si el modelo queda con errores TMDL que antes no tenia, se revierte entero. La respuesta distingue lo comprobado de lo no comprobado: `parse_checked` y `tmdl_load_checked` dicen que el TMDL se lee y que el serializador oficial lo acepta; `m_engine_checked` y `refresh_checked` son SIEMPRE false. Que el archivo parsee no significa que la consulta cargue: eso solo lo dice un refresh.

Mueve/redimensiona un visual existente.

Abre un .pbip/.pbix y captura su ventana real sin depender del foco. Es la comprobacion visual automatizable que complementa al validador PBIR: espera el modelo, identifica la ventana por PID y hora de inicio, y la renderiza con PrintWindow directamente a ``outputs/desktop_captures``. La captura no activa ni trae Desktop al frente, por lo que no puede fotografiar por accidente otra ventana que tape el informe. `path` (o `pbip_path`, el mismo nombre que devuelve `pbi_session_info`) se puede omitir: entonces se usa el proyecto .pbip activo. **`refresh=true` es lo que hace que la captura signifique algo en un .pbip**: ese formato guarda la definicion, no los datos, asi que recien abierto el modelo viene VACIO y las tablas y matrices salen en blanco aunque el informe este perfecto. Con `refresh` se abre, se refresca, se espera a que la ventana deje de repintar y se captura. Ese es tambien el camino para fotografiar OTRA pagina con datos: `page` exige abrir el proyecto, y al abrirlo hay que volver a refrescar. Como el refresh modifica de forma irreversible el modelo en memoria, `refresh=true` exige ademas `confirm=true`. `confirm_reuse` autoriza mover una ventana que ya era del usuario; son autorizaciones distintas. Pase lo que pase, la respuesta lleva `data_loaded`: si es `false`, la captura no es representativa del informe, es la foto de un modelo sin datos. Si no se pudo comprobar, se dice; no se afirma ninguna de las dos. `page`: captura ESA pagina (id o nombre visible), no la que quedo activa. `fit_to_page` (activado por defecto): fuerza la vista "Ajustar a la pagina" para que salga el lienzo COMPLETO y no el tercio superior al zoom guardado. Con el proyecto CERRADO (.pbip) ambos se aplican como una vista temporal en disco que se restaura byte a byte al terminar. Con la ventana YA ABIERTA -que es del usuario- se hacen en la propia interfaz, pero SOLO con `confirm_reuse=true`: elegir una pestaña y cambiar el zoom mueven esa ventana, y una captura que solo debia observar no lo hace por su cuenta. Sin `confirm_reuse`, `page` sobre una sesion abierta es un error y `fit_to_page` degrada a un aviso (se captura al zoom actual). Con el, se elige la pestaña y el zoom por UI Automation y se demuestra el resultado hasta donde se puede (`navigation`): la pagina por el `IsSelected` de su pestaña; el zoom solo por el nivel que anuncia Power BI, lo que prueba que el zoom CAMBIO y no que el modo resultante sea "Ajustar a la pagina" -`verified_means` lo dice en la propia respuesta-. Si la pagina no se pudo demostrar, la tool falla en vez de capturar otra; si el zoom no se pudo demostrar, lo dice en `warnings`. Nunca toca `pages.json` de un proyecto abierto. La captura separa cuatro señales que no son la misma cosa: `capture.identity_settled` (la ventana muestra ESTE documento), `capture.frame_settled` (la imagen dejo de cambiar), `data_loaded` (el modelo tiene filas) y `capture.frame_uniform` (la imagen es casi de un solo color: pagina vacia o visuales sin pintar). `capture.capture_representative` resume las tres primeras. `data_loaded` habla de lo que muestra la VENTANA, no solo del motor: `canvas` lee por UI Automation los avisos de Power BI ("es necesario actualizar manualmente", "datos incompletos") y los valores «(En blanco)». Si Power BI avisa de que faltan datos, `data_loaded` es `false` aunque el motor tenga filas -van en `model_data_loaded`- y la captura deja de ser representativa. Con `refresh=true` se espera a que esos avisos desaparezcan antes de capturar (`canvas.wait_after_refresh`). En un .pbip con la pagina conocida se espera ademas a que se vean los titulos de sus visuales: si no aparecen todos, `canvas.state` es `visuals_not_painted` y la captura tampoco es representativa. `canvas.state="no_blank_signals"` no demuestra datos pintados: solo que no se vio lo contrario; `unknown` es que no se pudo leer. "Ajustar a la pagina" en una sesion YA ABIERTA no necesita `confirm_reuse` si esa ventana la abrio este mismo servidor (p. ej. con `pbi_open_and_refresh`) o si la llamada trae `refresh=true` y `confirm=true`. `navigation`/`authorized_by` dice cual fue. Si la tool tuvo que abrir Desktop, lo cierra al terminar (tambien si la captura falla) y devuelve la seleccion de modelo a como estaba. Si el informe ya estaba abierto, reutiliza esa sesion y nunca cierra la ventana del usuario.

Verifica una pagina YA escrita: referencias rotas y geometria. Se usa despues de aplicar un spec para comprobar que el resultado es valido de verdad, no solo que la escritura no fallo.

Valida DAX de medidas SIN modificar el modelo (dry-run con DEFINE MEASURE). Ideal para probar medidas ANTES de crearlas con pbi_create_measure. `measures`: lista de {"name","dax","table"(opcional)}. Las medidas pueden referenciarse entre si. Devuelve por cada una: valid, value (muestra) y error.

Valida un spec: esquema, referencias contra el modelo y geometria. Los errores traen su JSON path (`$.visuals[2].fields.values[0]`) para que se puedan corregir sin adivinar. No escribe nada.

Valida a fondo el proyecto .pbip activo (estructura, PBIR, TMDL). Incluye `references`: cada Measure/Column que un visual.json o su filterConfig citan, cruzada contra el TMDL real. El esquema PBIR y la sintaxis TMDL pueden pasar limpios por separado con un visual que apunta a una medida borrada -- Desktop lo resuelve en silencio a nada, sin marca visible. Solo corre si el TMDL es valido (comparar contra un modelo que no abre es ruido, no una comprobacion).

Comprueba si un modelo TMDL abrira, sin abrir Power BI Desktop. Dos capas. Un lint estatico que caza las trampas que solo se veian al abrir (una propiedad de tabla colocada despues de sus hijos, un comentario '///' sobre una relacion, una medida que se llama como una columna de su tabla, medidas duplicadas, referencias rotas) y, si estan las DLL, un parseo con el MISMO serializador que usa Power BI. Cada hallazgo trae `rule`, `severity`, el archivo y la linea. Si el parseo no se pudo ejecutar se dice (`parse_checked: false`) en vez de darlo por bueno. Hay fallos que NINGUN analisis estatico ve porque dependen de los datos —un blanco en el lado 'uno' de una relacion, un separador decimal mal interpretado—. Salen en `limitations`: para esos hay que refrescar. `path`: carpeta `definition` del modelo, la carpeta `.SemanticModel` o el `.pbip`. Si se omite, el proyecto activo. `use_tom=False`: solo el lint estatico, sin tocar las DLL.