# @inso_web/els-mcp

🇬🇧 **English documentation**: [`../README.md`](../README.md)

MCP-коннектор к INSO Event Logs Service. Подключает Claude Desktop, Cursor,
Windsurf, ChatGPT и любого другого AI-агента к логам ошибок вашего
приложения — для поиска, анализа, корреляций и быстрого триажа.

Сервис облачный, развёрнут на стороне INSO. Этот пакет нужен только тем
клиентам, которым удобно подключаться через stdio. Если ваш клиент умеет
Streamable HTTP — пакет ставить вообще не нужно, см. ниже.

- Сайт сервиса: <https://mcp.insoweb.ru/els/>
- Личный кабинет (ключи доступа): <https://lk.insoweb.ru>

## Быстрый старт

### Шаг 1. Получите ключ доступа

Зайдите в [личный кабинет](https://lk.insoweb.ru), создайте API-ключ с
правом `errors:mcp-read`. Ключ имеет вид `els_live_xxxxxxxxxxxxxxxx`.

### Шаг 2. Подключите коннектор

#### Вариант A — облачный endpoint (рекомендуем)

Подходит для большинства современных MCP-клиентов: Cursor, Windsurf, Zed,
Claude Code, ChatGPT Custom Connectors, Claude Desktop ≥ 0.9.

В настройках клиента укажите:

```json
{
  "mcpServers": {
    "els": {
      "url": "https://mcp.insoweb.ru/els/mcp",
      "headers": {
        "Authorization": "Bearer els_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Перезапустите клиент — в списке инструментов появятся ELS-tools. Никакой
установки на машину не требуется.

#### Вариант B — через `npx` (для клиентов без HTTP)

Если ваш клиент пока поддерживает только stdio (старые версии Claude
Desktop, некоторые корпоративные сборки):

```json
{
  "mcpServers": {
    "els": {
      "command": "npx",
      "args": ["-y", "@inso_web/els-mcp"],
      "env": {
        "ELS_API_KEY": "els_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

`npx` сам подкачает пакет при первом запуске. Никаких глобальных
установок.

### Шаг 3. Проверьте подключение

В диалоге с агентом попросите: «покажи последние 10 ошибок за час». Если
ELS-tools появились — он сходит в облако и вернёт ответ.

## Какие инструменты доступны

18 read-only инструментов охватывают поиск, аналитику, fingerprinting,
корреляции, regression detection и AI-триаж. Никаких записей или
модификации данных через MCP не делается.

Краткая разбивка по группам:

- **Поиск и детали**: `search_logs`, `get_log_details`, `query_logs_jql`,
  `errors_in_session`
- **Аналитика и тренды**: `top_error_messages`, `error_histogram`,
  `error_heatmap`, `traffic_stats`, `error_stats_breakdown`
- **Группировка и корреляции**: `find_similar_errors`,
  `find_correlated_errors`, `grouped_errors`
- **Influence и регрессии**: `impact_analysis`, `baseline_compare`,
  `version_regression`
- **Триаж и AI**: `triage_recent_critical`, `explain_error`, `list_apps`

Полный справочник с описанием параметров и **примерами промптов для
LLM-агентов** — [`TOOLS.ru.md`](./TOOLS.ru.md).

## Контекст проекта (опционально)

Чтобы агент сам понимал, к какому приложению относятся запросы, положите в
корень репозитория файл `els.config.json`:

```json
{
  "$schema": "https://mcp.insoweb.ru/els/schema/els.config.schema.json",
  "appSlug": "my-app",
  "environments": {
    "dev": "DEV",
    "production": "PRODUCTION"
  },
  "defaultEnvironment": "production",
  "alerts": {
    "criticalRateThreshold": 5
  }
}
```

После этого агент:

- автоматически подставляет `appSlug` во все инструменты,
- знает какие у вас окружения,
- может проактивно выполнять стандартные workflow: проверить DEV-логи
  после фичи, снять baseline перед деплоем, сравнить с baseline после.

Альтернативно: секция `inso.els` прямо в `package.json` — формат тот же.

## Форматы ответов и пагинация

Все listing-инструменты поддерживают параметр `response_format`:

- `compact` (по умолчанию) — без `stack`, `componentStack`, `userAgent`,
  `message` ограничено 200 символов. Экономит токены LLM.
- `full` — все поля.
- `summary` — только `traceId`, `message`, `level`, `lastSeen`.

Постраничный обход — через `cursor` (НЕ `page`/`offset`). Курсор opaque,
содержит хэш текущих фильтров; если между страницами поменять фильтр,
сервер вернёт `INVALID_ARGS` и предложит начать заново.

## Безопасность данных

Все ответы проходят через PII-маскирование до передачи в LLM:

- IPv4 — последний октет обнуляется (`192.168.1.42` → `192.168.1.0`)
- IPv6 — оставляется только `/64`-префикс
- Email, телефоны, номера карт (с проверкой Luhn), JWT и Bearer-токены
  заменяются на `[…_REDACTED]`
- Из URL и referer вырезается query-string
- User-Agent сводится к семейству браузера

Пользовательский ввод из логов (`message`, `stack`) оборачивается в теги
`<untrusted>…</untrusted>` для защиты от prompt-injection.

## Лимиты по тарифам

| Тариф | Запросов в день | Параллельных SSE | AI-explain в день |
|---|---|---|---|
| Free | 1 000 | 2 | 20 |
| Standard | 50 000 | 20 | 500 |
| Premium | 500 000 | 100 | 5 000 |
| Unlimited | ∞ | 500 | ∞ |

При превышении приходит `TIER_QUOTA_EXCEEDED` с `retryAfter` до полуночи
UTC. До 110 % лимита работает grace-zone (`_meta.overage = true`).

## Коды ошибок

`RATE_LIMITED`, `UPSTREAM_UNAVAILABLE`, `INVALID_ARGS`, `NOT_FOUND`,
`INSUFFICIENT_SCOPE`, `QUOTA_EXCEEDED`, `INTERNAL`.

## Переменные окружения

Минимально необходимая — только `ELS_API_KEY`. Остальные имеют разумные
значения по умолчанию.

| ENV | Default | Описание |
|---|---|---|
| `ELS_API_KEY` | — | Ключ доступа (`els_live_*` или `els_test_*`) |
| `ELS_BASE_URL` | `https://api.insoweb.ru/els` | Endpoint ELS API |
| `MCP_LOG_LEVEL` | `info` | Уровень логирования (pino) |
| `MCP_DISABLE_TOOLS` | — | CSV с именами инструментов, которые нужно отключить |
| `MCP_UPSTREAM_TIMEOUT_MS` | `30000` | Таймаут одного запроса в ELS |

## Поддержка

- Документация и обновления: <https://mcp.insoweb.ru/els/>
- Личный кабинет, ключи, тарифы: <https://lk.insoweb.ru>
- Контакт команды: <https://insoweb.ru>

## Разработка пакета

Документация для контрибьюторов и сценарии локального запуска —
в [`CONTRIBUTING.ru.md`](./CONTRIBUTING.ru.md).

## Лицензия

MIT