@griddo/activity-log-mcp

Servidor MCP que expone el Activity Log de la API privada de Griddo como primitivas MCP: herramientas (tools), un recurso y un prompt.

Todos los endpoints requieren rol superadmin en la instancia de Griddo de destino. El servidor utiliza el transporte stdio.

Configuración

El servidor lee las credenciales desde variables de entorno:

| Variable | Descripción | | --------------------- | -------------------------------------------------------- | | GRIDDO_API_URL | URL base de la API privada de Griddo. | | GRIDDO_API_EMAIL | Email de un usuario superadmin. | | GRIDDO_API_PASSWORD | Contraseña de ese usuario. |

El servidor inicia sesión de forma perezosa en la primera llamada a una herramienta (POST /login_check), cachea el token devuelto y reintenta una vez si recibe un 401.

Uso desde un cliente MCP

Claude Code

Claude Code añade el servidor con el comando claude mcp add. Elige el ámbito según cómo quieras compartirlo:

• -s user: disponible en todos los proyectos de esta máquina.
• -s project: se escribe en un .mcp.json versionable en la raíz del repositorio; cualquiera que clone el repo lo obtiene.
• -s local (por defecto): solo este proyecto, solo esta máquina.

claude mcp add griddo-activity-log -s user \
  --env GRIDDO_API_URL=https://api.tu-griddo.example.com \
  --env [email protected] \
  --env GRIDDO_API_PASSWORD=*** \
  -- npx -y @griddo/activity-log-mcp

Comprueba que se ha cargado:

claude mcp list
claude mcp get griddo-activity-log

Para eliminarlo más adelante:

claude mcp remove griddo-activity-log

Ámbito de proyecto vía .mcp.json

Si has usado -s project, el comando anterior crea o actualiza el archivo .mcp.json en la raíz del repositorio. También puedes escribirlo a mano y subirlo al repo:

{
  "mcpServers": {
    "griddo-activity-log": {
      "command": "npx",
      "args": ["-y", "@griddo/activity-log-mcp"],
      "env": {
        "GRIDDO_API_URL": "https://api.tu-griddo.example.com",
        "GRIDDO_API_EMAIL": "[email protected]",
        "GRIDDO_API_PASSWORD": "***"
      }
    }
  }
}

No subas credenciales reales al repositorio: usa valores de ejemplo y que cada desarrollador los rellene en local, o léelos desde el entorno ("GRIDDO_API_PASSWORD": "${GRIDDO_API_PASSWORD}").

Uso de las herramientas desde Claude Code

Una vez añadido el servidor, reinicia Claude Code (o ejecuta /mcp para refrescar). Las herramientas, el recurso activity://event-types y el prompt daily-activity-digest aparecen automáticamente. Los comandos coinciden con el nombre de cada herramienta: por ejemplo, get_activity_timeline, export_activity_logs. Ejecuta /mcp dentro de Claude Code para revisar el estado del servidor y las herramientas conectadas.

Claude Desktop o cualquier cliente MCP por stdio

Añade una entrada bajo mcpServers en el JSON de configuración del cliente:

{
  "mcpServers": {
    "griddo-activity-log": {
      "command": "npx",
      "args": ["-y", "@griddo/activity-log-mcp"],
      "env": {
        "GRIDDO_API_URL": "https://api.tu-griddo.example.com",
        "GRIDDO_API_EMAIL": "[email protected]",
        "GRIDDO_API_PASSWORD": "***"
      }
    }
  }
}

Herramientas (tools)

| Herramienta | Método | Endpoint | | --------------------------------- | ------ | --------------------------------------- | | get_activity_timeline | GET | /logs/activity-timeline | | get_activity_grouped_by_user | GET | /logs/activity-grouped-user | | get_activity_grouped_by_day | GET | /logs/activity-grouped-day | | export_activity_logs | POST | /logs/{timeline\|grouped-user\|grouped-day}/export |

Las tres herramientas de listado comparten los parámetros de consulta de LogActivityPaginationRequest: pagination, page, itemsPerPage, order, search, date, sites, contentTypes, eventTypes, users.

export_activity_logs recibe un discriminador scope ("timeline" | "grouped-user" | "grouped-day") y el cuerpo LogActivityExportRequest (format, dateRange, startTime?, maxEvents?).

Recursos

| URI | mimeType | Descripción | | --------------------------- | ------------------ | --------------------------------------------------------------------------- | | activity://event-types | application/json | Catálogo de tipos de evento disponibles (id + etiqueta), obtenido de /logs/activity-events-type. |

Prompts

| Nombre | Argumentos | Descripción | | -------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | daily-activity-digest | date? (YYYY/MM/DD, por defecto ayer en UTC), sites? (CSV de IDs de site y/o global) | Resumen ejecutivo de la actividad de Griddo en un día. |

Desarrollo local

Desde la raíz del monorepo:

pnpm -F @griddo/activity-log-mcp build
node --env-file=.env packages/activity-log-mcp/dist/index.js

Licencia

MIT