Servidor MCP de CloudNativePG

Un servidor MCP para gestionar clústeres de PostgreSQL a través del operador CloudNativePG.

Esta versión utiliza el andamiaje (scaffold) de MCP Base para su estructura de servidor, autenticación, construcción de contenedores, gráfico de Helm, registro de prompts y banco de pruebas. La implementación manual anterior se conserva en deprecated-v1/ como referencia.

Superficie de herramientas

El servidor expone las herramientas de CloudNativePG de la implementación v1:

• 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

También incluye herramientas de administración del andamiaje MCP Base para la gestión de prompts:

• admin_reload_prompts

• admin_get_prompt_manifest

Related MCP server: PostgreSQL MCP Server

Estructura

• src/cnpg_mcp_server.py: punto de entrada HTTP de FastMCP para producción

• src/cnpg_mcp_test_server.py: punto de entrada de prueba sin autenticación/OIDC

• src/cnpg_mcp_tools.py: implementaciones y registro de herramientas de CloudNativePG

• src/mcp_context.py: envoltorio de contexto MCP con extracción de identidad de usuario

• src/auth_*.py: soporte de autenticación del andamiaje MCP Base

• chart/: activos de despliegue de Helm

• test/: banco de pruebas de plugins MCP

• SCAFFOLD_INVENTORY.md: hashes de artefactos del andamiaje MCP Base

Desarrollo

Cree un entorno e instale las dependencias:

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

Ejecute la prueba de humo de registro del andamiaje:

python bin/smoke_test.py

Ejecute la suite de pruebas MCP local sin autenticación:

python test/run-local-tests.py

Ejecute las pruebas de integración de Kubernetes de CloudNativePG adaptadas de deprecated-v1/test/plugins:

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

Estas pruebas crean, escalan, actualizan y eliminan recursos reales de CloudNativePG. Configuraciones opcionales útiles:

• CNPG_MCP_TEST_NAMESPACE: espacio de nombres para los recursos de prueba

• CNPG_MCP_TEST_CLUSTER_PREFIX: prefijo generado para el nombre del clúster

• CNPG_MCP_TEST_STORAGE_SIZE: tamaño de almacenamiento por instancia, por defecto 1Gi

• CNPG_MCP_TEST_CREATE_WAIT_SECONDS: tiempo de espera de preparación del clúster, por defecto 300

• CNPG_MCP_TEST_SCALE_WAIT_SECONDS: tiempo de espera de preparación del escalado, por defecto 300

Ejecución local

El punto de entrada del andamiaje utiliza transporte HTTP:

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

El servidor de pruebas se puede ejecutar sin autenticación:

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

Acceso a Kubernetes

Las herramientas utilizan el cliente de Python para Kubernetes. Cargan la configuración en este orden:

1. Configuración de la cuenta de servicio dentro del clúster

2. Kubeconfig local desde ~/.kube/config o KUBECONFIG

La mayoría de las herramientas aceptan un namespace opcional. Cuando se omite, se utiliza el espacio de nombres del contexto actual de Kubernetes, recurriendo a default.

Para despliegues de Helm dentro del clúster, el servidor utiliza la cuenta de servicio del despliegue. Por defecto, el gráfico otorga a esa cuenta de servicio permisos de CNPG y secretos solo en el espacio de nombres de la versión de Helm. Para gestionar recursos de CNPG en otro espacio de nombres, pase el argumento namespace de la herramienta y otorgue acceso a la cuenta de servicio allí:

rbac:
  targetNamespaces:
    - application-databases

Para un despliegue MCP compartido que deba operar en espacios de nombres arbitrarios, opte por RBAC a nivel de clúster:

rbac:
  clusterWide: true

El modo a nivel de clúster otorga acceso a secretos en todos los espacios de nombres, por lo que es preferible usar targetNamespaces explícitos cuando se conoce el conjunto de destino.

Despliegue

El andamiaje MCP Base incluye activos de Docker y Helm:

make build
make push
make helm-install

Utilice python bin/configure-make.py para generar make.env para la configuración de la imagen y el espacio de nombres antes de utilizar los objetivos de despliegue.