将 Spanner 与 MCP Toolbox for Databases、Gemini CLI 和其他智能体搭配使用

本文档介绍了如何将 Spanner 实例连接到支持 Model Context Protocol (MCP) 的各种开发者工具。

我们建议使用 Gemini CLI 的专用 Spanner 扩展程序。此扩展程序无需设置单独的服务器连接。您可以将 Gemini Code Assist 配置为使用 Gemini CLI，从而在 IDE 中获得类似的设置优势。如需了解详情，请参阅 Gemini CLI 扩展程序 - Spanner。

或者，支持 MCP 的其他 IDE 和开发者工具可以通过 MCP Toolbox for Databases 进行连接。MCP Toolbox 是一款开源 MCP 服务器，旨在将 AI 智能体连接到您的数据。它可处理身份验证和连接池等任务，让您可以直接通过 IDE 使用自然语言与数据进行交互。

在 Spanner 中使用 Gemini CLI 扩展程序

Spanner 与 Gemini CLI 的集成是通过一个开源扩展程序实现的，该扩展程序提供了比标准 MCP Toolbox 连接更多的附加功能。除了提供安装、配置和使用示例的详细信息外，该扩展程序还提供了一个安装流程和一套工具。如果您使用 Gemini CLI 扩展程序，则无需安装 MCP Toolbox。如需了解详情，请参阅 Gemini CLI 扩展程序 - Spanner。

spanner 扩展程序包含用于列出表以及执行 SQL 和 SQL DQL 语句的工具。

工具	自然语言提示示例
`list_tables`	我的 Spanner 实例中有哪些表？
`execute_sql`	将测试数据插入到商品表中。
`execute_sql_dql`	哪些电子类商品在美国销售？

准备工作

在 Google Cloud 控制台的项目选择器页面上，选择或创建 Google Cloud 项目。
确保您的 Google Cloud 项目已启用结算功能。

设置 Spanner 实例

在 Google Cloud 项目中启用 Spanner API。
创建或选择 Spanner 实例和数据库。
配置完成此任务所需的角色和权限。调用 LLM 智能体的用户需要在数据库级层拥有以下角色：
- Cloud Spanner Database Reader (roles/spanner.databaseReader)，用于执行 DQL 查询和列出表。
- Cloud Spanner Database User (roles/spanner.databaseUser)，用于执行 DML 查询。
为您的环境配置应用默认凭证 (ADC)。

安装 MCP Toolbox

以二进制文件形式下载最新版本的 MCP Toolbox。选择与您的操作系统 (OS) 和 CPU 架构对应的二进制文件。您必须使用 MCP Toolbox 0.15.0 版或更高版本：

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

将该二进制文件设为可执行文件：
```
chmod +x toolbox
```
验证安装：
```
./toolbox --version
```

设置智能体工具

本部分介绍了如何配置各种开发者工具，以便连接到 Spanner 实例。从以下选项中选择您的智能体工具：

Gemini CLI

安装 Gemini CLI。
使用以下命令从 GitHub 代码库安装适用于 Gemini CLI 的 Spanner 扩展程序：

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

设置以下环境变量以连接到 Spanner 实例：
```
    export SPANNER_PROJECT: "PROJECT_ID"
    export SPANNER_INSTANCE: "INSTANCE_NAME"
    export SPANNER_DATABASE: "DATABASE_NAME"
    export SPANNER_DIALECT: "DIALECT_NAME"
    
```
替换以下内容：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- INSTANCE_NAME：您的 Spanner 实例名称。
- DATABASE_NAME：您的 Spanner 数据库名称。
- DIALECT_NAME：您的 Spanner SQL 方言。接受 googlesql 或 postgresql。如果未定义，则默认为 googlesql。
以互动模式启动 Gemini CLI：
```
    gemini
    
```
该 CLI 会自动加载适用于 Gemini CLI 的 Spanner 扩展程序及其工具，您可以使用这些工具与数据库进行交互。

Gemini Code Assist

我们强烈建议您将 Gemini Code Assist 配置为使用 Gemini CLI，因为这种方法无需手动配置 MCP 服务器。不过，您仍可在以下部分找到手动配置 MCP 服务器的说明：

1. 在 VS Code 中安装 Gemini Code Assist 扩展程序。
2. 启用代理模式，并将代理模型切换为 Gemini。
3. 在项目根目录中，创建名为 .gemini 的文件夹，并在其中创建 settings.json 文件。
4. 根据 settings.json 文件中的 Spanner 方言添加以下配置之一。
5. 将以下变量替换为您的值：

PROJECT_ID：您的 Google Cloud 项目 ID。
INSTANCE_NAME：您的 Spanner 实例名称。
DATABASE_NAME：您的 Spanner 数据库名称。

6. 保存文件。

使用 GoogleSQL 方言的 Spanner：

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