LogLens

Un servidor MCP (Model Context Protocol) para análisis de registros (logs). En lugar de pegar un archivo de log en un chat y pedirle a un LLM que lo depure, LogLens expone la búsqueda en logs, la recuperación de contexto y el resumen de incidentes como herramientas a las que cualquier cliente compatible con MCP (Claude Desktop, Claude Code o tu propio agente) puede llamar directamente — con recuperación dirigida en lugar de inflar el contexto, y un paso de autoverificación para detectar afirmaciones de causa raíz sin respaldo antes de devolverlas.

Por qué existe

Creada como una versión pública de portafolio de un analizador de logs con IA que ganó el 1.er puesto en un hackathon interno. La versión corta de por qué supera al método de pegar el log en el chat: los logs de producción no caben en una ventana de contexto, un texto pegado en un chat no es invocable por otros sistemas, y un prompt en bruto no tiene ningún mecanismo para comprobar si la respuesta del modelo está de verdad fundamentada en los datos del log.

Related MCP server: Log Analyzer MCP

Estado

• Servidor principal, 3 herramientas — funcionales de punta a punta con un log de ejemplo. ✅

• Generación de causa raíz basada en LLM con un bucle de verificación de alucinaciones que comprueba la hipótesis en dos ejes independientes y reintenta una vez si falla en alguno. ✅

• Arquitectura de varios proveedores (Groq + Gemini) — el verificador corre en una familia de modelos distinta a la del generador, así que la comprobación no comparte los puntos ciegos del generador. ✅

• Suite de evaluación de 8 casos, puntuación determinista, 8/8 pasando. ✅

• Dockerizado, funciona como servidor HTTP accesible desde la red, verificado de extremo a extremo contra un contenedor en ejecución. ✅

• Siguiente: despliegue en la nube (Azure Container Apps o similar), un GIF de demostración.

Herramientas

Arquitectura

Question ──▶ extract search terms (Groq, gpt-oss-20b)
                 │
                 ▼
         search_logs (lexical match)
                 │
                 ▼
    + time-window expansion (asymmetric: 900s before / 180s after —
      causes precede symptoms)
                 │
                 ▼
    + global anomaly scan (all WARN/ERROR lines, not just in-window —
      the explaining line is often itself a warning)
                 │
                 ▼
       generate hypothesis (Groq, gpt-oss-120b)
                 │
                 ▼
    verify: soundness + completeness (Gemini — DIFFERENT provider
    from the generator, on purpose; falls back to same-provider
    Groq if Gemini is unavailable, and reports which happened)
                 │
          unsound/incomplete? ──▶ regenerate once, feeding back
                 │                the lines the first pass overlooked
                 ▼
              answer

Dos proveedores, y a propósito — no solo una solución para el límite de coste

Groq realiza la extracción y la generación de hipótesis; Gemini realiza la verificación. Esto comenzó como una solución a la cuota (el nivel gratuito de Gemini limita a 20 peticiones/día; el de Groq es mucho más generoso), pero se convirtió en una mejora arquitectónica real: un verificador que solo comparte modelo con la hipótesis que está comprobando comparte también sus puntos ciegos. Verificar la hipótesis con una familia de modelos distinta convierte la comprobación de alucinaciones en algo genuinamente independiente, no solo una segunda opinión de la misma fuente. Verification.independent reporta si una respuesta concreta recibió de verdad la comprobación entre proveedores o cayó en un proveedor único (Gemini caído/no configurado) — la información aflora, no se oculta.

La brecha de recuperación entre servicios — encontrada vía test, corrección a la capa adecuada

Las pruebas tempranas destaparon una limitación real: summarize_incident encontraba la causa inmediata de un error de checkout (agotamiento del pool de la DB) pero no alcanzaba la causa escrit uppersteam que el propio log de ejemplo transmite — una query de larga duración en otro servicio que era la que retenía la conexión. Dos problemas estructurales:

• La recuperación era puramente léxica. Los términos extraídos estaban limitados al checkout, así que las líneas de inventory-service jamás podían entrar en el conjunto de evidencias, sin importar lo buen el razonamiento. Se corrigió a propósito con una expansión de ventana de datos asimétrica (900 segundos antes / 180 después); las causas preceden siempre a los síntomas, con frecuencia por un margen superior al que atraparía una ventana simétrica corta — y sobre eso un escaneo global de líneas anómalas (WARN/ERROR) sin límite de ventana, porque a menudo la línea que explica algo es en sí misma una advertencia ("NTP sync failed", "rotation skipped").

• El verificador solo podía dar el visto bueno. Inicialmente veía tan solo las líneas que una hipótesis citaba, lo cual lo hacía estructuralmente incapaz de advertir una respuesta incompleta: una hipótesis que describe el síntoma siempre parecerá respaldada por las líneas que eligió citar. Ahora ve el conjunto de evidencias al completo y califica soundness y completeness por separado; un veredicto sólido pero incompleto retroalimenta a la regeneración las líneas que pasó por alto.

Suite de evaluación

npx tsx evals/run-evals.ts          # all 8 cases
npx tsx evals/run-evals.ts 03 08    # a subset, by id substring

8 casos que cubren arquetipos de fallas muy distintas: contención de recursos entre servicios, caída de la memoria por caché descontrolada, amplificación de tormenta de reintentos, un despliegue erróneo, dos causas que se combinan, un reloj desviado en un solo nodo, un log sano (la respuesta correcta es "nada falla") y un caso de síntoma ruidoso que tapa una causa sutil, creado específicamente para ejercitar el eje de exhaustividad. La puntuación es determinista — grupos de conceptos con sinónimos, más la necesidad de citar las evidencias, sin un juez LLM — para que las ejecuciones sean reproducibles. El informe separa los fallos de recuperación (evidencia nunca llegó al modelo) de los fallos de razonamiento (la evidencia estaba presente pero la respuesta seguía equivocada), pues requieren soluciones distintas.

Resultado actual: 8/8 superando, 0 fallos de recuperación, 0 fallos de razonamiento.

Depurar esta suite es también en sí mismo una historia de ingeniería aprovechable: una ventana temporal asimétrica y un escaneo global de anomalías resolvieron fragilidad real en la recuperación; en el plan gratuito de Groq, max_tokens es una reserva contra un presupuesto de tokens por minuto, no un límite de gasto medio — un valor demasiado alto devuelve un 413 sin importar el tamaño real del prompt; fue necesario usar reasoning_effort: "low" con los modelos gpt-oss, que de otra forma consumen el presupuesto en tokens de razonamiento y se truncan antes de emitir JSON válido; además, el propio harness tenía dos errores de puntuación (variantes Unicode de puntuación, y luego una variante de espacio previo dentro de un compassador identificador compuesto) que reportaban respuestas correctas como fallos — un recordatorio de que también tu propio harness de evaluación necesita depurarse.

Docker

docker build -t loglens:local .
docker run -d -p 3000:3000 \
  -e GROQ_API_KEY=your-key \
  -e GEMINI_API_KEY=your-key \
  loglens:local
curl http://localhost:3000/health

Multi-stage build (compilar con devDependencies, ejecutar con solo dependencias productivas + usuario no root + healthcheck de contenedor sobre /health). El contenedor ejecuta el transporte HTTP ( MCP_TRANSPORT=http, establecida por defecto en la imagen) en lugar de stdio, porque un contenedor ya desplegado no tiene proceso padre que lo esparaza de la forma en que hacen Claude Desktop/Code.

Bug real encontrado y corregido durante la puesta y verificación, que conviene conocer si ya se ha implementado un MCP HTTP servidor streamable stateless: el modo stateless del SDK requiere un transporte nuevo por solicitud; reutilizar el mismo transporte entre peticiones provoca de forma silenciosa un 500 en cada petición posterior a la primera, sin lanzar una excepción que permita detectarlo. Aparte, un servidor McpServer con una sola instancia solo puede estar conectado a un transporte a la vez ("Already connected to a transport"). La solución (ver createServer() y el handler HTTP en src/index.ts) crea tanto un McpServer nuevo como un StreamableHTTPServerTransport nuevo para cada solicitud — algo barato, porque el servidor solo guarda las definiciones de las herramientas, sin estado propio por conexión (ninguna de estas herramientas transporta estado entre llamadas de una de todas formas). Verificado contra un contenedor real en ejecución: con la corrección, search_logs y lo full completo de summarize_incident se completaron correctamente de extremo a extremo.

Variables de entorno

Configuración

npm install
npm run build

Por omisión el servidor lee fixtures/sample.log, un incidente sintético (una consulta sin índice de larga duración en inventory-service agota el pool de conexiones compartido de la DB y se derrama en fallos en checkout-service). Para usar un archivo de log real, cambia:

LOGLENS_LOG_FILE=/path/to/real.log node dist/index.js

Pruebas de humo (sin necesit un clic MCP)

npx tsx scripts/smoke-test.ts                              # stdio transport
npx tsx scripts/smoke-test-http.ts http://localhost:3000/mcp  # HTTP transport

Inicia (o conectate a) el servidor y pruébalo todas las tres herramientas — útil para verificar que funciona antes de preparar un cliente real. Una ejecución completa de summarize_incident requiere 3–4 llamadas secuenciales al LLM y puede tomar 30–90 seg ; si quieres hacerlo por programación, pasa un timeout generoso (ambos scripts lo hacen).

Conexión con Claude Desktop

Edita %APPDATA%\Claude\claude_desktop_config.json (Windows) y añade:

{
  "mcpServers": {
    "loglens": {
      "command": "node",
      "args": ["C:\\Users\\sarve\\OneDrive\\Desktop\\LogLens\\dist\\index.js"],
      "env": {
        "GROQ_API_KEY": "your-groq-key",
        "GEMINI_API_KEY": "your-gemini-key"
      }
    }
  }
}

El bloque env es obligatorio, no opcional — los clientes MCP inician el servidor con un entorno limpio por defecto, no con el entorno completo de tu shell, así que sin ese bloque las claves no serán visibles para summarize_incident, aunque estén configuradas en todo tu sistema.

Reinicia Claude Desktop y pide por ejemplo "busca en los logs 'pool exhausted'" — debería llamar a search_logs automáticamente.

Conexión con Claude Code

claude mcp add loglens --scope user --env GROQ_API_KEY=your-groq-key --env GEMINI_API_KEY=your-gemini-key -- node C:\Users\sarve\OneDrive\Desktop\LogLens\dist\index.js

(Misma razón que arriba: --env pasa las claves explícitamente porque el proceso hijo no hereda tu entorno shell de la forma habitual.)

Estructura del proyecto

src/
  index.ts       MCP server (dual transport: stdio + HTTP) + tool registration
  logParser.ts   log loading, search, time-window expansion, anomaly scan
  summarize.ts   the summarize_incident pipeline: extract -> retrieve -> hypothesize -> verify -> retry
  providers.ts   Groq + Gemini clients, model config, schema-constrained JSON generation
fixtures/
  sample.log     synthetic incident for local testing
evals/
  cases.ts       8 eval case definitions
  run-evals.ts   deterministic scoring harness
  logs/          synthetic logs for eval cases 02-08
scripts/
  smoke-test.ts       stdio transport smoke test
  smoke-test-http.ts  HTTP transport smoke test
Dockerfile       multi-stage build, non-root user, container healthcheck