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 для гибкого построения запросов

Установка

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"
 }
}

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• get_field_valuesB
• get_mappingA
• get_sample_logB
• search_by_fieldC
• search_by_serviceC
• search_by_traceA
• search_errorsC
• search_logsA