@inso_web/els-mcp
Version:
MCP-сервер поверх INSO Error Logs Service. Read-only tools (search, analytics, fingerprinting, correlations) для подключения Claude Desktop/Code и ChatGPT к логам ошибок. Streamable HTTP transport + stdio для npx-запуска.
196 lines (143 loc) • 8.36 kB
Markdown
# @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