npx @luminondev/mcp-dashboard mcp
npx @luminondev/mcp-dashboard start renderer

{
  "mcpServers": {
    "luminon": {
      "command": "npx",
      "args": ["@luminondev/mcp-dashboard", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "luminon": {
      "command": "npx",
      "args": ["@luminondev/mcp-dashboard", "mcp"]
    }
  }
}

[mcp_servers.luminon]
command = "npx"
args = ["@luminondev/mcp-dashboard", "mcp"]

npx @luminondev/mcp-dashboard mcp

Documentación de MCP Dashboard

Estado: Beta - las interfaces y los formatos de datos pueden cambiar hasta la versión 1.0.

Resumen

Luminon es un espacio de trabajo para dashboards con enfoque local compuesto por cuatro partes:

• Un servidor MCP para crear y editar dashboards y datasets
• Un paquete compartido de esquemas con contratos Zod
• Un renderer en React y una pequeña API en Express para la vista previa local
• Una CLI que inicia el servidor MCP y el renderer con un directorio de datos compartido

Este documento describe el código que existe hoy en este repositorio. Excluye de forma intencional comportamientos antiguos o confusos que ya no están expuestos.

Para un comportamiento estricto del cliente de IA con uso mínimo de herramientas no destructivas, consulta:

• docs/LLM_TOOL_POLICY.md
• skills/luminon-tool-policy/SKILL.md

Configuración de agentes de IA

Usa la política y el skill solo cuando el cliente vaya a modificar dashboards, páginas, gráficos, grupos, carpetas o el estado de compartición.

Codex

• Ubicación opcional del skill en este repo: skills/luminon-tool-policy/
• Para instalarlo localmente en Codex, copia esa carpeta a ~/.codex/skills/luminon-tool-policy
• Reinicia Codex después de instalar el skill para que sea detectado
• El skill está pensado para tareas de mutación; las consultas de solo lectura no lo necesitan

Claude CLI

• Claude no carga skills de Codex directamente
• Usa docs/LLM_TOOL_POLICY.md como texto de política de sesión o pega su contenido en las instrucciones del proyecto
• Para tareas de mutación, prefiere las herramientas explícitas nombradas en la política en lugar de lenguaje natural libre

Gemini CLI

• Gemini no carga skills de Codex directamente
• Usa docs/LLM_TOOL_POLICY.md como política del prompt o inclúyela en instrucciones persistentes
• Para mutaciones peligrosas, exige que el cliente lea la política antes de actuar

Estructura del repositorio

• packages/shared: esquemas Zod compartidos, tipos de gráficos, contratos de filtros, esquemas de plantillas y tipos de TypeScript
• packages/mcp-server: el servidor de herramientas MCP y la lógica de almacenamiento de dashboards/datasets
• packages/renderer: la interfaz web, la compilación estática del demo y el servidor API local
• packages/cli: la CLI luminon usada para ejecutar el servidor MCP y el renderer
• data/: datasets y dashboards semilla del repo para instalaciones nuevas y el demo estático
• docs/: documentación del repositorio

Desarrollo local

Instala dependencias y compila todos los workspaces:

npm install
npm run build

Ejecuta solo el servidor MCP:

npm run dev:mcp

Ejecuta solo el renderer:

npm run dev:renderer

Ejecuta ambos para desarrollo local:

npm run dev:stack

Puntos finales locales actuales:

• UI + API del renderer: http://localhost:5173
• HTTP remoto de MCP (opcional): http://localhost:3001/mcp
• Salud del MCP remoto: http://localhost:3001/health
• Transporte MCP local: stdio (luminon mcp)

Uso de la CLI

El paquete publicado expone una CLI luminon. En este repo, el binario compilado es packages/cli/dist/index.js.

Comandos principales:

luminon mcp
luminon start
luminon start remote
luminon start stack
luminon stop renderer
luminon stop remote
luminon status
luminon token create <name>
luminon token list
luminon token current
luminon token set-default <id|name>
luminon token delete <id|name>

Distribución recomendada:

• Ejecuta luminon mcp dentro de la herramienta de IA como proceso MCP por stdio
• Ejecuta luminon start por separado cuando quieras la vista previa en el navegador
• Ejecuta luminon start remote cuando necesites MCP por HTTP para clientes remotos o de LAN
• Usa los comandos luminon token ... para administrar tokens bearer remotos, cifrados en reposo en el directorio local de datos

Uso directo del paquete:

npx -y @luminondev/mcp-dashboard mcp
npx -y @luminondev/mcp-dashboard start
npx -y @luminondev/mcp-dashboard start remote

start stack inicia el renderer y el MCP remoto. El MCP por stdio todavía debe ser administrado por el cliente de IA anfitrión.

Modos de herramientas

El servidor MCP soporta tres modos de exposición:

• full: expone todas las herramientas MCP
• lite: expone solo el conjunto principal de herramientas con menos tokens
• ultra-lite: un conjunto más pequeño de creación e inspección para clientes muy limitados

Usa lite o ultra-lite cuando trabajes con clientes que tienen cuotas diarias ajustadas.

Ejemplo:

LUMINON_MCP_MODE=lite luminon mcp

En la configuración del cliente de IA, usa la misma variable de entorno en el proceso del servidor MCP.

Valores aceptados:

• full
• lite
• ultra-lite

La CLI también soporta un flag de modo que tiene prioridad sobre la variable de entorno:

luminon mcp --mode lite
luminon mcp --mode ultra-lite

Orden de prioridad:

1. --mode
2. LUMINON_MCP_MODE
3. valor por defecto full

Directorio de datos y persistencia

Por defecto, los datos de usuario se almacenan en:

~/Documents/luminon

Puedes cambiarlo con:

MCP_DATA_DIR=/custom/path

El almacén activo contiene estos archivos:

• dashboards.json
• datasets.json
• dashboard_versions.json
• dataset_snapshots.json
• deleted_dashboards.json
• tokens.secure.json
• share_links.json

Comportamiento de los seeds

El repositorio incluye archivos semilla en data/.

Comportamiento actual al iniciar:

• Si el store del usuario no existe, se inicializa desde los archivos del repo
• Si el store del usuario ya existe, los dashboards semilla faltantes del repo se agregan por id
• Si el store del usuario ya existe, los datasets semilla faltantes del repo se agregan por id
• Los dashboards y datasets existentes del usuario no se sobrescriben
• El dataset integrado de solo lectura default_business siempre se inyecta si falta

Esto importa para actualizaciones: cambiar los seeds del repo y reiniciar el servidor MCP actualizado basta para que los nuevos id aparezcan en el store del usuario.

Seeds de demo integrados

El repositorio incluye actualmente estos datasets semilla de demo:

• coffee_roastery_lab
• hr_dataset
• sales_complex
• marketing_campaign_performance

El repositorio incluye actualmente estos dashboards semilla de demo:

• Coffee Roastery Lab
• HR Workforce Overview
• Sales Performance Hub
• Marketing Campaign Command Center

También existe un dataset integrado de solo lectura:

• default_business

Y una plantilla integrada:

• business-3x3

Demo estático

El renderer soporta un modo estático controlado por:

VITE_STATIC_DEMO=true

En el modo demo estático:

• La UI carga demo-data.json en lugar de llamar a la API en vivo
• El archivo se genera automáticamente a partir de los dashboards y datasets semilla del repo
• Los filtros del dashboard siguen funcionando porque el filtrado se aplica del lado del cliente en el renderer
• Actualizar los seeds del repo y recompilar el renderer actualiza la salida del demo estático

El payload del demo estático lo genera:

• packages/renderer/scripts/generate-static-demo.mjs

La compilación del renderer ya ejecuta este script antes de Vite:

• packages/renderer/package.json

API del renderer

El renderer local incluye una API usada por la UI del navegador.

Rutas actuales:

• GET /api/health
• GET /api/dashboards
• GET /api/dashboards/:id
• PATCH /api/dashboards/:id
• DELETE /api/dashboards/:id/filters/:filterId
• GET /api/dashboard-groups
• GET /api/datasets
• PATCH /api/datasets/:id
• GET /api/dashboards/:id/share-links
• POST /api/dashboards/:id/share-links
• POST /api/share-links/:id/passcode
• POST /api/share-links/:id/revoke
• GET /api/shared/:token
• GET /shared/:token
• GET /api/events

Notas:

• GET /api/dashboards/:id devuelve el dashboard solicitado por id
• GET /api/dashboards devuelve la lista local de dashboards usada por la UI principal
• GET /api/events es un endpoint SSE usado para refrescos en vivo
• /shared/:token es un punto de entrada de acceso compartido sensible a passcode que redirige a la ruta visual del dashboard

Ejemplo: refrescar un dataset de demo sin MCP (sin tokens de IA)

Reemplaza mensualmente el dataset coffee_roastery_lab usando la API local.

Bash:

#!/usr/bin/env bash
set -euo pipefail
CSV_FILE="$1"
API_URL="${API_URL:-http://localhost:5173/api/datasets/coffee_roastery_lab}"

jq -Rs --arg mode "replace" '{csv: ., mode: $mode, allowSchemaChange: true}' < "$CSV_FILE" \
| curl -sS -X PATCH "$API_URL" \
    -H "Content-Type: application/json" \
    --data-binary @- \
| jq -r '.dataset.id + " updated at " + (.dataset.updatedAt // "unknown")'

Python:

import requests, json, pathlib, sys

csv_path = pathlib.Path(sys.argv[1])
api_url = "http://localhost:5173/api/datasets/coffee_roastery_lab"
body = {
    "csv": csv_path.read_text(encoding="utf-8"),
    "mode": "replace",
    "allowSchemaChange": True,
}
r = requests.patch(api_url, json=body, timeout=30)
r.raise_for_status()
print(r.json()["dataset"]["updatedAt"])

Ejecutarlo con cron (ejemplo, día 1 a las 03:00):

0 3 1 * * /usr/local/bin/update_coffee.sh /path/to/coffee_roastery_lab.csv >> /var/log/update_coffee.log 2>&1

Superficie de herramientas MCP

Estas son las herramientas MCP expuestas por packages/mcp-server/src/index.ts hoy.

Herramientas de dashboard

• create_dashboard
• update_dashboard
• add_chart
• add_chart_to_dashboard
• delete_chart
• delete_dashboard
• list_dashboards
• snapshot_dashboard
• list_dashboard_versions
• restore_dashboard_version
• undo_dashboard
• restore_deleted_dashboard
• list_dashboard_filters
• update_dashboard_filters
• list_dashboard_pages
• create_dashboard_page
• rename_dashboard_page
• delete_dashboard_page
• move_chart_to_page
• copy_dashboard_page
• import_dashboard_pages
• create_dashboard_folder
• list_dashboard_folders
• move_dashboard_to_folder
• create_dashboard_group
• list_dashboard_groups
• add_dashboard_group_item
• remove_dashboard_group_item

Herramientas de dataset

• register_dataset
• update_dataset
• restore_dataset_snapshot
• list_datasets
• list_dataset_content
• describe_dataset

Plantillas y lenguaje natural

• list_templates
• create_dashboard_from_template
• dashboard_nl

Creación y estilo de gráficos

• create_chart
• list_theme_presets
• set_chart_theme
• set_chart_presentation
• reset_chart_presentation

En modo lite, el conjunto expuesto se reduce a:

• create_dashboard
• update_dashboard
• delete_dashboard
• list_dashboards
• list_templates
• create_dashboard_from_template
• dashboard_nl
• register_dataset
• update_dataset
• restore_dataset_snapshot
• list_datasets
• list_dataset_content
• describe_dataset
• create_chart
• list_dashboard_filters
• update_dashboard_filters

En modo ultra-lite, el conjunto expuesto se reduce todavía más a:

• create_dashboard
• list_dashboards
• list_templates
• create_dashboard_from_template
• register_dataset
• list_datasets
• describe_dataset
• list_dataset_content
• create_chart
• list_dashboard_filters
• update_dashboard_filters

Cobertura de dashboard_nl

dashboard_nl es el principal punto de entrada no técnico. Actualmente maneja:

• listar dashboards
• listar datasets
• describir un dataset
• listar plantillas
• listar presets de tema
• crear un dashboard
• crear un dashboard desde una plantilla
• registrar un dataset desde CSV
• renombrar un dashboard
• crear, listar e importar páginas de dashboard
• crear y listar carpetas y mover dashboards entre carpetas
• crear y listar grupos y agregar o quitar dashboards en grupos
• cambiar columnas del dashboard o auto-layout
• aplicar cambios de tema y presentación del dashboard
• crear gráficos bar, line, area, scatter, radar, donut, funnel, kpi_card, table, combo y gráficos multi-bar agrupados o apilados

Acepta solicitudes tanto en inglés como en español mediante un matching ligero de intenciones. El payload de respuesta se resume intencionalmente para mantener más bajo el uso de MCP en clientes con cuotas limitadas.

Notas de UX de compartición (UI actual de OSS)

• La acción principal de compartición de dashboards ahora es Share en el header del renderer.
• Private/Published se conserva como metadato de compatibilidad del backend, pero ya no aparece como acción primaria de UI en OSS.
• Los enlaces compartidos seguros pueden crearse con o sin passcode.
• Para enlaces protegidos con passcode:
  • /shared/:token pide el passcode,
  • después de validarlo, redirige a la ruta visual del dashboard,
  • el passcode se guarda en session storage del navegador para esa sesión, no en la query de la URL durante la redirección.

Operaciones de dashboard

create_dashboard

Crea un dashboard con opciones:

• name
• subtitle
• themePreset
• presentation
• charts
• layout
• filters
• published

Si se omite layout, el valor por defecto es una grilla 3x3 sin elementos.

update_dashboard

Actualiza propiedades a nivel de dashboard en una sola llamada. Los campos soportados actualmente son:

• name
• subtitle
• themePreset
• presentation
• columns
• layout
• autoLayout

No existe una herramienta MCP separada llamada set_dashboard_theme o set_dashboard_presentation; usa update_dashboard.

add_chart vs add_chart_to_dashboard

• add_chart agrega un payload de gráfico sin colocación automática
• add_chart_to_dashboard agrega un gráfico y lo coloca automáticamente en la grilla, salvo que pases una ubicación personalizada

Eliminación y recuperación de dashboards

• delete_dashboard requiere confirm: "DELETE"
• Los dashboards eliminados se guardan en deleted_dashboards.json
• restore_deleted_dashboard restaura desde ese almacén eliminado y opcionalmente puede renombrar el dashboard o asignarle un nuevo id

Modelo de snapshots

Los snapshots de dashboard son intencionalmente de instancia única por dashboard.

Comportamiento actual:

• snapshot_dashboard sobrescribe el snapshot existente de ese dashboard
• list_dashboard_versions devuelve ese snapshot actual si existe
• restore_dashboard_version restaura desde el snapshot
• undo_dashboard restaura el último snapshot almacenado

Esto no es un historial completo de versiones. Es un único punto de retroceso por dashboard.

Operaciones de dataset

register_dataset

Los datasets pueden crearse a partir de:

• texto CSV crudo
• filas JSON

update_dataset

Modos actuales de actualización:

• replace
• append

Comportamiento importante:

• Debe proporcionarse exactamente una fuente: csv o rows
• Los cambios de esquema requieren allowSchemaChange: true
• Los datasets integrados de solo lectura no pueden actualizarse
• El servidor guarda un único snapshot de rollback antes de la mutación

restore_dataset_snapshot

Restaura el último snapshot guardado para un dataset. También es un undo de un solo nivel, no un historial completo de versiones.

Tipos de gráfico que realmente existen

Tipos de gráfico almacenados y renderizados:

• bar
• bar_grouped
• bar_stacked
• line
• area
• scatter
• radar
• donut
• funnel
• kpi_card
• table
• combo

funnel y combo son características reales en la base de código actual. Existen en:

• esquemas compartidos
• creación de gráficos del lado del servidor
• lógica de renderizado

Tipos de create_chart

La herramienta MCP unificada create_chart acepta:

• bar
• line
• area
• scatter
• radar
• donut
• funnel
• kpi_card
• table
• combo
• multi_bar

Distinción importante:

• multi_bar es un alias de entrada para crear gráficos de varias series
• El tipo almacenado pasa a ser bar_grouped o bar_stacked según el modo solicitado

Soporte de plantillas

Las plantillas son un subconjunto más reducido que create_chart.

El esquema actual de plantillas soporta estos tipos de gráfico:

• kpi_card
• table
• bar
• line
• area
• scatter
• radar
• donut

Entonces:

• funnel, combo y los multi-bar de varias series están disponibles a través de create_chart
• No forman parte del esquema actual de tipos de gráfico para plantillas

Filtros de dashboard

Los filtros de dashboard se almacenan en el dashboard y son diferentes de los filtros de origen de un gráfico.

Campos actuales de filtros de dashboard:

• id
• field
• fieldType
• op
• value
• valueTo
• applyTo

Tipos actuales de filtros de dashboard:

• string
• number
• date

Operadores actuales de filtros de dashboard:

• eq
• neq
• gte
• lte
• between
• in
• not_in

Notas:

• gt y lt no son operadores de filtros de dashboard
• applyTo puede restringir un filtro a ids específicos de gráficos o datasets
• between usa value y valueTo
• in y not_in aceptan arreglos en el esquema

UI de filtros del renderer

El renderer actualmente mapea los operadores de filtros de dashboard a estos controles:

• eq, in, not_in: un <select> simple
• between: dos inputs de texto
• gte, lte, neq: un input de texto

Comportamiento importante del renderer hoy:

• in sí muestra un selector en el renderer
• Ese selector es de selección única, no múltiple
• not_in también usa una UI de selección única
• Si un filtro se define con un valor tipo arreglo en el JSON almacenado, el motor de filtros lo soporta, pero la UI integrada del renderer sigue exponiendo solo un valor seleccionado a la vez

Filtros de origen de gráfico

Los filtros de origen de gráfico se usan dentro de create_chart y en las definiciones source de los gráficos. Son un esquema distinto al de los filtros de dashboard.

Operadores actuales de filtros de origen:

• eq
• neq
• gt
• gte
• lt
• lte
• in

Los filtros de origen también soportan un dateRange opcional.

Agregación y ordenamiento

Los gráficos generados a partir de datasets soportan estas agregaciones donde aplique:

• sum
• avg
• count

Las etiquetas parecidas a meses se ordenan cronológicamente tanto en el servidor MCP como en el renderer cuando los valores se ven como:

• Jan
• January
• 2025-Jan
• cadenas de mes similares

Por eso los dashboards demo basados en meses ahora quedan en orden de calendario en vez de orden alfabético.

Presets de tema y presentación

IDs actuales de presets de tema:

• clean
• business
• dark_analytics
• pastel
• high_contrast
• textured

Comportamiento de tema y presentación:

• Los dashboards pueden establecer themePreset y presentation mediante create_dashboard y update_dashboard
• Los gráficos individuales pueden sobreescribir tema y presentación mediante:
  • set_chart_theme
  • set_chart_presentation
  • reset_chart_presentation

Límites prácticos impuestos por el servidor

Los límites de seguridad actuales incluyen:

• máximo 12 gráficos por dashboard
• máximo 50,000 filas por dataset
• tamaño máximo de CSV de 20 MB para registrar o reemplazar un dataset
• gráficos de tabla limitados a 500 filas

También hay límites específicos por tipo de gráfico para evitar degradación del renderer con payloads grandes.

Plantilla integrada actual

El repositorio incluye actualmente una plantilla:

• business-3x3

Espera el dataset default_business con estas columnas:

• year
• month
• country
• channel
• category
• sales
• orders

Los metadatos de plantilla almacenados en packages/shared/templates.json ahora están en inglés y coinciden con el resto del contenido público del demo.

Solución de problemas

Un dataset o dashboard semilla no aparece

Revisa estos puntos:

• Reinicia el servidor MCP para que la sincronización de seeds vuelva a ejecutarse
• Confirma qué directorio de datos está usando el proceso en ejecución
• Asegúrate de que el cliente de IA esté lanzando este repositorio actualizado o el paquete publicado actualizado
• Verifica el id del dataset o dashboard en el datasets.json o dashboards.json activo

El renderer muestra filtros, pero el comportamiento parece más limitado que el esquema

Eso es esperado en un caso:

• El esquema de filtros de dashboard soporta valores tipo arreglo para in y not_in
• El renderer integrado actualmente expone esos operadores con un control de selección única, no de selección múltiple

Parece faltar un tipo de gráfico

Estado actual de implementación:

• funnel existe
• combo existe
• los multi-series agrupados y apilados existen como bar_grouped y bar_stacked
• multi_bar solo es el tipo de entrada al crear en create_chart

Claude u otro cliente consume la cuota demasiado rápido

La causa histórica principal fueron respuestas MCP demasiado grandes, especialmente listados de datasets que devolvían payloads completos de filas. El servidor ahora devuelve resúmenes más pequeños para respuestas pesadas, y list_datasets devuelve metadatos en lugar de contenido completo.

Si un cliente todavía tiene una cuota diaria baja:

• usa LUMINON_MCP_MODE=lite
• usa LUMINON_MCP_MODE=ultra-lite para los clientes más restrictivos
• prioriza list_datasets y describe_dataset antes de exploraciones más amplias
• usa list_dataset_content solo para el dataset que realmente quieras inspeccionar

Modelo mental recomendado

Usa el proyecto en este orden:

1. Registra o inspecciona un dataset
2. Crea un dashboard
3. Agrega gráficos con create_chart o con payloads crudos usando add_chart_to_dashboard
4. Agrega filtros de dashboard con update_dashboard_filters
5. Previsualiza en el renderer
6. Usa snapshots y herramientas de restore cuando iteres

Si quieres el punto de entrada menos técnico, usa dashboard_nl y deja que el servidor traduzca la solicitud a las herramientas de menor nivel.