mcp-percona-pg

mcp-percona-pg

Um servidor Model Context Protocol para o Percona Operator for PostgreSQL. Ele permite que um cliente compatível com MCP (Claude Desktop, Claude Code, Cursor, …) opere clusters PostgreSQL + PgBouncer no Kubernetes — topologia, pool de conexões, ajustes, backups/PITR, DR, extensões e ciclo de vida — com o comportamento controlado inteiramente por flags.

Ele aciona os recursos personalizados do operador (PerconaPGCluster, PerconaPGBackup, PerconaPGRestore, PerconaPGUpgrade) através do seu kube-config, então o modelo funciona da mesma forma que você já trabalha: "escalar dev-pg para 3 réplicas", "alternar pooling para modo transacional", "restaurar prod-pg para 12:00 UTC".

Seguro por padrão: ele inicia somente leitura, pode ser limitado a uma lista de permissões de namespaces e clusters, protege clusters críticos de mutações, controla restauração / upgrade / exclusão por opt-ins separados e exige confirmação digitada para ações de alto impacto. Ele nunca lê ou retorna credenciais de banco de dados.

Recursos

• Descoberta e status — lista clusters, resumo por cluster e .status bruto (membros Patroni, prontidão PostgreSQL/PgBouncer), endpoints de conexão, backups e restaurações.
• Pool de conexões — lê e atualiza pool_mode do PgBouncer e os ajustes globais do pool (default_pool_size, max_client_conn, …).
• Ajustes do PostgreSQL — lê/mescla parâmetros via spec.patroni.dynamicConfiguration (o único caminho seguro para Patroni).
• Ciclo de vida — escala PostgreSQL/PgBouncer, pausa/retoma, alterna extensões integradas, backups sob demanda.
• DR e recuperação — restauração / recuperação point-in-time, promoção de standby, upgrades de versão principal — cada um com controle individual.

Modelo de segurança

Camada	Flag	Efeito
Modo de acesso	PERCONA_MODE	read-only → read-write → admin; ferramentas com privilégios excessivos nunca são registradas
Listas de permissão de namespace/cluster	PERCONA_NAMESPACE_ALLOWLIST, PERCONA_CLUSTER_ALLOWLIST	limita o que o agente pode acessar
Clusters protegidos	PERCONA_PROTECTED_CLUSTERS	legíveis, nunca mutados/restaurados/excluídos
Restauração / upgrade / exclusão	PERCONA_ALLOW_RESTORE, PERCONA_ALLOW_UPGRADE, PERCONA_ALLOW_DELETE	opt-ins separados além do modo admin
Confirmação	PERCONA_REQUIRE_CONFIRMATION	operações de alto impacto exigem repetir o nome do cluster
Dry-run / auditoria	PERCONA_DRY_RUN, PERCONA_AUDIT_LOG	somente validação; linha de auditoria JSON por operação protegida

Ferramentas

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

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

Admin (admin): restore_cluster (requer PERCONA_ALLOW_RESTORE), upgrade_cluster (requer PERCONA_ALLOW_UPGRADE), promote_standby, delete_backup / delete_cluster (requerem PERCONA_ALLOW_DELETE)

Início rápido — adicione ao seu agente

Publicado no npm como @dockndevai/mcp-percona-pg. Sem necessidade de clone ou build — seu cliente MCP o executa sob demanda com npx. Comece no modo read-only; veja .env.example para todas as variáveis e docs/CLIENTS.md para o guia completo 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 — mesmo bloco em claude_desktop_config.json, .cursor/mcp.json ou ~/.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 — em ~/.codex/config.toml:

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

Exemplos de prompts

• "Liste os clusters PostgreSQL e mostre o status de dev-pg."
• "Qual pool_mode o dev-pg está usando e qual o tamanho do pool padrão?" → get_pgbouncer_config
• "Configure o PgBouncer do dev-pg para pooling transacional com default_pool_size 25." (requer read-write)
• "Aumente shared_buffers para 512MB no dev-pg." (requer read-write)
• "Faça um backup completo de dev-pg para repo1." (requer read-write)
• "Restaure dev-pg para 2026-08-30 12:00:00+00." (requer admin + PERCONA_ALLOW_RESTORE + confirmação)

Pré-requisitos

• Um cluster Kubernetes executando o Percona Operator for PostgreSQL v2 (pgv2.percona.com/v2).
• Um kube-config que o servidor possa ler. Por segurança, use um ServiceAccount/RBAC limitado aos namespaces do operador e aos recursos pgv2.percona.com que você deseja que o agente veja.

Executar a partir do código-fonte (desenvolvimento)

Prefira o pacote publicado acima. Para executar a partir de um clone:

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

Desenvolvimento

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

Publicação

Este servidor inclui um server.json para o registro oficial do MCP e um mcpName para validação de propriedade no npm. Veja PUBLISHING.md.

Licença

MIT