WhiteCapData-Dev

WhiteCapData-Dev

Opera un clúster k3s / Kubernetes directamente desde tu agente de IA — seguro por defecto.

Un servidor MCP que permite a un agente (Claude Code, Claude Desktop, Cursor, …) inspeccionar y operar un clúster Kubernetes / k3s — tu máquina de homelab, un clúster de desarrollo, lo que sea que apunte tu kubeconfig — sin recurrir a kubectl. Se comunica directamente con la API de Kubernetes usando tu kubeconfig existente (o una cuenta de servicio dentro del clúster).

El objetivo de diseño es seguro por defecto: las lecturas siempre están habilitadas; cada acción mutante (reiniciar / escalar / eliminar) está restringida antes de la llamada a la API por un interruptor de solo lectura y una lista de permitidos de namespaces, para que un agente demasiado entusiasta no pueda tocar kube-system ni destruir un deployment que no hayas puesto en la zona de pruebas.

Nota sobre el nombre: el paquete de PyPI es whitecapdata-dev (el nombre estilo homelab-k8s ya estaba tomado); el paquete de importación y las herramientas están enfocadas en k8s/homelab como se describe aquí.

---

Por qué querrías esto

• 🩺 Salud con una sola llamada. cluster_summary da totales de nodos y pods, y los pods no saludables, para que el agente comience el triaje con datos reales.
• 🔒 Seguro por defecto. Las mutaciones están bloqueadas a menos que el namespace esté en tu lista de permitidos; activa HOMELAB_MCP_READONLY=1 para que todo el servidor sea de solo lectura.
• 🧰 Las operaciones que realmente haces. Pods, deployments, eventos, logs, salud de nodos, rollout-restart, escalado, eliminación de pods.
• 🪶 Sin backend personalizado. Usa la API estándar de Kubernetes + tu kubeconfig — nada que desplegar en el lado del servidor.
• ✅ Probado. La lógica pura está probada con unit tests con fakes; la lógica de protección está probada contra una API simulada. No se necesita clúster para ejecutar la suite.

Requisitos

• Un clúster accesible y un kubeconfig funcional (el mismo que usa kubectl), o ejecutarlo dentro del clúster con una cuenta de servicio.
• Python 3.11+ (o simplemente uvx).

Instalación

uvx whitecapdata-dev          # run directly
# or
pip install whitecapdata-dev  # then run: whitecapdata-dev

Claude Code

claude mcp add homelab -- uvx whitecapdata-dev

Claude Desktop / Cursor

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["whitecapdata-dev"],
      "env": {
        "HOMELAB_MCP_MUTABLE_NAMESPACES": "default,apps,monitoring",
        "HOMELAB_MCP_READONLY": "0"
      }
    }
  }
}

Ejecutar con Docker

Se incluye un Dockerfile. El servidor habla MCP sobre stdio y llega a tu clúster a través de un kubeconfig montado. Ejecútalo de forma interactiva (-i), comenzando en modo solo lectura:

docker build -t whitecapdata-dev .
docker run --rm -i \
  -v "$HOME/.kube/config:/home/app/.kube/config:ro" \
  -e HOMELAB_MCP_READONLY=1 \
  whitecapdata-dev

Herramientas

Herramienta	Tipo	Descripción
cluster_summary	lectura	Totales de salud de nodos/pods + pods no saludables
list_pods	lectura	Pods (opcionalmente un namespace), no saludables primero
list_deployments	lectura	Deployments con réplicas listas/deseadas
list_events	lectura	Eventos recientes, advertencias primero
pod_logs	lectura	Cola de logs de un pod
node_health	lectura	Preparación por nodo, kubelet, capacidad, presión
restart_deployment	escritura	Rollout-restart (namespaces permitidos)
scale_deployment	escritura	Escalar a N réplicas (0..máx, permitidos)
delete_pod	escritura	Eliminar un pod; su controlador lo recrea (permitidos)
server_info	lectura	Configuración efectiva (contexto, solo lectura, lista de permitidos)

Configuración

Variable	Predeterminado	Descripción
HOMELAB_MCP_CONTEXT	contexto actual	Contexto de kubeconfig a usar
HOMELAB_MCP_READONLY	0	1/true desactiva todas las herramientas mutantes
HOMELAB_MCP_MUTABLE_NAMESPACES	default,apps,monitoring,ci	Namespaces que las mutaciones pueden tocar; * = todos
HOMELAB_MCP_MAX_REPLICAS	10	Límite superior para scale_deployment

Modelo de seguridad

1. Interruptor de solo lectura — HOMELAB_MCP_READONLY=1 rechaza cada herramienta mutante de antemano.
2. Lista de permitidos de namespaces — las herramientas mutantes rechazan cualquier namespace que no esté en HOMELAB_MCP_MUTABLE_NAMESPACES (por defecto un conjunto amigable para homelab; * opta por todos).
3. Escalado acotado — scale_deployment limita a 0..HOMELAB_MCP_MAX_REPLICAS.

El RBAC propio del clúster sigue aplicándose encima — este servidor solo puede hacer lo que la identidad del kubeconfig tenga permitido hacer.

Desarrollo

git clone https://github.com/Michael-WhiteCapData/WhiteCapData-Dev
cd WhiteCapData-Dev
uv pip install -e ".[dev]"
ruff check .
pytest          # no cluster required — APIs are faked/mocked

Consulta CONTRIBUTING.md.

Licencia

MIT © Michael Tierney