Skip to main content
Glama
ndjson-local-log-triage-mcp

ndjson-local-log-triage-mcp

by vola-trebla

🪵 ndjson-local-log-triage-mcp

npm CI License: MIT

Your service just crashed. The log file is 2GB. Your AI agent can't help.

MCP server that stream-parses NDJSON log files without loading them into memory — filter by pattern, detect error spikes via Z-score analysis, summarize severity timelines by time window.


🤔 The problem

A service crashes at 3am. The log file is app.log.ndjson and it's 2GB. You ask your agent to find what caused the spike in errors around 03:17. The agent can't read 2GB. It can't even try.

ndjson-local-log-triage-mcp streams the file line by line — never loading it into memory — and gives the agent exactly the slice it needs.


Related MCP server: Log Analyzer MCP Server

🛠️ Tools

query_log_pattern

Filter log entries by a field/value match. Returns up to N matching entries, streaming the file without loading it entirely. Pass lineStartPattern (e.g. "^{") to reconstruct multiline stack traces silently dropped by the default parser.

Log Query Results
  File:        /var/log/app.log.ndjson
  Filter:      service contains "auth"
  Lines read:  847,293
  Matches:     50 (limit 50 reached)

{"timestamp":"2025-01-15T03:17:02Z","level":"error","service":"auth","msg":"token validation failed","userId":"u_abc123"}
...

detect_error_anomalies

Z-score frequency analysis. Buckets errors by time window, computes mean + stddev, flags windows where the error rate is anomalously high.

Error Anomaly Detection
  File:            /var/log/app.log.ndjson
  Window:          5min
  Z-score cutoff:  2.0
  Baseline:        mean=3.2 errors/window, stdDev=1.8
  Anomalies found: 2

  [z=4.71] 2025-01-15T03:15:00.000Z  23 errors
  [z=2.33] 2025-01-15T03:20:00.000Z  9 errors

summarize_log_timeline

Chronological aggregation of errors, warnings, and info counts per time window. Quick visual of where the incident is.

Pass adaptive: true to auto-scale bucket size to actual event density and zoom in on the peak error window at 10× finer resolution.

Log Timeline Summary
  File:        /var/log/app.log.ndjson
  Window:      5min
  Buckets:     48

  Time (UTC)                 Errors  Warnings  Info  Other
  ─────────────────────────────────────────────────────────
    2025-01-15 03:00:00Z          2         8   142      0
    2025-01-15 03:05:00Z          1         5   138      0
    2025-01-15 03:10:00Z          3         9   141      0
  ! 2025-01-15 03:15:00Z         23        14   119      0
    2025-01-15 03:20:00Z          9        11   133      0

correlate_request

Reconstructs a distributed trace from multiple NDJSON log files. Given a trace_id, collects all correlated events in chronological order across all files and surfaces the services involved and total duration.

Request Correlation
  Trace ID:          trace-8f7a9b2c
  Files scanned:     2
  Events found:      10
  Services involved: api, worker
  Duration:          890ms

[2025-01-15T14:00:00.001Z] api           {"level":"info","msg":"incoming request",...}
[2025-01-15T14:00:00.045Z] api           {"level":"info","msg":"auth token validated",...}
[2025-01-15T14:00:00.112Z] worker        {"level":"info","msg":"job queued",...}
...

discover_log_schema

Analyze a log file to infer its wrapper format (NDJSON, Syslog, Kubernetes container logs) and extract type schemas, identifying polymorphic keys, timestamp patterns, and severity fields.

{
  "fileFormat": "NDJSON",
  "detectedKeys": {
    "timestamp": { "type": "string", "format": "date-time", "isChronologicalIndex": true },
    "level": { "type": "string", "isSeverityField": true, "possibleValues": ["info", "error"] }
  }
}

group_semantic_patterns

Cluster log messages dynamically using the fixed-depth tree-based Drain parsing algorithm to isolate distinct log templates and analyze their parameter distributions (wildcard variations).

Processed Logs: 1500
Unique Patterns: 2

- Template: "connection failed from * port *"
  Occurrences: 1200
  Parameters:
    - param_0 (client_ip): 192.168.1.1 (80%), 10.0.0.5 (20%)

start_live_triage

Start background log tailing with real-time Z-score anomaly alerting on error frequency spikes and heap memory protection limits. Dispatches notifications directly over standard JSON-RPC channels.

{
  "method": "notifications/triage",
  "params": {
    "type": "anomaly",
    "message": "Live Anomaly Detected: 45 errors in current window (Z-score: 3.52)",
    "z_score": 3.52,
    "error_count": 45
  }
}

query_external_logs

A unified gateway to query central log providers (Datadog, Splunk, Elasticsearch), converting search patterns to vendor-specific dialects and mapping the output into the standardized OpenTelemetry Log Data Model structure.


⚡ Setup

{
  "mcpServers": {
    "log-triage": {
      "command": "npx",
      "args": ["-y", "ndjson-local-log-triage-mcp"]
    }
  }
}

🚀 Usage

"Analyze /var/log/app.log.ndjson — summarize the error timeline in 5-minute windows, detect any anomalous spikes, and show me the error entries around the spike."

Works great alongside:


License

MIT

Available Tools

8 tools
correlate_requestA

Reconstruct a distributed trace by collecting all log events matching a trace/request ID across multiple NDJSON files, sorted chronologically.

Inputs: traceId (required), logFiles (required), idField, serviceField, +2 more.

detect_error_anomaliesB

Z-score frequency analysis to find sudden error spikes by time window.

Inputs: logFile (required), levelField, errorValues, windowMinutes, +3 more.

discover_log_schemaB

Analyze a log file to infer format and type schemas, including key type polymorphism and regex patterns for timestamps.

Inputs: file_path (required), sample_size.

group_semantic_patternsA

Cluster similar log messages using Drain algorithm to isolate core events and parameter distributions.

Inputs: file_path (required), depth, time_window_start, similarity_threshold.

query_external_logsA

Query external log providers (Datadog, Splunk, Elasticsearch) translating search patterns and mapping to OpenTelemetry format.

Inputs: query (required), provider (required), limit, start_time.

query_log_patternA

Filter NDJSON log file by field/value pattern, return top N matching entries.

Inputs: field (required), value (required), logFile (required), limit, +1 more.

start_live_triageA

Start background log tailing with real-time Z-score anomaly alerting and heap memory safety limits.

Inputs: file_path (required), high_water_mark, anomaly_threshold_z.

summarize_log_timelineA

Chronological severity aggregation — errors, warnings, and info counts per time window.

Inputs: logFile (required), adaptive, levelField, windowMinutes, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 8 tools

    Disambiguation4/5

    Tools target distinct operations: schema exploration, pattern querying, anomaly detection, timeline summary, request correlation, semantic clustering, live monitoring, and external integration. Some minor overlap exists between static anomaly detection and live triage, but descriptions clarify the static vs. real-time contexts.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, with clear action verbs (discover, query, detect, summarize, correlate, group, start). Even the two query tools are distinguished by their target (local pattern vs. external providers).

    Tool Count5/5

    8 tools is well within the optimal range for a log triage server, covering analysis, querying, aggregation, correlation, clustering, live monitoring, and external access without being excessive or sparse.

    Completeness4/5

    The tool set covers the core triage lifecycle: schema discovery, querying, anomaly detection, timeline summary, trace correlation, semantic grouping, live monitoring, and external log retrieval. Notable gaps include the absence of a stop/control tool for live triage and a dedicated raw context retrieval by log ID, but these are minor and workable.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers