Gavriel MCP

Servidor MCP local (TypeScript) que expone la API de Gavriel — sistema de monitoreo de alarmas — como herramientas para agentes de IA (OpenCode, Claude Desktop).

Requisitos

• Node.js 18+ (probado con Node 22)

• Credenciales de usuario de Gavriel (app.gavriel.com.ar)

Related MCP server: Moleculer MCP Bridge

Instalación

cd ~/proyectos/gavriel-mcp
npm install
npm run build
cp .env.example .env   # completar GAVRIEL_EMAIL y GAVRIEL_PASSWORD

Configuración

src/config.ts lee estas variables (de .env o del entorno):

Configuración del rol de servicio

El rol de servicio está definido en PROPUESTA_ROL_SERVICIO.md. La configuración recomendada es usar el rol MCP Service (solo lectura) como default.

Nota: hoy el MCP se loguea con una cuenta Admin (CRUD completo). Ese es el estado actual no deseado que la propuesta de rol busca reemplazar, no un modo de uso soportado. Configurar la cuenta Admin solo tiene sentido como paso previo hasta crear el rol MCP Service.

El JWT se cachea en memoria (nunca en disco) y se renueva ~5 min antes de expirar o ante un 401. La API renueva el token vía el header x-new-token, que el cliente respeta automáticamente.

Resolución de secretos

El server resuelve password y trusted_device_token al arrancar, en este orden (ver src/secrets.ts):

1. Keyring del sistema (secret-tool, paquete libsecret-tools): más seguro, es el modo recomendado.

2. Variables de entorno GAVRIEL_PASSWORD / GAVRIEL_TRUSTED_DEVICE_TOKEN (útil para dev local fuera de opencode).

3. Archivos legacy (~/.secrets/gavriel-password y ~/.local/share/gavriel-mcp/trusted-device.json): solo último recurso, con warning explícito en stderr.

El JWT se cachea en memoria (nunca en disco) y se renueva ~5 min antes de expirar o ante un 401. La API renueva el token vía el header x-new-token, que el cliente respeta automáticamente. El trusted_device_token (válido ~20 días, salta el 2FA en logins posteriores) también va al keyring.

Registrarlo en OpenCode

Instalar libsecret-tools (si no está) y guardar ambos secretos una sola vez, de forma interactiva (el valor se pide por stdin, no va en la línea de comando):

sudo apt install libsecret-tools    # si hace falta (daemon: gnome-keyring)

secret-tool store --label="Gavriel MCP - password" service gavriel-mcp account password
secret-tool store --label="Gavriel MCP - trusted device token" service gavriel-mcp account trusted_device_token

El server los lee solo del keyring; la config de opencode ya no necesita el secret:

{
  "mcp": {
    "gavriel": {
      "type": "local",
      "command": ["node", "/ruta/al/proyecto/gavriel-mcp/dist/index.js"],
      "environment": {
        "GAVRIEL_EMAIL": "user@example.com"
      },
      "enabled": true
    }
  }
}

Interino (hasta migrar): si secret-tool no está instalado, el server cae al archivo ~/.secrets/gavriel-password (chmod 600) con warning. En ese caso la config de opencode puede seguir usando {file:~/.secrets/gavriel-password} como hoy.

Herramientas

Los nombres MCP no llevan prefijo. Al usarlas desde una sesión de opencode, opencode antepone el nombre del server: create_ticket se expone como gavriel_create_ticket.

Lectura (no requieren confirm)

Escritura — todas requieren confirm: true

El gate es la Fase 0, regla 2: si confirm falta o es false, la tool no ejecuta nada y devuelve un preview (método + path + body). Si confirm: true, ejecuta y loguea la operación en writes.log.

Importante: probá siempre primero con confirm ausente/false y revisá el preview. La primera ejecución real de cada tool hacela en presencia del operador — son datos reales de clientes en producción.

Recursos (catálogos semi-estáticos, cache 1 h)

gavriel://catalog/... para eventos-types, events-codes, events-formats, protocols, intervention-categories, device-brands (y activas), device-models, device-connection-types (y activos), device-taxonomies, states, cities, jurisdictions, zones, tickets status/priority options, ticket-categories, activities type-options, events-types/gavriel-intervention y companies/type/technical.

Endpoints no implementados (Tier 3)

Los endpoints de escritura que exceden el perfil de riesgo aprobado (borrados, gestión de usuarios/roles, activación de monitoreo, facturación, catálogos, archivos) están inventariados en TIER3_PENDIENTE.md y no se implementan sin instrucción explícita.

Log de escrituras

Toda escritura ejecutada queda registrada en ~/.local/share/gavriel-mcp/writes.log (JSONL): timestamp, tool, parámetros, email del usuario del JWT, y respuesta de la API (status + body resumido). Esto es adicional al audit log propio de Gavriel (/audit/logs).

Despliegue

No se despliega: es local, transporte stdio. No requiere Docker ni el host Hyper-V.

Seguridad

• Los secretos (password y trusted_device_token) viven en el keyring del sistema (recomendado); el archivo legacy ~/.secrets/gavriel-password (chmod 600) queda solo como fallback interino con warning. El .env del repo (gitignoreado) es un fallback de ejecución local.

• El JWT nunca se persiste en disco.

• El gate de confirm evita ejecuciones accidentales; el control de cuándo se usan las escrituras queda a nivel de skill/prompt del agente, no bloqueado en el código (decisión del dueño del proyecto).

• Respuestas no parseables: ocasionalmente el backend puede devolver HTTP 200 con un body truncado o inválido. Esta tool lo detecta (writeStatus: "applied_response_unparseable"), loguea el body crudo y re-lee el recurso para verificar el estado real. No asumir éxito ni fallo ante ese status: consultar el verifiedState devuelto o re-consultar el recurso.