搭配使用 Spanner 與 MCP Toolbox for Databases、Gemini CLI 和其他代理程式

本文說明如何將 Spanner 執行個體連線至支援模型上下文協定 (MCP) 的各種開發人員工具。

建議您使用 Gemini CLI 專用的 Spanner 擴充功能。這項擴充功能會抽象化，因此不必設定個別的伺服器連線。您可以設定 Gemini Code Assist 使用 Gemini CLI，在 IDE 中享有類似的設定優勢。詳情請參閱「Gemini CLI Extension - 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 Extension - 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 資料庫讀取者 (roles/spanner.databaseReader) 權限，可執行 DQL 查詢及列出資料表。
- Cloud Spanner 資料庫使用者 (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"
      }
    }
  }
}