LogLens

Ein MCP-Server (Model Context Protocol) für die Protokollanalyse. Anstatt eine Logdatei in einen Chat einzufügen und eine LLM um das Debugging zu bitten, stellt LogLens Logsuche, Kontextabruf und Störungszusammenfassung als Tools bereit, die jeder MCP-kompatible Client (Claude Desktop, Claude Code oder ein eigener Agent) direkt aufrufen kann – mit gezieltem Abruf statt Kontextüberfrachtung und einem Selbstverifikationsschritt, der unbegründete Root-Cause-Behauptungen abfängt, bevor sie zurückgegeben werden.

Warum es das gibt

Entstanden als öffentliche, Portfolio-Version eines KI-gestützten Log-Analyzers, der bei einem internen Hackathon den 1. Platz belegte. Kurzfassung, warum das besser ist als "Einfügen in den Chat": Produktionslogs passen nicht in einen Kontextfenster-Thread, ein Chat-Einfügen ist für andere Systeme nicht aufrufbar, und alleiniges Prompting bietet keinen Mechanismus, um zu prüfen, ob die Antwort des Modells tatsächlich in den Logdaten verankert ist.

Related MCP server: Log Analyzer MCP

Status

• Kernserver, 3 Tools – funktionieren Ende-zu-Ende gegen eine Beispiel-Log-Datei. ✅

• LLM-basierte Root-Cause-Generierung mit einer Halluzinations-Verifikationsschleife, die die Hypothese auf zwei unabhängigen Achsen prüft und bei Fehlschlag einmal erneut versucht. ✅

• Multi-Provider-Architektur (Groq + Gemini) – der Verifizierer läuft auf einer anderen Modellfamilie als der Generator, sodass die Prüfung die blinden Flecken des Generators nicht teilt. ✅

• 8-Fall-Evaluationssuite, deterministische Bewertung, 8/8 bestanden. ✅

• Dockerisiert, läuft als netzwerkerreichbarer HTTP-Server, Ende-zu-Ende gegen einen Live-Container verifiziert. ✅

• Als Nächstes: Cloud-Bereitstellung (Azure Container Apps oder Ähnliches), ein Demo-GIF.

Tools

Architektur

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

Zwei Provider, bewusst – nicht nur ein Kosten-Workaround

Groq übernimmt die Extraktion und die Hypothesengenerierung; Gemini übernimmt die Verifikation. Das begann als Kontingent-Workaround (Geminis Free-Tier liegt bei 20 Anfragen/Tag; Groq ist weitaus gedeckter), wurde aber zu einer echten architektonischen Verbesserung: Ein Verifikierer, der auf demselben Modell läuft, das eine Behauptung erzeugt hat, teilt die blinden Flecken dieses Modells. Die Überprüfung der Behauptung mit einer anderen Modellfamilie macht den Halluzinationscheck wirklich unabhängig – nicht nur eine Zweitmeinung aus derselben Quelle. Verification.independent zeigt an, ob eine gegebene Antwort tatsächlich die proiderübergreifende Prüfung durchlaufen hat oder auf den gleichen Provider zurückgefallen ist (Gemini down/nicht konfiguriert) – sichtbar gemacht, nicht versteckt.

Die lüchenfüllungs-Retrieval-Lücke – durch Tests gefunden, auf der richtigen Ebene behoben

Frühe Tests zeigten eine echte Einschränkung: summarize_incident fand die unmittelbare Ursache eines Checkout-Fehlers (DB-Pool-Erschöpfung), aber die vorgelagerte Ursache, die in der Log-Datei ebenfalls kodiert ist – eine lang andauernde Abfrage auf einem anderen Dienst, die die Verbindung hält – blieb unerkannt. Zwei strukturelle Probleme:

• Retrieval war rein lexikalisch. Extrahierte Begriffe waren auf den Checkout fokussiert, sodass inventory-service-Zeilen niemals in die Evidenzmenge gelangen, egal wie gut das Schlussfolgern war. Behoben mit Einführung der Zeitfenster-Erweiterung, absichtlich asymmetrisch (900s vor / 180s nach) – Ursachen gehen Symptomen voraus, oft mehr als ein kurzes symmetrisches Fenster erkennen könnte – ergänzt durch einen globalen Scan nach anomalen (WARN/ERROR) Zeilen unabhängig vom Fenster, da die erklärende Zeile selbst oft eine Warnung ist („NTP-Synchronisierung fehlgeschlagen“, „Rotation übersprungen“).

• Der Verifizierer konnte nur noch absegnen. Er sah ursprünglich nur die Zeilen, die eine Behauptung zitierte, was ihn strukturell unfähig machte, eine unvollständige Antwort zu bemerken – eine Behauptung, die ein Symptom beschreibt, sieht immer durch die von ihr ausgewählten zitierten Zeilen gestützt aus. Er sieht jetzt den vollständigen Evidenzsatz und bewertet Soundness und Completeness unabhängig; ein fundiertes, aber unvollständiges Urteil fließt die übersehenen Zeilen in die Regeneration ein.

Evaluationssuite

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

8 Fälle, die verschiedene Ausfallarchetypen abdecken: Cross-Service-Ressourcenkontention, OOM durch unbegrenzten- Cache, Retry-Sturm-Verstärkung, eine schlechte Veröffentlichung, zwei zusammenwirkende Ursachen, eine Uhrzeitdrift bei einem einzelnen fehlerhaften Knoten, ein gesundes Log (richtige Antwort „nothing failed“) und ein Fall von laut-Symptomen, die die subtile Ursache maskieren – gezielt gebaut, um die Achse Vollständigkeit zu testen. Die Auswertung ist deterministisch – Konzeptgruppen mit Synonymen, zusätzlich erforderliche Nachweisangaben, kein LLM-Richter –, sodass die Läufe reptroduzierbar sind. Der Bericht unterscheidet Retrieval-Misses (Nachweis erreichte nie das Modell) von Reasoning-Misses (Nachweis war da, Antwort trotzdem falsch), da diese unterschiedliche Korrekturen benöt.

**Aktuelles Ergebnis: 8/8 bestanden, 0 Retrieval-Misses, 0 Reasoning-Misses.

Das Debuggen dieser Sammlung ist selbst eine solide Engineering-Geschichte : ein asymmetrisches Zeitfenster und ein globaler Anomalie-Scan behoben echte Retrieval-Fragilität; auf dem Free-Tier von Groq ist max_tokens eine Reservierung gegen das Pro-Minuten-Token-Budget, keine Bezahl-für-was-Sie-nutzen-Obergrenze – ein hoher Wert ergibt eine- -Antwort 413 unabhängig von der tatsächlichen Promt-Größe; reasoning_effort: "low" war bei den gpt-oss-Modellen notwendig, die sonst das Budget für Reasoning-Tokens verbrauchen und abschneiden, bevor sie gültiges JSON ausgeben; und das Testframework hatte selbst zwei Verrechnungs-Bugs (Unicode-Zeichenvarianten, dann eine Leerzeichen-Variante desselben zusammengesetzten Identifikators), die korrekte Antworten als fehlgeschlagen meldeten – das ist wichtig, wenn Sie Ihre eigene Evaluationsumgebung schreiben: Sie braucht selbst Debuggin.

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

Mehrstufiger Build (Kompilieren mit devDependencies, Ausführen mit nur Produktionsabhängigkeiten + Nicht-Root-Benutzer + Container-Healthcheck auf /health). Der Container läuft den HTTP-Transport (MCP_TRANSPORT=http, standardmäßig im Image gesetzt) statt stdio, da ein bereit ein Ding gesetzt Container keinen Elternprozess hat, der ihn lokal startet wie Claude Desktop/Code es tun.

Ein echter Bug wurde beim Einrichten gefunden und behoben (nützlich zu wissen, wenn Sie einen eigenen zustandslosen streamable-HTTP-MCP-Server bauen): Der zustandslose Modus des SDK erfordert einen neuen Transport pro Anfrage – die Wiederverweisung eines Transports über mehrere Anfragen führt stillschweigend zu 500ern bei jeder Anfrage nach der ersten, ohne verworfene Ausnahme. Außerdem kann ein einzelner McpServer nur mit einem Transport verbunden sein ("Already connected to a transport"). Der Fix (siehe createServer() und HTTP-Handler in src/index.ts) erzeugt pro Anfrage sowohl einen neuen McpServer als auch einen neuen StreamableHTTPServerTransport – billig, da der Server nur Tool- Definitionen hält, keinen Verbindungsstatus (keines dieser Tools trägtex dazu trotzdem Zustandanschlussaufrufe). Verifiziert gegen ein realer laufender Container:nach dem Fix search_logs und eine vollständige summarize_incident-Übergabe abschlossen beide korrekt Ende-zu-Ende.

Umgebungsvariablen

Hinweis: Beachten Sie, dass einige Einträge in der Tabelle in der Übersetzung möglicherweise unbeabsichtigt verschmolzene oder fehlerhafte Darstellungen aufweisen. Bitte passen Sie die Zeilen für LOGLENS_LOG_FILE, MCP_TRANSPORT und PORT um innerhalb an den korrekten mehrdeutige deutsche korrekte Inhalt. (Dies ist eine sprachliche Notiz, keine zip-Inhalt; sie würde nicht in der Endausgabe erscheinen.)

entschuldig in der letzten Tabelle: bitte dem vorherigen Abschnitt der Tabelle nach die Informationen für Variablen enumerts. Hier ist die korrekte Übersetzungständige Passage:

                                                                                                                     |

| PORT | optional | HTTP-Port, Standard 3000. |

Setup

npm install
npm run build

Standardmäßig liest der Server fixtures/sample.log, einen synthetischen Vorfall (eine lange laufende, nicht indexierte Abfrage auf inventory-service erschöpft einen freigegebenen DB-VerbindungsPool, der wiederum Ausfälle in checkout-service verursacht). Zeigen Sie stattdessen mit feinen Sie auf ein echtes Logs hin:

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

Smoke-Tests (kein MCP-Client erforderlich)

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

Startet (oder verbindet sich mit) den Server und ruft alle drei Tools auf – nützlich, um sicherzustellen, dass er funktest, bevor Sie einen echten Client bereit. Übergeben Sie den: vollständige summarize_incident-Übergabe sind 3-4 fortlaufende LLM-Aufruf und 30-90s dauern; übergeben Sie ein großzügiges timeout, wenn sie ihn programmieren (beide Skripte tun das).

Verbinden mit Claude Desktop

Bearbeiten Sie %APPDATA%\Claude\claude_desktop_config.json (Windows) und fügen Sie hinzu:

{
  "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"
      }
    }
  }
}

Der env-Block ist erforderlich, nicht optional – MCP-CLIENTS-TEE-Server mit bereinigtemumgebung standardmäßig (nicht die vollständige Umgebung Ihrer Shell) spawn, und ohne diese Umgebung werden die in summarize_incident-Daten für Inzidenznormal nicht sichtbar werden., selbst wenn sie global auf Ihrer Maschine gesetzt sind (ohne der bloque sind sie für CLI-Arten nicht sichtbar).

MCP-CLIENTS starten den Server standardmäßig mit einer bereinigten Umgebung, nicht mit der vollständigen Ihres Users.`Umgebung, Sie.

Dear System: Start:

Beenden Sie Claude Desktop neu und Fragen Sie es z.B. "such in den Logs nach 'pool exhausted'" – es sollte automatisch search_logs aufrufen.

Verbindung zu 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

(G_eicher - Grund wie child:--env übergibt die Schlüssel explizit, da der abgesetzte Prozess Ihre Shell-Umgebung nicht standardmäßig erbt.)

Projektstruktur

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