Heru Events MCP

MCP (Model Context Protocol) server para validar y monitorear eventos de analytics en Heru. Se integra con Claude Code para dar acceso a tools de consulta de eventos directamente desde el IDE.

Setup

1. Clonar el repo

git clone git@github.com:Heru-Technologies/heru-events-mcp.git
cd heru-events-mcp

2. Instalar dependencias

npm install

3. Configurar variables de entorno

cp config/.env.example config/.env

Edita config/.env con las credenciales reales. Pide los valores al equipo de backend.

4. Configurar Claude Code

Agrega el MCP a tu proyecto. Crea o edita .mcp.json en la raíz de heru-web-app:

{
  "mcpServers": {
    "heru-events-testing": {
      "command": "node",
      "args": [
        "/ruta/absoluta/a/heru-events-mcp/mcp-server.js"
      ]
    }
  }
}

Reemplaza /ruta/absoluta/a/ con la ruta donde clonaste el repo.

Eso es todo. Claude Code detecta el .mcp.json y ejecuta el server automáticamente cuando necesita las tools.

Tools disponibles

Tool	Descripcion
get_user_events	Consulta eventos de un usuario por rango de fechas
get_event_stats	Estadisticas de eventos por tipo, fuente y dia
validate_event_tracking	Valida que un evento llega a DB y Amplitude
compare_amplitude_vs_database	Compara eventos entre DB y Amplitude
validate_checkout_funnel	Valida el funnel completo de checkout
validate_stripe_payment	Valida un payment intent de Stripe
get_amplitude_funnel	Consulta datos de funnel en Amplitude
get_clevertap_user_profile	Perfil de usuario en CleverTap
get_clevertap_events	Eventos de CleverTap por nombre
get_clevertap_profile_count	Conteo de perfiles en CleverTap

Uso con Hermes

El agente /hermes en heru-web-app usa estas tools automaticamente para validar eventos despues de integrarlos. Ver .claude/commands/hermes.md en el proyecto web.

Scripts standalone

npm run query          # Consultar eventos
npm run query-db       # Consultar solo en DB
npm run compare        # Comparar DB vs Amplitude
npm run validate-funnel # Validar funnel

Variables de entorno

Variable	Requerida	Descripcion
EVENTS_DB_URI	Si	Connection string de PostgreSQL (eventos)
AMPLITUDE_API_KEY	Si	API key de Amplitude
AMPLITUDE_SECRET_KEY	No	Secret key de Amplitude (para Export API)
STRIPE_SECRET_KEY	No	Secret key de Stripe (para validar pagos)
CLEVERTAP_ACCOUNT_ID	No	Account ID de CleverTap
CLEVERTAP_PASSCODE	No	Passcode de CleverTap
DB_SSL	No	true para produccion, false para localhost