Utilizzare Spanner con MCP Toolbox for Databases, l'interfaccia a riga di comando di Gemini e altri agenti

Questo documento descrive come connettere l'istanza Spanner a vari strumenti per sviluppatori che supportano il Model Context Protocol (MCP).

Ti consigliamo di utilizzare l'estensione Spanner dedicata per l'interfaccia a riga di comando di Gemini. Questa estensione elimina la necessità di configurare una connessione server separata. Puoi configurare Gemini Code Assist per utilizzare Gemini CLI, che offre vantaggi di configurazione simili nel tuo IDE. Per saperne di più, consulta Estensione Gemini CLI - Spanner.

In alternativa, altri IDE e strumenti per sviluppatori che supportano MCP possono connettersi tramite MCP Toolbox for Databases. MCP Toolbox è un server MCP open source progettato per connettere gli agenti AI ai tuoi dati. Gestisce attività come l'autenticazione e il pool di connessioni, consentendoti di interagire con i tuoi dati con il linguaggio naturale direttamente dal tuo IDE.

Utilizzare l'estensione Gemini CLI in Spanner

L'integrazione di Spanner con Gemini CLI avviene tramite un'estensione open source che offre funzionalità aggiuntive rispetto alla connessione standard di MCP Toolbox. L'estensione offre una procedura di installazione e un insieme di strumenti, oltre a fornire informazioni dettagliate su installazione, configurazione ed esempi di utilizzo. Se utilizzi l'estensione Gemini CLI, non è necessario installare MCP Toolbox. Per saperne di più, consulta Estensione Gemini CLI - Spanner.

L'estensione spanner include strumenti per elencare le tabelle ed eseguire istruzioni SQL e SQL DQL.

Strumenti	Esempio di prompt in linguaggio naturale
`list_tables`	Quali tabelle ho nella mia istanza Spanner?
`execute_sql`	Inserisci i dati di test nella tabella dei prodotti.
`execute_sql_dql`	Quali prodotti della categoria elettronica vengono venduti in America?

Prima di iniziare

Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .
Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

Configura l'istanza di Spanner

Abilita l'API Spanner nel progetto Google Cloud .
Crea o seleziona un'istanza e un database Spanner.
Configura i ruoli e le autorizzazioni richiesti per completare questa attività. L'utente che richiama gli agenti LLM deve disporre dei seguenti ruoli a livello di database:
- Cloud Spanner Database Reader (roles/spanner.databaseReader) per eseguire query DQL ed elencare le tabelle.
- Utente database Cloud Spanner (roles/spanner.databaseUser) per eseguire query DML.
Configura le credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.

Installare MCP Toolbox

Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario corrispondente al tuo sistema operativo e all'architettura della CPU. Devi utilizzare MCP Toolbox versione 0.15.0 o successive:

linux/amd64

curl -O https://storage.googleapis.com/genai-toolbox/version/linux/amd64/toolbox

darwin/arm64

curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/arm64/toolbox

darwin/amd64

curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/amd64/toolbox

windows/amd64

curl -O https://storage.googleapis.com/genai-toolbox/version/windows/amd64/toolbox

Rendi eseguibile il file binario:
```
chmod +x toolbox
```
Verifica l'installazione:
```
./toolbox --version
```

Configurare lo strumento dell'agente

Questa sezione descrive come configurare vari strumenti per sviluppatori per connettersi all'istanza Spanner. Seleziona lo strumento agente tra le seguenti opzioni:

Interfaccia a riga di comando di Gemini

Installa la Gemini CLI.
Installa l'estensione Spanner per Gemini CLI dal repository GitHub utilizzando il seguente comando:

  gemini extensions install https://github.com/gemini-cli-extensions/spanner

Imposta le seguenti variabili di ambiente per connetterti all'istanza Spanner:
```
    export SPANNER_PROJECT="PROJECT_ID"
    export SPANNER_INSTANCE="INSTANCE_NAME"
    export SPANNER_DATABASE="DATABASE_NAME"
    export SPANNER_DIALECT="DIALECT_NAME"
    
```
Sostituisci quanto segue:
- PROJECT_ID: il tuo ID progetto Google Cloud .
- INSTANCE_NAME: il nome dell'istanza Spanner.
- DATABASE_NAME: il nome del database Spanner.
- DIALECT_NAME: il dialetto SQL di Spanner. Accetta googlesql o postgresql. Il valore predefinito è googlesql se non definito.
Avvia Gemini CLI in modalità interattiva:
```
    gemini
    
```
La CLI carica automaticamente l'estensione Spanner per Gemini CLI e i relativi strumenti, che puoi utilizzare per interagire con il tuo database.

Gemini Code Assist

Ti consigliamo vivamente di configurare Gemini Code Assist per utilizzare Gemini CLI, in quanto questo approccio elimina la necessità di configurare manualmente un server MCP. Tuttavia, le istruzioni per configurare manualmente un server MCP sono ancora disponibili nella sezione seguente:

1. Installa l'estensione Gemini Code Assist in VS Code.
2. Attiva la modalità Agent e passa al modello di agente Gemini.
3. Nella directory radice del progetto, crea una cartella denominata .gemini e, al suo interno, un file settings.json.
4. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner nel file settings.json.
5. Sostituisci le seguenti variabili con i tuoi valori:

PROJECT_ID: il tuo ID progetto Google Cloud .
INSTANCE_NAME: il nome dell'istanza Spanner.
DATABASE_NAME: il nome del database Spanner.

6. Salva il file.

Spanner con dialetto GoogleSQL:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}