millerson-overlay.nix/tasks/kubernetes-mcp-server.md

# Требования для добавления пакета `kubernetes-mcp-server`

## Общая информация

| Параметр | Значение |
|----------|----------|
| **Название пакета** | `kubernetes-mcp-server` |
| **Репозиторий** | https://github.com/containers/kubernetes-mcp-server |
| **Язык** | Go (91.6%) |
| **Модуль** | `github.com/containers/kubernetes-mcp-server` |
| **Бинарный файл** | `kubernetes-mcp-server` |
| **Точка входа** | `./cmd/kubernetes-mcp-server` |
| **Версия** | `v0.0.62` (latest) |
| **Лицензия** | Apache-2.0 |
| **Категория** | MCP Servers |

## Описание

Model Context Protocol (MCP) сервер для Kubernetes и OpenShift. Это нативная Go-реализация, которая напрямую взаимодействует с Kubernetes API **без** необходимости в `kubectl` или `helm`. Позволяет AI-агентам управлять ресурсами Kubernetes (поды, деплойменты, неймспейсы, события, Helm-чарты, Tekton-пайплайны и др.) через стандартизированный протокол MCP.

## Шаги по добавлению

### 1. Создать структуру директорий

```bash
mkdir -p packages/kubernetes-mcp-server
```

### 2. Создать `packages/kubernetes-mcp-server/package.nix`

Шаблон основан на `buildGoModule` (аналогично пакету `container-use`):

- **`buildGoModule`** — стандартный билдер для Go-пакетов в nixpkgs
- **`vendorHash`** — хеш зависимостей Go (будет уточнён при первой сборке)
- **`CGO_ENABLED = 0`** — проект собирается без CGo (статическая линковка, кроссплатформенность)
- **`subPackages = [ "cmd/kubernetes-mcp-server" ]`** — указывает точку входа
- **`doCheck = false`** — тесты требуют доступ к реальному Kubernetes-кластеру, что невозможно в sandbox Nix
- **`ldflags`** — передача версии в бинарник (`-s -w` для уменьшения размера)
- **`passthru.updateScript`** — поддержка `nix-update` для автоматического обновления версии
- **`meta.mainProgram`** — `kubernetes-mcp-server`

Примерный код `package.nix`:

```nix
{
  lib,
  buildGoModule,
  fetchFromGitHub,
}:

buildGoModule rec {
  pname = "kubernetes-mcp-server";
  version = "0.0.62";

  src = fetchFromGitHub {
    owner = "containers";
    repo = "kubernetes-mcp-server";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; # Будет уточнён при сборке
  };

  vendorHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; # Будет уточнён при сборке

  env.CGO_ENABLED = 0;

  subPackages = [ "cmd/kubernetes-mcp-server" ];

  # Тесты требуют доступ к Kubernetes-кластеру
  doCheck = false;

  ldflags = [
    "-s"
    "-w"
  ];

  passthru = {
    category = "MCP Servers";
    updateScript = [
      "nix-update"
      "--flake"
      ".#kubernetes-mcp-server"
    ];
  };

  meta = with lib; {
    description = "Model Context Protocol (MCP) server for Kubernetes and OpenShift";
    homepage = "https://github.com/containers/kubernetes-mcp-server";
    changelog = "https://github.com/containers/kubernetes-mcp-server/releases/tag/v${version}";
    license = licenses.asl20;
    sourceProvenance = with sourceTypes; [ fromSource ];
    mainProgram = "kubernetes-mcp-server";
    platforms = platforms.all;
  };
}
```

### 3. Создать `packages/kubernetes-mcp-server/default.nix`

Стандартная обёртка для blueprint:

```nix
{ pkgs, ... }:
pkgs.callPackage ./package.nix { }
```

### 4. Первая сборка и получение хешей

```bash
# Первая попытка сборки (ожидаемо упадёт с неверным хешем)
nix build .#kubernetes-mcp-server 2>&1 | grep -E "(hash|Hash)"

# Подставить правильные значения hash и vendorHash в package.nix
```

Альтернативно, использовать `nix-update`:

```bash
nix-update kubernetes-mcp-server --version=0.0.62
```

### 5. Проверка

```bash
# Сборка
nix build .#kubernetes-mcp-server

# Запуск (проверка справки)
nix run .#kubernetes-mcp-server -- --help

# Проверка всех пакетов
nix flake check
```

### 6. Обновить README.md

Добавить строку в таблицу «Available Packages»:

```markdown
| `kubernetes-mcp-server` | Model Context Protocol (MCP) server for Kubernetes and OpenShift | MCP Servers |
```

### 7. Коммит

Использовать `conventional-commit` skill для создания коммита с сообщением типа:

```
feat: add kubernetes-mcp-server package
```

Или более детально:

```
feat(packages): add kubernetes-mcp-server v0.0.62

Model Context Protocol (MCP) server for Kubernetes and OpenShift.
Native Go implementation that interacts directly with the Kubernetes
API server without external dependencies like kubectl or helm.
```

## Особенности пакета

| Особенность | Детали |
|-------------|--------|
| **Тип сборки** | Go module (`buildGoModule`) |
| **CGo** | Отключено (`CGO_ENABLED = 0`) |
| **Тесты** | Отключены (нужен Kubernetes-кластер) |
| **Платформы** | Все (`platforms.all`) |
| **Версионирование** | Стандартные теги `v0.0.X` |
| **Обновление** | `nix-update kubernetes-mcp-server` |

## Зависимости (уже в nixpkgs)

Пакет использует только стандартные Go-зависимости, указанные в `go.mod` и `go.sum`. Никаких дополнительных системных зависимостей не требуется благодаря `CGO_ENABLED = 0`.

## Критерии приёмки

- [ ] Пакет собирается: `nix build .#kubernetes-mcp-server`
- [ ] Бинарник запускается и выводит справку: `nix run .#kubernetes-mcp-server -- --help`
- [ ] `nix flake check` проходит без ошибок
- [ ] Пакет виден в списке: пакет появляется в выводе `nix flake show`
- [ ] README.md обновлён
- [ ] Коммит создан с использованием conventional commits