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

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

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