Usa Spanner con el kit de herramientas de MCP para bases de datos, Gemini CLI y otros agentes

En este documento, se describe cómo conectar tu instancia de Spanner a varias herramientas para desarrolladores que admiten el Protocolo de contexto del modelo (MCP).

Te recomendamos que uses la extensión de Spanner dedicada para Gemini CLI. Esta extensión abstrae la necesidad de configurar una conexión de servidor independiente. Puedes configurar Gemini Code Assist para usar la CLI de Gemini, lo que ofrece beneficios de configuración similares en tu IDE. Para obtener más información, consulta Extensión de Gemini CLI: Spanner.

También puedes usar otros IDE y herramientas para desarrolladores que admitan el MCP para conectarte a través de MCP Toolbox para bases de datos. MCP Toolbox es un servidor de MCP de código abierto diseñado para conectar agentes de IA a tus datos. Maneja tareas como la autenticación y la agrupación de conexiones, lo que te permite interactuar con tus datos en lenguaje natural directamente desde tu IDE.

Usa la extensión de Gemini CLI en Spanner

La integración de Spanner con Gemini CLI se realiza a través de una extensión de código abierto que ofrece capacidades adicionales en comparación con la conexión estándar de MCP Toolbox. La extensión ofrece un proceso de instalación y un conjunto de herramientas, además de proporcionar información detallada sobre la instalación, la configuración y ejemplos de uso. Si usas la extensión de Gemini CLI, no es necesario que instales MCP Toolbox. Para obtener más información, consulta Extensión de Gemini CLI: Spanner.

La extensión spanner incluye herramientas para enumerar tablas y ejecutar instrucciones SQL y DQL de SQL.

Herramientas	Ejemplo de instrucción en lenguaje natural
`list_tables`	¿Qué tablas tengo en mi instancia de Spanner?
`execute_sql`	Inserta datos de prueba en la tabla de productos.
`execute_sql_dql`	¿Qué productos de la categoría de electrónica se venden en América?

Antes de comenzar

En la consola de Google Cloud , en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud .
Asegúrate de tener habilitada la facturación para tu proyecto de Google Cloud .

Configura la instancia de Spanner

Habilita la API de Spanner en el Google Cloud proyecto.
Crea o selecciona una instancia y una base de datos de Spanner.
Configura los roles y permisos necesarios para completar esta tarea. El usuario que invoca a los agentes de LLM necesita los siguientes roles a nivel de la base de datos:
- Lector de base de datos de Cloud Spanner (roles/spanner.databaseReader) para ejecutar consultas de DQL y enumerar tablas
- Usuario de base de datos de Cloud Spanner (roles/spanner.databaseUser) para ejecutar consultas de DML.
Configura las credenciales predeterminadas de la aplicación (ADC) para tu entorno.

Instala MCP Toolbox

Descarga la versión más reciente de MCP Toolbox como un objeto binario. Selecciona el objeto binario correspondiente a tu sistema operativo (SO) y a la arquitectura de CPU. Debes usar la versión 0.15.0 o posterior de 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

Haz que el objeto binario sea ejecutable:
```
chmod +x toolbox
```
Verifica la instalación:
```
./toolbox --version
```

Configura la herramienta del agente

En esta sección, se describe cómo configurar varias herramientas para desarrolladores para conectarse a tu instancia de Spanner. Selecciona tu herramienta de agente entre las siguientes opciones:

CLI de Gemini

Instala la Gemini CLI.
Instala la extensión de Spanner para Gemini CLI desde el repositorio de GitHub con el siguiente comando:

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

Configura las siguientes variables de entorno para conectarte a tu instancia de Spanner:
```
    export SPANNER_PROJECT="PROJECT_ID"
    export SPANNER_INSTANCE="INSTANCE_NAME"
    export SPANNER_DATABASE="DATABASE_NAME"
    export SPANNER_DIALECT="DIALECT_NAME"
    
```
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto de Google Cloud .
- INSTANCE_NAME: Es el nombre de tu instancia de Spanner.
- DATABASE_NAME: Es el nombre de tu base de datos de Spanner.
- DIALECT_NAME: Es tu dialecto de SQL de Spanner. Se acepta googlesql o postgresql. El valor predeterminado es googlesql si no se define.
Inicia Gemini CLI en modo interactivo:
```
    gemini
    
```
La CLI carga automáticamente la extensión de Spanner para Gemini CLI y sus herramientas, que puedes usar para interactuar con tu base de datos.

Gemini Code Assist

Te recomendamos que configures Gemini Code Assist para que use la CLI de Gemini, ya que este enfoque elimina la necesidad de configurar manualmente un servidor de MCP. Sin embargo, las instrucciones para configurar manualmente un servidor de MCP aún están disponibles en la siguiente sección:

1. Instala la extensión Gemini Code Assist en VS Code.
2. Habilita el modo agente y cambia el modelo del agente a Gemini.
3. En el directorio raíz del proyecto, crea una carpeta llamada .gemini y, dentro de ella, un archivo settings.json.
4. Agrega una de las siguientes configuraciones según tu dialecto de Spanner en el archivo settings.json.
5. Reemplaza las siguientes variables por tus valores:

PROJECT_ID: Es el ID del proyecto de Google Cloud .
INSTANCE_NAME: Es el nombre de tu instancia de Spanner.
DATABASE_NAME: Es el nombre de tu base de datos de Spanner.

6. Guarda el archivo.

Spanner con el dialecto GoogleSQL:

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