@dici1435/observability-mcp

Observability MCP server for dici-spec projects. Queries Grafana Tempo for distributed traces and Grafana Loki for application logs. Enables closed-loop debugging: test → trace → diagnose → fix → retest.

Installation

npm install -g @dici1435/observability-mcp
# or run directly
npx @dici1435/observability-mcp

Added to a project via dici-spec add observability, which also sets up Docker Compose and OTel configuration.

Tools

Core Query Tools

| Tool | Description | |---|---| | get_trace | Fetch a full distributed trace timeline by trace ID. Returns spans with services, durations, statuses, attributes. | | get_logs | Search application logs via LogQL. Filter by service, level, trace ID, correlation ID, or free-text regex. | | search_traces | Search traces by service, status code, or minimum duration. Returns matching trace summaries. | | check_services | Health-check Tempo and Loki backends. Reports availability, latency, connection errors. | | get_error_info | Look up detailed info about a specific error code from error-level logs. | | get_error_rate | Get error rate metrics over a time window, bucketed by configurable interval. |

Advanced Tools

| Tool | Description | |---|---| | run_tests | Execute a test command, capture trace IDs from output, return pass/fail + trace IDs for investigation | | analyze_request | Fetch trace + correlated logs for a request, produce structured diagnosis with timeline, errors, and root cause hints | | compare_traces | Diff two traces: align spans by operation/service, show duration and status changes | | get_frontend_errors | Query browser/frontend error logs from Loki, filterable by page URL, browser, time window |

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | TEMPO_URL | No | http://localhost:3200 | Grafana Tempo endpoint | | LOKI_URL | No | http://localhost:3100 | Grafana Loki endpoint | | LOKI_CORRELATION_ID_ATTR | No | correlationId | Log attribute name for correlation IDs | | PROJECT_ROOT | No | process.cwd() | Working directory for run_tests |

Closed-Loop Debugging Flow

run_tests → (captures trace IDs) → get_trace → analyze_request → fix → run_tests

The run_tests tool executes tests, parses stdout for traceId=... patterns, and returns the trace IDs. Agents can then call get_trace and analyze_request to diagnose failures, fix the code, and re-run.

Prerequisites

Requires Grafana Tempo and Grafana Loki running as backends. The dici-spec add observability command sets up a Docker Compose stack with these services pre-configured.

Transport

Stdio (stdin/stdout). Designed to be launched by AI agent IDEs as a child process.

License

MIT