MKP

Servidor do Model Kontext Protocol para Kubernetes que permite que aplicações baseadas em LLM interajam com clusters Kubernetes por meio de implementação nativa em Go, com integração direta de API e gerenciamento abrangente de recursos.

GitHub
59
Experimente este MCPPatrocinado

Documentação

MKP - Servidor de Protocolo de Contexto de Modelo para Kubernetes

MKP Logo

O MKP é um servidor de Protocolo de Contexto de Modelo (MCP) para Kubernetes que permite que aplicações alimentadas por LLM interajam com clusters Kubernetes. Ele fornece ferramentas para listar e aplicar recursos Kubernetes através do protocolo MCP.

Recursos

  • Listar recursos suportados pelo servidor de API do Kubernetes
  • Listar recursos de cluster
  • Listar recursos por namespace
  • Obter recursos e seus subrecursos (incluindo status, scale, logs, etc.)
  • Aplicar (criar ou atualizar) recursos de cluster
  • Aplicar (criar ou atualizar) recursos por namespace
  • Executar comandos em pods com controle de tempo limite
  • Implementação genérica e plugável usando o cliente não estruturado do API Machinery
  • Limitação de taxa integrada para proteção contra chamadas excessivas de API

Por que MKP?

O MKP oferece várias vantagens principais como um servidor de Protocolo de Contexto de Modelo para Kubernetes:

Implementação Nativa em Go

  • Construído com a mesma linguagem do próprio Kubernetes
  • Excelentes características de desempenho para aplicações de servidor
  • Forte segurança de tipos e suporte a concorrência
  • Integração perfeita com bibliotecas Kubernetes

Integração Direta com API

  • Usa o API machinery do Kubernetes diretamente, sem dependências externas
  • Sem dependência de kubectl, helm ou outras ferramentas de CLI
  • Comunica-se diretamente com o servidor de API do Kubernetes
  • Menos sobrecarga e maior confiabilidade

Suporte Universal a Recursos

  • Funciona com qualquer tipo de recurso Kubernetes através do cliente não estruturado
  • Sem esquemas de recursos codificados ou manipuladores especializados
  • Suporta automaticamente Definições de Recursos Personalizados (CRDs)
  • À prova de futuro para novos recursos Kubernetes

Design Minimalista

  • Focado em operações essenciais de recursos Kubernetes
  • Código limpo e de fácil manutenção com clara separação de responsabilidades
  • Leve com dependências mínimas
  • Fácil de entender, estender e contribuir

Arquitetura Pronta para Produção

  • Projetado para confiabilidade e desempenho em ambientes de produção
  • Tratamento adequado de erros e gerenciamento de recursos
  • Limitação de taxa integrada para proteção contra chamadas excessivas de API
  • Design testável com testes unitários abrangentes
  • Segue as melhores práticas de desenvolvimento do Kubernetes

Pré-requisitos

  • Go 1.24 ou posterior
  • Cluster Kubernetes e kubeconfig
  • Task para executar tarefas

Instalação

  1. Clone o repositório:

    git clone https://github.com/StacklokLabs/mkp.git
cd mkp

  2. Instale as dependências:

    task install

  3. Compile o servidor:

    task build

Uso

Executando o servidor

Para executar o servidor com o kubeconfig padrão:

task run

Para executar o servidor com um kubeconfig específico:

KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig

Para executar o servidor em uma porta específica:

MCP_PORT=9091 task run

Executando com ToolHive

O MKP pode ser executado como um servidor de Protocolo de Contexto de Modelo (MCP) usando ToolHive, que simplifica a implantação e o gerenciamento de servidores MCP.

Consulte a documentação do ToolHive para instruções detalhadas sobre como configurar o MKP com a interface do ToolHive, CLI ou operador Kubernetes.

Ferramentas MCP

O servidor MKP fornece as seguintes ferramentas MCP:

get_resource

Obter um recurso Kubernetes ou seu subrecurso.

Parâmetros:

  • resource_type (obrigatório): Tipo de recurso a obter (cluster ou namespace)
  • group: Grupo de API (ex.: apps, networking.k8s.io)
  • version (obrigatório): Versão da API (ex.: v1, v1beta1)
  • resource (obrigatório): Nome do recurso (ex.: deployments, services)
  • namespace: Namespace (obrigatório para recursos por namespace)
  • name (obrigatório): Nome do recurso a obter
  • subresource: Subrecurso a obter (ex.: status, scale, logs)
  • parameters: Parâmetros opcionais para a solicitação (veja exemplos abaixo)

Exemplo:

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "name": "nginx-deployment",
    "subresource": "status"
  }
}

Exemplo de obtenção de logs de um contêiner específico com parâmetros:

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "logs",
    "parameters": {
      "container": "my-container",
      "sinceSeconds": "3600",
      "timestamps": "true",
      "limitBytes": "102400"
    }
  }
}

Parâmetros disponíveis para logs de pods:

  • container: Especificar de qual contêiner obter os logs
  • previous: Obter logs da instância anterior do contêiner (true/false)
  • sinceSeconds: Retornar apenas logs mais recentes que uma duração relativa em segundos
  • sinceTime: Retornar apenas logs após um horário específico (formato RFC3339)
  • timestamps: Incluir carimbos de data/hora em cada linha (true/false)
  • limitBytes: Número máximo de bytes a retornar
  • tailLines: Número de linhas a retornar do final dos logs

Por padrão, os logs de pods são limitados às últimas 100 linhas e 32KB para evitar sobrecarregar a janela de contexto do LLM. Esses padrões podem ser substituídos usando os parâmetros acima.

Parâmetros disponíveis para recursos regulares:

  • resourceVersion: Quando especificado, mostra o recurso naquela versão específica

list_resources

Lista recursos Kubernetes de um tipo específico.

Parâmetros:

  • resource_type (obrigatório): Tipo de recurso a listar (cluster ou namespace)
  • group: Grupo de API (ex.: apps, networking.k8s.io)
  • version (obrigatório): Versão da API (ex.: v1, v1beta1)
  • resource (obrigatório): Nome do recurso (ex.: deployments, services)
  • namespace: Namespace (obrigatório para recursos por namespace)
  • label_selector: Seletor de rótulos Kubernetes para filtrar recursos (opcional)
  • include_annotations: Se deve incluir anotações na saída (padrão: true)
  • exclude_annotation_keys: Lista de chaves de anotação a excluir da saída (suporta curingas com *)
  • include_annotation_keys: Lista de chaves de anotação a incluir na saída (se especificado, apenas estas são incluídas)
Filtragem de Anotações

A ferramenta list_resources fornece poderosos recursos de filtragem de anotações para controlar o tamanho da saída de metadados e evitar problemas de truncamento com anotações grandes (como anotações de nós GPU).

Uso Básico:

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default"
  }
}

Excluir anotações específicas (útil para nós GPU):

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "clustered",
    "group": "",
    "version": "v1",
    "resource": "nodes",
    "exclude_annotation_keys": [
      "nvidia.com/*",
      "kubectl.kubernetes.io/last-applied-configuration"
    ]
  }
}

Incluir apenas anotações específicas:

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotation_keys": ["app", "version", "prometheus.io/scrape"]
  }
}

Desabilitar anotações completamente para máximo desempenho:

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotations": false
  }
}

Regras de Filtragem de Anotações:

  • Por padrão, kubectl.kubernetes.io/last-applied-configuration é excluído para evitar grandes dados de configuração
  • exclude_annotation_keys suporta padrões curinga usando * (ex.: nvidia.com/* exclui todas as anotações NVIDIA)
  • Quando include_annotation_keys é especificado, ele tem precedência e apenas essas anotações são incluídas
  • Definir include_annotations: false remove completamente todas as anotações da saída
  • Padrões curinga suportam apenas * no final da chave (ex.: nvidia.com/*)

apply_resource

Aplica (cria ou atualiza) um recurso Kubernetes.

Parâmetros:

  • resource_type (obrigatório): Tipo de recurso a aplicar (cluster ou namespace)
  • group: Grupo de API (ex.: apps, networking.k8s.io)
  • version (obrigatório): Versão da API (ex.: v1, v1beta1)
  • resource (obrigatório): Nome do recurso (ex.: deployments, services)
  • namespace: Namespace (obrigatório para recursos por namespace)
  • manifest (obrigatório): Manifesto do recurso

Exemplo:

{
  "name": "apply_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "manifest": {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "nginx-deployment",
        "namespace": "default"
      },
      "spec": {
        "replicas": 3,
        "selector": {
          "matchLabels": {
            "app": "nginx"
          }
        },
        "template": {
          "metadata": {
            "labels": {
              "app": "nginx"
            }
          },
          "spec": {
            "containers": [
              {
                "name": "nginx",
                "image": "nginx:latest",
                "ports": [
                  {
                    "containerPort": 80
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

post_resource

Envia dados para um recurso Kubernetes ou seu subrecurso, particularmente útil para executar comandos em pods.

Parâmetros:

  • resource_type (obrigatório): Tipo de recurso para envio (cluster ou namespace)
  • group: Grupo de API (ex.: apps, networking.k8s.io)
  • version (obrigatório): Versão da API (ex.: v1, v1beta1)
  • resource (obrigatório): Nome do recurso (ex.: deployments, services)
  • namespace: Namespace (obrigatório para recursos por namespace)
  • name (obrigatório): Nome do recurso para envio
  • subresource: Subrecurso para envio (ex.: exec)
  • body (obrigatório): Corpo a enviar para o recurso
  • parameters: Parâmetros opcionais para a solicitação

Exemplo de execução de um comando em um pod:

{
  "name": "post_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "exec",
    "body": {
      "command": ["ls", "-la", "/"],
      "container": "my-container",
      "timeout": 30
    }
  }
}

O body para execução em pod suporta os seguintes campos:

  • command (obrigatório): Comando a executar, como uma string ou um array de strings
  • container (opcional): Nome do contêiner para executar o comando (padrão: o primeiro contêiner)
  • timeout (opcional): Tempo limite em segundos (padrão: 15 segundos, máximo 60 segundos)

Nota sobre tempos limite:

  • Tempo limite padrão: 15 segundos se não especificado
  • Tempo limite máximo: 60 segundos (qualquer valor maior será limitado)
  • Comandos que excedem o tempo limite serão encerrados e retornarão um erro de tempo limite

A resposta inclui stdout, stderr e qualquer mensagem de erro:

{
  "apiVersion": "v1",
  "kind": "Pod",
  "metadata": {
    "name": "my-pod",
    "namespace": "default"
  },
  "spec": {
    "command": ["ls", "-la", "/"]
  },
  "status": {
    "stdout": "total 48\ndrwxr-xr-x   1 root root 4096 May  5 14:30 .\ndrwxr-xr-x   1 root root 4096 May  5 14:30 ..\n...",
    "stderr": "",
    "error": ""
  }
}

Recursos MCP

O servidor MKP fornece acesso a recursos Kubernetes através de recursos MCP. Os URIs de recursos seguem estes formatos:

  • Recursos de cluster: k8s://clustered/{group}/{version}/{resource}/{name}
  • Recursos por namespace: k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}

Configuração

Protocolo de Transporte

O MKP suporta dois protocolos de transporte para o servidor MCP:

  • HTTP Streamable: O protocolo de transporte padrão, adequado para a maioria dos casos de uso
  • SSE (Server-Sent Events): Protocolo de transporte legado, principalmente para compatibilidade com clientes mais antigos

Você pode configurar o protocolo de transporte usando um sinalizador de CLI ou uma variável de ambiente:

# Using CLI flag
./build/mkp-server --transport=sse

# Using environment variable
MCP_TRANSPORT=sse ./build/mkp-server

# Default (Streamable HTTP)
./build/mkp-server

A variável de ambiente MCP_TRANSPORT é definida automaticamente pelo ToolHive ao executar o MKP nesse ambiente.

Controlando a Descoberta de Recursos

Por padrão, o MKP serve todos os recursos Kubernetes como recursos MCP, o que fornece contexto útil para LLMs. No entanto, em clusters grandes com muitos recursos, isso pode consumir espaço significativo de contexto no LLM.

Você pode desabilitar esse comportamento usando o sinalizador --serve-resources:

# Run without serving cluster resources
./build/mkp-server --serve-resources=false

# Run with a specific kubeconfig without serving cluster resources
./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false

Mesmo com a descoberta de recursos desabilitada, as ferramentas MCP (get_resource, list_resources, apply_resource, delete_resource e post_resource) permanecem totalmente funcionais, permitindo que você interaja com seu cluster Kubernetes.

Habilitando Operações de Escrita

Por padrão, o MKP opera em modo somente leitura, o que significa que não permite operações de escrita no cluster, ou seja, as ferramentas apply_resource, delete_resource e post_resource não estarão disponíveis. Você pode habilitar operações de escrita usando o sinalizador --read-write:

# Run with write operations enabled
./build/mkp-server --read-write=true

# Run with a specific kubeconfig and write operations enabled
./build/mkp-server --kubeconfig=/path/to/kubeconfig --read-write=true

Limitação de Taxa

O MKP inclui um mecanismo integrado de limitação de taxa para proteger o servidor de chamadas excessivas de API, o que é particularmente importante quando usado com agentes de IA. O limitador de taxa usa um algoritmo de balde de tokens e aplica limites diferentes com base no tipo de operação:

  • Operações de leitura (list_resources, get_resource): 120 solicitações por minuto
  • Operações de escrita (apply_resource, delete_resource): 30 solicitações por minuto
  • Padrão para outras operações: 60 solicitações por minuto

Os limites de taxa são aplicados por sessão de cliente, garantindo alocação justa de recursos entre múltiplos clientes. O recurso de limitação de taxa pode ser habilitado ou desabilitado através do sinalizador de linha de comando:

# Run with rate limiting enabled (default)
./build/mkp-server

# Run with rate limiting disabled
./build/mkp-server --enable-rate-limiting=false

Os limites de taxa podem ser personalizados através de variáveis de ambiente:

  • MKP_RATE_LIMIT_DEFAULT: Limite de taxa padrão (padrão: 60)
  • MKP_RATE_LIMIT_READ: Limite de taxa para operações de leitura (padrão: 120)
  • MKP_RATE_LIMIT_WRITE: Limite de taxa para operações de escrita (padrão: 30)
# Run with custom rate limits
MKP_RATE_LIMIT_READ=200 MKP_RATE_LIMIT_WRITE=50 ./build/mkp-server

Desenvolvimento

Executando testes

task test

Formatando código

task fmt

Verificando código com linter

task lint

Atualizando dependências

task deps

Contribuindo

Aceitamos contribuições para este servidor MCP! Se você gostaria de contribuir, por favor revise o guia de CONTRIBUIÇÃO para detalhes sobre como começar.

Se você encontrar um bug ou tiver uma solicitação de recurso, por favor abra uma issue no repositório ou junte-se a nós no canal #mcp-servers em nosso servidor comunitário no Discord.

Licença

Este projeto é licenciado sob a Licença Apache v2 - consulte o arquivo LICENSE para detalhes.