chore: import upstream snapshot with attribution

2026-07-13 13:32:45 +08:00
commit e04ed9c211
1798 changed files with 307905 additions and 0 deletions
@@ -0,0 +1,4 @@
+---
+title: "Samples"
+weight: 3
+---
@@ -0,0 +1,11 @@
+---
+title: "Getting started with alloydb-ai-nl tool"
+type: docs
+weight: 30
+description: >
+  An end to end tutorial for building an ADK agent using the AlloyDB AI NL tool.
+sample_filters: ["AlloyDB", "ADK", "Python"]
+is_sample: true
+---
+
+{{< ipynb "alloydb_ai_nl.ipynb" >}}
@@ -0,0 +1,370 @@
+---
+title: "Quickstart (MCP with AlloyDB)"
+type: docs
+weight: 7
+description: >
+  How to get started running Toolbox with MCP Inspector and AlloyDB as the source.
+sample_filters: ["AlloyDB", "MCP Inspector"]
+is_sample: true
+---
+
+## Overview
+
+[Model Context Protocol](https://modelcontextprotocol.io) is an open protocol
+that standardizes how applications provide context to LLMs. Check out this page
+on how to [connect to Toolbox via MCP](../../../documentation/connect-to/mcp-client/_index.md).
+
+## Before you begin
+
+This guide assumes you have already done the following:
+
+1.  [Create a AlloyDB cluster and
+    instance](https://cloud.google.com/alloydb/docs/cluster-create) with a
+    database and user.
+1. Connect to the instance using [AlloyDB
+   Studio](https://cloud.google.com/alloydb/docs/manage-data-using-studio),
+   [`psql` command-line tool](https://www.postgresql.org/download/), or any
+   other PostgreSQL client.
+
+1.  Enable the `pgvector` and `google_ml_integration`
+    [extensions](https://cloud.google.com/alloydb/docs/ai). These are required
+    for Semantic Search and Natural Language to SQL tools. Run the following SQL
+    commands:
+
+    ```sql
+    CREATE EXTENSION IF NOT EXISTS "vector";
+    CREATE EXTENSION IF NOT EXISTS "google_ml_integration";
+    CREATE EXTENSION IF NOT EXISTS alloydb_ai_nl cascade;
+    CREATE EXTENSION IF NOT EXISTS parameterized_views;
+    ```
+
+## Step 1: Set up your AlloyDB database
+
+In this section, we will create the necessary tables and functions in your
+AlloyDB instance.
+
+1.  Create tables using the following commands:
+
+    ```sql
+    CREATE TABLE products (
+      product_id SERIAL PRIMARY KEY,
+      name VARCHAR(255) NOT NULL,
+      description TEXT,
+      price DECIMAL(10, 2) NOT NULL,
+      category_id INT,
+      embedding vector(3072) -- Vector size for model(gemini-embedding-001)
+    );
+
+    CREATE TABLE customers (
+      customer_id SERIAL PRIMARY KEY,
+      name VARCHAR(255) NOT NULL,
+      email VARCHAR(255) UNIQUE NOT NULL
+    );
+
+    CREATE TABLE cart (
+      cart_id SERIAL PRIMARY KEY,
+      customer_id INT UNIQUE NOT NULL,
+      created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (customer_id) REFERENCES customers(customer_id)
+    );
+
+    CREATE TABLE cart_items (
+      cart_item_id SERIAL PRIMARY KEY,
+      cart_id INT NOT NULL,
+      product_id INT NOT NULL,
+      quantity INT NOT NULL,
+      price DECIMAL(10, 2) NOT NULL,
+      FOREIGN KEY (cart_id) REFERENCES cart(cart_id),
+      FOREIGN KEY (product_id) REFERENCES products(product_id)
+    );
+
+    CREATE TABLE categories (
+      category_id SERIAL PRIMARY KEY,
+      name VARCHAR(255) NOT NULL
+    );
+    ```
+
+2.  Insert sample data into the tables:
+
+    ```sql
+    INSERT INTO categories (category_id, name) VALUES
+    (1, 'Flowers'),
+    (2, 'Vases');
+
+    INSERT INTO products (product_id, name, description, price, category_id, embedding) VALUES
+    (1, 'Rose', 'A beautiful red rose', 2.50, 1, embedding('gemini-embedding-001', 'A beautiful red rose')),
+    (2, 'Tulip', 'A colorful tulip', 1.50, 1, embedding('gemini-embedding-001', 'A colorful tulip')),
+    (3, 'Glass Vase', 'A transparent glass vase', 10.00, 2, embedding('gemini-embedding-001', 'A transparent glass vase')),
+    (4, 'Ceramic Vase', 'A handmade ceramic vase', 15.00, 2, embedding('gemini-embedding-001', 'A handmade ceramic vase'));
+
+    INSERT INTO customers (customer_id, name, email) VALUES
+    (1, 'John Doe', 'john.doe@example.com'),
+    (2, 'Jane Smith', 'jane.smith@example.com');
+
+    INSERT INTO cart (cart_id, customer_id) VALUES
+    (1, 1),
+    (2, 2);
+
+    INSERT INTO cart_items (cart_id, product_id, quantity, price) VALUES
+    (1, 1, 2, 2.50),
+    (1, 3, 1, 10.00),
+    (2, 2, 5, 1.50);
+    ```
+
+## Step 2: Install Toolbox
+
+In this section, we will download and install the Toolbox binary.
+
+1. Download the latest version of Toolbox as a binary:
+
+    {{< notice tip >}}
+   Select the
+   [correct binary](https://github.com/googleapis/mcp-toolbox/releases)
+   corresponding to your OS and CPU architecture.
+    {{< /notice >}}
+    <!-- {x-release-please-start-version} -->
+    ```bash
+    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, windows/amd64, or windows/arm64
+    export VERSION="0.30.0"
+    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/$OS/toolbox
+    ```
+    <!-- {x-release-please-end} -->
+
+1. Make the binary executable:
+
+    ```bash
+    chmod +x toolbox
+    ```
+
+## Step 3: Configure the tools
+
+Create a `tools.yaml` file and add the following content. You must replace the
+placeholders with your actual AlloyDB configuration.
+
+First, define the data source for your tools. This tells Toolbox how to connect
+to your AlloyDB instance.
+
+```yaml
+kind: source
+name: alloydb-pg-source
+type: alloydb-postgres
+project: YOUR_PROJECT_ID
+region: YOUR_REGION
+cluster: YOUR_CLUSTER
+instance: YOUR_INSTANCE
+database: YOUR_DATABASE
+user: YOUR_USER
+password: YOUR_PASSWORD
+```
+
+Next, define the tools the agent can use. We will categorize them into three
+types:
+
+### 1. Structured Queries Tools
+
+These tools execute predefined SQL statements. They are ideal for common,
+structured queries like managing a shopping cart. Add the following to your
+`tools.yaml` file:
+
+```yaml
+kind: tool
+name: access-cart-information
+type: postgres-sql
+source: alloydb-pg-source
+description: >-
+  List items in customer cart.
+  Use this tool to list items in a customer cart. This tool requires the cart ID.
+parameters:
+  - name: cart_id
+    type: integer
+    description: The id of the cart.
+statement: |
+  SELECT
+    p.name AS product_name,
+    ci.quantity,
+    ci.price AS item_price,
+    (ci.quantity * ci.price) AS total_item_price,
+    c.created_at AS cart_created_at,
+    ci.product_id AS product_id
+  FROM
+    cart_items ci JOIN cart c ON ci.cart_id = c.cart_id
+    JOIN products p ON ci.product_id = p.product_id
+  WHERE
+    c.cart_id = $1;
+---
+kind: tool
+name: add-to-cart
+type: postgres-sql
+source: alloydb-pg-source
+description: >-
+  Add items to customer cart using the product ID and product prices from the product list.
+  Use this tool to add items to a customer cart.
+  This tool requires the cart ID, product ID, quantity, and price.
+parameters:
+  - name: cart_id
+    type: integer
+    description: The id of the cart.
+  - name: product_id
+    type: integer
+    description: The id of the product.
+  - name: quantity
+    type: integer
+    description: The quantity of items to add.
+  - name: price
+    type: float
+    description: The price of items to add.
+statement: |
+  INSERT INTO
+    cart_items (cart_id, product_id, quantity, price)
+  VALUES($1,$2,$3,$4);
+---
+kind: tool
+name: delete-from-cart
+type: postgres-sql
+source: alloydb-pg-source
+description: >-
+  Remove products from customer cart.
+  Use this tool to remove products from a customer cart.
+  This tool requires the cart ID and product ID.
+parameters:
+  - name: cart_id
+    type: integer
+    description: The id of the cart.
+  - name: product_id
+    type: integer
+    description: The id of the product.
+statement: |
+  DELETE FROM
+    cart_items
+  WHERE
+    cart_id = $1 AND product_id = $2;
+```
+
+### 2. Semantic Search Tools
+
+These tools use vector embeddings to find the most relevant results based on the
+meaning of a user's query, rather than just keywords. Append the following tool
+with the `tool` kind in your `tools.yaml`:
+
+```yaml
+kind: tool
+name: search-product-recommendations
+type: postgres-sql
+source: alloydb-pg-source
+description: >-
+  Search for products based on user needs.
+  Use this tool to search for products. This tool requires the user's needs.
+parameters:
+  - name: query
+    type: string
+    description: The product characteristics
+statement: |
+  SELECT
+    product_id,
+    name,
+    description,
+    ROUND(CAST(price AS numeric), 2) as price
+  FROM
+    products
+  ORDER BY
+    embedding('gemini-embedding-001', $1)::vector <=> embedding
+  LIMIT 5;
+```
+
+### 3. Natural Language to SQL (NL2SQL) Tools
+
+1. Create a [natural language
+   configuration](https://cloud.google.com/alloydb/docs/ai/use-natural-language-generate-sql-queries#create-config)
+   for your AlloyDB cluster.
+
+    {{< notice tip >}}Before using NL2SQL tools,
+    you must first install the `alloydb_ai_nl` extension and
+    create the [semantic
+    layer](https://cloud.google.com/alloydb/docs/ai/natural-language-overview)
+    under a configuration named `flower_shop`.
+    {{< /notice >}}
+
+2. Configure your NL2SQL tool to use your configuration. These tools translate
+   natural language questions into SQL queries, allowing users to interact with
+   the database conversationally. Append the following tool with the `tool` kind:
+
+```yaml
+kind: tool
+name: ask-questions-about-products
+type: alloydb-ai-nl
+source: alloydb-pg-source
+nlConfig: flower_shop
+description: >-
+  Ask questions related to products or brands.
+  Use this tool to ask questions about products or brands.
+  Always SELECT the IDs of objects when generating queries.
+```
+
+Finally, group the tools into a `toolset` to make them available to the model.
+Add the following to the end of your `tools.yaml` file:
+
+```yaml
+kind: toolset
+name: flower_shop
+tools:
+  - access-cart-information
+  - search-product-recommendations
+  - ask-questions-about-products
+  - add-to-cart
+  - delete-from-cart
+```
+
+For more info on tools, check out the
+[Tools](../../../documentation/configuration/tools/_index.md) section.
+
+## Step 4: Run the Toolbox server
+
+Run the Toolbox server, pointing to the `tools.yaml` file created earlier:
+
+```bash
+./toolbox --config "tools.yaml"
+```
+
+## Step 5: Connect to MCP Inspector
+
+1. Run the MCP Inspector:
+
+    ```bash
+    npx @modelcontextprotocol/inspector
+    ```
+
+1. Type `y` when it asks to install the inspector package.
+
+1. It should show the following when the MCP Inspector is up and running (please
+   take note of `<YOUR_SESSION_TOKEN>`):
+
+    ```bash
+    Starting MCP inspector...
+    ⚙️ Proxy server listening on localhost:6277
+    🔑 Session token: <YOUR_SESSION_TOKEN>
+       Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth
+
+    🚀 MCP Inspector is up and running at:
+       http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<YOUR_SESSION_TOKEN>
+    ```
+
+1. Open the above link in your browser.
+
+1. For `Transport Type`, select `Streamable HTTP`.
+
+1. For `URL`, type in `http://127.0.0.1:5000/mcp`.
+
+1. For `Configuration` -> `Proxy Session Token`, make sure
+   `<YOUR_SESSION_TOKEN>` is present.
+
+1. Click Connect.
+
+1. Select `List Tools`, you will see a list of tools configured in `tools.yaml`.
+
+1. Test out your tools here!
+
+## What's next
+
+- Learn more about [MCP Inspector](../../../documentation/connect-to/mcp-client/_index.md).
+- Learn more about [Toolbox Configuration](../../../documentation/configuration/_index.md).
+- Learn more about [Toolbox Tutorials](../../../samples/_index.md).