splunk-mcp

Splunk MCP-Tool (Model Context Protocol)

Ein FastMCP-basiertes Tool für die Interaktion mit Splunk Enterprise/Cloud über natürliche Sprache. Dieses Tool bietet eine Reihe von Funktionen zum Durchsuchen von Splunk-Daten, Verwalten von KV-Speichern und Zugriff auf Splunk-Ressourcen über eine intuitive Benutzeroberfläche.

Betriebsarten

Das Tool arbeitet in drei Modi:

1. SSE-Modus (Standard)
   • Server-Sent Events-basierte Kommunikation
   • Bidirektionale Interaktion in Echtzeit
   • Geeignet für webbasierte MCP-Clients
   • Standardmodus, wenn keine Argumente angegeben sind
   • Zugriff über /sse -Endpunkt
2. API-Modus
   • RESTful-API-Endpunkte
   • Zugriff über das Endpunktpräfix /api/v1
   • Beginnen Sie mit python splunk_mcp.py api
3. STDIO-Modus
   • Standardmäßige Eingabe-/Ausgabe-basierte Kommunikation
   • Kompatibel mit Claude Desktop und anderen MCP-Clients
   • Ideal für die direkte Integration mit KI-Assistenten
   • Beginnen Sie mit python splunk_mcp.py stdio

Merkmale

• Splunk-Suche : Führen Sie Splunk-Suchen mit Abfragen in natürlicher Sprache aus
• Indexverwaltung : Splunk-Indizes auflisten und prüfen
• Benutzerverwaltung : Splunk-Benutzer anzeigen und verwalten
• KV Store Operations : Erstellen, Auflisten und Verwalten von KV Store-Sammlungen
• Asynchrone Unterstützung : Erstellt mit Asynchron-/Wartemustern für bessere Leistung
• Detaillierte Protokollierung : Umfassende Protokollierung mit Emoji-Indikatoren für bessere Sichtbarkeit
• SSL-Konfiguration : Flexible SSL-Verifizierungsoptionen für unterschiedliche Sicherheitsanforderungen
• Verbessertes Debugging : Detaillierte Verbindungs- und Fehlerprotokollierung zur Fehlerbehebung
• Umfassende Tests : Unit-Tests, die alle wichtigen Funktionen abdecken
• Fehlerbehandlung : Robuste Fehlerbehandlung mit entsprechenden Statuscodes
• SSE-Konformität : Vollständig konform mit der MCP SSE-Spezifikation

Verfügbare MCP-Tools

Über die MCP-Schnittstelle stehen folgende Tools zur Verfügung:

Werkzeugverwaltung

• list_tools
  • Listet alle verfügbaren MCP-Tools mit ihren Beschreibungen und Parametern auf

Gesundheitscheck

• Gesundheitscheck
  • Gibt eine Liste der verfügbaren Splunk-Apps zurück, um die Konnektivität zu überprüfen
• Klingeln
  • Einfacher Ping-Endpunkt zur Überprüfung, ob der MCP-Server aktiv ist

Benutzerverwaltung

• aktueller_Benutzer
  • Gibt Informationen über den aktuell authentifizierten Benutzer zurück
• Benutzerliste
  • Gibt eine Liste aller Benutzer und ihrer Rollen zurück

Indexverwaltung

• Listenindizes
  • Gibt eine Liste aller zugänglichen Splunk-Indizes zurück
• get_index_info
  • Gibt detaillierte Informationen zu einem bestimmten Index zurück
  • Parameter: index_name (Zeichenfolge)
• Indizes und Quelltypen
  • Gibt eine umfassende Liste der Indizes und ihrer Quelltypen zurück

Suchen

• Suche_splunk
  • Führt eine Splunk-Suchabfrage aus
  • Parameter:
    • search_query (Zeichenfolge): Splunk-Suchzeichenfolge
    • earliest_time (Zeichenfolge, optional): Startzeit für das Suchfenster
    • latest_time (Zeichenfolge, optional): Endzeit für das Suchfenster
    • max_results (Ganzzahl, optional): Maximale Anzahl der zurückzugebenden Ergebnisse
• Liste gespeicherter Suchen
  • Gibt eine Liste der gespeicherten Suchen in der Splunk-Instanz zurück

KV Store

• Liste_kvstore_sammlungen
  • Listet alle KV-Store-Kollektionen auf
• Erstellen Sie eine KVStore-Sammlung
  • Erstellt eine neue KV-Store-Kollektion
  • Parameter: collection_name (Zeichenfolge)
• delete_kvstore_collection
  • Löscht eine vorhandene KV-Store-Sammlung
  • Parameter: collection_name (Zeichenfolge)

SSE-Endpunkte

Beim Ausführen im SSE-Modus sind die folgenden Endpunkte verfügbar:

• /sse : Gibt SSE-Verbindungsinformationen im Text-/Ereignisstromformat zurück
  • Stellt Metadaten zur SSE-Verbindung bereit
  • Enthält die URL für den Nachrichtenendpunkt
  • Bietet Protokoll- und Fähigkeitsinformationen
• /sse/messages : Der Hauptendpunkt des SSE-Streams
  • Streamt Systemereignisse wie Heartbeats
  • Hält die Verbindung dauerhaft aufrecht
  • Sendet ordnungsgemäß formatierte SSE-Ereignisse
• /sse/health : Integritätsprüfungsendpunkt für den SSE-Modus
  • Gibt Status- und Versionsinformationen im SSE-Format zurück

Fehlerbehandlung

Die MCP-Implementierung beinhaltet eine konsistente Fehlerbehandlung:

• Ungültige Suchbefehle oder fehlerhafte Anfragen
• Unzureichende Berechtigungen
• Ressource nicht gefunden
• Validierung ungültiger Eingaben
• Unerwartete Serverfehler
• Verbindungsprobleme mit dem Splunk-Server

Alle Fehlerantworten enthalten eine detaillierte Meldung, die den Fehler erklärt.

Voraussetzungen

• Python 3.10 oder höher
• Poesie für das Abhängigkeitsmanagement
• Splunk Enterprise/Cloud-Instanz
• Entsprechende Splunk-Anmeldeinformationen mit den erforderlichen Berechtigungen

Installation

Option 1: Lokale Installation

1. Klonen Sie das Repository:

2. Installieren Sie Abhängigkeiten mit Poetry:

3. Kopieren Sie die Beispielumgebungsdatei und konfigurieren Sie Ihre Einstellungen:

4. Aktualisieren Sie die .env Datei mit Ihren Splunk-Anmeldeinformationen:

Option 2: Docker-Installation

1. Rufen Sie das neueste Bild ab:

2. Erstellen Sie Ihre .env Datei wie oben beschrieben oder verwenden Sie Umgebungsvariablen direkt.
3. Mit Docker Compose ausführen:

Oder direkt mit Docker:

Verwendung

Lokale Nutzung

Das Tool kann in drei Modi ausgeführt werden:

1. SSE-Modus (Standard für MCP-Clients):

3. STDIO-Modus:

Docker-Nutzung

Das Projekt unterstützt sowohl die neuen Befehle docker compose “ (V2) als auch docker-compose (V1). Die folgenden Beispiele verwenden die Syntax von V2, aber beide werden unterstützt.

1. SSE-Modus (Standard):

2. API-Modus:

3. STDIO-Modus:

Testen mit Docker

Das Projekt umfasst eine dedizierte Testumgebung in Docker:

1. Führen Sie alle Tests aus:

2. Führen Sie bestimmte Testkomponenten aus:

Die Testergebnisse sind im Verzeichnis ./test-results verfügbar.

Tipps zur Docker-Entwicklung

1. Gebäudebilder :

2. Protokolle anzeigen :

3. Debuggen :

Hinweis: Wenn Sie Docker Compose V1 verwenden, ersetzen Sie in den obigen Befehlen docker compose durch docker-compose .

Sicherheitshinweise

1. Umgebungsvariablen :

• Übernehmen Sie niemals .env Dateien
• Verwenden Sie .env.example als Vorlage
• Erwägen Sie die Verwendung von Docker-Geheimnissen für die Produktion

2. SSL-Verifizierung :

• VERIFY_SSL=true empfohlen für die Produktion
• Kann für Entwicklung/Tests deaktiviert werden
• Konfigurieren über Umgebungsvariablen

3. Hafenlage :

• Nur die erforderlichen Ports offen legen
• Verwenden Sie nach Möglichkeit das interne Docker-Netzwerk
• Berücksichtigen Sie die Netzwerksicherheit in der Produktion

Umgebungsvariablen

Konfigurieren Sie die folgenden Umgebungsvariablen:

• SPLUNK_HOST : Ihre Splunk-Hostadresse
• SPLUNK_PORT : Splunk-Verwaltungsport (Standard: 8089)
• SPLUNK_USERNAME : Ihr Splunk-Benutzername
• SPLUNK_PASSWORD : Ihr Splunk-Passwort
• SPLUNK_SCHEME : Verbindungsschema (Standard: https)
• VERIFY_SSL : SSL-Verifizierung aktivieren/deaktivieren (Standard: true)
• FASTMCP_LOG_LEVEL : Protokollierungsebene (Standard: INFO)
• SERVER_MODE : Servermodus (sse, api, stdio) bei Verwendung von uvicorn

SSL-Konfiguration

Das Tool bietet flexible SSL-Verifizierungsoptionen:

1. Standardmodus (Sicherer Modus) :

• Vollständige SSL-Zertifikatsüberprüfung
• Hostnamenüberprüfung aktiviert
• Empfohlen für Produktionsumgebungen

2. Entspannter Modus :

• SSL-Zertifikatsüberprüfung deaktiviert
• Hostnamenüberprüfung deaktiviert
• Nützlich zum Testen oder für selbstsignierte Zertifikate

Testen

Das Projekt umfasst eine umfassende Testabdeckung mit pytest und End-to-End-Tests mit einem benutzerdefinierten MCP-Client:

Ausführen von Tests

Grundlegende Testausführung:

Mit Berichterstattung über die Berichterstattung:

Mit ausführlicher Ausgabe:

End-to-End-SSE-Tests

Das Projekt umfasst ein benutzerdefiniertes MCP-Client-Testskript, das eine Verbindung zum Live-SSE-Endpunkt herstellt und alle Tools testet:

Dieses Skript fungiert als MCP-Client, indem es:

1. Herstellen einer Verbindung zum /sse -Endpunkt, um die Nachrichten-URL abzurufen
2. Senden von Toolaufrufen an den Nachrichtenendpunkt
3. Verarbeiten der SSE-Ereignisse zum Extrahieren von Toolergebnissen
4. Validieren der Ergebnisse anhand der erwarteten Formate

Dies ermöglicht praxisnahe Tests der SSE-Schnittstelle, wie sie von einem tatsächlichen MCP-Client verwendet würde.

Teststruktur

Das Projekt verwendet drei sich ergänzende Testansätze:

1. MCP-Integrationstests ( tests/test_api.py ) :
   • Testet die MCP-Tools-Schnittstelle über mcp.call_tool()
   • Überprüft die ordnungsgemäße Werkzeugregistrierung mit FastMCP
   • Stellt das richtige Antwortformat und die richtige Datenstruktur sicher
   • Validiert die Fehlerbehandlung auf MCP-Schnittstellenebene
   • Hinweis: Diese Datei sollte idealerweise in test_mcp.py umbenannt werden, um ihren Zweck besser widerzuspiegeln
2. Direkte Funktionstests ( tests/test_endpoints_pytest.py ) :
   • Testet Splunk-Funktionen direkt (unter Umgehung der MCP-Schicht)
   • Bietet eine umfassendere Abdeckung der Details der Funktionsimplementierung
   • Testet Randfälle, Parametervariationen und Fehlerbehandlung
   • Beinhaltet Tests für SSL-Konfiguration, Verbindungsparameter und Timeouts
   • Verwendet parametrisiertes Testen für eine effiziente Testabdeckung
3. End-to-End-MCP-Clienttests ( test_endpoints.py ) :
   • Verhält sich wie ein echter MCP-Client, der eine Verbindung zum SSE-Endpunkt herstellt
   • Testet den gesamten Ablauf von der Verbindung über den Tool-Aufruf bis hin zur Antwortanalyse
   • Validiert die tatsächliche Implementierung des SSE-Protokolls
   • Testet Tools mit realen Parametern gegen den Live-Server
4. Konfigurationstests ( tests/test_config.py ) :
   • Tests zum Parsen von Umgebungsvariablen
   • SSL-Verifizierungseinstellungen
   • Validierung der Verbindungsparameter

Testwerkzeuge

Die Tests unterstützen:

• Asynchrones Testen mit pytest-asyncio
• Abdeckungsberichte mit pytest-cov
• Mocking mit pytest-mock
• Parametrisiertes Testen
• Testen des Verbindungstimeouts

Fehlerbehebung

Verbindungsprobleme

1. Grundlegende Konnektivität :

• Das Tool führt nun einen grundlegenden TCP-Konnektivitätstest durch
• Überprüfen Sie, ob Port 8089 erreichbar ist
• Überprüfen Sie das Netzwerk-Routing und die Firewalls

2. SSL-Probleme :

• Wenn SSL-Fehler auftreten, versuchen Sie VERIFY_SSL=false festzulegen.
• Überprüfen Sie die Gültigkeit des Zertifikats und die Vertrauenskette
• Überprüfen, ob der Hostname mit dem Zertifikat übereinstimmt

3. Authentifizierungsprobleme :

• Überprüfen der Splunk-Anmeldeinformationen
• Überprüfen Sie die Benutzerberechtigungen
• Stellen Sie sicher, dass das Konto nicht gesperrt ist

4. Debuggen :

• Setzen Sie FASTMCP_LOG_LEVEL=DEBUG für detaillierte Protokolle
• Überprüfen Sie die Verbindungsprotokolle auf bestimmte Fehlermeldungen
• Überprüfen der SSL-Konfigurationsmeldungen

5. SSE-Verbindungsprobleme :

• Überprüfen Sie, ob der SSE-Endpunkt über /sse erreichbar ist.
• Überprüfen Sie, ob die Inhaltstyp-Header korrekt sind.
• Verwenden Sie Browser-Entwicklertools, um SSE-Verbindungen zu überprüfen

Claude Integration

Claude Desktop-Konfiguration

Sie können Splunk MCP in Claude Desktop integrieren, indem Sie es für den SSE- oder STDIO-Modus konfigurieren. Fügen Sie Ihrer claude_desktop_config.json die folgende Konfiguration hinzu:

STDIO-Modus (empfohlen für Desktop)

SSE-Modus

Verwendung mit Claude

Nach der Konfiguration können Sie über Claude in natürlicher Sprache mit Splunk interagieren. Beispiele:

1. Liste der verfügbaren Indizes:

2. Splunk-Daten durchsuchen:

3. Systemzustand abrufen:

4. KV-Stores verwalten:

Die MCP-Tools stehen Claude automatisch zur Verfügung, sodass er diese Vorgänge über Befehle in natürlicher Sprache ausführen kann.

Lizenz

[Ihre Lizenz hier]

Danksagung

• FastMCP-Framework
• Splunk SDK für Python
• Python-Decouple für das Konfigurationsmanagement
• SSE Starlette für die SSE-Implementierung