Tools de analytics
71 tools del dominio analytics montadas en
https://mcp.dynamotech.co/mcp. Corren siempre
como vos — con tu identidad de Entra ya resuelta
(Gateway.asUser sobre pg-dynamo-<env>),
nunca con una clave de servicio. El scope de tu token (read
/ write) es una capa aditiva; el
gate real es la RLS de pg-dynamo-<env>:
si no tenés acceso al proyecto o al dashboard, la fila no existe
para vos — cero excepciones por clave de servicio.
Rename. En el MCP local (stdio) de
hoy estas tools se llaman sin el prefijo
analytics_ (list_dashboards,
get_my_projects, set_field_config, …). En
el gateway solo existen los nombres nuevos, con
prefijo analytics_ — son los que documenta esta
página. Los nombres viejos siguen vivos únicamente en
stdio, marcados [DEPRECADO] durante un
sprint. Instalación y uso local: Para
desarrolladores.
Lectura
| Tool | Qué hace | Inputs | Permiso | Ejemplo de prompt |
|---|---|---|---|---|
analytics_list_dashboards |
Lista los dashboards de un proyecto — id, form_id, name, tu rol (my_role). |
project_id (uuid) |
read RLS: ves solo los dashboards donde tenés algún rol. | "Mostrame los dashboards del proyecto de Minera Andina." |
analytics_get_form_metrics |
Métricas del dashboard de un form (resuelve form_id→dashboard_id). 100% lectura por default. |
form_id (uuid) · create_if_missing (bool, default false) |
read para leer · create_if_missing:true exige además write y el mismo gate que analytics_create_dashboard. |
"Traeme las métricas del form de ingreso a mina." |
analytics_get_field_config |
Config de visibilidad/orden/override de gráfico por campo de un dashboard. | dashboard_id (uuid) |
read RLS: requiere poder ver el dashboard. | "¿Qué campos están visibles en este dashboard y en qué orden?" |
analytics_list_analytics_forms |
Forms con analytics habilitado de un proyecto, con si ya tienen dashboard. | project_id (uuid) |
read RLS: proyectos donde tenés acceso. | "¿Qué forms tienen analytics activado en este proyecto?" |
analytics_get_form_components |
Componentes reales del form vinculado a un dashboard (field_key, label, tipo, shared resource). |
dashboard_id (uuid) |
read RLS: requiere rol admin en el dashboard. | "Necesito armar la config de presencia — dame los componentes del form de este dashboard." |
analytics_get_shared_resource_columns |
Columnas reales de la tabla de un shared resource (para elegir columna de breakdown o de nombre). | dashboard_id (uuid) · shared_resource_id (uuid) |
read RLS: requiere rol admin en el dashboard. | "¿Qué columnas tiene el recurso compartido de empleados de este dashboard?" |
analytics_get_dashboard_branding |
Identidad visual (whitelabel): logos, colores y nombre de la organización dueña + nombre del dashboard. | dashboard_id (uuid) |
read RLS: falla "forbidden" si no podés ver el dashboard. | "¿Qué branding tiene configurado este dashboard?" |
analytics_get_dashboard_presence_config |
Config de "net presence" (Trabajadores en Mina Ahora) de un dashboard. | dashboard_id (uuid) |
read RLS: vacío si no tenés acceso — nunca lanza. | "¿Cómo está configurada la presencia en este dashboard?" |
analytics_get_dashboard_presence_detail |
Tabla "Detalle" de presencia. Con scope recent (default): los últimos movimientos, Ingresos y Salidas, más recientes primero. Con inside: QUIÉNES están adentro, una fila por persona cuyo último movimiento es el Ingreso (lugar y hora de ese Ingreso); ignora limit, tope 5000. |
dashboard_id (uuid) · limit (1-500, default 50) · scope (recent|inside, default recent) |
read RLS: vacío sin acceso — nunca lanza. | "Mostrame los últimos 20 movimientos de presencia." |
analytics_get_project_dashboard_sort_mode |
Modo de orden de los dashboards de un proyecto: manual (default, manda sort_order) o alphabetical (por nombre). Es el orden en que analytics_list_dashboards y el menú Reportes listan los tableros. |
project_id (uuid) |
read Gate: analytics.entitled del proyecto. |
"¿Cómo se ordenan los dashboards de este proyecto?" |
Configuración
Escriben sobre un dashboard existente. Todas exigen rol admin en ese dashboard vía RLS — un token con scope write sin ese rol sigue fallando en la base de datos, nunca en el MCP.
| Tool | Qué hace | Inputs | Permiso | Ejemplo de prompt |
|---|---|---|---|---|
analytics_create_dashboard |
Crea (o devuelve, si ya existe) el dashboard de Analytics de un form. | form_id (uuid) |
write RLS: el form necesita has_analytics=true + rol sobre el form (admin global, de proyecto, o propio). |
"Creá el dashboard de analytics para este form." |
analytics_delete_dashboard |
Borra un dashboard. Soft-delete (is_active=false), no un DELETE físico: la fila de auditoría de quién borró qué sobrevive. Desaparece de toda lectura de inmediato. No reversible por MCP. |
dashboard_id (uuid) |
write RLS: rol admin en el dashboard + analytics.entitled. |
"Borrá este dashboard obsoleto." |
analytics_move_dashboard |
Sube o baja un dashboard un puesto dentro del sidebar (orden plano, sin carpetas ni jerarquía). Swapea el sort_order con el vecino inmediato en una sola transacción; si ya es primero (up) o último (down) es un no-op seguro: devuelve moved:false sin fallar. Queda auditado en dashboard_model_audit (action="reorder"). El orden nuevo se lee con analytics_list_dashboards (columna sort_order). |
dashboard_id (uuid) · direction (up|down) |
write RLS: rol admin en el dashboard (y en su vecino) + analytics.entitled. |
"Subí este dashboard un puesto en el menú." |
analytics_set_project_dashboard_sort_mode |
Cambia el modo de orden de los dashboards de un proyecto: manual o alphabetical (por nombre, sin distinguir mayúsculas ni tildes, orden natural de números). Idempotente. No toca sort_order: al volver a manual reaparece el orden manual previo. En alphabetical, analytics_move_dashboard falla con sort_mode_alphabetical. |
project_id (uuid) · mode (manual|alphabetical) |
write Admin del proyecto o global admin + analytics.entitled. |
"Ordená alfabéticamente los dashboards de este proyecto." |
analytics_list_dashboard_folders |
Lista las carpetas del menú Reportes de un proyecto (un nivel, sin ACL propia), en su orden manual. | project_id (uuid) |
read RLS: analytics.entitled del proyecto. |
"¿Qué carpetas tiene el menú Reportes de este proyecto?" |
analytics_create_dashboard_folder |
Crea una carpeta en el menú Reportes de un proyecto, al final del orden. Nombre único por proyecto (sin distinguir mayúsculas). | project_id (uuid) · name |
write Admin del proyecto o global admin + analytics.entitled. |
"Creá la carpeta Financiero en Reportes." |
analytics_rename_dashboard_folder |
Renombra una carpeta del menú Reportes. Falla con folder_name_taken si otra carpeta del proyecto ya se llama así. |
folder_id (uuid) · name |
write Admin del proyecto o global admin + analytics.entitled. |
"Renombrá la carpeta Financiero a Finanzas." |
analytics_delete_dashboard_folder |
Borra una carpeta del menú Reportes. Sus tableros NO se borran: quedan sin carpeta. | folder_id (uuid) |
write Admin del proyecto o global admin + analytics.entitled. |
"Borrá la carpeta vacía de Reportes." |
analytics_move_dashboard_folder |
Sube o baja una carpeta del menú Reportes un puesto. El orden de carpetas es siempre manual. | folder_id (uuid) · direction (up|down) |
write Admin del proyecto o global admin + analytics.entitled. |
"Subí la carpeta Finanzas un puesto." |
analytics_set_dashboard_folder |
Pone un dashboard en una carpeta del menú Reportes, o lo deja sin carpeta (folder_id: null). Idempotente. |
dashboard_id (uuid) · folder_id (uuid|null) |
write Rol admin en el dashboard + analytics.entitled. |
"Poné este dashboard en la carpeta Finanzas." |
analytics_set_field_config |
Visibilidad, orden y override de gráfico de un campo del dashboard. | dashboard_id, field_key, visible (bool), chart_override (bar|stats|number|pie, opcional), label_override (opcional), sort_order (int) |
write RLS: rol admin en el dashboard. | "Ocultá el campo de comentarios y poné el gráfico de edad primero." |
analytics_grant_dashboard_access |
Otorga o actualiza el rol de un usuario ya existente sobre un dashboard. | dashboard_id, user_id (uuid), role (viewer|analyst|admin, default viewer) |
write RLS: rol admin en el dashboard. | "Dale rol analyst a este usuario en el dashboard." |
analytics_revoke_dashboard_access |
Revoca el acceso de un usuario a un dashboard. | dashboard_id, user_id (uuid) |
write RLS: rol admin en el dashboard. | "Sacale el acceso a este dashboard a este usuario." |
analytics_invite_dashboard_by_email |
Invita por email: acceso directo si ya tiene cuenta (status="granted"), invitación pendiente si no (status="invited"). |
dashboard_id, email, role (default viewer) |
write RLS: rol admin en el dashboard. | "Invitá a fulano@empresa.com como viewer de este dashboard." |
analytics_set_presence_config |
Configura "net presence": campo de identidad/evento, breakdown opcional, lugar opcional, columnas de nombre. | dashboard_id, identity_field_key, event_field_key, in_value (default "Ingreso"), out_value (default "Salida"), shared_resource_id?, breakdown_column?, place_field_key?, name_columns? |
write RLS: rol admin en el dashboard. | "Configurá la presencia con el campo de cédula como identidad y el de tipo de movimiento como evento." |
Authoring del dashboard_spec
El spec declarativo (grilla de widgets) que reemplaza al template
legacy de un dashboard. Escrituras con optimistic locking
(base_version): si alguien más escribió en el medio, la
RPC falla con spec_version_conflict — no es un bug, es
el sistema evitando que dos escrituras se pisen. Releé con
analytics_get_dashboard_spec y reintentá con la versión
nueva.
| Tool | Qué hace | Inputs | Permiso | Ejemplo de prompt |
|---|---|---|---|---|
analytics_get_dashboard_spec |
Lee el spec vigente de un dashboard + su spec_version. 0 filas = sin spec todavía, o sin permiso (no distingue los dos casos). |
dashboard_id (uuid) |
read RLS: acceso de lectura al dashboard. | "¿Qué spec tiene este dashboard ahora mismo?" |
analytics_set_dashboard_spec |
Escribe el spec completo con locking optimista (base_version; 0 = crear el primero). Con dry_run:true solo valida forma (ajv) — nunca escribe. |
dashboard_id, spec (objeto), base_version (int), dry_run (default false), via (mcp|editor|migrator|sql, default mcp) |
write RLS: rol admin en el dashboard. | "Aplicá este diseño de dashboard que armamos." |
analytics_delete_dashboard_spec |
"Restablecer diseño": borra el spec vigente y vuelve al template legacy. No borra el historial. | dashboard_id (uuid) |
write RLS: rol admin en el dashboard. | "Volvé este dashboard al diseño por defecto." |
analytics_edit_component |
Aplica UNA operación (add|update|remove|move) sobre un componente puntual del spec, sin reescribir el spec entero. Se llamaba analytics_edit_widget hasta analytics-mcp 0.7.0. |
dashboard_id, base_version, op, component_id, component (objeto, add/update), layout ({x,y,w,h}, move), via |
write RLS: rol admin en el dashboard (lo gatea analytics_set_dashboard_spec). |
"Movéme la tarjeta de KPI a la esquina superior derecha." |
analytics_check_spec |
Valida la FORMA de un spec propuesto — 100% client-side (ajv contra el JSON-Schema), cero llamadas a la base. | spec (objeto) · dashboard_id (opcional) |
Ninguno más allá de estar autenticado — no toca la DB. | "¿Este spec que armé es válido?" |
analytics_get_spec_format |
JSON-Schema canónico del dashboard_spec + ejemplos empaquetados (mínimo, réplica de presencia, v1.1 documental). Cero DB. |
(ninguno) | Ninguno más allá de estar autenticado — no toca la DB. | "Mostrame el formato del dashboard_spec con un ejemplo." |
analytics_list_datasets |
Lista los datasets adjuntos de un dashboard (modelo multi-dataset): dataset_key, form de origen, label y columnas. |
dashboard_id (uuid) |
read RLS: rol admin en el dashboard + proyecto con analytics habilitado. | "¿Qué datasets tiene enganchados este dashboard?" |
analytics_attach_dataset |
Adjunta un form como dataset adicional del dashboard, bajo un dataset_key. Ojo: un dataset_key ya usado en un detach no se puede reusar. |
dashboard_id, form_id, dataset_key (^[a-z][a-z0-9_]{0,23}$), label (opcional) |
write RLS: rol admin en el dashboard. | "Sumá el form de novedades como dataset de este dashboard." |
analytics_detach_dataset |
Desadjunta un dataset del dashboard. No se puede desadjuntar el dataset primario, y el dataset_key queda quemado para siempre. |
dashboard_id, dataset_key |
write RLS: rol admin en el dashboard. | "Sacá el dataset de novedades de este dashboard." |
analytics_generate_spec_draft |
Sintetiza (sin escribir nada) un spec de arranque a partir del estado real del dashboard: presencia configurada + un widget por métrica visible. | dashboard_id (uuid) |
read RLS: lee config de presencia/campos/métricas del dashboard. | "Armame un primer diseño para este dashboard a partir de lo que ya tiene configurado." |
Nuevas en analytics-mcp@0.15.0 (34)
Analytics-dynamo pagó su deuda de superficie MCP declarada
(surface-catalog.ts, dominio propio): 34 tools nuevas en
cuatro bloques, todas auditadas contra la clase de bug de RPC que
recibe el actor por parámetro ANTES de exponerse (SECURITY DEFINER,
gate como primera sentencia, sujeto siempre auth.uid()).
12 de estas tools se renombraron el mismo día que se publicaron
(analytics-dynamo#233) porque el nombre viejo sonaba a entitlement de
auth y es en realidad acceso a los dashboards del proyecto.
Relaciones multi-dataset y motor de datos v1.1 (8)
| Tool | Qué hace | Permiso |
|---|---|---|
analytics_set_dashboard_relation | Escribe un join entre dos datasets adjuntos. | write RLS: rol admin en el dashboard. |
analytics_drop_dashboard_relation | Borra una relación entre datasets. | write RLS: rol admin en el dashboard. |
analytics_list_dashboard_relations | Lista las relaciones vigentes de un dashboard. | read RLS: requiere poder ver el dashboard. |
analytics_set_dashboard_name | Renombra un dashboard. | write RLS: rol admin en el dashboard. |
analytics_run_widget_query | Ejecuta un componente del spec vigente y devuelve sus cifras — cierra el lazo escribir→validar→ejecutar. | read RLS: poder VER el dashboard, no hace falta ser admin. |
analytics_preview_widget_query | Ejecuta un query suelto (sin persistirlo) contra un dashboard, para iterar antes de guardarlo. | Gate MÁS DURO que run: rol admin (un query arbitrario elige qué columnas se proyectan). |
analytics_get_widget_drill_rows | Filas crudas detrás de una cifra (el drill-down del spec), con limit obligatorio 1..500. | read RLS: poder VER el dashboard. |
analytics_get_dataset_components | Componentes de un dataset secundario adjunto, para saber qué field_keys referenciar en el spec. | Rol admin + analytics.entitled en el proyecto. |
Estado de publicación pública y consola de transacciones (6)
Publicar, rotar y revocar links públicos siguen sin tool a propósito (ADR-0020: acto humano con doble acknowledgment). Estas 6 son LECTURA del estado, con el mismo gate que publicar.
| Tool | Qué hace | Permiso |
|---|---|---|
analytics_get_dashboard_publish_state | ¿Está expuesto a internet? Con qué link, desde cuándo y quién lo publicó. | read RLS: analytics.can_publish_dashboard. |
analytics_list_dashboard_affected_links | Links públicos vivos y cuáles cayeron por un cambio de modelo (attach/detach de dataset, herencia). | read RLS: rol admin + entitled. |
analytics_get_dashboard_link_audit | Quién abrió un link público, cuándo y qué pidió (hashes de IP/UA, nunca los datos crudos). | read RLS: analytics.can_publish_dashboard sobre el dashboard del link. |
analytics_list_tx_scope | Scope visible del usuario en la consola de transacciones (ADR-0023) — organizaciones y proyectos. | read RLS: resuelto por auth.uid(). |
analytics_get_org_tx_summary | Rollup mensual de transacciones de una organización, por proyecto. | read RLS: analytics.entitled; respeta el switch org_rollup_enabled. |
analytics_get_project_tx_summary | Rollup mensual de transacciones de un proyecto, por form. | read RLS: analytics.entitled sobre el proyecto. |
analytics_get_project_tx_usage | Consumo de TX de un proyecto por mes y form (Bogotá). | read RLS: analytics.entitled. |
analytics_list_tx_usage_rows | Detalle conciliable de las TX contadas en un mes de un proyecto. | read RLS: analytics.entitled. |
analytics_get_tx_plan | Cupo mensual de TX vigente de un proyecto en un mes. | read RLS: analytics.entitled. |
analytics_set_tx_plan | Escribe el cupo mensual de TX de una organización (bolsa compartida) o de un proyecto. Solo global admin. | write RLS: analytics.entitled. |
analytics_close_tx_month | Cierra (congela) un mes de TX con su snapshot por proyecto y form. | write RLS: analytics.entitled. |
analytics_reopen_tx_month | Reabre un mes de TX cerrado de un proyecto. Solo global admin. | write RLS: analytics.entitled. |
analytics_list_tx_usage_all | Vista Dynamo multi-cliente del consumo de TX: una fila por proyecto para un mes. | read RLS: analytics.entitled. |
analytics_list_tx_plans | Historial y vigente de los planes de cupo de TX de una organización y sus proyectos. | read RLS: analytics.entitled. |
analytics_end_tx_plan | Termina un plan de cupo vigente en una fecha. Solo global admin. | write RLS: analytics.entitled. |
analytics_list_task_template_fields | Claves de inheritance_mapping de los task_templates activos de un proyecto, para armar un spec query.source:"tasks". | read RLS: analytics.entitled sobre el proyecto. |
Gestión de acceso con grupos propios (ADR-0021, 19)
8 lecturas + 12 escrituras. Las 8 lecturas devuelven identidades de
otras personas (emails, membresía) — ninguna es "pública para quien ve
el dashboard": todas exigen administrar el acceso. Las 12 escrituras
administran acceso INTERNO con sesión (Daniel las autorizó
explícitamente); 12/12 auditadas: SECURITY DEFINER, gate
como primera sentencia, sujeto siempre auth.uid(), sin
auto-otorgamiento ni escalada cross-proyecto, ninguna puede otorgar
admin.
| Tool | Qué hace | Permiso |
|---|---|---|
analytics_list_dashboard_access_groups | Grupos propios de analytics de un proyecto. | read Gate: analytics.can_admin_project_access. |
analytics_list_dashboard_access_group_members | Miembros de un grupo. | read mismo gate, sobre el proyecto DEL GRUPO. |
analytics_list_project_dashboards_grants | Grants de grano proyecto (alcanzan TODOS los dashboards, presentes y futuros). | read mismo gate. |
analytics_list_project_member_candidates | Usuarios del proyecto, para sacar los user_id que consumen los grants. | read mismo gate. |
analytics_list_project_dashboards_grantable_principals | Catálogo unificado de roles de Forms + grupos de analytics otorgables. | read mismo gate. |
analytics_list_dashboard_grantable_roles | Roles de Forms del proyecto, con el grant que ya tienen sobre UN dashboard. | read rol admin en el dashboard. |
analytics_list_dashboard_inherited_readers | Quiénes leen un dashboard SOLO por herencia de roles de Forms — leé esto antes de apagar la herencia. | read rol admin + entitled. |
analytics_list_dashboard_principals | El mapa completo: quién accede a un dashboard y por qué camino. | read rol admin en el dashboard. |
analytics_create_dashboard_access_group | Crea un grupo propio en un proyecto. | write Gate: analytics.can_admin_project_access. |
analytics_update_dashboard_access_group | Renombra/redescribe un grupo. | write mismo gate, sobre el proyecto DEL GRUPO. |
analytics_delete_dashboard_access_group | Borra un grupo, EN CASCADA (toda su membresía y grants). | write mismo gate. |
analytics_add_dashboard_access_group_member | Suma un usuario ya-del-proyecto a un grupo. | write mismo gate. |
analytics_remove_dashboard_access_group_member | Saca un usuario de un grupo (no le quita necesariamente el acceso — puede entrar por otro camino). | write mismo gate. |
analytics_grant_project_dashboards_access | Otorga acceso a TODOS los dashboards de un proyecto. Nivel tope: contributor — admin no se otorga acá. | write mismo gate. |
analytics_revoke_project_dashboards_access | Revoca un grant de grano proyecto. | write mismo gate. |
analytics_grant_dashboard_group_access | Otorga el acceso de un grupo sobre UN dashboard. | write rol admin en el dashboard. |
analytics_grant_dashboard_role_access | Otorga el acceso de un rol de Forms sobre UN dashboard. | write rol admin en el dashboard. |
analytics_revoke_dashboard_role_access | Revoca el acceso de un rol de Forms sobre un dashboard. | write rol admin en el dashboard. |
analytics_set_dashboard_inherit_form_roles | Enciende/apaga la herencia de roles de Forms — puede sacarle el acceso a gente; mirá analytics_list_dashboard_inherited_readers antes de apagarla. | write rol admin + entitled. |
Lo que NO está acá.
analytics_pbix_extract y
analytics_pbix_propose_spec se quedan
stdio-only y no se exponen en el gateway: el primero
lee un .pbix del disco de quien invoca y el segundo
escribe report.md/proposed_spec.json a
ese mismo disco — en un container remoto y compartido ese "disco"
no existe, y subir un .pbix de cliente ahí es una
decisión de manejo de datos que merece su propio diseño, no un
efecto colateral de este gateway. El flujo de migración PBIX se
sigue corriendo local — ver Para
desarrolladores. El paso que sí queda cubierto acá es aplicar
el resultado con analytics_set_dashboard_spec.
Tampoco está analytics_session_status: lo reemplaza
dynamo_session_status, documentada en
Tools de ops.