pgEdge PostgreSQL MCP Server

Servidor MCP pgEdge Postgres e Agente de Linguagem Natural

• Sobre o Servidor MCP pgEdge Postgres
  • Servidor MCP pgEdge Postgres
  • Escolhendo a Solução Certa
  • Melhores Práticas - Consultando o Servidor
• Instalando o Servidor MCP
  • Início Rápido
  • Demonstração de Início Rápido com Northwind
  • Implantação no Docker
  • Implantação a partir do Código-Fonte
  • Testando a Implantação do Servidor MCP
• Configurando o Servidor MCP
  • Especificando Preferências de Configuração
  • Usando Variáveis de Ambiente para Especificar Opções
  • Incluindo Embeddings de Provedores em um Arquivo de Configuração
  • Configurando o Agente para Múltiplos Bancos de Dados
  • Configurando Serviços de Suporte; HTTP, systemd e nginx
  • Usando um Arquivo de Segredo de Criptografia
  • Habilitando ou Desabilitando Recursos
• Configurando e Usando um Aplicativo Cliente
  • Conectando com o Cliente Web
  • Usando o Cliente de Chat Go
  • Configurando o Servidor para uso com Claude Desktop
  • Configurando o Servidor para uso com Cursor
• Revisando os Logs do Servidor
• Autenticação e Segurança
  • Autenticação - Visão Geral
  • Autenticação - Gerenciamento de Usuários
  • Autenticação - OAuth
  • Autenticação - Gerenciamento de Tokens
  • Checklist de Segurança
  • Gerenciamento de Segurança
• Referência
  • Usando Ferramentas MCP
  • Usando Recursos MCP
  • Usando Prompts MCP
  • Referência de Erros
  • Arquivo de Configuração do Servidor
  • Arquivo de Configuração de Tokens de API
  • Detalhes de Configuração do Cliente CLI
• Tópicos Avançados
  • Criando Definições Personalizadas
  • Configurando e Usando a Busca na Base de Conhecimento
  • Usando o Proxy LLM
  • Segurança em Nível de Linha e Coluna
  • Implantação Distribuída
• Para Desenvolvedores
  • Para Desenvolvedores - Visão Geral
  • Protocolo MCP
  • Referência da API
  • Navegador da API
  • Exemplos de Clientes
  • Construindo Clientes de Chat
    • Visão Geral
    • Python (Stdio + Claude)
    • Python (HTTP + Ollama)
• Contribuindo
  • Configuração de Desenvolvimento
  • Arquitetura
  • Arquitetura Interna
  • Testes
  • CI/CD
• Acessando a Ajuda Online
• Solução de Problemas
• Notas de Versão
• Licença

O servidor pgEdge Postgres Model Context Protocol (MCP) permite consultas SQL em bancos de dados PostgreSQL por meio de clientes compatíveis com MCP. O Agente de Linguagem Natural fornece funcionalidades de suporte que permitem usar linguagem natural para formular consultas SQL.

Versões Suportadas: PostgreSQL 14 e superiores.

NÃO PARA APLICAÇÕES PÚBLICAS: Este servidor MCP fornece aos LLMs acesso de leitura a todo o esquema e dados do seu banco de dados. Ele deve ser usado apenas para ferramentas internas, fluxos de trabalho de desenvolvedores ou ambientes onde todos os usuários são confiáveis. Para aplicações voltadas ao público, considere o pgEdge RAG Server em vez disso. Consulte o guia Escolhendo a Solução Certa para obter detalhes.

Início Rápido

O guia de Início Rápido cobre a instalação e configuração para todos os clientes suportados:

Cliente	Transporte	Melhor Para
CLI (Stdio)	Stdio	Desenvolvimento local de usuário único
CLI (HTTP)	HTTP	Acesso multiusuário ou remoto
Interface Web	HTTP	Interface de chat baseada em navegador
Claude Code	Stdio	Agente CLI da Anthropic
Claude Desktop	Stdio	Aplicativo de desktop da Anthropic
Cursor	Stdio	Editor de código com IA
Windsurf	Stdio	Editor de código Codeium
VS Code Copilot	Stdio	Agente GitHub Copilot

Para uma demonstração guiada com dados de exemplo, consulte a Demonstração de Início Rápido com Northwind.

Principais Recursos

• Proteção Somente Leitura - Todas as consultas são executadas em transações somente leitura por padrão
• Recursos - Acesse estatísticas do PostgreSQL e muito mais
• Ferramentas - Execução de consultas, análise de esquema, busca híbrida avançada (BM25+MMR), geração de embeddings, leitura de recursos e muito mais
• Prompts - Fluxos de trabalho guiados para configuração de busca semântica, exploração de banco de dados, diagnóstico de consultas e muito mais
• Cliente de Chat de Produção - Cliente Go completo com cache de prompts da Anthropic (redução de 90% nos custos)
• Modo HTTP/HTTPS - Acesso direto à API com autenticação de usuário e token
• Interface Web - Interface moderna baseada em React com chat com IA para interação com banco de dados em linguagem natural
• Suporte a Docker - Imagens pré-construídas no GitHub Container Registry com implantação via Docker Compose
• Seguro - Suporte a TLS, autenticação de usuário e token, aplicação de somente leitura
• Recarga Automática - Recarga automática de arquivos de autenticação sem reiniciar o servidor

Desenvolvimento

Pré-requisitos

• Go 1.21 ou superior
• PostgreSQL 14 ou superior (para testes)
• golangci-lint v1.x (para linting)

Configuração do Linter

O projeto usa golangci-lint v1.x. Instale-o com:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Observação: O arquivo de configuração .golangci.yml é compatível com golangci-lint v1.x (não v2).

Compilação

git clone https://github.com/pgEdge/pgedge-postgres-mcp.git
cd pgedge-postgres-mcp
make build

Testes

# Run all tests
make test

# Run server tests with a database
export TEST_PGEDGE_POSTGRES_CONNECTION_STRING=\
  "postgres://localhost/postgres?sslmode=disable"
go test ./...

# Run with coverage
go test -v -cover ./...

# Run linting
make lint

Testes da Interface Web

A interface web possui uma suíte de testes abrangente. Consulte web/TEST_SUMMARY.md para obter detalhes.

cd web
npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage

Segurança

• Aplicação de transações somente leitura (configurável por banco de dados)
• Autenticação de usuário e token de API com expiração
• Suporte a TLS/HTTPS
• Hash SHA256 de tokens
• Aplicação de permissões de arquivo (0600)
• Validação e sanitização de entrada

Consulte o Guia de Segurança para documentação abrangente de segurança.

Solução de Problemas

Ferramentas não visíveis no Claude Desktop?

• Use caminhos absolutos na configuração
• Reinicie o Claude Desktop completamente
• Verifique a sintaxe do JSON

Erros de conexão com o banco de dados?

• Certifique-se de que a conexão com o banco de dados esteja configurada antes de iniciar o servidor (via arquivo de configuração, variáveis de ambiente ou flags de linha de comando)
• Verifique se o PostgreSQL está em execução: pg_isready
• Verifique se os parâmetros de conexão estão corretos

Consulte o Guia de Solução de Problemas para soluções detalhadas.

Suporte

Para relatar um problema com o software, visite: GitHub Issues

Para mais informações, visite docs.pgedge.com

Este projeto é licenciado sob a Licença PostgreSQL.