SafeSelect

SafeSelect

Agentes podem consultar. Eles não podem alterar.

Acesso somente leitura a PostgreSQL & MongoDB para agentes de codificação.

Depure com contexto real de banco de dados, sem expor ferramentas de escrita.
Política local, com escopo de projeto—mesmo quando suas credenciais existentes permitem escritas.

Comece agora → · Demonstração · Agentes · Segurança · Documentação · Site

O que você pode fazer

• Inspecionar PostgreSQL — descubra tabelas, índices e planos de consulta; leia linhas limitadas.
• Explorar MongoDB — descubra coleções, infira esquemas amostrados e execute leituras limitadas.
• Reutilizar suas conexões — importe do DBeaver, Docker Compose ou MongoDB Compass.
• Conectar seu agente de codificação — instale uma entrada MCP fixada ao projeto/ambiente.
• Manter o controle — stdio local, política de projeto, segredos externos e metadados de auditoria.

[!IMPORTANT] Somente leitura se aplica às ferramentas de banco de dados do SafeSelect, não ao shell de um agente, a outros servidores MCP ou a credenciais diretas. Comece com dados de desenvolvimento ou uma réplica sanitizada e use usuários de banco de dados com privilégios mínimos. Revise o modelo de ameaças e limites antes de conectar dados sensíveis.

Veja em ação

Onboarding completo: do Homebrew a um agente protegido

Instale o SafeSelect via Homebrew, importe uma conexão DBeaver com suporte SSH, mantenha a senha no Keychain do macOS, instale a integração OpenCode e veja o agente ler um pedido pago enquanto sua tentativa de DELETE é rejeitada. Clipes focados no agente e no backend permanecem na galeria de demonstrações completa.

Início Rápido

Execute a configuração a partir da raiz do seu repositório. Você precisará de uma conexão PostgreSQL ou MongoDB e de um runtime Java 17+ para comandos de banco de dados.

1. Instalar

No macOS com Homebrew:

brew install antonillos/tap/safeselect

curl -fsSL https://raw.githubusercontent.com/antonillos/safeselect/main/packaging/install/install-release.sh | sh

asdf plugin add safeselect https://github.com/antonillos/asdf-safeselect.git
asdf install safeselect latest
SAFESELECT_VERSION="$(asdf latest safeselect | sed -n '$p')"
asdf set -u safeselect "${SAFESELECT_VERSION}"
asdf reshim safeselect "${SAFESELECT_VERSION}"

O SafeSelect usa qualquer runtime Java 17+ disponível em vez de exigir uma fórmula específica de gerenciador de pacotes. Se o Java estiver ausente ou muito antigo, instale ou selecione um runtime Java 17+ antes de executar comandos de banco de dados. No macOS com Homebrew, você pode instalar um com brew install openjdk@17.

2. Importar uma fonte de conexão

Escolha a fonte que você já usa; você não precisa executar todas as três:

Use seu diretório real de exportação ou do Compass. Siga os próximos passos do importador para configuração de driver e senha antes de continuar. Mantenha segredos fora dos arquivos do projeto. Para um passo a passo com suporte SSH, veja DBeaver → Codex.

3. Verificar e conectar seu agente

# Check configured environments; this can open SSH tunnels and contact databases.
safeselect check

# Install for OpenCode (replace with codex for OpenAI Codex).
safeselect agent install opencode

# Inspect the installed MCP entry and its configuration location.
safeselect agent status

Vários ambientes? Use safeselect check --environment <name> para evitar verificar bancos de dados não relacionados e adicione --environment <name> a agent install para selecionar o destino pretendido. A instalação infere o nome apenas quando há um único ambiente.

Abra ou reinicie seu agente e aprove o servidor MCP se solicitado. A instalação usa o escopo do usuário por padrão; veja agentes suportados e o guia de configuração do cliente para escopo de projeto e etapas específicas do cliente.

4. Tentar uma primeira leitura

Pergunte ao seu agente:

Use o SafeSelect para identificar o backend conectado e descobrir suas tabelas ou coleções disponíveis. Descreva uma e pare antes de consultar o conteúdo de linhas ou documentos. Siga as próximas sugestões apenas dentro desse escopo somente de descoberta.

Sucesso parece com: o agente chama database_info, usa as ferramentas correspondentes de descoberta de esquema e relata a estrutura encontrada. Nenhuma ferramenta de escrita ou senha de banco de dados é necessária na conversa.

Travou? Execute safeselect doctor --environment <name> para diagnósticos concisos (isso pode contatar o banco de dados) e siga o próximo passo relatado. Não afrouxe a política para contornar uma rejeição. Veja recuperação do agente.

{
  "mcpServers": {
    "safeselect-myapp-testing": {
      "command": "safeselect",
      "args": ["serve", "--project", "/path/to/myapp", "--environment", "testing"]
    }
  }
}

Documentação

Onde Ajuda

• Depure um aplicativo com dados realistas sem expor ferramentas de mutação.
• Deixe um agente inspecionar esquemas, índices, planos de consulta e linhas limitadas durante o desenvolvimento.
• Explore coleções MongoDB por meio de leituras limitadas e inferência de esquema amostrado.
• Reutilize conexões existentes do DBeaver, Docker Compose ou MongoDB Compass.
• Dê contexto de banco de dados aos agentes de codificação mantendo política, limites, segredos e auditoria sob seu controle.

Por que SafeSelect?

O SafeSelect é intencionalmente mais restrito do que servidores MCP de banco de dados de propósito geral. Não é um construtor de ferramentas, bancada SQL ou gateway remoto de banco de dados. É um limite de segurança local para agentes que precisam de visibilidade do banco de dados, não de poder sobre ele.

O Que Torna Diferente?

A combinação importa: inspeção de PostgreSQL e MongoDB, uma superfície fixa de leitura de banco de dados, stdio local, política de projeto, importação de conexão e evidência de segurança reproduzível. Modos somente leitura e controles em camadas também existem em outros projetos; eles não são exclusivos do SafeSelect.

Veja a comparação datada para DBHub, MongoDB MCP Server, Postgres MCP Pro e SchemaBrain—incluindo quando cada um é mais adequado.

Agentes podem consultar, mas não podem alterar por meio das ferramentas de banco de dados do SafeSelect. Este limite não cobre um shell, outro servidor MCP ou credenciais diretas também disponíveis para o agente. Use usuários de banco de dados com privilégios mínimos e revise o modelo de ameaças e limites.

Suporte de Backend

Arquitetura

O agente fala com o SafeSelect por meio de MCP stdio. O SafeSelect aplica política em Rust, armazena segredos fora dos arquivos do projeto e alcança bancos de dados por meio de um sidecar Java embutido: JDBC para backends SQL e o driver MongoDB para MongoDB. O canal Rust para Java é JSON-lines sobre stdin/stdout: sem sockets, sem portas abertas.

Contexto MCP Guiado

Clientes que suportam prompts MCP podem invocar read_only_database_debugging para uma lista de verificação segura de investigação. Clientes também podem ler safeselect://guide/read-only-database-debugging para o mesmo fluxo de trabalho estático e notas de limite. Nenhum desses recursos expõe dados de banco de dados, credenciais ou acesso de escrita; use as ferramentas de banco de dados abaixo para descoberta e leituras limitadas.

Fluxo de Trabalho do Agente

Agentes devem usar o SafeSelect nesta ordem:

1. database_info
2. list_tables e depois describe_table; inspecione list_table_indexes ou estatísticas limitadas quando útil para SQL
3. list_databases, list_collections e depois discover_document_schema para NoSQL
4. select / explain, ou a ferramenta de leitura MongoDB limitada que corresponde à tarefa
5. check, connect ou reconnect quando a conectividade estiver obsoleta

Agentes devem descobrir a estrutura de relações ou coleções antes de consultar dados desconhecidos e usar o next_suggestion de cada resposta de descoberta em vez de adivinhar nomes de colunas ou campos. Descrições SQL são metadados de catálogo; esquemas MongoDB são inferidos de uma amostra limitada e não exaustiva.

Documentos de consulta MongoDB devem permanecer valores JSON aninhados completos. Clientes que achatam argumentos de ferramentas aninhados podem passar filter, projection e sort como strings de objeto codificadas em JSON e pipeline como uma string de array codificada em JSON. redact_fields também aceita uma string de array codificada em JSON. Chaves achatadas são rejeitadas para que um filtro ou redação perdido nunca possa se tornar um fallback menos restrito.

JavaScript do lado do servidor MongoDB nunca está disponível: $where, $function e $accumulator são rejeitados recursivamente em filtros, projeções, ordenações e pipelines de agregação antes que o driver MongoDB os receba. Quando rejeitado, reconstrua a solicitação com operadores MQL declarativos; o SafeSelect não tem configuração que habilite JavaScript.

Respostas de consulta incluem row_count, byte_count, elapsed_ms e um valor elapsed legível por humanos para que agentes possam raciocinar sobre o tamanho do resultado e a latência.

Cada sucesso e erro MCP inclui um next_suggestion contextual. Agentes devem seguir essa única ação segura, nunca repetir cegamente uma solicitação inválida e parar quando a sugestão for terminal. Para clientes que mostram apenas um resumo de erro MCP, o SafeSelect também inclui a próxima sugestão confiável nesse resumo sem expor detalhes derivados do banco de dados.

Modelo de Segurança

• Falha fechada: violações de segurança encerram o processo MCP.
• Somente leitura: SQL permite SELECT, EXPLAIN e WITH; backends NoSQL permitem descoberta e leitura de documentos somente leitura.
• Sem JavaScript no servidor: $where, $function e $accumulator do MongoDB são rejeitados em Rust e novamente no sidecar Java.
• Acesso limitado: schemas, relações, bancos de dados e coleções podem ser permitidos ou negados.
• Limites rígidos: contagem de linhas, bytes de resultado e timeouts são aplicados; comandos de leitura do MongoDB recebem o mesmo timeout que maxTimeMS.
• Isolamento de segredos: senhas ficam no Keychain do macOS ou em variáveis de ambiente, nunca na configuração do projeto.
• Verificação de drivers: drivers JDBC são verificados por SHA-256 antes do uso.
• Trilha de auditoria: o texto da consulta é hash antes de ser registrado; a sessão atual expõe metadados de auditoria limitados por meio de audit_status e audit_recent.

Limites Deliberados

• SafeSelect não expõe gravações no banco de dados, migrações, administração ou execução arbitrária de comandos.
• PostgreSQL e MongoDB são os backends suportados hoje; uma ampla quantidade de conectores não é o objetivo.
• O transporte MCP é stdio local. SafeSelect não é um gateway de banco de dados remoto.
• A descoberta de schema do MongoDB é amostrada e limitada, não uma garantia exaustiva de schema.
• SafeSelect complementa o privilégio mínimo nativo do banco de dados; não o substitui.

Ferramentas MCP

get_maintenance_diagnostics suporta PostgreSQL 15, 16, 17 e 18.

Quando não existe um diretório .safeselect/, safeselect serve procura por serviços PostgreSQL do Compose. Se encontrar, entra automaticamente no modo de configuração: importa-os, escreve a configuração do projeto e inicia um servidor MCP somente de configuração. Caso contrário, imprime instruções de configuração e sai. Uma configuração existente, mas vazia ou inválida, é rejeitada, não substituída pela configuração.

[!IMPORTANT] O modo de configuração não expõe ferramentas de consulta. Agentes podem ajudar a importar e validar a configuração antes que qualquer ferramenta de inspeção de banco de dados esteja disponível.

Essenciais da CLI

Galeria visual de comandos

A CLI é mais fácil de escanear por tarefa do que como uma longa lista. A galeria de comandos web usa as mesmas capturas de demonstração sintéticas. query é mantido separado porque é um fluxo de trabalho SQL direto; agentes normalmente devem descobrir o schema primeiro por meio das ferramentas MCP.

safeselect import-dbeaver ~/Downloads/connections.zip

safeselect import-compose --path .

safeselect import-compass --path ~/.config/MongoDB Compass

safeselect config show --project demo --environment postgres

safeselect driver list

safeselect agent detect

safeselect check

safeselect doctor

safeselect posture --strict

safeselect serve

safeselect connect

safeselect disconnect

safeselect reconnect

safeselect query --sql "SELECT order_id, status, subtotal FROM public.demo_orders WHERE status = 'paid' LIMIT 3"

list_tables({"schema":"public"})

describe_table({"schema":"public","table":"demo_orders"})

get_maintenance_diagnostics({"schema":"public"})

list_databases()

list_collections({"database":"safeselect_demo"})

discover_document_schema({"database":"safeselect_demo","collection":"orders","sample_size":5})

find_documents({"database":"safeselect_demo","collection":"orders","filter":{"status":"paid"},"limit":3})

Use safeselect --help ou um --help específico de comando para a CLI completa.

A desinstalação verifica tanto os locais de binário do instalador de release quanto do Cargo. As importações do MongoDB Compass suportam conexões mongodb+srv:// com túnel SSH resolvendo o alvo SRV e reescrevendo o endpoint local com as opções necessárias de TLS e conexão direta.

Configuração

O estado global vive em ~/.config/safeselect/ por padrão. A política do projeto vive em .safeselect/ na raiz do repositório:

<repo-root>/
└── .safeselect/
    ├── project.toml
    └── environments/
        └── <env>.toml

SafeSelect caminha para cima a partir do diretório atual para encontrar .safeselect/. Use --project <path> quando um agente ou script deve mirar um repositório específico.

Convenção antes da configuração

A partir de um repositório configurado, os comandos inferem o projeto a partir do diretório .safeselect/ mais próximo e inferem o ambiente quando existe exatamente um arquivo environments/*.toml. Por exemplo, safeselect serve, safeselect check, safeselect query --sql "SELECT 1" e safeselect config show não precisam de flags de projeto ou ambiente em um projeto de ambiente único. --project e --environment permanecem disponíveis para scripts, outros diretórios de trabalho e seleção deliberada. Se existirem múltiplos ambientes, os comandos que atuam em um falham em vez de adivinhar e dizem para você passar --environment <name>.

Os padrões diferem por operação:

• serve, query, connect, disconnect, config show e comandos de senha exigem um ambiente explícito ou unicamente inferido. Sem ambientes, eles falham; serve tem o comportamento separado de primeira execução acima.
• check, doctor, posture, reconnect e config validate inspecionam ou processam todos os ambientes quando a flag é omitida. As verificações não são offline: elas podem resolver segredos, estabelecer túneis SSH e contatar bancos de dados. Use --environment <name> para evitar tocar em ambientes não relacionados ou de produção.
• query suporta apenas ambientes JDBC e ainda precisa de SQL através de --sql ou stdin (stdin interativo aguarda EOF). Selecionar um ambiente MongoDB não o transforma em um comando de consulta MongoDB.
• CLI connect e disconnect operam em um novo sidecar JDBC temporário e o encerram antes de sair. Eles não controlam uma sessão MCP já em execução; use as ferramentas de conexão MCP dessa sessão.
• Comandos de senha modificam o Keychain/configuração local, não a senha do banco de dados em si. config set-ssh-password alterna a autenticação SSH para senha e limpa a referência de arquivo de identidade configurada.

As entradas MCP geradas fixam deliberadamente tanto o projeto quanto o ambiente. Mantenha esses argumentos na configuração do cliente e em scripts não assistidos: a inferência é uma conveniência da CLI, não um ambiente padrão persistente.

Agentes Suportados

O SafeSelect nunca recai silenciosamente em um escopo mais amplo. Em particular, --local para Windsurf falha com uma correção clara porque o Windsurf não documenta uma configuração MCP com escopo de projeto.

Compilar a Partir do Código-Fonte

# Installs makevn through Homebrew or asdf only when it is missing.
./install.sh --install-makevn
"$HOME/.local/bin/safeselect" --version

Requisitos: Rust 1.85+ e Java 17+. O bootstrap requer Homebrew ou asdf; caso contrário, instale makevn primeiro. sshpass é opcional para túneis SSH baseados em senha. Adicione ~/.local/bin ao seu PATH antes de invocar safeselect sem o caminho completo.

Documentação

• Guia de instalação
• Integração com agentes de IA
• Revisão de código Codex sob demanda
• Modelo de segurança
• Prova de segurança
• Suíte de testes de segurança
• Política de segurança
• Distribuição
• Changelog

As notas de versão são geradas a partir de CHANGELOG.md.

Ecossistema

Licença

MIT - veja LICENSE.