Introdução Detalhada ao Projeto Kong MCP-Konnect

Visão Geral do Projeto

Kong MCP-Konnect é um projeto de servidor baseado no Protocolo de Contexto de Modelo (Model Context Protocol, MCP) que permite que assistentes de IA consultem e analisem a configuração, o tráfego e os dados analíticos do Kong Gateway. Este projeto permite que assistentes de IA como o Claude interajam com o gateway de API do Kong Konnect através de linguagem natural.

Principais Características

• Consulta de Análise de Requisições de API: Suporte para filtros personalizados na análise de requisições de API.
• Gestão de Configuração do Gateway: Listar e inspecionar serviços, rotas, consumidores e plugins do gateway.
• Gestão do Plano de Controle: Gerenciar planos de controle e grupos de planos de controle.
• Integração com Assistentes de IA: Integração com Claude e outros assistentes de IA compatíveis com MCP.

Estrutura do Projeto

src/
├── index.ts            # Ponto de entrada principal
├── api.ts             # Cliente da API Kong
├── tools.ts           # Definições de ferramentas
├── parameters.ts      # Esquemas Zod para parâmetros de ferramentas
├── prompts.ts         # Documentação detalhada das ferramentas
├── operations/
│   ├── analytics.ts   # Operações de análise de requisições de API
│   ├── configuration.ts # Serviços, rotas, consumidores, plugins
│   └── controlPlanes.ts # Gestão do plano de controle
└── types.ts           # Definições de tipos genéricos

Requisitos do Sistema

• Node.js 20 ou superior
• Conta Kong Konnect com acesso à API
• Cliente com suporte para MCP (como Claude Desktop, Cursor, etc.)

Instalação e Configuração

1. Clonar e Instalar

# Clonar o repositório
git clone https://github.com/Kong/mcp-konnect.git
cd mcp-konnect

# Instalar dependências
npm install

# Construir o projeto
npm run build

2. Configuração do Ambiente

Defina as seguintes variáveis de ambiente para configurar o servidor MCP:

# Obrigatório: Sua chave de API do Kong Konnect
export KONNECT_ACCESS_TOKEN=kpat_api_key_here

# Opcional: Região da API a ser usada (padrão é US)
# Valores possíveis: US, EU, AU, ME, IN
export KONNECT_REGION=us

Ferramentas Disponíveis

Ferramentas de Análise

1. Análise de Requisições de API (analyze-api-requests)

Consultar e analisar requisições do Kong API Gateway, suportando filtros personalizados.

Parâmetros de Entrada:

• timeRange: Intervalo de tempo para recuperação de dados (15M, 1H, 6H, 12H, 24H, 7D)
• statusCodes: Filtrar por códigos de status HTTP específicos
• excludeStatusCodes: Excluir códigos de status HTTP específicos
• httpMethods: Filtrar por métodos HTTP
• consumerIds: Filtrar por IDs de consumidores
• serviceIds: Filtrar por IDs de serviços
• routeIds: Filtrar por IDs de rotas
• maxResults: Número máximo de resultados a serem retornados

2. Análise de Requisições de Consumidor (analyze-consumer-requests)

Analisar requisições de API feitas por um consumidor específico.

Parâmetros de Entrada:

• consumerId: ID do consumidor a ser analisado
• timeRange: Intervalo de tempo para recuperação de dados
• successOnly: Mostrar apenas requisições bem-sucedidas (2xx)
• failureOnly: Mostrar apenas requisições com falha (não 2xx)
• maxResults: Número máximo de resultados a serem retornados

Ferramentas de Configuração

1. Listar Serviços (list-services)

Listar todos os serviços associados a um plano de controle.

Parâmetros de Entrada:

• controlPlaneId: ID do plano de controle
• size: Número de serviços a serem retornados
• offset: Token de deslocamento para paginação

2. Listar Rotas (list-routes)

Listar todas as rotas associadas a um plano de controle.

3. Listar Consumidores (list-consumers)

Listar todos os consumidores associados a um plano de controle.

4. Listar Plugins (list-plugins)

Listar todos os plugins associados a um plano de controle.

Ferramentas de Gestão do Plano de Controle

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

Listar todos os planos de controle na organização.

Parâmetros de Entrada:

• pageSize: Número de planos de controle por página
• pageNumber: Número da página a ser recuperada
• filterName: Filtrar planos de controle por nome
• filterClusterType: Filtrar por tipo de cluster
• filterCloudGateway: Filtrar por funcionalidade de gateway na nuvem
• labels: Filtrar por rótulos
• sort: Campo e direção para ordenação

2. Obter Plano de Controle (get-control-plane)

Obter detalhes de um plano de controle específico.

3. Listar Membros do Grupo do Plano de Controle (list-control-plane-group-members)

Listar todos os membros do plano de controle para um grupo específico.

4. Verificar Associação ao Grupo do Plano de Controle (check-control-plane-group-membership)

Verificar se um plano de controle é membro de algum grupo.

Usando com Integração com Claude

1. Instalar Claude for Desktop

Baixe e instale o Claude for Desktop do site oficial do Claude.

2. Configurar Claude Desktop

Crie ou edite o arquivo de configuração do Claude Desktop:

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

3. Adicionar Configuração

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

Após reiniciar, as ferramentas Kong Konnect estarão disponíveis para uso no Claude.

Exemplos de Fluxo de Trabalho

1. Listar Todos os Planos de Controle

Por favor, liste todos os planos de controle na minha organização Kong Konnect.

2. Listar Serviços de um Plano de Controle Específico

Liste todos os serviços do plano de controle [CONTROL_PLANE_NAME/ID].

3. Consultar Requisições de API para um Serviço Específico

Mostre-me todas as requisições de API com códigos de status 5xx para o serviço [SERVICE_NAME/ID] na última hora.

4. Listar Consumidores de um Plano de Controle

Liste todos os consumidores do plano de controle [CONTROL_PLANE_NAME/ID].

5. Analisar Requisições de um Consumidor Específico

Mostre-me todas as requisições feitas pelo consumidor [CONSUMER_NAME/ID] nas últimas 24 horas.

6. Verificar Erros ou Padrões Comuns

Quais são os erros mais comuns que este consumidor está encontrando?

Guia de Desenvolvimento

Para adicionar uma nova ferramenta, siga estes passos:

1. Defina os parâmetros em parameters.ts
2. Adicione a documentação em prompts.ts
3. Crie a lógica da operação no arquivo apropriado em operations/
4. Registre a ferramenta em tools.ts
5. Lide com a execução da ferramenta em index.ts

Resolução de Problemas

Erros de Conexão

• Verifique se sua chave de API é válida e tem as permissões necessárias
• Verifique se a região da API está especificada corretamente
• Certifique-se de que sua rede pode se conectar à API Kong Konnect

Erros de Autenticação

• Regere sua chave de API no portal Kong Konnect
• Verifique se as variáveis de ambiente estão configuradas corretamente

Dados Não Encontrados

• Verifique se os IDs usados nas requisições estão corretos
• Verifique se o recurso existe no plano de controle especificado
• Certifique-se de que o intervalo de tempo para a consulta de análise é válido

Resumo

Kong MCP-Konnect é uma ferramenta poderosa que preenche a lacuna entre assistentes de IA e a gestão do Kong API Gateway. Ao fornecer uma interface de linguagem natural para consultar e analisar a configuração, o tráfego e os dados analíticos do gateway de API, torna a gestão da API mais intuitiva e eficiente. O projeto oferece um rico conjunto de funcionalidades, desde consultas básicas de configuração até análises avançadas de tráfego, sendo uma ferramenta importante para a gestão moderna de infraestruturas de API.