mcp-percona-pg

mcp-percona-pg

Un servidor de Model Context Protocol para el Percona Operator for PostgreSQL. Permite que un cliente compatible con MCP (Claude Desktop, Claude Code, Cursor, …) opere clústeres de PostgreSQL + PgBouncer en Kubernetes — topología, agrupación de conexiones, ajuste, copias de seguridad/PITR, DR, extensiones y ciclo de vida — con un comportamiento controlado enteramente por banderas.

Impulsa los recursos personalizados del operador (PerconaPGCluster, PerconaPGBackup, PerconaPGRestore, PerconaPGUpgrade) a través de tu kube-config, de modo que el modelo funcione como ya lo haces: "escala dev-pg a 3 réplicas", "cambia la agrupación a modo transacción", "restaura prod-pg a las 12:00 UTC".

Seguro por defecto: inicia en modo solo lectura, puede limitarse a una lista permitida de espacios de nombres y clústeres, protege clústeres críticos de mutaciones, controla restauración / actualización / eliminación mediante opciones de aceptación separadas, y requiere confirmación escrita para acciones de alto impacto. Nunca lee ni devuelve credenciales de bases de datos.

Características

• Descubrimiento y estado — lista de clústeres, resumen por clúster y .status sin procesar (miembros de Patroni, disponibilidad de PostgreSQL/PgBouncer), puntos finales de conexión, copias de seguridad y restauraciones.
• Agrupación de conexiones — lectura y actualización de pool_mode de PgBouncer y los parámetros globales del grupo (default_pool_size, max_client_conn, …).
• Ajuste de PostgreSQL — lectura/fusión de parámetros mediante spec.patroni.dynamicConfiguration (la única vía segura para Patroni).
• Ciclo de vida — escalado de PostgreSQL/PgBouncer, pausa/reanudación, activación de extensiones integradas, copias de seguridad bajo demanda.
• DR y recuperación — restauración / recuperación a un punto en el tiempo, promoción de un standby, actualizaciones de versión mayor — cada una controlada individualmente.

Modelo de seguridad

Capa	Bandera	Efecto
Modo de acceso	PERCONA_MODE	read-only → read-write → admin; las herramientas con privilegios excesivos nunca se registran
Listas permitidas de espacios de nombres/clústeres	PERCONA_NAMESPACE_ALLOWLIST, PERCONA_CLUSTER_ALLOWLIST	delimitan lo que el agente puede tocar
Clústeres protegidos	PERCONA_PROTECTED_CLUSTERS	legibles, nunca mutados/restaurados/eliminados
Restauración / actualización / eliminación	PERCONA_ALLOW_RESTORE, PERCONA_ALLOW_UPGRADE, PERCONA_ALLOW_DELETE	opciones de aceptación separadas además del modo administrador
Confirmación	PERCONA_REQUIRE_CONFIRMATION	las operaciones de alto impacto requieren repetir el nombre del clúster
Simulación / auditoría	PERCONA_DRY_RUN, PERCONA_AUDIT_LOG	solo validación; línea de auditoría JSON por operación protegida

Herramientas

Lectura (read-only+): list_contexts, list_clusters, get_cluster, get_cluster_status, get_connection_info, get_pgbouncer_config, get_pg_parameters, list_backups, list_restores

Escritura (read-write+): scale_cluster, set_pgbouncer_config, set_pg_parameters, pause_cluster, toggle_builtin_extension, create_backup

Administración (admin): restore_cluster (requiere PERCONA_ALLOW_RESTORE), upgrade_cluster (requiere PERCONA_ALLOW_UPGRADE), promote_standby, delete_backup / delete_cluster (requieren PERCONA_ALLOW_DELETE)

Inicio rápido — añádelo a tu agente

Publicado en npm como @dockndevai/mcp-percona-pg. No se necesita clonar ni compilar — tu cliente MCP lo ejecuta bajo demanda con npx. Comienza en modo read-only; consulta .env.example para cada variable y docs/CLIENTS.md para la guía completa por cliente.

Claude Code (CLI)

claude mcp add percona-pg -e PERCONA_MODE="read-only" -e PERCONA_NAMESPACE="postgres-operator" -- npx -y @dockndevai/mcp-percona-pg

Claude Desktop · Cursor · Windsurf — el mismo bloque en claude_desktop_config.json, .cursor/mcp.json o ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "percona-pg": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-percona-pg"],
      "env": {
        "PERCONA_MODE": "read-only",
        "PERCONA_NAMESPACE": "postgres-operator"
      }
    }
  }
}

OpenAI Codex CLI — en ~/.codex/config.toml:

[mcp_servers.percona-pg]
command = "npx"
args = ["-y", "@dockndevai/mcp-percona-pg"]
env = { PERCONA_MODE = "read-only", PERCONA_NAMESPACE = "postgres-operator" }

Ejemplos de indicaciones

• "Lista los clústeres de PostgreSQL y muéstrame el estado de dev-pg."
• "¿Qué pool_mode está usando dev-pg y qué tamaño tiene el grupo predeterminado?" → get_pgbouncer_config
• "Configura dev-pg PgBouncer a agrupación por transacción con default_pool_size 25." (requiere read-write)
• "Aumenta shared_buffers a 512MB en dev-pg." (requiere read-write)
• "Haz una copia de seguridad completa de dev-pg en repo1." (requiere read-write)
• "Restaura dev-pg a 2026-08-30 12:00:00+00." (requiere admin + PERCONA_ALLOW_RESTORE + confirmación)

Requisitos previos

• Un clúster de Kubernetes que ejecute el Percona Operator for PostgreSQL v2 (pgv2.percona.com/v2).
• Un kube-config que el servidor pueda leer. Por seguridad, usa una ServiceAccount/RBAC limitada a los espacios de nombres del operador y a los recursos pgv2.percona.com que quieras que el agente vea.

Ejecutar desde el código fuente (desarrollo)

Prefiere el paquete publicado anteriormente. Para ejecutar desde un clon:

npm install
npm run build
node dist/index.js   # with the environment variables set

Desarrollo

npm run dev
npm test          # security policy + annotations
npm run typecheck

Publicación

Este servidor incluye un server.json para el registro oficial de MCP y un mcpName para la validación de propiedad en npm. Consulta PUBLISHING.md.

Licencia

MIT