MKP

Servidor del Protocolo de Contexto de Modelo para Kubernetes que permite a aplicaciones impulsadas por LLM interactuar con clústeres de Kubernetes mediante una implementación nativa en Go con integración directa de API y gestión integral de recursos.

GitHub
59
Prueba este MCPPatrocinado

Documentación

MKP - Servidor de Protocolo de Contexto de Modelo para Kubernetes

MKP Logo

MKP es un servidor de Protocolo de Contexto de Modelo (MCP) para Kubernetes que permite a aplicaciones impulsadas por LLM interactuar con clústeres de Kubernetes. Proporciona herramientas para listar y aplicar recursos de Kubernetes a través del protocolo MCP.

Características

  • Listar recursos compatibles con el servidor de API de Kubernetes
  • Listar recursos agrupados
  • Listar recursos con espacio de nombres
  • Obtener recursos y sus subrecursos (incluyendo estado, escala, registros, etc.)
  • Aplicar (crear o actualizar) recursos agrupados
  • Aplicar (crear o actualizar) recursos con espacio de nombres
  • Ejecutar comandos en pods con control de tiempo de espera
  • Implementación genérica y conectable utilizando el cliente no estructurado de API Machinery
  • Limitación de velocidad integrada para protección contra llamadas excesivas a la API

¿Por qué MKP?

MKP ofrece varias ventajas clave como servidor de Protocolo de Contexto de Modelo para Kubernetes:

Implementación Nativa en Go

  • Construido con el mismo lenguaje que Kubernetes
  • Excelentes características de rendimiento para aplicaciones de servidor
  • Fuerte seguridad de tipos y soporte de concurrencia
  • Integración perfecta con las bibliotecas de Kubernetes

Integración Directa con la API

  • Utiliza la maquinaria de API de Kubernetes directamente sin dependencias externas
  • Sin dependencia de kubectl, helm u otras herramientas CLI
  • Se comunica directamente con el servidor de API de Kubernetes
  • Menos sobrecarga y mayor fiabilidad

Soporte Universal de Recursos

  • Funciona con cualquier tipo de recurso de Kubernetes a través del cliente no estructurado
  • No se necesitan esquemas de recursos codificados ni manejadores especializados
  • Soporta automáticamente Definiciones de Recursos Personalizados (CRDs)
  • A prueba de futuro para nuevos recursos de Kubernetes

Diseño Minimalista

  • Enfocado en operaciones básicas de recursos de Kubernetes
  • Código limpio y mantenible con clara separación de responsabilidades
  • Ligero con dependencias mínimas
  • Fácil de entender, extender y contribuir

Arquitectura Lista para Producción

  • Diseñado para fiabilidad y rendimiento en entornos de producción
  • Manejo adecuado de errores y gestión de recursos
  • Limitación de velocidad integrada para proteger contra llamadas excesivas a la API
  • Diseño comprobable con pruebas unitarias exhaustivas
  • Sigue las mejores prácticas de desarrollo de Kubernetes

Requisitos Previos

  • Go 1.24 o posterior
  • Clúster de Kubernetes y kubeconfig
  • Task para ejecutar tareas

Instalación

  1. Clonar el repositorio:

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

  2. Instalar dependencias:

    task install

  3. Compilar el servidor:

    task build

Uso

Ejecutar el servidor

Para ejecutar el servidor con el kubeconfig predeterminado:

task run

Para ejecutar el servidor con un kubeconfig específico:

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

Para ejecutar el servidor en un puerto específico:

MCP_PORT=9091 task run

Ejecutar con ToolHive

MKP se puede ejecutar como un servidor de Protocolo de Contexto de Modelo (MCP) usando ToolHive, que simplifica la implementación y gestión de servidores MCP.

Consulte la documentación de ToolHive para instrucciones detalladas sobre cómo configurar MKP con la interfaz de usuario, CLI o operador de Kubernetes de ToolHive.

Herramientas MCP

El servidor MKP proporciona las siguientes herramientas MCP:

get_resource

Obtener un recurso de Kubernetes o su subrecurso.

Parámetros:

  • resource_type (obligatorio): Tipo de recurso a obtener (agrupado o con espacio de nombres)
  • group: Grupo de API (por ejemplo, apps, networking.k8s.io)
  • version (obligatorio): Versión de API (por ejemplo, v1, v1beta1)
  • resource (obligatorio): Nombre del recurso (por ejemplo, deployments, services)
  • namespace: Espacio de nombres (obligatorio para recursos con espacio de nombres)
  • name (obligatorio): Nombre del recurso a obtener
  • subresource: Subrecurso a obtener (por ejemplo, status, scale, logs)
  • parameters: Parámetros opcionales para la solicitud (ver ejemplos a continuación)

Ejemplo:

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

Ejemplo de obtención de registros de un contenedor específico con 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 disponibles para registros de pods:

  • container: Especificar de qué contenedor obtener los registros
  • previous: Obtener registros de la instancia anterior del contenedor (verdadero/falso)
  • sinceSeconds: Devolver solo registros más recientes que una duración relativa en segundos
  • sinceTime: Devolver solo registros posteriores a un tiempo específico (formato RFC3339)
  • timestamps: Incluir marcas de tiempo en cada línea (verdadero/falso)
  • limitBytes: Número máximo de bytes a devolver
  • tailLines: Número de líneas a devolver desde el final de los registros

De forma predeterminada, los registros de pods se limitan a las últimas 100 líneas y 32KB para evitar abrumar la ventana de contexto del LLM. Estos valores predeterminados se pueden anular usando los parámetros anteriores.

Parámetros disponibles para recursos regulares:

  • resourceVersion: Cuando se especifica, muestra el recurso en esa versión particular

list_resources

Lista recursos de Kubernetes de un tipo específico.

Parámetros:

  • resource_type (obligatorio): Tipo de recurso a listar (agrupado o con espacio de nombres)
  • group: Grupo de API (por ejemplo, apps, networking.k8s.io)
  • version (obligatorio): Versión de API (por ejemplo, v1, v1beta1)
  • resource (obligatorio): Nombre del recurso (por ejemplo, deployments, services)
  • namespace: Espacio de nombres (obligatorio para recursos con espacio de nombres)
  • label_selector: Selector de etiquetas de Kubernetes para filtrar recursos (opcional)
  • include_annotations: Si incluir anotaciones en la salida (predeterminado: verdadero)
  • exclude_annotation_keys: Lista de claves de anotación a excluir de la salida (admite comodines con *)
  • include_annotation_keys: Lista de claves de anotación a incluir en la salida (si se especifica, solo se incluyen estas)
Filtrado de Anotaciones

La herramienta list_resources proporciona potentes capacidades de filtrado de anotaciones para controlar el tamaño de la salida de metadatos y prevenir problemas de truncamiento con anotaciones grandes (como anotaciones de nodos GPU).

Uso Básico:

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

Excluir anotaciones específicas (útil para nodos 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 solo anotaciones específicas:

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

Deshabilitar anotaciones completamente para máximo rendimiento:

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

Reglas de Filtrado de Anotaciones:

  • De forma predeterminada, kubectl.kubernetes.io/last-applied-configuration se excluye para prevenir datos de configuración grandes
  • exclude_annotation_keys admite patrones comodín usando * (por ejemplo, nvidia.com/* excluye todas las anotaciones de NVIDIA)
  • Cuando se especifica include_annotation_keys, tiene prioridad y solo se incluyen esas anotaciones
  • Establecer include_annotations: false elimina completamente todas las anotaciones de la salida
  • Los patrones comodín solo admiten * al final de la clave (por ejemplo, nvidia.com/*)

apply_resource

Aplica (crea o actualiza) un recurso de Kubernetes.

Parámetros:

  • resource_type (obligatorio): Tipo de recurso a aplicar (agrupado o con espacio de nombres)
  • group: Grupo de API (por ejemplo, apps, networking.k8s.io)
  • version (obligatorio): Versión de API (por ejemplo, v1, v1beta1)
  • resource (obligatorio): Nombre del recurso (por ejemplo, deployments, services)
  • namespace: Espacio de nombres (obligatorio para recursos con espacio de nombres)
  • manifest (obligatorio): Manifiesto del recurso

Ejemplo:

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

Publica en un recurso de Kubernetes o su subrecurso, particularmente útil para ejecutar comandos en pods.

Parámetros:

  • resource_type (obligatorio): Tipo de recurso al que publicar (agrupado o con espacio de nombres)
  • group: Grupo de API (por ejemplo, apps, networking.k8s.io)
  • version (obligatorio): Versión de API (por ejemplo, v1, v1beta1)
  • resource (obligatorio): Nombre del recurso (por ejemplo, deployments, services)
  • namespace: Espacio de nombres (obligatorio para recursos con espacio de nombres)
  • name (obligatorio): Nombre del recurso al que publicar
  • subresource: Subrecurso al que publicar (por ejemplo, exec)
  • body (obligatorio): Cuerpo a publicar en el recurso
  • parameters: Parámetros opcionales para la solicitud

Ejemplo de ejecución de un comando en un 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
    }
  }
}

El body para ejecución en pods admite los siguientes campos:

  • command (obligatorio): Comando a ejecutar, ya sea como cadena o como matriz de cadenas
  • container (opcional): Nombre del contenedor en el que ejecutar el comando (predeterminado: el primer contenedor)
  • timeout (opcional): Tiempo de espera en segundos (predeterminado: 15 segundos, máximo: 60 segundos)

Nota sobre tiempos de espera:

  • Tiempo de espera predeterminado: 15 segundos si no se especifica
  • Tiempo de espera máximo: 60 segundos (cualquier valor mayor se limitará)
  • Los comandos que excedan el tiempo de espera se terminarán y devolverán un error de tiempo de espera

La respuesta incluye stdout, stderr y cualquier mensaje de error:

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

El servidor MKP proporciona acceso a recursos de Kubernetes a través de recursos MCP. Los URI de recursos siguen estos formatos:

  • Recursos agrupados: k8s://clustered/{group}/{version}/{resource}/{name}
  • Recursos con espacio de nombres: k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}

Configuración

Protocolo de Transporte

MKP admite dos protocolos de transporte para el servidor MCP:

  • HTTP Transmisible: El protocolo de transporte predeterminado, adecuado para la mayoría de los casos de uso
  • SSE (Eventos Enviados por el Servidor): Protocolo de transporte heredado, principalmente para compatibilidad con clientes más antiguos

Puede configurar el protocolo de transporte usando una bandera CLI o una variable de entorno:

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

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

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

La variable de entorno MCP_TRANSPORT se establece automáticamente por ToolHive cuando se ejecuta MKP en ese entorno.

Control del Descubrimiento de Recursos

De forma predeterminada, MKP sirve todos los recursos de Kubernetes como recursos MCP, lo que proporciona contexto útil para los LLM. Sin embargo, en clústeres grandes con muchos recursos, esto puede consumir espacio de contexto significativo en el LLM.

Puede deshabilitar este comportamiento usando la bandera --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

Incluso con el descubrimiento de recursos deshabilitado, las herramientas MCP (get_resource, list_resources, apply_resource, delete_resource y post_resource) permanecen completamente funcionales, permitiéndole interactuar con su clúster de Kubernetes.

Habilitar Operaciones de Escritura

De forma predeterminada, MKP opera en modo de solo lectura, lo que significa que no permite operaciones de escritura en el clúster, es decir, las herramientas apply_resource, delete_resource y post_resource no estarán disponibles. Puede habilitar operaciones de escritura usando la bandera --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

Limitación de Velocidad

MKP incluye un mecanismo de limitación de velocidad integrado para proteger el servidor de llamadas excesivas a la API, lo cual es particularmente importante cuando se usa con agentes de IA. El limitador de velocidad utiliza un algoritmo de cubo de tokens y aplica diferentes límites según el tipo de operación:

  • Operaciones de lectura (list_resources, get_resource): 120 solicitudes por minuto
  • Operaciones de escritura (apply_resource, delete_resource): 30 solicitudes por minuto
  • Predeterminado para otras operaciones: 60 solicitudes por minuto

Los límites de velocidad se aplican por sesión de cliente, asegurando una asignación justa de recursos entre múltiples clientes. La función de limitación de velocidad se puede habilitar o deshabilitar mediante la bandera de línea de comandos:

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

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

Los límites de velocidad se pueden personalizar mediante variables de entorno:

  • MKP_RATE_LIMIT_DEFAULT: Límite de velocidad predeterminado (predeterminado: 60)
  • MKP_RATE_LIMIT_READ: Límite de velocidad para operaciones de lectura (predeterminado: 120)
  • MKP_RATE_LIMIT_WRITE: Límite de velocidad para operaciones de escritura (predeterminado: 30)
# Run with custom rate limits
MKP_RATE_LIMIT_READ=200 MKP_RATE_LIMIT_WRITE=50 ./build/mkp-server

Desarrollo

Ejecutar pruebas

task test

Formatear código

task fmt

Verificar código con linter

task lint

Actualizar dependencias

task deps

Contribuciones

¡Damos la bienvenida a contribuciones a este servidor MCP! Si desea contribuir, por favor revise la guía de CONTRIBUCIONES para detalles sobre cómo comenzar.

Si encuentra un error o tiene una solicitud de función, por favor abra un problema en el repositorio o únase a nosotros en el canal #mcp-servers en nuestro servidor de Discord de la comunidad.

Licencia

Este proyecto está licenciado bajo la Licencia Apache v2 - consulte el archivo LICENSE para detalles.