platform-mcp

sonar-prod 클러스터의 인프라 서비스(Argo CD, Vault, Keycloak)를 위한 MCP 서버로, SSO 로그인(GitLab은 Argo/Vault, FreeIPA는 Keycloak)을 지원합니다.

왜 필요한가

에디터의 에이전트가 Argo CD, Vault, Keycloak에 접근해야 하지만, 서비스 계정을 발급할 수는 없습니다. 감사 로그에 사람 대신 공용 계정이 남고, 권한도 특정 개발자의 권한보다 넓어지기 때문입니다.

이 패키지는 로컬에 설치되어 브라우저를 통한 일반적인 SSO 로그인을 수행합니다. 이후 로그인한 사용자의 신분으로 명령을 실행합니다. 감사 로그에는 실제 로그인이 기록되고, 권한은 그룹 멤버십이 부여하는 만큼만 정확히 부여됩니다.

서비스별 도구는 정확히 하나씩입니다 — argocd_exec, vault_exec, keycloak_exec이며, 명령줄 인자를 받습니다. 내부적으로는 공식 CLI(argocd, vault, kcadm)를 사용하므로 이들이 지원하는 모든 기능을 사용할 수 있습니다. 새 서비스는 인터페이스 구현 하나로 추가됩니다.

Related MCP server: mcp-read-only-argocd

설치

1단계. 패키지 레지스트리 접근

아래 모든 방법에 공통으로 한 번만 필요합니다. 패키지는 공개 npm이 아니라 이 GitLab 프로젝트의 npm 레지스트리에 있습니다. read_package_registry 권한이 있는 토큰(개인 액세스 토큰 또는 프로젝트 deploy 토큰)을 발급받아 ~/.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

주소는 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 패키지와 내부 서비스 주소가 있는데, 이 주소는 어차피 네트워크 내부에서만 resolve됩니다. 저장소에는 비밀이 없어야 하고 없을 것입니다. 액세스 토큰은 서버가 ~/.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는 네트워크 내부에서만 resolve됩니다. 외부에서는 공개 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은 master realm의 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/"]
  }
}

서비스 하나의 주소만 설정해도 충분합니다. 나머지는 도구 목록에 표시되지 않을 뿐입니다.

세션이 없거나 만료된 경우 도구는 이해하기 쉬운 오류를 반환하고, 에이전트는 대화창에서 바로 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가 아님). 일반 OIDC 사용자에게 sys/mounts는 종종 403입니다 — discovery에 사용하지 마세요. kv list의 exit code 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을 지원하면 일반 대화 상자가 표시됩니다. 지원하지 않으면 대체 방식이 작동합니다. 첫 번째 호출은 영향 설명과 일회용 토큰을 반환하고, 이 토큰을 사용한 두 번째 호출이 작업을 실행합니다. 토큰은 5분간 유효하며 특정 인자에 바인딩되므로 "하나를 확인하고 다른 것을 실행"할 수 없고, 에이전트가 스스로 토큰을 만들어낼 수도 없습니다.

Keycloak은 예외입니다. 변경 작업은 즉시 실행되지만 응답에 에이전트용 warning이 추가됩니다. 구성이 CR/operator를 통해 전달되므로 kcadm을 통한 수동 수정은 sync 시 operator가 덮어쓸 수 있습니다. 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은 별도의 Go 바이너리가 아닌 Java 스크립트이기 때문입니다.

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은 구성에 truststore가 없으면 인증서 검증 건너뛰기가 활성화됩니다(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. 로그인은 Dex를 통한 Authorization Code + PKCE입니다. Argo CD가 Dex에 자동으로 등록하는 public 클라이언트 argo-cd-cli가 사용되며, redirect URI http://localhost:8085/auth/callback도 함께 등록되므로 설치를 위해 argocd-cm을 변경할 필요가 없습니다. Argo CD는 access_token이 아닌 id_token을 Bearer로 받습니다 — Dex의 access_token은 불투명하며 API 서버가 검증하지 않습니다. 토큰은 refresh 토큰으로 갱신됩니다.

CLI는 --grpc-web으로 실행됩니다: ingress-nginx가 일반 HTTP/1.1을 argocd-server로 프록시하며(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. master realm의 public 클라이언트 platform-mcp-cli를 통한 Authorization Code + PKCE(bootstrap에서 한 번 생성, redirect http://localhost:8280/oidc/callback). 로그인은 FreeIPA입니다. 세션에는 access_token(Admin API)이 저장됩니다. kcadm 실행 전에 서버는 ~/.config/platform-mcp/에 개인 kcadm.config를 씁니다 — 공용 ~/.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

테스트는 명령 분류와 금지 규칙, 시크릿 제거, 일회용 확인 토큰, CLI 실행 시 shell 부재, 자체 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는 자체 plugin.json의 mcpServers 경로에서 파일을 가져오며, Cursor용 작업 플러그인은 래퍼가 있는 형식을 사용합니다. command/args와 env 키는 일치합니다; Cursor의 env 값은 ${VAR} 플레이스홀더(plugin.json의 variables 스키마, UI의 Configure)이고, Claude의 값은 리터럴 기본값입니다. npm run check:manifests가 두 형식이 어긋나지 않도록 관리합니다.

서버 코드는 플러그인에 복사되지 않습니다: 두 파일 모두 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 작업은 세 매니페스트의 버전과 두 서버 설명의 일관성을 검증하고, publish는 태그의 버전과 package.json을 대조합니다. 이 검증이 없으면 서버가 새 버전인데도 사용자의 플러그인은 "변경되지 않음"으로 남게 됩니다: Claude Code와 Cursor 모두 플러그인 업데이트 여부를 version으로 결정하기 때문입니다.

플러그인을 별도로 배포할 필요는 없습니다: main으로의 푸시는 보호된 브랜치 미러로 GitHub에 전송되며, 사용자는 /plugin marketplace update로 변경 사항을 받습니다. 플러그인은 태그가 아닌 브랜치에서 설치된다는 점에 유의하세요: 수정 사항이 main에 들어가는 즉시 버전이 태그로 아직 릴리스되지 않았어도 모든 사용자가 사용할 수 있습니다.