WhiteCapData-Dev

WhiteCapData-Dev

Opere um cluster k3s / Kubernetes diretamente do seu agente de IA — seguro por padrão.

Um servidor MCP que permite que um agente (Claude Code, Claude Desktop, Cursor, …) inspecione e opere um cluster Kubernetes / k3s — sua máquina de homelab, um cluster de desenvolvimento, o que seu kubeconfig apontar — sem invocar kubectl. Ele fala diretamente com a API do Kubernetes usando seu kubeconfig existente (ou uma conta de serviço dentro do cluster).

O objetivo do design é seguro por padrão: leituras estão sempre ativas; toda ação de mutação (reiniciar / escalar / excluir) é bloqueada antes da chamada à API por um interruptor somente leitura e uma lista de permissões de namespaces, para que um agente excessivamente ansioso não possa tocar em kube-system ou destruir um deployment que você não isolou.

Nota sobre o nome: o pacote PyPI é whitecapdata-dev (o nome no estilo homelab-k8s já estava ocupado); o pacote de importação e as ferramentas são focados em k8s/homelab, como descrito aqui.

---

Por que você vai querer isso

• 🩺 Saúde em uma chamada. cluster_summary fornece totais de nós e pods e os pods não saudáveis, então o agente começa a triagem com dados reais.
• 🔒 Seguro por padrão. Mutações são bloqueadas a menos que o namespace esteja na sua lista de permissões; alterne HOMELAB_MCP_READONLY=1 para tornar o servidor inteiro somente leitura.
• 🧰 As operações que você realmente faz. Pods, deployments, eventos, logs, saúde de nós, rollout-restart, escala, exclusão de pod.
• 🪶 Sem backend personalizado. Usa a API padrão do Kubernetes + seu kubeconfig — nada para implantar no lado do servidor.
• ✅ Testado. A lógica pura é testada com fakes; a lógica de proteção é testada contra uma API simulada. Nenhum cluster é necessário para executar a suíte.

Requisitos

• Um cluster acessível e um kubeconfig funcional (o mesmo que kubectl usa), ou execute-o dentro do cluster com uma conta de serviço.
• Python 3.11+ (ou apenas uvx).

Instalação

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

Executar com Docker

Um Dockerfile está incluído. O servidor fala MCP via stdio e alcança seu cluster através de um kubeconfig montado. Execute interativamente (-i), começando somente leitura:

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

Ferramentas

Ferramenta	Tipo	Descrição
cluster_summary	leitura	Totais de saúde de nós/pods + pods não saudáveis
list_pods	leitura	Pods (opcionalmente um namespace), não saudáveis primeiro
list_deployments	leitura	Deployments com réplicas prontas/desejadas
list_events	leitura	Eventos recentes, Avisos primeiro
pod_logs	leitura	Cauda dos logs de um pod
node_health	leitura	Prontidão por nó, kubelet, capacidade, pressão
restart_deployment	escrita	Rollout-restart (namespaces permitidos)
scale_deployment	escrita	Escalar para N réplicas (0..máx, permitidos)
delete_pod	escrita	Excluir um pod; seu controlador o recria (permitidos)
server_info	leitura	Configuração efetiva (contexto, somente leitura, lista de permissões)

Configuração

Variável	Padrão	Descrição
HOMELAB_MCP_CONTEXT	contexto atual	Contexto do kubeconfig a usar
HOMELAB_MCP_READONLY	0	1/true desativa todas as ferramentas de mutação
HOMELAB_MCP_MUTABLE_NAMESPACES	default,apps,monitoring,ci	Namespaces que as mutações podem tocar; * = todos
HOMELAB_MCP_MAX_REPLICAS	10	Limite superior para scale_deployment

Modelo de segurança

1. Interruptor somente leitura — HOMELAB_MCP_READONLY=1 rejeita toda ferramenta de mutação antecipadamente.
2. Lista de permissões de namespaces — ferramentas de mutação recusam qualquer namespace que não esteja em HOMELAB_MCP_MUTABLE_NAMESPACES (padrão: um conjunto amigável para homelab; * opta por todos).
3. Escala limitada — scale_deployment limita a 0..HOMELAB_MCP_MAX_REPLICAS.

O próprio RBAC do cluster ainda se aplica por cima — este servidor só pode fazer o que a identidade do kubeconfig tem permissão para fazer.

Desenvolvimento

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

Veja CONTRIBUTING.md.

Licença

MIT © Michael Tierney