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

Resumen

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

• 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.

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 repositorio 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 del renderer: http://localhost:5173
• API del renderer: http://localhost:4010
• Transporte MCP: solo stdio

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 renderer
luminon stop renderer
luminon stop mcp
luminon status

Distribución recomendada:

• Ejecuta luminon mcp dentro de la herramienta de IA como proceso MCP por stdio
• Ejecuta luminon start renderer por separado cuando quieras la vista previa en el navegador

Uso directo del paquete:

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

start stack se desaconseja de forma intencional en la CLI porque MCP sobre stdio 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

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 repositorio
• 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 upgrades: 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 repositorio
• 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/datasets
• PATCH /api/datasets/:id
• GET /api/events

Notas:

• GET /api/dashboards/:id devuelve solo dashboards publicados
• 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

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

Reemplaza el dataset coffee_roastery_lab cada mes usando la API local.

Bash:

#!/usr/bin/env bash
set -euo pipefail
CSV_FILE="$1"
API_URL="${API_URL:-http://localhost:4010/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:4010/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"])

Ejecuta esto 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 hoy por packages/mcp-server/src/index.ts.

Herramientas de dashboards

• 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

Herramientas de datasets

• 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 de gráficos y estilo

• create_chart
• list_theme_presets
• set_chart_theme
• set_chart_presentation
• reset_chart_presentation

En modo lite, el conjunto de herramientas 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 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
• 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 multi-bar agrupados/apilados

Acepta solicitudes en inglés y también estilo español mediante coincidencia ligera de intención. El payload de respuesta está resumido de forma intencional para reducir el uso de MCP en clientes con cuotas ajustadas.

Operaciones de dashboard

create_dashboard

Crea un dashboard con estos campos opcionales:

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

Si no se pasa 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 actuales soportados 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 ubica automáticamente en la grilla, salvo que pases una colocación personalizada

Eliminación y recuperación de dashboards

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

Modelo de snapshots

Los snapshots de dashboard están diseñados como un único punto por dashboard.

Comportamiento actual:

• snapshot_dashboard sobrescribe el snapshot existente para 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 rollback por dashboard.

Operaciones de dataset

register_dataset

Los datasets pueden crearse a partir de:

• texto CSV crudo
• filas JSON

update_dataset

Modos de actualización actuales:

• 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 se pueden actualizar
• El servidor guarda un 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.

Tipos de gráficos que realmente existen

Tipos de gráficos 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

Diferencia 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 de la 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

Un tipo de gráfico parece faltar

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.