platform-mcp

MCP-сервер для инфраструктурных сервисов кластера sonar-prod — Argo CD, Vault и Keycloak — с SSO-входом (GitLab для Argo/Vault, FreeIPA для Keycloak).

Зачем

Агенту в редакторе нужен доступ к Argo CD, Vault и Keycloak, но выдавать ему сервисную учётку нельзя: в аудите вместо человека появится общий аккаунт, а права окажутся шире, чем у любого конкретного разработчика.

Этот пакет ставится локально и проводит обычный SSO-вход через браузер. Дальше он выполняет команды от имени вошедшего пользователя: в аудит-логах виден реальный логин, а права ровно те, что даёт членство в группах.

Инструмент на сервис ровно один — argocd_exec, vault_exec и keycloak_exec, принимающие аргументы командной строки. Под капотом — официальные CLI (argocd, vault, kcadm), поэтому доступно всё, что умеют они. Новый сервис добавляется одной реализацией интерфейса.

Related MCP server: Kepler MCP GitLab Server

Установка

Шаг 1. Доступ к реестру пакетов

Нужен один раз и для всех способов ниже: пакет лежит в npm registry этого GitLab-проекта, а не в публичном npm. Возьмите токен с правом read_package_registry (личный access token или deploy token проекта) и добавьте в ~/.npmrc:

@sonar:registry=https://git.sonar-corp.ru/api/v4/projects/98/packages/npm/
//git.sonar-corp.ru/api/v4/projects/98/packages/npm/:_authToken=<ваш gitlab токен>

Шаг 2. Подключение к редактору

Claude Code и Cursor — плагином. Репозиторий сам себе каталог плагинов, поэтому достаточно двух команд:

/plugin marketplace add https://github.com/K-manankov/platform-mcp.git
/plugin install platform-mcp

Адрес именно GitHub, а не GitLab, и это не опечатка — см. Почему каталог плагинов на GitHub.

Адреса Argo CD, Vault и Keycloak уже прописаны в плагине — настраивать ничего не нужно. Обновления приезжают сами: плагин запускает сервер через npx -y, то есть всегда последнюю опубликованную версию. Обновить сам плагин — /plugin marketplace update.

Claude Desktop плагины этого формата не устанавливает, поэтому там запись делается вручную. Поставьте пакет глобально:

npm install -g @sonar/platform-mcp

и добавьте в claude_desktop_config.json (Settings → Developer → Edit Config). Путь к node и к серверу — обязательно абсолютные: GUI-приложения на macOS не наследуют PATH из шелла. Свои пути посмотрите командами which node и which platform-mcp:

{
  "mcpServers": {
    "platform": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/opt/homebrew/lib/node_modules/@sonar/platform-mcp/dist/index.js"],
      "env": {
        "ARGOCD_BASE_URL": "https://argocd.infra.sonar-corp.ru",
        "VAULT_ADDR": "https://vault.infra.sonar-corp.ru",
        "KEYCLOAK_BASE_URL": "https://auth.infra.sonar-corp.ru",
        "PLATFORM_MCP_INSECURE": "true"
      }
    }
  }
}

Argo CD, Vault и Keycloak ставить отдельно не нужно ни в одном из вариантов: сервер сам скачает нужные версии CLI при первом обращении (см. Откуда берутся CLI). Для kcadm на машине должна быть Java 17+.

Почему каталог плагинов на GitHub

Claude Desktop подключает каталоги плагинов только с GitHub. Плюс к этому наш GitLab живёт во внутренней сети и снаружи недоступен в принципе, так что до git.sonar-corp.ru он бы и не дотянулся.

Поэтому исходный код остаётся в GitLab, а в github.com/K-manankov/platform-mcp настроено зеркало защищённых веток. Защищена одна ветка — main, и именно она уезжает на GitHub при каждом пуше. Обратной синхронизации нет: правки делаются только в GitLab, GitHub-копия существует ради установки плагина.

Само зеркало ничего не раскрывает лишнего — там тот же публичный npm-пакет и адреса внутренних сервисов, которые всё равно резолвятся только из сети. Секретов в репозитории нет и быть не должно: токены доступа сервер держит в ~/.config/platform-mcp/, а токен реестра пакетов каждый заводит себе сам в ~/.npmrc.

Обновить установленный плагин после изменений:

/plugin marketplace update sonar-infra
/plugin update platform-mcp

Вход

Нужен VPN: имена argocd.infra.sonar-corp.ru, vault.infra.sonar-corp.ru и auth.infra.sonar-corp.ru резолвятся только изнутри сети. Снаружи их подхватывает публичный wildcard *.infra.sonar-corp.ru, и запрос молча уезжает не туда — проверка dig +short argocd.infra.sonar-corp.ru должна дать 192.168.88.106.

Проще всего войти прямо из диалога: попросите агента вызвать argocd_login, vault_login или keycloak_login, откройте выданную ссылку и завершите вход. Перезапускать редактор не нужно.

То же самое из терминала, если пакет установлен глобально:

export ARGOCD_BASE_URL=https://argocd.infra.sonar-corp.ru
export VAULT_ADDR=https://vault.infra.sonar-corp.ru
export KEYCLOAK_BASE_URL=https://auth.infra.sonar-corp.ru
export PLATFORM_MCP_INSECURE=true   # пока нет настоящих сертификатов, см. TLS

platform-mcp login             # во все настроенные сервисы подряд
platform-mcp login keycloak    # только в один

Откроется браузер: для Argo CD и Vault — GitLab SSO, для Keycloak — FreeIPA в realm master (клиент platform-mcp-cli, см. bootstrap в infra). Сессии лягут в ~/.config/platform-mcp/ с правами 0600 и общие для всех редакторов: войдя один раз, вы вошли везде.

По SSH или в devcontainer, где браузера нет:

platform-mcp login --no-browser

Ссылку из вывода нужно открыть на своей машине; порт 8085 (Argo CD), 8250 (Vault) или 8280 (Keycloak) при этом должен быть проброшен на хост, где запущена команда.

Вход администратором Vault

Обычный вход идёт в точку монтирования oidc, где политика выдаётся по членству в подгруппе. Полные права на хранилище живут в отдельном mount'е oidc-admin и достаются только Owner'ам группы infra/k8s — почему так, описано в platform/vault-config/40-groups.yaml:

VAULT_OIDC_MOUNT=oidc-admin platform-mcp login vault

Настройка

Менять что-либо необязательно — адреса уже прописаны в плагине.

Cursor. Plugins → Configure у platform-mcp: URL Argo CD, Vault и Keycloak, PLATFORM_MCP_INSECURE, и mount Vault OIDC (oidc — обычный вход, oidc-admin — полные права для Owner'ов infra/k8s). Дефолты совпадают с кластером sonar-prod.

Claude Code и ручной конфиг. Если нужно другое (свой инстанс, oidc-admin, свои запреты), переопределите переменными окружения в конфиге редактора либо положите в ~/.config/platform-mcp/config.json:

{
  "argocdUrl": "https://argocd.infra.sonar-corp.ru",
  "vaultUrl": "https://vault.infra.sonar-corp.ru",
  "keycloakUrl": "https://auth.infra.sonar-corp.ru",
  "vaultOidcMount": "oidc",
  "policy": {
    "requireConfirmation": true,
    "denyVaultPaths": ["kv/infra/"]
  }
}

Достаточно задать адрес хотя бы одного сервиса — остальные просто не появятся в списке инструментов.

Если сессии нет или она истекла, инструменты вернут понятную ошибку, а агент сможет вызвать argocd_login / vault_login / keycloak_login прямо из диалога — перезапускать редактор не нужно. Эти инструменты открывают браузер и сразу возвращают ссылку, не дожидаясь завершения входа: человек ходит по SSO минуты, а таймаут запроса у MCP-клиентов обычно 60 секунд. Результат проверяется отдельным вызовом *_auth_status.

Команды

platform-mcp                    # MCP-сервер поверх stdio (так его запускает редактор)
platform-mcp login [сервис]     # интерактивный вход, --no-browser для headless
platform-mcp status [сервис]    # кто вошёл и до какого момента действует токен
platform-mcp logout [сервис]    # удалить сохранённую сессию

Сервис — argocd, vault или keycloak; без него команда применяется ко всем настроенным.

Инструменты

На каждый сервис: <сервис>_exec, <сервис>_login, <сервис>_auth_status, <сервис>_logout.

argocd_exec, vault_exec и keycloak_exec принимают args — массив аргументов командной строки:

argocd_exec { "args": ["app", "list", "-o", "json"] }
argocd_exec { "args": ["app", "sync", "team-a-api"] }
vault_auth_status   # сначала: username, role, policies
vault_exec  { "args": ["token", "lookup"] }
vault_exec  { "args": ["kv", "list", "kv/teams"] }
vault_exec  { "args": ["kv", "get", "kv/teams/team-a/postgres"] }
keycloak_exec { "args": ["get", "realms"] }
keycloak_exec { "args": ["get", "users", "-r", "sonar-prod", "-q", "username=alice"] }

Для Vault начинайте с vault_auth_status: по policies сразу видно, есть ли доступ к KV. ["token","lookup"] — канон CLI (не lookup-self). sys/mounts у обычных OIDC-пользователей часто 403 — не используйте для discovery. Exit code 2 у kv list обычно значит «пусто или нет list ACL», а не «нужно пробовать другой mount».

Аргументы всегда передаются массивом и никогда не склеиваются в строку: shell не участвует, поэтому ; и $(...) в аргументах остаются обычным текстом.

Адрес и токен подставляет сервер. Флаги, которые их переопределяют (--server, --auth-token, --config, --core у Argo CD; -address, -tls-skip-verify у Vault; --server, --config, --no-config у Keycloak), запрещены — иначе рабочий токен из окружения дочернего процесса можно было бы отправить на чужой хост.

Подтверждение опасных операций

Читающие команды выполняются сразу. Для Argo CD и Vault всё остальное требует подтверждения пользователя.

Мутирующей считается любая команда, которая не опознана как читающая: список глаголов замкнут в безопасную сторону, поэтому незнакомая команда попадёт под подтверждение, а не проскочит мимо него.

Если клиент поддерживает MCP elicitation, появляется обычный диалог. Если нет — работает запасная схема: первый вызов возвращает описание последствий и одноразовый токен, второй вызов с этим токеном выполняет операцию. Токен живёт 5 минут и привязан к конкретным аргументам, поэтому «подтвердил одно, выполнил другое» не пройдёт, а придумать его самостоятельно агент не может.

Keycloak — исключение: мутации выполняются сразу, но в ответе агенту добавляется warning — конфиг едет через CR/оператор, ручные правки через kcadm оператор может перетереть при sync. Предпочтительны манифесты в Git.

Отдельно запрещены совсем:

• вход и выход (argocd login, vault login, kcadm config …) — сессией управляет сам сервер;

• команды, которые не завершаются: vault server|agent|proxy|monitor, argocd app logs --follow;

• argocd admin — управление самим Argo CD;

• vault operator seal|step-down|init|rekey|generate-root|migrate — отказ любой из них кладёт хранилище целиком;

• изменение инфраструктурных приложений Argo CD (argocd, vault, keycloak, cert-manager, ingress-nginx, …): они едут из Git через merge request, а не из диалога с агентом. Читать их можно.

Списки настраиваются в config.json (policy.denyApplications, policy.denyVaultPaths).

Это защита от ошибок агента, а не граница безопасности. Участник группы infra/k8s и так администратор Argo CD (g, infra/k8s, role:admin) и может сделать то же самое через UI. Реально ограничить права можно только разделением ролей в argocd-rbac-cm и политиками Vault.

Секреты не попадают в контекст модели

Значения секретов вырезаются из ответов, а имена ключей и метаданные остаются:

• Vault — значения из kv get, read по KV-пути и unwrap. Ответы kv list, kv metadata get, policy read, sys/mounts не трогаются: там нет секретов, и вырезание сделало бы их бесполезными.

• Argo CD — data и stringData у ресурсов Secret, в том числе внутри полей manifest, liveState, targetState, где Argo CD отдаёт манифесты строками с JSON внутри. base64 — это не шифрование.

Обходные пути закрыты: vault kv get -field=password печатает голое значение мимо JSON, а -format=table не даёт из чего вырезать — оба отклоняются с объяснением.

Если значения действительно нужны в диалоге:

export PLATFORM_MCP_ALLOW_SECRET_VALUES=true

Осознанный опт-ин: после него содержимое секретов уезжает провайдеру модели. По умолчанию смотрите секреты в Vault напрямую.

Дополнительно: ответы длиннее 100 КБ обрезаются с подсказкой, чем сузить запрос, а вывод помечается как данные из кластера — манифесты, аннотации и логи пишут люди, и встреченные там указания агент выполнять не должен.

Откуда берутся argocd, vault и kcadm

Сервер работает не через самописный REST-клиент, а через официальные CLI: у Argo CD Node-клиента нет вовсе, у Vault официальный — это Go-библиотека и тот же бинарник, у Keycloak Admin API — kcadm из дистрибутива. Полнота возможностей при этом равна полноте CLI.

Ставить их вручную не нужно:

1. Если argocd / vault / kcadm (kcadm.sh) уже есть в PATH — используется он, ничего не скачивается.

2. Иначе при первом обращении скачивается закреплённая версия с официальных релизов (github.com/argoproj/argo-cd, releases.hashicorp.com, github.com/keycloak/keycloak) под текущую платформу. Для Keycloak — zip дистрибутива целиком (~170 МБ): kcadm — Java-скрипт, а не отдельный Go-бинарник.

3. Контрольная сумма сверяется до распаковки и до chmod +x. Без этого шага всё свелось бы к «скачать из интернета и выполнить».

4. Файл кладётся в ~/.config/platform-mcp/bin/ и переиспользуется дальше.

Для kcadm на машине нужна Java 17+ (java в PATH или JAVA_HOME). Без неё сервер вернёт понятную ошибку.

Скачивание происходит при первом использовании, а не в postinstall: postinstall-скрипты повсеместно отключают (npm ci --ignore-scripts), и установка молча оставалась бы неполной.

Версии закреплены в src/config.ts и совпадают с развёрнутыми в кластере (Argo CD v3.4.5, Vault 2.0.3, Keycloak 26.6.4). При обновлении кластера их нужно поднять здесь же.

TLS

У argocd.infra.sonar-corp.ru, vault.infra.sonar-corp.ru и auth.infra.sonar-corp.ru сейчас нет настоящих сертификатов: в Ingress секрет с сертификатом не указан, поэтому ingress-nginx отдаёт свой дефолтный самоподписанный (CN=Kubernetes Ingress Controller Fake Certificate, SAN ingress.local).

Пока это так, нужен явный опт-ин:

export PLATFORM_MCP_INSECURE=true

Он отключает проверку сертификата для Node (OIDC login) и печатает предупреждение при каждом запуске. Соединение остаётся шифрованным, но подлинность сервера не подтверждается, а по этому каналу ходят токены доступа. У kcadm при отсутствии truststore в конфиге включён skip certificate validation (предупреждение в stderr CLI).

NODE_EXTRA_CA_CERTS здесь не поможет: SAN сертификата (ingress.local) не совпадает с именем хоста, поэтому проверка имени провалится даже с доверенным корневым CA.

После выпуска нормальных сертификатов опцию нужно убрать. Если они подписаны внутренним CA, достаточно указать корневой — переменные наследуются дочерними CLI:

export NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem   # для самого сервера (Node)
export SSL_CERT_FILE=/path/to/internal-ca.pem         # для argocd и vault (Go)

Как это устроено

редактор ──stdio──▶ platform-mcp ──argv+env──▶ argocd ──▶ Argo CD
                    (OIDC, политика,  vault  ──▶ Vault
                     вырезание секретов) kcadm ──▶ Keycloak

Argo CD. Вход — Authorization Code + PKCE через Dex. Используется public-клиент argo-cd-cli, которого Argo CD регистрирует в Dex автоматически вместе с redirect URI http://localhost:8085/auth/callback, поэтому менять argocd-cm для установки не нужно. Argo CD принимает как Bearer именно id_token, а не access_token — последний у Dex непрозрачный и API-сервером не проверяется. Токен обновляется по refresh-токену.

CLI запускается с --grpc-web: ingress-nginx проксирует в argocd-server обычный HTTP/1.1 (configs.params.server.insecure: true), и чистый gRPC до него не доходит.

Vault. Поток проще: PKCE не нужен, потому что код на токен меняет сам Vault — секрет OAuth-приложения хранится в нём. От клиента требуется поднять listener на http://localhost:8250/oidc/callback (он заранее прописан в allowedRedirectURIs) и вернуть code, state и client_nonce. Параметр state генерирует сам Vault и кладёт внутрь выданной ссылки — оттуда он и берётся для проверки редиректа. Токен продлевается через auth/token/renew-self, пока renewable.

Keycloak. Authorization Code + PKCE через public-клиент platform-mcp-cli в realm master (заводится один раз в bootstrap, redirect http://localhost:8280/oidc/callback). Вход — FreeIPA. В сессию кладётся access_token (Admin API). Перед kcadm сервер пишет приватный kcadm.config в ~/.config/platform-mcp/ — не общий ~/.keycloak/kcadm.config.

Токены передаются дочерним процессам только через окружение (Argo/Vault) или через приватный config-файл (Keycloak): в argv они были бы видны в ps любому процессу пользователя. Окружение не наследуется целиком — CLI получает ровно то, что ему нужно, без секретов соседних сервисов.

Сессии хранятся в собственных файлах, а не в ~/.config/argocd/config, ~/.vault-token и ~/.keycloak/kcadm.config: провайдер ротирует токен при обновлении, и общий файл приводил бы к тому, что обычные CLI в терминале и этот сервер инвалидировали бы сессии друг другу.

Разработка

npm install
npm run build
npm test

Тесты покрывают классификацию команд и запреты, вырезание секретов, одноразовые токены подтверждения, отсутствие shell при запуске CLI и собственный распаковщик ZIP (он нужен потому, что HashiCorp отдаёт vault архивом, а встроенного распаковщика в Node нет).

Плагин

Репозиторий одновременно и каталог плагинов, и сам плагин:

.claude-plugin/marketplace.json      каталог для Claude Code
.cursor-plugin/marketplace.json      каталог для Cursor
plugins/platform-mcp/
  .claude-plugin/plugin.json         манифест для Claude Code
  .cursor-plugin/plugin.json         манифест для Cursor
  .mcp.json                          сервер для Claude Code — ПЛОСКАЯ карта
  mcp.json                           тот же сервер для Cursor — с обёрткой mcpServers

Описание сервера продублировано в двух формах, и это не небрежность. Claude Code читает .mcp.json как плоскую карту «имя → сервер»: с обёрткой mcpServers он молча не подхватывает сервер — плагин ставится и числится включённым, но инструментов не появляется. Cursor же берёт файл по пути из mcpServers в своём plugin.json, и рабочие плагины для него используют форму с обёрткой. command/args и ключи env совпадают; значения env у Cursor — плейсхолдеры ${VAR} (схема variables в plugin.json, Configure в UI), у Claude — литеральные дефолты. npm run check:manifests следит, чтобы формы не разъехались.

Код сервера в плагин не копируется: оба файла запускают опубликованный пакет через npx, поэтому плагин остаётся несколькими небольшими файлами и не требует пересборки при изменениях сервера.

Проверить изменения до пуша можно, подключив каталог с локального пути:

/plugin marketplace add /путь/к/platform-mcp
/plugin install platform-mcp

Публикация

CI (.gitlab-ci.yml) публикует пакет в GitLab npm registry этого проекта автоматически по тегу вида vX.Y.Z, аутентификация — через встроенный CI_JOB_TOKEN, личных токенов в CI не требуется.

Версия продублирована в манифестах плагина, и её нужно поднимать там же:

npm version <major|minor|patch> --no-git-tag-version   # только package.json
# поправить version в обоих plugins/platform-mcp/*/plugin.json
npm run check:manifests                                # сверить
git commit -am "0.X.Y" && git tag v0.X.Y && git push --follow-tags

Расхождение поймает CI: задание test сверяет версии в трёх манифестах и согласованность двух описаний сервера, а publish — версию из тега с package.json. Без этого плагин у пользователя остался бы «неизменившимся» при свежем сервере: и Claude Code, и Cursor решают, обновлять ли плагин, по его version.

Отдельно выкладывать плагин никуда не нужно: пуш в main уезжает на GitHub зеркалом защищённых веток, и пользователи подхватывают изменения через /plugin marketplace update. Обратите внимание, что плагин ставится из ветки, а не из тега: как только правка попала в main, она уже доступна всем — даже если версия ещё не выпущена тегом.