MCP-сервер журналов OpenSearch

MCP-сервер (Model Context Protocol) для запроса журналов OpenTelemetry в OpenSearch. Поддерживает среды разработки (dev) и производства (prod).

Архитектура

Сервер следует принципам SOLID и Clean Architecture:

src/
├── index.ts                     # Entry point
├── server.ts                    # MCP Server setup
├── config/
│   └── environments.ts          # Environment configuration
├── types/
│   └── index.ts                 # Type definitions
├── services/
│   ├── opensearch-client.ts     # HTTP client for OpenSearch
│   └── log-search.service.ts    # Business logic
├── tools/
│   ├── tool-definitions.ts      # Tool schemas
│   └── tool-handlers.ts         # Tool execution
└── utils/
    ├── query-builder.ts         # Query construction (Builder pattern)
    └── time-range.ts            # Time utilities

Примененные принципы

• Single Responsibility (SRP): Каждый модуль имеет единственную ответственность

• Open/Closed (OCP): Легко добавлять новые инструменты без изменения существующего кода

• Dependency Inversion (DIP): Сервисы зависят от абстракций (интерфейсов)

• Builder Pattern: QueryBuilder для гибкого построения запросов

Related MCP server: datadog-logs-mcp

Установка

cd Tools/mcp-opensearch-logs
npm install
npm run build

Настройка в Cursor

Добавьте это в свою конфигурацию Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "opensearch-logs": {
      "command": "node",
      "args": ["/ruta/al/proyecto/Tools/mcp-opensearch-logs/dist/index.js"],
      "env": {
        "OPENSEARCH_DEV_USERNAME": "tu-usuario-dev",
        "OPENSEARCH_DEV_PASSWORD": "tu-password-dev",
        "OPENSEARCH_PROD_USERNAME": "tu-usuario-prod",
        "OPENSEARCH_PROD_PASSWORD": "tu-password-prod"
      }
    }
  }
}

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

search_logs

Свободный поиск с использованием синтаксиса Lucene.

Примеры:

• "Найди журналы, содержащие 'error' в dev за последний час"

• "Найди журналы со статусом 500 в prod за последние 6 часов"

search_by_trace

Поиск всех журналов для конкретной трассировки OpenTelemetry.

Пример:

• "Дай мне все журналы для трассировки abc123 в dev"

search_by_service

Фильтрация журналов по имени сервиса.

Примеры:

• "Найди журналы сервиса stori-ios в prod"

• "Дай мне ошибки сервиса stori-ios в dev"

search_errors

Поиск журналов уровня ERROR или выше (severityNumber >= 17).

Примеры:

• "Дай мне ошибки за последний час в prod"

• "Найди ошибки, связанные с KYC в dev"

get_field_values

Получение наиболее распространенных значений поля (агрегация).

Примеры:

• "Какие значения имеет поле 'event' в prod?"

• "Дай мне самые распространенные типы ошибок в dev"

search_by_field

Поиск по конкретному полю и значению.

Пример:

• "Найди журналы с transactionId=abc123 в prod"

get_mapping

Получение маппинга полей индекса.

Пример:

• "Какие поля доступны в журналах prod?"

get_sample_log

Получение примера журнала для просмотра структуры.

Пример:

• "Дай мне пример журнала из prod, чтобы увидеть структуру"

Синтаксис поиска Lucene

Поле query поддерживает полный синтаксис Lucene:

Временные диапазоны

Разработка

# Desarrollo con watch mode
npm run dev

# Build
npm run build

# Lint
npm run lint

Структура журналов OpenTelemetry

Журналы следуют схеме OpenTelemetry:

{
  "time": "2024-01-15T10:30:00.000Z",
  "severityText": "ERROR",
  "severityNumber": 17,
  "body": "Error message",
  "attributes": {
    "event": "kyc_error",
    "kycFlow": "creditL1",
    "transactionId": "abc123"
  },
  "resource": {
    "service.name": "stori-ios",
    "service.version": "1.0.0"
  }
}