@inso_web/els-mcp/docs/TOOLS.md

MCP-сервер поверх INSO Error Logs Service. Read-only tools (search, analytics, fingerprinting, correlations) для подключения Claude Desktop/Code и ChatGPT к логам ошибок. Streamable HTTP transport + stdio для npx-запуска.

# Tools Reference

🇷🇺 **Русская версия**: [`TOOLS.ru.md`](./TOOLS.ru.md)

Complete reference for the 18 read-only tools exposed by
`@inso_web/els-mcp`. For each tool you'll find purpose, common parameters
and example prompts you can give to your AI agent (Claude Code, Cursor,
Windsurf, ChatGPT etc.) to invoke it naturally.

All tools require an API key with the `errors:mcp-read` scope. `list_apps`
additionally requires a master key (with graceful fallback for non-master
keys).

## Table of contents

- [Search & details](#search--details)
  - [`search_logs`](#search_logs)
  - [`get_log_details`](#get_log_details)
  - [`query_logs_jql`](#query_logs_jql)
  - [`errors_in_session`](#errors_in_session)
- [Analytics & trends](#analytics--trends)
  - [`top_error_messages`](#top_error_messages)
  - [`error_histogram`](#error_histogram)
  - [`error_heatmap`](#error_heatmap)
  - [`traffic_stats`](#traffic_stats)
  - [`error_stats_breakdown`](#error_stats_breakdown)
- [Grouping & correlation](#grouping--correlation)
  - [`find_similar_errors`](#find_similar_errors)
  - [`find_correlated_errors`](#find_correlated_errors)
  - [`grouped_errors`](#grouped_errors)
- [Impact & regression](#impact--regression)
  - [`impact_analysis`](#impact_analysis)
  - [`baseline_compare`](#baseline_compare)
  - [`version_regression`](#version_regression)
- [Triage & AI](#triage--ai)
  - [`triage_recent_critical`](#triage_recent_critical)
  - [`explain_error`](#explain_error)
  - [`list_apps`](#list_apps)

---

## Search & details

### `search_logs`

**Purpose**: Faceted search across error logs with full filter support.
Returns hits, facets (level, browser, urlPath, etc.) and a histogram in
one call.

**Common params**: `appSlug`, `from`, `to`, `level`, `serviceName`,
`appVersion`, `urlPath`, `fingerprint`, `sessionId`, `search`,
`response_format`, `limit`, `cursor`.

**Example prompts**:

- "Show the last 20 critical errors in production for the past hour."
- "Find WARNING-level logs from `auth-service` where URL contains `/login`, last 24 hours."
- "List errors with appVersion `2.4.1` and serviceName `billing`."

---

### `get_log_details`

**Purpose**: Full details for a single log entry by `traceId` — stack
trace, headers, request context, AI diagnosis if available.

**Common params**: `appSlug`, `traceId`.

**Example prompts**:

- "Show full details for traceId `abc-123-def-456`."
- "Pull the complete stack trace and request context for trace `xyz789`."

---

### `query_logs_jql`

**Purpose**: Search logs via JQL (JIRA-like Query Language). Supports
`AND`, `OR`, `NOT`, comparison and `IN` operators on whitelisted fields.

**Common params**: `appSlug`, `jql`, `from`, `to`, `limit`, `cursor`,
`response_format`.

**Example prompts**:

- "Run JQL `level IN (ERROR, CRITICAL) AND serviceName = \"api-gateway\" AND NOT urlPath ~ \"/health\"` for last 6 hours."
- "Use JQL to find ERRORs where browser is Safari and appVersion ≥ `3.0.0`."
- "Show me an example JQL query that filters by fingerprint and lists only the matching messages."

---

### `errors_in_session`

**Purpose**: Reconstruct the full chronological list of errors that
happened inside a single user session — useful to understand cause &
effect during a user's flow.

**Common params**: `appSlug`, `sessionId`, `response_format`.

**Example prompts**:

- "What errors did session `sess_abc` hit? Show them in order."
- "Reconstruct the failure timeline for sessionId `01HX9Y…` — I need to
  understand what the user experienced."

---

## Analytics & trends

### `top_error_messages`

**Purpose**: Top-N error messages ranked by frequency (deduped by
normalised message).

**Common params**: `appSlug`, `from`, `to`, `limit`, `level`, `serviceName`.

**Example prompts**:

- "What were the top 10 error messages last week?"
- "Top 25 errors for `payment-service` over the last 24h, only ERROR and CRITICAL."

---

### `error_histogram`

**Purpose**: Time-series histogram of error counts with automatic bucket
selection (`5m` / `30m` / `1h` / `1d`) based on the requested window.

**Common params**: `appSlug`, `from`, `to`, `level`, `serviceName`,
`bucket` (auto by default).

**Example prompts**:

- "Plot the error rate for the last 7 days, hourly buckets."
- "Histogram of CRITICAL errors from `lk` over the past 30 minutes."

---

### `error_heatmap`

**Purpose**: Weekday × hour heatmap. Shows when errors typically happen.

**Common params**: `appSlug`, `from`, `to`, `level`.

**Example prompts**:

- "Heatmap of errors over the last 30 days — when are we most fragile?"
- "Show the day-of-week / hour heatmap for `payment-service`, ERROR level only, last 14 days."

---

### `traffic_stats`

**Purpose**: Request rate (RPM) and latency percentiles (p50, p95, p99)
per service.

**Common params**: `appSlug`, `from`, `to`, `serviceName`.

**Example prompts**:

- "Show RPM and latency p95/p99 for `api-gateway` over the past hour."
- "Compare traffic and latency for `billing` and `payment` services last 24h."

---

### `error_stats_breakdown`

**Purpose**: Statistical breakdown of errors across an arbitrary field
(browser, appVersion, deploymentEnv, etc.). Returns counts and shares.

**Common params**: `appSlug`, `from`, `to`, `dimension`, `level`.

**Example prompts**:

- "Break down errors by browser for last 7 days — what proportion is mobile?"
- "Distribution of errors by `appVersion` over the past 24h."
- "Stats per deploymentEnv for the last week."

---

## Grouping & correlation

### `find_similar_errors`

**Purpose**: Aggregates around a given error (by fingerprint):
`totalOccurrences`, counters for last hour / 24h / 7d, top URLs and IPs,
client/server split.

**Common params**: `appSlug`, `traceId`.

**Example prompts**:

- "How widespread is the error at traceId `abc-123`? Show me hour / 24h / 7d counts."
- "Find similar errors to `xyz789` — how many users hit it, on which URLs?"

---

### `find_correlated_errors`

**Purpose**: Errors that happened within ±N minutes around a given
traceId — for diagnosing cascading failures.

**Common params**: `appSlug`, `traceId`, `windowMinutes` (default 5).

**Example prompts**:

- "What else broke in the 5 minutes around traceId `abc-123`?"
- "Show errors correlated with `xyz789` within ±15 minutes — I think there's a cascade."

---

### `grouped_errors`

**Purpose**: Group errors by fingerprint — list of unique error
signatures with counts.

**Common params**: `appSlug`, `from`, `to`, `limit`, `level`,
`serviceName`.

**Example prompts**:

- "Group last 24h of errors by fingerprint — how many distinct issues do we have?"
- "Show the top 15 unique error fingerprints over the past week."

---

## Impact & regression

### `impact_analysis`

**Purpose**: Severity scoring of an error — how many users, sessions,
URLs are affected, with URL-weight factored in.

**Common params**: `appSlug`, `traceId` or `fingerprint`, `from`, `to`.

**Example prompts**:

- "How serious is the error at traceId `abc-123`? Compute impact."
- "Rank impact for the top 10 fingerprints last week — which ones should I fix first?"

---

### `baseline_compare`

**Purpose**: Compare the current time window with a baseline period.
Detects regressions (error count up, error rate up, latency up).

**Common params**: `appSlug`, `from`, `to`, `baselineFrom`, `baselineTo`.

**Example prompts**:

- "Compare today's errors with the same time yesterday — what's regressed?"
- "Baseline-compare last hour against the previous 24h average."

---

### `version_regression`

**Purpose**: Per-version timeline of error counts. Shows which release
introduced or fixed which issue.

**Common params**: `appSlug`, `from`, `to`, `serviceName`.

**Example prompts**:

- "Which errors started in `v2.4.1` of `lk` that weren't present in `v2.4.0`?"
- "Show version-by-version regression timeline for `payment-service` last 30 days."

---

## Triage & AI

### `triage_recent_critical`

**Purpose**: Composite tool for fast triage of CRITICAL errors over the
last N minutes. Combines `search_logs` + `find_similar_errors` +
`impact_analysis` into a single ranked summary.

**Common params**: `appSlug`, `minutesBack` (default 30).

**Example prompts**:

- "Triage the last 30 minutes of CRITICAL errors — prioritised list, please."
- "What's on fire in `lk` right now? Show top critical issues with impact."

---

### `explain_error`

**Purpose**: Returns the error's context (stack, headers, similar
counts, correlated traces) so the LLM can synthesise a root-cause
explanation. AI summary planned for next releases — currently the
client LLM does the synthesis.

**Common params**: `appSlug`, `traceId`.

**Example prompts**:

- "Explain the error at traceId `abc-123` — what likely caused it?"
- "Walk me through the failure at `xyz789` and suggest a fix."

---

### `list_apps`

**Purpose**: List of apps (tenants) the current API key has access to.
Master keys see all apps; regular keys get `[{ slug: '(current-app)' }]`
as a graceful fallback.

**Common params**: none.

**Example prompts**:

- "Which apps can I query?"
- "List all available appSlugs for my key."