CloudNativePG MCP 서버

CloudNativePG 오퍼레이터를 통해 PostgreSQL 클러스터를 관리하기 위한 MCP 서버입니다.

이 버전은 서버 레이아웃, 인증, 컨테이너 빌드, Helm 차트, 프롬프트 레지스트리 및 테스트 하네스를 위해 MCP Base 스캐폴드를 사용합니다. 이전의 수동 구현은 참조를 위해 deprecated-v1/ 하위에 유지됩니다.

도구 인터페이스

이 서버는 v1 구현의 CloudNativePG 도구를 노출합니다:

• list_postgres_clusters

• get_cluster_status

• create_postgres_cluster

• scale_postgres_cluster

• delete_postgres_cluster

• list_postgres_roles

• create_postgres_role

• update_postgres_role

• delete_postgres_role

• list_postgres_databases

• create_postgres_database

• delete_postgres_database

또한 프롬프트 관리를 위한 MCP Base 스캐폴드 관리 도구도 포함되어 있습니다:

• admin_reload_prompts

• admin_get_prompt_manifest

Related MCP server: PostgreSQL MCP Server

레이아웃

• src/cnpg_mcp_server.py: 프로덕션 FastMCP HTTP 진입점

• src/cnpg_mcp_test_server.py: 인증 없음/OIDC 테스트 진입점

• src/cnpg_mcp_tools.py: CloudNativePG 도구 구현 및 등록

• src/mcp_context.py: 사용자 ID 추출 기능을 포함한 MCP 컨텍스트 래퍼

• src/auth_*.py: MCP Base 스캐폴드 인증 지원

• chart/: Helm 배포 자산

• test/: MCP 플러그인 테스트 하네스

• SCAFFOLD_INVENTORY.md: MCP Base 스캐폴드 아티팩트 해시

개발

환경을 생성하고 의존성을 설치합니다:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt -r test/requirements.txt

스캐폴드 등록 스모크 테스트를 실행합니다:

python bin/smoke_test.py

로컬 인증 없음 MCP 테스트 모음을 실행합니다:

python test/run-local-tests.py

deprecated-v1/test/plugins에서 조정된 CloudNativePG Kubernetes 통합 테스트를 실행합니다:

python test/run-local-tests.py --include-integration
# or
make test-integration

이 테스트들은 실제 CloudNativePG 리소스를 생성, 확장, 업데이트 및 삭제합니다. 유용한 선택적 설정:

• CNPG_MCP_TEST_NAMESPACE: 테스트 리소스를 위한 네임스페이스

• CNPG_MCP_TEST_CLUSTER_PREFIX: 생성된 클러스터 이름 접두사

• CNPG_MCP_TEST_STORAGE_SIZE: 인스턴스당 스토리지 크기, 기본값 1Gi

• CNPG_MCP_TEST_CREATE_WAIT_SECONDS: 클러스터 준비 시간 초과, 기본값 300

• CNPG_MCP_TEST_SCALE_WAIT_SECONDS: 확장 준비 시간 초과, 기본값 300

로컬 실행

스캐폴드 진입점은 HTTP 전송을 사용합니다:

python src/cnpg_mcp_server.py --host 0.0.0.0 --port 4200

테스트 서버는 인증 없이 실행할 수 있습니다:

python src/cnpg_mcp_test_server.py --host 127.0.0.1 --port 4201 --no-auth

Kubernetes 액세스

도구들은 Kubernetes Python 클라이언트를 사용합니다. 설정은 다음 순서로 로드됩니다:

1. 클러스터 내 서비스 계정 설정

2. ~/.kube/config 또는 KUBECONFIG의 로컬 kubeconfig

대부분의 도구는 선택적 namespace를 허용합니다. 생략 시 현재 Kubernetes 컨텍스트 네임스페이스가 사용되며, 기본값은 default입니다.

클러스터 내 Helm 배포의 경우, 서버는 배포 서비스 계정을 사용합니다. 기본적으로 차트는 해당 서비스 계정에 Helm 릴리스 네임스페이스 내의 CNPG 및 시크릿 권한만 부여합니다. 다른 네임스페이스에서 CNPG 리소스를 관리하려면 도구의 namespace 인수를 전달하고 해당 네임스페이스에 서비스 계정 액세스 권한을 부여하십시오:

rbac:
  targetNamespaces:
    - application-databases

임의의 네임스페이스에서 작동해야 하는 공유 MCP 배포의 경우, 클러스터 전체 RBAC를 선택하십시오:

rbac:
  clusterWide: true

클러스터 전체 모드는 네임스페이스 전반에 걸쳐 시크릿 액세스 권한을 부여하므로, 대상 세트가 알려진 경우 명시적인 targetNamespaces를 사용하는 것이 좋습니다.

배포

MCP Base 스캐폴드에는 Docker 및 Helm 자산이 포함되어 있습니다:

make build
make push
make helm-install

배포 대상을 사용하기 전에 python bin/configure-make.py를 사용하여 이미지 및 네임스페이스 설정을 위한 make.env를 생성하십시오.