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

1. 概要

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

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

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

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

エンドツーエンドのオブザーバビリティ: OpenTelemetry の組み込みサポートによる、すぐに使える指標とトレース。

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

作成するアプリの概要

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

データベース向け MCP ツールボックスをインストールする
ツールボックスサーバーでツール（AlloyDB でタスクを実行するように設計されているツール）を設定する
データベース向け MCP ツールボックスを Cloud Run にデプロイする
デプロイされた 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 を使用します。データベースやログなどのすべてのリソースを保持するためにクラスタを使用します。各クラスタには、データへのアクセスポイントを提供するプライマリインスタンスが 1 つあります。テーブルには実際のデータが格納されます。

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

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

Cloud Console で AlloyDB ページに移動します。

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

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

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

クラスタ ID: "vector-cluster"
パスワード: "alloydb"
PostgreSQL 15 との互換性
リージョン: "us-central1"
ネットワーク: "default"

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

インスタンス 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 プロジェクトでは、エンベディングモデルへの 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/genai-toolbox/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"

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

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

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

このページの手順に沿って、[Cloud Run にデプロイ] セクションの 3 番目の項目にあるgcloud run deploy toolboxコマンドに到達するまで、1 つずつ操作します。VPC ネットワークメソッドを使用する場合は、2 つ目のオプションではなく、最初のオプションが必要です。
正常にデプロイされると、ツールボックスサーバーの 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. Cloud に移行する

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

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

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

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

{

           "search": "White plush toy"

}

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

12. 完了

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

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