OpenSearch Logs MCP Server

MCP (Model Context Protocol) Server zum Abfragen von OpenTelemetry-Logs in OpenSearch. Unterstützt Entwicklungs- (dev) und Produktionsumgebungen (prod).

Architektur

Der Server folgt den SOLID-Prinzipien und der 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

Angewandte Prinzipien

• Single Responsibility (SRP): Jedes Modul hat eine einzige Verantwortung

• Open/Closed (OCP): Einfaches Hinzufügen neuer Tools ohne Änderung des bestehenden Codes

• Dependency Inversion (DIP): Dienste hängen von Abstraktionen (Interfaces) ab

• Builder Pattern: QueryBuilder für den flüssigen Aufbau von Abfragen

Related MCP server: datadog-logs-mcp

Installation

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

Konfiguration in Cursor

Füge dies zu deiner Cursor-Konfiguration hinzu (~/.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"
      }
    }
  }
}

Verfügbare Tools

search_logs

Freitextsuche mit Lucene-Syntax.

Beispiele:

• "Suche nach Logs, die 'error' enthalten, in dev aus der letzten Stunde"

• "Suche nach Logs mit Status 500 in prod aus den letzten 6 Stunden"

search_by_trace

Sucht alle Logs eines OpenTelemetry-Traces.

Beispiel:

• "Gib mir alle Logs für den Trace abc123 in dev"

search_by_service

Filtert Logs nach Dienstname.

Beispiele:

• "Suche nach Logs des Dienstes stori-ios in prod"

• "Gib mir die Fehler des Dienstes stori-ios in dev"

search_errors

Sucht nach Logs der Stufe ERROR oder höher (severityNumber >= 17).

Beispiele:

• "Gib mir die Fehler der letzten Stunde in prod"

• "Suche nach Fehlern im Zusammenhang mit KYC in dev"

get_field_values

Ruft die häufigsten Werte eines Feldes ab (Aggregation).

Beispiele:

• "Welche Werte hat das Feld 'event' in prod?"

• "Gib mir die häufigsten Fehlertypen in dev"

search_by_field

Sucht nach einem spezifischen Feld und Wert.

Beispiel:

• "Suche nach Logs mit transactionId=abc123 in prod"

get_mapping

Ruft das Feld-Mapping des Index ab.

Beispiel:

• "Welche Felder sind in den prod-Logs verfügbar?"

get_sample_log

Ruft ein Beispiel-Log ab, um die Struktur zu sehen.

Beispiel:

• "Gib mir ein Beispiel-Log aus prod, um die Struktur zu sehen"

Lucene-Suchsyntax

Das Feld query unterstützt die vollständige Lucene-Syntax:

Zeitbereiche

Entwicklung

# Desarrollo con watch mode
npm run dev

# Build
npm run build

# Lint
npm run lint

OpenTelemetry-Logstruktur

Die Logs folgen dem OpenTelemetry-Schema:

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