MCP
Referencia de tools · todas las tools

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

ToolQué haceInputsPermisoEjemplo 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.

ToolQué haceInputsPermisoEjemplo 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.

ToolQué haceInputsPermisoEjemplo 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)

ToolQué hacePermiso
analytics_set_dashboard_relationEscribe un join entre dos datasets adjuntos.write RLS: rol admin en el dashboard.
analytics_drop_dashboard_relationBorra una relación entre datasets.write RLS: rol admin en el dashboard.
analytics_list_dashboard_relationsLista las relaciones vigentes de un dashboard.read RLS: requiere poder ver el dashboard.
analytics_set_dashboard_nameRenombra un dashboard.write RLS: rol admin en el dashboard.
analytics_run_widget_queryEjecuta 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_queryEjecuta 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_rowsFilas 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_componentsComponentes 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.

ToolQué hacePermiso
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_linksLinks 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_auditQuié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_scopeScope visible del usuario en la consola de transacciones (ADR-0023) — organizaciones y proyectos.read RLS: resuelto por auth.uid().
analytics_get_org_tx_summaryRollup mensual de transacciones de una organización, por proyecto.read RLS: analytics.entitled; respeta el switch org_rollup_enabled.
analytics_get_project_tx_summaryRollup mensual de transacciones de un proyecto, por form.read RLS: analytics.entitled sobre el proyecto.
analytics_get_project_tx_usageConsumo de TX de un proyecto por mes y form (Bogotá).read RLS: analytics.entitled.
analytics_list_tx_usage_rowsDetalle conciliable de las TX contadas en un mes de un proyecto.read RLS: analytics.entitled.
analytics_get_tx_planCupo mensual de TX vigente de un proyecto en un mes.read RLS: analytics.entitled.
analytics_set_tx_planEscribe 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_monthCierra (congela) un mes de TX con su snapshot por proyecto y form.write RLS: analytics.entitled.
analytics_reopen_tx_monthReabre un mes de TX cerrado de un proyecto. Solo global admin.write RLS: analytics.entitled.
analytics_list_tx_usage_allVista Dynamo multi-cliente del consumo de TX: una fila por proyecto para un mes.read RLS: analytics.entitled.
analytics_list_tx_plansHistorial y vigente de los planes de cupo de TX de una organización y sus proyectos.read RLS: analytics.entitled.
analytics_end_tx_planTermina un plan de cupo vigente en una fecha. Solo global admin.write RLS: analytics.entitled.
analytics_list_task_template_fieldsClaves 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.

ToolQué hacePermiso
analytics_list_dashboard_access_groupsGrupos propios de analytics de un proyecto.read Gate: analytics.can_admin_project_access.
analytics_list_dashboard_access_group_membersMiembros de un grupo.read mismo gate, sobre el proyecto DEL GRUPO.
analytics_list_project_dashboards_grantsGrants de grano proyecto (alcanzan TODOS los dashboards, presentes y futuros).read mismo gate.
analytics_list_project_member_candidatesUsuarios del proyecto, para sacar los user_id que consumen los grants.read mismo gate.
analytics_list_project_dashboards_grantable_principalsCatálogo unificado de roles de Forms + grupos de analytics otorgables.read mismo gate.
analytics_list_dashboard_grantable_rolesRoles de Forms del proyecto, con el grant que ya tienen sobre UN dashboard.read rol admin en el dashboard.
analytics_list_dashboard_inherited_readersQuié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_principalsEl mapa completo: quién accede a un dashboard y por qué camino.read rol admin en el dashboard.
analytics_create_dashboard_access_groupCrea un grupo propio en un proyecto.write Gate: analytics.can_admin_project_access.
analytics_update_dashboard_access_groupRenombra/redescribe un grupo.write mismo gate, sobre el proyecto DEL GRUPO.
analytics_delete_dashboard_access_groupBorra un grupo, EN CASCADA (toda su membresía y grants).write mismo gate.
analytics_add_dashboard_access_group_memberSuma un usuario ya-del-proyecto a un grupo.write mismo gate.
analytics_remove_dashboard_access_group_memberSaca un usuario de un grupo (no le quita necesariamente el acceso — puede entrar por otro camino).write mismo gate.
analytics_grant_project_dashboards_accessOtorga acceso a TODOS los dashboards de un proyecto. Nivel tope: contributor — admin no se otorga acá.write mismo gate.
analytics_revoke_project_dashboards_accessRevoca un grant de grano proyecto.write mismo gate.
analytics_grant_dashboard_group_accessOtorga el acceso de un grupo sobre UN dashboard.write rol admin en el dashboard.
analytics_grant_dashboard_role_accessOtorga el acceso de un rol de Forms sobre UN dashboard.write rol admin en el dashboard.
analytics_revoke_dashboard_role_accessRevoca el acceso de un rol de Forms sobre un dashboard.write rol admin en el dashboard.
analytics_set_dashboard_inherit_form_rolesEnciende/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.