Présentation détaillée du projet Kong MCP-Konnect

Aperçu du projet

Kong MCP-Konnect est un projet de serveur basé sur le protocole de contexte de modèle (Model Context Protocol, MCP) qui permet aux assistants d'IA d'interroger et d'analyser la configuration, le trafic et les données d'analyse de Kong Gateway. Ce projet permet à des assistants d'IA tels que Claude d'interagir avec la passerelle API de Kong Konnect en langage naturel.

Caractéristiques principales

• Requêtes d'analyse des requêtes API : Prise en charge de l'analyse des requêtes API avec des filtres personnalisés
• Gestion de la configuration de la passerelle : Liste et inspection des services, des routes, des consommateurs et des plugins de la passerelle
• Gestion du plan de contrôle : Gestion du plan de contrôle et des groupes de plans de contrôle
• Intégration de l'assistant d'IA : Intégration avec Claude et d'autres assistants d'IA compatibles MCP

Structure du projet

src/
├── index.ts            # Point d'entrée principal
├── api.ts             # Client API Kong
├── tools.ts           # Définitions des outils
├── parameters.ts      # Schémas Zod pour les paramètres des outils
├── prompts.ts         # Documentation détaillée des outils
├── operations/
│   ├── analytics.ts   # Opérations d'analyse des requêtes API
│   ├── configuration.ts # Services, routes, consommateurs, plugins
│   └── controlPlanes.ts # Gestion du plan de contrôle
└── types.ts           # Définitions de types communs

Configuration système requise

• Node.js 20 ou version ultérieure
• Compte Kong Konnect avec accès API
• Client prenant en charge les fonctionnalités MCP (tel que Claude Desktop, Cursor, etc.)

Installation et configuration

1. Cloner et installer

# Cloner le dépôt
git clone https://github.com/Kong/mcp-konnect.git
cd mcp-konnect

# Installer les dépendances
npm install

# Construire le projet
npm run build

2. Configuration de l'environnement

Définissez les variables d'environnement suivantes pour configurer le serveur MCP :

# Obligatoire : Votre clé API Kong Konnect
export KONNECT_ACCESS_TOKEN=kpat_api_key_here

# Facultatif : Région API à utiliser (par défaut US)
# Valeurs possibles : US, EU, AU, ME, IN
export KONNECT_REGION=us

Outils disponibles

Outils d'analyse

1. Analyse des requêtes API (analyze-api-requests)

Interroge et analyse les requêtes de la passerelle API Kong, prend en charge les filtres personnalisés.

Paramètres d'entrée :

• timeRange: Plage de temps pour la récupération des données (15M, 1H, 6H, 12H, 24H, 7D)
• statusCodes: Filtrer par codes d'état HTTP spécifiques
• excludeStatusCodes: Exclure les codes d'état HTTP spécifiques
• httpMethods: Filtrer par méthode HTTP
• consumerIds: Filtrer par ID de consommateur
• serviceIds: Filtrer par ID de service
• routeIds: Filtrer par ID de route
• maxResults: Nombre maximal de résultats à renvoyer

2. Analyse des requêtes des consommateurs (analyze-consumer-requests)

Analyse les requêtes API émises par un consommateur spécifique.

Paramètres d'entrée :

• consumerId: ID du consommateur à analyser
• timeRange: Plage de temps pour la récupération des données
• successOnly: Afficher uniquement les requêtes réussies (2xx)
• failureOnly: Afficher uniquement les requêtes échouées (non-2xx)
• maxResults: Nombre maximal de résultats à renvoyer

Outils de configuration

1. Lister les services (list-services)

Liste tous les services associés à un plan de contrôle.

Paramètres d'entrée :

• controlPlaneId: ID du plan de contrôle
• size: Nombre de services à renvoyer
• offset: Jeton de décalage de pagination

2. Lister les routes (list-routes)

Liste toutes les routes associées à un plan de contrôle.

3. Lister les consommateurs (list-consumers)

Liste tous les consommateurs associés à un plan de contrôle.

4. Lister les plugins (list-plugins)

Liste tous les plugins associés à un plan de contrôle.

Outils de gestion du plan de contrôle

1. Lister les plans de contrôle (list-control-planes)

Liste tous les plans de contrôle de l'organisation.

Paramètres d'entrée :

• pageSize: Nombre de plans de contrôle par page
• pageNumber: Numéro de page à récupérer
• filterName: Filtrer les plans de contrôle par nom
• filterClusterType: Filtrer par type de cluster
• filterCloudGateway: Filtrer par fonctionnalité de passerelle cloud
• labels: Filtrer par étiquettes
• sort: Champ et direction de tri

2. Obtenir un plan de contrôle (get-control-plane)

Obtient les détails d'un plan de contrôle spécifique.

3. Lister les membres du groupe de plans de contrôle (list-control-plane-group-members)

Liste tous les membres du plan de contrôle d'un groupe spécifique.

4. Vérifier l'appartenance au groupe de plans de contrôle (check-control-plane-group-membership)

Vérifie si un plan de contrôle est membre d'un groupe.

Utilisation avec l'intégration de Claude

1. Installer Claude for Desktop

Téléchargez et installez Claude for Desktop depuis le site officiel de Claude.

2. Configurer Claude Desktop

Créez ou modifiez le fichier de configuration de Claude Desktop :

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

3. Ajouter la configuration

{
  "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. Redémarrer Claude for Desktop

Après le redémarrage, l'outil Kong Konnect sera disponible pour Claude.

Exemples de flux de travail

1. Lister tous les plans de contrôle

Veuillez lister tous les plans de contrôle de mon organisation Kong Konnect.

2. Lister les services d'un plan de contrôle spécifique

Lister tous les services du plan de contrôle [CONTROL_PLANE_NAME/ID].

3. Interroger les requêtes API d'un service spécifique

Montrez-moi toutes les requêtes API du service [SERVICE_NAME/ID] avec des codes d'état 5xx au cours de la dernière heure.

4. Lister les consommateurs d'un plan de contrôle

Lister tous les consommateurs du plan de contrôle [CONTROL_PLANE_NAME/ID].

5. Analyser les requêtes d'un consommateur spécifique

Montrez-moi toutes les requêtes émises par le consommateur [CONSUMER_NAME/ID] au cours des dernières 24 heures.

6. Vérifier les erreurs ou les modèles courants

Quelles sont les erreurs les plus courantes rencontrées par ce consommateur ?

Guide de développement

Pour ajouter un nouvel outil, suivez ces étapes :

1. Définir les paramètres dans parameters.ts
2. Ajouter la documentation dans prompts.ts
3. Créer la logique d'opération dans le fichier approprié dans operations/
4. Enregistrer l'outil dans tools.ts
5. Gérer l'exécution de l'outil dans index.ts

Dépannage

Erreurs de connexion

• Vérifiez que votre clé API est valide et dispose des autorisations nécessaires
• Vérifiez que la région API est correctement spécifiée
• Assurez-vous que votre réseau peut se connecter à l'API Kong Konnect

Erreurs d'authentification

• Régénérez votre clé API dans le portail Kong Konnect
• Vérifiez que les variables d'environnement sont correctement définies

Données introuvables

• Vérifiez que les ID utilisés dans la requête sont corrects
• Vérifiez que la ressource existe dans le plan de contrôle spécifié
• Assurez-vous que la plage de temps de la requête d'analyse est valide

Résumé

Kong MCP-Konnect est un outil puissant qui comble le fossé entre les assistants d'IA et la gestion de la passerelle API Kong. En fournissant une interface en langage naturel pour interroger et analyser la configuration, le trafic et les données d'analyse de la passerelle API, il rend la gestion des API plus intuitive et efficace. Le projet offre un ensemble riche de fonctionnalités, des requêtes de configuration de base à l'analyse avancée du trafic, ce qui en fait un outil important pour la gestion moderne de l'infrastructure API.