# graylog-mcp

> 🔍 Model Context Protocol (MCP) сервер для интеграции Graylog с AI-ассистентами

Минималистичный MCP сервер, предоставляющий инструменты для поиска логов в Graylog через stdio протокол. Работает с Cursor, Claude Desktop и другими MCP-клиентами.

## ✨ Особенности

- 🚀 Три мощных инструмента для поиска логов
- 🔒 Поддержка Personal Access Token (PAT) аутентификации
- 🌐 Работа с self-signed TLS сертификатами
- 📦 Простая установка через npm/npx
- 🎯 Автоматическая нормализация полей логов
- 🔍 Умный поиск по UUID/trace ID/request ID

## 📋 Требования

- Node.js >= 18
- Graylog сервер с настроенным Personal Access Token

## 📦 Установка

### Глобальная установка
```bash
npm i -g @alexbuzo/graylog-mcp
```

### Использование через npx (рекомендуется)
Не требует установки - см. раздел "Настройка в Cursor"

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

### Запуск вручную

```bash
graylog-mcp \
  --graylog-url https://graylog.example.com \
  --token YOUR_GRAYLOG_PAT \
  --ssl-verify=false
```

### Параметры командной строки

| Параметр | Обязательный | Описание | По умолчанию |
|----------|--------------|----------|--------------|
| `--graylog-url` | ✅ | URL вашего Graylog сервера | - |
| `--token` | ✅ | Personal Access Token | - |
| `--ssl-verify` | ❌ | Проверка SSL сертификата | `true` |
| `--debug` | ❌ | Режим отладки | `false` |

## 🔌 Настройка в Cursor

**Настройки → MCP Servers → Add custom server**

### Вариант 1: Через npx (рекомендуется)

```json
{
  "mcpServers": {
    "graylog": {
      "command": "npx",
      "args": [
        "-y",
        "@alexbuzo/graylog-mcp@latest",
        "--graylog-url", "https://graylog.example.com",
        "--token", "YOUR_GRAYLOG_PAT",
        "--ssl-verify", "false"
      ],
      "name": "Graylog Search"
    }
  }
}
```

### Вариант 2: С переменными окружения (безопаснее)

```json
{
  "mcpServers": {
    "graylog": {
      "command": "bash",
      "args": [
        "-lc",
        "npx -y @alexbuzo/graylog-mcp@latest --graylog-url \"$GRAYLOG_URL\" --token \"$GRAYLOG_TOKEN\" --ssl-verify=false"
      ],
      "env": {
        "GRAYLOG_URL": "https://graylog.example.com",
        "GRAYLOG_TOKEN": "YOUR_GRAYLOG_PAT"
      },
      "name": "Graylog (secure)"
    }
  }
}
```

### Вариант 3: Глобальная установка

```json
{
  "mcpServers": {
    "graylog": {
      "command": "graylog-mcp",
      "args": [
        "--graylog-url", "https://graylog.example.com",
        "--token", "YOUR_GRAYLOG_PAT",
        "--ssl-verify", "false"
      ],
      "name": "Graylog"
    }
  }
}
```

## 🛠 Доступные инструменты

### 1. `graylog.search_logs`
Поиск логов с использованием Lucene/GELF запросов.

**Параметры:**
- `query` (string, обязательный): Lucene/GELF запрос
- `rangeSec` (number, по умолчанию 3600): Временной диапазон в секундах
- `limit` (number, опционально): Максимальное количество результатов (макс. 500)
- `offset` (number, опционально): Смещение для пагинации
- `filter` (string, опционально): Дополнительный фильтр (например, `stream:<STREAM_ID>`)

**Пример запроса:**
```typescript
{
  query: "level:ERROR AND service:api",
  rangeSec: 3600,
  limit: 100,
  filter: "stream:507f1f77bcf86cd799439011"
}
```

### 2. `graylog.search_uuid`
Умный поиск по UUID, request ID, trace ID и другим идентификаторам. Автоматически проверяет множество распространенных полей.

**Параметры:**
- `uuid` (string, обязательный): UUID или идентификатор для поиска
- `rangeSec` (number, по умолчанию 86400): Временной диапазон в секундах (24 часа)
- `limit` (number, опционально): Максимальное количество результатов (макс. 500)

**Автоматически ищет в полях:**
- `request_id`, `requestId`, `req_id`
- `trace_id`, `traceId`, `trace.id`
- `span_id`, `spanId`, `span.id`
- `transaction_id`, `transactionId`
- `correlation_id`, `correlationId`
- `_id`

**Пример запроса:**
```typescript
{
  uuid: "550e8400-e29b-41d4-a716-446655440000",
  rangeSec: 86400,
  limit: 200
}
```

### 3. `graylog.search_stream`
Получение сообщений из конкретного потока (stream).

**Параметры:**
- `streamId` (string, обязательный): ID потока в Graylog
- `rangeSec` (number, по умолчанию 3600): Временной диапазон в секундах
- `limit` (number, опционально): Максимальное количество результатов (макс. 500)

**Пример запроса:**
```typescript
{
  streamId: "507f1f77bcf86cd799439011",
  rangeSec: 7200,
  limit: 150
}
```

## 📊 Формат ответа

Все инструменты возвращают нормализованный JSON со следующей структурой:

```json
{
  "total": 42,
  "messages": [
    {
      "id": "message_id",
      "ts": "2024-01-15T10:30:00.000Z",
      "level": "ERROR",
      "source": "api-server-01",
      "container": "api-service",
      "message": "Database connection failed",
      "short_message": "DB error",
      "http_method": "POST",
      "url": "/api/users",
      "status": 500,
      "latency_ms": 1234,
      "trace_id": "abc123",
      "span_id": "def456",
      "request_id": "req-789",
      "tenant_id": "tenant-001",
      "client_ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "service": "user-api",
      "request": {...},
      "response": {...}
    }
  ]
}
```

### Автоматическая нормализация полей

Сервер автоматически извлекает и нормализует следующие поля из различных форматов:

| Поле | Альтернативные имена |
|------|---------------------|
| `container` | `container_name`, `kubernetes.container_name` |
| `http_method` | `method`, `http_method`, `request_method` |
| `url` | `path`, `request_path` |
| `status` | `http_status`, `response_status` |
| `latency_ms` | `duration_ms`, `response_time_ms` |
| `trace_id` | `traceId`, `trace.id` |
| `span_id` | `spanId`, `span.id` |
| `request_id` | `req_id`, `requestId` |
| `client_ip` | `remote_addr`, `ip` |
| `service` | `service_name`, `app` |

## 💻 Локальная разработка

### Установка зависимостей
```bash
npm install
```

### Сборка проекта
```bash
npm run build
```

### Запуск в режиме разработки
```bash
npm run dev -- --graylog-url https://graylog.example.com --token YOUR_PAT --ssl-verify=false
```

### Тестирование собранной версии
```bash
node dist/cli.js --graylog-url https://graylog.example.com --token YOUR_PAT --ssl-verify=false --debug
```

## 🔧 Структура проекта

```
graylog-mcp/
├── src/
│   ├── cli.ts        # CLI интерфейс и точка входа
│   ├── server.ts     # MCP сервер и регистрация инструментов
│   └── graylog.ts    # API клиент для Graylog
├── dist/             # Скомпилированный код
├── package.json      # Метаданные и зависимости
└── tsconfig.json     # Конфигурация TypeScript
```

## 🔒 Безопасность

### Personal Access Token (PAT)

1. Создайте PAT в Graylog: **System → Users → [Your User] → Edit → Create Token**
2. Токен должен иметь права на чтение целевых потоков
3. Сервер автоматически пробует два формата авторизации:
   - `token:YOUR_PAT`
   - `YOUR_PAT:token`

### SSL/TLS

- **Production:** Используйте валидный CA сертификат и `--ssl-verify=true`
- **Development/Self-signed:** Используйте `--ssl-verify=false`
- **Альтернатива:** Установите `NODE_EXTRA_CA_CERTS` на путь к доверенному CA

### Рекомендации

- ✅ Используйте переменные окружения для токенов
- ✅ Не коммитьте токены в git
- ✅ Используйте минимально необходимые права для PAT
- ✅ Регулярно ротируйте токены

## 🐛 Устранение неполадок

### 401/403 ошибки
- Проверьте валидность PAT
- Убедитесь, что у токена есть права на чтение потоков
- Проверьте формат URL (должен включать протокол: `https://`)

### TLS/SSL ошибки
```bash
# Опция 1: Отключить проверку (не для production!)
--ssl-verify=false

# Опция 2: Указать CA сертификат
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```

### Нет результатов
- Попробуйте простой запрос: `query: "*"`
- Проверьте временной диапазон (увеличьте `rangeSec`)
- Убедитесь, что в выбранных потоках есть данные
- Проверьте синтаксис Lucene запроса

### Debug режим
Запустите с флагом `--debug` для диагностики:
```bash
graylog-mcp --graylog-url ... --token ... --debug
```

## 🤝 Примеры использования

### Пример 1: Поиск ошибок за последний час
```typescript
// Инструмент: graylog.search_logs
{
  query: "level:ERROR",
  rangeSec: 3600
}
```

### Пример 2: Поиск по trace ID
```typescript
// Инструмент: graylog.search_uuid
{
  uuid: "abc-123-def-456",
  rangeSec: 86400
}
```

### Пример 3: Получение логов конкретного сервиса
```typescript
// Инструмент: graylog.search_logs
{
  query: "service:auth-api AND level:WARN",
  rangeSec: 7200,
  limit: 50
}
```

### Пример 4: Поиск HTTP 5xx ошибок
```typescript
// Инструмент: graylog.search_logs
{
  query: "status:[500 TO 599]",
  rangeSec: 3600
}
```

## 📝 Примечания

- Сервер использует Graylog REST API через `/api/search/universal/relative` и `/api/streams/{id}/messages`
- Максимальное количество результатов на запрос: 500
- По умолчанию возвращается 150 записей
- Поддерживается пагинация через параметры `limit` и `offset`
- Все временные метки в UTC

## 🔗 Полезные ссылки

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Graylog API Documentation](https://go2docs.graylog.org/current/downloading_and_installing_graylog/rest_api.htm)
- [Lucene Query Syntax](https://lucene.apache.org/core/9_0_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html)

## 📄 Лицензия

MIT © Aliaksei Buzo

## 🙏 Вклад

Contributions приветствуются! Пожалуйста, создайте issue или pull request в [GitHub репозитории](https://github.com/abuzo/graylog-mcp).