Use o Spanner com a MCP Toolbox for Databases, a CLI do Gemini e outros agentes

Este documento descreve como ligar a sua instância do Spanner a várias ferramentas para programadores que suportam o protocolo Model Context Protocol (MCP).

Recomendamos que use a extensão do Spanner dedicada para a Gemini CLI. Esta extensão abstrai a necessidade de configurar uma ligação de servidor separada. Pode configurar o Gemini Code Assist para usar a Gemini CLI, oferecendo vantagens de configuração semelhantes no seu IDE. Para mais informações, consulte o artigo Extensão da CLI Gemini – Spanner.

Em alternativa, outros IDEs e ferramentas para programadores que suportem o MCP podem estabelecer ligação através da caixa de ferramentas do MCP para bases de dados. A caixa de ferramentas do MCP é um servidor MCP de código aberto concebido para associar agentes de IA aos seus dados. Processa tarefas como a autenticação e a partilha de ligações, o que lhe permite interagir com os seus dados com linguagem natural diretamente a partir do IDE.

Use a extensão Gemini CLI no Spanner

A integração do Spanner com a CLI do Gemini é feita através de uma extensão de código aberto que oferece capacidades adicionais em comparação com a ligação padrão da caixa de ferramentas do MCP. A extensão oferece um processo de instalação e um conjunto de ferramentas, além de fornecer informações detalhadas sobre a instalação, a configuração e exemplos de utilização. Se usar a extensão da CLI Gemini, não precisa de instalar a caixa de ferramentas do MCP. Para mais informações, consulte o artigo Extensão Gemini CLI – Spanner.

A extensão spanner inclui ferramentas para listar tabelas e executar declarações SQL e SQL DQL.

Ferramentas	Exemplo de comando de linguagem natural
`list_tables`	Que tabelas tenho na minha instância do Spanner?
`execute_sql`	Insira dados de teste na tabela de produtos.
`execute_sql_dql`	Que produtos na categoria de eletrónica são vendidos na América?

Antes de começar

Na Google Cloud consola, na página do seletor de projetos, selecione ou crie um Google Cloud projeto.
Certifique-se de que a faturação está ativada para o seu Google Cloud projeto.

Configure a instância do Spanner

Ative a API Spanner no Google Cloud projeto.
Crie ou selecione uma instância e uma base de dados do Spanner.
Configure as funções e as autorizações necessárias para concluir esta tarefa. O utilizador que invoca os agentes do MDG precisa das seguintes funções ao nível da base de dados:
- Leitor de base de dados do Cloud Spanner (roles/spanner.databaseReader) para executar consultas DQL e listar tabelas.
- Utilizador da base de dados do Cloud Spanner (roles/spanner.databaseUser) para executar consultas DML.
Configure as Credenciais padrão da aplicação (ADC) para o seu ambiente.

Instale a caixa de ferramentas do MCP

Transfira a versão mais recente da MCP Toolbox como um ficheiro binário. Selecione o binário correspondente ao seu sistema operativo (SO) e arquitetura da CPU. Tem de usar a versão 0.15.0 ou posterior da MCP Toolbox:

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

Torne o ficheiro binário executável:
```
chmod +x toolbox
```
Valide a instalação:
```
./toolbox --version
```

Configure a ferramenta de agente

Esta secção descreve como configurar várias ferramentas para programadores para estabelecer ligação à sua instância do Spanner. Selecione a ferramenta do agente nas seguintes opções:

CLI do Gemini

Instale a Gemini CLI.
Instale a extensão Spanner para a Gemini CLI a partir do repositório do GitHub através do seguinte comando:

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

Defina as seguintes variáveis de ambiente para estabelecer ligação à sua instância do Spanner:
```
    export SPANNER_PROJECT="PROJECT_ID"
    export SPANNER_INSTANCE="INSTANCE_NAME"
    export SPANNER_DATABASE="DATABASE_NAME"
    export SPANNER_DIALECT="DIALECT_NAME"
    
```
Substitua o seguinte:
- PROJECT_ID: o ID do seu Google Cloud projeto.
- INSTANCE_NAME: o nome da sua instância do Spanner.
- DATABASE_NAME: o nome da base de dados do Spanner.
- DIALECT_NAME: o dialeto de SQL do Spanner. Aceita googlesql ou postgresql. A predefinição é googlesql se não estiver definida.
Inicie a Gemini CLI no modo interativo:
```
    gemini
    
```
A CLI carrega automaticamente a extensão do Spanner para o Gemini CLI e as respetivas ferramentas, que pode usar para interagir com a sua base de dados.

Gemini Code Assist

Recomendamos vivamente que configure o Gemini Code Assist para usar a Gemini CLI, uma vez que esta abordagem elimina a necessidade de configurar manualmente um servidor MCP. No entanto, as instruções para configurar manualmente um servidor MCP continuam disponíveis na secção seguinte:

1. Instale a extensão Gemini Code Assist no VS Code.
2. Ative o modo de agente e mude o modelo de agente para o Gemini.
3. No diretório raiz do projeto, crie uma pasta com o nome .gemini e, dentro desta, um ficheiro settings.json.
4. Adicione uma das seguintes configurações com base no seu dialeto do Spanner no ficheiro settings.json.
5. Substitua as seguintes variáveis pelos seus valores:

PROJECT_ID: o ID do seu Google Cloud projeto.
INSTANCE_NAME: o nome da sua instância do Spanner.
DATABASE_NAME: o nome da base de dados do Spanner.

6. Guarde o ficheiro.

Spanner com dialeto GoogleSQL:

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