Gatekeeper
I tuoi agenti propongono l'SQL. Tu approvi cosa viene eseguito.
Gatekeeper è un ponte approvato da un umano tra gli agenti AI e il tuo database. Un agente propone una query tramite MCP; di default non viene eseguito nulla finché non la approvi in Beekeeper Studio, sul testo SQL, prima dell'esecuzione. La query viene poi eseguita sulla connessione che Beekeeper ha già aperto e le righe tornano all'agente.
Sola lettura di default. Una scrittura viene eseguita solo con una modalità che attivi tu stesso nel plugin, e quella modalità è temporanea. L'agente non ha mai accesso alle credenziali del tuo database.
Musica da #Uppbeat
Shine by Swoop: https://uppbeat.io/t/swoop/shineSuggerimento
Modalità automatica beta: abilita esplicitamente l'approvazione automatica per un sottoinsieme ristretto di letture PostgreSQL. Devono passare sia i controlli locali sia Jev. Vedi Modalità automatica per configurazione, condivisione con il provider e limitazioni.
I tre componenti
| Componente | Cosa fa | Dove gira |
|---|---|---|
| Plugin per Beekeeper Studio | Mostra ogni query proposta, ne classifica il rischio e la esegue sulla tua connessione dopo la tua approvazione | Dentro Beekeeper Studio |
| Server MCP | Il lato rivolto all'agente: gli strumenti che un agente chiama per proporre una query e raccoglierne il risultato | Sulla tua macchina, avviato dal tuo agente |
| Skill per agenti | Insegna a qualsiasi agente a usare bene quegli strumenti | Nella cartella delle skill del tuo agente |
Vengono distribuiti insieme con un'unica versione e sono utili insieme: il plugin senza il server non ha nulla da approvare, il server senza il plugin non ha nessuno a cui chiedere.
Perché
- Approvazione manuale di default. La modalità automatica è opzionale e temporanea. La fonte dell'approvazione e l'attribuzione del valutatore, se disponibile, vengono registrate.
- Nessuna credenziale del database esce da Beekeeper. Le query passano dalla sua connessione già autenticata. Collega Beekeeper a una replica in lettura o a un ruolo in sola lettura per una protezione definitiva.
- Il rischio viene classificato, non presunto. Un parser che conosce il dialetto classifica ogni query come lettura, scrittura o distruttiva, e il pulsante Approva resta bloccato finché non attivi la modalità corrispondente.
Come funziona
MCP client Gatekeeper server (127.0.0.1) Beekeeper Studio
┌────────────────────┐ MCP ┌───────────────────────────┐ fetch ┌────────────────────┐
│ submit_query(sql) │ ───────► │ MCP server + HTTP broker │ ◄─────── │ Plugin (iframe) │
│ get_query_result() │ ◄─────── │ SQLite lease queue + audit│ poll │ 1. show SQL │
│ cancel_query() │ │ /pending /executing │ ───────► │ 2. human approves │
│ │ │ /result /lease/renew │ result │ 3. runQuery() │
└────────────────────┘ └───────────────────────────┘ │ 4. post result │
└────────────────────┘
- L'agente invia una proposta e riceve subito un id di richiesta. Niente si blocca.
- Il plugin interroga il broker locale, prende in carico la proposta con un lease e mostra l'SQL.
- Tu approvi o rifiuti. Se approvi, Beekeeper esegue la query sulla tua connessione.
- Il plugin invia l'esito e l'agente lo raccoglie quando è pronto.
Il plugin gira in un iframe sandbox, quindi non può mai ricevere una connessione in entrata: interroga invece il broker. Questo unico vincolo spiega tutta la struttura. Tutti i dettagli in Architettura.
Per iniziare
Prerequisiti: Beekeeper Studio >= 5.4 e Node >= 22. Se usi Claude Code o Codex CLI hai già Node. Non c'è nessun servizio in background da installare: il tuo agente avvia il server quando si apre la sessione e il server si chiude quando la sessione finisce.
Attenzione
Solo macOS, per ora. Gatekeeper è sviluppato e testato su macOS. Windows e Linux non sono ancora testati, quindi considerali non supportati finché qualcuno non dà un riscontro. Nel codice distribuito nulla è specifico di macOS (il server ricava i percorsi dalla tua home directory, il plugin è una webview standard di Beekeeper), quindi dovrebbero funzionare entrambi, ma "dovrebbe" non significa verificato. Le segnalazioni da entrambe le piattaforme sono benvenutissime.
Installazione rapida
Una skill dedicata configura tutto per te: il plugin, il server MCP, la skill companion e l'abbinamento. Aggiungi le skill al tuo agente:
npx skills add Gldywn/gatekeeper
Poi chiedi al tuo agente di installare Gatekeeper, oppure esegui direttamente la skill:
/install-gatekeeper
Esegue tutti i passaggi che il tuo ambiente consente e ti lascia una breve checklist per il resto, come riavviare Beekeeper. In seguito, /update-gatekeeper controlla tutti e tre i componenti e aggiorna solo quelli non aggiornati.
Installazione manuale
Preferisci farlo a mano, o vuoi vedere esattamente cosa succede?
Importante
Non è ancora nel registro dei plugin di Beekeeper. È in corso una richiesta con i maintainer di Beekeeper. Finché non viene accettata, Gestisci plugin non elencherà Gatekeeper e l'installazione con un clic non è disponibile, quindi il passaggio 1 qui sotto è la via manuale. Nient'altro cambia.
1. Installa il plugin in Beekeeper Studio. Scarica gatekeeper-<version>.zip dalla release più recente, estrailo nella cartella dei plugin di Beekeeper e riavvia Beekeeper:
| OS | Cartella dei plugin |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/plugins/ |
| Linux | ~/.config/beekeeper-studio/plugins/ |
| Windows | %APPDATA%\beekeeper-studio\plugins\ |
La cartella estratta deve chiamarsi esattamente
gatekeeper. Lo zip si estrae ingatekeeper-<version>/, quindi rinominala dopo l'estrazione. Beekeeper confronta il nome della cartella con l'id del plugin e salta senza dire nulla ogni cartella che non corrisponde: nessun errore, nessuna voce in Gestisci plugin, niente da cliccare. È il motivo più comune per cui un'installazione manuale sembra non fare nulla.
2. Registra il server MCP nel tuo agente. Questa è anche l'installazione del server: npx lo scarica e lo mette in cache al primo avvio.
# Claude Code
claude mcp add gatekeeper --scope user -- npx -y @gldywn/gatekeeper-mcp-server
# Codex CLI, in ~/.codex/config.toml
[mcp_servers.gatekeeper]
command = "npx"
args = ["-y", "@gldywn/gatekeeper-mcp-server"]
Preferisci pnpm? pnpm dlx @gldywn/gatekeeper-mcp-server è l'equivalente diretto della riga npx. Per risolvere il pacchetto una volta sola invece che a ogni avvio dell'agente, installalo con pnpm add -g @gldywn/gatekeeper-mcp-server e punta il tuo client al binario gatekeeper-mcp-server che aggiunge al tuo PATH.
Qualsiasi client che legge .mcp.json può usare .mcp.json.example così com'è. Fissa la versione (@gldywn/gatekeeper-mcp-server@<version>) se preferisci verificare gli aggiornamenti invece di riceverli: senza versione fissa, npx risolve di nuovo l'ultima release a ogni avvio dell'agente, il che ti tiene aggiornato ma significa che un processo con accesso al tuo database cambia a tua insaputa.
3. Installa la skill per l'agente.
npx skills add Gldywn/gatekeeper
La CLI è interattiva: ti chiede per quali agenti installare e se installare globalmente. Funziona con Claude Code, Codex, Cursor e gli altri.
4. Abbina il plugin, una volta per macchina. Avvia il tuo agente, poi chiedigli qualcosa che richieda il database. Finché il plugin non è abbinato, ogni strumento di Gatekeeper risponde con un codice di 6 cifre: inserisci quel codice nel plugin (Tools -> Gatekeeper). Il codice è monouso e dura circa cinque minuti, e http://127.0.0.1:9999/pair mostra sempre quello attuale. Il token di capability che consegna viene conservato nello storage cifrato di Beekeeper.
Su quella porta non risponde nulla finché il tuo agente non ha avviato il server almeno una volta. Se apri il plugin prima, te lo dice, invece di mostrarti un campo di abbinamento che non può funzionare.
5. Usalo. Chiedi al tuo agente qualcosa che richieda il database. Propone l'SQL, la query compare nel plugin, tu approvi e le righe tornano all'agente. Le letture funzionano subito; una scrittura viene eseguita solo dopo che attivi la modalità Write o Destructive.
La compilazione dai sorgenti è documentata in Sviluppo.
Se il plugin non compare
Beekeeper viene distribuito con il sistema di plugin bloccato, quindi un'installazione nuova può ignorare completamente un plugin di terze parti. Tre cose da controllare, in ordine:
1. Il nome della cartella. Esattamente gatekeeper, non gatekeeper-0.1.1. Una mancata corrispondenza viene saltata in silenzio, come sopra.
2. Il sistema di plugin è abilitato. I valori predefiniti di Beekeeper impostano pluginSystem.disabled = true, con una allowlist che contiene solo i suoi due plugin. Aggiungi questo alla tua configurazione utente, poi riavvia:
[pluginSystem]
disabled = false
3. I plugin della community sono abilitati. Anche communityDisabled = true è un valore predefinito, e disabilita qualsiasi plugin che Beekeeper classifica come community. Se il gestore dei plugin mostra “Community plugins are disabled via configuration”, aggiungi communityDisabled = false nello stesso blocco.
| OS | File di configurazione utente |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/user.config.ini |
| Linux | ~/.config/beekeeper-studio/user.config.ini |
| Windows | %APPDATA%\beekeeper-studio\user.config.ini |
Modalità di accesso
Di default, ogni query richiede il clic di un umano sul suo testo. La modalità di esecuzione decide quali classi di rischio possono essere eseguite. La modalità automatica è separata e, quando è attiva, forza la sola lettura.
| Modalità | Approva | Attivata da |
|---|---|---|
| Read (predefinita) | SELECT e simili |
Niente da fare |
| Write | INSERT, UPDATE |
Tu, nel plugin, con una seconda conferma |
| Destructive | DELETE, DROP, TRUNCATE, ALTER |
Tu, nel plugin, con una seconda conferma |
La modalità attivata resta solo in memoria, non viene mai salvata e torna alla sola lettura quando cambi connessione o rifai l'abbinamento. Il plugin riclassifica e ricontrolla al momento dell'esecuzione, quindi attivazione e disattivazione hanno effetto immediato.
La scheda legge la query per te, così decidere richiede un'occhiata invece di un'analisi attenta. L'SQL arriva formattato ed evidenziato, con i caratteri invisibili e quelli che invertono la direzione mostrati come marcatori espliciti, così ciò che leggi è ciò che viene eseguito. Un'istruzione di scrittura o distruttiva ha un badge colorato della sua classe e indica il verbo e le tabelle coinvolte, mentre un'istruzione che il parser non riesce a leggere lo segnala con un testo fisso e viene trattata come distruttiva.
Sotto l'SQL, un'annotazione indica le tabelle lette dalla query e le colonne sensibili tra queste: i dati personali con un colore, i dati aziendali e commerciali con un altro, un valore sensibile segnalato anche quando compare solo in un filtro WHERE, e un SELECT * espanso sulle colonne reali così niente si nasconde dietro l'asterisco. Un punto sull'icona del database nell'intestazione mostra se l'ultimo controllo della connessione è andato a buon fine, e l'icona apre i dettagli: quel controllo, poi i tre livelli di sola lettura (la modalità attivata, la connessione di Beekeeper e l'endpoint del database). Il robot accanto mostra il collegamento al server Gatekeeper a cui i tuoi agenti inviano le query. È verde quando il server risponde, ambra durante la connessione e barrato in rosso quando non è raggiungibile; passandoci sopra vedi quando il server ha risposto l'ultima volta.
Ogni rilevatore si attiva o disattiva nelle impostazioni del plugin, girano tutti sulla tua macchina e nulla di ciò che rilevano viene mai inviato all'agente. Confrontano nomi di colonne e formati dei valori, quindi considerali un rapido indicatore di ciò che merita una seconda occhiata, non la prova che una query sia pulita. L'assenza di segnalazioni può anche significare che l'annotazione non è stata risolta.
Sicurezza
- Il controllo sta dove avviene l'esecuzione. Il plugin è l'unico componente che può eseguire una query, quindi è lì che risiedono il classificatore e il controllo della modalità.
- Token di capability su ogni richiesta. Senza, il broker risponde
401. Viene generato al primo avvio, salvato con permessi0600in~/.gatekeepere conservato dal plugin nello storage cifrato di Beekeeper. - Abbinamento tramite codice. Il broker non riesce a distinguere il plugin da una qualsiasi pagina web che visiti, quindi il token passa su un canale che una pagina non può osservare: un codice monouso di 6 cifre che leggi con i tuoi occhi, valido cinque minuti e annullato dopo cinque tentativi sbagliati.
- Solo loopback. Il broker si collega a
127.0.0.1e rifiuta headerHostinattesi, quindi una pagina di DNS rebinding riceve un421. - Risultati limitati, audit minimo. Le righe inoltrate sono limitate per numero e byte, così una lettura massiva non inonda mai il contesto dell'agente. L'audit lato agente conserva la decisione e un digest dell'SQL, mai l'SQL grezzo e mai le righe.
La lettura non garantisce zero effetti collaterali: una SELECT può chiamare una funzione volatile, ed è proprio per questo che l'approvazione avviene sull'SQL visibile. SECURITY.md contiene il threat model, il confine di fiducia dello stesso utente, i tempi di conservazione e la policy sulla supply chain.
Documentazione
| Documento | Contenuto |
|---|---|
| Architettura | I due canali, il ciclo di approvazione, la coda dei lease, i limiti dei risultati |
| Strumenti MCP | Ogni strumento che un agente può chiamare, la struttura del ticket, il contratto di attesa |
| Configurazione | Variabili d'ambiente e notifiche desktop |
| Sicurezza | Threat model, confine di fiducia, conservazione, supply chain |
| Sviluppo | Compilazione dai sorgenti, configurazione di sviluppo, struttura del repo, stack tecnologico |
| Rilascio | Come un commit diventa una release del plugin e un pacchetto npm |
Sviluppo
pnpm install
pnpm build # both packages
pnpm ci # typecheck + build + test
pnpm dev:link collega Beekeeper al tuo checkout e pnpm dev avvia la UI del plugin con hot reload. La configurazione completa, inclusi i database di test, è in Sviluppo.