Kong MCP-Konnect Projekt – Detaillierte Beschreibung

Projektübersicht

Kong MCP-Konnect ist ein Serverprojekt, das auf dem Model Context Protocol (MCP) basiert und es KI-Assistenten ermöglicht, Kong Gateway-Konfigurationen, Traffic- und Analysedaten abzufragen und zu analysieren. Das Projekt ermöglicht es KI-Assistenten wie Claude, über natürliche Sprache mit dem Kong Konnect API-Gateway zu interagieren.

Kernfunktionen

• API-Request-Analyse-Abfragen: Unterstützung für API-Request-Analysen mit benutzerdefinierten Filtern
• Gateway-Konfigurationsmanagement: Auflisten und Überprüfen von Gateway-Services, Routen, Konsumenten und Plugins
• Control-Plane-Management: Verwalten von Control Planes und Control-Plane-Gruppen
• KI-Assistenten-Integration: Integration mit Claude und anderen MCP-kompatiblen KI-Assistenten

Projektstruktur

src/
├── index.ts            # Haupteinstiegspunkt
├── api.ts             # Kong API-Client
├── tools.ts           # Tool-Definitionen
├── parameters.ts      # Zod-Schema für Tool-Parameter
├── prompts.ts         # Detaillierte Tool-Dokumentation
├── operations/
│   ├── analytics.ts   # API-Request-Analyse-Operationen
│   ├── configuration.ts # Services, Routen, Konsumenten, Plugins
│   └── controlPlanes.ts # Control-Plane-Management
└── types.ts           # Allgemeine Typdefinitionen

Systemanforderungen

• Node.js 20 oder höher
• Kong Konnect-Konto mit API-Zugriffsberechtigungen
• MCP-fähiger Client (wie Claude Desktop, Cursor usw.)

Installation und Konfiguration

1. Klonen und Installieren

# Repository klonen
git clone https://github.com/Kong/mcp-konnect.git
cd mcp-konnect

# Abhängigkeiten installieren
npm install

# Projekt bauen
npm run build

2. Umgebungskonfiguration

Setzen Sie die folgenden Umgebungsvariablen, um den MCP-Server zu konfigurieren:

# Erforderlich: Ihr Kong Konnect API-Schlüssel
export KONNECT_ACCESS_TOKEN=kpat_api_key_here

# Optional: Die zu verwendende API-Region (Standard: US)
# Mögliche Werte: US, EU, AU, ME, IN
export KONNECT_REGION=us

Verfügbare Tools

Analysetools

1. API-Request-Analyse (analyze-api-requests)

Abfragen und Analysieren von Kong API-Gateway-Requests, unterstützt benutzerdefinierte Filter.

Eingabeparameter:

• timeRange: Zeitraum für die Datenabfrage (15M, 1H, 6H, 12H, 24H, 7D)
• statusCodes: Filtern nach bestimmten HTTP-Statuscodes
• excludeStatusCodes: Ausschließen bestimmter HTTP-Statuscodes
• httpMethods: Filtern nach HTTP-Methode
• consumerIds: Filtern nach Konsumenten-ID
• serviceIds: Filtern nach Service-ID
• routeIds: Filtern nach Routen-ID
• maxResults: Maximale Anzahl der zurückzugebenden Ergebnisse

2. Konsumenten-Request-Analyse (analyze-consumer-requests)

Analysieren von API-Requests, die von einem bestimmten Konsumenten gesendet wurden.

Eingabeparameter:

• consumerId: ID des zu analysierenden Konsumenten
• timeRange: Zeitraum für die Datenabfrage
• successOnly: Nur erfolgreiche (2xx) Requests anzeigen
• failureOnly: Nur fehlgeschlagene (Nicht-2xx) Requests anzeigen
• maxResults: Maximale Anzahl der zurückzugebenden Ergebnisse

Konfigurationstools

1. Services auflisten (list-services)

Auflisten aller Services, die mit einer Control Plane verknüpft sind.

Eingabeparameter:

• controlPlaneId: Control-Plane-ID
• size: Anzahl der zurückzugebenden Services
• offset: Paginierungs-Offset-Token

2. Routen auflisten (list-routes)

Auflisten aller Routen, die mit einer Control Plane verknüpft sind.

3. Konsumenten auflisten (list-consumers)

Auflisten aller Konsumenten, die mit einer Control Plane verknüpft sind.

4. Plugins auflisten (list-plugins)

Auflisten aller Plugins, die mit einer Control Plane verknüpft sind.

Control-Plane-Management-Tools

1. Control Planes auflisten (list-control-planes)

Auflisten aller Control Planes in der Organisation.

Eingabeparameter:

• pageSize: Anzahl der Control Planes pro Seite
• pageNumber: Nummer der abzurufenden Seite
• filterName: Filtern von Control Planes nach Namen
• filterClusterType: Filtern nach Clustertyp
• filterCloudGateway: Filtern nach Cloud-Gateway-Funktionalität
• labels: Filtern nach Labels
• sort: Sortierfeld und -richtung

2. Control Plane abrufen (get-control-plane)

Abrufen detaillierter Informationen zu einer bestimmten Control Plane.

3. Control-Plane-Gruppenmitglieder auflisten (list-control-plane-group-members)

Auflisten aller Control-Plane-Mitglieder einer bestimmten Gruppe.

4. Control-Plane-Gruppenmitgliedschaft prüfen (check-control-plane-group-membership)

Prüfen, ob eine Control Plane Mitglied einer Gruppe ist.

Verwendung mit Claude-Integration

1. Claude for Desktop installieren

Laden Sie Claude for Desktop von der Claude-Website herunter und installieren Sie es.

2. Claude Desktop konfigurieren

Erstellen oder bearbeiten Sie die Claude Desktop-Konfigurationsdatei:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Konfiguration hinzufügen

{
  "mcpServers": {
    "kong-konnect": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-konnect/build/index.js"
      ],
      "env": {
        "KONNECT_ACCESS_TOKEN": "kpat_api_key_here",
        "KONNECT_REGION": "us"
      }
    }
  }
}

4. Claude for Desktop neu starten

Nach dem Neustart stehen die Kong Konnect-Tools in Claude zur Verfügung.

Beispiel-Workflows

1. Alle Control Planes auflisten

Bitte liste alle Control Planes in meiner Kong Konnect-Organisation auf.

2. Services einer bestimmten Control Plane auflisten

Liste alle Services der Control Plane [CONTROL_PLANE_NAME/ID] auf.

3. API-Requests eines bestimmten Services abfragen

Zeige mir alle API-Requests des Services [SERVICE_NAME/ID] mit 5xx-Statuscodes in der letzten Stunde.

4. Konsumenten einer Control Plane auflisten

Liste alle Konsumenten der Control Plane [CONTROL_PLANE_NAME/ID] auf.

5. Requests eines bestimmten Konsumenten analysieren

Zeige mir alle Requests des Konsumenten [CONSUMER_NAME/ID] in den letzten 24 Stunden.

6. Häufige Fehler oder Muster prüfen

Was sind die häufigsten Fehler, die dieser Konsument erlebt?

Entwicklungsleitfaden

Um ein neues Tool hinzuzufügen, führen Sie die folgenden Schritte aus:

1. Definieren Sie Parameter in parameters.ts
2. Fügen Sie Dokumentation in prompts.ts hinzu
3. Erstellen Sie die Operationslogik in der entsprechenden Datei in operations/
4. Registrieren Sie das Tool in tools.ts
5. Verarbeiten Sie die Tool-Ausführung in index.ts

Fehlerbehebung

Verbindungsfehler

• Stellen Sie sicher, dass Ihr API-Schlüssel gültig ist und die erforderlichen Berechtigungen besitzt
• Überprüfen Sie, ob die API-Region korrekt angegeben ist
• Stellen Sie sicher, dass Ihr Netzwerk eine Verbindung zur Kong Konnect API herstellen kann

Authentifizierungsfehler

• Generieren Sie Ihren API-Schlüssel im Kong Konnect-Portal neu
• Überprüfen Sie, ob die Umgebungsvariablen korrekt gesetzt sind

Daten nicht gefunden

• Stellen Sie sicher, dass die in der Anfrage verwendeten IDs korrekt sind
• Überprüfen Sie, ob die Ressource in der angegebenen Control Plane vorhanden ist
• Stellen Sie sicher, dass der Zeitraum für die Analyseabfrage gültig ist

Zusammenfassung

Kong MCP-Konnect ist ein leistungsstarkes Tool, das die Kluft zwischen KI-Assistenten und der Verwaltung von Kong API-Gateways überbrückt. Durch die Bereitstellung einer Schnittstelle in natürlicher Sprache zum Abfragen und Analysieren von API-Gateway-Konfigurationen, Traffic- und Analysedaten wird die API-Verwaltung intuitiver und effizienter. Das Projekt bietet einen umfangreichen Funktionsumfang, von grundlegenden Konfigurationsabfragen bis hin zu erweiterten Traffic-Analysen, und ist ein wichtiges Werkzeug für die moderne API-Infrastrukturverwaltung.