AKS-MCP

Ferramenta: call_az (padrão, disponível quando USE_LEGACY_TOOLS não está definido ou está definido como false)

Ferramenta unificada para executar comandos da Azure CLI diretamente. Esta ferramenta fornece uma interface flexível para executar qualquer comando da Azure CLI.

Parâmetros:

• cli_command: O comando completo da Azure CLI a ser executado (por exemplo, az aks list --resource-group myRG, az vm list --subscription <sub-id>)
• timeout: Tempo limite opcional em segundos (padrão: 120)

Exemplo de uso:

{
  "cli_command": "az aks list --resource-group myResourceGroup --output json"
}

Controle de acesso:

• readonly: Apenas operações de leitura são permitidas
• readwrite/admin: Operações de leitura e gravação são permitidas

Importante: Os comandos devem ser invocações simples da Azure CLI, sem recursos de shell como pipes (|), redirecionamentos (>, <), substituição de comandos ou ponto e vírgula (;).

Ferramenta: az_aks_operations (disponível quando USE_LEGACY_TOOLS=true)

Ferramenta unificada para gerenciar clusters do Azure Kubernetes Service (AKS) e operações relacionadas.

Operações disponíveis:

• Somente leitura (todos os níveis de acesso):

  • show: Mostrar detalhes do cluster
  • list: Listar clusters na assinatura/grupo de recursos
  • get-versions: Obter versões disponíveis do Kubernetes
  • check-network: Realizar verificação de conectividade de rede de saída
  • nodepool-list: Listar pools de nós no cluster
  • nodepool-show: Mostrar detalhes do pool de nós
  • account-list: Listar assinaturas do Azure

• Leitura-gravação (níveis de acesso readwrite/admin):

  • create: Criar novo cluster
  • delete: Excluir cluster
  • scale: Dimensionar contagem de nós do cluster
  • start: Iniciar um cluster parado
  • stop: Parar um cluster em execução
  • update: Atualizar configuração do cluster
  • upgrade: Atualizar versão do Kubernetes
  • nodepool-add: Adicionar pool de nós ao cluster
  • nodepool-delete: Excluir pool de nós
  • nodepool-scale: Dimensionar pool de nós
  • nodepool-upgrade: Atualizar pool de nós
  • account-set: Definir assinatura ativa
  • login: Autenticação do Azure

• Somente administrador (nível de acesso admin):

  • get-credentials: Obter credenciais do cluster para acesso kubectl

Ferramenta: aks_network_resources

Ferramenta unificada para obter informações de recursos de rede do Azure usados por clusters AKS.

Tipos de recursos disponíveis:

• all: Obter informações sobre todos os recursos de rede
• vnet: Informações da Virtual Network
• subnet: Informações da Subnet
• nsg: Informações do Network Security Group
• route_table: Informações da Route Table
• load_balancer: Informações do Load Balancer
• private_endpoint: Informações do private endpoint

Ferramenta: aks_monitoring

Ferramenta unificada para operações de monitoramento e diagnóstico do Azure para clusters AKS.

Operações disponíveis:

• metrics: Listar valores de métricas para recursos
• resource_health: Recuperar eventos de integridade de recursos para clusters AKS
• app_insights: Executar consultas KQL contra dados de telemetria do Application Insights
• diagnostics: Verificar se o cluster AKS tem configurações de diagnóstico definidas
• control_plane_logs: Consultar logs do plano de controle do AKS com restrições de segurança e validação de intervalo de tempo

Ferramenta: get_aks_vmss_info

• Obter configuração detalhada do VMSS para pools de nós no cluster AKS

Ferramenta: collect_aks_node_logs

Coletar logs do sistema de nós VMSS do AKS para depuração e solução de problemas.

Parâmetros:

• aks_resource_id: ID do recurso do cluster AKS
• vmss_name: Nome do VMSS (obter de get_aks_vmss_info ou kubectl get nodes)
• instance_id: ID da instância do VMSS
• log_type: Tipo de logs a coletar (kubelet, containerd, kernel, syslog)
• lines: Número de linhas de log recentes a retornar (padrão: 500, máximo: 2000)
• since: Intervalo de tempo para logs (por exemplo, 1h, 30m, 2d) - tem precedência sobre lines
• level: Filtro de nível de log (ERROR, WARN, INFO)
• filter: Filtrar logs por palavra-chave (correspondência de texto sem diferenciar maiúsculas de minúsculas)

Exemplo de uso:

{
  "aks_resource_id": "/subscriptions/.../managedClusters/myAKS",
  "vmss_name": "aks-nodepool1-12345678-vmss",
  "instance_id": "0",
  "log_type": "kubelet",
  "since": "1h",
  "level": "ERROR",
  "filter": "ImagePullBackOff"
}

Limitações:

• Suporta apenas nós VMSS Linux (nós Windows e VMs autônomas ainda não são suportados)
• Apenas um comando de execução pode ser executado por vez por instância do VMSS

Ferramenta: az_compute_operations Ferramenta unificada para gerenciar Azure Virtual Machines (VMs) e Virtual Machine Scale Sets (VMSS) usados pelo AKS.

Operações disponíveis:

• show: Obter detalhes de uma VM/VMSS
• list: Listar VMs/VMSS na assinatura ou grupo de recursos
• get-instance-view: Obter status de tempo de execução
• start: Iniciar VM
• stop: Parar VM
• restart: Reiniciar instâncias de VM/VMSS
• reimage: Reimagear instâncias de VMSS (VM não suporta reimage)

Tipos de recursos: vm (máquinas virtuais individuais), vmss (conjuntos de escala de máquinas virtuais)

Ferramenta: az_fleet

Gerenciamento abrangente de frota do Azure para cenários de múltiplos clusters.

Operações disponíveis:

• Operações de Frota: listar, mostrar, criar, atualizar, excluir, obter credenciais
• Operações de Membro: listar, mostrar, criar, atualizar, excluir
• Operações de Execução de Atualização: listar, mostrar, criar, iniciar, parar, excluir
• Operações de Estratégia de Atualização: listar, mostrar, criar, excluir
• Operações de ClusterResourcePlacement: listar, mostrar, obter, criar, excluir

Suporta operações de gerenciamento de frota do Azure e operações de CRD do Kubernetes ClusterResourcePlacement.

Ferramenta: aks_detector

Ferramenta unificada para executar operações de detectores de diagnóstico do AKS.

Operações disponíveis:

• list: Listar todos os detectores de cluster AKS disponíveis
• run: Executar um detector de diagnóstico específico do AKS
• run_by_category: Executar todos os detectores em uma categoria específica

Parâmetros:

• operation (obrigatório): Operação a ser executada (list, run ou run_by_category)
• aks_resource_id (obrigatório): ID do recurso do cluster AKS
• detector_name (obrigatório para a operação run): Nome do detector a ser executado
• category (obrigatório para a operação run_by_category): Categoria do detector
• start_time (obrigatório para as operações run e run_by_category): Hora de início no formato ISO UTC (dentro dos últimos 30 dias)
• end_time (obrigatório para as operações run e run_by_category): Hora de término no formato ISO UTC (dentro dos últimos 30 dias, máximo 24h a partir do início)

Categorias disponíveis:

• Melhores Práticas
• Disponibilidade e Desempenho do Cluster e do Plano de Controle
• Problemas de Conectividade
• Criar, Atualizar, Excluir e Escalar
• Depreciações
• Identidade e Segurança
• Saúde do Nó
• Armazenamento

Exemplo de uso:

{
  "operation": "list",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx"
}

{
  "operation": "run",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx",
  "detector_name": "node-health-detector",
  "start_time": "2025-01-15T10:00:00Z",
  "end_time": "2025-01-15T12:00:00Z"
}

Ferramenta: aks_advisor_recommendation

Recuperar e gerenciar recomendações do Azure Advisor para clusters AKS.

Operações disponíveis:

• list: Listar recomendações com opções de filtro
• report: Gerar relatórios de recomendações
• Opções de Filtro: resource_group, cluster_names, categoria (Custo, Alta Disponibilidade, Desempenho, Segurança), severidade (Alta, Média, Baixa)

Nota: Todas as ferramentas do Kubernetes (kubectl, helm, cilium, hubble) estão habilitadas por padrão. Use --enabled-components para habilitar seletivamente componentes específicos.

Ferramenta kubectl Unificada (Padrão)

Ferramenta: call_kubectl (padrão, disponível quando USE_LEGACY_TOOLS não está definido ou definido como false)

Ferramenta unificada para executar comandos kubectl diretamente. Esta ferramenta fornece uma interface flexível para executar qualquer comando kubectl com suporte completo a argumentos.

Parâmetros:

• args: Os argumentos do comando kubectl (por exemplo, get pods, describe node mynode, apply -f deployment.yaml)

Exemplo de uso:

{
  "args": "get pods -n kube-system -o wide"
}

Controle de Acesso: As operações são restritas com base no nível de acesso configurado:

• somente leitura: Apenas operações de leitura (get, describe, logs, etc.) são permitidas
• leitura/escrita/admin: Todas as operações, incluindo comandos de mutação (create, delete, apply, etc.)

Ferramentas kubectl Legadas (Especializadas)

Disponíveis quando USE_LEGACY_TOOLS=true:

• Somente Leitura (todos os níveis de acesso):

  • kubectl_resources: Visualizar recursos (get, describe) - filtrado para operações somente leitura no modo somente leitura
  • kubectl_diagnostics: Depurar e diagnosticar (logs, events, top, exec, cp)
  • kubectl_cluster: Informações do cluster (cluster-info, api-resources, api-versions, explain)
  • kubectl_config: Gerenciamento de configuração (diff, auth, config) - filtrado para operações somente leitura no modo somente leitura

• Leitura/Escrita/Admin (níveis de acesso readwrite/admin):

  • kubectl_resources: Gerenciamento completo de recursos (get, describe, create, delete, apply, patch, replace, cordon, uncordon, drain, taint)
  • kubectl_workloads: Ciclo de vida de cargas de trabalho (run, expose, scale, autoscale, rollout)
  • kubectl_metadata: Gerenciamento de metadados (label, annotate, set)
  • kubectl_config: Gerenciamento completo de configuração (diff, auth, certificate, config)

Helm

Ferramenta: call_helm

Gerenciador de pacotes Helm para Kubernetes.

Cilium

Ferramenta: call_cilium

CLI do Cilium para rede e segurança baseadas em eBPF.

Hubble

Ferramenta: call_hubble

Observabilidade de rede do Hubble para Cilium.

Ferramenta: inspektor_gadget_observability

Ferramenta de observabilidade em tempo real para clusters do Azure Kubernetes Service (AKS) usando eBPF.

Ações disponíveis:

• deploy: Implantar o Inspektor Gadget no cluster (via extensão de cluster do AKS)
• undeploy: Remover a extensão de cluster do Inspektor Gadget do cluster
• is_deployed: Verificar status da implantação
• run: Executar gadgets de uso único
• start: Iniciar gadgets contínuos
• stop: Parar gadgets em execução
• get_results: Recuperar resultados de gadgets
• list_gadgets: Listar gadgets disponíveis

Gadgets disponíveis:

• observe_dns: Monitorar solicitações e respostas de DNS
• observe_tcp: Monitorar conexões TCP
• observe_file_open: Monitorar operações do sistema de arquivos
• observe_process_execution: Monitorar execução de processos
• observe_signal: Monitorar entrega de sinais
• observe_system_calls: Monitorar chamadas de sistema
• top_file: Principais arquivos por operações de I/O
• top_tcp: Principais conexões TCP por tráfego
• tcpdump: Capturar pacotes de rede

A maneira mais fácil de começar com o AKS-MCP é através da Extensão do Azure Kubernetes Service para VS Code.

Passo 1: Instale a Extensão do AKS

1. Abra o VS Code e vá para Extensões (Ctrl+Shift+X no Windows/Linux ou Cmd+Shift+X no macOS).
2. Pesquise por Azure Kubernetes Service.
3. Instale a extensão oficial do AKS da Microsoft.

Passo 2: Inicie o Servidor AKS-MCP

1. Abra a Paleta de Comandos (Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no macOS).
2. Pesquise e execute: AKS: Configurar Servidor MCP do AKS.

Após a instalação bem-sucedida, o servidor agora estará visível em MCP: Listar Servidores (via Paleta de Comandos). A partir daí, você pode iniciar o servidor MCP ou visualizar seu status.

Passo 3: Comece a Usar o AKS-MCP

Uma vez iniciado, o servidor MCP aparecerá no menu suspenso Copilot Chat: Configurar Ferramentas sob MCP Server: AKS MCP, pronto para aprimorar prompts contextuais com base no seu ambiente AKS. Por padrão, todas as ferramentas do servidor AKS-MCP estão habilitadas. Você pode revisar a lista de ferramentas disponíveis e desabilitar qualquer uma que não seja necessária para o seu cenário específico.

Experimente um prompt como "Listar todos os meus clusters AKS", que começará a usar ferramentas do servidor AKS-MCP.

Configuração do WSL

A configuração do MCP difere dependendo se o VS Code está rodando no Windows ou dentro do WSL:

🪟 Host Windows (VS Code no Windows): Use "command": "wsl" para invocar o binário WSL a partir do Windows:

{
  "servers": {
    "aks-mcp": {
      "type": "stdio",
      "command": "wsl",
      "args": [
        "--",
        "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp"
      ]
    }
  }
}

🐧 Remote-WSL (VS Code rodando dentro do WSL): Chame o binário diretamente ou use um wrapper de shell:

{
  "servers": {
    "aks-mcp": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp"
      ]
    }
  }
}

🔧 Solução de Problemas de Erros ENOENT

Se você vir erros "spawn ENOENT", verifique seu ambiente VS Code:

• Host Windows: Verifique se o caminho do binário WSL está correto e acessível via wsl -- ls /path/to/aks-mcp
• Remote-WSL: NÃO use "command": "wsl" - use caminhos diretos ou wrapper bash como mostrado acima

Passo 1: Baixe o Binário

Escolha sua plataforma e baixe o binário mais recente do AKS-MCP:

Passo 2: Configure o VS Code

Após o download, crie um arquivo .vscode/mcp.json na raiz do seu workspace com o caminho para o binário baixado.

Opção A: Script de Configuração Automatizado

Para configuração rápida, você pode usar estes scripts de uma linha que baixam o binário e criam a configuração:

Windows (PowerShell):

# Download binary and create VS Code configuration
mkdir -p .vscode ; Invoke-WebRequest -Uri "https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-amd64.exe" -OutFile "aks-mcp.exe" ; @{servers=@{"aks-mcp-server"=@{type="stdio";command="$PWD\aks-mcp.exe";args=@()}}} | ConvertTo-Json -Depth 3 | Out-File ".vscode/mcp.json" -Encoding UTF8

macOS/Linux (Bash):

# Download binary and create VS Code configuration
mkdir -p .vscode && curl -sL https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-amd64 -o aks-mcp && chmod +x aks-mcp && echo '{"servers":{"aks-mcp-server":{"type":"stdio","command":"'$PWD'/aks-mcp","args":[]}}}' > .vscode/mcp.json

Opção B: Configuração Manual

✨ Configuração Simples: Baixe o binário para sua plataforma e use a configuração manual abaixo para configurar o servidor MCP no VS Code.

Configuração Manual do VS Code

Você pode configurar o servidor AKS-MCP de duas maneiras:

1. Configuração específica do workspace (recomendada para uso específico do projeto):

Crie um arquivo .vscode/mcp.json no seu workspace com o caminho para o binário baixado:

{
  "servers": {
    "aks-mcp-server": {
      "type": "stdio",
      "command": "<enter the file path>",
      "args": []
    }
  }
}

2. Configuração no nível do usuário (persistente em todos os workspaces):

Para uma configuração persistente que funcione em todos os seus workspaces do VS Code, adicione o servidor MCP às configurações de usuário do VS Code:

1. Abra as Configurações do VS Code (Ctrl+, ou Cmd+,)
2. Pesquise por "mcp" nas configurações
3. Adicione o seguinte ao JSON de Configurações do Usuário:

{
  "github.copilot.chat.mcp.servers": {
    "aks-mcp-server": {
      "type": "stdio",
      "command": "<enter the file path>",
      "args": []
    }
  }
}

Passo 3: Carregue as ferramentas do servidor AKS-MCP no GitHub Copilot

1. Se estiver rodando em uma versão mais antiga do VS Code: reinicie o VS Code, ou seja, feche e reabra o VS Code para carregar a nova configuração do servidor MCP.
2. Abra o GitHub Copilot no VS Code e mude para o modo Agente
3. Clique no botão Ferramentas ou execute /list na janela do GitHub Copilot para ver a lista de ferramentas disponíveis
4. Você deve ver as ferramentas do AKS-MCP na lista
5. Experimente um prompt como: "Listar todos os meus clusters AKS na assinatura xxx"
6. O agente usará automaticamente as ferramentas do AKS-MCP para concluir sua solicitação

💡 Dica: Se você não vir as ferramentas do AKS-MCP após reiniciar, verifique o painel de saída do VS Code para erros de conexão do servidor MCP e verifique o caminho do binário em .vscode/mcp.json.

Nota: Certifique-se de ter autenticado com o Azure CLI (az login) para que o servidor acesse seus recursos do Azure.

Para outros clientes de IA compatíveis com MCP, como Claude Desktop ou GitHub Copilot CLI, configure o servidor na sua configuração MCP:

{
  "mcpServers": {
    "aks": {
      "command": "<path of binary aks-mcp>",
      "args": []
    }
  }
}

🤖 Instalação em Cliente MCP Personalizado

Você pode configurar qualquer cliente compatível com MCP para usar o servidor AKS-MCP executando o binário diretamente:

# Run the server directly
./aks-mcp

🔧 Instalação Manual do Binário

Para uso direto do binário sem gerenciadores de pacotes:

1. Baixe a versão mais recente na página de releases
2. Extraia o binário para o local de sua preferência
3. Torne-o executável (em sistemas Unix):

   chmod +x aks-mcp
   

4. Configure seu cliente MCP para usar o caminho do binário