platform-mcp

クラスタ sonar-prod のインフラストラクチャサービス（Argo CD、Vault、Keycloak）向けMCPサーバー。SSOログイン対応（Argo/VaultはGitLab、KeycloakはFreeIPA）。

目的

エディタ内のエージェントにArgo CD、Vault、Keycloakへのアクセスが必要だが、サービスアカウントを渡すことはできない。監査ログに個人ではなく共有アカウントが記録され、権限も特定の開発者より広くなってしまうためだ。

このパッケージはローカルにインストールされ、ブラウザ経由で通常のSSOログインを実行する。以降はログインしたユーザーの権限でコマンドを実行する。監査ログには実際のログインIDが記録され、権限はグループメンバーシップで付与されるものと正確に一致する。

サービスごとのツールは argocd_exec、vault_exec、keycloak_exec の1つだけで、コマンドライン引数を受け取る。内部では公式CLI（argocd、vault、kcadm）を使用しているため、それらが対応するすべての操作が可能。新しいサービスはインターフェースの実装を1つ追加するだけで組み込める。

Related MCP server: mcp-read-only-argocd

インストール

ステップ1. パッケージレジストリへのアクセス

以下のすべての方法で一度だけ必要: パッケージは公開npmではなく、このGitLabプロジェクトのnpmレジストリにある。read_package_registry 権限を持つトークン（個人アクセストークンまたはプロジェクトのデプロイトークン）を取得し、~/.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はプラグインで。 リポジトリ自体がプラグインカタログになっているため、2つのコマンドで十分:

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

アドレスはGitLabではなくGitHub。これは誤字ではない。 プラグインカタログが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 とサーバーへのパスは必ず絶対パスにすること。macOSのGUIアプリケーションはシェルの 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を自動でダウンロードする（argocd、vault、kcadmの入手元 を参照）。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 はネットワーク内からのみ解決される。外部からは公開ワイルドカード *.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はrealm master のFreeIPA（クライアント platform-mcp-cli、infraのbootstrapを参照）。セッションは ~/.config/platform-mcp/ に権限 0600 で保存され、すべてのエディタで共有される。一度ログインすれば、どこでもログイン済みになる。

SSHやdevcontainerなどブラウザがない環境では:

platform-mcp login --no-browser

出力のリンクは自分のマシンで開く必要がある。その際、ポート 8085（Argo CD）、8250（Vault）、8280（Keycloak）がコマンドを実行しているホストに転送されている必要がある。

Vault管理者としてのログイン

通常のログインは oidc マウントポイントに対して行われ、ポリシーはサブグループのメンバーシップに基づいて付与される。ストレージへの完全な権限は別のマウント oidc-admin にあり、infra/k8s グループのOwnerのみが取得できる。その理由は platform/vault-config/40-groups.yaml に記載されている:

VAULT_OIDC_MOUNT=oidc-admin platform-mcp login vault

設定

変更は必須ではない。アドレスはプラグインにすでに設定されている。

Cursor. platform-mcp のPlugins → Configure: Argo CD、Vault、KeycloakのURL、PLATFORM_MCP_INSECURE、Vault OIDCのマウント（oidc — 通常ログイン、oidc-admin — infra/k8s のOwner向け完全権限）。デフォルトはクラスタ 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/"]
  }
}

少なくとも1つのサービスのアドレスを設定すれば十分。残りは単にツールリストに表示されないだけ。

セッションがない、または期限切れの場合、ツールはわかりやすいエラーを返し、エージェントはダイアログから直接 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になることが多いため、ディスカバリには使わないこと。kv list の終了コード2は通常「空、またはlist ACLがない」ことを意味し、「別のマウントを試すべき」ではない。

引数は常に配列で渡され、文字列に連結されることはない。シェルは関与しないため、引数内の ; や $(...) は単なるテキストとして扱われる。

アドレスとトークンはサーバーが設定する。これらを上書きするフラグ（Argo CDの --server、--auth-token、--config、--core、Vaultの -address、-tls-skip-verify、Keycloakの --server、--config、--no-config）は禁止されている。子プロセスの環境から作業用トークンを外部ホストに送信できてしまうためだ。

危険な操作の確認

読み取り専用コマンドは即座に実行される。Argo CDとVaultでは、それ以外のすべての操作にユーザーの確認が必要。

読み取り専用と認識されないコマンドはすべて変更操作とみなされる。動詞のリストは安全側に閉じているため、未知のコマンドは確認をすり抜けるのではなく、確認の対象になる。

クライアントがMCP elicitationをサポートしている場合、通常のダイアログが表示される。サポートしていない場合はフォールバックスキームが機能する。最初の呼び出しで影響の説明とワンタイムトークンが返され、そのトークンを使った2回目の呼び出しで操作が実行される。トークンの有効期限は5分で、特定の引数にバインドされているため、「Aを確認したのにBを実行した」は成立せず、エージェントが独自にトークンを生成することもできない。

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、KVパスへの read、unwrap の値。kv list、kv metadata get、policy read、sys/mounts の応答は変更されない。シークレットが含まれず、削除すると役に立たなくなるためだ。

• Argo CD — Secret リソースの data と stringData。Argo CDがJSONを含む文字列としてマニフェストを返す manifest、liveState、targetState フィールド内も含む。base64 は暗号化ではない。

回避策は封じられている: vault kv get -field=password はJSONを介さずに素の値を出力し、-format=table は削除対象を特定できない。両方とも説明付きで拒否される。

ダイアログで値が本当に必要な場合:

export PLATFORM_MCP_ALLOW_SECRET_VALUES=true

意図的なオプトイン。これ以降、シークレットの内容はモデルプロバイダーに送信される。デフォルトではVaultでシークレットを直接確認すること。

さらに: 100KBを超える応答は、クエリを絞り込むヒント付きで切り詰められる。また、出力はクラスタからのデータとしてマークされる。マニフェスト、アノテーション、ログは人間が書くものであり、そこで見つかった指示をエージェントが実行してはならない。

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全体（約170MB）。kcadm はJavaスクリプトであり、独立したGoバイナリではない。

3. チェックサムは解凍前かつ chmod +x の前に検証される。 このステップがなければ「インターネットからダウンロードして実行」と同じことになる。

4. ファイルは ~/.config/platform-mcp/bin/ に配置され、以降再利用される。

kcadm を使用するにはマシンに Java 17+ が必要（PATH の java または 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 ログイン）の証明書検証を無効化し、起動のたびに警告を出力します。接続は暗号化されたままですが、サーバーの真正性は確認されず、このチャネルを介してアクセストークンがやり取りされます。kcadm は設定にトラストストアがない場合、証明書検証のスキップが有効になります（stderr CLI に警告）。

ここでは NODE_EXTRA_CA_CERTS は役に立ちません。証明書の SAN（ingress.local）がホスト名と一致しないため、信頼されたルート CA があっても名前検証は失敗します。

正常な証明書を発行したら、このオプションは削除する必要があります。内部 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。 ログインは Dex を介した Authorization Code + PKCE。Argo CD が自動的に Dex に登録する public クライアント argo-cd-cli が使用され、redirect URI は http://localhost:8085/auth/callback なので、セットアップのために argocd-cm を変更する必要はありません。Argo CD は Bearer として access_token ではなく id_token を受け入れます。後者は Dex では不透明であり、API サーバーによって検証されません。トークンは refresh トークンによって更新されます。

CLI は --grpc-web で起動されます。ingress-nginx は argocd-server に通常の HTTP/1.1 をプロキシするため（configs.params.server.insecure: true）、純粋な gRPC はそこに到達しません。

Vault。 フローはより単純です。PKCE は不要です。コードをトークンに交換するのは Vault 自身だからです。OAuth アプリケーションのシークレットは Vault に保存されています。クライアントは http://localhost:8250/oidc/callback でリスナーを起動する必要があり（これは事前に allowedRedirectURIs に登録されています）、code、state、client_nonce を返します。state パラメータは Vault 自身が生成し、発行されたリンクの中に配置します。リダイレクトの検証にはそこから取得されます。トークンは renewable の間、auth/token/renew-self を介して延長されます。

Keycloak。 realm master の public クライアント platform-mcp-cli を介した Authorization Code + PKCE（bootstrap で一度だけ作成され、redirect は http://localhost:8280/oidc/callback）。ログインは FreeIPA。セッションには access_token（Admin API）が格納されます。kcadm の前に、サーバーはプライベートな kcadm.config を ~/.config/platform-mcp/ に書き込みます。共通の ~/.keycloak/kcadm.config ではありません。

トークンは子プロセスに環境変数のみを介して（Argo/Vault）またはプライベートな設定ファイルを介して（Keycloak）渡されます。argv では、ユーザーの任意のプロセスが ps で見ることができてしまうからです。環境変数は全体が継承されるわけではありません。CLI は必要なものだけを、隣接するサービスのシークレットなしで受け取ります。

セッションは ~/.config/argocd/config、~/.vault-token、~/.keycloak/kcadm.config ではなく、独自のファイルに保存されます。プロバイダーは更新時にトークンをローテーションするため、共通ファイルを使用すると、ターミナルの通常の CLI とこのサーバーが互いのセッションを無効化してしまうことになります。

開発

npm install
npm run build
npm test

テストは、コマンドの分類と禁止、シークレットの除去、ワンタイム確認トークン、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

サーバーの説明は2つの形式で重複しており、これは怠慢ではありません。Claude Code は .mcp.json を「名前 → サーバー」のフラットなマップとして読み取ります。mcpServers ラッパーがあると、サーバーを静かに認識しません。プラグインはインストールされ、有効として表示されますが、ツールは現れません。一方 Cursor は、自身の plugin.json の mcpServers からパスでファイルを取得し、動作するプラグインはラッパー付きの形式を使用します。command/args と env キーは一致します。Cursor の env 値はプレースホルダー ${VAR}（plugin.json の variables スキーマ、UI の Configure）、Claude の場合はリテラルなデフォルト値です。npm run check:manifests が2つの形式が乖離しないように監視します。

サーバーのコードはプラグインにコピーされません。両方のファイルが npx を介して公開パッケージを起動するため、プラグインは少数の小さなファイルのままであり、サーバーの変更時に再ビルドは不要です。

プッシュ前に変更を確認するには、ローカルパスからディレクトリを接続します：

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

公開

CI（.gitlab-ci.yml）は、vX.Y.Z 形式のタグによって、このプロジェクトの GitLab npm レジストリにパッケージを自動的に公開します。認証は組み込みの 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 ジョブは3つのマニフェストのバージョンと2つのサーバー記述の整合性を照合し、publish はタグのバージョンを package.json と照合します。これがないと、サーバーが新しくてもプラグインはユーザー側で「変更なし」のままになります。Claude Code と Cursor はどちらも、プラグインを更新するかどうかをその version で判断するからです。

プラグインを別途どこかにアップロードする必要はありません。main へのプッシュは保護されたブランチのミラーとして GitHub に送られ、ユーザーは /plugin marketplace update で変更を取得します。プラグインはタグではなくブランチからインストールされることに注意してください。修正が main に入るとすぐに、バージョンがまだタグでリリースされていなくても、すべてのユーザーが利用できるようになります。