Kong MCP-Konnect - Descripción Detallada del Proyecto

Resumen del Proyecto

Kong MCP-Konnect es un proyecto de servidor basado en el Protocolo de Contexto del Modelo (Model Context Protocol, MCP) que permite a los asistentes de IA consultar y analizar la configuración, el tráfico y los datos analíticos de Kong Gateway. Este proyecto permite que asistentes de IA como Claude interactúen con la puerta de enlace API de Kong Konnect a través del lenguaje natural.

Características Principales

• Análisis de Consultas de Solicitudes API: Soporte para análisis de solicitudes API con filtros personalizados.
• Gestión de la Configuración de la Puerta de Enlace: Listar e inspeccionar servicios, rutas, consumidores y plugins de la puerta de enlace.
• Gestión del Plano de Control: Gestionar el plano de control y los grupos de planos de control.
• Integración con Asistentes de IA: Integración con Claude y otros asistentes de IA compatibles con MCP.

Estructura del Proyecto

src/
├── index.ts            # Punto de entrada principal
├── api.ts             # Cliente API de Kong
├── tools.ts           # Definiciones de herramientas
├── parameters.ts      # Esquemas Zod para los parámetros de las herramientas
├── prompts.ts         # Documentación detallada de las herramientas
├── operations/
│   ├── analytics.ts   # Operaciones de análisis de solicitudes API
│   ├── configuration.ts # Servicios, rutas, consumidores, plugins
│   └── controlPlanes.ts # Gestión del plano de control
└── types.ts           # Definiciones de tipos genéricos

Requisitos del Sistema

• Node.js 20 o superior
• Cuenta de Kong Konnect con acceso a la API
• Cliente compatible con MCP (como Claude Desktop, Cursor, etc.)

Instalación y Configuración

1. Clonar e Instalar

# Clonar el repositorio
git clone https://github.com/Kong/mcp-konnect.git
cd mcp-konnect

# Instalar dependencias
npm install

# Construir el proyecto
npm run build

2. Configuración del Entorno

Configure las siguientes variables de entorno para configurar el servidor MCP:

# Requerido: Su clave API de Kong Konnect
export KONNECT_ACCESS_TOKEN=kpat_api_key_here

# Opcional: Región de la API a utilizar (por defecto US)
# Valores posibles: US, EU, AU, ME, IN
export KONNECT_REGION=us

Herramientas Disponibles

Herramientas de Análisis

1. Análisis de Solicitudes API (analyze-api-requests)

Consulta y analiza las solicitudes de la puerta de enlace API de Kong, con soporte para filtros personalizados.

Parámetros de Entrada:

• timeRange: Rango de tiempo para la recuperación de datos (15M, 1H, 6H, 12H, 24H, 7D)
• statusCodes: Filtrar por códigos de estado HTTP específicos
• excludeStatusCodes: Excluir códigos de estado HTTP específicos
• httpMethods: Filtrar por métodos HTTP
• consumerIds: Filtrar por ID de consumidor
• serviceIds: Filtrar por ID de servicio
• routeIds: Filtrar por ID de ruta
• maxResults: Número máximo de resultados a devolver

2. Análisis de Solicitudes de Consumidor (analyze-consumer-requests)

Analiza las solicitudes API realizadas por un consumidor específico.

Parámetros de Entrada:

• consumerId: ID del consumidor a analizar
• timeRange: Rango de tiempo para la recuperación de datos
• successOnly: Mostrar solo las solicitudes exitosas (2xx)
• failureOnly: Mostrar solo las solicitudes fallidas (no 2xx)
• maxResults: Número máximo de resultados a devolver

Herramientas de Configuración

1. Listar Servicios (list-services)

Lista todos los servicios asociados con un plano de control.

Parámetros de Entrada:

• controlPlaneId: ID del plano de control
• size: Número de servicios a devolver
• offset: Token de desplazamiento para la paginación

2. Listar Rutas (list-routes)

Lista todas las rutas asociadas con un plano de control.

3. Listar Consumidores (list-consumers)

Lista todos los consumidores asociados con un plano de control.

4. Listar Plugins (list-plugins)

Lista todos los plugins asociados con un plano de control.

Herramientas de Gestión del Plano de Control

1. Listar Planos de Control (list-control-planes)

Lista todos los planos de control en la organización.

Parámetros de Entrada:

• pageSize: Número de planos de control por página
• pageNumber: Número de página a recuperar
• filterName: Filtrar planos de control por nombre
• filterClusterType: Filtrar por tipo de clúster
• filterCloudGateway: Filtrar por funcionalidad de puerta de enlace en la nube
• labels: Filtrar por etiquetas
• sort: Campo y dirección de ordenación

2. Obtener Plano de Control (get-control-plane)

Obtiene los detalles de un plano de control específico.

3. Listar Miembros del Grupo del Plano de Control (list-control-plane-group-members)

Lista todos los miembros del plano de control para un grupo específico.

4. Comprobar la Pertenencia al Grupo del Plano de Control (check-control-plane-group-membership)

Comprueba si un plano de control es miembro de algún grupo.

Uso con la Integración de Claude

1. Instalar Claude for Desktop

Descargue e instale Claude for Desktop desde Sitio web de Claude.

2. Configurar Claude Desktop

Cree o edite el archivo de configuración de Claude Desktop:

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

3. Añadir Configuración

{
  "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. Reiniciar Claude for Desktop

Después de reiniciar, las herramientas de Kong Konnect estarán disponibles para su uso con Claude.

Ejemplos de Flujos de Trabajo

1. Listar Todos los Planos de Control

Por favor, lista todos los planos de control en mi organización de Kong Konnect.

2. Listar Servicios para un Plano de Control Específico

Lista todos los servicios para el plano de control [CONTROL_PLANE_NAME/ID].

3. Consultar Solicitudes API para un Servicio Específico

Muéstrame todas las solicitudes API con códigos de estado 5xx para el servicio [SERVICE_NAME/ID] en la última hora.

4. Listar Consumidores para un Plano de Control

Lista todos los consumidores para el plano de control [CONTROL_PLANE_NAME/ID].

5. Analizar Solicitudes para un Consumidor Específico

Muéstrame todas las solicitudes realizadas por el consumidor [CONSUMER_NAME/ID] en las últimas 24 horas.

6. Comprobar Errores o Patrones Comunes

¿Cuáles son los errores más comunes que está experimentando este consumidor?

Guía de Desarrollo

Para añadir una nueva herramienta, siga estos pasos:

1. Defina los parámetros en parameters.ts
2. Añada documentación en prompts.ts
3. Cree la lógica de la operación en el archivo apropiado en operations/
4. Registre la herramienta en tools.ts
5. Maneje la ejecución de la herramienta en index.ts

Resolución de Problemas

Errores de Conexión

• Verifique que su clave API sea válida y tenga los permisos necesarios
• Compruebe que la región de la API esté especificada correctamente
• Asegúrese de que su red pueda conectarse a la API de Kong Konnect

Errores de Autenticación

• Vuelva a generar su clave API en el portal de Kong Konnect
• Compruebe que las variables de entorno estén configuradas correctamente

Datos No Encontrados

• Verifique que los ID utilizados en la solicitud sean correctos
• Compruebe que el recurso exista en el plano de control especificado
• Asegúrese de que el rango de tiempo para la consulta de análisis sea válido

Resumen

Kong MCP-Konnect es una herramienta poderosa que cierra la brecha entre los asistentes de IA y la gestión de la puerta de enlace API de Kong. Al proporcionar una interfaz de lenguaje natural para consultar y analizar la configuración, el tráfico y los datos analíticos de la puerta de enlace API, hace que la gestión de la API sea más intuitiva y eficiente. El proyecto ofrece un rico conjunto de características, desde consultas de configuración básicas hasta análisis de tráfico avanzados, y es una herramienta importante para la gestión moderna de la infraestructura API.