OpenSearch Logs MCP Server

MCP (Model Context Protocol) server para consultar logs de OpenTelemetry en OpenSearch. Soporta ambientes de desarrollo (dev) y producción (prod).

Arquitectura

El servidor sigue los principios SOLID y 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

Principios Aplicados

• Single Responsibility (SRP): Cada módulo tiene una única responsabilidad
• Open/Closed (OCP): Fácil agregar nuevas herramientas sin modificar código existente
• Dependency Inversion (DIP): Los servicios dependen de abstracciones (interfaces)
• Builder Pattern: QueryBuilder para construcción fluida de queries

Instalación

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

Configuración en Cursor

Agrega esto a tu configuración de 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"
      }
    }
  }
}

Herramientas Disponibles

search_logs

Búsqueda libre con sintaxis Lucene.

Ejemplos:

• "Busca logs que contengan 'error' en dev de la última hora"
• "Busca logs con status 500 en prod de las últimas 6 horas"

search_by_trace

Busca todos los logs de un trace de OpenTelemetry.

Ejemplo:

• "Dame todos los logs del trace abc123 en dev"

search_by_service

Filtra logs por nombre de servicio.

Ejemplos:

• "Busca logs del servicio stori-ios en prod"
• "Dame los errores del servicio stori-ios en dev"

search_errors

Busca logs de nivel ERROR o superior (severityNumber >= 17).

Ejemplos:

• "Dame los errores de la última hora en prod"
• "Busca errores relacionados con KYC en dev"

get_field_values

Obtiene los valores más comunes de un campo (agregación).

Ejemplos:

• "Qué valores tiene el campo 'event' en prod?"
• "Dame los tipos de error más comunes en dev"

search_by_field

Busca por un campo y valor específico.

Ejemplo:

• "Busca logs con transactionId=abc123 en prod"

get_mapping

Obtiene el mapeo de campos del índice.

Ejemplo:

• "Qué campos están disponibles en los logs de prod?"

get_sample_log

Obtiene un log de ejemplo para ver la estructura.

Ejemplo:

• "Dame un ejemplo de log de prod para ver la estructura"

Sintaxis de Búsqueda Lucene

El campo query soporta sintaxis Lucene completa:

Rangos de Tiempo

Desarrollo

# Desarrollo con watch mode
npm run dev

# Build
npm run build

# Lint
npm run lint

Estructura de Logs OpenTelemetry

Los logs siguen el esquema 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"
  }
}