AlloyDB 上の生成 AI およびエージェントアプリケーション用のデータベース用 MCP ツールボックスのインストールと設定

1. 概要

データベース向け MCP ツールボックスは、データベースとやり取りするための生成 AI ツールの構築を容易にする Google のオープンソースサーバーです。これにより、接続プーリングや認証などの複雑な処理に対応して、ツールの開発をより簡単、迅速、セキュアに行うことができます。エージェントがデータベース内のデータにアクセスできるようにする生成 AI ツールの構築に役立ちます。Toolbox には次の機能があります。

簡素化された開発: 10 行未満のコードでツールをエージェントに統合し、複数のエージェントまたはフレームワーク間でツールを再利用し、ツールの新しいバージョンをより簡単にデプロイできます。

パフォーマンスの向上: 接続プーリングや認証などのベストプラクティス。

セキュリティの強化: 統合認証により、データへのアクセスがより安全になります。

エンドツーエンドのオブザーバビリティ: OpenTelemetry のサポートが組み込まれた、すぐに使用できる指標とトレース。

ツールボックスは、アプリケーションのオーケストレーションフレームワークとデータベースの間に配置され、ツールの変更、配布、呼び出しに使用されるコントロールプレーンを提供します。ツールを保存して更新する一元化された場所を提供することで、ツールの管理を簡素化します。これにより、エージェントとアプリケーション間でツールを共有し、必ずしもアプリケーションを再デプロイしなくてもツールを更新できます。

作成するアプリの概要

このラボでは、エージェントまたは生成 AI アプリケーションから呼び出すことができるシンプルなデータベース（AlloyDB）クエリを実行するツールを使用するアプリケーションを構築します。このためには、

データベース向け MCP ツールボックスをインストールする
ツールボックスサーバーにツール（AlloyDB でタスクを実行するように設計されたツール）を設定する
Cloud Run に MCP Toolbox for Databases をデプロイする
デプロイされた Cloud Run エンドポイントを使用してツールをテストする
ツールボックスを呼び出す Cloud Run functions をビルドする

要件

ブラウザ（Chrome、Firefox など）
課金が有効になっている Google Cloud プロジェクト（次のセクションの手順を参照）。

2. 始める前に

プロジェクトを作成する

Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
Google Cloud 上で動作するコマンドライン環境の Cloud Shell を使用します。Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] をクリックします。

[Cloud Shell をアクティブにする] ボタンの画像

Cloud Shell に接続したら、次のコマンドを使用して、すでに認証済みであることと、プロジェクトが正しいプロジェクト ID に設定されていることを確認します。

gcloud auth list

Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。

gcloud config list project

プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。

gcloud config set project <YOUR_PROJECT_ID>

Cloud Shell ターミナルで次のコマンドを 1 つずつ実行して、必要な API を有効にします。

以下のコマンドを 1 つのコマンドで実行することもできますが、トライアルアカウントのユーザーがこれらのコマンドを一括で有効にしようとすると、割り当ての問題が発生する可能性があります。そのため、コマンドは 1 行に 1 つずつ記述されています。

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

gcloud コマンドの代わりに、各プロダクトを検索するか、このリンクを使用して、コンソールから実行することもできます。

API が見つからない場合は、実装中にいつでも有効にできます。

gcloud コマンドとその使用方法については、ドキュメントをご覧ください。

3. データベースの設定

このラボでは、小売データを保持するデータベースとして AlloyDB を使用します。クラスタを使用して、データベースやログなどのすべてのリソースを保持します。各クラスタには、データへのアクセスポイントを提供するプライマリインスタンスがあります。テーブルには実際のデータが格納されます。

e コマースデータセットが読み込まれる AlloyDB クラスタ、インスタンス、テーブルを作成しましょう。

クラスタとインスタンスを作成する

Cloud コンソールの AlloyDB ページに移動します。

Cloud コンソールでほとんどのページを簡単に見つけるには、コンソールの検索バーを使用して検索します。

このページで [クラスタを作成] を選択します。

次のような画面が表示されます。次の値を使用してクラスタとインスタンスを作成します（リポジトリからアプリケーションコードを複製する場合は、値が一致していることを確認してください）。

クラスタ ID: 「vector-cluster」
password: "alloydb"
PostgreSQL 15 互換
リージョン: 「us-central1」
ネットワーキング: 「default」

デフォルトのネットワークを選択すると、次のような画面が表示されます。[接続の設定] を選択します。
[自動的に割り当てられた IP 範囲を使用する] を選択して、[続行] をクリックします。情報を確認したら、[接続を作成] を選択します。
ネットワークを設定したら、クラスタの作成を続行できます。[CREATE CLUSTER] をクリックして、次のようにクラスタの設定を完了します。

インスタンス ID を「

vector-instance"

クラスタの作成には 10 分ほどかかります。成功すると、作成したクラスタの概要を示す画面が表示されます。

4. データの取り込み

次に、店舗に関するデータを含むテーブルを追加します。AlloyDB に移動し、プライマリクラスタと AlloyDB Studio を選択します。

インスタンスの作成が完了するまで待つ必要がある場合があります。完了したら、クラスタの作成時に作成した認証情報を使用して AlloyDB にログインします。PostgreSQL の認証には次のデータを使用します。

ユーザー名: 「postgres」
データベース: 「postgres」
パスワード: 「alloydb」

AlloyDB Studio への認証に成功すると、エディタで SQL コマンドを入力できるようになります。最後のウィンドウの右にあるプラス記号を使用して、複数のエディタウィンドウを追加できます。

必要に応じて [実行]、[形式]、[クリア] オプションを使用して、エディタウィンドウで AlloyDB のコマンドを入力できます。

拡張機能を有効にする

このアプリのビルドには、拡張機能 pgvector と google_ml_integration を使用します。pgvector 拡張機能を使用すると、ベクトルエンベディングを保存して検索できます。google_ml_integration 拡張機能は、Vertex AI 予測エンドポイントにアクセスして SQL で予測を取得するために使用する関数を提供します。次の DDL を実行して、これらの拡張機能を有効にします。

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

データベースで有効になっている拡張機能を確認するには、次の SQL コマンドを実行します。

select extname, extversion from pg_extension;

テーブルを作成する

次の DDL ステートメントを使用してテーブルを作成します。

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

上記のコマンドが正常に実行されると、データベースでテーブルを表示できるようになります。

データを取り込む

このラボでは、SQL ファイルに約 72 件のテストデータがあります。id, name, description, quantity, price, image_url フィールドが含まれています。他のフィールドはラボで後ほど入力します。

そこから行/挿入ステートメントをコピーし、空白のエディタタブに貼り付けて、[実行] を選択します。

テーブルの内容を確認するには、[エクスプローラ] セクションを開き、apparels という名前のテーブルを表示します。三点リーダー（⋮）を選択して、テーブルのクエリオプションを表示します。SELECT ステートメントが新しいエディタタブで開きます。

権限を付与

次のステートメントを実行して、embedding 関数に対する実行権限をユーザー postgres に付与します。

GRANT EXECUTE ON FUNCTION embedding TO postgres;

AlloyDB サービスアカウントに Vertex AI ユーザーロールを付与する

Cloud Shell ターミナルに移動し、次のコマンドを実行します。

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5. コンテキストのエンベディングを作成する

コンピュータは、テキストよりも数値を処理する方がはるかに簡単です。エンベディングシステムは、テキストを浮動小数点数のシーケンス（ベクトルエンベディング）に変換します。このシーケンスは、テキストの表現方法や使用言語などに関係なく、テキストを表す必要があります。

たとえば、海辺の場所は「海辺」、「ビーチフロント」、「部屋から海まで歩いて行ける」、「sur la mer」、「на берегу океана」などと表現されます。これらの用語はすべて異なりますが、セマンティクス的な意味、または機械学習の用語で言うと、埋め込みは互いに非常に近いものになります。

データとコンテキストの準備ができたので、SQL を実行して、商品説明のエンベディングを embedding フィールドのテーブルに追加します。使用できるエンベディングモデルは多数あります。Vertex AI の text-embedding-005 を使用しています。プロジェクト全体で同じエンベディングモデルを使用してください。

注: 古い Google Cloud プロジェクトを使用している場合は、textembedding-gecko などの古いバージョンのテキストエンベディングモデルを引き続き使用する必要がある場合があります。

AlloyDB Studio タブに戻り、次の DML を入力します。

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

toys テーブルをもう一度見て、エンベディングを確認します。変更を確認するには、SELECT ステートメントを再実行してください。

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

次のように、おもちゃの説明のエンベディングベクトル（浮動小数点数の配列）が返されます。

注: 無料枠で新しく作成された Google Cloud プロジェクトでは、Embedding モデルに対して 1 秒あたりに許可されるエンベディングリクエストの数に関して割り当ての問題が発生する可能性があります。ID のフィルタクエリを使用して、エンベディングを生成しながら 1 ～ 5 件のレコードを選択的に選択することをおすすめします。

6. ベクトル検索を実行する

テーブル、データ、エンベディングの準備が整ったので、ユーザーの検索テキストに対してリアルタイムのベクトル検索を実行しましょう。

ユーザーが次のように質問したとします。

「I want a white plush teddy bear toy with a floral pattern。」

次のクエリを実行すると、この一致を確認できます。

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

このクエリを詳しく見てみましょう。

このクエリでは、

ユーザーの検索テキストは「I want a white plush teddy bear toy with a floral pattern.」です。
モデル text-embedding-005 を使用して、embedding() メソッドでエンベディングに変換しています。このステップは、テーブル内のすべての項目にエンベディング関数を適用した最後のステップと似ています。
「<=>」は、コサイン類似度距離メソッドの使用を表します。使用可能な類似度指標については、pgvector のドキュメントをご覧ください。
エンベディングメソッドの結果をベクトル型に変換して、データベースに保存されているベクトルと互換性を持たせています。
LIMIT 5 は、検索テキストの最近傍を 5 つ抽出することを表します。

結果は次のようになります。

結果を見ると、検索テキストとかなり近い一致が見つかっています。テキストを変更して、結果がどのように変化するかを確認してみます。

7. ツールボックスの操作のために AlloyDB を準備する

ツールボックスの設定に備えて、AlloyDB インスタンスでパブリック IP 接続を有効にして、新しいツールがデータベースにアクセスできるようにしましょう。

AlloyDB インスタンスに移動し、[編集] をクリックして [プライマリインスタンスの編集] ページに移動します。
[パブリック IP 接続] セクションに移動し、[パブリック IP を有効にする] チェックボックスをオンにして、Cloud Shell マシンの IP アドレスを入力します。
Cloud Shell マシンの IP を取得するには、Cloud Shell ターミナルに移動して ifconfig と入力します。結果から eth0 inet アドレスを特定し、下 2 桁を 0.0 に置き換えて、マスクサイズを「/16」にします。たとえば、「XX.XX.0.0/16」のようになります（XX は数字）。
この IP を、インスタンスの編集ページの [承認済み外部ネットワーク] の [ネットワーク] テキストボックスに貼り付けます。

完了したら、[インスタンスを更新] をクリックします。

完了するまでに数分かかります。

8. データベース向け MCP ツールボックスのインストール

ツール詳細を保存するプロジェクトフォルダを作成できます。ここでは、おもちゃ屋のデータを扱うため、「toystore」という名前のフォルダを作成して移動します。Cloud Shell ターミナルに移動し、プロジェクトが選択され、ターミナルのプロンプトに表示されていることを確認します。Cloud Shell ターミナルから次のコマンドを実行します。

mkdir toystore

cd toystore

次のコマンドを実行して、新しいフォルダにツールボックスをダウンロードしてインストールします。

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Cloud Shell エディタに切り替えます。新しく作成した「toystore」フォルダを開き、tools.yaml という新しいファイルを作成します。以下の内容をコピーします。YOUR_PROJECT_ID を置き換え、他の接続の詳細がすべて正確であることを確認します。

sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

このツールでは、ユーザーの検索テキスト（カスタム玩具の説明）に最も近い一致を見つけて、その価格を返します。また、上位 5 つの最も近い一致するおもちゃの平均価格を検索するように変更することもできます。

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

ツールの定義が完了しました。

tools.yaml の構成の詳細については、こちらのドキュメントをご覧ください。

Cloud Shell ターミナルに切り替え、次のコマンドを入力して、ツール構成でツールボックスサーバーを起動します。

./toolbox --tools_file "tools.yaml"

クラウドでウェブプレビューモードでサーバーを開くと、get-toy-price. という名前の新しいツールで Toolbox サーバーが起動して実行されていることがわかります。

9. データベース向け MCP ツールボックスの Cloud Run デプロイ

このツールを実際に使用できるように、Cloud Run にデプロイしましょう。

このページの手順に沿って、[Cloud Run にデプロイする] セクションの 3 番目のポイントにある gcloud run deploy toolbox コマンドまで進みます。VPC ネットワークメソッドを使用する場合の 2 番目のオプションではなく、最初のオプションが必要です。
デプロイが正常に完了すると、Toolbox サーバーの Cloud Run デプロイエンドポイントが届きます。CURL コマンドでテストします。

ヒント:

ページの手順に沿って慎重に対応し、見落としがないようにしてください。

これで、新しくデプロイしたツールをエージェントアプリケーションで使用する準備が整いました。

10. MCP Toolbox for Databases を使用してアプリを接続する

このパートでは、アプリケーションのニーズに対応してレスポンスを取得するツールをテストするための小さなアプリケーションを構築します。

Google Colab に移動して、新しいノートブックを開きます。
ノートブックで次のコマンドを実行します。

!pip install toolbox-core
from toolbox_core import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")

# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")

# If there are multiple tools 
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")

# Invoke the tool with a search text to pass as the parameter
 result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

次のような結果が表示されます。

これは、ツールキット toolbox-langchain. を使用する Python アプリケーションで明示的に呼び出されるツールです。

このツールを使用して LangGraph 統合アプリケーション内のエージェントにバインドする場合は、langgraph ツールキットを使用すると簡単に実行できます。
これについては、コードスニペットをご覧ください。

11. クラウドに移行しましょう。

この Python コードスニペットを Cloud Run Functions でラップして、サーバーレスにしましょう。

このコードを Cloud Functions に取得するために、コードリポジトリフォルダからソースをコピーします。
Cloud Run Functions コンソールに移動し、[関数を作成] をクリックします。
デモアプリケーションでは認証なしのままにして、次のページで Python 3.11 ランタイムを選択します。
ステップ 1 で共有されたソースリポジトリから main.py ファイルと requirements.txt ファイルをコピーし、それぞれのファイルに貼り付けます。
main.py のサーバー URL を、ご自身のサーバー URL に置き換えます。
関数をデプロイすると、価格予測ツール用の REST エンドポイントが作成され、おもちゃ店のウェブアプリケーションからアクセスできるようになります。
エンドポイントは次のようになります。

https://us-central1-*****.cloudfunctions.net/toolbox-toys

Cloud Functions コンソールで直接テストするには、[テスト] タブに移動し、リクエスト入力として次のように入力します。

{

           "search": "White plush toy"

}

[関数をテスト] をクリックするか、Cloud Shell ターミナルで選択したものを実行します。右側の [出力] の下に結果が表示されます。

12. 完了

おめでとうございます！データベース、プラットフォーム、生成 AI オーケストレーションフレームワーク間でやり取りできる、堅牢で真にモジュール式のツールが正常に作成されました。このツールは、エージェントアプリケーションの作成に役立ちます。

AlloyDB 上の生成 AI およびエージェント アプリケーション用のデータベース用 MCP ツールボックスのインストールと設定